Java Connection Pooling | AllegroGraph 9.0.1
Author: Franz Incorporated

Copyright (c) 2005 - 2026 Franz, Incorporated
Last updated 27 May 2026 at 10:34

# Java Connection Pooling 9.0.1

- Documentation Index
  - Release Notes
  - Quick Start
  - SSL/TLS Quick Start
  - Introduction
  - Setup and Configuration
    - Download
    - Server Installation
    - Server Configuration and Control
    - WebView
    - Database Upgrading
    - Managing Users
  - Server Management
    - Performance Tuning
    - Deleting Duplicate Triples
    - Purging Deleted Triples
    - Auditing
    - Managing Users
    - Replication
    - Point-in-Time Recovery
    - Transaction Log Archiving
    - Security Overview
    - Security Implementation
  - Tools
    - agtool
    - Data Loading
    - Data Export
    - Backup and Restore
    - Querying
    - RDFS++
    - Materializer
    - Event Scheduler
    - SHACL
  - Details
    - Triple Indices
    - Freetext Indices
    - Encoded IDs
    - Connection Pooling
    - N-dimensional Geospatial Overview
    - 2-D Geospatial
    - Temporal
    - Social Network
    - JavaScript
    - Datatypes
    - Data Conversion (Rapper)
    - Stored Procedures
    - Triple Attributes
    - Lineparse Format
  - Querying
    - SPARQL documentation summary
    - SPARQL Reference
    - SPIN
    - SPARQL Magic Properties
    - Prolog
  - 3rd-party tools
    - Solr text Indices
    - MongoDB integration
    - TopBraid Composer Plugin
    - Cloudera
  - Client APIs
    - Gruff
    - GraphTalker
    - REST/HTTP interface
    - HTTP reference
    - Javadocs (Sesame and Jena)
    - Python API
    - Lisp Reference
    - JavaScript
  - Tutorials
    - N-dimensional Geospatial
    - SPARQL Tutorial
    - Java Sesame
    - Java Jena
    - Python Sesame
    - Lisp
    - Prolog
    - More...
  - Other
    - Conferences and Seminars
    - Source Code on Github
    - Amazon EC2
    - Copyrights
  - Franz, Inc.

- AllegroGraph Java Connection Pooling introduction
- Features
- Lifetime of the Pool
- Lifetime of Connections
- Libraries

Documentation Index

## AllegroGraph Java Connection Pooling introduction

The relevant package in the Javadocs is com.franz.agraph.pool.

The agraph-java-client library now has a feature for pooling connections to the AllegroGraph server. This is useful in webserver and appserver applications where many threads need to access the same AllegroGraph database. By using a pool of connections, AllegroGraph server resources can be minimized while supporting concurrent access.

The API to the pool is the `AGConnPool` class in the `com.franz.agraph.pool` package. AGConnPool may be configured in code, or through JNDI with the `AGConnPoolJndiFactory` class. The AGConnPool implements `ObjectPool` from the Apache commons-pool library, and the objects it manages are `AGRepositoryConnection`. More details can be found in the javadocs.

## Features

The features of the pool are exposed through properties so it may be configured in JNDI or java code.

Related to the connection itself are properties: `serverUrl`, `catalog`, `repository`, `username`, `password`, `session`, and `sessionLifetime`. The session configures whether connections are shared, dedicated (`autoCommit`), or dedicated/transactional - it is recommended that applications set this appropriately on the pool, then not change the `setAutoCommit` property of the connection within the application code. The `sessionLifetime` helps manage server resources and is discussed more below.

Note that users of the pool will share the same connections and sessions (though not concurrently). For example, all connections will have the same repository and username. If different properties are needed, then multiple pools must be configured.

Not all features of the agraph-java-client library are supported yet in the pool properties. This includes managing catalogs and repositories, server scripts, rules, SNA, mappings, bulkMode, duplicates, and federation. These features must be managed in application code, and care must be taken since the connections will be reused after returning to the pool.

