com.uwyn.rife.rep
Class BlockingRepository

java.lang.Object
  java.lang.ThreadGroup
      com.uwyn.rife.rep.BlockingRepository

All Implemented Interfaces:

Repository, Thread.UncaughtExceptionHandler

public class BlockingRepository
extends ThreadGroup
implements Repository

The BlockingRepository class provides a Repository implementation that loads the participants from an XML file.

This file defaults to rep/participants.xml, but it can be overridden by providing another filename to the initialize method. The participants are initialized according to their listed order.

Following is an example of such an XML file :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rep SYSTEM "/dtd/rep.dtd">
<rep>
<participant blocking="true" parameter="rep/config.xml">ParticipantConfig</participant>
<participant blocking="false" parameter="graphics/buttons/">ParticipantImages</participant>
<participant name="my cursors" blocking="false" parameter="graphics/cursors/">ParticipantCursors</participant>
</rep>

Each participant has a blocking attribute that determines whether the repository should wait for the end of the participant's initialization before progressing to the next participant or not. Using this intelligently, it's possible to dramatically increase the perceived startup time of an application.

Optionally a participant can have a name attribute which makes it possible to declare multiple participants of the same class. If no name is provided, the participant's class name will be used to identify the declared participant.

Optionally a participant can also have a parameter attribute which is merely a String that is provided to the participant object for configuration purposes.

Listeners can be added to the repository to receive notifications about the initialization advancement of the participants and to know when the initialization has completely finished. These notifications can, for example, be used to display a progress bar in a splash window and to switch to the real application window when the initialization has finished.

The JDK's logging facility is used to output informative text during the advancement of the initialization. Each participant has to provide an initialization message that will be output.

Since:

1.0

Version:

$Revision: 3634 $

Author:

Geert Bevin (gbevin[remove] at uwyn dot com)

See Also:

RepositoryListener, BlockingParticipant

Constructor Summary

BlockingRepository()
Default constructor without a repository context.

BlockingRepository(Object context)
Constructor which sets up a the context in which the repository is initialized.

Method Summary

boolean	addParticipant(Class klass) Adds a BlockingParticipant to the repository, using the class name as the name of the participant.
boolean	addParticipant(Class klass, boolean blocking) Adds a BlockingParticipant to the repository, using the class name as the name of the participant.
boolean	addParticipant(Class klass, boolean blocking, String parameter) Adds a BlockingParticipant to the repository, using the class name as the name of the participant.
boolean	addParticipant(Class klass, String parameter) Adds a BlockingParticipant to the repository, using the class name as the name of the participant.
boolean	addParticipant(Class klass, String name, boolean blocking, String parameter) Adds a BlockingParticipant to the repository.
boolean	addParticipant(String className) Adds a BlockingParticipant to the repository, using the class name for the name of the participant.
boolean	addParticipant(String className, boolean blocking) Adds a BlockingParticipant to the repository, using the class name for the name of the participant.
boolean	addParticipant(String className, boolean blocking, String parameter) Adds a BlockingParticipant to the repository, using the class name for the name of the participant.
boolean	addParticipant(String className, String parameter) Adds a BlockingParticipant to the repository, using the class name for the name of the participant.
boolean	addParticipant(String className, String name, boolean blocking, String parameter) Adds a BlockingParticipant to the repository.
void	addRepListener(RepositoryListener repListener) Adds the specified repository listener to receive repository initialization events.
void	cleanup() Cleans up the participants in the order in which they have been declared.
void	fireInitActionPerformed(BlockingParticipant participant) Notifies the registered listeners that a new initialization action has been performed.
void	fireInitFinished() Notifies the registered listeners that the repository initialization has finished.
Object	getContext() Retrieves the context in which the repository was initialized.
BlockingParticipant	getParticipant(String name) Looks for the participant that corresponds to a given name and returns it when found.
Collection<BlockingParticipant>	getParticipants(String className) Returns all the participants with a given class name
HierarchicalProperties	getProperties() Retrieves the repository's properties.
boolean	hasParticipant(String name) Verifies if a participant that corresponds to a given name is present.
void	initialize(String repXmlPath, ResourceFinder resourcefinder) Parses the XML file to determine what the participants are.
boolean	isFinished() Obtains the finished status of the initialization.
void	removeRepListener(RepositoryListener repListener) Removes the repository listener so that it no longer receives repository initialization events.
void	runParticipants() Sequentially execute the participants according to their registration order.
void	runParticipants(ResourceFinder resourceFinder) Sequentially execute the participants according to their registration order.
void	uncaughtException(Thread thread, Throwable e) If participants call an exception, clean up correctly and rethrow the exception afterwards.

