org.wandora.utils

Class XMLParamProcessor

java.lang.Object

org.wandora.utils.XMLParamProcessor

public class XMLParamProcessor
extends java.lang.Object

Utility to create Java Objects from xml. Recursively creates or retrieves objects from symbol table for constructor and method parameters. With some helper classes inserted into the symbol table beforehand, can be pretty much used to execute arbitrary Java code. Normally parameters to class constructors are parsed recursively from the child elements of the creating element. Your class can however implement XMLParamAware in which case your class will be provided with the DOM element and you can implement custom parameter parsing. XMLParamAware clasesses are also given this XMLParamProcessor so they have access to the entire symbol table created (at the time of their generation). So parameters can also be passed by putting objects in the symbol table with specific keys. This is especially usefull for objects that are passed to allmost every object (such as loggers; which many classes will try to get from symbol table with key "logger").

New objects are usually created by providing the full class name of the created object. You can also map element names to different classes beforehand and then create new objects with these element names.

• id attribute specifies the id of the created or returned object in the symbol table. If the symbol table allready contains an object with the given id, it is overwritten.
• idref attribute specifies the id of the object to be retrieved from the symbol table.
• class attribute specifies the full class name of the object to be created.
• array attribute specifies the full class name of the component type of the array to be created.
• method attribute specifies the name of the method to execute.
• literal attribute specifies whether the contents of the element should be interpreted as a literal string. Possible values true and false, default is false.

Only one of the idref, class, array and static attributes can be specified. This determines how to create or retrieve the object. The value of idref must be the id of the object in the symbol table, the value of the other three must be a full class name. With idref you can use either method or field attribute to invoke a method or get the value of a field respectively and with static you must use one of these.

• When class is used, a new object is created and child elements are used as constructor parameters.
• When array is used, a new array object is created and child elements are used to populate the array.
• When idref is used, object is retrieved from the symbol table.
• When static is used, the resulting object is the return value of a static method or the value of a static field.
• When none of the above are specified
  1. If the used element name has been mapped to a class, this mapping will be used to create a new instance of the class as if class attribute were used. The following mappings are used by default
     • string => java.lang.String
     • integer => java.lang.Integer
     • double => java.lang.Double
     • boolean => java.lang.Boolean
     • properties => org.wandora.piccolo.XMLProperties
  2. If that fails, class attribute is treated to be "java.lang.String" and literal is forced to true.

When you use class attribute to create a new object, note that the class you are creating might implement XMLParamAware, in which case refer to the documentation of that class about how the child elements are used. You must use either method or field attribute when using static.

• Using the method attribute will cause the invokation of the specified method with the parameters read from the child elements except when it is used with class attribute, in which case the method is called without parameters.
• Using the field attribute will get the specified field of the object.
• When id attribute is specified, the created object or the object returned by the method call or the object retrieved from the symbol table is assigned into the symbol table with the specified id. Also the used element name is stored and can be retrieved with getObjectType method.
• literal attribute is used to create String objects from the contents of the element.

For example, consider the following xml:

 <object id="p" class="Store">
  <param class="java.lang.String" literal="true">Store name</param>
  <param array="StoreItem">
   <item class="StoreItem">
    <param class="java.lang.String" literal="true">apple</param>
    <param class="java.lang.Integer" literal="true">5</param>
   </item>   
   <item class="StoreItem">
    <String>banana</String>
    <Integer>10</Integer>
   </item>   
  </param>
 </object>
 <object id="customer" class="Customer"/>
 <method id="error" idref="p" method="buyOne">
  <param idref="customer"/>
  <param class="java.lang.String">apple</param>
 </method>
 

This would roughly be equivalent to the following java code:

 Store p=new Store("Store name",new StoreItem[]{new StoreItem("apple",5),new StoreItem("banana",10)});
 Customer customer=new Customer();
 Boolean error=p.buyOne(customer,"apple");
 

Note that the first StoreItem is created using the full syntax and the second item shows how to use the shorter syntax for java.lang.* classes.

As another example, the following is pretty much equal to System.out.println("Hello World"); (note the use of name space).

 <root xmlns:xp="http://wandora.org/xmlparamprocessor">
  <object xp:id="out" xp:static="java.lang.System" xp:field="out"/>
  <method xp:idref="out" xp:method="println">
   <param xp:class="java.lang.String" xp:literal="true">Hello World!</param>
  </method>
 </root>
 

