Package javax.xml.xquery

## Interface PooledXQConnection

-     public interface PooledXQConnection

  An object that provides hooks for connection pool management. A `PooledXQConnection` object represents a physical connection to a data source. The connection can be recycled rather than being closed when an application is finished with it, thus reducing the number of connections that need to be made.

  An application programmer does not use the `PooledXQConnection` interface directly; rather, it is used by a middle tier infrastructure that manages the pooling of connections.

  When an application calls the method `XQDataSource.getConnection`, it gets back an `XQConnection` object. If connection pooling is being done, that `XQConnection` object is actually a handle to a `PooledXQConnection` object, which is a physical connection.

  The connection pool manager, typically the application server, maintains a pool of `PooledXQConnection` objects. If there is a `PooledXQConnection` object available in the pool, the connection pool manager returns an `XQConnection` object that is a handle to that physical connection. If no `PooledXQConnection` object is available, the connection pool manager calls the `ConnectionPoolXQDataSource` method `getPooledConnection` to create a new physical connection and returns a handle to it.

  When an application closes a connection, it calls the `XQConnection` method `close`. When connection pooling is being done, the connection pool manager is notified because it has registered itself as an `XQConnectionEventListener` object using the `PooledXQConnection` method `addConnectionEventListener`. The connection pool manager deactivates the handle to the `PooledXQConnection` object and returns the `PooledXQConnection` object to the pool of connections so that it can be used again. Thus, when an application closes its connection, the underlying physical connection is recycled rather than being closed.

  The physical connection is not closed until the connection pool manager calls the `PooledXQConnection` method `close`. This method is generally called to have an orderly shutdown of the server or if a fatal error has made the physical connection unusable.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addConnectionEventListener​(XQConnectionEventListener listener)` | Registers the given event listener so that it will be notified when an event occurs on this `PooledXQConnection` object.
    `void` | `close()` | Closes the physical connection that this `PooledXQConnection` object represents.
    `XQConnection` | `getConnection()` | Creates and returns an `XQConnection` object that is a handle for the physical connection that this `PooledXQConnection` object represents.
    `void` | `removeConnectionEventListener​(XQConnectionEventListener listener)` | Removes the given event listener from the list of components that will be notified when an event occurs on this `PooledXQConnection` object.

- - ### Method Detail

    - #### getConnection

          XQConnection getConnection()
                              throws XQException

      Creates and returns an `XQConnection` object that is a handle for the physical connection that this `PooledXQConnection` object represents. The connection pool manager calls this method when an application has called the `XQDataSource` method `getConnection` and there are no `PooledXQConnection` objects available.
      Returns:
        an `XQConnection` object that is a handle to this `PooledXQConnection` object
      Throws:
        `XQException` - if a datasource access error occurs

    - #### close

          void close()
              throws XQException

      Closes the physical connection that this `PooledXQConnection` object represents. An application never calls this method directly; it is called by the connection pool manager.
      Throws:
        `XQException` - if a datasource access error occurs

    - #### addConnectionEventListener

          void addConnectionEventListener​(XQConnectionEventListener listener)

      Registers the given event listener so that it will be notified when an event occurs on this `PooledXQConnection` object.
      Parameters:
        `listener` - a component, usually the connection pool manager, that has implemented the `XQConnectionEventListener` interface and wants to be notified when the connection is closed or has an error
      See Also:
        `removeConnectionEventListener(javax.xml.xquery.XQConnectionEventListener)`

    - #### removeConnectionEventListener

          void removeConnectionEventListener​(XQConnectionEventListener listener)

      Removes the given event listener from the list of components that will be notified when an event occurs on this `PooledXQConnection` object.
      Parameters:
        `listener` - a component, usually the connection pool manager, that has implemented the `XQConnectionEventListener` interface and been registered with this `PooledXQConnection` object as a listener
      See Also:
        `addConnectionEventListener(javax.xml.xquery.XQConnectionEventListener)`