org.apache.cocoon.generation
Class TraversableGenerator

java.lang.Object
  extended by org.apache.avalon.framework.logger.AbstractLogEnabled
      extended by org.apache.cocoon.xml.AbstractXMLProducer
          extended by org.apache.cocoon.generation.AbstractGenerator
              extended by org.apache.cocoon.generation.ServiceableGenerator
                  extended by org.apache.cocoon.generation.TraversableGenerator
All Implemented Interfaces:
Poolable, Recyclable, Disposable, Component, LogEnabled, Serviceable, CacheableProcessingComponent, Generator, SitemapModelComponent, XMLProducer
Direct Known Subclasses:
TraversableSourceDescriptionGenerator, XPathTraversableGenerator

public class TraversableGenerator
extends ServiceableGenerator
implements CacheableProcessingComponent

Generates an XML source hierarchy listing from a Traversable Source.

The root node of the generated document will normally be a collection node and a collection node can contain zero or more resource or collection nodes. A resource node has no children. Each node will contain the following attributes:

name
the name of the source
lastModified
the time the source was last modified, measured as the number of milliseconds since the epoch (as in java.io.File.lastModified)
size
the source size, in bytes (as in java.io.File.length)
date (optional)
the time the source was last modified in human-readable form

Configuration options:

depth (optional)
Sets how deep TraversableGenerator should delve into the source hierarchy. If set to 1 (the default), only the starting collection's immediate contents will be returned.
sort (optional)
Sort order in which the nodes are returned. Possible values are name, size, time, collection. collection is the same as name, except that the collection entries are listed first. System order is default.
reverse (optional)
Reverse the order of the sort
dateFormat (optional)
Sets the format for the date attribute of each node, as described in java.text.SimpleDateFormat. If unset, the default format for the current locale will be used.
timeZone (optional)
Sets the time zone offset ID for the date attribute, as described in java.util.TimeZone. If unset, the default system time zone will be used.
refreshDelay (optional)
Sets the delay (in seconds) between checks on the source hierarchy for changed content. Defaults to 1 second.

Version:
CVS $Id: TraversableGenerator.html 1304258 2012-03-23 10:09:27Z ilgrosso $
Author:
Pierpaolo Fumagalli (Apache Software Foundation), Conny Krappatsch (SMB GmbH) for Virbus AG, Daniele Madama, Gianugo Rabellino

Field Summary
protected  AttributesImpl attributes
          Convenience object, so we don't need to create an AttributesImpl for every element.
protected  List cacheKeyParList
          The cache key needs to be generated for the configuration of this generator, so storing the parameters for generateKey().
protected static String COL_NODE_NAME
           
protected static String DATE_ATTR_NAME
           
protected  SimpleDateFormat dateFormatter
          The dateFormatter determines into which date format the lastModified time should be converted.
protected  int depth
          The depth parameter determines how deep the TraversableGenerator should delve.
protected  org.apache.regexp.RE excludeRE
          The regular expression for the exclude pattern.
protected  org.apache.regexp.RE includeRE
          The regular expression for the include pattern.
protected  boolean isRequestedSource
          This is only set to true for the requested source specified by the src attribute on the generator's configuration.
protected static String LASTMOD_ATTR_NAME
           
protected static String PREFIX
          The namespace prefix for this namespace.
protected  long refreshDelay
          The delay between checks on updates to the source hierarchy.
protected static String RES_NAME_ATTR_NAME
           
protected static String RESOURCE_NODE_NAME
           
protected  boolean reverse
          The reverse parameter reverses the sort order.
protected  org.apache.regexp.RE rootRE
          The regular expression for the root pattern.
protected static String SIZE_ATTR_NAME
           
protected  String sort
          The sort parameter determines by which attribute the content of one collection should be sorted.
protected static String URI
          The URI of the namespace of this generator.
protected static String URI_ATTR_NAME
           
protected  MultiSourceValidity validity
          The validity that is being built
 
Fields inherited from class org.apache.cocoon.generation.ServiceableGenerator
manager
 
Fields inherited from class org.apache.cocoon.generation.AbstractGenerator
objectModel, parameters, resolver, source
 
Fields inherited from class org.apache.cocoon.xml.AbstractXMLProducer
contentHandler, EMPTY_CONTENT_HANDLER, lexicalHandler, xmlConsumer
 
Fields inherited from interface org.apache.cocoon.generation.Generator
ROLE
 