Note the autoboxing/unboxing of primitive types. However, the symbol table will only contain Objects, that is no primitive types. Also note that String,Integer,Double,Boolean etc all have a constructor accepting a single String parameter thus the creation of Integers with literal attribute set to true works (as does the shorter syntax using Integer element name). Note that arithmetic operations are not directly possible. However you could make an object into the symbol table which provides the necessary methods.

To use XMLParamProcessor, first create a new instance of it. Then add whatever objects you want to the symbol table (optional). Then use processElement or one of the create methods to process elements of the XML. Finally you can get objects from the symbol table if you need to.

You can use getObjectType to get the element name used to create the object. This way you can easily group your objects into different categories.

Note that by default XMLParamProcessor uses a namespace "http://wandora.org/xmlparamprocessor" for all the attributes. So either use setNameSpace method to set the name space to null to disable this or take care that your xml has proper name spaces setup and that the xml implementation supports name spaces. You should use javax.xml.parsers.DocumentBuilderFactory.setNamespaceAware(true) before creating the document builder used to parse the document.

Author:

olli

See Also:

XMLParamAware

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.HashMap	classMap
static java.lang.String	DEFAULT_NAMESPACE The default namespace URI.
private java.util.HashSet	forcedLiterals
private java.lang.String	nameSpace
private java.util.HashMap	objectTable
private java.util.HashMap	objectTypeTable

Constructor Summary

Constructors

Constructor and Description
XMLParamProcessor() Creates a new instance of XMLParamProcessor

Method Summary

Modifier and Type	Method and Description
void	addObjectToTable(java.lang.String id, java.lang.Object o) Adds (or reassigns) a single object to the symbol table.
java.lang.Object[]	createArray(org.w3c.dom.Element e, java.lang.Object[] arrayType) Creates an array of the child nodes of the given element.
java.lang.Object	createObject(org.w3c.dom.Element e) Interprets one element and returns the created or retrieved object.
java.lang.Object	createObject(org.w3c.dom.Element e, java.lang.String forceClass)
static java.lang.reflect.Constructor	findConstructor(java.lang.Class cls, java.lang.Object[] params)
static java.lang.reflect.Method	findMethod(java.lang.Class cls, java.lang.String method, java.lang.Object[] params)
private java.lang.String	getAttribute(org.w3c.dom.Element e, java.lang.String attr)
java.lang.String	getClassMapping(java.lang.String nodeName)
static java.lang.String	getElementContents(org.w3c.dom.Element e)
static java.lang.String	getNodeContents(org.w3c.dom.Node n)
java.lang.Object	getObject(java.lang.String id) Gets an object from the symbol table.
java.lang.String	getObjectType(java.lang.String id)
java.util.HashMap	getSymbolTable() Returns the whole symbol table.
static java.lang.Class[]	getTypeArray(java.lang.Object[] params)
static boolean	isInstanceOrBoxed(java.lang.Class type, java.lang.Object param)
static void	main(java.lang.String[] args) A test main method.
void	mapClass(java.lang.String nodeName, java.lang.String className) Map a given node name to a specific class.
static org.w3c.dom.Document	parseDocument(java.io.InputStream in) A convenience method to parse a Document from a File.
static org.w3c.dom.Document	parseDocument(java.lang.String file) A convenience method to parse a Document from a File.
java.lang.Object	processElement(org.w3c.dom.Element e) Processes all the child elements of the given element.
void	setNameSpace(java.lang.String ns) Sets the used name space URI.
void	setSymbolTable(java.util.HashMap table) Reset the whole symbol table.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_NAMESPACE

public static final java.lang.String DEFAULT_NAMESPACE

The default namespace URI.

See Also:

Constant Field Values

objectTable

private java.util.HashMap objectTable

objectTypeTable

private java.util.HashMap objectTypeTable

nameSpace

private java.lang.String nameSpace

classMap

private java.util.HashMap classMap

forcedLiterals

private java.util.HashSet forcedLiterals

Constructor Detail

XMLParamProcessor

public XMLParamProcessor()

Creates a new instance of XMLParamProcessor

Method Detail

setNameSpace

public void setNameSpace(java.lang.String ns)

Sets the used name space URI.

Parameters:

