Plugins : Connection Provider

DataNucleus is developed as a plugin-driven framework and one of the components that is pluggable is the failover mechanism. DataNucleus provides a support for basic Failover algorithm, and is structured so that you can easily add your own failover algorithm and have them usable within your DataNucleus usage.

Failover algorithm for DataNucleus can be plugged using the plugin extension org.datanucleus.store.connection_provider .

Plugin extension-point Key Description Location
org.datanucleus.store_connectionprovider PriorityList Ordered List Algorithm datanucleus-rdbms


Interface

Any Connection Provider plugin will need to implement org.datanucleus.store.rdbms.ConnectionProvider . So you need to implement the following interface 

package org.datanucleus.store.rdbms;

import java.sql.Connection;
import java.sql.SQLException;

import javax.sql.DataSource;

/**
 * Connects to a DataSource to obtain a Connection.
 * The ConnectionProvider is not a caching and neither connection pooling mechanism.
 * The ConnectionProvider exists to perform failover algorithm on multiple DataSources
 * when necessary.
 * One instance per StoreManager (RDBMSManager) is created.
 * Users can provide their own implementation via the extension org.datanucleus.store_connectionprovider 
 */
public interface ConnectionProvider
{
    /**
     * Flag if an error causes the operation to thrown an exception, or false to skip to next DataSource. 
     * If an error occurs on the last DataSource on the list an Exception will be thrown no matter if 
     * failOnError is true or false. This is a hint. 
     * Implementations may ignore the user setting and force it's own behaviour
     * @param flag true if to fail on error
     */
    void setFailOnError(boolean flag);
    
    /**
     * Obtain a connection from the datasources, starting on the first
     * datasource, and if unable to obtain a connection skips to the next one on the list, and try again 
     * until the list is exhausted.
     * @param ds the array of datasources. An ordered list of datasources
     * @return the Connection, null if ds is null, or null if the DataSources has returned 
     *              a null as connection
     * @throws SQLException in case of error and failOnError is true or the error occurs while obtaining 
     *              a connection with the last
     * DataSource on the list
     */
    Connection getConnection(DataSource[] ds) throws SQLException;

}


Plugin Specification

So we now have our custom "Connection Provider" 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.connectionprovider" name="My DataNucleus plug-in" provider-name="MyCompany">
    <extension point="org.datanucleus.store_connectionprovider">
       <connection-provider class-name="mydomain.MyConnectionProvider" name="MyName"/>
    </extension>
</plugin>

So here we have our "ConnectionProvider" class "MyConnectionProvider" which is named "MyName". When constructing the PersistenceManagerFactory, add the setting datanucleus.rdbms.connectionProviderName=MyName .

Lifecycle

The ConnectionProvider instance is created when the RBMSManager is instantiated and hold as hard reference during the lifecycle of the RDBMSManager.