org.apache.tiles.core.definition.digester

## Class DigesterDefinitionsReader

- java.lang.Object
- - org.apache.tiles.core.definition.digester.DigesterDefinitionsReader

- All Implemented Interfaces:
    DefinitionsReader

      public class DigesterDefinitionsReader
      extends Object
      implements DefinitionsReader

  Reads `Definition` objects from an XML InputStream using Digester.

  This `DefinitionsReader` implementation expects the source to be passed as an `InputStream`. It parses XML data from the source and builds a Map of Definition objects.

  The Digester object can be configured by passing in initialization parameters. Currently the only parameter that is supported is the `validating` parameter. This value is set to `false` by default. To enable DTD validation for XML Definition files, give the init method a parameter with a key of `org.apache.tiles.definition.digester.DigesterDefinitionsReader.PARSER_VALIDATE` and a value of `"true"`.

  The Definition objects are stored internally in a Map. The Map is stored as an instance variable rather than a local variable in the `read` method. This means that instances of this class are not thread-safe and access by multiple threads must be synchronized.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `DigesterDefinitionsReader.AddNestedDefinitionRule` Digester rule to manage assignment of a nested definition in an attribute value.
    `static class` | `DigesterDefinitionsReader.FillAttributeRule` Digester rule to manage attribute filling.
    `static class` | `DigesterDefinitionsReader.FillDefinitionRule` Digester rule to manage definition filling.
    `static class` | `DigesterDefinitionsReader.PutAttributeRule` Digester rule to manage assignment of the attribute to the parent element.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static String` | `DEFINITION_HANDLER_CLASS` The handler to create definitions.
    `protected org.apache.commons.digester.Digester` | `digester` `Digester` object used to read Definition data from the source.
    `protected static String` | `LIST_HANDLER_CLASS` The handler to create list attributes.
    `static String` | `PARSER_VALIDATE_PARAMETER_NAME` Digester validation parameter name.
    `protected static String` | `PUT_ATTRIBUTE_HANDLER_CLASS` The handler to create attributes.
    `protected String[]` | `registrations` The set of public identifiers, and corresponding resource names for the versions of the configuration file DTDs we know about.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DigesterDefinitionsReader()` Creates a new instance of DigesterDefinitionsReader.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDefinition(Definition definition)` Adds a new `Definition` to the internal Map or replaces an existing one.
    `protected String` | `getNextUniqueDefinitionName(Map<String,Definition> definitions)` Create a unique definition name usable to store anonymous definitions.
    `protected String[]` | `getRegistrations()` Returns the registrations for local DTDs.
    `protected void` | `initSyntax(org.apache.commons.digester.Digester digester)` Initialised the syntax for reading XML files containing Tiles definitions.
    `Map<String,Definition>` | `read(Object source)` Reads ``Definition`` objects from a source.
    `void` | `setValidating(boolean validating)` Sets the validation of XML files.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### PARSER_VALIDATE_PARAMETER_NAME

          public static final String PARSER_VALIDATE_PARAMETER_NAME

      Digester validation parameter name.
      See Also:
        Constant Field Values

    - #### DEFINITION_HANDLER_CLASS

          protected static final String DEFINITION_HANDLER_CLASS

      The handler to create definitions.
      Since:
        2.1.0

    - #### PUT_ATTRIBUTE_HANDLER_CLASS

          protected static final String PUT_ATTRIBUTE_HANDLER_CLASS

      The handler to create attributes.
      Since:
        2.1.0

    - #### LIST_HANDLER_CLASS

          protected static final String LIST_HANDLER_CLASS

      The handler to create list attributes.
      Since:
        2.1.0

    - #### digester

          protected org.apache.commons.digester.Digester digester

      `Digester` object used to read Definition data from the source.

    - #### registrations

          protected String[] registrations

      The set of public identifiers, and corresponding resource names for the versions of the configuration file DTDs we know about. There MUST be an even number of Strings in this list!

  - ### Constructor Detail

    - #### DigesterDefinitionsReader

          public DigesterDefinitionsReader()

      Creates a new instance of DigesterDefinitionsReader.

  - ### Method Detail

    - #### setValidating

          public void setValidating(boolean validating)

      Sets the validation of XML files.
      Parameters:
        `validating` - `true` means that XML validation is turned on. `false` otherwise.
      Since:
        3.3.0

    - #### read

          public Map<String,Definition> read(Object source)

      Reads ``Definition`` objects from a source.

      Implementations should publish what type of source object is expected.
      Specified by:
        `read` in interface `DefinitionsReader`
      Parameters:
        `source` - The `InputStream` source from which definitions will be read.
      Returns:
        a Map of `Definition` objects read from the source.
      Throws:
        `DefinitionsFactoryException` - If the source is invalid or an error occurs when reading definitions.

    - #### initSyntax

          protected void initSyntax(org.apache.commons.digester.Digester digester)

      Initialised the syntax for reading XML files containing Tiles definitions.
      Parameters:
        `digester` - The digester to initialize.

    - #### addDefinition

          public void addDefinition(Definition definition)

      Adds a new `Definition` to the internal Map or replaces an existing one.
      Parameters:
        `definition` - The Definition object to be added.

    - #### getRegistrations

          protected String[] getRegistrations()

      Returns the registrations for local DTDs.
      Returns:
        An array containing the locations for registrations of local DTDs.
      Since:
        2.1.0

    - #### getNextUniqueDefinitionName

          protected String getNextUniqueDefinitionName(Map<String,Definition> definitions)

      Create a unique definition name usable to store anonymous definitions.
      Parameters:
        `definitions` - The already created definitions.
      Returns:
        The unique definition name to be used to store the definition.
      Since:
        2.1.0

Copyright © 2000–2023 Apache Software Foundation. All rights reserved.