oracle.portal.utils.xml.v2
Class DefaultNodeHandler

java.lang.Object
  oracle.portal.utils.xml.v2.DefaultNodeHandler

All Implemented Interfaces:

NodeHandler

Direct Known Subclasses:

LiteralXML.Handler

public class DefaultNodeHandler
extends java.lang.Object
implements NodeHandler

A DefaultNodeHandler is capable of translating an XML DOM object tree into an analogous hierarchy of application objects, whose classes, attributes and associations all reflect the configuration of the nodes in the XML tree. The class therefore provides an extensible mechanism for configuring a potentially complex system of Java objects through an XML document.

The main entry point is the processNode(Node,Object) method, which recursively processes the nodes in the XML document and builds up a corresponding tree of application objects. Each call to the method processes all the children of a given XML node in the context of a particular application object represented by that node. For each of the given node's child nodes in turn, the method proceeds as follows:

• If the child node is a complex element, that is, an element node with either further element nodes as children, or no element or text node children at all, it is considered to correspond to a new application object. The precise type of this application object is determined by the overridable getApplicationObjectForElement(Element) method, which returns a new instance of an appropriate application object class. Given this new object, processNode records a parent-child association between the context application object and the new object. Finally, a recursive call to <processNode> is made in order to process the child node in the context of the new application object. However, this call may actually be redirected to the processNode method of a different NodeHandler object, depending on the value the overridable getHandlerForElement(Element) method returns for the complex element. This mechanism is designed to allow the 'delegation' of the processing of certain complex elements to customized NodeHandlers.
• If the child node is a simple element, that is, an element node which has a text node as a child and no other element children, it is considered to correspond to a particular property of the context application object. In this case, the overridable handleSimpleElement(Element,Object) method is used to set a corresponding property on the context application object to the 'value' of the simple element (derived from the String value of the element's first text node child).
• If the child node is any other type of node, then it is ignored.

In this default implementation, the following restrictions are placed on complex elements and the classes of the objects they describe:

• Each complex element must have a class attribute, containing the fully qualified name of the corresponding application object class.
• The application object class should have a public zero-argument constructor.
• If initialization of an application object requires knowledge of its 'context' in the tree of application objects, its class should implement the InitializableXMLObject interface. Initialization to be performed when the object is first created, perhaps relating the new object to its parent, should be placed in a preInitialize(Object) method, and any extra initialization and validation to be performed once the object's own children have been initialized should be placed in a postInitialize() method.
• For each possible child of a complex element that is itself a complex element, the application object class should have a public method to record a parent-child association with the application object corresponding to the child element. The method should take the child application object as a single Object parameter, and should have a name prefixed by "set" or "add" and suffixed by the name of the child element (with initial captital letter).
• For each possible child of a complex element that is a simple element, the application object class should have a method to set a corresponding property. The method should take the String value of the first text node child of the simple element as a parameter. If the parameter is to be stored as a non-String value (e.g. an int), then the method will also be responsible for converting the parameter to a value of the appropriate type, and possibly throwing an exception should the conversion fail. The same naming restrictions for the method as above apply.
• If a complex element is to be handled by a NodeHandler other than the current one, then it should have a handler attribute, containing the fully qualified name of a class implementing NodeHandler.

In the example XML below:

• complex1 and complex2 are complex elements. complex1 describes an object of class oracle.portal.ApplicationClass, while complex2 describes an object of class my.custom.ApplicationClass.
• complex1 has no handler attribute, so will be processed by the same NodeHandler that processed its parent (the root document element). complex2 specifies my.custom.HandlerClass in its handler attribute, so its processing will be delegated to a NodeHandler object of the specified class.
• simple1 and simple2 are simple elements. simple1 controls a single property in the oracle.portal.ApplicationClass object, while simple2 controls a collection of values in the same object. A corresponding method of oracle.portal.ApplicationClass, setSimple1(String) might set a single member variable to the given string value, while another method addSimple2(String) might add the given value to list of values held within the object.

    <complex1 class="oracle.portal.ApplicationClass">
      <simple1>value</simple1>
      <simple2>value1</item>
      <simple2>value2</item>
      <simple2>value3</item>
      <complex2 class="my.custom.ApplicationClass" handler="my.custom.HandlerClass"/>
    </complex1>
   

Constructor Summary

DefaultNodeHandler()
Constructs a DefaultNodeHandler which uses the ClassLoader that loaded its own class.

DefaultNodeHandler(java.lang.ClassLoader classLoader)
Constructs a DefaultNodeHandler which uses the given ClassLoader.

Method Summary

java.lang.Object	getApplicationObjectForElement(org.w3c.dom.Element e) For a given 'complex' element, returns an instance of the type of object it represents.
NodeHandler	getHandlerForElement(org.w3c.dom.Element e) For a given 'complex' element, returns the NodeHandler that should be used to process it.
void	handleSimpleElement(org.w3c.dom.Element e, java.lang.Object o) For a given 'simple' element, and the current context application object, performs the steps necessary to set the value of a property of the application object corresponding to the simple element, to the value held by the element.
void	invokePostInitialize(java.lang.Object o) Performs any extra steps required to initialize and validate an application object once its child application objects have been created.
void	invokePreInitialize(java.lang.Object o, java.lang.Object parent) Performs any steps required to initialize an application object after it has been created, perhaps relating the new object to its parent.
void	processNode(org.w3c.dom.Node n, java.lang.Object o) Recursively processes all the children of a given XML node in the context of an application object represented by that node, in order to populate the application object and create and populate other 'child' application objects.

Methods inherited from class java.lang.Object

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

Constructor Detail

DefaultNodeHandler

public DefaultNodeHandler(java.lang.ClassLoader classLoader)

Constructs a DefaultNodeHandler which uses the given ClassLoader.

Parameters:

classLoader - the class loader to use when resolving class names.

DefaultNodeHandler

public DefaultNodeHandler()

Constructs a DefaultNodeHandler which uses the ClassLoader that loaded its own class. Note: if you have pdkjava.jar in you global classpath, using this constructor means that you will not be able to load classes specific to a particular web app.

Method Detail

processNode

public void processNode(org.w3c.dom.Node n,
                        java.lang.Object o)
                 throws NodeHandlerException

Recursively processes all the children of a given XML node in the context of an application object represented by that node, in order to populate the application object and create and populate other 'child' application objects.

Specified by:

processNode in interface NodeHandler

Parameters:

n - current node whose children will be processed to populate the context application object.

o - the context application object.

Throws:

NodeHandlerException - if unable to instantiate a child object or handler object, find a method corresponding to a simple element, or an exception occurs while calling a method on a child object.

getApplicationObjectForElement

public java.lang.Object getApplicationObjectForElement(org.w3c.dom.Element e)
                                                throws NodeHandlerException

For a given 'complex' element, returns an instance of the type of object it represents. In this default implementation, the method simply attempts to create an instance of the class named in the element's class attribute, if it has one. Users should override if the type of object corresponding to a particular complex element can be determined in a different way.

Parameters:

e - the 'complex' element for which a corresponing object is to be created

Returns:

an object of the class corresponding to the element, or null if no corresponding class can be determined for the element

Throws:

NodeHandlerException - if an error occurs while trying to create an appropriate object.

getHandlerForElement

public NodeHandler getHandlerForElement(org.w3c.dom.Element e)
                                 throws NodeHandlerException

For a given 'complex' element, returns the NodeHandler that should be used to process it. In this default implementation, the method simply returns an instance of the class named in the element's handler attribute, if it has one, or the current DefaultNodeHandler otherwise. Users should override if the handler for a particular complex element can be determined in a different way.

Parameters:

e - the 'complex' element whose handler is to be determined

Returns:

a handler for the element

Throws:

NodeHandlerException - if an error occurs while trying to create an appropriate handler object.

handleSimpleElement

public void handleSimpleElement(org.w3c.dom.Element e,
                                java.lang.Object o)
                         throws NodeHandlerException

For a given 'simple' element, and the current context application object, performs the steps necessary to set the value of a property of the application object corresponding to the simple element, to the value held by the element. In this default implementation, the method looks for a method on the application object with a name prefixed by "set" or "add" and suffixed by the tag name of the simple element (with initial captital letter), taking a single String parameter. If such a method is found, it is called with the String value of the simple element's first child text node as an argument. Users should override if application object properties should be set in a different way.

Parameters:

e - a 'simple' element corresponding to a property of the application object

o - the application object on which the property is to be set

Throws:

NodeHandlerException - if an error occurs while trying to locate and set the property on the application object

invokePreInitialize

public void invokePreInitialize(java.lang.Object o,
                                java.lang.Object parent)
                         throws NodeHandlerException

Performs any steps required to initialize an application object after it has been created, perhaps relating the new object to its parent. In this default implementation, the method simply calls the object's preInitialize method with the parent object as an argument, if it implements InitializableXMLObject. Users should override if there are further actions to be performed on their application objects.

Parameters:

o - the application object to be initialized

parent - the application object that will become this object's parent

Throws:

NodeHandlerException - if an error occurs while initializing the application object

invokePostInitialize

public void invokePostInitialize(java.lang.Object o)
                          throws NodeHandlerException

Performs any extra steps required to initialize and validate an application object once its child application objects have been created. In this default implementation, the method simply calls the object's postInitialize method, if it implements InitializableXMLObject. Users should override if there are further post-initialization steps to be performed on their application objects.

Parameters:

o - the application object to be initialized

Throws:

NodeHandlerException - if an error occurs while initializing or validating the application object