net.sourceforge.groboutils.autodoc.v1
Class AutoDoc

java.lang.Object
  net.sourceforge.groboutils.autodoc.v1.AutoDoc

public class AutoDoc

extends java.lang.Object

Entry class for loading the AutoDoc pieces for a particular class. As this class is always instantiated, it does not need an interface. This acts as a central factory for generating all the AutoDoc instances.

This default implementation uses a static factory to load each instance's data. That factory may be set by a using class. Since initialization of the inner data is lazy-loaded (only loaded when needed, but when needed it is all loaded), the factory may be set at any time after construction, and before a data access member function is called. If no factory is ever specified, it will load the factory from the fully-qualified class name in the value of the System property specified by the key given by FACTORY_PROPERTY_NAME.

This class follows a combination of the Abstract Factory and Proxy patterns. AutoDoc acts as a Proxy for an Abstract Factory, allowing the particular implemented factory to be hidden from the user. However, a "hole" is open to each instance with the method setFactory(), allowing the owner to setup the factory to their needs.

NOTE: need to update the documentation. I've since replaced the single factory with an SPI fleet. The proxied objects are delegators to collections of sub-proxies, which are loaded as late as possible.

Since:

March 16, 2002

Version:

$Date: 2003/02/10 22:52:11 $

Author:

Matt Albrecht groboclown@users.sourceforge.net

Constructor Summary

AutoDoc(java.lang.Class c)
Base constructor.

Method Summary

protected void	addFactory(AutoDocFactory adf) Sets the AutoDoc factory instance.
protected void	checkLoad() Check if the data instances have been loaded.
protected void	cleanUpFactories() After loading the instances, we have no need to keep the memory of the original factories around - they may pollute our loaded proxied objects anyway.
protected AutoDocFactory[]	getFactories() Returns the factory this implementation knows.
static SPISingletonStore	getFactoryStore() Retrieve the AutoDocFactory singleton store for setting up the factory to be used for all uninitialized or uncreated AutoDoc instances.
AutoDocIT	getIT() Get the Issue Tracker implementation.
AutoDocLog	getLog() Get the log implementation.
protected java.lang.Class	getOwner() Retrieves the owning class.
AutoDocTP	getTP() Get the Test Procedure Marker implementation.
protected void	loadFromFactory(AutoDocFactory adf) Adds to all inner instances from the given factory.
protected void	loadInstances() Loads all class

Methods inherited from class java.lang.Object

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

Constructor Detail

AutoDoc

public AutoDoc(java.lang.Class c)

Base constructor. Pass in the Class instance which will AutoDoc itself.

Parameters:

c - the class which will be AutoDoced.

Throws:

java.lang.IllegalArgumentException - if the passed-in class is null.

Method Detail

getLog

public AutoDocLog getLog()

Get the log implementation. Each call will return the same object.

Returns:

the log for the owning class.

getIT

public AutoDocIT getIT()

Get the Issue Tracker implementation. Each call will return the same object.

Returns:

the Issue Tracker for the owning class.

getTP

public AutoDocTP getTP()

Get the Test Procedure Marker implementation. Each call will return the same object.

checkLoad

protected final void checkLoad()

Check if the data instances have been loaded. If they have not, then load the instances, and ensure initialization is not performed again. This lazy-loading is thread-safe.

getOwner

protected final java.lang.Class getOwner()

Retrieves the owning class. Will never return null.

Returns:

the class which is being AutoDoced.

loadInstances

protected void loadInstances()

Loads all class

loadFromFactory

protected void loadFromFactory(AutoDocFactory adf)

Adds to all inner instances from the given factory.

getFactories

protected AutoDocFactory[] getFactories()

Returns the factory this implementation knows. By default, this is the static factory instance. This is only called at AutoDoc creation time. This is not static, because subclasses may need to re-implement this method. The factory may be changed through invocation of setFactory( AutoDocFactory ).

Returns:

the inner factory, or the static singleton if it was never assigned.

cleanUpFactories

protected void cleanUpFactories()

After loading the instances, we have no need to keep the memory of the original factories around - they may pollute our loaded proxied objects anyway. But since we've loaded, we don't want to allow another load. So keep the vector, but clean it out.

addFactory

protected void addFactory(AutoDocFactory adf)

Sets the AutoDoc factory instance. If this method is never invoked, then the default static store will be used instead.

The standard factory/singleton pattern used in this framework normally does not allow direct setting of the framework for an instance, but rather for the classloader's class. Since AutoDoc (or a subclass) is directly instantiated as a central processing point, opening a "hole" into the class allows for an easier method to setup a particular AutoDoc style. However, this is not the "recommended" usage, since, in general, AutoDoc instances are instantiated independently throughout many different classes, causing independent factory setting to be more difficult.

Parameters:

adf - the new factory to assign.

Throws:

java.lang.IllegalArgumentException - if adf is null.

java.lang.IllegalStateException - if the inner factory has already been assigned. This usually indicates that all the objects have already been loaded.

getFactoryStore

public static SPISingletonStore getFactoryStore()

Retrieve the AutoDocFactory singleton store for setting up the factory to be used for all uninitialized or uncreated AutoDoc instances.