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