Part 1 for issue eclipse-ee4j#24900 Document and rename some Resource…

…Handle fields.

Document and rename some ConnectionPool fields.
Remove some unused methods and constructor parameters.
Functional / possible incompatibility changes in DataStructureFactory
and in ResourceHandle due to constructor changes.

appserver/connectors/connectors-inbound-runtime/src/main/java/com/sun/enterprise/connectors/inbound/BasicResourceAllocator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022, 2024 Contributors to the Eclipse Foundation.
  * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -42,21 +42,19 @@ public final class BasicResourceAllocator extends AbstractConnectorAllocator {
     public BasicResourceAllocator() {
     }
 
-
     @Override
     public ResourceHandle createResource() throws PoolingException {
         throw new UnsupportedOperationException();
     }
 
-
     public ResourceHandle createResource(XAResource xaResource) throws PoolingException {
         ResourceHandle resourceHandle = null;
         ResourceSpec spec = new ResourceSpec(JMS_RESOURCE_FACTORY, ResourceSpec.JMS);
 
         if (xaResource != null) {
             logger.logp(Level.FINEST, "BasicResourceAllocator", "createResource", "NOT NULL", xaResource);
             try {
-                resourceHandle = new ResourceHandle(null, spec, this, null);
+                resourceHandle = new ResourceHandle(null, spec, this);
                 if (logger.isLoggable(Level.FINEST)) {
                     xaResource = new XAResourceWrapper(xaResource);
                 }
@@ -71,14 +69,12 @@ public ResourceHandle createResource(XAResource xaResource) throws PoolingExcept
         return resourceHandle;
     }
 
-
     @Override
     public void closeUserConnection(ResourceHandle resourceHandle)
             throws PoolingException {
         throw new UnsupportedOperationException();
     }
 
-
     @Override
     public boolean matchConnection(ResourceHandle resourceHandle) {
         return false;

appserver/connectors/connectors-inbound-runtime/src/main/java/com/sun/enterprise/connectors/inbound/ConnectorMessageBeanClient.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2023 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022, 2024 Contributors to the Eclipse Foundation.
  * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -353,7 +353,7 @@ private EjbMessageBeanDescriptor getDescriptor() {
      */
     @Override
     public MessageEndpoint createEndpoint(XAResource xa) throws UnavailableException {
-        // This is a temporary workaround for blocking the the create enpoint
+        // This is a temporary workaround for blocking the created endpoint
         // until the deployment completes. One thread would wait for maximum a
         // a minute.
         return createEndpoint(xa, WAIT_TIME);

appserver/connectors/connectors-internal-api/src/main/java/com/sun/appserv/connectors/internal/api/ResourceHandle.java

@@ -1,4 +1,5 @@
 /*
+ * Copyright (c) 2022, 2024 Contributors to the Eclipse Foundation.
  * Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -19,33 +20,85 @@
 import javax.transaction.xa.XAResource;
 
 /**
- * ResourceHandle interface to be used by transaction manager components
+ * ResourceHandle interface to be used by transaction manager components.
  *
  * @author Marina Vatkina
  */
 
 public interface ResourceHandle {
 
+    /**
+     * Returns true if the resource is part of a transaction.
+     *
+     * @return true if the resource is part of a transaction.
+     */
     public boolean isTransactional();
 
-    //TODO V3 not needed as of now.
+    /**
+     * To check whether lazy enlistment is suspended or not.<br>
+     * If {@code true}, transaction manager will not do enlist/lazy enlist.
+     *
+     * @return true if enlistment is suspended, otherwise false.
+     */
     public boolean isEnlistmentSuspended();
 
+    /**
+     * Allows a ResourceManager to change the enlistement suspended state of a resource to enlist a resource in a
+     * transaction.
+     *
+     * @param enlistmentSuspended true if enlistment in a transaction is suspended, false if enlistment is not suspended.
+     */
     public void setEnlistmentSuspended(boolean enlistmentSuspended);
 
+    /**
+     * Returns the (optional) XAResource reference for this resource handle.
+     *
+     * @return the XAResource reference for this resource handle or null if no reference is set.
+     */
     public XAResource getXAResource();
 
+    /**
+     * Returns true if the ResourceHandle is supported in an XA transaction.
+     *
+     * @return true if the ResourceHandle is supported in an XA transaction, otherwise false.
+     */
     public boolean supportsXA();
 
+    /**
+     * Returns the component instance holding this resource handle.
+     *
+     * @return the component instance holding this resource handle.
+     */
     public Object getComponentInstance();
 
+    /**
+     * Sets the component instance holding this resource handle.
+     *
+     * @param instance the component instance holding this resource handle.
+     */
     public void setComponentInstance(Object instance);
 
+    /**
+     * Closes the (optional) 'userConnection' / 'connection handle' (used by the application code to refer to the underlying
+     * physical connection). Example: the ManagedConnection represented by this ResourceHandle is closed / cleaned up.
+     *
+     * @throws PoolingException wrapping any 'userConnection' specific exception that might occur during the close call.
+     * @throws UnsupportedOperationException when the method is not implemented.
+     */
     public void closeUserConnection() throws PoolingException;
 
+    /**
+     * Returns true if the resource handle is enlisted in a transaction.
+     *
+     * @return true if the resource handle is enlisted in a transaction.
+     */
     public boolean isEnlisted();
 
+    /**
+     * Returns true if the resource handle is sharable within the component.
+     *
+     * @return true if the resource handle is sharable within the component.
+     */
     public boolean isShareable();
 
-    public void destroyResource();
 }

appserver/connectors/connectors-internal-api/src/main/java/com/sun/appserv/connectors/internal/api/TransactedPoolManager.java

@@ -29,7 +29,11 @@
 public interface TransactedPoolManager {
 
     /**
-     * Indicate that a resource is enlisted.
+     * Indicate that a resource is enlisted.<br>
+     * Expecting this method is called from the
+     * {@link com.sun.enterprise.resource.ResourceHandle#enlistedInTransaction(Transaction)} method and not directly from a
+     * pool manager.
+     *
      * @param tran Transaction to which the resource is enlisted
      * @param res Resource that is enlisted
      * @throws IllegalStateException when unable to enlist the resource

appserver/connectors/connectors-runtime/src/main/java/com/sun/enterprise/connectors/ConnectorConnectionPool.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022, 2024 Contributors to the Eclipse Foundation.
  * Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -75,7 +75,6 @@ public class ConnectorConnectionPool implements Serializable {
     private String poolWaitQueue;
     private String dataStructureParameters;
     private String resourceGatewayClass;
-    private String resourceSelectionStrategyClass;
     private boolean nonTransactional_;
     private boolean nonComponent_;
 
@@ -774,14 +773,6 @@ public void setResourceGatewayClass(String resourceGatewayClass) {
         this.resourceGatewayClass = resourceGatewayClass;
     }
 
-    public String getResourceSelectionStrategyClass() {
-        return resourceSelectionStrategyClass;
-    }
-
-    public void setResourceSelectionStrategyClass(String resourceSelectionStrategyClass) {
-        this.resourceSelectionStrategyClass = resourceSelectionStrategyClass;
-    }
-
     public boolean isPreferValidateOverRecreate() {
         return preferValidateOverRecreate_;
     }

appserver/connectors/connectors-runtime/src/main/java/com/sun/enterprise/resource/AssocWithThreadResourceHandle.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022, 2024 Contributors to the Eclipse Foundation.
  * Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
@@ -18,6 +18,7 @@
 package com.sun.enterprise.resource;
 
 import com.sun.enterprise.resource.allocator.ResourceAllocator;
+import jakarta.resource.spi.ManagedConnection;
 
 /**
  * ResourceHandle with state related to assoc-with-thread pool
@@ -30,8 +31,8 @@ public class AssocWithThreadResourceHandle extends ResourceHandle {
     private long threadId_;
     private boolean dirty_;
 
-    public AssocWithThreadResourceHandle(Object resource, ResourceSpec spec, ResourceAllocator alloc, ClientSecurityInfo info) {
-        super(resource, spec, alloc, info);
+    public AssocWithThreadResourceHandle(ManagedConnection resource, ResourceSpec spec, ResourceAllocator alloc) {
+        super(resource, spec, alloc);
     }
 
     public boolean isDirty() {

appserver/connectors/connectors-runtime/src/main/java/com/sun/enterprise/resource/ConnectorXAResource.java

@@ -81,7 +81,7 @@ private void handleResourceException(Exception ex) throws XAException {
     @Override
     public void commit(Xid xid, boolean onePhase) throws XAException {
         try {
-            ManagedConnection managedConnection = (ManagedConnection) getResourceHandle().getResource();
+            ManagedConnection managedConnection = getResourceHandle().getResource();
             managedConnection.getLocalTransaction().commit();
         } catch (Exception ex) {
             handleResourceException(ex);
@@ -96,7 +96,7 @@ public void start(Xid xid, int flags) throws XAException {
         try {
             ResourceHandle handle = getResourceHandle();
             if (!localHandle_.equals(handle)) {
-                ManagedConnection managedConnection = (ManagedConnection) handle.getResource();
+                ManagedConnection managedConnection = handle.getResource();
                 managedConnection.associateConnection(userHandle);
                 LocalTxConnectionEventListener listener = (LocalTxConnectionEventListener) handle.getListener();
 
@@ -122,7 +122,7 @@ public void end(Xid xid, int flags) throws XAException {
 
                 ResourceHandle handle = listener.removeAssociation(userHandle);
                 if (handle != null) { // not needed, just to be sure.
-                    ManagedConnection associatedConnection = (ManagedConnection) handle.getResource();
+                    ManagedConnection associatedConnection = handle.getResource();
                     associatedConnection.associateConnection(userHandle);
                     _logger.log(FINE, "connection_sharing_reset_association", userHandle);
                 }
@@ -177,7 +177,7 @@ public Xid[] recover(int flag) throws XAException {
     public void rollback(Xid xid) throws XAException {
         try {
             ResourceHandle handle = getResourceHandle();
-            ManagedConnection managedConnection = (ManagedConnection) handle.getResource();
+            ManagedConnection managedConnection = handle.getResource();
             managedConnection.getLocalTransaction().rollback();
         } catch (Exception ex) {
             handleResourceException(ex);
@@ -211,7 +211,7 @@ private ResourceHandle getResourceHandle() throws PoolingException {
             }
 
             if (resourceHandle.getResourceState().isUnenlisted()) {
-                ManagedConnection managedConnection = (ManagedConnection) resourceHandle.getResource();
+                ManagedConnection managedConnection = resourceHandle.getResource();
 
                 // Begin the local transaction if first time
                 // this ManagedConnection is used in this JTA transaction
@@ -236,8 +236,8 @@ private void resetAssociation() throws XAException {
             // Clear the associations and Map all associated handles back to their actual Managed Connection.
             Map<Object, ResourceHandle> associatedHandles = listener.getAssociatedHandlesAndClearMap();
             for (Entry<Object, ResourceHandle> userHandleEntry : associatedHandles.entrySet()) {
-                ResourceHandle associatedHandle = (ResourceHandle) userHandleEntry.getValue();
-                ManagedConnection associatedConnection = (ManagedConnection) associatedHandle.getResource();
+                ResourceHandle associatedHandle = userHandleEntry.getValue();
+                ManagedConnection associatedConnection = associatedHandle.getResource();
                 associatedConnection.associateConnection(userHandleEntry.getKey());
                 _logger.log(FINE, "connection_sharing_reset_association", userHandleEntry.getKey());
             }