apache > cocoon

- Home

# Directory Generator

The root node of the generated document will normally be a `directory` node. A directory node can contain zero or more `file` or `directory` nodes. A file node has no children. All generated elements have the namespace `http://apache.org/cocoon/directory/2.0`.

Each node will contain the following attributes:

- `name`: the name of the file or directory.
- `lastModified`: the time the file was last modified, measured as the number of milliseconds since the epoch (as in `java.io.File.lastModified`).
- `date` (optional): the time the file was last modified in human-readable form.
- `size`: the file size (or 0 for directories).

Additionally the node for the requested directory has the attributes:

- `requested`: with the value set to `true`.
- `sort`: the sort order of the `file` and `directory` nodes.
- `reverse`: determines whether reverse sort was chosen.

This node needs not to be the root node as you will see later.

## Configuration

      <map:generate type="directory" src="the/requested/directory">
        <map:parameter name="depth" value="2"/>
      </map:generate>

The `src` attribute on the `<map:generate/>` must be set to the directory the XML listing should be created of. This is the requested directory.

The following parameter are all optional and can be specified in the pipeline for the generate command (as seen in the example above for the parameter `depth`):

- depth: Sets how deep the generator should delve into the directory structure. If set to 1 (the default), only the starting directory's immediate contents will be returned.
- dateFormat: 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.
- refreshDelay: Sets the delay (in seconds, default is 1) between checks for updates on the file system. So this option influences the caching of the directory listing.
- sort: Sets the sort order in which the `file` and `directory` nodes are returned. Possible values are `name`, `size`, `lastmodified` and `directory` (where `directory` is the same as `name`, except that directory entries are listed first). The default sort order is `name`.
- reverse: Reverses the sort order, defaults to `false`.
- root: The root pattern. From the requested director upwards a directory is searched using this pattern, that is added as root node to the document. The path from this root node down to the requested directory will also be in the output. If no root pattern is specified or no ancestor of the requested directory matches this pattern, the requested directory will be the root in the output document.
  The pattern is a regular expression as described in the API docs of the Apache RegExp project.
- include: The include pattern. Specifies the directories and files that should be included. Also a regular expression.
- exclude: The exclude pattern. Specifies the directories and files that should be excluded. Also a regular expression.

## DTD

XML generated by Directory Generator uses namespace `http://apache.org/cocoon/status/2.0`. The DTD of XML generated by Directory Generator:

      <!ELEMENT directory (directory|file)*>
      <!ATTLIST directory
        name         CDATA #REQUIRED
        lastModified CDATA #REQUIRED
        date         CDATA #REQUIRED
        size         CDATA #REQUIRED
        requested    CDATA #IMPLIED
        sort         CDATA #IMPLIED
        reverse      CDATA #IMPLIED>

      <!ELEMENT file #EMPTY>
      <!ATTLIST file
        name         CDATA #REQUIRED
        lastModified CDATA #REQUIRED
        date         CDATA #REQUIRED
        size         CDATA #REQUIRED>

## Example

The current Directory Generator may generate following xml:

    <dir:directory xmlns:dir="http://apache.org/cocoon/directory/2.0"
        name="stylesheets" lastModified="1056668768203" date="27.06.03 01:06" size="0"
        requested="true" sort="name" reverse="false">
      <dir:directory name="sites" lastModified="1056668768203" date="27.06.03 01:06" size="0"/>
      <dir:file name="dynamic-page2html.xsl" lastModified="1056668768203" date="27.06.03 01:06" size="4321"/>
      <dir:file name="simple-xml2html.xslt" lastModified="1056668768203" date="27.06.03 01:06" size="1234"/>
    </dir:directory>

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).