org.apache.commons.jocl
public class JOCLContentHandler extends DefaultHandler implements ContentHandler
JOCL provides an XML syntax for constructing arbitrary Java {@link 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 {@link 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 {@link #endElement(java.lang.String,java.lang.String,java.lang.String)} has been invoked by the {@link XMLReader}), it will be appended to a list of Objects maintained by the JOCLContentHandler.
(See {@link #size}, {@link #clear}, {@link #clear(int)}, {@link #getType(int)}, {@link #getValue(int)}, {@link #getTypeArray}, and {@link #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 {@link #getTypeArray} method will return an composed of two instances of java.util.Date. The sequence of {@link 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 {@link java.lang.String 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 {@link java.lang.Object Object}s. The {@link #getType 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 {@link java.lang.Object Object}'s constructor. For example, while:
<int value="5"/> <int value="26"/> <int value="100"/>
results in three {@link java.lang.Integer} instances being added to the list of values, with types corresponding to {@link java.lang.Integer}, the fragment:
<int value="5"/> <int value="26"/> <int value="100"/>
results in three {@link java.lang.Integer} instances being added to the list of values, with types corresponding to {@link 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 {@link org.xml.sax.ContentHandler}s that include JOCL as part of their grammar. Simply extend this class, and override the {@link #startElement}, {@link #characters}, and {@link #endElement} 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 {@link InputStream}, {@link Reader} or {@link InputSource}.
Note that this class is not synchronized.
Version: $Revision: 1.6 $ $Date: 2004/02/28 21:37:42 $
Field Summary | |
---|---|
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 {@link #JOCLContentHandler(boolean,boolean,boolean,boolean) JOCLContentHandler(true,true,true,true)}. | |
JOCLContentHandler(boolean emptyEltNS, boolean joclEltPrefix, boolean emptyAttrNS, boolean joclAttrPrefix)
Construct a JOCLContentHandler. |
Method Summary | |
---|---|
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) |
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. |
static void | main(String[] args)
A simple tester method. |
static JOCLContentHandler | parse(File f)
Parses a JOCL document from the specified file, using the
{@link XMLReader} specified by the org.xml.sax.driver
property.
|
static JOCLContentHandler | parse(Reader in)
Parses a JOCL document from the specified {@link Reader}, using the
{@link XMLReader} specified by the org.xml.sax.driver
property.
|
static JOCLContentHandler | parse(InputStream in)
Parses a JOCL document from the specified {@link InputStream}, using the
{@link XMLReader} specified by the org.xml.sax.driver
property.
|
static JOCLContentHandler | parse(InputSource in)
Parses a JOCL document from the specified {@link InputSource}, using thethe
{@link 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
{@link XMLReader} specified by the org.xml.sax.driver
property.
|
static JOCLContentHandler | parse(Reader in, XMLReader reader)
Parses a JOCL document from the specified {@link Reader}, using the specified
{@link XMLReader}.
|
static JOCLContentHandler | parse(InputStream in, XMLReader reader)
Parses a JOCL document from the specified {@link InputStream}, using the specified
{@link XMLReader}.
|
static JOCLContentHandler | parse(InputSource in, XMLReader reader)
Parses a JOCL document from the specified {@link InputSource}, using the
specified {@link 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) |
Parameters: emtpyEltNs 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
Parameters: f a {@link File} containing the JOCL document
Returns: a {@link JOCLContentHandler} containing the list of objects described by the JOCL document
Parameters: in a {@link Reader} containing the JOCL document
Returns: a {@link JOCLContentHandler} containing the list of objects described by the JOCL document
Parameters: in a {@link InputStream} containing the JOCL document
Returns: a {@link JOCLContentHandler} containing the list of objects described by the JOCL document
Parameters: in a {@link InputSource} containing the JOCL document
Returns: a {@link JOCLContentHandler} containing the list of objects described by the JOCL document
Parameters: f a {@link File} containing the JOCL document reader the {@link XMLReader} to use to parse the file
Returns: a {@link JOCLContentHandler} containing the list of objects described by the JOCL document
Parameters: in a {@link Reader} containing the JOCL document reader the {@link XMLReader} to use to parse the document
Returns: a {@link JOCLContentHandler} containing the list of objects described by the JOCL document
Parameters: in a {@link InputStream} containing the JOCL document reader the {@link XMLReader} to use to parse the document
Returns: a {@link JOCLContentHandler} containing the list of objects described by the JOCL document
Parameters: in a {@link InputSource} containing the JOCL document reader the {@link XMLReader} to use to parse the document
Returns: a {@link JOCLContentHandler} containing the list of objects described by the JOCL document
Returns: the number of values and types in my list.