org.springframework.beandoc
Class DefaultContextProcessor

java.lang.Object
  extended by org.springframework.beandoc.DefaultContextProcessor
All Implemented Interfaces:
ContextProcessor, InitializingBean

public class DefaultContextProcessor
extends Object
implements ContextProcessor, InitializingBean

Default implementation of the ContextProcessor interface that generates documentation in a file system directory. Input context files can be any resolveable Spring Resource.

This class maintains a List of Decorator objects and a List of Transformer objects that it manages and uses to conduct most of the actual output. Input resources are verified and loaded into memory before being cleaned of XML comments and extra whitespace. Bean references are marked with an additional attribute denoting the original name of the file that they were found in prior to each Decorator being applied in turn. Following decoration of the DOM trees, each Transformer is subsequently applied to the array of input DOM's.

The processor offers the ability to ignore some beans in the context by means of simple pattern matching. Ignored bean definitions are stripped from the DOM prior to decoration and transformation and will therefore not show up in any output.

Since:
1.0
Author:
Darren Davison, Marat Radchenko, Jan Tietjens

Field Summary
static org.jdom.Namespace SPRING_2_0_NAMESPACE
           
 
Constructor Summary
protected DefaultContextProcessor(Resource[] inputFiles, File outputDir)
          Construct with an array of Spring Resources used as input files for the program
  DefaultContextProcessor(String[] inputFileNames, File outputDir)
          Construct with an array of resource names that will resolve to one or more input resources using standard Spring Resource resolution strategies.
  DefaultContextProcessor(String[] inputFileNames, String outputDirName)
          Construct with an array of resource names that will resolve to one or more input resources using standard Spring Resource resolution strategies.
 
Method Summary
 void afterPropertiesSet()
           
protected  Element createBeanElement(BeanDefinition beanDefinition, Document document, String name)
           
