AGConnPool (agraph-java-client 5.0.4-SNAPSHOT API)
Description: declaration: package: com.franz.agraph.pool, class: AGConnPool

Package com.franz.agraph.pool

# Class AGConnPool

java.lang.Object
com.franz.agraph.pool.AGConnPool

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`, `ObjectPool<AGRepositoryConnection>`

public class AGConnPool extends Object implements ObjectPool<AGRepositoryConnection>, AutoCloseable
Pooling for `AGRepositoryConnection`s. The recommended way to create a pool is by `create(Object...)` or by configuring a `AGConnPoolJndiFactory` with your appserver.

         AGConnPool pool = AGConnPool.create(
             AGConnProp.serverUrl, "http://localhost:10035",
             AGConnProp.username, "test",
             AGConnProp.password, "xyzzy",
             AGConnProp.catalog, "/",
             AGConnProp.repository, "my_repo",
             AGConnProp.session, AGConnProp.Session.DEDICATED,
             AGPoolProp.shutdownHook, true,
             AGPoolProp.maxActive, 10,
             AGPoolProp.initialSize, 2,
             AGPoolProp.warmup, true,
             AGPoolPool.warmupIncludeStrings, true,
             AGConnPool.warmupIncludeTriples, false);
         AGRepositoryConnection conn = pool.borrowConnection();
         try {
             ...
             conn.commit();
         } finally {
             conn.close();
             // or equivalently
             pool.returnObject(conn);
         }

This pool delegates the pooling implementation to another pool (a `GenericObjectPool`). When `Connections` are `borrowed`, they are wrapped so that `AutoCloseable.close()` will call `ObjectPool.returnObject(Object)` instead of actually closing.

Closing the connection pool is important because server sessions will stay active until `AGConnProp.sessionLifetime`. The option to use a Runtime shutdownHook is built-in with `AGPoolProp.shutdownHook`. Another option is to use `ServletContextListener` - this is appropriate if the agraph jar is deployed within your webapp and not with the webserver. With tomcat, a Lifecycle Listener can be configured, but the implementation to do this is not included in this library.

Note, when `close()` is called on a `AGConnPool`, connections that have not been returned to the pool will *not* be closed. Such connections will be closed immediately when returned to the pool.

In addition to standard commons-pool parameters this class supports some other features:

- `initialSize` can be used to pre-create a set number of connections. By default the pool only opens connections if needed.
- `warmup` can be set to `true` to force the server to read internal structures of the repository into memory, thus speeding up future requests. If requested, this will happen at pool creation time. `warmupIncludeStrings` and `warmupIncludeStrings` can be set to false to exclude specific structures from the warmup operation.

Since:
  v4.3.3

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addObject()`
  `AGRepositoryConnection`
  `borrowConnection()`
  Deprecated.
  Use `borrowObject()` instead.
  `AGRepositoryConnection`
  `borrowObject()`
  `void`
  `clear()`
  `void`
  `close()`
  `static AGConnPool`
  `create(Object... keyValuePairs)`
  Create a pool from configuration properties.
  `static AGConnPool`
  `create(Map<AGConnProp,String> connProps, Map<AGPoolProp,String> poolProps)`
  Create a pool from configuration properties.
  `static AGConnPool`
  `create(PooledObjectFactory<AGRepositoryConnection> factory, AGPoolConfig poolConfig)`
  Creates a pool using a custom connection factory.
  `void`
  `ensureIdle(int n)`
  `int`
  `getNumActive()`
  `int`
  `getNumIdle()`
  `void`
  `invalidateObject(AGRepositoryConnection conn)`
  `void`
  `returnObject(AGRepositoryConnection conn)`
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface org.apache.commons.pool2.ObjectPool

  `addObjects, invalidateObject`

- ## Method Details

  - ### create

    public static AGConnPool create(PooledObjectFactory<AGRepositoryConnection> factory, AGPoolConfig poolConfig)
    Creates a pool using a custom connection factory.
    Parameters:
      `factory` - a connection factory.
      `poolConfig` - an `AGPoolConfig`
    Returns:
      AGConnPool the connection pool object

  - ### create

    public static AGConnPool create(Map<AGConnProp,String> connProps, Map<AGPoolProp,String> poolProps) throws org.eclipse.rdf4j.repository.RepositoryException
    Create a pool from configuration properties.
    Parameters:
      `connProps` - keys are `AGConnProp`
      `poolProps` - keys are `AGPoolProp`
    Returns:
      AGConnPool the connection pool object
    Throws:
      `org.eclipse.rdf4j.repository.RepositoryException` - if an error occurs during pool creation

  - ### create

    public static AGConnPool create(Object... keyValuePairs) throws org.eclipse.rdf4j.repository.RepositoryException
    Create a pool from configuration properties.
    Parameters:
      `keyValuePairs` - alternating key/value pairs where keys are `AGConnProp` and `AGPoolProp`
    Returns:
      `AGConnPool` the connection pool object
    Throws:
      `org.eclipse.rdf4j.repository.RepositoryException` - if an error occurs during pool creation

  - ### addObject

    public void addObject() throws Exception
    Specified by:
      `addObject` in interface `ObjectPool<AGRepositoryConnection>`
    Throws:
      `Exception`

  - ### borrowObject

    public AGRepositoryConnection borrowObject() throws org.eclipse.rdf4j.repository.RepositoryException
    Specified by:
      `borrowObject` in interface `ObjectPool<AGRepositoryConnection>`
    Throws:
      `org.eclipse.rdf4j.repository.RepositoryException`

  - ### borrowConnection

    @Deprecated public AGRepositoryConnection borrowConnection()
    Deprecated.
    Use `borrowObject()` instead.
    Same as `borrowObject()`.
    Returns:
      A connection.

  - ### clear

    public void clear() throws Exception
    Specified by:
      `clear` in interface `ObjectPool<AGRepositoryConnection>`
    Throws:
      `Exception`

  - ### getNumActive

    public int getNumActive() throws UnsupportedOperationException
    Specified by:
      `getNumActive` in interface `ObjectPool<AGRepositoryConnection>`
    Throws:
      `UnsupportedOperationException`

  - ### getNumIdle

    public int getNumIdle() throws UnsupportedOperationException
    Specified by:
      `getNumIdle` in interface `ObjectPool<AGRepositoryConnection>`
    Throws:
      `UnsupportedOperationException`

  - ### invalidateObject

    public void invalidateObject(AGRepositoryConnection conn) throws Exception
    Specified by:
      `invalidateObject` in interface `ObjectPool<AGRepositoryConnection>`
    Throws:
      `Exception`

  - ### returnObject

    public void returnObject(AGRepositoryConnection conn) throws Exception
    Specified by:
      `returnObject` in interface `ObjectPool<AGRepositoryConnection>`
    Throws:
      `Exception`

  - ### ensureIdle

    public void ensureIdle(int n) throws Exception
    Throws:
      `Exception`

  - ### close

    public void close()
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Specified by:
      `close` in interface `ObjectPool<AGRepositoryConnection>`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`