Related to the pooling mechanism are more properties: `initialSize`, `shutdownHook` (discussed below), `maxActive`, `maxWait`, `testOnBorrow`, and `testOnReturn`. `MaxActive` is important to limit server resources. The correct number is dependent on server resources and how many concurrent requests need to be handled. The server should have some number of `SessionPorts` configured based on machine resources, and to avoid running out of sessions, all possible pools (usually different JVMs) should have `maxActive` be a fraction of that number so that they can't request more than the server has. `MaxWait` is important so that borrowing a connection does not block your application request forever - it should be set to approximately the longest tolerable time a request should last before failing. TestOnBorrow is important so the application does not try to use stale connections, usually resulting in a "connection refused" error because the server session has been reclaimed due to inactivity (see `sessionLifetime`).

Also, commons-pool will run a background "eviction thread" based on these properties: `maxIdle`, `minIdle`, `testWhileIdle`, `timeBetweenEvictionRunsMillis`, `minEvictableIdleTimeMillis`, `softMinEvictableIdleTimeMillis`, and `numTestsPerEvictionRun`. This may reduce time that a request waits for a connection if `testOnBorrow` were called, and a new connection is established.

## Lifetime of the Pool

Care must be taken with the lifetime of the pool. Like all resource objects in Java, it must be closed/shutdown properly. Note that AllegroGraph server sessions are OS processes that must be closed explicitly - there is not a persistent socket connection for it to know when the client disappears, so close must be called. The server sessions should have a lifetime set so they will end after inactivity; the javadoc has more details as well as the server http protocol.

`AGConnPool` supports a property called shutdownHook to register itself with the JVM to shutdown resources before the JVM exits - this is a good last resort, but is not guaranteed and may not be as timely as other means. The lifetime of the pool may be controlled by the web/appserver based on JNDI configuration. A `shutdownHook` is not always appropriate, as in a webapp if the pool library exists within the application instead of configured with the web/appserver JNDI. In particular, if the shutdownHook is used and the webserver undeploys the pool without closing it, the shutdownHook will become the source of a leak, keeping the pool object, connections, and classes alive in the JVM. Closing a pool will remove its `shutdownHook` if there is one.

For webapps directly controlling the pool (not by JNDI), an easy way to manage the lifecycle of the pool is by implementing a `javax.servlet.ServletContextListener` to create and shutdown the pool, keeping the pool object where it can be accessed during requests.

When configuring the pool in JNDI with Tomcat, a Lifecycle Listener can be implemented and configured.

## Lifetime of Connections

Connections (class `AGRepositoryConnection`) must not be used by concurrent threads. The agraph-java library, and supporting libraries (Jena and RDF4J), are not built to be thread-safe.

Connections are borrowed from the pool just before use, and returned to the pool as soon as the thread is done with it. The return of the connection (method `pool.returnObject(connection)` or `connection.close()`) must be done in a finally block to ensure the connection is not leaked.

If a connection is leaked, the `sessionLifetime` (if used) will cause the server process to be closed eventually, and the only leak will be the connection objects in JVM memory, until the pool is shutdown. If `sessionLifetime` is not set, the AllegroGraph server may run out of resources or session ports, new connections will fail, and the server process must be killed by an admin.

For webapps, an easy way to manage the lifecycle of connections is by implementing a `javax.servlet.ServletRequestListener` to borrow and return a connection from the pool and keep it in a `ThreadLocal`. This may not be the most efficient use of connections if requests last significantly longer than the connection is really used.

## Libraries

This library uses the Apache commons-pool library for the underlying pool functionality.

If the pool is to be configured in a webserver with JNDI, the webserver will need access to the agraph jar and all of it's dependencies (RDF4J, Jena, commons-httpclient, commons-pool, logging, etc).

Alternatively, if the application is configuring AGConnPool directly, the agraph jar and its dependencies may be packaged with the application.

The agraph-java-client library uses the SLF4J API for logging, so you can choose the implementation see www.slf4j.org will log exceptions as DEBUG, but automatically recover. Apache commons-httpclient will log http errors and exceptions to INFO even though agraph-java ends up recovering.