FoDS – Failover DataSource

FODS – Fail-over data-source for any JDBC compatible database.


Add redundancy to your application. This solution is fully transparent, so you can use it for all JDBC compatible databases without changing your application code.

License: Apache License 2.0
Source code: gitHub


FoDS modules

FoDS contains two modules fods-core and fods-client. Add those two jars to your application server classpath. If you want to create your own extension for fods you will need to implement some of interfaces from fods-client jar.

Module foDS core:
FoDS core is a main part of this project. If you want to provide database fail over layer for your application use it. Simple add a foDS data-source to your application.
Simple configuration file for Apache Tomcat 6.0 can be found at the bottom of this page. It is only example, you can use foDS for any kind of java applications. FoDS registers it’s own JMX bean, so you can use jconsole or tjconsole (text version of jconsole) to manipulate or access current state of foDS.

Module foDS client:
If you want to check current state of fods datasource in your application code, use foDS client. It provides communication API for foDS core. Communication layer
between foDS core and foDS client is MXBean registered on platform default JXM server, so the foDS data-source and foDS client must be executed on the same JVM.


How does it work?

  1. An application request for connection from foDS (fail over data source).
  2. DataSource’s selector is used to choose database that should be used.
  3. Database’s connectionCreator is used to obtain database connection.
  4. DataSource checks that obtained connection is valid by executing test query (configuration property: testSQL).
  5. If connection is invalid the database is marked as broken. Next go to 2.
  6. If there is no valid database available then dataSource throws SQLException.


Features

  • Fail over mechanism for databases.
  • Load balancing mechanism for databases.
  • Custom selector implementation provides ability to create your own database selection strategy.
  • Different connectionCreators can be used to obtain a sql connection.
  • Logging to commons-logging, slf4j, java-logging or console.
  • Manageable via jconsole (MXBeans).
  • Database usage statistics.
  • Multiple and simple configuration methods.


Configuration

Add to jdni tree a DataSource – org.jsoftware.fods.FoDataSource. Class FoDataSource has three constructors:

  1. public FoDataSource(java.util.Properties props) throws IOException – this one creates FoDataSource from java.util.Properties
  2. public FoDataSource(java.io.InputStream inputStream) throws IOException – this creates properties from inputStream and uses those properties to create FoDataSource
  3. public FoDataSource(java.lang.String loaction) throws IOException – this constructor takes location parameter. A location is used to find properties file. The location parameter can be a classpath (server classpath) location or file path.

Examples of FoDataSource configuration as jndi resource:


Properties file structure

FoDS property file contains mail properties section and one or more database specific sections. A main type property can not contain any dots in property name. A database property must contain at least one dot in property name. That dot separates database name and real property name. An example of database property name is:

myDB.jdbcURI=jdbc:hsqldb:mem:myDatabase

myDB is a database name and jndiURI is real name of the property. Database properties creates a database specific configuration. There is one required database property connectionCreatorFactory a value of this property must be a implementation of org.jsoftware.fods.client.ext.ConnectionCreatorFactory interface. Each ConnectionCreatorFactory can specify its own set of required and optional parameters. You can also add a testSQL property to database specifics properties to override main testSQL value for this database.


Available parameters

Main parameters:

property name

description

type

default value

fodsName

Name of foDataSource.

text

no default but value is required

statsEnabled

Enable statistics.

boolean

true

registerMXBeans

Register MBeans that allows foDS management via jconsole.

boolean

true

disableEvents

You can add event listeners via MXBean. Each database or foDS change a state a proper event is raised. Disable it in case of performance problems.

boolean

false

selectorFactory

Implementation of org.jsoftware.fods.client.ext.SelectorFactory.

class

org.jsoftware.fods.

DefaultSelectorFactory

selectorMinRecoveryTime

Minimal time that foDS tries to use broken database. This feature is implemented by Selector and can be not available if selector do not provide it.

number [ms]

180000

testSQL

SQL statement used to test a connection.

string

select 1+2

loggerLogEvents

If events should be logged.

boolean

true

loggerDebugOn

Turn on debug logs.

boolean

false

loggerForceLogOnConsole

Always log to standard output.

boolean

false

loggerLogLongSQLs

Log statements that executes longer then value (time). If less then zero then this feature is disabled.

number

[ms]

-1

loggerFile

Log into a file. If not specified then this feature is disabled. Value is a path to log file.

string

no default value

Available selectorFactory implementations:

  • org.jsoftware.fods.DefaultSelectorFactory and org.jsoftware.fods.RoundRobinOnFailSelectorFactory – create a selector that changes database only in case of database failure.
  • org.jsoftware.fods.RoundRobinSelectorFactory – creates selector that changes database each time a connection is required.

This two above selector has a optional property (main configuration) selectorSequence. You can use this property to specify a database selection order. A value o this property database names separated with coma.

Database section parameters:

 There is only one required property for each database configuration a connnectionCreatorFactory. Value of this property must be a name of class that implements org.jsoftware.fods.client.ext.ConnectionCreatorFactory. Other obligatory and optional database configuration properties depends on implementation of connectionCreatorFactory.

You can write your own ConnectionCreatorFactory or choose one of:

  • org.jsoftware.fods.SimplePoolConnectionCreatorFactory
  • org.jsoftware.fods.SingleConnectionJdbcConnectionCreatorFactory

Those two ConnectionCreatorFactories has following obligatory properties (in database configuration section):

  • driverClassName = a class name of jdbc driver
  • jdbcURI = jdbc uri
  • user = database user name
  • password = database password

For more information see project’s javadocs or example fods-example.properties file.


Author contact

In case of bugs or new feature suggestions please contact me at marek.szalik@removeIT.jsoftware.org or leave a comment.