ns - The new name space URI or null to disable the use of name spaces.

setSymbolTable

public void setSymbolTable(java.util.HashMap table)

Reset the whole symbol table.

Parameters:

table - The new symbol table. Should contain id Strings mapped to the corresponding objects.

mapClass

public void mapClass(java.lang.String nodeName,
                     java.lang.String className)

Map a given node name to a specific class. If className is null, removes the previous association. After a node name N is mapped to class C, an element with node name N will behave as if it had attribute class with value C. Thus if you create many instances of the same class, you can map a specific node name to that class after which you don't need to write the class attribute for every element.

getClassMapping

public java.lang.String getClassMapping(java.lang.String nodeName)

addObjectToTable

public void addObjectToTable(java.lang.String id,
                             java.lang.Object o)

Adds (or reassigns) a single object to the symbol table.

Parameters:

id - The id of the object.

o - The object to be assigned with the given id.

getObject

public java.lang.Object getObject(java.lang.String id)

Gets an object from the symbol table.

Parameters:

id - The id of the object to get.

Returns:

The object or null if not found (or the object really is null).

getObjectType

public java.lang.String getObjectType(java.lang.String id)

getSymbolTable

public java.util.HashMap getSymbolTable()

Returns the whole symbol table.

Returns:

The symbol table with ids mapped to objects.

getTypeArray

public static java.lang.Class[] getTypeArray(java.lang.Object[] params)

isInstanceOrBoxed

public static boolean isInstanceOrBoxed(java.lang.Class type,
                                        java.lang.Object param)

findConstructor

public static java.lang.reflect.Constructor findConstructor(java.lang.Class cls,
                                                            java.lang.Object[] params)
                                                     throws java.lang.Exception

Throws:

java.lang.Exception

findMethod

public static java.lang.reflect.Method findMethod(java.lang.Class cls,
                                                  java.lang.String method,
                                                  java.lang.Object[] params)
                                           throws java.lang.Exception

Throws:

java.lang.Exception

getAttribute

private java.lang.String getAttribute(org.w3c.dom.Element e,
                                      java.lang.String attr)

getNodeContents

public static java.lang.String getNodeContents(org.w3c.dom.Node n)

getElementContents

public static java.lang.String getElementContents(org.w3c.dom.Element e)

createObject

public java.lang.Object createObject(org.w3c.dom.Element e)
                              throws java.lang.Exception

Interprets one element and returns the created or retrieved object. Also interpretes any parameters (child nodes) the interpration of the actual element might require. Adds objects to symbol table where elements contain id attribute.

Parameters:

e - The element to interpret.

Returns:

The created object, the retrieved object or the result of the method call or null if the symbol table didn't contain the object or the method call returns null.

Throws:

java.lang.Exception

createObject

public java.lang.Object createObject(org.w3c.dom.Element e,
                                     java.lang.String forceClass)
                              throws java.lang.Exception

Throws:

java.lang.Exception

createArray

public java.lang.Object[] createArray(org.w3c.dom.Element e,
                                      java.lang.Object[] arrayType)
                               throws java.lang.Exception

Creates an array of the child nodes of the given element. This is equivalent to calling createObject for each child element of the given element, and putting the results in an array. The returned array will have the type or arrayType or Object[] if arrayType is null.

Parameters:

e - The element whose child elements are parsed.

arrayType - An object used to determine the type of the returned array. If null, the returned array will be of type Object[].

Returns:

The created array.

Throws:

java.lang.Exception

processElement

public java.lang.Object processElement(org.w3c.dom.Element e)
                                throws java.lang.Exception

Processes all the child elements of the given element. First (non null) element is returned and the processing might add objects to the symbol table which can then be retrieved there.

Parameters:

e - The element whose child elements are parsed.

Throws:

java.lang.Exception

parseDocument

public static org.w3c.dom.Document parseDocument(java.lang.String file)
                                          throws java.lang.Exception

A convenience method to parse a Document from a File. The returned document should support name spaces.

Throws:

java.lang.Exception

parseDocument

public static org.w3c.dom.Document parseDocument(java.io.InputStream in)
                                          throws java.lang.Exception

A convenience method to parse a Document from a File. The returned document should support name spaces.

Throws:

java.lang.Exception

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

A test main method. Parses the file given as the first command line parameter.

Throws:

java.lang.Exception