com.programix.thread
Class InitializationMonitor

java.lang.Object
  com.programix.thread.InitializationMonitor

All Implemented Interfaces:

ThreadSafe

public class InitializationMonitor
extends Object
implements ThreadSafe

This class serves as a thread-safe way to monitor the initialization of a component in a system.

This monitor starts off in the "in progress" state and ends up in either one of two states: "success" or "failure". Only on state transition occurs (they state either goes from "in progress" to "success" or it goes from "in progress" to "failed"). There is no way to "reset" or "retry"—that is, the state never returns to "in progress".

Author:

Paul Hyde

Nested Class Summary

static class

InitializationMonitor.FailedException Thrown by some methods on InitializationMonitor to indicate that the initialization failed.

Constructor Summary

InitializationMonitor()
Creates a monitor that starts off in the "in progress" state and locks on this instance.

InitializationMonitor(Object lockObject)
Creates a monitor that starts off in the "in progress" state.

InitializationMonitor(Waiter waiter)
Creates a monitor that starts off in the "in progress" state.

Method Summary

void	indicateFailure() Mark the initialization as complete but a failure.
void	indicateFailureIfNotSuccess() Mark the initialization as complete but a failure if it has not already been marked as a success.
void	indicateSuccess() Mark the initialization as complete and successful.
void	indicateSuccessIfNotFailure() Mark the initialization as complete and successful if it has not already been marked as a failure.
boolean	isFailure() Returns true if the initialization is complete but failed.
boolean	isInProgress() Returns true while the initialization is still "in progress".
boolean	isSuccess() Returns true if the initialization is complete and was successful.
void	waitUntilSuccess() Waits until the initialization has completed successfully.
void	waitUntilSuccess(long msTimeout) Waits until the initialization has completed successfully.
void	waitWhileInProgress() Waits until the initialization is completed—whether it is successful or a failure.
void	waitWhileInProgress(long msTimeout) Waits until the initialization is completed—whether it is successful or a failure.

Methods inherited from class java.lang.Object

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

Constructor Detail

InitializationMonitor

public InitializationMonitor(Waiter waiter)

Creates a monitor that starts off in the "in progress" state.

Parameters:

waiter - the Waiter to use. If null, then a new Waiter is automatically created.

InitializationMonitor

public InitializationMonitor(Object lockObject)

Creates a monitor that starts off in the "in progress" state.

Parameters:

lockObject - the object to synchronize on. If null, the the synchronization will be on this instance.

InitializationMonitor

public InitializationMonitor()

Creates a monitor that starts off in the "in progress" state and locks on this instance.

Method Detail

isInProgress

public boolean isInProgress()

Returns true while the initialization is still "in progress".

isSuccess

public boolean isSuccess()

Returns true if the initialization is complete and was successful.

isFailure

public boolean isFailure()

Returns true if the initialization is complete but failed.

indicateSuccess

public void indicateSuccess()
                     throws IllegalStateException

Mark the initialization as complete and successful.

Throws:

IllegalStateException - if the state is not currently "in progress".

indicateSuccessIfNotFailure

public void indicateSuccessIfNotFailure()
                                 throws IllegalStateException

Mark the initialization as complete and successful if it has not already been marked as a failure. If this is "in progress", then it is transitions to "success". If this is already "success", then nothing is changed and no exception is thrown.

Throws:

IllegalStateException - if the state is already "failure".

indicateFailure

public void indicateFailure()
                     throws IllegalStateException

Mark the initialization as complete but a failure.

Throws:

IllegalStateException - if the state is not currently "in progress".

indicateFailureIfNotSuccess

public void indicateFailureIfNotSuccess()
                                 throws IllegalStateException

Mark the initialization as complete but a failure if it has not already been marked as a success. If this is "in progress", then it is transitions to "failure". If this is already "failure", then nothing is changed and no exception is thrown.

Throws:

IllegalStateException - if the state is already "success".

waitUntilSuccess

public void waitUntilSuccess(long msTimeout)
                      throws InitializationMonitor.FailedException,
                             InterruptException,
                             TimedOutException

Waits until the initialization has completed successfully. If the initialization fails, then a InitializationMonitor.FailedException is thrown.

Parameters:

msTimeout - the maximum number of ms to wait

Throws:

InitializationMonitor.FailedException - if the initialization completed, but was a failure.

InterruptException - if interrupted while waiting

TimedOutException - if the time runs out and it is still "in progress".

waitUntilSuccess

public void waitUntilSuccess()
                      throws InitializationMonitor.FailedException,
                             InterruptException

Waits until the initialization has completed successfully. If the initialization fails, then a InitializationMonitor.FailedException is thrown.

Throws:

InitializationMonitor.FailedException - if the initialization completed, but was a failure.

InterruptException - if interrupted while waiting

waitWhileInProgress

public void waitWhileInProgress(long msTimeout)
                         throws InterruptException,
                                TimedOutException

Waits until the initialization is completed—whether it is successful or a failure. Call isSuccess() and/or call isFailure() to find out the result when no longer "in progress".

Parameters:

msTimeout - the maximum number of ms to wait

Throws:

InterruptException - if interrupted while waiting

TimedOutException - if the time runs out and it is still "in progress".

waitWhileInProgress

public void waitWhileInProgress()
                         throws InterruptException

Waits until the initialization is completed—whether it is successful or a failure. Call isSuccess() and/or call isFailure() to find out the result when no longer "in progress".

Throws:

InterruptException - if interrupted while waiting