org.jpu.patterns.factory
Class PrototypeFactory

java.lang.Object
  org.jpu.patterns.factory.PrototypeFactory

All Implemented Interfaces:

IPrototypeFactory

public abstract class PrototypeFactory

extends java.lang.Object

implements IPrototypeFactory

Implementation of IPrototypeFactory.

Nested Class Summary

Nested classes inherited from class org.jpu.patterns.factory.IPrototypeFactory

IPrototypeFactory.IConfigStrategy, IPrototypeFactory.IInitializer, IPrototypeFactory.IInstantiator, IPrototypeFactory.IPrototypeReference

Constructor Summary

PrototypeFactory()

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.
protected java.lang.Object	clonePrototype(java.lang.Object prototype, FactoryOptions options) Clones the given prototype.
protected java.lang.String	descPrototype(java.lang.Object prototype) Returns a description of the given prototype for logging.
protected void	doGetAllowableTypes(java.util.Set types) The subclass can override this method to enable type checking for inserted prototypes.
protected java.lang.Object	doNewObject(java.lang.Object prototype, FactoryOptions options) Creates a new object based on the given prototype.
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.
protected java.util.List	getModifiableKeysList() Returns the modifiable list of prototype keys ordered by their insertion into the factory.
protected java.util.Map	getModifiablePrototypeMap() Gets the modifiable prototype map.
java.lang.Object	getObject(java.lang.Object key, FactoryOptions options)
protected java.lang.Object	getPrototypeFromMap(java.lang.Object key)
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.
protected java.lang.Object	newInstance(java.lang.Class itsClass, FactoryOptions options) Creates a new instance of the given class.
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 key)
java.lang.Object	newObject(java.lang.Object key, FactoryOptions options)
protected boolean	okayToClone(java.lang.Object prototype) By default returns false, but subclasses may override.
protected java.lang.String	prepareKeyForLookup(java.lang.Object key) Changes the given key to a String for lookup.
boolean	preserveInsertionOrder() Retruns whether prototype insertion order is preserved and thus avaiable for later retrieval via getPrototypeKeysInInsertionOrder().
boolean	prototypeExists(java.lang.Object key) 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.
protected java.lang.Object	putPrototypeToMap(java.lang.Object key, java.lang.Object value)
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.

Methods inherited from class java.lang.Object

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

Constructor Detail

PrototypeFactory

public PrototypeFactory()

Method Detail

getInitializers

public java.util.List getInitializers()

Description copied from interface: IPrototypeFactory

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.

Specified by:

getInitializers in interface IPrototypeFactory

addInitializer

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

Description copied from interface: IPrototypeFactory

Adds the given initializer at position "i".

Specified by:

addInitializer in interface IPrototypeFactory

removeInitializer

public IPrototypeFactory.IInitializer removeInitializer(int i)

Description copied from interface: IPrototypeFactory

Removes the given initializer at position "i".

Specified by:

removeInitializer in interface IPrototypeFactory

removeInitializer

public boolean removeInitializer(IPrototypeFactory.IInitializer ini)

Description copied from interface: IPrototypeFactory

Removes the given initializer.

Specified by:

removeInitializer in interface IPrototypeFactory

getLock

public IReentrantLock getLock()

Description copied from interface: IPrototypeFactory

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

Specified by:

getLock in interface IPrototypeFactory

setLock

public void setLock(IReentrantLock lock)

Description copied from interface: IPrototypeFactory

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

Specified by:

setLock in interface IPrototypeFactory

lock

public boolean lock()

Description copied from interface: IPrototypeFactory

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

Specified by:

lock in interface IPrototypeFactory

unlock

public void unlock(boolean locked)

Description copied from interface: IPrototypeFactory

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

Specified by:

unlock in interface IPrototypeFactory

getAllowableTypes

public java.util.Set getAllowableTypes()

Description copied from interface: IPrototypeFactory

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

Specified by:

