Package io.hekate.util

Class StateGuard

java.lang.Object

io.hekate.util.StateGuard

public class StateGuard
extends Object

Helper class that provides support for components lifecycle management and locking.

Internally this class is backed by ReentrantReadWriteLock.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	StateGuard.GuardedRunnable<E extends Exception>	Guarded runnable.
static interface	StateGuard.GuardedSupplier<T,E extends Exception>	Guarded supplier.
static class	StateGuard.State	Enumeration of StateGuard states.

Constructor Summary

Constructors

Constructor	Description
StateGuard(Class<?> type)	Constructs a new instance.

Method Summary

Modifier and Type	Method	Description
void	becomeInitialized()	Switches this guard to StateGuard.State.INITIALIZED state.
<E extends Exception> void	becomeInitialized(StateGuard.GuardedRunnable<E> task)	Switches this guard to StateGuard.State.INITIALIZED state and executes the specified task.
void	becomeInitializing()	Switches this guard to StateGuard.State.INITIALIZING state.
boolean	becomeTerminated()	Switches this guard to StateGuard.State.TERMINATED state if guard is currently in any other state besides StateGuard.State.TERMINATED.
<E extends Exception> void	becomeTerminated(StateGuard.GuardedRunnable<E> task)	Switches this guard to StateGuard.State.TERMINATED state and executes the specified task.
<E extends Exception> Waiting	becomeTerminated(StateGuard.GuardedSupplier<List<Waiting>,E> task)	Switches this guard to StateGuard.State.TERMINATED state and executes the specified task.
boolean	becomeTerminating()	Switches this guard to StateGuard.State.TERMINATING state if guard is currently in StateGuard.State.INITIALIZING or StateGuard.State.INITIALIZED state.
<E extends Exception> void	becomeTerminating(StateGuard.GuardedRunnable<E> task)	Tries to switch this guard to StateGuard.State.TERMINATING state and executes the specified task if switch happened.
<E extends Exception> Waiting	becomeTerminating(StateGuard.GuardedSupplier<List<Waiting>,E> task)	Tries to switch this guard to StateGuard.State.TERMINATING state and executes the specified task if switch happened.
boolean	isInitialized()	Returns true if this guard is in StateGuard.State.INITIALIZED state.
boolean	isInitializing()	Returns true if this guard is in StateGuard.State.INITIALIZING state.
boolean	isWriteLocked()	Returns true if the current thread holds a write lock.
void	lockRead()	Acquires the read lock.
void	lockReadWithStateCheck()	Acquires the read lock on this guard and checks its current state.
void	lockReadWithStateCheck(StateGuard.State state)	Acquires the read lock on this guard and checks its current state.
void	lockWrite()	Acquires the write lock.
void	lockWriteWithStateCheck()	Acquires the write lock on this guard and checks its current state.
String	toString()
boolean	tryLockRead(long timeout, TimeUnit unit)	Tries to acquire the read lock with the specified timeout.
boolean	tryLockReadWithStateCheck()	Tries to acquire the read lock on this guard only if current state is StateGuard.State.INITIALIZED.
boolean	tryLockReadWithStateCheck(StateGuard.State state)	Tries to acquire the read lock on this guard only if current state is the same with the specified one.
boolean	tryLockWrite(long timeout, TimeUnit unit)	Tries to acquire the write lock with the specified timeout.
void	unlockRead()	Releases the read lock.
void	unlockWrite()	Releases the write lock.
<E extends Exception> void	withReadLock(StateGuard.GuardedRunnable<E> task)	Executes the specified task while holding the read lock.
<T,E extends Exception> T	withReadLock(StateGuard.GuardedSupplier<T,E> task)	Executes the specified task while holding the read lock.
<E extends Exception> void	withReadLockAndStateCheck(StateGuard.GuardedRunnable<E> task)	Executes the specified task while holding the read lock.
<T,E extends Exception> T	withReadLockAndStateCheck(StateGuard.GuardedSupplier<T,E> task)	Executes the specified task while holding the read lock.
<E extends Exception> boolean	withReadLockIfInitialized(StateGuard.GuardedRunnable<E> task)	Conditionally executes the specified task in the read-locked context if this guard is in initialized state.
<E extends Exception> void	withWriteLock(StateGuard.GuardedRunnable<E> task)	Executes the specified task while holding the write lock.
<T,E extends Exception> T	withWriteLock(StateGuard.GuardedSupplier<T,E> task)	Executes the specified task while holding the write lock.
<E extends Exception> boolean	withWriteLockIfInitialized(StateGuard.GuardedRunnable<E> task)	Conditionally executes the specified task in the write-locked context if this guard is in initialized state.

Methods inherited from class java.lang.Object

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

Constructor Detail

StateGuard

public StateGuard(Class<?> type)

Constructs a new instance.

Parameters:

type - Guarded component type (for errors reporting).

Method Detail

withReadLockIfInitialized

