Class JOCLContentHandler

  • All Implemented Interfaces:
    org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

    public class JOCLContentHandler
    extends org.xml.sax.helpers.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 Objects 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 Strings. 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 Objects. 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 ContentHandlers 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.

    Version:
    $Revision: 883416 $ $Date: 2009-11-23 12:12:14 -0500 (Mon, 23 Nov 2009) $
    Author:
    Rodney Waldhoff
    • Field Summary

      Fields 
      Modifier and Type Field 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.commons.jocl.JOCLContentHandler.ConstructorDetails _cur
      The object I'm currently working on.
      protected org.xml.sax.Locator _locator
      My Locator.
      protected java.util.ArrayList _typeList
      A list of the types (Classes) already created via the parse.
      protected java.util.ArrayList _valueList
      A list of the values (Objects) already created via the parse.
      protected static java.lang.String ATT_CLASS
      The name of the "object" element's "class" attribute.
      protected static java.lang.String ATT_ISNULL
      The name of the "object" element's "isnull" attribute.
      protected static java.lang.String ATT_VALUE
      The name of the "value" attribute.
      protected static java.lang.String ELT_ARRAY
      The name of the "array" element.
      protected static java.lang.String ELT_BOOLEAN
      The name of the "boolean" element.
      protected static java.lang.String ELT_BYTE
      The name of the "byte" element.
      protected static java.lang.String ELT_CHAR
      The name of the "char" element.
      protected static java.lang.String ELT_COLLECTION
      The name of the "collection" element.
      protected static java.lang.String ELT_DOUBLE
      The name of the "double" element.
      protected static java.lang.String ELT_FLOAT
      The name of the "float" element.
      protected static java.lang.String ELT_INT
      The name of the "int" element.
      protected static java.lang.String ELT_LIST
      The name of the "list" element.
      protected static java.lang.String ELT_LONG
      The name of the "long" element.
      protected static java.lang.String ELT_OBJECT
      The name of the "object" element.
      protected static java.lang.String ELT_SHORT
      The name of the "short" element.
      protected static java.lang.String ELT_STRING
      The name of the "string" element.
      static java.lang.String JOCL_NAMESPACE_URI
      The JOCL namespace URI, http://apache.org/xml/xmlns/jakarta/commons/jocl.
      static java.lang.String JOCL_PREFIX
      The default JOCL prefix, jocl:.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void addObject​(java.lang.Class type, java.lang.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​(java.lang.String uri, java.lang.String localName, java.lang.String qname)  
      protected java.lang.String getAttributeValue​(java.lang.String localname, org.xml.sax.Attributes attr)
      protected java.lang.String getAttributeValue​(java.lang.String localname, org.xml.sax.Attributes attr, java.lang.String implied)
      Returns the value of attribute with the given localname within the JOCL namespace from the given set of Attributes.
      java.lang.Class getType​(int i)
      Returns the type of the object at the specified index.
      java.lang.Object[] getTypeArray()
      Returns a shallow copy of my list of types.
      java.lang.Object getValue​(int i)
      Returns the value of the object at the specified index.
      java.lang.Object[] getValueArray()
      Returns a shallow copy of my list of values.
      protected boolean isJoclNamespace​(java.lang.String uri, java.lang.String localname, java.lang.String qname)
      Returns true if the given attributes define an element within the JOCL namespace (according to my current configuration.)
      static void main​(java.lang.String[] args)
      A simple tester method.
      static JOCLContentHandler parse​(java.io.File f)
      Parses a JOCL document from the specified file, using the XMLReader specified by the org.xml.sax.driver property.
      static JOCLContentHandler parse​(java.io.File f, org.xml.sax.XMLReader reader)
      Parses a JOCL document from the specified file, using the XMLReader specified by the org.xml.sax.driver property.
      static JOCLContentHandler parse​(java.io.InputStream in)
      Parses a JOCL document from the specified InputStream, using the XMLReader specified by the org.xml.sax.driver property.
      static JOCLContentHandler parse​(java.io.InputStream in, org.xml.sax.XMLReader reader)
      Parses a JOCL document from the specified InputStream, using the specified XMLReader.
      static JOCLContentHandler parse​(java.io.Reader in)
      Parses a JOCL document from the specified Reader, using the XMLReader specified by the org.xml.sax.driver property.
      static JOCLContentHandler parse​(java.io.Reader in, org.xml.sax.XMLReader reader)
      Parses a JOCL document from the specified Reader, using the specified XMLReader.
      static JOCLContentHandler parse​(org.xml.sax.InputSource in)
      Parses a JOCL document from the specified InputSource, using thethe XMLReader specified by the org.xml.sax.driver property.
      static JOCLContentHandler parse​(org.xml.sax.InputSource in, org.xml.sax.XMLReader reader)
      Parses a JOCL document from the specified InputSource, using the specified XMLReader.
      void setDocumentLocator​(org.xml.sax.Locator locator)  
      int size()
      Returns the number of values and types in my list.
      void startElement​(java.lang.String uri, java.lang.String localName, java.lang.String qname, org.xml.sax.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 java.lang.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 java.lang.String JOCL_PREFIX
        The default JOCL prefix, jocl:.
        See Also:
        Constant Field Values
      • _typeList

        protected java.util.ArrayList _typeList
        A list of the types (Classes) already created via the parse.
      • _valueList

        protected java.util.ArrayList _valueList
        A list of the values (Objects) already created via the parse.
      • _cur

        protected org.apache.commons.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 org.xml.sax.Locator _locator
        My Locator.
      • ELT_OBJECT

        protected static final java.lang.String ELT_OBJECT
        The name of the "object" element.
        See Also:
        Constant Field Values
      • ELT_ARRAY

        protected static final java.lang.String ELT_ARRAY
        The name of the "array" element.
        Since:
        1.2.2
        See Also:
        Constant Field Values
      • ELT_COLLECTION

        protected static final java.lang.String ELT_COLLECTION
        The name of the "collection" element.
        Since:
        1.2.2
        See Also:
        Constant Field Values
      • ELT_LIST

        protected static final java.lang.String ELT_LIST
        The name of the "list" element.
        Since:
        1.2.2
        See Also:
        Constant Field Values
      • ATT_CLASS

        protected static final java.lang.String ATT_CLASS
        The name of the "object" element's "class" attribute.
        See Also:
        Constant Field Values
      • ATT_ISNULL

        protected static final java.lang.String ATT_ISNULL
        The name of the "object" element's "isnull" attribute.
        See Also:
        Constant Field Values
      • ELT_BOOLEAN

        protected static final java.lang.String ELT_BOOLEAN
        The name of the "boolean" element.
        See Also:
        Constant Field Values
      • ELT_BYTE

        protected static final java.lang.String ELT_BYTE
        The name of the "byte" element.
        See Also:
        Constant Field Values
      • ELT_CHAR

        protected static final java.lang.String ELT_CHAR
        The name of the "char" element.
        See Also:
        Constant Field Values
      • ELT_DOUBLE

        protected static final java.lang.String ELT_DOUBLE
        The name of the "double" element.
        See Also:
        Constant Field Values
      • ELT_FLOAT

        protected static final java.lang.String ELT_FLOAT
        The name of the "float" element.
        See Also:
        Constant Field Values
      • ELT_INT

        protected static final java.lang.String ELT_INT
        The name of the "int" element.
        See Also:
        Constant Field Values
      • ELT_LONG

        protected static final java.lang.String ELT_LONG
        The name of the "long" element.
        See Also:
        Constant Field Values
      • ELT_SHORT

        protected static final java.lang.String ELT_SHORT
        The name of the "short" element.
        See Also:
        Constant Field Values
      • ELT_STRING

        protected static final java.lang.String ELT_STRING
        The name of the "string" element.
        See Also:
        Constant Field Values
      • ATT_VALUE

        protected static final java.lang.String ATT_VALUE
        The name of the "value" attribute.
        See Also:
        Constant Field Values
    • Constructor Detail

      • 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​(java.lang.String[] args)
                         throws java.lang.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:
        java.lang.Exception
      • parse

        public static JOCLContentHandler parse​(java.io.File f)
                                        throws org.xml.sax.SAXException,
                                               java.io.FileNotFoundException,
                                               java.io.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:
        org.xml.sax.SAXException
        java.io.FileNotFoundException
        java.io.IOException
      • parse

        public static JOCLContentHandler parse​(java.io.Reader in)
                                        throws org.xml.sax.SAXException,
                                               java.io.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:
        org.xml.sax.SAXException
        java.io.IOException
      • parse

        public static JOCLContentHandler parse​(java.io.InputStream in)
                                        throws org.xml.sax.SAXException,
                                               java.io.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:
        org.xml.sax.SAXException
        java.io.IOException
      • parse

        public static JOCLContentHandler parse​(org.xml.sax.InputSource in)
                                        throws org.xml.sax.SAXException,
                                               java.io.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:
        org.xml.sax.SAXException
        java.io.IOException
      • parse

        public static JOCLContentHandler parse​(java.io.File f,
                                               org.xml.sax.XMLReader reader)
                                        throws org.xml.sax.SAXException,
                                               java.io.FileNotFoundException,
                                               java.io.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:
        org.xml.sax.SAXException
        java.io.FileNotFoundException
        java.io.IOException
      • parse

        public static JOCLContentHandler parse​(java.io.Reader in,
                                               org.xml.sax.XMLReader reader)
                                        throws org.xml.sax.SAXException,
                                               java.io.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:
        org.xml.sax.SAXException
        java.io.IOException
      • parse

        public static JOCLContentHandler parse​(java.io.InputStream in,
                                               org.xml.sax.XMLReader reader)
                                        throws org.xml.sax.SAXException,
                                               java.io.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:
        org.xml.sax.SAXException
        java.io.IOException
      • parse

        public static JOCLContentHandler parse​(org.xml.sax.InputSource in,
                                               org.xml.sax.XMLReader reader)
                                        throws org.xml.sax.SAXException,
                                               java.io.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:
        org.xml.sax.SAXException
        java.io.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 java.lang.Class getType​(int i)
        Returns the type of the object at the specified index.
      • getValue

        public java.lang.Object getValue​(int i)
        Returns the value of the object at the specified index.
      • getValueArray

        public java.lang.Object[] getValueArray()
        Returns a shallow copy of my list of values.
      • getTypeArray

        public java.lang.Object[] getTypeArray()
        Returns a shallow copy of my list of types.
      • startElement

        public void startElement​(java.lang.String uri,
                                 java.lang.String localName,
                                 java.lang.String qname,
                                 org.xml.sax.Attributes attr)
                          throws org.xml.sax.SAXException
        Specified by:
        startElement in interface org.xml.sax.ContentHandler
        Overrides:
        startElement in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException
      • endElement

        public void endElement​(java.lang.String uri,
                               java.lang.String localName,
                               java.lang.String qname)
                        throws org.xml.sax.SAXException
        Specified by:
        endElement in interface org.xml.sax.ContentHandler
        Overrides:
        endElement in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException
      • setDocumentLocator

        public void setDocumentLocator​(org.xml.sax.Locator locator)
        Specified by:
        setDocumentLocator in interface org.xml.sax.ContentHandler
        Overrides:
        setDocumentLocator in class org.xml.sax.helpers.DefaultHandler
      • isJoclNamespace

        protected boolean isJoclNamespace​(java.lang.String uri,
                                          java.lang.String localname,
                                          java.lang.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 java.lang.String getAttributeValue​(java.lang.String localname,
                                                     org.xml.sax.Attributes attr,
                                                     java.lang.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​(java.lang.Class type,
                                 java.lang.Object val)
        Add the specified object either to my type/value list, or as an argument to the object I'm currently constructing.