org.jpu.patterns.factory
Interface IPrototypeFactory

All Known Implementing Classes:

PrototypeFactory

public interface IPrototypeFactory

Interface for classes that provide general-purpose functionality commonly needed by prototype-based factories, especially those that need to be initialized from an external configuration source such as a properties or XML file. See PrototypeFactory for a an implementation.

Features include the following:

• Configuration support via the IPrototypeFactory.IConfigStrategy interface, which can support any arbitrary configuration source. A property-based configurator called PropertyFactoryConfigStrategy is included, and can be tailored to hook into whichever configuration source your application uses; or you can write your own custom strategy.
• Automatic type checking of prototypes as they are added to the factory. The subclass can override the method PrototypeFactory.doGetAllowableTypes(java.util.Set) to define which types are permitted. An attempt to add a prototype of an illegal type results in an exception.
• Support for both synchronized and unsynchronized operation. Synchronization is enabled by default but can be disabled by passing false to setSynchronized(boolean). If you disable synchronization, you should enclose calls to IPrototypeFactory in appropriate synchronized blocks if the factory can be referenced concurrently by multiple threads.
• Support for strategization of the instantiation process. Among other things, this allows the use of dynamically generated proxies as prototypes. Such a proxy is of a class that has no well-known name and hence cannot be listed in the configuration file as a prototype. However, if you write a class that implements IPrototypeFactory.IInstantiator, and list the instantiator's name in the configuration file, the factory will delegate prototype creation to your instantiator's IPrototypeFactory.IInstantiator.create(org.jpu.patterns.factory.FactoryOptions) method, which in turn can use any arbitrary approach to instantiation including use of java.lang.reflect.Proxy.newProxyInstance().
• Support for strategization of the prototype initialization process. Prototype initialization strategies implementing the interface IPrototypeFactory.IInitializer may be registered with the factory, and they will be called in the specified order to initialize an object after its instantiation prior to its return to the client.
• Standard map-oriented methods for querying the prototype map and dynamically adding and removing prototypes.

Nested Class Summary

static interface	IPrototypeFactory.IConfigStrategy Defines the interface to the factory's configurator.
static interface	IPrototypeFactory.IInitializer Interface to be implemented by classes that are registered as initializers via addInitializer(int, org.jpu.patterns.factory.IPrototypeFactory.IInitializer).
static interface	IPrototypeFactory.IInstantiator Interface to be implemented by a class to which object creation should be delegated.
static interface	IPrototypeFactory.IPrototypeReference

Method Summary

void	addInitializer(int i, IPrototypeFactory.IInitializer initializer) Adds the given initializer at position "i".
void	assertTypeAllowed(java.lang.Class theType) Calls isTypeAllowed(Class) and throws TypeMismatchException if it returns false.
void	clear() Removes all prototypes from the factory.
java.util.Set	getAllowableTypes() Returns the set types allowable for prototypes held by this factory.
IPrototypeFactory.IConfigStrategy	getConfigStrategy() Returns the IPrototypeFactory.IConfigStrategy used to configure this factory.
java.util.List	getInitializers() Returns a shallow copy of the internal list of IPrototypeFactory.IInitializer's.
void	getIntrinsicAliases(java.lang.Object prototype, java.util.Set aliases) By default does nothing, but subclasses may override.
IReentrantLock	getLock() Returns the lock used for synchronizing on shared data structures.
boolean	getLookupCaseSensitive() Returns whether factory lookup of prototypes is case sensitive.
java.lang.Object	getObject(java.lang.Object key, FactoryOptions options)
java.util.List	getPrototypeKeysInInsertionOrder() If prototype insertion order is being preserved (as determined by preserveInsertionOrder()), returns the keys of these prototypes as an unmodifiable List in the order in which they were inserted; else returns an empty unmodifiable List.
java.util.Map	getPrototypes() Returns an unmodifiable Map defining the mapping between prototype keys and their corresponding prototypes.
java.util.List	getPrototypesInInsertionOrder() If prototype insertion order is being preserved (as determined by preserveInsertionOrder()), returns the prototypes as an unmodifiable List in the order in which they were inserted; else returns an empty unmodifiable List.
boolean	getSynchronized() Returns whether the factory synchronizes on a IReentrantLock to protect shared data structures.
void	initializePrototype(java.lang.Object prototype, int howCreated, FactoryOptions options) Calls all initializers registered with the factory in order.
boolean	isTypeAllowed(java.lang.Class theType) Returns the set types allowable for prototypes held by this factory.
boolean	lock() If getSynchronized() returns false this method does nothing; else it acquires the lock returned by getLock().
IPrototypeFactory.IConfigStrategy	newConfigStrategy() Creates a new IPrototypeFactory.IConfigStrategy.
java.lang.Object	newObject(java.lang.Class itsClass)
java.lang.Object	newObject(java.lang.Class itsClass, FactoryOptions options)
java.lang.Object	newObject(java.lang.Object name)
java.lang.Object	newObject(java.lang.Object name, FactoryOptions options)
boolean	preserveInsertionOrder() Retruns whether prototype insertion order is preserved and thus avaiable for later retrieval via getPrototypeKeysInInsertionOrder().
boolean	prototypeExists(java.lang.Object name) Returns whether a prototype is currently keyed under the given name.
void	putPrototype(java.lang.Object obj) Convenience alias for "putPrototype( obj, (Object[])null )".
void	putPrototype(java.lang.Object obj, java.lang.Object oneAlias) Convenience alias for "putPrototype( obj, new Object[] { oneAlias } )".
void	putPrototype(java.lang.Object obj, java.lang.Object[] explicitAliases) Enters the given object into the factory as a prototype.
IPrototypeFactory.IInitializer	removeInitializer(int i) Removes the given initializer at position "i".
boolean	removeInitializer(IPrototypeFactory.IInitializer ini) Removes the given initializer.
void	setConfigStrategy(IPrototypeFactory.IConfigStrategy strat) Causes this factory to use "strat" as its configuration strategy.
void	setLock(IReentrantLock lock) Sets the lock used for synchronizing on shared data structures.
void	setLookupCaseSensitive(boolean b) Sets the flag indicating whether lookup of prototypes is case sensitive or not.
void	setSynchronized(boolean s) Sets the flag indiciating whether the factory synchronizes on a IReentrantLock to protect shared data structures.
void	unlock(boolean locked) If locked is true, calls "getLock().unlock()"; else does nothing.