Constructor Summary
TraversableGenerator()
           
 
Method Summary
protected  void addAncestorPath(TraversableSource source, Stack ancestors)
          Adds recursively the path from the source matched by the root pattern down to the requested source.
protected  void addContent(TraversableSource source)
          Allow subclasses a chance to generate additional elements within collection and resource elements.
protected  void addPath(TraversableSource source, int depth)
          Adds a single node to the generated document.
protected  void endNode(String nodeName)
          Ends the named node.
 void generate()
          Generate XML data.
protected  Stack getAncestors(TraversableSource source)
          Creates a stack containing the ancestors of a traversable source up to specific parent matching the root pattern.
 Serializable getKey()
          Generate the unique key.
 SourceValidity getValidity()
          Gets the source validity, using a deferred validity object.
protected  boolean isExcluded(TraversableSource source)
          Determines if a given source shall be excluded from viewing.
protected  boolean isIncluded(TraversableSource source)
          Determines if a given source shall be visible.
protected  boolean isRoot(TraversableSource source)
          Determines if a given source is the defined root.
 void recycle()
          Recycle resources
protected  void setNodeAttributes(TraversableSource source)
          Sets the attributes for a given source.
 void setup(SourceResolver resolver, Map objectModel, String src, Parameters par)
          Set the request parameters.
protected  void startNode(String nodeName, TraversableSource source)
          Begins a named node and calls setNodeAttributes to set its attributes.
 
Methods inherited from class org.apache.cocoon.generation.ServiceableGenerator
dispose, service
 
Methods inherited from class org.apache.cocoon.xml.AbstractXMLProducer
setConsumer, setContentHandler, setLexicalHandler
 
Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled
enableLogging, getLogger, setupLogger, setupLogger, setupLogger
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.cocoon.xml.XMLProducer
setConsumer
 

Field Detail

URI

protected static final String URI
The URI of the namespace of this generator.

See Also:
Constant Field Values

PREFIX

protected static final String PREFIX
The namespace prefix for this namespace.

See Also:
Constant Field Values

COL_NODE_NAME

protected static final String COL_NODE_NAME
See Also:
Constant Field Values

RESOURCE_NODE_NAME

protected static final String RESOURCE_NODE_NAME
See Also:
Constant Field Values

RES_NAME_ATTR_NAME

protected static final String RES_NAME_ATTR_NAME
See Also:
Constant Field Values

URI_ATTR_NAME

protected static final String URI_ATTR_NAME
See Also:
Constant Field Values

LASTMOD_ATTR_NAME

protected static final String LASTMOD_ATTR_NAME
See Also:
Constant Field Values

DATE_ATTR_NAME

protected static final String DATE_ATTR_NAME
See Also:
Constant Field Values

SIZE_ATTR_NAME

protected static final String SIZE_ATTR_NAME
See Also:
Constant Field Values

validity

protected MultiSourceValidity validity
The validity that is being built


attributes

protected AttributesImpl attributes
Convenience object, so we don't need to create an AttributesImpl for every element.


cacheKeyParList

protected List cacheKeyParList
The cache key needs to be generated for the configuration of this generator, so storing the parameters for generateKey(). Using the member variables after setup() would not work I guess. I don't know a way from the regular expressions back to the pattern or at least a useful string.


depth

protected int depth
The depth parameter determines how deep the TraversableGenerator should delve.


dateFormatter

protected SimpleDateFormat dateFormatter
The dateFormatter determines into which date format the lastModified time should be converted. FIXME: SimpleDateFormat is not supported by all locales!


refreshDelay

protected long refreshDelay
The delay between checks on updates to the source hierarchy.


sort

protected String sort
The sort parameter determines by which attribute the content of one collection should be sorted. Possible values are "name", "size", "time" and "collection", where "collection" is the same as "name", except that collection entries are listed first.


reverse

protected boolean reverse
The reverse parameter reverses the sort order. false is default.


rootRE

protected org.apache.regexp.RE rootRE
The regular expression for the root pattern.


includeRE

protected org.apache.regexp.RE includeRE
The regular expression for the include pattern.


excludeRE

protected org.apache.regexp.RE excludeRE
The regular expression for the exclude pattern.


isRequestedSource

protected boolean isRequestedSource
This is only set to true for the requested source specified by the src attribute on the generator's configuration.

Constructor Detail

TraversableGenerator

public TraversableGenerator()
Method Detail

setup

