Home » commons-dbcp-1.4-src » org.apache.commons » jocl » [javadoc | source]
org.apache.commons.jocl
public class: JOCLContentHandler [javadoc | source]
java.lang.Object
   org.xml.sax.helpers.DefaultHandler
      org.apache.commons.jocl.JOCLContentHandler

All Implemented Interfaces:
    ErrorHandler, EntityResolver, ContentHandler, DTDHandler

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 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 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|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 org.xml.sax.ContentHandler s that include JOCL as part of their grammar. Simply extend this class, and override the #startElement , #characters , and #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 InputStream , Reader or InputSource .

Note that this class is not synchronized.

Nested Class Summary:
static class  JOCLContentHandler.ConstructorDetails   
Field Summary
public static final  String JOCL_NAMESPACE_URI    The JOCL namespace URI, http://apache.org/xml/xmlns/jakarta/commons/jocl
public static final  String JOCL_PREFIX    The default JOCL prefix, jocl:
protected  ArrayList _typeList    A list of the types (Class es) already created via the parse. 
protected  ArrayList _valueList    A list of the values (Object s) already created via the parse. 
protected  ConstructorDetails _cur    The object I'm currently working on. 
protected  boolean _acceptEmptyNamespaceForElements    When true, I will treat elements with an empty namespace URI as part of 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  boolean _acceptEmptyNamespaceForAttributes    When true, I will treat attributes 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  Locator _locator    My Locator
protected static final  String ELT_OBJECT    The name of the "object" element. 
protected static final  String ELT_ARRAY    The name of the "array" element.
    since: 1.2.2 -
 
protected static final  String ELT_COLLECTION    The name of the "collection" element.
    since: 1.2.2 -
 
protected static final  String ELT_LIST    The name of the "list" element.
    since: 1.2.2 -
 
protected static final  String ATT_CLASS    The name of the "object" element's "class" attribute. 
protected static final  String ATT_ISNULL    The name of the "object" element's "isnull" attribute. 
protected static final  String ELT_BOOLEAN    The name of the "boolean" element. 
protected static final  String ELT_BYTE    The name of the "byte" element. 
protected static final  String ELT_CHAR    The name of the "char" element. 
protected static final  String ELT_DOUBLE    The name of the "double" element. 
protected static final  String ELT_FLOAT    The name of the "float" element. 
protected static final  String ELT_INT    The name of the "int" element. 
protected static final  String ELT_LONG    The name of the "long" element. 
protected static final  String ELT_SHORT    The name of the "short" element. 
protected static final  String ELT_STRING    The name of the "string" element. 
protected static final  String ATT_VALUE    The name of the "value" attribute. 
Constructor:
 public JOCLContentHandler() 
 public JOCLContentHandler(boolean emptyEltNS,
    boolean joclEltPrefix,
    boolean emptyAttrNS,
    boolean joclAttrPrefix) 
Method from org.apache.commons.jocl.JOCLContentHandler Summary:
addObject,   clear,   clear,   endElement,   getAttributeValue,   getAttributeValue,   getType,   getTypeArray,   getValue,   getValueArray,   isJoclNamespace,   main,   parse,   parse,   parse,   parse,   parse,   parse,   parse,   parse,   setDocumentLocator,   size,   startElement
Methods from org.xml.sax.helpers.DefaultHandler:
characters,   endDocument,   endElement,   endPrefixMapping,   error,   fatalError,   ignorableWhitespace,   notationDecl,   processingInstruction,   resolveEntity,   setDocumentLocator,   skippedEntity,   startDocument,   startElement,   startPrefixMapping,   unparsedEntityDecl,   warning
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.apache.commons.jocl.JOCLContentHandler Detail:
 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.
 public  void clear() 
    Clears all the values and types in my list.
 public  void clear(int i) 
    Removes the value/type pair at the specified index.
 public  void endElement(String uri,
    String localName,
    String qname) throws SAXException 
 protected String getAttributeValue(String localname,
    Attributes attr) 
 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.
 public Class getType(int i) 
    Returns the type of the object at the specified index.
 public Object[] getTypeArray() 
    Returns a shallow copy of my list of types.
 public Object getValue(int i) 
    Returns the value of the object at the specified index.
 public 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.)
 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 .
 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.
 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.
 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.
 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.
 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.
 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.
 public static JOCLContentHandler parse(InputStream in,
    XMLReader reader) throws SAXException, IOException 
 public static JOCLContentHandler parse(InputSource in,
    XMLReader reader) throws SAXException, IOException 
 public  void setDocumentLocator(Locator locator) 
 public int size() 
    Returns the number of values and types in my list.
 public  void startElement(String uri,
    String localName,
    String qname,
    Attributes attr) throws SAXException