public <E extends Exception> boolean withReadLockIfInitialized(StateGuard.GuardedRunnable<E> task)
                                                        throws E extends Exception

Conditionally executes the specified task in the read-locked context if this guard is in initialized state.

Type Parameters:

E - Error type.

Parameters:

task - Task.

Returns:

true if task was executed or false if this guard is not in the initialized state.

Throws:

E - Task execution error.

E extends Exception

withWriteLockIfInitialized

public <E extends Exception> boolean withWriteLockIfInitialized(StateGuard.GuardedRunnable<E> task)
                                                         throws E extends Exception

Conditionally executes the specified task in the write-locked context if this guard is in initialized state.

Type Parameters:

E - Error type.

Parameters:

task - Task.

Returns:

true if task was executed or false if this guard is not in the initialized state.

Throws:

E - Task execution error.

E extends Exception

withReadLock

public <E extends Exception> void withReadLock(StateGuard.GuardedRunnable<E> task)
                                        throws E extends Exception

Executes the specified task while holding the read lock.

Type Parameters:

E - Error type.

Parameters:

task - Task.

Throws:

E - Task execution error.

E extends Exception

withReadLock

public <T,E extends Exception> T withReadLock(StateGuard.GuardedSupplier<T,E> task)
                                             throws E extends Exception

Executes the specified task while holding the read lock.

Type Parameters:

T - Result type.

E - Error type.

Parameters:

task - Task.

Returns:

Task execution result.

Throws:

E - Task execution error.

E extends Exception

withWriteLock

public <E extends Exception> void withWriteLock(StateGuard.GuardedRunnable<E> task)
                                         throws E extends Exception

Executes the specified task while holding the write lock.

Type Parameters:

E - Error type.

Parameters:

task - Task.

Throws:

E - Task execution error.

E extends Exception

withWriteLock

public <T,E extends Exception> T withWriteLock(StateGuard.GuardedSupplier<T,E> task)
                                              throws E extends Exception

Executes the specified task while holding the write lock.

Type Parameters:

T - Result type.

E - Error type.

Parameters:

task - Task.

Returns:

Task execution result.

Throws:

E - Task execution error.

E extends Exception

becomeInitializing

public void becomeInitializing()

Switches this guard to StateGuard.State.INITIALIZING state.

Important!!! This method must be invoked with write lock being held.

isInitializing

public boolean isInitializing()

Returns true if this guard is in StateGuard.State.INITIALIZING state.

Important!!! This method must be invoked with write lock or read lock being held.

Returns:

true if this guard is in StateGuard.State.INITIALIZING state.

becomeInitialized

public void becomeInitialized()

Switches this guard to StateGuard.State.INITIALIZED state.

Important!!! This method must be invoked with write lock being held.

becomeInitialized

public <E extends Exception> void becomeInitialized(StateGuard.GuardedRunnable<E> task)
                                             throws E extends Exception

Switches this guard to StateGuard.State.INITIALIZED state and executes the specified task.

Type Parameters:

E - Error type.

Parameters:

task - Task.

Throws:

E - Task execution error.

E extends Exception

isInitialized

public boolean isInitialized()

Returns true if this guard is in StateGuard.State.INITIALIZED state.

Important!!! This method must be invoked with write lock or read lock being held.

Returns:

true if this guard is in StateGuard.State.INITIALIZED state.

becomeTerminating

public boolean becomeTerminating()

Switches this guard to StateGuard.State.TERMINATING state if guard is currently in StateGuard.State.INITIALIZING or StateGuard.State.INITIALIZED state.

Important!!! This method must be invoked with write lock being held.

Returns:

true if successfully switched to StateGuard.State.TERMINATING state.

becomeTerminating

public <E extends Exception> Waiting becomeTerminating(StateGuard.GuardedSupplier<List<Waiting>,E> task)
                                                throws E extends Exception

Tries to switch this guard to StateGuard.State.TERMINATING state and executes the specified task if switch happened.

Type Parameters:

E - Error type.

Parameters:

task - Task.

Returns:

Waiting object to await for the task execution.

Throws:

E - Task execution error.

E extends Exception

See Also:

becomeTerminating()

becomeTerminating

public <E extends Exception> void becomeTerminating(StateGuard.GuardedRunnable<E> task)
                                             throws E extends Exception

Tries to switch this guard to StateGuard.State.TERMINATING state and executes the specified task if switch happened.

Type Parameters:

E - Error type.

Parameters:

task - Task.

Throws:

E - Task execution error.

E extends Exception

See Also:

becomeTerminating()

becomeTerminated

public boolean becomeTerminated()

Switches this guard to StateGuard.State.TERMINATED state if guard is currently in any other state besides StateGuard.State.TERMINATED.

Important!!! This method must be invoked with write lock being held.

Returns:

true if successfully switched to StateGuard.State.TERMINATED state.

becomeTerminated

