JDBC Callbacks
- Contact: Justin Deoliveira
- Tracker: GEOT-5639
- TLDR: Add callback interface for JDBC modules.
- Pull Request: jdbc-callback
The motivation for this proposal is to allow the plugging in of instrumentation code into the JDBC data access module. The use case being to add the ability to provide metrics in production about how communication with the database is performing. These sorts of metrics are common in many applications and a crucial part of managing applications in production. The dropwizard metrics library has become a very common way of capturing and reporting app metrics. This proposal provides the underlying framework on top of which something like dropwizard could be used.
It should be clarified that at this time the callback proposal will not cover all communication with the database. It only covers the "normal query". Things like joins, aggregates, etc... are not covered. But the proposal leaves the "door open" for such callbacks to added at a future time.
References:
- Under Discussion
- In Progress
- Completed
- Rejected,
- Deferred
Voting:
- Andrea Aime: +1
- Ben Caradoc-Davies: +1
- Christian Mueller:
- Ian Turton: +1
- Justin Deoliveira: +1
- Jody Garnett: +1
- Simone Giannecchini:
- Add new interfaces
- Update JDBC datastore adding new parameter, and loading of callback factory
- Update JDBC datastore docs
All API added as part of this proposal is additive, no existing API should be affected.
The main addition is the top level JDBCCallbackFactory interface, that looks something like:
interface JDBCCallbackFactory {
/**
* Callback factory name.
*/
String getName();
/**
* Creates a callback for {@link JDBCFeatureReader}.
*/
JDBCReaderCallback createReaderCallback();
}
This factory is responsible for creating callbacks for specific JDBC data store components. At this time the only component for which this will occur is the feature reader. But the idea is that this could later be extended to include callbacks for other JDBC objects. Factories are managed via the normal GeoTools SPI plugin framework.
The factory creates instances of the JDBCReaderCallback interface that looks like:
public interface JDBCReaderCallback {
/**
* Called when the reader is created.
*
* @param reader The feature reader.
*/
void init(JDBCFeatureReader reader);
/**
* Called directly before the reader makes it's initial query to the database.
*
* @param st The query statement being executed.
*/
void beforeQuery(Statement st);
/**
* Called directly after the reader makes it's initial query to the database.
*
* @param st The query statement that was executed.
*/
void afterQuery(Statement st);
/**
* Called when an error occurs making the initial query to the database.
*/
void queryError(Exception e);
/**
* Called before the reader makes a call to {@link java.sql.ResultSet#next()}.
*
* @param rs The result set.
*/
void beforeNext(ResultSet rs);
/**
* Called after the reader makes a call to {@link java.sql.ResultSet#next()}.
*
* @param rs The result set.
* @param hasMore Whether or not any more rows exist in the {@link java.sql.ResultSet}
*/
void afterNext(ResultSet rs, boolean hasMore);
/**
* Called when an error occurs fetching the next row in the result set.
* @param e
*/
void rowError(Exception e);
/**
* Called after the last row from the reader {@link java.sql.ResultSet} is read.
*
* @param reader The feature reader.
*/
void finish(JDBCFeatureReader reader);
}
The interface contains a number of methods that are called during the lifecycle of a JDBC feature reader, specifically:
- before and after the initial query to the database is made
- before and after each row from the result set is obtained
- on a database error
- after the result set has been exhausted
Two methods of specifying a callback factory will be supported initially.
- Using a system property of the form
gt2.jdbc.callback. The value of which will be the name of the callback factory. - Using a datastore parameter on the JDBC datastore itself.