Package org.apache.commons.chain

Class CatalogFactory

java.lang.Object

org.apache.commons.chain.CatalogFactory

Direct Known Subclasses:

CatalogFactoryBase

public abstract class CatalogFactory
extends java.lang.Object

A CatalogFactory is a class used to store and retrieve Catalogs. The factory allows for a default Catalog as well as Catalogs stored with a name key. Follows the Factory pattern (see GoF).

The base CatalogFactory implementation also implements a resolution mechanism which allows lookup of a command based on a single String which encodes both the catalog and command names.

Version:

$Revision: 480477 $ $Date: 2006-11-29 08:34:52 +0000 (Wed, 29 Nov 2006) $

Author:

Sean Schofield

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	DELIMITER	Values passed to the getCommand(String) method should use this as the delimiter between the "catalog" name and the "command" name.
private static java.util.Map	factories	The set of registered CatalogFactory instances, keyed by the relevant class loader.

Constructor Summary

Constructors

Constructor	Description
CatalogFactory()

Method Summary

Modifier and Type	Method	Description
abstract void	addCatalog(java.lang.String name, Catalog catalog)	Adds a named instance of Catalog to the factory (for subsequent retrieval later).
static void	clear()	Clear all references to registered catalogs, as well as to the relevant class loader.
abstract Catalog	getCatalog()	Gets the default instance of Catalog associated with the factory (if any); otherwise, return null.
abstract Catalog	getCatalog(java.lang.String name)	Retrieves a Catalog instance by name (if any); otherwise return null.
private static java.lang.ClassLoader	getClassLoader()	Return the relevant ClassLoader to use as a Map key for this request.
Command	getCommand(java.lang.String commandID)	Return a Command based on the given commandID.
static CatalogFactory	getInstance()	Return the singleton CatalogFactory instance for the relevant ClassLoader.
abstract java.util.Iterator	getNames()	Return an Iterator over the set of named Catalogs known to this CatalogFactory.
abstract void	setCatalog(Catalog catalog)	Sets the default instance of Catalog associated with the factory.

Methods inherited from class java.lang.Object

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

Field Detail

DELIMITER

public static final java.lang.String DELIMITER

Values passed to the getCommand(String) method should use this as the delimiter between the "catalog" name and the "command" name.

See Also:

Constant Field Values

factories

private static java.util.Map factories

The set of registered CatalogFactory instances, keyed by the relevant class loader.

Constructor Detail

CatalogFactory

public CatalogFactory()

Method Detail

getCatalog

public abstract Catalog getCatalog()

Gets the default instance of Catalog associated with the factory (if any); otherwise, return null.

Returns:

the default Catalog instance

setCatalog

public abstract void setCatalog(Catalog catalog)

Sets the default instance of Catalog associated with the factory.

Parameters:

catalog - the default Catalog instance

getCatalog

public abstract Catalog getCatalog(java.lang.String name)

Retrieves a Catalog instance by name (if any); otherwise return null.

Parameters:

name - the name of the Catalog to retrieve

Returns:

the specified Catalog

addCatalog

public abstract void addCatalog(java.lang.String name,
                                Catalog catalog)

Adds a named instance of Catalog to the factory (for subsequent retrieval later).

Parameters:

name - the name of the Catalog to add

catalog - the Catalog to add

getNames

public abstract java.util.Iterator getNames()

Return an Iterator over the set of named Catalogs known to this CatalogFactory. If there are no known catalogs, an empty Iterator is returned.

Returns:

An Iterator of the names of the Catalogs known by this factory.

getCommand

public Command getCommand(java.lang.String commandID)

Return a Command based on the given commandID.

At this time, the structure of commandID is relatively simple: if the commandID contains a DELIMITER, treat the segment of the commandID up to (but not including) the DELIMITER as the name of a catalog, and the segment following the DELIMITER as a command name within that catalog. If the commandID contains no DELIMITER, treat the commandID as the name of a command in the default catalog.

To preserve the possibility of future extensions to this lookup mechanism, the DELIMITER string should be considered reserved, and should not be used in command names. commandID values which contain more than one DELIMITER will cause an IllegalArgumentException to be thrown.

Parameters:

commandID - the identifier of the command to return

Returns:

the command located with commandID, or null if either the command name or the catalog name cannot be resolved

Throws:

java.lang.IllegalArgumentException - if the commandID contains more than one DELIMITER

Since:

Chain 1.1

getInstance

public static CatalogFactory getInstance()

Return the singleton CatalogFactory instance for the relevant ClassLoader. For applications that use a thread context class loader (such as web applications running inside a servet container), this will return a separate instance for each application, even if this class is loaded from a shared parent class loader.

Returns:

the per-application singleton instance of CatalogFactory

clear

public static void clear()

Clear all references to registered catalogs, as well as to the relevant class loader. This method should be called, for example, when a web application utilizing this class is removed from service, to allow for garbage collection.

getClassLoader

private static java.lang.ClassLoader getClassLoader()

Return the relevant ClassLoader to use as a Map key for this request. If there is a thread context class loader, return that; otherwise, return the class loader that loaded this class.