Class JOCLContentHandler
- All Implemented Interfaces:
ContentHandler
,DTDHandler
,EntityResolver
,ErrorHandler
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 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.
- Version:
- $Revision: 883416 $ $Date: 2009-11-23 12:12:14 -0500 (Mon, 23 Nov 2009) $
- Author:
- Rodney Waldhoff
-
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionEquivalent toJOCLContentHandler(true,true,true,true)
.JOCLContentHandler
(boolean emptyEltNS, boolean joclEltPrefix, boolean emptyAttrNS, boolean joclAttrPrefix) Construct a JOCLContentHandler. -
Method Summary
Modifier and TypeMethodDescriptionvoid
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) getType
(int i) Returns the type of the object at the specified index.Object[]
Returns a shallow copy of my list of types.getValue
(int i) Returns the value of the object at the specified index.Object[]
Returns a shallow copy of my list of values.static void
A simple tester method.static JOCLContentHandler
Parses a JOCL document from the specified file, using theXMLReader
specified by the org.xml.sax.driver property.static JOCLContentHandler
Parses a JOCL document from the specified file, using theXMLReader
specified by the org.xml.sax.driver property.static JOCLContentHandler
parse
(InputStream in) Parses a JOCL document from the specifiedInputStream
, using theXMLReader
specified by the org.xml.sax.driver property.static JOCLContentHandler
parse
(InputStream in, XMLReader reader) Parses a JOCL document from the specifiedInputStream
, using the specifiedXMLReader
.static JOCLContentHandler
static JOCLContentHandler
static JOCLContentHandler
parse
(InputSource in) Parses a JOCL document from the specifiedInputSource
, using thetheXMLReader
specified by the org.xml.sax.driver property.static JOCLContentHandler
parse
(InputSource in, XMLReader reader) Parses a JOCL document from the specifiedInputSource
, using the specifiedXMLReader
.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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.xml.sax.ContentHandler
declaration
-
Field Details
-
JOCL_NAMESPACE_URI
The JOCL namespace URI, http://apache.org/xml/xmlns/jakarta/commons/jocl.- See Also:
-
JOCL_PREFIX
The default JOCL prefix, jocl:.- See Also:
-
-
Constructor Details
-
JOCLContentHandler
public JOCLContentHandler()Equivalent toJOCLContentHandler(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 namespacejoclEltPrefix
- when true I should assume any element who's prefix is jocl: and who's namespace is empty is within the JOCL namespaceemptyAttrNS
- when true I should assume any attribute with an empty namespace is within the JOCL namespacejoclAttrPrefix
- when true I should assume any attribute who's prefix is jocl: and who's namespace is empty is within the JOCL namespace
-
-
Method Details
-
main
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 anXMLReader
.- Throws:
Exception
-
parse
public static JOCLContentHandler parse(File f) throws SAXException, FileNotFoundException, IOException Parses a JOCL document from the specified file, using theXMLReader
specified by the org.xml.sax.driver property. The returnedJOCLContentHandler
will contain the list of objects described by the file.- Parameters:
f
- aFile
containing the JOCL document- Returns:
- a
JOCLContentHandler
containing the list of objects described by the JOCL document - Throws:
SAXException
FileNotFoundException
IOException
-
parse
Parses a JOCL document from the specifiedReader
, using theXMLReader
specified by the org.xml.sax.driver property. The returnedJOCLContentHandler
will contain the list of objects described by the file.- Parameters:
in
- aReader
containing the JOCL document- Returns:
- a
JOCLContentHandler
containing the list of objects described by the JOCL document - Throws:
SAXException
IOException
-
parse
Parses a JOCL document from the specifiedInputStream
, using theXMLReader
specified by the org.xml.sax.driver property. The returnedJOCLContentHandler
will contain the list of objects described by the file.- Parameters:
in
- aInputStream
containing the JOCL document- Returns:
- a
JOCLContentHandler
containing the list of objects described by the JOCL document - Throws:
SAXException
IOException
-
parse
Parses a JOCL document from the specifiedInputSource
, using thetheXMLReader
specified by the org.xml.sax.driver property. The returnedJOCLContentHandler
will contain the list of objects described by the file.- Parameters:
in
- aInputSource
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 theXMLReader
specified by the org.xml.sax.driver property. The returnedJOCLContentHandler
will contain the list of objects described by the file.- Parameters:
f
- aFile
containing the JOCL documentreader
- theXMLReader
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 specifiedReader
, using the specifiedXMLReader
. The returnedJOCLContentHandler
will contain the list of objects described by the file.- Parameters:
in
- aReader
containing the JOCL documentreader
- theXMLReader
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 specifiedInputStream
, using the specifiedXMLReader
. The returnedJOCLContentHandler
will contain the list of objects described by the file.- Parameters:
in
- aInputStream
containing the JOCL documentreader
- theXMLReader
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 specifiedInputSource
, using the specifiedXMLReader
. The returnedJOCLContentHandler
will contain the list of objects described by the file.- Parameters:
in
- aInputSource
containing the JOCL documentreader
- theXMLReader
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
Returns the type of the object at the specified index. -
getValue
Returns the value of the object at the specified index. -
getValueArray
Returns a shallow copy of my list of values. -
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 interfaceContentHandler
- Overrides:
startElement
in classDefaultHandler
- Throws:
SAXException
-
endElement
- Specified by:
endElement
in interfaceContentHandler
- Overrides:
endElement
in classDefaultHandler
- Throws:
SAXException
-
setDocumentLocator
- Specified by:
setDocumentLocator
in interfaceContentHandler
- Overrides:
setDocumentLocator
in classDefaultHandler
-