com.ihr.xbrl.util

Class InitializeInThread

java.lang.Object

com.ihr.xbrl.util.InitializeInThread

public final class InitializeInThread
extends java.lang.Object

This class allows to fire initialization of a class in a separate thread and provides a method to synchronize all threads until initialization is complete.

How to use it:

1. in the class that requires initialization, create a static property of this type and pass an instance of the InitializeInThread.Initializable interface defined in this class.
2. in the initialize() method, put the code for initializing the class
3. call the start() method on this class
4. at the beginning of all methods that requires the class to be initialized add a call to waitInitialization() so the thread going to execute that code waits until initialization is complete or raises errors

Usage pattern:

 private static final InitializeInThread intializationStatus = new InitializeInThread(new Initializable() {             
   public void initialize() {
     prepareProcessorInASeparateThread();
   }
 });
 static {
   intializationStatus.start();
 }
 

There are examples of uses of this class in all the following classes: RSRemoteCatalogResolver, TaxonomyPackageUriResolver, ZipCascadeURIResolver

This is how this process works

1. When an instance of this class is just created, the status is PENDING
2. In the constructor, a call to private initialize method verifies the status is PENDING and changes it to INITIALIZABLE
3. a call to start() will check the status is INITIALIZABLE and will start initialization. If several threads call start simultaneously only one starts the initialization thread and the others will raise an exception

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	InitializeInThread.Initializable this is the interface that must be implemented by a class that will contain a callback method called InitializeInThread.Initializable.initialize().
static class	InitializeInThread.InitializationResult The Enum InitializationResult: InitializeInThread.InitializationResult.PENDING InitializeInThread.InitializationResult.INITIALIZABLE InitializeInThread.InitializationResult.RUNNING InitializeInThread.InitializationResult.ERROR InitializeInThread.InitializationResult.INITIALIZED InitializeInThread.InitializationResult.CANCELLED .

Constructor Summary

Constructors

Constructor and Description
InitializeInThread(InitializeInThread.Initializable task) creates an instance of the Initialize thread and calls initialize on the parameter.

Method Summary

Modifier and Type	Method and Description
void	cancel() Cancel Sets the status to CANCELLED and error is set to null If the status is RUNNING, then after the finalization of the initialization thread, the status is not changed to ERROR or INITIALIZED but remains in CANCELLED status.
java.lang.Throwable	getError() If the status is ERROR, a call to this method returns the error thar was generated during the initialization phase.
InitializeInThread.InitializationResult	getStatus() Access to the initialization status.
void	start() Starts initialization and returns immediately.
void	waitInitialization() If the class is initializing a call to this method by another thread will wait until the initialization process ends.

Methods inherited from class java.lang.Object

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

Constructor Detail

InitializeInThread

public InitializeInThread(InitializeInThread.Initializable task)

creates an instance of the Initialize thread and calls initialize on the parameter.

Parameters:

task - the task

Throws:

java.lang.IllegalStateException - if the task arguments was already used

Method Detail

start

public void start()

Starts initialization and returns immediately.

The initialization run in a separate thread

Throws:

java.lang.IllegalStateException - if the initialization cannot be called most likely because it is already running or was already executed

cancel

public void cancel()

Cancel Sets the status to CANCELLED and error is set to null

If the status is RUNNING, then after the finalization of the initialization thread, the status is not changed to ERROR or INITIALIZED but remains in CANCELLED status.

If the status is in any other value, this call sets the status to CANCELLED and nothing else happens.

waitInitialization

public void waitInitialization()
                        throws java.lang.InterruptedException

If the class is initializing a call to this method by another thread will wait until the initialization process ends. If the class is already initialized the method returns immediately

Errors generated during the initialization phase are captured and raised at this time as instances of InterruptedException with a suppressed exception that contains the original error

If the initialization was cancelled, this method raises an InterruptedException as well but without additional information. A call to getStatus() can be used to distinguish a cancellation from an error

Throws:

java.lang.InterruptedException - the interrupted exception

getError

public java.lang.Throwable getError()

If the status is ERROR, a call to this method returns the error thar was generated during the initialization phase.

Returns:

Throwable, the error raised during the initialization phase

getStatus

public InitializeInThread.InitializationResult getStatus()

Access to the initialization status.

Returns:

a value from the InitializeInThread.InitializationResult enumeration