Section : Documentation > Extensions

Extensions : Connection Factory

Plugin

Any plugin for a datastore needs a way of connecting to the datastore and linking these connections into the persistence process. This is provided by way of a ConnectionFactory. This is pluggable so you can define your own and register it for the datastore, and you use the plugin extension _org.datanucleus.storeconnectionfactory. This plugin point is intended to be implemented by provider of the datastore plugin. Below are two samples that provide this, but you will find at least the transactional one for any datastore plugin.

Plugin extension-point Name Datastore Transactional Location
org.datanucleus.store_connectionfactory rdbms/tx rdbms true datanucleus-rdbms
org.datanucleus.store_connectionfactory rdbms/nontx rdbms false datanucleus-rdbms

Interface

Any Connection Factory plugin will need to implement org.datanucleus.store.connection.ConnectionFactory. Javadoc So you need to implement the following interface

public interface ConnectionFactory
{
    /**
     * Obtain a connection from the Factory. 
     * The connection will be enlisted within the {@link org.datanucleus.Transaction} 
     * associated to the ObjectManager if "enlist" is set to true.
     * @param om the ObjectManager
     * @param options Any options for then creating the connection
     * @return the ManagedConnection
     */
    ManagedConnection getConnection(ObjectManager om, Map options);

    /**
     * Create the ManagedConnection.
     * Only used by ConnectionManager so do not call this.
     * @param om ObjectManager (if any)
     * @param transactionOptions the Transaction options this connection will be enlisted to, 
     *                           null if non existent
     * @return The ManagedConnection.
     */
    ManagedConnection createManagedConnection(ObjectManager om, Map transactionOptions);
}

Plugin Specification

So we now have our custom Connection Factory and we just need to make this into a DataNucleus plugin. To do this you simply add a file plugin.xml to your JAR at the root. The file plugin.xml should look like this

<?xml version="1.0"?>
<plugin id="mydomain.connectionfactory" name="My DataNucleus plug-in" provider-name="MyCompany">
    <extension point="org.datanucleus.store_connectionfactory">
        <connectionfactory name="rdbms/tx" class-name="org.datanucleus.store.rdbms.ConnectionFactoryImpl"
            transactional="true" datastore="rdbms"/>
        <connectionfactory name="rdbms/nontx" class-name="org.datanucleus.store.rdbms.ConnectionFactoryImpl"
            transactional="false" datastore="rdbms"/>
    </extension>
</plugin>

Note that you also require a MANIFEST.MF file as per the Extensions Guide.

So now for the datastore rdbms we will use this implementation when transactional or non-transactional

Lifecycle

The ConnectionFactory instance(s) are created when the StoreManager is instantiated and held as hard references during the lifecycle of the StoreManager.