getAllowableTypes in interface IPrototypeFactory

isTypeAllowed

public boolean isTypeAllowed(java.lang.Class theType)

Description copied from interface: IPrototypeFactory

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

Specified by:

isTypeAllowed in interface IPrototypeFactory

assertTypeAllowed

public void assertTypeAllowed(java.lang.Class theType)

Description copied from interface: IPrototypeFactory

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

Specified by:

assertTypeAllowed in interface IPrototypeFactory

getPrototypes

public java.util.Map getPrototypes()

Description copied from interface: IPrototypeFactory

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

Specified by:

getPrototypes in interface IPrototypeFactory

getPrototypeKeysInInsertionOrder

public java.util.List getPrototypeKeysInInsertionOrder()

Description copied from interface: IPrototypeFactory

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.

Specified by:

getPrototypeKeysInInsertionOrder in interface IPrototypeFactory

getPrototypesInInsertionOrder

public java.util.List getPrototypesInInsertionOrder()
                                             throws PrototypeFactoryException

Description copied from interface: IPrototypeFactory

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

Specified by:

getPrototypesInInsertionOrder in interface IPrototypeFactory

Throws:

PrototypeFactoryException

setConfigStrategy

public void setConfigStrategy(IPrototypeFactory.IConfigStrategy strat)

Description copied from interface: IPrototypeFactory

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

Specified by:

setConfigStrategy in interface IPrototypeFactory

getConfigStrategy

public IPrototypeFactory.IConfigStrategy getConfigStrategy()

Description copied from interface: IPrototypeFactory

Returns the IPrototypeFactory.IConfigStrategy used to configure this factory.

Specified by:

getConfigStrategy in interface IPrototypeFactory

newConfigStrategy

public IPrototypeFactory.IConfigStrategy newConfigStrategy()

Description copied from interface: IPrototypeFactory

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

Specified by:

newConfigStrategy in interface IPrototypeFactory

newObject

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

Specified by:

newObject in interface IPrototypeFactory

Throws:

PrototypeFactoryException

newObject

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

Specified by:

newObject in interface IPrototypeFactory

Throws:

PrototypeFactoryException

newObject

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

Specified by:

newObject in interface IPrototypeFactory

Throws:

PrototypeFactoryException

newObject

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

Specified by:

newObject in interface IPrototypeFactory

Throws:

PrototypeFactoryException

getObject

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

Specified by:

getObject in interface IPrototypeFactory

Throws:

PrototypeFactoryException

prototypeExists

public boolean prototypeExists(java.lang.Object key)

Description copied from interface: IPrototypeFactory

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

Specified by:

prototypeExists in interface IPrototypeFactory

clear

public void clear()

Description copied from interface: IPrototypeFactory

Removes all prototypes from the factory.

Specified by:

clear in interface IPrototypeFactory

putPrototype

public void putPrototype(java.lang.Object obj)

Description copied from interface: IPrototypeFactory

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

Specified by:

putPrototype in interface IPrototypeFactory

putPrototype

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

Description copied from interface: IPrototypeFactory

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

Specified by:

putPrototype in interface IPrototypeFactory

putPrototype

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

Description copied from interface: IPrototypeFactory

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 IPrototypeFactory.getIntrinsicAliases(java.lang.Object, java.util.Set).

Specified by:

putPrototype in interface IPrototypeFactory

getSynchronized

public boolean getSynchronized()

Description copied from interface: IPrototypeFactory

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, IPrototypeFactory.getLock() and IPrototypeFactory.setLock(IReentrantLock) can be used to respectively get and set the IReentrantLock used for synchronization.

Specified by:

getSynchronized in interface IPrototypeFactory

setSynchronized

public void setSynchronized(boolean s)

Description copied from interface: IPrototypeFactory

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, IPrototypeFactory.getLock() and IPrototypeFactory.setLock(IReentrantLock) can be used to respectively get and set the IReentrantLock used for synchronization.