public <E extends Exception> Waiting becomeTerminated(StateGuard.GuardedSupplier<List<Waiting>,E> task)
                                               throws E extends Exception

Switches this guard to StateGuard.State.TERMINATED state and executes the specified task.

Type Parameters:

E - Error type.

Parameters:

task - Task.

Returns:

Waiting object to await for the task execution.

Throws:

E - Task execution error.

E extends Exception

becomeTerminated

public <E extends Exception> void becomeTerminated(StateGuard.GuardedRunnable<E> task)
                                            throws E extends Exception

Switches this guard to StateGuard.State.TERMINATED state and executes the specified task.

Type Parameters:

E - Error type.

Parameters:

task - Task.

Throws:

E - Task execution error.

E extends Exception

lockReadWithStateCheck

public void lockReadWithStateCheck()

Acquires the read lock on this guard and checks its current state. If state is anything other than StateGuard.State.INITIALIZED then IllegalStateException will be thrown and lock will be released.

Throws:

IllegalStateException - If guard is not in StateGuard.State.INITIALIZED state.

lockReadWithStateCheck

public void lockReadWithStateCheck(StateGuard.State state)

Acquires the read lock on this guard and checks its current state. If state is anything other than the specified state then IllegalStateException will be thrown and lock will be released.

Parameters:

state - Expected state.

Throws:

IllegalStateException - If the specified state doesn't match the current state of this guard.

withReadLockAndStateCheck

public <T,E extends Exception> T withReadLockAndStateCheck(StateGuard.GuardedSupplier<T,E> task)
                                                          throws E extends Exception

Executes the specified task while holding the read lock.

If the current state is anything other than StateGuard.State.INITIALIZED then IllegalStateException will be thrown and lock will be released without executing the task.

Type Parameters:

T - Result type.

E - Task execution error type.

Parameters:

task - Task.

Returns:

Task execution result.

Throws:

E - Task execution error.

E extends Exception

withReadLockAndStateCheck

public <E extends Exception> void withReadLockAndStateCheck(StateGuard.GuardedRunnable<E> task)
                                                     throws E extends Exception

Executes the specified task while holding the read lock.

If the current state is anything other than StateGuard.State.INITIALIZED then IllegalStateException will be thrown and lock will be released without executing the task.

Type Parameters:

E - Task execution error type.

Parameters:

task - Task.

Throws:

E - Task execution error.

E extends Exception

tryLockReadWithStateCheck

public boolean tryLockReadWithStateCheck()

Tries to acquire the read lock on this guard only if current state is StateGuard.State.INITIALIZED.

Returns:

true if lock was acquired.

tryLockReadWithStateCheck

public boolean tryLockReadWithStateCheck(StateGuard.State state)

Tries to acquire the read lock on this guard only if current state is the same with the specified one.

Parameters:

state - Expected state.

Returns:

true if lock was acquired.

lockRead

public void lockRead()

Acquires the read lock.

See Also:

ReentrantReadWriteLock.ReadLock.lock()

tryLockRead

public boolean tryLockRead(long timeout,
                           TimeUnit unit)
                    throws InterruptedException

Tries to acquire the read lock with the specified timeout.

Parameters:

timeout - Timeout.

unit - Unit of timeout.

Returns:

true if lock was successfully acquired.

Throws:

InterruptedException - If thread was interrupted while waiting for lock acquisition.

See Also:

ReentrantReadWriteLock.ReadLock.tryLock(long, TimeUnit)

unlockRead

public void unlockRead()

Releases the read lock.

See Also:

ReentrantReadWriteLock.ReadLock.unlock()

lockWriteWithStateCheck

public void lockWriteWithStateCheck()

Acquires the write lock on this guard and checks its current state. If state is anything other than StateGuard.State.INITIALIZED then IllegalStateException will be thrown and lock will be released.

Throws:

IllegalStateException - If guard is not in StateGuard.State.INITIALIZED state.

lockWrite

public void lockWrite()

Acquires the write lock.

See Also:

ReentrantReadWriteLock.WriteLock.lock()

tryLockWrite

public boolean tryLockWrite(long timeout,
                            TimeUnit unit)
                     throws InterruptedException

Tries to acquire the write lock with the specified timeout.

Parameters:

timeout - Timeout.

unit - Unit of timeout.

Returns:

true if lock was successfully acquired.

Throws:

InterruptedException - If thread was interrupted while awaiting for lock acquisition.

See Also:

ReentrantReadWriteLock.WriteLock.tryLock(long, TimeUnit)

unlockWrite

public void unlockWrite()

Releases the write lock.

See Also:

ReentrantReadWriteLock.WriteLock.unlock()

isWriteLocked

public boolean isWriteLocked()

Returns true if the current thread holds a write lock.

Returns:

true if the current thread holds a write lock.

See Also:

ReentrantReadWriteLock.WriteLock.isHeldByCurrentThread()

toString

public String toString()

Overrides:

toString in class Object