com.ibm.as400.access

Class AS400ConnectionPool

  • All Implemented Interfaces:
    Serializable


    public class AS400ConnectionPool
    extends ConnectionPool
    implements Serializable
    Manages a pool of AS400 objects. A connection pool is used to share connections and manage the number of connections a user can have to the system.

    A connection is defined by a systemName, userID, and an optional password and/or service. Services should be referred to using constants from the AS400 class (FILE, PRINT, COMMAND, DATAQUEUE, etc.)

    When a connection is requested, a fully functional AS400 object is returned to the calling application. It is then up to the application to return the AS400 object to the pool. It is not recommended that an application use this object to create additional connections as the pool would not keep track of these connections.

    The AS400ConnectionPool class keeps track of the number of connections it creates. The user can set the maximum number of connections that can be given out by a pool. If the maximum number of connections has already been given out when an additional connection is requested, an exception is thrown.

    Note: AS400ConnectionPool objects are threadsafe.

    This example creates an AS400ConnectionPool with a limit of 128 connections:

      // Create an AS400ConnectionPool.
      AS400ConnectionPool testPool = new AS400ConnectionPool();
      // Set a maximum of 128 connections to this pool.
      testPool.setMaxConnections(128);
      // Preconnect 5 connections to the AS400.COMMAND service.
      testPool.fill("myAS400", "myUserID", "myPassword", AS400.COMMAND, 5);
      // Create a connection to the AS400.COMMAND service. (Use the service number constants 
      // defined in the AS400 class (FILE, PRINT, COMMAND, DATAQUEUE, etc.))
      AS400 newConn = testPool.getConnection("myAS400", "myUserID", "myPassword", AS400.COMMAND);
      // Create a new command call object and run a command.
      CommandCall cmd = new CommandCall(newConn); 
      cmd.run("CRTLIB FRED");
      // Return the connection to the pool.
      testPool.returnConnectionToPool(newConn);  
      // Close the test pool.
      testPool.close();
      

    AS400ConnectionPool objects generate the following events:

    • ConnectionPoolEvent - The events fired are:
      • CONNECTION_CREATED
      • CONNECTION_EXPIRED
      • CONNECTION_POOL_CLOSED
      • CONNECTION_RELEASED
      • CONNECTION_RETURNED
      • MAINTENANCE_THREAD_RUN
    • PropertyChangeEvent
    See Also:
    Serialized Form
    • Field Detail

      • CCSID_DEFAULT

        public static final int CCSID_DEFAULT
        Indicates that the CCSID used for new connections is the same as the system default CCSID.
        See Also:
        Constant Field Values
    • Constructor Detail

      • AS400ConnectionPool

        public AS400ConnectionPool()
        Constructs an AS400ConnectionPool with default ConnectionPoolProperties.

    • Method Detail

      • close

        public void close()
        Close and cleanup the connection pool.
        Specified by:
        close in class ConnectionPool
      • fill

        public void fill(String systemName,
                String userID,
                ProfileTokenCredential profileToken,
                int service,
                int numberOfConnections)
                  throws ConnectionPoolException
        Preconnects a specified number of connections to a specific system, userID, profileToken, and service.
        Parameters:
        systemName - The name of the system where the connections should exist.
        userID - The name of the user.
        profileToken - The profile token to use to authenticate to the system.
        service - The service to be connected. See the service number constants defined by AS400 class.
        numberOfConnections - The number of connections to be made.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • fill

        public void fill(String systemName,
                String userID,
                ProfileTokenCredential profileToken,
                int service,
                int numberOfConnections,
                Locale locale)
                  throws ConnectionPoolException
        Preconnects a specified number of connections to a specific system, userID, profileToken, service, and Locale.
        Parameters:
        systemName - The name of the system where the connections should exist.
        userID - The name of the user.
        profileToken - The profile token to use to authenticate to the system.
        service - The service to be connected. See the service number constants defined by AS400 class.
        numberOfConnections - The number of connections to be made.
        locale - The Locale used to set the National Language Version (NLV) on the system for the AS400 objects created. Only the COMMAND, PRINT, and DATABASE services accept an NLV.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • fill

        public void fill(String systemName,
                String userID,
                String password,
                int service,
                int numberOfConnections)
                  throws ConnectionPoolException
        Preconnects a specified number of connections to a specific system, userID, password, and service.
        Parameters:
        systemName - The name of the system where the connections should exist.
        userID - The name of the user.
        password - The password of the user.
        service - The service to be connected. See the service number constants defined by AS400 class.
        numberOfConnections - The number of connections to be made.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • fill

        public void fill(String systemName,
                String userID,
                String password,
                int service,
                int numberOfConnections,
                Locale locale)
                  throws ConnectionPoolException
        Preconnects a specified number of connections to a specific system, userID, password, service, and Locale.
        Parameters:
        systemName - The name of the system where the connections should exist.
        userID - The name of the user.
        password - The password of the user.
        service - The service to be connected. See the service number constants defined by AS400 class.
        numberOfConnections - The number of connections to be made.
        locale - The Locale used to set the National Language Version (NLV) on the system for the AS400 objects created. Only the COMMAND, PRINT, and DATABASE services accept an NLV.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • finalize

        protected void finalize()
                         throws Throwable
        Closes the connection if not explicitly closed by the caller.
        Overrides:
        finalize in class ConnectionPool
        Throws:
        Throwable - If an error occurs.
      • getActiveConnectionCount

        public int getActiveConnectionCount(String systemName,
                                   String userID)
        Get the number of active (in-use) connections to a system. Note: The value returned is based only on systemName and userID, and does not reflect the authentication scheme (e.g. password, profile token).
        Parameters:
        systemName - The name of the system where the connections exist.
        userID - The name of the user.
        Returns:
        The number of connections that are currently in use.
      • getAvailableConnectionCount

        public int getAvailableConnectionCount(String systemName,
                                      String userID)
        Get the number of available connections to a system. Note: The value returned is based only on systemName and userID, and does not reflect the authentication scheme (e.g. password, profile token).
        Parameters:
        systemName - The name of the system where the connections exist.
        userID - The name of the user.
        Returns:
        The number of connections that are not currently in use.
      • getCCSID

        public int getCCSID()
        Returns the CCSID that is used when creating new connections. The default value is the system default CCSID as determined by the AS400 class.
        Returns:
        The CCSID, or CCSID_DEFAULT if the system default CCSID is used.
      • getConnection

        public AS400 getConnection(String systemName,
                          String userID,
                          String password,
                          int service)
                            throws ConnectionPoolException
        Get a connected AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. Note that the password is validated only when creating a new connection, of the match criteria to pull a connection out of the pool. This means that if an existing connection in the pool matches the systemName and userID passed in, a connection will be returned without the password being validated.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        password - The password of the user.
        service - The service to connect. See the service number constants defined by AS400 class.
        Returns:
        A connected AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getConnection

        public AS400 getConnection(String systemName,
                          String userID,
                          String password,
                          int service,
                          Locale locale)
                            throws ConnectionPoolException
        Get a connected AS400 object from the connection pool with the specified Locale. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        password - The password of the user.
        service - The service to connect. See the service number constants defined by AS400 class.
        locale - The Locale used to set the National Language Version (NLV) on the system for the AS400 object returned. Only the COMMAND, PRINT, and DATABASE services accept an NLV.
        Returns:
        A connected AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getConnection

        public AS400 getConnection(String systemName,
                          String userID,
                          int service)
                            throws ConnectionPoolException
        Deprecated. Use getConnection(String systemName, String userID, String password, int service) instead.
        Get a connected AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        service - The service to connect. See the service number constants defined by AS400 class.
        Returns:
        A connected AS400 object.
        Throws:
        ConnectionPoolException - Always thrown because this method has been deprecated.
      • getConnection

        public AS400 getConnection(String systemName,
                          String userID,
                          String password)
                            throws ConnectionPoolException
        Get an AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. The AS400 object may not be connected to any services. Note that the password is validated only when creating a new connection, of the match criteria to pull a connection out of the pool. This means that if an existing connection in the pool matches the systemName and userID passed in, a connection will be returned without the password being validated.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        password - The password of the user.
        Returns:
        An AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getConnection

        public AS400 getConnection(String systemName,
                          String userID,
                          String password,
                          Locale locale)
                            throws ConnectionPoolException
        Get an AS400 object from the connection pool with the specified Locale. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. The AS400 object may not be connected to any services.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        password - The password of the user.
        locale - The Locale used to set the National Language Version (NLV) on the system for the AS400 object returned. Only the COMMAND, PRINT, and DATABASE services accept an NLV.
        Returns:
        An AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getConnection

        public AS400 getConnection(String systemName,
                          String userID)
                            throws ConnectionPoolException
        Deprecated. Use getConnection(String systemName, String userID, String password) instead.
        Get an AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. The AS400 object may not be connected to any services.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        Returns:
        An AS400 object.
        Throws:
        ConnectionPoolException - Always thrown because this method has been deprecated.
      • getConnection

        public AS400 getConnection(String systemName,
                          String userID,
                          ProfileTokenCredential profileToken,
                          int service)
                            throws ConnectionPoolException
        Get a connected AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. Note that the profileTokenCredential is validated only when creating a new connection, of the match criteria to pull a connection out of the pool. This means that if an existing connection in the pool matches the systemName and userID passed in, a connection will be returned without the profileTokenCredential being validated.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        profileToken - The profile token to use to authenticate to the system.
        service - The service to connect. See the service number constants defined by AS400 class.
        Returns:
        A connected AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getConnection

        public AS400 getConnection(String systemName,
                          String userID,
                          ProfileTokenCredential profileToken,
                          int service,
                          Locale locale)
                            throws ConnectionPoolException
        Get a connected AS400 object from the connection pool with the specified Locale. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        profileToken - The profile token to use to authenticate to the system.
        service - The service to connect. See the service number constants defined by AS400 class.
        locale - The Locale used to set the National Language Version (NLV) on the system for the AS400 object returned. Only the COMMAND, PRINT, and DATABASE services accept an NLV.
        Returns:
        A connected AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getConnection

        public AS400 getConnection(String systemName,
                          String userID,
                          ProfileTokenCredential profileToken)
                            throws ConnectionPoolException
        Get an AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. The AS400 object may not be connected to any services. Note that the password is validated only when creating a new connection, not as part of the match criteria to pull a connection out of the pool. This means that if a connection in the pool matches the systemName and userID passed in, a connection will be returned without the password being validated.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        profileToken - The profile token to use to authenticate to the system.
        Returns:
        An AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getConnection

        public AS400 getConnection(String systemName,
                          String userID,
                          ProfileTokenCredential profileToken,
                          Locale locale)
                            throws ConnectionPoolException
        Get an AS400 object from the connection pool with the specified Locale. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. The AS400 object may not be connected to any services.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        profileToken - The profile token to use to authenticate to the system.
        locale - The Locale used to set the National Language Version (NLV) on the system for the AS400 object returned. Only the COMMAND, PRINT, and DATABASE services accept an NLV.
        Returns:
        An AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getSecureConnection

        public AS400 getSecureConnection(String systemName,
                                String userID,
                                String password)
                                  throws ConnectionPoolException
        Get an secure connected AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. The AS400 object may not be connected to any services. Note that the password is validated only when creating a new connection, of the match criteria to pull a connection out of the pool. This means that if an existing connection in the pool matches the systemName and userID passed in, a connection will be returned without the password being validated.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        password - The password of the user.
        Returns:
        A secure connected AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getSecureConnection

        public AS400 getSecureConnection(String systemName,
                                String userID)
                                  throws ConnectionPoolException
        Deprecated. Use getSecureConnection(String systemName, String userID, String password) instead.
        Get an secure connected AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. The AS400 object may not be connected to any services.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        Returns:
        A secure connected AS400 object.
        Throws:
        ConnectionPoolException - Always thrown because this method has been deprecated.
      • getSecureConnection

        public AS400 getSecureConnection(String systemName,
                                String userID,
                                String password,
                                int service)
                                  throws ConnectionPoolException
        Get a secure connected AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. Note that the password is validated only when creating a new connection, of the match criteria to pull a connection out of the pool. This means that if an existing connection in the pool matches the systemName and userID passed in, a connection will be returned without the password being validated.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        password - The password of the user.
        service - The service to connect. See the service number constants defined by AS400 class.
        Returns:
        A connected AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getSecureConnection

        public AS400 getSecureConnection(String systemName,
                                String userID,
                                int service)
                                  throws ConnectionPoolException
        Deprecated. Use getConnection(String systemName, String userID, String password, int service) instead.
        Get a secure connected AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        service - The service to connect. See the service number constants defined by AS400 class.
        Returns:
        A connected AS400 object.
        Throws:
        ConnectionPoolException - Always thrown because this method has been deprecated.
      • getSecureConnection

        public AS400 getSecureConnection(String systemName,
                                String userID,
                                ProfileTokenCredential profileToken)
                                  throws ConnectionPoolException
        Get an secure connected AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. The AS400 object may not be connected to any services. Note that the profileTokenCredential is validated only when creating a new connection, of the match criteria to pull a connection out of the pool. This means that if an existing connection in the pool matches the systemName and userID passed in, a connection will be returned without the profileTokenCredential being validated.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        profileToken - The profile token to use to authenticate to the system.
        Returns:
        A secure connected AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getSecureConnection

        public AS400 getSecureConnection(String systemName,
                                String userID,
                                ProfileTokenCredential profileToken,
                                int service)
                                  throws ConnectionPoolException
        Get a secure connected AS400 object from the connection pool. If an appropriate one is not found, one is created. If the maximum connection limit has been reached, an exception will be thrown. Note that the profileTokenCredential is validated only when creating a new connection, of the match criteria to pull a connection out of the pool. This means that if an existing connection in the pool matches the systemName and userID passed in, a connection will be returned without the profileTokenCredential being validated.
        Parameters:
        systemName - The name of the system where the object should exist.
        userID - The name of the user.
        profileToken - The profile token to use to authenticate to the system.
        service - The service to connect. See the service number constants defined by AS400 class.
        Returns:
        A connected AS400 object.
        Throws:
        ConnectionPoolException - If a connection pool error occurred.
      • getSocketProperties

        public SocketProperties getSocketProperties()
        Returns a copy of the socket properties that this AS400ConnectionPool specifies when it creates new AS400 objects, for example in fill(), getConnection(), or getSecureConnection().
        Returns:
        The socket properties. A null value indicates that this AS400ConnectionPool specifies no socket properties.
      • getSystemNames

        public String[] getSystemNames()
        Get a list of the system names in the pool.
        Returns:
        A list of the system names in the pool. If the the pool is empty, returns a zero-length list.
      • getUsers

        public Enumeration getUsers()
        Get an enumeration of the systemName/userId pairs in the pool. Note: The returned information is regardless of the authentication scheme used when filling the pool (e.g. password, profile token).
        Returns:
        An enumeration of the systemName/userIds in the pool
      • getUsers

        public String[] getUsers(String systemName)
        Get a list of the userIds in the pool with connections to a specific system. UserIds are listed regardless of whether their connections are currently active or disconnected. Note: The returned information is regardless of the authentication scheme used when filling the pool (e.g. password, profile token).
        Parameters:
        systemName - The name of the system of interest.
        Returns:
        A list of the userIds in the pool for system systemName. If there are no userIDs for that system, empty list is returned.
      • getConnectedUsers

        public String[] getConnectedUsers(String systemName)
        Get a list of the userIds in the pool with connections to a specific system. Only userIds with currently active (non-disconnected) connections are listed. Note: The returned information is regardless of the authentication scheme used when filling the pool (e.g. password, profile token).
        Parameters:
        systemName - The name of the system of interest.
        Returns:
        A list of the connected userIds in the pool for system systemName. If there are no connected userIDs for that system, empty list is returned.
      • removeFromPool

        public void removeFromPool(String systemName,
                          String userID)
        Remove the connections for a systemName/userID. Call this function if connections for a particular system/userID would no longer be valid. For example, if you change the password for a userId, you will want to call this method to remove the connections for the old userID combination. This will not invalidate connections in use; rather it will mean that the next time a connection is requested for that userID, a new connection will be established to the system. After you call this method, you may want to fill the pool with connections with your new password to avoid connection time. Note: This method will remove connections regardless of the authentication scheme used when filling the pool (e.g. password, profile token).
        Parameters:
        systemName - The system name of connections you want to remove.
        userID - The user ID of connections you want to remove.
      • removeFromPool

        public void removeFromPool(AS400 system)
        Remove the specified connection from the pool, and disconnect it. Call this function if a specific connection has been discovered to no longer be valid.

        This method should only be called by the process or thread to which the connection is currently allocated; that is, the process or thread that most recently obtained the connection via getConnection() or getSecureConnection(). To remove the connection from the pool, the process or thread holding the connection should call this method rather than returnConnectionToPool().

        Caution: The pool does not verify that the process or thread removing the connection, is the same as the process or thread to which the connection is currently allocated. This may cause unpredictable results if the connection is in use by another process or thread.

        Parameters:
        system - The system to remove from the pool.
      • returnConnectionToPool

        public void returnConnectionToPool(AS400 system)
        Return the AS400 object to the connection pool.

        This method should only be called by the process or thread to which the connection is currently allocated; that is, the process or thread that most recently obtained the connection via getConnection() or getSecureConnection().

        Caution: The pool does not verify that the process or thread returning the connection, is the same as the process or thread to which the connection is currently allocated. This may cause unpredictable results if the connection is in use by another process or thread.

        Parameters:
        system - The system to return to the pool.
        See Also:
        removeFromPool(AS400)
      • setCCSID

        public void setCCSID(int ccsid)
        Sets the CCSID to use when creating new connections. The default value is the system default CCSID as determined by the AS400 class. Note: This method only affects the CCSID of newly-created connections. Existing connections are not affected.
        Parameters:
        ccsid - The CCSID to use for connections in the pool, or CCSID_DEFAULT to indicate that the system default CCSID should be used.
      • setLog

        public void setLog(Log log)
        Set the Log object to log events. The default is to not log events.
        Parameters:
        log - The log object to use, or null if events should not be logged.
        See Also:
        Log
      • setSocketProperties

        public void setSocketProperties(SocketProperties properties)
        Sets the socket properties that this AS400ConnectionPool specifies when it creates new AS400 objects, for example in fill(), getConnection(), or getSecureConnection().
        Note that properties will apply only to AS400 objects created after this method is called. Any AS400 objects already in the pool are not affected.
        Parameters:
        properties - The socket properties. If null, then this AS400ConnectionPool will specify no socket properties when it creates new AS400 objects. That is, setSocketProperties(null) cancels the effects of any previous setSocketProperties().