Method Detail

initializePrototype

public void initializePrototype(java.lang.Object prototype,
                                int howCreated,
                                FactoryOptions options)

Calls all initializers registered with the factory in order. The last three parameters are passed directly to IPrototypeFactory.IInitializer.initialize(org.jpu.patterns.factory.IPrototypeFactory, java.lang.Object, int, org.jpu.patterns.factory.FactoryOptions).

getInitializers

public java.util.List getInitializers()

Returns a shallow copy of the internal list of IPrototypeFactory.IInitializer's. Since the List is a copy, the caller can query and modify it at will without synchronization.

addInitializer

public void addInitializer(int i,
                           IPrototypeFactory.IInitializer initializer)

Adds the given initializer at position "i".

removeInitializer

public IPrototypeFactory.IInitializer removeInitializer(int i)

Removes the given initializer at position "i".

removeInitializer

public boolean removeInitializer(IPrototypeFactory.IInitializer ini)

Removes the given initializer.

getConfigStrategy

public IPrototypeFactory.IConfigStrategy getConfigStrategy()

Returns the IPrototypeFactory.IConfigStrategy used to configure this factory.

lock

public boolean lock()

If getSynchronized() returns false this method does nothing; else it acquires the lock returned by getLock(). Returns whether a lock was acquired or not.

unlock

public void unlock(boolean locked)

If locked is true, calls "getLock().unlock()"; else does nothing.

getLock

public IReentrantLock getLock()

Returns the lock used for synchronizing on shared data structures. This lock is only used if getSynchronized() returns true.

setLock

public void setLock(IReentrantLock lock)

Sets the lock used for synchronizing on shared data structures. This lock is only used if getSynchronized() returns true.

getSynchronized

public boolean getSynchronized()

Returns whether the factory synchronizes on a IReentrantLock to protect shared data structures. Synchronization is enabled by default but can be disabled if needed. If synchronization is disabled, getLock() and setLock(IReentrantLock) can be used to respectively get and set the IReentrantLock used for synchronization.

setSynchronized

public void setSynchronized(boolean s)

Sets the flag indiciating whether the factory synchronizes on a IReentrantLock to protect shared data structures. Synchronization is enabled by default but can be disabled if needed. If synchronization is disabled, getLock() and setLock(IReentrantLock) can be used to respectively get and set the IReentrantLock used for synchronization.

getAllowableTypes

public java.util.Set getAllowableTypes()

Returns the set types allowable for prototypes held by this factory. Each element in the set is a Class instance.

isTypeAllowed