Methods inherited from class java.lang.ThreadGroup

activeCount, activeGroupCount, allowThreadSuspension, checkAccess, destroy, enumerate, enumerate, enumerate, enumerate, getMaxPriority, getName, getParent, interrupt, isDaemon, isDestroyed, list, parentOf, resume, setDaemon, setMaxPriority, stop, suspend, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

BlockingRepository

public BlockingRepository()

Default constructor without a repository context.

BlockingRepository

public BlockingRepository(Object context)

Constructor which sets up a the context in which the repository is initialized.

Method Detail

addParticipant

public boolean addParticipant(String className)
                       throws RepException

Adds a BlockingParticipant to the repository, using the class name for the name of the participant.

The participant will not be blocking and have no parameter.

Parameters:

className - The fully resolved name of the participant's class, or only the class name if the participant resides in the com.uwyn.rife.rep.participants package.

Returns:

true if the participants was added successfully; or

false if errors occurred

Throws:

RepException

Since:

1.5

See Also:

BlockingParticipant, Participant, addParticipant(Class, String, boolean, String)

addParticipant

public boolean addParticipant(String className,
                              boolean blocking)
                       throws RepException

Adds a BlockingParticipant to the repository, using the class name for the name of the participant.

The participant will have no parameter.

Parameters:

className - The fully resolved name of the participant's class, or only the class name if the participant resides in the com.uwyn.rife.rep.participants package.

blocking - Indicates if this a blocking participant or not.

Returns:

true if the participants was added successfully; or

false if errors occurred

Throws:

RepException

Since:

1.5

See Also:

BlockingParticipant, Participant, addParticipant(Class, String, boolean, String)

addParticipant

public boolean addParticipant(String className,
                              String parameter)
                       throws RepException

Adds a BlockingParticipant to the repository, using the class name for the name of the participant.

The participant will not be blocking.

Parameters:

className - The fully resolved name of the participant's class, or only the class name if the participant resides in the com.uwyn.rife.rep.participants package.

parameter - An optional string that contains the parameter for this participant.

Returns:

true if the participants was added successfully; or

false if errors occurred

Throws:

RepException

Since:

1.5

See Also:

BlockingParticipant, Participant, addParticipant(Class, String, boolean, String)

addParticipant

public boolean addParticipant(String className,
                              boolean blocking,
                              String parameter)
                       throws RepException

Adds a BlockingParticipant to the repository, using the class name for the name of the participant.

Parameters:

className - The fully resolved name of the participant's class, or only the class name if the participant resides in the com.uwyn.rife.rep.participants package.

blocking - Indicates if this a blocking participant or not.

parameter - An optional string that contains the parameter for this participant.

Returns:

true if the participants was added successfully; or

false if errors occurred

Throws:

RepException

Since:

1.5

See Also:

BlockingParticipant, Participant, addParticipant(Class, String, boolean, String)

addParticipant

public boolean addParticipant(String className,
                              String name,
                              boolean blocking,
                              String parameter)
                       throws RepException

Adds a BlockingParticipant to the repository.

Parameters:

className - The fully resolved name of the participant's class, or only the class name if the participant resides in the com.uwyn.rife.rep.participants package.

name - The name under which the participant will be registered, if the name is null the class name will be used

blocking - Indicates if this a blocking participant or not.

parameter - An optional string that contains the parameter for this participant.

Returns:

true if the participants was added successfully; or

false if errors occurred

Throws:

RepException

Since:

1.0

See Also:

BlockingParticipant, Participant, addParticipant(Class, String, boolean, String)

addParticipant

public boolean addParticipant(Class klass,
                              boolean blocking,
                              String parameter)
                       throws RepException

Adds a BlockingParticipant to the repository, using the class name as the name of the participant.

Parameters:

klass - The class of the participant.

blocking - Indicates if this a blocking participant or not.

