docs: @Override
      public Object allocateConnection(ManagedConnectionFactory factory, ConnectionRequestInfo requestInfo) throws ResourceException {
          final boolean isTraceOn = TraceComponent.isAnyTracingEnabled();
          if (isTraceOn && tc.isEntryEnabled()) {
              Tr.entry(this, tc, "allocateConnection");
          }
  
          if (_pm == null) {
              if (isTraceOn && tc.isDebugEnabled()) {
                  Tr.debug(this, tc, "This should not happen!  pm was null for cf name " + cmConfig.getCfKey());
              }
              String formattedMessage = CommonFunction.getNLSMessage("POOL_MANAGER_NOT_FOUND_J2CA0695",
                                                                     new Object[] { cmConfig.getJNDIName() == null ? cmConfig.getCfKey() : cmConfig.getJNDIName() });
              java.lang.IllegalStateException re = new java.lang.IllegalStateException(formattedMessage);
              Tr.error(tc, "FAILED_MANAGED_CONNECTION_J2CA0020", re);
              throw re;
          }
  
          UOWCurrent uowCurrent = (UOWCurrent) _pm.connectorSvc.transactionManager;
          UOWCoordinator uowCoord = uowCurrent == null ? null : uowCurrent.getUOWCoord();
  
          Subject subj = getFinalSubject(requestInfo, factory, this);
  
          if (isTraceOn && tc.isDebugEnabled()) {
              Tr.debug(this, tc, "This CM is " + this.toString());
              Tr.debug(this, tc, "Input MCF is     " + factory);
          }
  
          Object rVal = null;
  
          Object credTokenObj = null;
          MCWrapper mcWrapper = null;
          try { // Begin processing to get connection
  
              // Perform any security setup that may be needed
              // before we proceed to get a connection.
  
              credTokenObj = securityHelper.beforeGettingConnection(subj, requestInfo);
              mcWrapper = allocateMCWrapper(factory, requestInfo, subj, uowCoord);
  
              involveMCInTran(mcWrapper, uowCoord, this);
  
              /*
               * Get the a Connection from the ManagedConnection to return to our caller.
               */
  
              int poolState = mcWrapper.getPoolState();
              try {
                  mcWrapper.setPoolState(50);
  
                  rVal = mcWrapper.getConnection(subj, requestInfo);
                  mcWrapper.setPoolState(poolState);
                  if (mcWrapper.do_not_reuse_mcw) {
                      if (isTraceOn && tc.isDebugEnabled()) {
                          Tr.debug(this, tc, "Connection error occurred for this mcw " + mcWrapper + ", mcw will not be reuse");
                      }
                      mcWrapper.markStale();
                      ResourceException e = new ResourceException("Resource adatepr called connection error event during getConnection " +
                                                                  "processing and did not throw a resource exception.  The reason for " +
                                                                  "this falue may have been logged during the connection error event " +
                                                                  "logging.");
                      throw e;
                  }
              } catch (ResourceException e) {
                  mcWrapper.setPoolState(poolState);
                  com.ibm.ws.ffdc.FFDCFilter.processException(e, "com.ibm.ejs.j2c.ConnectionManager.allocateConnection", "344", this);
                  Tr.error(tc, "FAILED_CONNECTION_J2CA0021", new Object[] { e, _pm.gConfigProps.cfName });
  
                  /*
                   * If the Resource Adapter throws a ResourceException and we are not in a
                   * transaction and there are no other connections open on the ManagedConnection,
                   * return the ManagedConnection to the pool before
                   * rethrowing the exception. The ManagedConnection is probably OK - the exception
                   * may only be a logon failure or similar so the MC shouldn't be 'lost'.
                   *
                   * If we are in a transaction, just throw the exception. Assume we will cleanup during
                   * the aftercompletion call on the tran wrapper.
                   *
                   * for resource adapter that support NOTXWRAPPER, if an error occurs, we can move them from the inuse
                   * pool, to the free pool, assuming the managed connection is good.
                   * This managed connection can be in a transaction (uowCoord != null) but it still should be ok to release it to the free pool
                   *
                   * if resource failover is enabled and we are in current mode 102, since we are now using the alternate
                   * resource adapter, instead of considering this connection ok, lets remove it. When the pool fails back we
                   * do not what to risk having pooled bad connections.
                   */
                  if (isTraceOn && tc.isDebugEnabled()) {
  
                      if (uowCoord != null) {
                          Tr.debug(this, tc, "getConnection failed for using uow is " + uowCoord +
                                             " tran wrapper id is " + mcWrapper.getTranWrapperId() +
                                             " handle count is " + mcWrapper.getHandleCount());
                      } else {
                          Tr.debug(this, tc, "getConnection failed for using uow is null" +
                                             " tran wrapper id is " + mcWrapper.getTranWrapperId() +
                                             " handle count is " + mcWrapper.getHandleCount());
  
                      }
  
                  }
                  if (mcWrapper.do_not_reuse_mcw) {
                      if (mcWrapper.getTranWrapperId() == MCWrapper.LOCALTXWRAPPER) {
                          if (!mcWrapper.getLocalTransactionWrapper().isEnlisted() && !mcWrapper.getLocalTransactionWrapper().isRegisteredForSync()) {
                              // We are not enlisted or registered, we need to remove this connection since after completion will not be called.
                              // Null the uowCoord and the following code will remove this connection from the pool.
                              if (isTraceOn && tc.isDebugEnabled()) {
                                  Tr.debug(this, tc, "This connection is not registered for sync or enlisted in a transaction");
                              }
                              uowCoord = null;
                              if (mcWrapper.getHandleCount() == 1) {
                                  /*
                                   * Since the resource adater call connection error event, they should not have returned
                                   * a connection handle. Since we are not enlisted or registered, we can decrement the
                                   * handle count and let the following code cleanup and destory this managed connection.
                                   */
                                  if (isTraceOn && tc.isDebugEnabled()) {
                                      Tr.debug(this, tc, "Decrementing the handle count for clean up and destroying the managed connection.");
                                  }
                                  mcWrapper.decrementHandleCount();
                              }
                          }
                      }
                  }
  
                  if ((uowCoord == null || (mcWrapper.getTranWrapperId() == MCWrapper.NOTXWRAPPER)) && mcWrapper.getHandleCount() == 0) {
  
                      try {
                          if (isTraceOn && tc.isDebugEnabled()) {
                              Tr.debug(this, tc,
                                       "Connection error occurred during getConnection to resource adapter.  The managed connection should be good, moving it to free pool.");
                          }
                          mcWrapper.releaseToPoolManager();
                      } catch (Exception exp) { // don't rethrow, already on exception path
                          com.ibm.ws.ffdc.FFDCFilter.processException(exp, "com.ibm.ejs.j2c.ConnectionManager.allocateConnection", "364", this);
                          Tr.error(tc, "FAILED_CONNECTION_RELEASE_J2CA0022", new Object[] { exp, _pm.gConfigProps.cfName });
                      }
                  }
                  if (isTraceOn && tc.isEntryEnabled()) {
                      Tr.exit(this, tc, "allocateConnection");
                  }
                  throw e;
              } catch (java.lang.Exception e) {
                  mcWrapper.setPoolState(poolState);
                  com.ibm.ws.ffdc.FFDCFilter.processException(e, "com.ibm.ejs.j2c.ConnectionManager.allocateConnection", "372", this);
                  Tr.error(tc, "FAILED_CONNECTION_J2CA0021", new Object[] { e, _pm.gConfigProps.cfName });
  
                  /*
                   * If the Resource Adapter throws an Exception and we are not in a
                   * transaction and there are no other connections open on the ManagedConnection,
                   * return the ManagedConnection to the pool before
                   * rethrowing the exception. The ManagedConnection is probably OK - the exception
                   * may only be a logon failure or similar so the MC shouldn't be 'lost'.
                   *
                   * If we are in a transaction, just throw the exception. Assume we will cleanup during
                   * the aftercompletion call on the tran wrapper.
                   *
                   * - for resource adapter that support NOTXWRAPPER, if an error occurs, we can move them from the inuse
                   * pool, to the free pool, assuming the managed connection is good.
                   * This managed connection can be in a transaction (uowCoord != null) but it still should be ok to release it to the free pool
                   */
  
                  if (isTraceOn && tc.isDebugEnabled()) {
  
                      if (uowCoord != null) {
                          Tr.debug(this, tc, "getConnection failed for using uow is " + uowCoord +
                                             " tran wrapper id is " + mcWrapper.getTranWrapperId() +
                                             " handle count is " + mcWrapper.getHandleCount());
                      } else {
                          Tr.debug(this, tc, "getConnection failed for using uow is null" +
                                             " tran wrapper id is " + mcWrapper.getTranWrapperId() +
                                             " handle count is " + mcWrapper.getHandleCount());
                      }
  
                  }
  
                  if ((uowCoord == null || (mcWrapper.getTranWrapperId() == MCWrapper.NOTXWRAPPER)) && mcWrapper.getHandleCount() == 0) {
  
                      try {
                          if (isTraceOn && tc.isDebugEnabled()) {
                              Tr.debug(this, tc,
                                       "Connection error occurred during getConnection to resource adapter.  The managed connection should be good, moving it to free pool.");
                          }
                          mcWrapper.releaseToPoolManager();
                      } catch (Exception exp) { // don't rethrow, already on exception path
                          com.ibm.ws.ffdc.FFDCFilter.processException(exp, "com.ibm.ejs.j2c.ConnectionManager.allocateConnection", "392", this);
                          Tr.error(tc, "FAILED_CONNECTION_RELEASE_J2CA0022", new Object[] { exp, _pm.gConfigProps.cfName });
  
                      }
  
                  }
  
                  ResourceException re = new ResourceException("allocateConnection: caught Exception");
                  re.initCause(e);
                  throw re;
  
              }
  
              if (_pm != null && (!(_pm.gConfigProps.isSmartHandleSupport() && shareable))) {
                  HandleList hl = null;
  
                  //  store the handle list in the MCWrapper
                  mcWrapper.addToHandleList(rVal, hl);
  
              }
  
              boolean connLeakOrmaxNumThreads = ((isTraceOn && ConnLeakLogic.isDebugEnabled()) || (_pm != null && _pm.maxNumberOfMCsAllowableInThread > 0));
              boolean usingTLS = ((isTraceOn && tc.isDebugEnabled()) && (_pm != null && _pm.maxCapacity > 0));
              if (connLeakOrmaxNumThreads || usingTLS) {
                  // add thread information to mcWrapper
                  Thread myThread = Thread.currentThread();
                  mcWrapper.setThreadID(RasHelper.getThreadId());
                  mcWrapper.setThreadName(myThread.getName());
                  if (connLeakOrmaxNumThreads) {
                      // add current time and stack information
                      if (mcWrapper.getLastAllocationTime() == 0)
                          mcWrapper.setLastAllocationTime(mcWrapper.getHoldTimeStart());
                      else
                          mcWrapper.setLastAllocationTime(System.currentTimeMillis());
                      if (mcWrapper.getInitialRequestStackTrace() == null) {
                          Throwable t = new Throwable();
                          mcWrapper.setInitialRequestStackTrace(t);
                      }
                  }
              }
  
          } // end try block
            // NOTE: Only a "finally" clause is implemented.
            //       No catch is done, because prior processing
            //       is already covered by catch clauses in
            //       either Connection Manager or other services
            //       which will record the error and then
            //       percolate up to the finally clause. The
            //       "finally" processing MUST be done to ensure
            //       any thread identity pushed to the OS
            //       thread is removed and the original identity
            //       is restored.
          finally {
              if (credTokenObj != null) {
                  securityHelper.afterGettingConnection(subj, requestInfo, credTokenObj);
              }
          }
  
          if (isTraceOn && tc.isEntryEnabled()) {
              Tr.exit(this, tc, "allocateConnection", rVal==null?" connection handle is null":Integer.toHexString(rVal.hashCode()));
          }
  
          return rVal;
  
      }