JDBCDataStore

The gt-jdbc module is odd in that it provides a single implementation of a DataStore ( JDBCDataStore actually) and you are forced to use the DataStoreFinder mechanism in order to access the different formats.

In this case each format is implementing a custom SQLDialect as discussed in the gt-jdbc internals page.

Creating a JDBCDataStore

The process of creating a JDBC data store follows the regular steps of creating any type of datastore. That is defining the parameters to connect to the database in a map, and then creating the data store factory.:

        Map<String, Object> params = new HashMap<>();
        params.put("dbtype", "postgis");
        params.put("host", "localhost");
        params.put("port", 5432);
        params.put("schema", "public");
        params.put("database", "database");
        params.put("user", "postgres");
        params.put("passwd", "postgres");
        params.put("preparedStatements", true);
        params.put("encode functions", true);

        DataStore dataStore = DataStoreFinder.getDataStore(params);

An important parameter is the dbtype parameter which specifies the type of database to connect to.

Using JNDI

The above example illustrates the case where a direct connection to a database is specified. A JNDI connection can also be specified using the JDBCJNDIDataStoreFactory class.:

Map map = new HashMap();
map.put( "dbtype", "postgis");
map.put( "jndiReferenceName", "java:comp/env/jdbc/geotools");

DataStore store =  DataStoreFinder.getDataStore(map);

Connection Pooling

Internally JDBC data stores use a connection pool when creating database connections. Properly configuring a connection pool for your application can have a profound impact on performance.

Here is an example:

map.put( "max connections", 25);
map.put( "min connections", 10);
map.put( "connection timeout", 5);

Connection validation is on by default, it takes a small toll to make sure the connection is still valid before using it (e.g., make sure the DBMS did not drop it due to a server side timeout). If you want to get extra performance and you’re sure the connections will never be dropped you can disable connection validation with:

map.put( "validating connections", false);

Connection Parameters

All the gt-jdbc formats have the option of using the following set of connection parameters. You will need to consult the documentation for the plugin you are using; the following is provided to help with consistency.

Crucial to this is the agreement that they use a unique dbtype for each format.

Parameter	Description
dbtype	A unique database type identifier
host	Server to connect to
port	Port to connect to.
database	Database name
schema	Database schema
user	Username if required
passwd	Password if required
namespace	Namespace prefix to use for content

Advanced

Parameter	Description
Data Source	Optional: DataSource instance to use.

Connection Pooling

Parameter	Description
max connections	Maximum number of connection the pool will hold at any time, default is 10
min connections	Minimum number of connection the pool will hold at any time, default is 1
connection timeout	Maximum number of second the pool will wait when trying to obtain a connection, default is 20 seconds
validate connections	Flag controlling if the pool should validate connections when a new connection is obtained
Max open prepared statements	Maximum number of prepared statements kept open and cached for each connection in the pool. Set to 0 to have unbounded caching, -1 to disable
Test while idle	Periodically test if the connections are still valid also while idle in the pool
Time between evictor runs	Number of seconds between idle object evictor runs. The default value is 300 seconds.
Min evictable time	Number of seconds a connection needs to stay idle before the evictor starts to consider closing it
Evictor tests per run	Number of connections checked by the idle connection evictor for each of its runs. The default value is 3 connections.

Tweaking and Performance

Parameter	Description
fetch size	Number of records to read
Primary key metadata table	The optional table containing primary key structure and sequence associations. Either expressed as ‘schema.name’ or just ‘name’
Expose primary keys	Expose primary key columns as attributes