public boolean isTypeAllowed(java.lang.Class theType)

Returns the set types allowable for prototypes held by this factory. Each element in the set is a Class instance.

assertTypeAllowed

public void assertTypeAllowed(java.lang.Class theType)

Calls isTypeAllowed(Class) and throws TypeMismatchException if it returns false.

getPrototypes

public java.util.Map getPrototypes()

Returns an unmodifiable Map defining the mapping between prototype keys and their corresponding prototypes.

getPrototypeKeysInInsertionOrder

public java.util.List getPrototypeKeysInInsertionOrder()

If prototype insertion order is being preserved (as determined by preserveInsertionOrder()), returns the keys of these prototypes as an unmodifiable List in the order in which they were inserted; else returns an empty unmodifiable List.

getPrototypesInInsertionOrder

public java.util.List getPrototypesInInsertionOrder()
                                             throws PrototypeFactoryException

If prototype insertion order is being preserved (as determined by preserveInsertionOrder()), returns the prototypes as an unmodifiable List in the order in which they were inserted; else returns an empty unmodifiable List.

Throws:

PrototypeFactoryException

preserveInsertionOrder

public boolean preserveInsertionOrder()

Retruns whether prototype insertion order is preserved and thus avaiable for later retrieval via getPrototypeKeysInInsertionOrder().

Returns:

true if prototype insertion order is preserved, false otherwise.

prototypeExists

public boolean prototypeExists(java.lang.Object name)

Returns whether a prototype is currently keyed under the given name.

clear

public void clear()

Removes all prototypes from the factory.

newObject

public java.lang.Object newObject(java.lang.Class itsClass,
                                  FactoryOptions options)
                           throws PrototypeFactoryException

Throws:

PrototypeFactoryException

newObject

public java.lang.Object newObject(java.lang.Class itsClass)
                           throws PrototypeFactoryException

Throws:

PrototypeFactoryException

newObject

public java.lang.Object newObject(java.lang.Object name,
                                  FactoryOptions options)
                           throws PrototypeFactoryException

Throws:

PrototypeFactoryException

newObject

public java.lang.Object newObject(java.lang.Object name)
                           throws PrototypeFactoryException

Throws:

PrototypeFactoryException

getObject

public java.lang.Object getObject(java.lang.Object key,
                                  FactoryOptions options)
                           throws PrototypeFactoryException

Throws:

PrototypeFactoryException

putPrototype

public void putPrototype(java.lang.Object obj)

Convenience alias for "putPrototype( obj, (Object[])null )".

putPrototype

public void putPrototype(java.lang.Object obj,
                         java.lang.Object oneAlias)

Convenience alias for "putPrototype( obj, new Object[] { oneAlias } )".

getIntrinsicAliases

public void getIntrinsicAliases(java.lang.Object prototype,
                                java.util.Set aliases)

By default does nothing, but subclasses may override. All prototypes and keyed by at least one name; in addition, each prototype may be assigned one or more "aliases", which are simply additional names by which the prototype may be referenced. This method is expected to insert into the aliases set zero or more such aliases. The alias should be unique among all the prototype keys; if it isn't, any previous mapping associated with the alias you assign will be silently overwritten.

It is good practice to call super.getIntrinsicAliases(prototype, aliases) before doing anything else in your subclass implementation of this method.

Parameters:

prototype - The prototype.

aliases - The set into which aliases may be inserted.

putPrototype

public void putPrototype(java.lang.Object obj,
                         java.lang.Object[] explicitAliases)

Enters the given object into the factory as a prototype. It will be registered under all keys passed in "explicitAliases", as well as all keys returned by getIntrinsicAliases(java.lang.Object, java.util.Set).

setConfigStrategy

public void setConfigStrategy(IPrototypeFactory.IConfigStrategy strat)

Causes this factory to use "strat" as its configuration strategy.

newConfigStrategy

public IPrototypeFactory.IConfigStrategy newConfigStrategy()

Creates a new IPrototypeFactory.IConfigStrategy. The default implementation creates a PropertyFactoryConfigStrategy, but subclasses are free to override.

getLookupCaseSensitive

public boolean getLookupCaseSensitive()

Returns whether factory lookup of prototypes is case sensitive. Set to true by default but can be changed via setLookupCaseSensitive(boolean).

Returns:

true if lookup is case sensitive, false otherwise.

setLookupCaseSensitive

public void setLookupCaseSensitive(boolean b)

Sets the flag indicating whether lookup of prototypes is case sensitive or not. Set to true by default.