org.tentackle.db
Class ModificationThread

java.lang.Object
  java.lang.Thread
      org.tentackle.db.ModificationThread

All Implemented Interfaces:

Runnable

public class ModificationThread
extends Thread

Thread to monitor the modification table.
Runs on a separate db connection and invokes runnables if modifications are detected.

Author:

harald

Nested Class Summary

class	ModificationThread.ModificationEntry Entry for each table (or class) to watch for modifications.
static interface	ModificationThread.SerialRunnable Special runnable invoked from within the ModificationThread whenever a serial on a table has changed.

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

protected	ModificationThread() Creates a dummy thread. Will never start and just log what would be registered It is used at startup for db-classes that register runnables before the real modthread is created.
protected	ModificationThread(Db db, long mseconds, boolean cloneDb) Creates a modification thread.

Method Summary

static ModificationThread	createThread(Db db, long mseconds) Creates a modification thread as a singleton with a cloned db connection.
static ModificationThread	createThread(Db db, long mseconds, boolean cloneDb) Creates a modification thread as a singleton.
Db	getDb() Gets the db connection for this thread.
long[]	getIdSerialForName(String tableName) Gets the pair of id/serial for a given tablename.
long	getInterval() Gets the polling interval.
long	getMasterSerial() Gets the current master serial.
protected int	getRemoteDelegateId() Gets the remote delegate.
long[]	getSerials(long[] ids) Gets all ModificationEntries (synchronized).
static ModificationThread	getThread() Gets the single modification thread. This is the method applications should refer to the modthread.
boolean	isDummy() Determines whether this is the dummy thread.
boolean	isIdle() Determines whether this is idle.
void	poll() Runs one poll and invokes the ModificationThread.SerialRunnables if a modification is detected.
long[]	readSerials(long[] ids) Reads serials for given ids.
void	registerMasterSerialRunnable(Runnable runnable) Registers a pure runnable to be executed if the master serial has changed
void	registerRunnable(Runnable runnable) Registers a pure runnable to be executed in the modification thread.
void	registerShutdownRunnable(Runnable runnable) Registers a pure runnable to be executed if the ModificationThread is terminated due to severe errors.
void	registerTable(String tableName, ModificationThread.SerialRunnable serialRunnable) Registers a table with a runnable invoked from the ModificationThread.
void	registerTable(String tableName, Runnable runnable) Registers a table with a runnable that will be invoked in the GUI-Thread.
void	requestToStop() Request to stop the thread.
void	run() The workhorse. Clones the db connection, sets the db-group and then in loop periodically invokeRunOnce() and poll().
void	runOnce(Runnable runnable) Runs a runnable within the modification thread's context.
void	runOnceAndWait(Runnable runnable) Runs a runnable within the modification thread's context and waits for completion.
long[]	selectIdSerialForName(String tableName) Selects the pair of id/serial for a given tablename.
long	selectMasterSerial() Reads the master-serial from the database.
String	selectNameForId(long id) Selects the tablename for a given ID.
void	setIdle(boolean idle) Sets the idle state of this thread. Application threads using the primary db-connection (i.e.
void	setInterval(long mseconds) Sets the polling interval.
void	terminate() Terminates this thread. Will request to stop and wait until stopped.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Constructor Detail

ModificationThread

protected ModificationThread(Db db,
                             long mseconds,
                             boolean cloneDb)

Creates a modification thread.

Parameters:

db - the database connection

mseconds - polling interval in milliseconds

cloneDb - true if clone db connection on start

ModificationThread

protected ModificationThread()

Creates a dummy thread.
Will never start and just log what would be registered It is used at startup for db-classes that register runnables before the real modthread is created. E.g. a table "users" that must be read for authentication.

Method Detail

createThread

public static ModificationThread createThread(Db db,
                                              long mseconds,
                                              boolean cloneDb)

Creates a modification thread as a singleton.

Parameters:

db - the database connection

mseconds - polling interval in milliseconds

cloneDb - true if clone db connection on start

Returns:

the thread (singleton)

Throws:

DbRuntimeException - if already created and was not the dummy thread

createThread

public static ModificationThread createThread(Db db,
                                              long mseconds)

Creates a modification thread as a singleton with a cloned db connection.

Parameters:

db - the database connection

mseconds - polling interval in milliseconds

Returns:

the thread (singleton)

Throws:

DbRuntimeException - if already created and was not the dummy thread

getThread

public static ModificationThread getThread()

Gets the single modification thread.
This is the method applications should refer to the modthread.

Returns:

the modification thread

getDb

public Db getDb()

Gets the db connection for this thread.

Returns:

the db connection

isDummy

public boolean isDummy()

Determines whether this is the dummy thread.

Returns:

true if this is the dummy thread

See Also:

ModificationThread()

runOnce

public void runOnce(Runnable runnable)

Runs a runnable within the modification thread's context.

Parameters:

runnable - the runnable to run

runOnceAndWait

public void runOnceAndWait(Runnable runnable)
                    throws InterruptedException

Runs a runnable within the modification thread's context and waits for completion.

Notice: if other runnables are already registered but not executed so far, those runnables will be executed *before* the runnable passed by this method.

Parameters:

runnable - the runnable to run

Throws:

InterruptedException

requestToStop

public void requestToStop()

Request to stop the thread. Applications should better use terminate() instead.

See Also:

terminate()

terminate

public void terminate()

Terminates this thread.
Will request to stop and wait until stopped.

See Also:

requestToStop()

run

public void run()

The workhorse.
Clones the db connection, sets the db-group and then in loop periodically invokeRunOnce() and poll(). On requestToStop() closes the db connection and terminates the thread.

Specified by:

run in interface Runnable

Overrides:

run in class Thread

See Also:

Thread.start(), Thread.stop(), Thread.Thread(ThreadGroup, Runnable, String)

poll

public void poll()

Runs one poll and invokes the ModificationThread.SerialRunnables if a modification is detected. The implementation keeps the sync locks as short as possible.

registerTable

public void registerTable(String tableName,
                          Runnable runnable)

Registers a table with a runnable that will be invoked in the GUI-Thread.

Parameters:

tableName - is the name of the table to watch for

runnable - to execute if something in table changed (invoked by EventQueue.invokeLater)

registerTable

public void registerTable(String tableName,
                          ModificationThread.SerialRunnable serialRunnable)

Registers a table with a runnable invoked from the ModificationThread.

Parameters:

tableName - is the name of the table to watch for

serialRunnable - to execute if something in table changed.

registerRunnable

public void registerRunnable(Runnable runnable)

Registers a pure runnable to be executed in the modification thread.

Parameters:

runnable - the runnable

registerMasterSerialRunnable

public void registerMasterSerialRunnable(Runnable runnable)

Registers a pure runnable to be executed if the master serial has changed

Parameters:

runnable - the runnable

registerShutdownRunnable

public void registerShutdownRunnable(Runnable runnable)

Registers a pure runnable to be executed if the ModificationThread is terminated due to severe errors.

Parameters:

runnable - the runnable

getMasterSerial

public long getMasterSerial()

Gets the current master serial. Used in remote connections.

Returns:

the current master serial

selectMasterSerial

public long selectMasterSerial()

Reads the master-serial from the database.

Returns:

the master serial

getSerials

public long[] getSerials(long[] ids)

Gets all ModificationEntries (synchronized). Used in remote connections.

Parameters:

ids - the table IDs to read the serials for

Returns:

the serials

getIdSerialForName

public long[] getIdSerialForName(String tableName)

Gets the pair of id/serial for a given tablename. Used in remote connections.

Parameters:

tableName - the table to lookup

Returns:

the id/serial pair for the tablename

selectIdSerialForName

public long[] selectIdSerialForName(String tableName)

Selects the pair of id/serial for a given tablename. If there is no modification entry so far in the db, it will be created.

Parameters:

tableName - the table to lookup

Returns:

the id/serial pair for the tablename

selectNameForId

public String selectNameForId(long id)

Selects the tablename for a given ID.

Parameters:

id - the table ID

Returns:

the tablename, null if the such an ID does not exist

readSerials

public long[] readSerials(long[] ids)

Reads serials for given ids. If a table ID is not monitored, the returned serial is -1.

Parameters:

ids - the table IDs

Returns:

the serials

setInterval

public void setInterval(long mseconds)

Sets the polling interval.

Parameters:

mseconds - the polling interval in milliseconds

getInterval

public long getInterval()

Gets the polling interval.

Returns:

the polling interval in milliseconds

isIdle

public boolean isIdle()

Determines whether this is idle.

Returns:

true if thread is currently set to idle

setIdle

public void setIdle(boolean idle)

Sets the idle state of this thread.
Application threads using the primary db-connection (i.e. not running in the GUI-Thread) should setIdle(true) for the time they are running and setIdle(false) when finished. This is because the modification thread runs the runnables in the GUI-Thread via invokeLater and this might interfere with application threads.

Parameters:

idle - true if thread should *not* process the modification table.

getRemoteDelegateId

protected int getRemoteDelegateId()

Gets the remote delegate.

Returns:

the delegate