net.sourceforge.stripes.tools
Class SiteStructureTool

java.lang.Object
  extended by net.sourceforge.stripes.tools.SiteStructureTool
All Implemented Interfaces:
AnnotationProcessor, AnnotationProcessorFactory

public class SiteStructureTool
extends Object
implements AnnotationProcessor, AnnotationProcessorFactory

A tool for extracting and documenting information related to the site structure of a Stripes application. SiteStructureTool is an AnnotationProcessor (and it's own factory) for use with apt, the Annotation Processing Tool. It is capable of processing several of the annotations used with Stripes to extract information about what bean is bound to which URL, the set of events handled and the possible resolutions. This information can then be printed to the screen, or output to a file in either text or xml format.

The SiteStructureTool can be run through the command line, though it is somewhat awkward with a large number of files, or a large classpath - it's command line is extremely similar to javac. A command line might look like this:

 apt -classpath $CLASSPATH -nocompile \
     -factory net.sourceforge.stripes.tools.SiteStructureTool \
     -Astripes.output.file=sitemap.txt \
     -Astripes.output.format=text \
     src/net/sourceforge/stripes/examples/bugzooky/web/*.java

SiteStructureTool modifies its behaviour based on two options. (Custom options are always passed to apt prefixed with -A). The first is stripes.output.file. This names the file into which the output will be written. If this option is omitted then the output is simply printed to the screen. The second option is stripes.output.format which controls (not surprisingly) the output format. Valid values are 'text' and 'xml'. If this value is omitted the default format is 'text' unless a filename is supplied which ends in '.xml', in which case xml output will be produced.

The easiest way to run the SiteStructureTool is with ant. Unfortunately the latest release of ant at the time of writing does not yet include an apt task. When it does, running apt through ant should become much simpler. Until then, you can run apt using an ant target like the example below:

 <target name="apt" depends="compile">
   <pathconvert property="cp" refid="build.class.path"/>
   <path id="srcfiles">
     <fileset dir="${src.dir}" includes="**‍/*.java"/>
   </path>
   <pathconvert property="srcfiles" refid="srcfiles" pathsep=" "/>
   <exec executable="apt">
     <arg line="-classpath ${cp} -nocompile"/>
     <arg line="-factory net.sourceforge.stripes.tools.SiteStructureTool"/>
     <arg line="-Astripes.output.file=sitemap.xml"/>
     <arg line="${srcfiles}"/>
   </exec>
 </target>

Since:
Stripes 1.1.2
Author:
Tim Fennell

Field Summary
static String FILE_PARAM
          Option name that controls the file to which output is written.
static String FORMAT_PARAM
          Option name that controls the output format of the annotation processor.
protected static Pattern RETURN_PATTERN
          Regular expression used to parse out return statements from a chunk of java source.
 
Constructor Summary
SiteStructureTool()
           
 
Method Summary
protected  String getOption(String name)
          For the named option to apt, returns the value of the option if it was supplied, or null if the option was not supplied.
 AnnotationProcessor getProcessorFor(Set<AnnotationTypeDeclaration> set, AnnotationProcessorEnvironment env)
          AnnotationProcessorFactory interface method that returns the SiteStructure annotation processor.
protected  void printTextEvent(PrintStream out, EventInfo event)
          Prints out a single event mapping in text format.
protected  void printTextFormat(PrintStream out)
          Prints out the accumulated information in text format to the supplied print stream.
protected  void printXmlEvent(PrintStream out, EventInfo event)
           
protected  void printXmlFormat(PrintStream out)
          Prints out the accumulated information in XML format.
 void process()
          AnnotationProcessor interface method that is invoked to perform the processing of the annotations discovered.
protected  void processHandlerAnnotations(Collection<Declaration> declarations)
          Responsible for iterating through the collection of declarations annotated with either @DefaultHandler, @HandlesEvent or both.
protected  void processUrlBindings(Collection<Declaration> declarations)
          Responsible for iterating through the collection of UrlBinding annotations and adding information to the instance level map of class names to ActionBeanInfo objects.
 Collection<String> supportedAnnotationTypes()
          AnnotationProcessorFactory interface method that returns the set of annotation class names that are supported.
 Collection<String> supportedOptions()
          AnnotationProcessorFactory interface method that returns the set of custom options that are supported.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FORMAT_PARAM

public static final String FORMAT_PARAM
Option name that controls the output format of the annotation processor.

See Also:
Constant Field Values

FILE_PARAM

public static final String FILE_PARAM
Option name that controls the file to which output is written.

See Also:
Constant Field Values

RETURN_PATTERN

protected static final Pattern RETURN_PATTERN
Regular expression used to parse out return statements from a chunk of java source.

Constructor Detail

SiteStructureTool

public SiteStructureTool()
Method Detail

supportedOptions

public Collection<String> supportedOptions()
AnnotationProcessorFactory interface method that returns the set of custom options that are supported. Currently returns the file name and format type parameter names.

Specified by:
supportedOptions in interface AnnotationProcessorFactory

supportedAnnotationTypes

public Collection<String> supportedAnnotationTypes()
AnnotationProcessorFactory interface method that returns the set of annotation class names that are supported. Currently returns the fully qualified names of the following annotations: @UrlBinding, @DefaultHandler, @HandlesEvent.

Specified by:
supportedAnnotationTypes in interface AnnotationProcessorFactory

getProcessorFor

public AnnotationProcessor getProcessorFor(Set<AnnotationTypeDeclaration> set,
                                           AnnotationProcessorEnvironment env)
AnnotationProcessorFactory interface method that returns the SiteStructure annotation processor. In reality all this method does is return the instance of the factory on which it is invoked because the SiteStructureTool is both the factory and the processor.

Specified by:
getProcessorFor in interface AnnotationProcessorFactory

process

public void process()
AnnotationProcessor interface method that is invoked to perform the processing of the annotations discovered. Builds up a set of information about the ActionBeans discovered and then prints it out according to the options passed in.

Specified by:
process in interface AnnotationProcessor

getOption

protected String getOption(String name)
For the named option to apt, returns the value of the option if it was supplied, or null if the option was not supplied.


processUrlBindings

protected void processUrlBindings(Collection<Declaration> declarations)
Responsible for iterating through the collection of UrlBinding annotations and adding information to the instance level map of class names to ActionBeanInfo objects.

Parameters:
declarations - a collection of Declarations annotated with UrlBinding.

processHandlerAnnotations

protected void processHandlerAnnotations(Collection<Declaration> declarations)
Responsible for iterating through the collection of declarations annotated with either @DefaultHandler, @HandlesEvent or both. Finds the relevant ActionBeanInfo object in the instance level map and adds the event information to it.

Parameters:
declarations - a collection of Declarations annotated with handler annotations.

printTextFormat

protected void printTextFormat(PrintStream out)
Prints out the accumulated information in text format to the supplied print stream. This produces a fairly human readable format that is not designed to be machine processed.


printTextEvent

protected void printTextEvent(PrintStream out,
                              EventInfo event)
Prints out a single event mapping in text format. Used by printTextFormat().


printXmlFormat

protected void printXmlFormat(PrintStream out)
Prints out the accumulated information in XML format.


printXmlEvent

protected void printXmlEvent(PrintStream out,
                             EventInfo event)


? Copyright 2005-2006, Stripes Development Team.