org.oddjob.state

Class StateHandler<S extends State>

java.lang.Object

org.oddjob.state.StateHandler<S>

All Implemented Interfaces:

StateLock, Stateful

Direct Known Subclasses:

EventStateHandler, JobStateHandler, ParentStateHandler, ServiceStateHandler, TimerStateHandler

public class StateHandler<S extends State>
extends java.lang.Object
implements Stateful, StateLock

Helps Jobs handle state change.

The state setting operations don't notify the listeners. This must be done using the separate fireEvent() method. This is because jobs that use this need to persist their themselves after setting the state.

Lock must be held during setting and firing operations. Considered using a read/write lock so state could be read while event fired to listeners, however as read write locks are not as performant as a single mutex lock, it was deemed not worth it.

Todo:

• Attempted to make waitToWhen(StateCondition, Runnable) and {@link #tryToWhen(StateCondition, Runnable) both use timeouts. This now required interrupt handling and the tryLock was intermittently interrupted. The cause of this could not be found so attempting to implement timeouts was abandoned for the time being.

Author:

Rob Gordon

Constructor Summary

Constructors

Constructor and Description
StateHandler(Stateful source, S readyState) Constructor.

Method Summary

Modifier and Type	Method and Description
void	addStateListener(StateListener listener) Add a job state listener.
void	assertAlive() Convenience method to check the job hasn't been destroyed.
void	assertLockHeld()
<T> T	callLocked(java.util.concurrent.Callable<T> callable) Wait to acquire the lock and execute the Callable while holding the lock.
void	fireEvent() Fire the event, update last event.
State	getState() Return the current state of the job.
StateEvent	lastStateEvent() Get the last event.
int	listenerCount() The number of listeners.
void	removeStateListener(StateListener listener) Remove a job state listener.
void	restoreLastJobStateEvent(StateEvent.SerializableNoSource savedEvent) Typically only called after restoring a jobstate handler after deserialisation.
void	runLocked(java.lang.Runnable runnable) Wait to acquire the lock and execute the Runnable while holding the lock.
void	setState(S state)
void	setState(S state, java.util.Date date)
void	setStateException(State state, java.lang.Throwable ex)
void	setStateException(S state, java.lang.Throwable t, java.util.Date date)
void	sleep(long time) Sleep.
<T> T	supplyLocked(java.util.function.Supplier<T> supplier) Wait to acquire the lock and execute the Supplier while holding the lock.
java.lang.String	toString() Override toString.
boolean	tryToWhen(StateCondition when, java.lang.Runnable runnable) Try to acquire the lock, and then do something when the condition is true.
boolean	waitToWhen(StateCondition when, java.lang.Runnable runnable) Wait to do something when the condition is true.
void	wake() Wake any threads that are sleeping via sleep(long).

Methods inherited from class java.lang.Object

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

Constructor Detail

StateHandler

public StateHandler(Stateful source,
                    S readyState)

Constructor.

Parameters:

source - The source for events.

readyState - The ready state.

Method Detail

lastStateEvent

public StateEvent lastStateEvent()

Get the last event.

Specified by:

lastStateEvent in interface Stateful

Returns:

The last event.

restoreLastJobStateEvent

public void restoreLastJobStateEvent(StateEvent.SerializableNoSource savedEvent)

Typically only called after restoring a jobstate handler after deserialisation.

Parameters:

savedEvent - The last serialised event.

setState

public void setState(S state,
                     java.util.Date date)
              throws JobDestroyedException

Throws:

JobDestroyedException

setState

public void setState(S state)
              throws JobDestroyedException

Throws:

JobDestroyedException

setStateException

public void setStateException(S state,
                              java.lang.Throwable t,
                              java.util.Date date)
                       throws JobDestroyedException

Throws:

JobDestroyedException

setStateException

public void setStateException(State state,
                              java.lang.Throwable ex)
                       throws JobDestroyedException

Throws:

JobDestroyedException

getState

public State getState()

Return the current state of the job.

Returns:

The current state.

assertAlive

public void assertAlive()
                 throws JobDestroyedException

Convenience method to check the job hasn't been destroyed.

Throws:

JobDestroyedException - If it has.

assertLockHeld

public void assertLockHeld()

tryToWhen

public boolean tryToWhen(StateCondition when,
                         java.lang.Runnable runnable)
                  throws OddjobLockedException

Description copied from interface: StateLock

Try to acquire the lock, and then do something when the condition is true. Both the condition evaluation and the performing of the action are done in the context of the same state lock. If the lock can not be acquired an OddjobLockedException is thrown.

Specified by:

tryToWhen in interface StateLock

Parameters:

when - The condition.

runnable - The action.

Returns:

true if the condition was true and the action executed. False otherwise.

Throws:

OddjobLockedException - If the lock can not be acquired.

waitToWhen

public boolean waitToWhen(StateCondition when,
                          java.lang.Runnable runnable)

Description copied from interface: StateLock

Wait to do something when the condition is true. Both the condition evaluation and the performing of the action are done in the context of the same state lock. If the lock can not be acquired then the lock is waited for.

Specified by:

waitToWhen in interface StateLock

Parameters:

when - The condition.

runnable - The action.

Returns:

true if the condition was true and the action executed.

runLocked

public void runLocked(java.lang.Runnable runnable)

Wait to acquire the lock and execute the Runnable while holding the lock.

Specified by:

runLocked in interface StateLock

Parameters:

runnable - The Runnable.

callLocked

public <T> T callLocked(java.util.concurrent.Callable<T> callable)
                 throws java.lang.Exception

Wait to acquire the lock and execute the Callable while holding the lock.

Specified by:

callLocked in interface StateLock

Parameters:

callable - The callable.

Returns:

The result of the callable.

Throws:

java.lang.Exception - from the callable.

supplyLocked

public <T> T supplyLocked(java.util.function.Supplier<T> supplier)

Wait to acquire the lock and execute the Supplier while holding the lock.

Specified by:

supplyLocked in interface StateLock

Parameters:

supplier - The Supplier.

Returns:

The result from the Supplier.

sleep

public void sleep(long time)
           throws java.lang.InterruptedException

Sleep.

Parameters:

time - The milliseconds to sleep for.

Throws:

java.lang.InterruptedException - If the sleep is interrupted.

wake

public void wake()

Wake any threads that are sleeping via sleep(long).

addStateListener

public void addStateListener(StateListener listener)
                      throws JobDestroyedException

Add a job state listener. This method will send the last event to the new listener. It is possible that the listener may get the notification twice.

Specified by:

addStateListener in interface Stateful

Parameters:

listener - The listener.

Throws:

JobDestroyedException - If trying to listen to a destroyed job.

removeStateListener

public void removeStateListener(StateListener listener)

Remove a job state listener.

Specified by:

removeStateListener in interface Stateful

Parameters:

listener - The listener.

listenerCount

public int listenerCount()

The number of listeners.

Returns:

The number of listeners.

toString

public java.lang.String toString()

Override toString.

Overrides:

toString in class java.lang.Object

fireEvent

public void fireEvent()

Fire the event, update last event.