parameter - An optional string that contains the parameter for this participant.

Returns:

true if the participants was added successfully; or

false if errors occurred

Throws:

RepException

Since:

1.5

See Also:

BlockingParticipant, Participant, addParticipant(Class, String, boolean, String)

addParticipant

public boolean addParticipant(Class klass)
                       throws RepException

Adds a BlockingParticipant to the repository, using the class name as the name of the participant.

The participant will not be blocking and have no parameter.

Parameters:

klass - The class of the participant. this participant.

Returns:

true if the participants was added successfully; or

false if errors occurred

Throws:

RepException

Since:

1.5

See Also:

BlockingParticipant, Participant, addParticipant(Class, String, boolean, String)

addParticipant

public boolean addParticipant(Class klass,
                              boolean blocking)
                       throws RepException

Adds a BlockingParticipant to the repository, using the class name as the name of the participant.

The participant will have no parameter.

Parameters:

klass - The class of the participant.

blocking - Indicates if this a blocking participant or not.

Returns:

true if the participants was added successfully; or

false if errors occurred

Throws:

RepException

Since:

1.5

See Also:

BlockingParticipant, Participant, addParticipant(Class, String, boolean, String)

addParticipant

public boolean addParticipant(Class klass,
                              String parameter)
                       throws RepException

Adds a BlockingParticipant to the repository, using the class name as the name of the participant.

The participant will not be blocking.

Parameters:

klass - The class of the participant.

parameter - An optional string that contains the parameter for this participant.

Returns:

true if the participants was added successfully; or

false if errors occurred

Throws:

RepException

Since:

1.5

See Also:

BlockingParticipant, Participant, addParticipant(Class, String, boolean, String)

addParticipant

public boolean addParticipant(Class klass,
                              String name,
                              boolean blocking,
                              String parameter)
                       throws RepException

Adds a BlockingParticipant to the repository.

Parameters:

klass - The class of the participant.

name - The name under which the participant will be registered, if the name is null the class name will be used

blocking - Indicates if this a blocking participant or not.

parameter - An optional string that contains the parameter for this participant.

Returns:

true if the participants was added successfully; or

false if errors occurred

Throws:

RepException

Since:

1.0

See Also:

BlockingParticipant, Participant

hasParticipant

public boolean hasParticipant(String name)

Verifies if a participant that corresponds to a given name is present.

Specified by:

hasParticipant in interface Repository

Parameters:

name - The name of the participant object that you wish to retrieve from the repository. See the getParticipant method for detailed information about how the participant's name is resolved.

Returns:

true if the provided class name could be found, or

false otherwise

Since:

1.0

See Also:

BlockingParticipant, getParticipant(String)

getParticipant

public BlockingParticipant getParticipant(String name)

Looks for the participant that corresponds to a given name and returns it when found.

Specified by:

getParticipant in interface Repository

Parameters:

name - The name of the participant instance that you wish to retrieve from the repository.

If no name was provided during the XML specification, the participant will have been registered with its class name. If the participant's class is not part of the com.uwyn.rife.rep.participants package, its full class name has to be provided, otherwise just the name of the class itself is sufficient.

Also, even though a participant has been registered with a name, it'll still be known under its class name. When a class name is provided as the argument, the first known participant of that class will be returned. This can be seen as the default participant for the specified type.

Returns:

A BlockingParticipant instance if the provided name could be found amongst the registered participants in the repository; or

null if the participant couldn't be found

Since:

1.0

See Also:

BlockingParticipant, hasParticipant(String)

getParticipants

public Collection<BlockingParticipant> getParticipants(String className)

Returns all the participants with a given class name

Specified by:

getParticipants in interface Repository

Parameters:

className - The class name of the participants that you wish to retrieve from the repository.

If the participant's class is not part of the com.uwyn.rife.rep.participants package, its full class name has to be provided, otherwise just the name of the class itself is sufficient.

Returns:

A Collection of BlockingParticipant instances of the provided class name; or

null if no participants with the provided class name could be found

Since:

1.0

See Also:

BlockingParticipant, getParticipant(String)

runParticipants

public void runParticipants()

Sequentially execute the participants according to their registration order. If the participant has already been run or is still running, it is not executed anymore. The repository waits for the participant's execution to finish if this has been indicated by registering with the blocking attribute.

