org.apache.commons.jocl

Class JOCLContentHandler

public class JOCLContentHandler extends DefaultHandler

A org.xml.sax.ContentHandler for the Java Object Configuration Language.

JOCL provides an XML syntax for constructing arbitrary Java java.lang.Object instances. It does not define a full XML document type (there's no root element), but rather an XML fragment describing the java.lang.Object 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 JOCLContentHandler has been invoked by the XMLReader), it will be appended to a list of Objects maintained by the JOCLContentHandler.

(See JOCLContentHandler, JOCLContentHandler, JOCLContentHandler, JOCLContentHandler, JOCLContentHandler, JOCLContentHandler, and JOCLContentHandler.)

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 JOCLContentHandler method will return an composed of two instances of java.util.Date. The sequence of java.lang.Object 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 primative values and arguments, as well as for constructing java.lang.String 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 java.lang.Object Objects. The type for these objects will reflect the proper primative type, however. When invoked with an <object> parent, these will be treated as primitive arguments to the specified java.lang.Object Object's constructor. For example, while:

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

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

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

results in three java.lang.Integer instances being added to the list of values, with types corresponding to java.lang.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|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 org.xml.sax.ContentHandlers that include JOCL as part of their grammar. Simply extend this class, and override the JOCLContentHandler, JOCLContentHandler, and JOCLContentHandler 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: 491655 $ $Date: 2007-01-01 15:05:30 -0700 (Mon, 01 Jan 2007) $

Author: Rodney Waldhoff

Field Summary
static StringJOCL_NAMESPACE_URI
The JOCL namespace URI, http://apache.org/xml/xmlns/jakarta/commons/jocl.
static StringJOCL_PREFIX
The default JOCL prefix, jocl:.
Constructor Summary
JOCLContentHandler()
JOCLContentHandler(boolean emptyEltNS, boolean joclEltPrefix, boolean emptyAttrNS, boolean joclAttrPrefix)
Construct a JOCLContentHandler.
Method Summary
voidclear()
Clears all the values and types in my list.
voidclear(int i)
Removes the value/type pair at the specified index.
voidendElement(String uri, String localName, String qname)
ClassgetType(int i)
Returns the type of the object at the specified index.
Object[]getTypeArray()
Returns a shallow copy of my list of types.
ObjectgetValue(int i)
Returns the value of the object at the specified index.
Object[]getValueArray()
Returns a shallow copy of my list of values.
static voidmain(String[] args)
A simple tester method.
static JOCLContentHandlerparse(File f)
Parses a JOCL document from the specified file, using the XMLReader specified by the org.xml.sax.driver property.
static JOCLContentHandlerparse(Reader in)
Parses a JOCL document from the specified Reader, using the XMLReader specified by the org.xml.sax.driver property.
static JOCLContentHandlerparse(InputStream in)
Parses a JOCL document from the specified InputStream, using the XMLReader specified by the org.xml.sax.driver property.
static JOCLContentHandlerparse(InputSource in)
Parses a JOCL document from the specified InputSource, using thethe XMLReader specified by the org.xml.sax.driver property.
static JOCLContentHandlerparse(File f, XMLReader reader)
Parses a JOCL document from the specified file, using the XMLReader specified by the org.xml.sax.driver property.
static JOCLContentHandlerparse(Reader in, XMLReader reader)
Parses a JOCL document from the specified Reader, using the specified XMLReader.
static JOCLContentHandlerparse(InputStream in, XMLReader reader)
Parses a JOCL document from the specified InputStream, using the specified XMLReader.
static JOCLContentHandlerparse(InputSource in, XMLReader reader)
Parses a JOCL document from the specified InputSource, using the specified XMLReader.
voidsetDocumentLocator(Locator locator)
intsize()
Returns the number of values and types in my list.
voidstartElement(String uri, String localName, String qname, Attributes attr)

Field Detail

JOCL_NAMESPACE_URI

public static final String JOCL_NAMESPACE_URI
The JOCL namespace URI, http://apache.org/xml/xmlns/jakarta/commons/jocl.

JOCL_PREFIX

public static final String JOCL_PREFIX
The default JOCL prefix, jocl:.

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

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.

endElement

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

getType

public Class getType(int i)
Returns the type of the object at the specified index.

getTypeArray

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

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.

main

public static void main(String[] args)
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.

parse

public static JOCLContentHandler parse(File f)
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

parse

public static JOCLContentHandler parse(Reader in)
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

parse

public static JOCLContentHandler parse(InputStream in)
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

parse

public static JOCLContentHandler parse(InputSource in)
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

parse

public 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. 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

parse

public static JOCLContentHandler parse(Reader in, XMLReader reader)
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

parse

public static JOCLContentHandler parse(InputStream in, XMLReader reader)
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

parse

public static JOCLContentHandler parse(InputSource in, XMLReader reader)
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

setDocumentLocator

public void setDocumentLocator(Locator locator)

size

public int size()
Returns the number of values and types in my list.

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

startElement

public void startElement(String uri, String localName, String qname, Attributes attr)
Copyright © 2001-2004 Apache Software Foundation. Documenation generated December 10 2007.