JOCLContentHandler (Apache Tomcat 7.0.104 API Documentation)

org.apache.tomcat.dbcp.jocl

## Class JOCLContentHandler

- java.lang.Object
- - org.xml.sax.helpers.DefaultHandler
  - - org.apache.tomcat.dbcp.jocl.JOCLContentHandler

- All Implemented Interfaces:
    ContentHandler, DTDHandler, EntityResolver, ErrorHandler

      public class JOCLContentHandler
      extends DefaultHandler

  A `ContentHandler` for the Java Object Configuration Language.

  JOCL provides an XML syntax for constructing arbitrary Java `Object` instances. It does not define a full XML document type (there's no root element), but rather an XML fragment describing the `Objects` to be constructed.

  In a JOCL fragment, one may define a series of objects using the `object` element. A trivial example is:

       <object class="java.util.Date"/>

  which constructs an instance of `java.util.Date` using the no-argument constructor.

  After a "root-level" `<object>` element has been processed (that is, once `endElement(java.lang.String,java.lang.String,java.lang.String)` has been invoked by the `XMLReader`), it will be appended to a list of `Object`s maintained by the `JOCLContentHandler`.

  (See `size()`, `clear()`, `clear(int)`, `getType(int)`, `getValue(int)`, `getTypeArray()`, and `getValueArray()`.)

  You can list multiple `object` elements in a fragment. For example, after processing the JOCL fragment:

       <object class="java.util.Date"/>
       <object class="java.util.Date"/>

  The `getTypeArray()` method will return an array composed of two instances of `java.util.Date`. The sequence of `Objects` in the array will correspond to the sequence of `<object>` elements in the JOCL fragment.

  As we've seen, when used with no child-elements, the `<object>` tag will cause the no-argument constructor of the specified class to be invoked. It is also possible to nest `<object>` tags to provide arguments for the constructor. For example, the fragment:

       <object class="mypackage.Foo">
         <object class="mypackage.Bar"/>
       </object>

  will add an instance of `mypackage.Foo` to the object list, constructed via `new mypackage.Foo(new mypackage.Bar())`.

  There is a special syntax available creating primitive values and arguments, as well as for constructing `String`s. Some examples:

       <byte value="3"/>
       <boolean value="false"/>
       <char value="c"/>
       <double value="3.14159"/>
       <float value="3.14"/>
       <int value="17"/>
       <long value="1700000"/>
       <short value="1"/>
       <string value="The quick brown fox..."/>

  When invoked at the "root" level (that is, with no `<object>` parent), this will cause the corresponding "object wrapper" to be added to the list of `Object`s. The `type` for these objects will reflect the proper primitive type, however. When invoked with an `<object>` parent, these will be treated as primitive arguments to the specified `Object`'s constructor. For example, while:

       <int value="5"/>
       <int value="26"/>
       <int value="100"/>

  results in three `Integer` instances being added to the list of values, with types corresponding to `Integer`, the fragment:

       <int value="5"/>
       <int value="26"/>
       <int value="100"/>

  results in three `Integer` instances being added to the list of values, with types corresponding to `Integer.TYPE`.

  Hence if you want to invoke the `mypackage.Foo(java.lang.Integer,java.lang.Integer,java.lang.Integer)` constructor, use:

       <object class="mypackage.Foo"/>
         <object class="java.lang.Integer"><int value="5"/></object>
         <object class="java.lang.Integer"><int value="26"/></object>
         <object class="java.lang.Integer"><int value="100"/></object>
       </object>

  If you want to invoke the `mypackage.Foo(int,int,int)` constructor, use:

       <object class="mypackage.Foo"/>
         <int value="5"/>
         <int value="26"/>
         <int value="100"/>
       </object>

  If you'd like to creat a `null` object, use:

       <object class="mypackage.Bar" null="true"/>

  Here's a simple but complete example:

       <?xml version="1.0"?>
       <arbitrary-root xmlns="http://apache.org/xml/xmlns/jakarta/commons/jocl">
         <string value="Hello World!"/>
         <string/>
         <boolean/>
         <boolean value="true"/>
         <byte value="1"/>
         <short value="1"/>
         <int value="1"/>
         <long value="1"/>
         <float value="1.0"/>
         <double value="1.0"/>
         <object class="java.util.Date"/>
         <object class="java.util.Date">
          <int value="1"/>
          <int value="1"/>
          <int value="1"/>
         </object>
       </arbitrary-root>

  Formally, a DTD for the JOCL grammar is as follows:

       <!ELEMENT object (object|array|collection|list|byte|boolean|char|double|float|int|long|short|string)*>
       <!ATTLIST object
         class CDATA #REQUIRED
         null (true|false) "false">

       <!ELEMENT byte EMPTY>
       <!ATTLIST byte value CDATA #REQUIRED>

       <!ELEMENT boolean EMPTY>
       <!ATTLIST boolean value (true|false) #REQUIRED>

       <!ELEMENT char EMPTY>
       <!ATTLIST char value CDATA #REQUIRED>

       <!ELEMENT double EMPTY>
       <!ATTLIST double value CDATA #REQUIRED>

       <!ELEMENT float EMPTY>
       <!ATTLIST float value CDATA #REQUIRED>

       <!ELEMENT int EMPTY>
       <!ATTLIST int value CDATA #REQUIRED>

       <!ELEMENT long EMPTY>
       <!ATTLIST long value CDATA #REQUIRED>

       <!ELEMENT short EMPTY>
       <!ATTLIST short value CDATA #REQUIRED>

       <!ELEMENT string EMPTY>
       <!ATTLIST string value CDATA #REQUIRED>

  This class can also be used as a base class for `ContentHandler`s that include JOCL as part of their grammar. Simply extend this class, and override the `startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)`, `DefaultHandler.characters(char[], int, int)`, and `endElement(java.lang.String, java.lang.String, java.lang.String)` methods to handle your tags, and invoke the method of the parent class (i.e., `super.XXX` for elements and data that you don't handle.

  A number of static methods are available for simply reading a list of objects from a `InputStream`, `Reader` or `InputSource`.

  Note that this class is not synchronized.

  Author:
    Rodney Waldhoff

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `_acceptEmptyNamespaceForAttributes` When `true`, I will treat attributes with an empty namespace URI as part of the JOCL namespace.
    `protected boolean` | `_acceptEmptyNamespaceForElements` When `true`, I will treat elements with an empty namespace URI as part of the JOCL namespace.
    `protected boolean` | `_acceptJoclPrefixForAttributes` When `true`, I will treat attributes with the `JOCL_PREFIX` but no namespace URI as being mapped to the jocl namespace.
    `protected boolean` | `_acceptJoclPrefixForElements` When `true`, I will treat elements with the `JOCL_PREFIX` but no namespace URI as being mapped to the jocl namespace.
    `protected org.apache.tomcat.dbcp.jocl.JOCLContentHandler.ConstructorDetails` | `_cur` The object I'm currently working on.
    `protected Locator` | `_locator` My `Locator`.
    `protected ArrayList<Class<?>>` | `_typeList` A list of the types (`Class`es) already created via the parse.
    `protected ArrayList<Object>` | `_valueList` A list of the values (`Object`s) already created via the parse.
    `protected static String` | `ATT_CLASS` The name of the "object" element's "class" attribute.
    `protected static String` | `ATT_ISNULL` The name of the "object" element's "isnull" attribute.
    `protected static String` | `ATT_VALUE` The name of the "value" attribute.
    `protected static String` | `ELT_ARRAY` The name of the "array" element.
    `protected static String` | `ELT_BOOLEAN` The name of the "boolean" element.
    `protected static String` | `ELT_BYTE` The name of the "byte" element.
    `protected static String` | `ELT_CHAR` The name of the "char" element.
    `protected static String` | `ELT_COLLECTION` The name of the "collection" element.
    `protected static String` | `ELT_DOUBLE` The name of the "double" element.
    `protected static String` | `ELT_FLOAT` The name of the "float" element.
    `protected static String` | `ELT_INT` The name of the "int" element.
    `protected static String` | `ELT_LIST` The name of the "list" element.
    `protected static String` | `ELT_LONG` The name of the "long" element.
    `protected static String` | `ELT_OBJECT` The name of the "object" element.
    `protected static String` | `ELT_SHORT` The name of the "short" element.
    `protected static String` | `ELT_STRING` The name of the "string" element.
    `static String` | `JOCL_NAMESPACE_URI` The JOCL namespace URI, `http://apache.org/xml/xmlns/jakarta/commons/jocl`.
    `static String` | `JOCL_PREFIX` The default JOCL prefix, `jocl:`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JOCLContentHandler()` Equivalent to `JOCLContentHandler(true,true,true,true)`.
    `JOCLContentHandler(boolean emptyEltNS, boolean joclEltPrefix, boolean emptyAttrNS, boolean joclAttrPrefix)` Construct a JOCLContentHandler.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addObject(Class<?> type, Object val)` Add the specified object either to my type/value list, or as an argument to the object I'm currently constructing.
    `void` | `clear()` Clears all the values and types in my list.
    `void` | `clear(int i)` Removes the value/type pair at the specified index.
    `void` | `endElement(String uri, String localName, String qname)`
    `protected String` | `getAttributeValue(String localname, Attributes attr)` Equivalent to ``getAttributeValue(localname,attr,null)``.
    `protected String` | `getAttributeValue(String localname, Attributes attr, String implied)` Returns the value of attribute with the given `localname` within the JOCL namespace from the given set of `Attributes`.
    `Class<?>` | `getType(int i)` Returns the type of the object at the specified index.
    `Object[]` | `getTypeArray()` Returns a shallow copy of my list of types.
    `Object` | `getValue(int i)` Returns the value of the object at the specified index.
    `Object[]` | `getValueArray()` Returns a shallow copy of my list of values.
    `protected boolean` | `isJoclNamespace(String uri, String localname, String qname)` Returns `true` if the given attributes define an element within the JOCL namespace (according to my current configuration.)
    `static void` | `main(String[] args)` A simple tester method.
    `static JOCLContentHandler` | `parse(File f)` Parses a JOCL document from the specified file, using the `XMLReader` specified by the `org.xml.sax.driver` property.
    `static JOCLContentHandler` | `parse(File f, XMLReader reader)` Parses a JOCL document from the specified file, using the `XMLReader` specified by the `org.xml.sax.driver` property.
    `static JOCLContentHandler` | `parse(InputSource in)` Parses a JOCL document from the specified `InputSource`, using thethe `XMLReader` specified by the `org.xml.sax.driver` property.
    `static JOCLContentHandler` | `parse(InputSource in, XMLReader reader)` Parses a JOCL document from the specified `InputSource`, using the specified `XMLReader`.
    `static JOCLContentHandler` | `parse(InputStream in)` Parses a JOCL document from the specified `InputStream`, using the `XMLReader` specified by the `org.xml.sax.driver` property.
    `static JOCLContentHandler` | `parse(InputStream in, XMLReader reader)` Parses a JOCL document from the specified `InputStream`, using the specified `XMLReader`.
    `static JOCLContentHandler` | `parse(Reader in)` Parses a JOCL document from the specified `Reader`, using the `XMLReader` specified by the `org.xml.sax.driver` property.
    `static JOCLContentHandler` | `parse(Reader in, XMLReader reader)` Parses a JOCL document from the specified `Reader`, using the specified `XMLReader`.
    `void` | `setDocumentLocator(Locator locator)`
    `int` | `size()` Returns the number of values and types in my list.
    `void` | `startElement(String uri, String localName, String qname, Attributes attr)`

    - ### Methods inherited from class org.xml.sax.helpers.DefaultHandler

      `characters, endDocument, endPrefixMapping, error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, skippedEntity, startDocument, startPrefixMapping, unparsedEntityDecl, warning`

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

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

- - ### Field Detail

    - #### JOCL_NAMESPACE_URI

          public static final String JOCL_NAMESPACE_URI

      The JOCL namespace URI, `http://apache.org/xml/xmlns/jakarta/commons/jocl`.
      See Also:
        Constant Field Values

    - #### JOCL_PREFIX

          public static final String JOCL_PREFIX

      The default JOCL prefix, `jocl:`.
      See Also:
        Constant Field Values

    - #### _typeList

          protected ArrayList<Class<?>> _typeList

      A list of the types (`Class`es) already created via the parse.

    - #### _valueList

          protected ArrayList<Object> _valueList

      A list of the values (`Object`s) already created via the parse.

    - #### _cur

          protected org.apache.tomcat.dbcp.jocl.JOCLContentHandler.ConstructorDetails _cur

      The object I'm currently working on.

    - #### _acceptEmptyNamespaceForElements

          protected boolean _acceptEmptyNamespaceForElements

      When `true`, I will treat elements with an empty namespace URI as part of the JOCL namespace.
      See Also:
        `JOCL_NAMESPACE_URI`

    - #### _acceptJoclPrefixForElements

          protected boolean _acceptJoclPrefixForElements

      When `true`, I will treat elements with the `JOCL_PREFIX` but no namespace URI as being mapped to the jocl namespace.
      See Also:
        `JOCL_PREFIX`, `JOCL_NAMESPACE_URI`

    - #### _acceptEmptyNamespaceForAttributes

          protected boolean _acceptEmptyNamespaceForAttributes

      When `true`, I will treat attributes with an empty namespace URI as part of the JOCL namespace.
      See Also:
        `JOCL_NAMESPACE_URI`

    - #### _acceptJoclPrefixForAttributes

          protected boolean _acceptJoclPrefixForAttributes

      When `true`, I will treat attributes with the `JOCL_PREFIX` but no namespace URI as being mapped to the jocl namespace.
      See Also:
        `JOCL_PREFIX`, `JOCL_NAMESPACE_URI`

    - #### _locator

          protected Locator _locator

      My `Locator`.

    - #### ELT_OBJECT

          protected static final String ELT_OBJECT

      The name of the "object" element.
      See Also:
        Constant Field Values

    - #### ELT_ARRAY

          protected static final String ELT_ARRAY

      The name of the "array" element.
      Since:
        1.2.2
      See Also:
        Constant Field Values

    - #### ELT_COLLECTION

          protected static final String ELT_COLLECTION

      The name of the "collection" element.
      Since:
        1.2.2
      See Also:
        Constant Field Values

    - #### ELT_LIST

          protected static final String ELT_LIST

      The name of the "list" element.
      Since:
        1.2.2
      See Also:
        Constant Field Values

    - #### ATT_CLASS

          protected static final String ATT_CLASS

      The name of the "object" element's "class" attribute.
      See Also:
        Constant Field Values

    - #### ATT_ISNULL

          protected static final String ATT_ISNULL

      The name of the "object" element's "isnull" attribute.
      See Also:
        Constant Field Values

    - #### ELT_BOOLEAN

          protected static final String ELT_BOOLEAN

      The name of the "boolean" element.
      See Also:
        Constant Field Values

    - #### ELT_BYTE

          protected static final String ELT_BYTE

      The name of the "byte" element.
      See Also:
        Constant Field Values

    - #### ELT_CHAR

          protected static final String ELT_CHAR

      The name of the "char" element.
      See Also:
        Constant Field Values

    - #### ELT_DOUBLE

          protected static final String ELT_DOUBLE

      The name of the "double" element.
      See Also:
        Constant Field Values

    - #### ELT_FLOAT

          protected static final String ELT_FLOAT

      The name of the "float" element.
      See Also:
        Constant Field Values

    - #### ELT_INT

          protected static final String ELT_INT

      The name of the "int" element.
      See Also:
        Constant Field Values

    - #### ELT_LONG

          protected static final String ELT_LONG

      The name of the "long" element.
      See Also:
        Constant Field Values

    - #### ELT_SHORT

          protected static final String ELT_SHORT

      The name of the "short" element.
      See Also:
        Constant Field Values

    - #### ELT_STRING

          protected static final String ELT_STRING

      The name of the "string" element.
      See Also:
        Constant Field Values

    - #### ATT_VALUE

          protected static final String ATT_VALUE

      The name of the "value" attribute.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### JOCLContentHandler

          public JOCLContentHandler()

      Equivalent to `JOCLContentHandler(true,true,true,true)`.

    - #### JOCLContentHandler

          public JOCLContentHandler(boolean emptyEltNS,
                            boolean joclEltPrefix,
                            boolean emptyAttrNS,
                            boolean joclAttrPrefix)

      Construct a JOCLContentHandler.
      Parameters:
        `emptyEltNS` - when `true` I should assume any element with an empty namespace is within the JOCL namespace
        `joclEltPrefix` - when `true` I should assume any element who's prefix is `jocl:` and who's namespace is empty is within the JOCL namespace
        `emptyAttrNS` - when `true` I should assume any attribute with an empty namespace is within the JOCL namespace
        `joclAttrPrefix` - when `true` I should assume any attribute who's prefix is `jocl:` and who's namespace is empty is within the JOCL namespace

  - ### Method Detail

    - #### main

          public static void main(String[] args)
                           throws Exception

      A simple tester method. Reads a JOCL document from standard in and prints a list of the objects created to standard out. (Use the `org.xml.sax.driver` system property to specify an `XMLReader`.
      Throws:
        `Exception`

    - #### parse

          public static JOCLContentHandler parse(File f)
                                          throws SAXException,
                                                 FileNotFoundException,
                                                 IOException

      Parses a JOCL document from the specified file, using the `XMLReader` specified by the `org.xml.sax.driver` property. The returned `JOCLContentHandler` will contain the list of objects described by the file.
      Parameters:
        `f` - a `File` containing the JOCL document
      Returns:
        a `JOCLContentHandler` containing the list of objects described by the JOCL document
      Throws:
        `SAXException`
        `FileNotFoundException`
        `IOException`

    - #### parse

          public static JOCLContentHandler parse(Reader in)
                                          throws SAXException,
                                                 IOException

      Parses a JOCL document from the specified `Reader`, using the `XMLReader` specified by the `org.xml.sax.driver` property. The returned `JOCLContentHandler` will contain the list of objects described by the file.
      Parameters:
        `in` - a `Reader` containing the JOCL document
      Returns:
        a `JOCLContentHandler` containing the list of objects described by the JOCL document
      Throws:
        `SAXException`
        `IOException`

    - #### parse

          public static JOCLContentHandler parse(InputStream in)
                                          throws SAXException,
                                                 IOException

      Parses a JOCL document from the specified `InputStream`, using the `XMLReader` specified by the `org.xml.sax.driver` property. The returned `JOCLContentHandler` will contain the list of objects described by the file.
      Parameters:
        `in` - a `InputStream` containing the JOCL document
      Returns:
        a `JOCLContentHandler` containing the list of objects described by the JOCL document
      Throws:
        `SAXException`
        `IOException`

    - #### parse

          public static JOCLContentHandler parse(InputSource in)
                                          throws SAXException,
                                                 IOException

      Parses a JOCL document from the specified `InputSource`, using thethe `XMLReader` specified by the `org.xml.sax.driver` property. The returned `JOCLContentHandler` will contain the list of objects described by the file.
      Parameters:
        `in` - a `InputSource` containing the JOCL document
      Returns:
        a `JOCLContentHandler` containing the list of objects described by the JOCL document
      Throws:
        `SAXException`
        `IOException`

    - #### parse

          public static JOCLContentHandler parse(File f,
                                 XMLReader reader)
                                          throws SAXException,
                                                 FileNotFoundException,
                                                 IOException

      Parses a JOCL document from the specified file, using the `XMLReader` specified by the `org.xml.sax.driver` property. The returned `JOCLContentHandler` will contain the list of objects described by the file.
      Parameters:
        `f` - a `File` containing the JOCL document
        `reader` - the `XMLReader` to use to parse the file
      Returns:
        a `JOCLContentHandler` containing the list of objects described by the JOCL document
      Throws:
        `SAXException`
        `FileNotFoundException`
        `IOException`

    - #### parse

          public static JOCLContentHandler parse(Reader in,
                                 XMLReader reader)
                                          throws SAXException,
                                                 IOException

      Parses a JOCL document from the specified `Reader`, using the specified `XMLReader`. The returned `JOCLContentHandler` will contain the list of objects described by the file.
      Parameters:
        `in` - a `Reader` containing the JOCL document
        `reader` - the `XMLReader` to use to parse the document
      Returns:
        a `JOCLContentHandler` containing the list of objects described by the JOCL document
      Throws:
        `SAXException`
        `IOException`

    - #### parse

          public static JOCLContentHandler parse(InputStream in,
                                 XMLReader reader)
                                          throws SAXException,
                                                 IOException

      Parses a JOCL document from the specified `InputStream`, using the specified `XMLReader`. The returned `JOCLContentHandler` will contain the list of objects described by the file.
      Parameters:
        `in` - a `InputStream` containing the JOCL document
        `reader` - the `XMLReader` to use to parse the document
      Returns:
        a `JOCLContentHandler` containing the list of objects described by the JOCL document
      Throws:
        `SAXException`
        `IOException`

    - #### parse

          public static JOCLContentHandler parse(InputSource in,
                                 XMLReader reader)
                                          throws SAXException,
                                                 IOException

      Parses a JOCL document from the specified `InputSource`, using the specified `XMLReader`. The returned `JOCLContentHandler` will contain the list of objects described by the file.
      Parameters:
        `in` - a `InputSource` containing the JOCL document
        `reader` - the `XMLReader` to use to parse the document
      Returns:
        a `JOCLContentHandler` containing the list of objects described by the JOCL document
      Throws:
        `SAXException`
        `IOException`

    - #### size

          public int size()

      Returns the number of values and types in my list.
      Returns:
        the number of values and types in my list.

    - #### clear

          public void clear()

      Clears all the values and types in my list.

    - #### clear

          public void clear(int i)

      Removes the value/type pair at the specified index.

    - #### getType

          public Class<?> getType(int i)

      Returns the type of the object at the specified index.

    - #### getValue

          public Object getValue(int i)

      Returns the value of the object at the specified index.

    - #### getValueArray

          public Object[] getValueArray()

      Returns a shallow copy of my list of values.

    - #### getTypeArray

          public Object[] getTypeArray()

      Returns a shallow copy of my list of types.

    - #### startElement

          public void startElement(String uri,
                          String localName,
                          String qname,
                          Attributes attr)
                            throws SAXException

      Specified by:
        `startElement` in interface `ContentHandler`
      Overrides:
        `startElement` in class `DefaultHandler`
      Throws:
        `SAXException`

    - #### endElement

          public void endElement(String uri,
                        String localName,
                        String qname)
                          throws SAXException

      Specified by:
        `endElement` in interface `ContentHandler`
      Overrides:
        `endElement` in class `DefaultHandler`
      Throws:
        `SAXException`

    - #### setDocumentLocator

          public void setDocumentLocator(Locator locator)

      Specified by:
        `setDocumentLocator` in interface `ContentHandler`
      Overrides:
        `setDocumentLocator` in class `DefaultHandler`

    - #### isJoclNamespace

          protected boolean isJoclNamespace(String uri,
                                String localname,
                                String qname)

      Returns `true` if the given attributes define an element within the JOCL namespace (according to my current configuration.)
      See Also:
        `_acceptEmptyNamespaceForElements`, `_acceptJoclPrefixForElements`

    - #### getAttributeValue

          protected String getAttributeValue(String localname,
                                 Attributes attr)

      Equivalent to ``getAttributeValue(localname,attr,null)``.

    - #### getAttributeValue

          protected String getAttributeValue(String localname,
                                 Attributes attr,
                                 String implied)

      Returns the value of attribute with the given `localname` within the JOCL namespace from the given set of `Attributes`. If no such attribute can be found, returns `implied`.
      Parameters:
        `localname` - the unqualified name of the attribute to look for
        `attr` - the Attributes in which to find the value
        `implied` - the default value for the attribute
      Returns:
        the value of attribute with the given `localname` within the JOCL namespace from the given set of `Attributes`. If no such attribute can be found, returns `implied`.

    - #### addObject

          protected void addObject(Class<?> type,
                       Object val)

      Add the specified object either to my type/value list, or as an argument to the object I'm currently constructing.

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.