Package org.dellroad.stuff.schema

Class AbstractUpdatingDataSource

java.lang.Object

org.dellroad.stuff.schema.AbstractUpdatingDataSource

All Implemented Interfaces:

Wrapper, CommonDataSource, DataSource

Direct Known Subclasses:

SchemaUpdatingDataSource, UpdatingDataSource

public abstract class AbstractUpdatingDataSource
extends Object
implements DataSource

A DataSource that wraps an inner DataSource and automatically performs some update operation on the inner DataSource on first access.

The update operation is triggered by an invocation of triggerUpdate() or any DataSource method.

Instances can operate in synchronous or asychronous mode.

In synchronous mode, the update is performed by the thread that triggers the update, and simultaneous invocations of any DataSource method will block until the update is complete.

In asynchronous mode, the update is performed in a separate thread, and invocations of any DataSource method before the update is complete will throw an UpdateInProgressException.

The getUpdateCompleteFuture() returns a Future that waits for completion of the initial update; isUpdated() checks whether the update is complete.

The dataSource property is required.

Constructor Summary

Constructors

Constructor	Description
AbstractUpdatingDataSource()

Method Summary

Modifier and Type	Method	Description
Connection	getConnection()
Connection	getConnection(String username, String password)
protected DataSource	getInnerDataSource()	Get the underlying DataSource.
int	getLoginTimeout()
PrintWriter	getLogWriter()
Logger	getParentLogger()
Future<DataSource>	getUpdateCompleteFuture()	Get a Future that waits for the update of the underlying DataSource to be completed.
protected DataSource	getUpdatedDataSource()	Get the wrapped DataSource, triggering and waiting for it to be updated as necessary.
boolean	isAsynchronous()	Determine whether this instance is in asynchronous mode.
boolean	isUpdated()	Determine if the underlying DataSource has been updated.
boolean	isWrapperFor(Class<?> cl)
void	setAsynchronous(boolean asynchronous)	Configure mode.
void	setDataSource(DataSource dataSource)	Configure the underlying DataSource.
void	setLoginTimeout(int timeout)
void	setLogWriter(PrintWriter pw)
boolean	triggerUpdate()	Trigger the update of the underlying DataSource if it has not already been triggered.
boolean	triggerUpdate(Executor executor)	Trigger the update of the underlying DataSource if it has not already been triggered.
<T> T	unwrap(Class<T> cl)
protected abstract void	updateDataSource(DataSource dataSource)	Update the inner DataSource.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface javax.sql.CommonDataSource

createShardingKeyBuilder

Methods inherited from interface javax.sql.DataSource

createConnectionBuilder

Constructor Details

AbstractUpdatingDataSource

public AbstractUpdatingDataSource()

Method Details

setDataSource

public void setDataSource(DataSource dataSource)

Configure the underlying DataSource. Required property.

Parameters:

dataSource - underlying DataSource to update

Throws:

IllegalStateException - if an update has already been triggered

isAsynchronous

public boolean isAsynchronous()

Determine whether this instance is in asynchronous mode.

Returns:

true if this instance is in asynchronous mode, otherwise false

setAsynchronous

public void setAsynchronous(boolean asynchronous)

Configure mode.

Parameters:

asynchronous - true for asynchronous mode, false for synchronous mode

Throws:

IllegalStateException - if an update has already been triggered

updateDataSource

protected abstract void updateDataSource(DataSource dataSource)
                                  throws SQLException

Update the inner DataSource.

This method will be invoked at most once.

Parameters:

dataSource - the DataSource to update

Throws:

SQLException - if the update attempt fails

getInnerDataSource

protected DataSource getInnerDataSource()

Get the underlying DataSource.

Returns:

the underlying DataSource

isUpdated

public boolean isUpdated()

Determine if the underlying DataSource has been updated.

Returns:

true if the underlying DataSource has already been updated

triggerUpdate

public boolean triggerUpdate()
                      throws SQLException

Trigger the update of the underlying DataSource if it has not already been triggered.

In synchronous mode, this will perform the update in the current thread if necesssary. In asynchronous mode, this will spawn a new anonymous thread to do the update; use triggerUpdate(Executor) if more control is needed.

Returns:

true if update was triggered by this invocation, false if update had already been triggered or is completed

Throws:

IllegalStateException - if no DataSource has been configured

SQLException - if the update fails or has already failed

triggerUpdate

public boolean triggerUpdate(Executor executor)
                      throws SQLException

Trigger the update of the underlying DataSource if it has not already been triggered.

Parameters:

executor - in asynchronous mode, the executor that will actually perform the update, otherwise ignored

Returns:

true if update was triggered by this invocation, false if update had already been triggered or is completed

Throws:

IllegalStateException - if no DataSource has been configured

IllegalArgumentException - if in asynchronous mode and executor is null

SQLException - if the update fails or has already failed

getUpdateCompleteFuture

public Future<DataSource> getUpdateCompleteFuture()

Get a Future that waits for the update of the underlying DataSource to be completed.

The returned Future does not support cancellation; invoking Future.cancel(boolean) will generate an UnsupportedOperationException.

Note that this method does not actually trigger the update; use triggerUpdate() for that.

Returns:

update completed future

getConnection

public Connection getConnection()
                         throws SQLException

Specified by:

getConnection in interface DataSource

Throws:

SQLException

getConnection

public Connection getConnection(String username,
 String password)
                         throws SQLException

Specified by:

getConnection in interface DataSource

Throws:

SQLException

getLogWriter

public PrintWriter getLogWriter()
                         throws SQLException

Specified by:

getLogWriter in interface CommonDataSource

Specified by:

getLogWriter in interface DataSource

Throws:

SQLException

setLogWriter

public void setLogWriter(PrintWriter pw)
                  throws SQLException

Specified by:

setLogWriter in interface CommonDataSource

Specified by:

setLogWriter in interface DataSource

Throws:

SQLException

setLoginTimeout

public void setLoginTimeout(int timeout)
                     throws SQLException

Specified by:

setLoginTimeout in interface CommonDataSource

Specified by:

setLoginTimeout in interface DataSource

Throws:

SQLException

getLoginTimeout

public int getLoginTimeout()
                    throws SQLException

Specified by:

getLoginTimeout in interface CommonDataSource

Specified by:

getLoginTimeout in interface DataSource

Throws:

SQLException

unwrap

public <T> T unwrap(Class<T> cl)
             throws SQLException

Specified by:

unwrap in interface Wrapper

Throws:

SQLException

isWrapperFor

public boolean isWrapperFor(Class<?> cl)
                     throws SQLException

Specified by:

isWrapperFor in interface Wrapper

Throws:

SQLException

getParentLogger

public Logger getParentLogger()
                       throws SQLFeatureNotSupportedException

Specified by:

getParentLogger in interface CommonDataSource

Throws:

SQLFeatureNotSupportedException

getUpdatedDataSource

protected DataSource getUpdatedDataSource()
                                   throws SQLException

Get the wrapped DataSource, triggering and waiting for it to be updated as necessary.

Returns:

updated DataSource

Throws:

SQLException - if an error occurs

UpdateInProgressException - if an update is in progress and this instance is in asynchronous mode