Specified by:

setSynchronized in interface IPrototypeFactory

getLookupCaseSensitive

public boolean getLookupCaseSensitive()

Description copied from interface: IPrototypeFactory

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

Specified by:

getLookupCaseSensitive in interface IPrototypeFactory

Returns:

true if lookup is case sensitive, false otherwise.

setLookupCaseSensitive

public void setLookupCaseSensitive(boolean b)

Description copied from interface: IPrototypeFactory

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

Specified by:

setLookupCaseSensitive in interface IPrototypeFactory

preserveInsertionOrder

public boolean preserveInsertionOrder()

Description copied from interface: IPrototypeFactory

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

Specified by:

preserveInsertionOrder in interface IPrototypeFactory

Returns:

true if prototype insertion order is preserved, false otherwise.

putPrototypeToMap

protected java.lang.Object putPrototypeToMap(java.lang.Object key,
                                             java.lang.Object value)

getPrototypeFromMap

protected java.lang.Object getPrototypeFromMap(java.lang.Object key)

doNewObject

protected java.lang.Object doNewObject(java.lang.Object prototype,
                                       FactoryOptions options)

Creates a new object based on the given prototype. Cloning is the preferred method of obtaining the new object and is done via clonePrototype(Object,FactoryOptions) if okayToClone(Object) returns true; else newInstance() is called on the prototype's class to invoke the no-arg constructor.

initializePrototype

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

Description copied from interface: IPrototypeFactory

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).

Specified by:

initializePrototype in interface IPrototypeFactory

okayToClone

protected boolean okayToClone(java.lang.Object prototype)

By default returns false, but subclasses may override. Returns whether it is acceptable for the factory to clone the given prototype when a new instance of this prototype is requested. If this method returns true, reflection will be used to call a public clone() method; else the class of the prototype will be obtained and newInstance() called on it.

Parameters:

prototype - The prototype.

Returns:

See above.

prepareKeyForLookup

protected java.lang.String prepareKeyForLookup(java.lang.Object key)

Changes the given key to a String for lookup. Default implementation converts the key to a string and downcases it if getLookupCaseSensitive() is true, but subclasses are free to override.

getIntrinsicAliases

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

Description copied from interface: IPrototypeFactory

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.

Specified by:

getIntrinsicAliases in interface IPrototypeFactory

Parameters:

prototype - The prototype.

aliases - The set into which aliases may be inserted.

clonePrototype

protected java.lang.Object clonePrototype(java.lang.Object prototype,
                                          FactoryOptions options)

Clones the given prototype. By default this method uses JPUObjectUtils.cloneObjectEfficiently(Object), but subclasses are free to override.

newInstance

protected java.lang.Object newInstance(java.lang.Class itsClass,
                                       FactoryOptions options)

Creates a new instance of the given class. By default this method uses itClass.newInstance(), but subclasses are free to override.

getModifiablePrototypeMap

protected java.util.Map getModifiablePrototypeMap()

Gets the modifiable prototype map. If this is the first time the method has been called, it creates the Map and calls IPrototypeFactory.IConfigStrategy.configure() on this factory's IPrototypeFactory.IConfigStrategy; else calls IPrototypeFactory.IConfigStrategy.reconfigureIfNecessary() on the config strategy and returns the Map.

getModifiableKeysList

protected java.util.List getModifiableKeysList()

Returns the modifiable list of prototype keys ordered by their insertion into the factory. If insertion order is not preserved, returns an empty List.

descPrototype

protected java.lang.String descPrototype(java.lang.Object prototype)

Returns a description of the given prototype for logging. By default just returns a string containing the prototype's class, but subclasses are free to override.

doGetAllowableTypes

protected void doGetAllowableTypes(java.util.Set types)

The subclass can override this method to enable type checking for inserted prototypes. The override should call types.add(x.class) for all permissible classes x. The default implementation does nothing.