Package net.sourceforge.hivetranse.transaction.jdbc

This is the main package for JDBC-specific transaction handling under HiveMind.

See:
Description

Interface Summary

ConnectionsRepository

Interface implemented by the object returned by JdbcTransactionService.getCurrentTransaction.

Class Summary

ConnectionProxyFactory	This service creates Proxys to JDBC Connections.
ConnectionsRepositoryImpl	Actual implementation class for ConnectionsRepository.
JdbcTransactionService	Service managing JDBC transactions.

Package net.sourceforge.hivetranse.transaction.jdbc Description

This is the main package for JDBC-specific transaction handling under HiveMind.

It implements the TransactionService specifically for JDBC Connections.
It also implements the necessary services to directly inject Connection into the application services.
The JdbcTransactionService can work with more than one DataSource at the same time.

DataSource

The JdbcTransactionService creates JDBC Connections from a service that must implement DataSource.
This package does not provide any such service for a good reason: this kind of service can be offered by existing libraries and configured into HiveMind easily.
For each database that you need to access, it is necessary to configure a DataSource service in HiveMind with its own service-id. That service will be used as explained later.
The actual implementation of DataSource must be pooled, while the service (as defined in hivemodule.xml configuration) must use the singleton service model.
The following excerpt shows an example of configuration for a DataSource implementation from jakarta commons-dbcp library.

        <service-point id="MyDataSource" interface="javax.sql.DataSource">
                <invoke-factory model="singleton">
                        <construct class="org.apache.commons.dbcp.BasicDataSource">
                                <set property="driverClassName" value="com.mysql.jdbc.Driver"/>
                                <set property="url" value="jdbc:mysql://localhost/test"/>
                                <set property="username" value="root"/>
                                <set property="password" value="xxx"/>
                                <set property="defaultAutoCommit" value="false"/>
                                <set property="maxActive" value="10"/>
                                <set property="initialSize" value="5"/>
                        </construct>
                </invoke-factory>
        </service-point>

It is advised to eager-load the DataSource services through HiveMind EagerLoad configuration point, so that the pool is initialized at startup time, not on first request from services (which may mean on first request of the first user). This can be done with the following declaration in hivemodule.xml:

        <contribution configuration-id="hivemind.EagerLoad">
                <load service-id="MyDataSource"/>
        </contribution>

Connection

When using JdbcTransactionService, you need to configure a service that implements Connection. This service must absolutely be declared as in the example below (except the id of the service and the id of the DataSource service that it uses).

        <service-point id="MyConnection" interface="java.sql.Connection">
                <invoke-factory      service-id="hivemind.jdbc.ConnectionFactory" model="singleton">
                        <datasource id="MyDataSource"/>
                </invoke-factory>
        </service-point>

Please note that, although it may sound strange at first sight, this service must use the singleton service model.
Such a Connection service can then be injected in your services that need it. Those services just need to use the injected Connection in a usual way, as if it had been obtained directly from a DataSource with the exception that the code of your service should never call commit, rollback, or close on this Connection.

Multiple DataSources

Although the JdbcTransactionService is not based on JTA, it is still possible to define more than one DataSource, hence more than one Connection service (each to a different DataSource, ie a different database).
However, since the resulting transactions are not enroled in a JTA transaction, such a usage is not considered safe in the sense that it is possible that one Connection has its transaction committed while another one has its transaction rolled back.
In more detail, the JdbcTransactionService will try to commit (or rollback) all the Connections transactions at the same time, but if one commit (or rollback) fails after the previous one has succeeded, then the resulting state of all databases will probably be inconsistent.
If your application can live with that, then you can feel free to use multiple DataSources with JdbcTransactionService.