Class JOCLContentHandler
- java.lang.Object
-
- org.xml.sax.helpers.DefaultHandler
-
- org.apache.commons.jocl.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
AContentHandler
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 theObjects
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 theXMLReader
), it will be appended to a list of Objects maintained by the JOCLContentHandler.(See
size()
,clear()
,clear(int)
,getType(int)
,getValue(int)
,getTypeArray()
, andgetValueArray()
.)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"/>
ThegetTypeArray()
method will return an array composed of two instances of java.util.Date. The sequence ofObjects
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. Thetype
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 specifiedObject
'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 toInteger
, 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 toInteger.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 thestartElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)
,DefaultHandler.characters(char[], int, int)
, andendElement(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
orInputSource
.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 theJOCL_PREFIX
but no namespace URI as being mapped to the jocl namespace.protected boolean
_acceptJoclPrefixForElements
When true, I will treat elements with theJOCL_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
MyLocator
.protected java.util.ArrayList
_typeList
A list of the types (Class
es) already created via the parse.protected java.util.ArrayList
_valueList
A list of the values (Object
s) 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:.
-
Constructor Summary
Constructors Constructor Description JOCLContentHandler()
Equivalent toJOCLContentHandler(true,true,true,true)
.JOCLContentHandler(boolean emptyEltNS, boolean joclEltPrefix, boolean emptyAttrNS, boolean joclAttrPrefix)
Construct a JOCLContentHandler.
-
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)
Equivalent togetAttributeValue(localname,attr,null)
.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 ofAttributes
.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 theXMLReader
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 theXMLReader
specified by the org.xml.sax.driver property.static JOCLContentHandler
parse(java.io.InputStream in)
Parses a JOCL document from the specifiedInputStream
, using theXMLReader
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 specifiedInputStream
, using the specifiedXMLReader
.static JOCLContentHandler
parse(java.io.Reader in)
Parses a JOCL document from the specifiedReader
, using theXMLReader
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 specifiedReader
, using the specifiedXMLReader
.static JOCLContentHandler
parse(org.xml.sax.InputSource in)
Parses a JOCL document from the specifiedInputSource
, using thetheXMLReader
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 specifiedInputSource
, using the specifiedXMLReader
.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)
-
-
-
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 (Class
es) already created via the parse.
-
_valueList
protected java.util.ArrayList _valueList
A list of the values (Object
s) 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 theJOCL_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 theJOCL_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
MyLocator
.
-
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()
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 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 anXMLReader
.- 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 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:
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 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:
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 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:
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 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:
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 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:
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 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:
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 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:
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 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:
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 interfaceorg.xml.sax.ContentHandler
- Overrides:
startElement
in classorg.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 interfaceorg.xml.sax.ContentHandler
- Overrides:
endElement
in classorg.xml.sax.helpers.DefaultHandler
- Throws:
org.xml.sax.SAXException
-
setDocumentLocator
public void setDocumentLocator(org.xml.sax.Locator locator)
- Specified by:
setDocumentLocator
in interfaceorg.xml.sax.ContentHandler
- Overrides:
setDocumentLocator
in classorg.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.)
-
getAttributeValue
protected java.lang.String getAttributeValue(java.lang.String localname, org.xml.sax.Attributes attr)
Equivalent togetAttributeValue(localname,attr,null)
.
-
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 ofAttributes
. If no such attribute can be found, returns implied.- Parameters:
localname
- the unqualified name of the attribute to look forattr
- the Attributes in which to find the valueimplied
- 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.
-
-