org.apache.commons.jocl
Class JOCLContentHandler

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      org.apache.commons.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 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

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 Locator	_locator My Locator.
protected ArrayList	_typeList A list of the types (Classes) already created via the parse.
protected ArrayList	_valueList A list of the values (Objects) 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

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

JOCLContentHandler(boolean emptyEltNS, boolean joclEltPrefix, boolean emptyAttrNS, boolean joclAttrPrefix)
Construct a JOCLContentHandler.

Method Summary

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 _typeList

A list of the types (Classes) already created via the parse.

_valueList

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