protected  Element createBeanElement(BeanDefinitionHolder beanDefinitionHolder, Document document)
           
 List getCompilers()
           
 List getDecorators()
           
 Resource[] getInputFiles()
          The input resources (files, classpath resources) used as the actual inputs to the beandoc tool.
 Map getMergeProxies()
           
 File getOutputDir()
          The File representing an output directory that the beandoc tool will use for outputting HTML and graph images.
 List getTransformers()
           
 boolean isValidateFiles()
          Input files can optionally be validated against a DTD in the XML file.
 void process()
          Handles each input file in turn, parsing the XML (which must validate against the DTD unless validation has been turned off (see setValidateFiles(boolean)) creating an array of in-memory DOM documents of all input files.
static void setAttribute(org.jdom.Element element, String attributeName, String attributeValue)
           
 void setCompilers(List list)
           
 void setDecorators(List list)
           
 void setMergeProxies(Map map)
          Permits selective merging of ProxyFactory beans and their targets where the targets are defined as top level (referenceable) beans rather than inner beans.
static void setSpringNamespace(org.jdom.Element element, boolean recursive)
           
 void setTransformers(List list)
          Set a List of Transformers.
 void setValidateFiles(boolean validateFiles)
          Set to false to prevent the XML parser validating input files against a DTD.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SPRING_2_0_NAMESPACE

public static final org.jdom.Namespace SPRING_2_0_NAMESPACE
Constructor Detail

DefaultContextProcessor

protected DefaultContextProcessor(Resource[] inputFiles,
                                  File outputDir)
                           throws IOException
Construct with an array of Spring Resources used as input files for the program

Parameters:
inputFiles -
outputDir -
Throws:
IOException

DefaultContextProcessor

public DefaultContextProcessor(String[] inputFileNames,
                               File outputDir)
                        throws IOException
Construct with an array of resource names that will resolve to one or more input resources using standard Spring Resource resolution strategies.

Parameters:
inputFileNames -
outputDir -
Throws:
IOException

DefaultContextProcessor

public DefaultContextProcessor(String[] inputFileNames,
                               String outputDirName)
                        throws IOException
Construct with an array of resource names that will resolve to one or more input resources using standard Spring Resource resolution strategies.

Parameters:
inputFileNames -
outputDirName -
Throws:
IOException
Method Detail

process

public void process()
             throws IOException,
                    BeanDocException
Handles each input file in turn, parsing the XML (which must validate against the DTD unless validation has been turned off (see setValidateFiles(boolean)) creating an array of in-memory DOM documents of all input files. The method adds an attribute to each tag that points to another bean such as <ref/> tags. This attribute contains the file name of the input file that contains the bean definition and can be used to link bean definitions for example in HTML documentation.

The array of Document objects is passed to each Decorator configured for use which can incrementally modify the attributes in the DOM trees.

The process method is threadsafe, synchronizing on a private lock during the execution of documentation output. A configured DefaultContextProcessor is therefore re-usable from client code, and the configuration properties can be modified between calls to the process method.

Specified by:
process in interface ContextProcessor
Throws:
IOException - if the input files cannot be read, if the output directory does not exist or is not writable, or if media files cannot be copied from the classpath to the output directory.
BeanDocException - of the input files do not validate against the DTD, if a problem occurs attempting to create graphs from the .dot files (such as the GraphViz program being unavailable) or other unknown problem occurs.
See Also:
ContextProcessor.process()

createBeanElement

protected Element createBeanElement(BeanDefinitionHolder beanDefinitionHolder,
                                    Document document)

createBeanElement

protected Element createBeanElement(BeanDefinition beanDefinition,
                                    Document document,
                                    String name)

setSpringNamespace

public static void setSpringNamespace(org.jdom.Element element,
                                      boolean recursive)

setAttribute

public static void setAttribute(org.jdom.Element element,
                                String attributeName,
                                String attributeValue)

setValidateFiles

public void setValidateFiles(boolean validateFiles)
Set to false to prevent the XML parser validating input files against a DTD.

Parameters:
validateFiles - set to true to enable validation, false otherwise. True by default.

getOutputDir

public File getOutputDir()
The File representing an output directory that the beandoc tool will use for outputting HTML and graph images.

Returns:
the directory that output will be written to.

getInputFiles

public Resource[] getInputFiles()
The input resources (files, classpath resources) used as the actual inputs to the beandoc tool. Typical non-trivial application contexts will be made up of two or more resources.

Returns:
the array of input resources that make up the application context being documented.

isValidateFiles

public boolean isValidateFiles()
Input files can optionally be validated against a DTD in the XML file. True by default.

Returns:
true if input files should be validated against a DTD, false otherwise.

getTransformers

public List getTransformers()
Returns:
the List of Transformer objects that will be applied to the context files and generate the output.

setTransformers

public void setTransformers(List list)
Set a List of Transformers. Each of these will be applied in turn by the process() method in order to generate output.

Parameters:
list - the List of Transformer objects

getDecorators

public List getDecorators()
Returns:
the List of Decorator implementations that will have an opportunity to markup the DOM trees with additional attributes or elements based on the configuration

setDecorators

public void setDecorators(List list)
Parameters:
list - the List of Decorator implementations that will have an opportunity to markup the DOM trees with additional attributes or elements based on the configuration

getCompilers

public List getCompilers()
Returns:
the List of DocumentCompiler implementations that will plug various pieces of transformed output together

setCompilers

public void setCompilers(List list)
Parameters:
list - the List of DocumentCompiler implementations that will plug various pieces of transformed output together

setMergeProxies

public void setMergeProxies(Map map)
Permits selective merging of ProxyFactory beans and their targets where the targets are defined as top level (referenceable) beans rather than inner beans. This potentially keeps the documentation and graphing output cleaner by showing one logical entity instead of two for the proxy and its target.

The keys into the Map specify a RegEx expression denoting either the bean name or the class name of the proxy bean (the wrapper). The value associated with the key is the property name that the target is referenced under. Typically this will be 'target'. Map values must be String objects specifying a bean property and not RegEx expressions or other object.

Parameters:
map - which cannot be null and will throw IllegalArgumentException if it is.

getMergeProxies

public Map getMergeProxies()
Returns:
the Map denoting which Proxy wrappers and their targets to merge

afterPropertiesSet

public void afterPropertiesSet()
                        throws Exception
Specified by:
afterPropertiesSet in interface InitializingBean
Throws:
Exception


Copyright © 2004-2011 Spring BeanDoc. All Rights Reserved.