public void setup(SourceResolver resolver,
                  Map objectModel,
                  String src,
                  Parameters par)
           throws ProcessingException,
                  SAXException,
                  IOException
Set the request parameters. Must be called before the generate method.

Specified by:
setup in interface SitemapModelComponent
Overrides:
setup in class AbstractGenerator
Parameters:
resolver - the SourceResolver object
objectModel - a Map containing model object
src - the Traversable Source to be XMLized specified as src attribute on <map:generate/>
par - configuration parameters
Throws:
ProcessingException
SAXException
IOException

getKey

public Serializable getKey()
Description copied from interface: CacheableProcessingComponent
Generate the unique key. This key must be unique inside the space of this component. This method must be invoked before the getValidity() method.

Specified by:
getKey in interface CacheableProcessingComponent
Returns:
The generated key or null if the component is currently not cacheable.

getValidity

public SourceValidity getValidity()
Gets the source validity, using a deferred validity object. The validity is initially empty since the resources that define it are not known before generation has occured. So the returned object is kept by the generator and filled with each of the resources that is traversed.

Specified by:
getValidity in interface CacheableProcessingComponent
Returns:
The generated validity object or null if the component is currently not cacheable.
See Also:
MultiSourceValidity

generate

public void generate()
              throws SAXException,
                     ProcessingException
Generate XML data.

Specified by:
generate in interface Generator
Throws:
SAXException - if an error occurs while outputting the document
ProcessingException - if something went wrong while traversing the source hierarchy

getAncestors

protected Stack getAncestors(TraversableSource source)
                      throws IOException
Creates a stack containing the ancestors of a traversable source up to specific parent matching the root pattern.

Parameters:
source - the traversable source whose ancestors shall be retrieved
Returns:
a Stack containing the ancestors.
Throws:
IOException

addAncestorPath

protected void addAncestorPath(TraversableSource source,
                               Stack ancestors)
                        throws SAXException,
                               ProcessingException
Adds recursively the path from the source matched by the root pattern down to the requested source.

Parameters:
source - the requested source.
ancestors - the stack of the ancestors.
Throws:
SAXException
ProcessingException

addPath

protected void addPath(TraversableSource source,
                       int depth)
                throws SAXException,
                       ProcessingException
Adds a single node to the generated document. If the path is a collection and depth is greater than zero, then recursive calls are made to add nodes for the collection's children.

Parameters:
source - the resource/collection to process
depth - how deep to scan the collection hierarchy
Throws:
SAXException - if an error occurs while constructing nodes
ProcessingException - if a problem occurs with the source

addContent

protected void addContent(TraversableSource source)
                   throws SAXException,
                          ProcessingException
Allow subclasses a chance to generate additional elements within collection and resource elements.

Parameters:
source - the source to generate additional data for.
Throws:
SAXException
ProcessingException

startNode

protected void startNode(String nodeName,
                         TraversableSource source)
                  throws SAXException,
                         ProcessingException
Begins a named node and calls setNodeAttributes to set its attributes.

Parameters:
nodeName - the name of the new node
source - the source a node with its attributes is added for
Throws:
SAXException - if an error occurs while creating the node
ProcessingException

setNodeAttributes

protected void setNodeAttributes(TraversableSource source)
                          throws SAXException,
                                 ProcessingException
Sets the attributes for a given source. For example attributes for the name, the size and the last modification date of the source are added.

Parameters:
source - the source attributes are added for
Throws:
SAXException
ProcessingException

endNode

protected void endNode(String nodeName)
                throws SAXException
Ends the named node.

Parameters:
nodeName - the name of the new node
Throws:
SAXException - if an error occurs while closing the node

isRoot

protected boolean isRoot(TraversableSource source)
Determines if a given source is the defined root.

Parameters:
source - the source to check
Returns:
true if the source is the root or the root pattern is not set, false otherwise.

isIncluded

protected boolean isIncluded(TraversableSource source)
Determines if a given source shall be visible.

Parameters:
source - the source to check
Returns:
true if the source shall be visible or the include Pattern is not set, false otherwise.

isExcluded

protected boolean isExcluded(TraversableSource source)
Determines if a given source shall be excluded from viewing.

Parameters:
source - the source to check
Returns:
false if the given source shall not be excluded or the exclude Pattern is not set, true otherwise.

recycle

public void recycle()
Recycle resources

Specified by:
recycle in interface Recyclable
Overrides:
recycle in class AbstractGenerator


Copyright © 1999-2010 The Apache Software Foundation. All Rights Reserved.