ProgramixGenericLib v5.0.1

com.programix.thread
Class InitializationMonitor

java.lang.Object
  extended by 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

ProgramixGenericLib v5.0.1

Copyright © 2001-2009 Programix Incorporated. All rights reserved. ProgramixGenericLib is free and is OSI Certified Open Source Software under the BSD license.