The resource finder that will be used is an instance of ResourceFinderClasspath.

Since:

1.5

See Also:

ResourceFinderClasspath, runParticipants(ResourceFinder)

runParticipants

public void runParticipants(ResourceFinder resourceFinder)

Sequentially execute the participants according to their registration order. If the participant has already been run or is still running, it is not executed anymore. The repository waits for the participant's execution to finish if this has been indicated by registering with the blocking attribute.

Parameters:

resourceFinder - The resource finder that is used during the initialization.

Since:

1.0

uncaughtException

public void uncaughtException(Thread thread,
                              Throwable e)

If participants call an exception, clean up correctly and rethrow the exception afterwards.

Specified by:

uncaughtException in interface Thread.UncaughtExceptionHandler

Overrides:

uncaughtException in class ThreadGroup

Since:

1.0

initialize

public void initialize(String repXmlPath,
                       ResourceFinder resourcefinder)
                throws RepException

Parses the XML file to determine what the participants are. Then, one by one, initializes each participant with the runParticipants method, waiting for it to finish if its blocking attribute was set to true.

Parameters:

repXmlPath - The path of the XML file.

If this is null, rep/participants.xml will be used.

resourcefinder - The resource finder that will be used to look up resources such as XML files and DTDs. It will also be used by other classes after initialization through the getResourceFinder() method.

If this is null, an instance of ResourceFinderClasspath will be used.

Throws:

RepException - when an error occurs during the initialization.

Since:

1.0

isFinished

public boolean isFinished()

Obtains the finished status of the initialization.

Specified by:

isFinished in interface Repository

Returns:

false if the initialization is still busy; or

true if the initialization is finished

Since:

1.0

cleanup

public void cleanup()
             throws RepException

Cleans up the participants in the order in which they have been declared. Every participant's cleanup() method is successively called.

Specified by:

cleanup in interface Repository

Throws:

RepException - when an error occurs during the cleanup.

Since:

1.0

getProperties

public HierarchicalProperties getProperties()

Description copied from interface: Repository

Retrieves the repository's properties. This is meant to be similar System.getProperties, but then not for the whole system, but just for this application.

Also, instead of just have a map of String keys and values, the property values are of the PropertyValue type and are looked up at run-time in a hierachical manner. This provides them with IoC capabilities.

Since Java allows the configuration of an application through the use of properties, many other sub-system have adopted a similar approach (for example servlet init parameters). Most of the time an application runs through several barriers of configuration that often function independently. These properties make it possible for each sub-system to add their properties to the same pool. This makes it much more convenient to retrieve a property value.

Specified by:

getProperties in interface Repository

Returns:

the repository's properties

getContext

public Object getContext()

Description copied from interface: Repository

Retrieves the context in which the repository was initialized.

Specified by:

getContext in interface Repository

Returns:

a reference to the context in which the repository was initialized; or

null if the context isn't accessible

addRepListener

public void addRepListener(RepositoryListener repListener)

Adds the specified repository listener to receive repository initialization events. If repListener is null, no exception is thrown and no action is performed.

Parameters:

repListener - The repository listener that will be added.

Since:

1.0

See Also:

RepositoryListener, removeRepListener(RepositoryListener)

removeRepListener

public void removeRepListener(RepositoryListener repListener)

Removes the repository listener so that it no longer receives repository initialization events. This method performs no function, nor does it throw an exception, if the listener specified by the argument was not previously added to this component. If repListener is null, no exception is thrown and no action is performed.

Parameters:

repListener - The repository listener that will be removed.

Since:

1.0

See Also:

RepositoryListener, addRepListener(RepositoryListener)

fireInitActionPerformed

public void fireInitActionPerformed(BlockingParticipant participant)

Notifies the registered listeners that a new initialization action has been performed.

This is always triggered when a participant's initialization has finished. Each participant however has the possibility to call this method directly, allowed for finer-grained notification of the advancement of the initialization.

Parameters:

participant - The participant that triggered the action.

Since:

1.0

See Also:

RepositoryListener

fireInitFinished

public void fireInitFinished()

Notifies the registered listeners that the repository initialization has finished.

Since:

1.0

See Also:

RepositoryListener