Overview | Package | Class | Tree | Deprecated | Index | Help
| The PDK Java API is part of the Portal Developer Kit on Portal Studio
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 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 `NodeHandler`s.
- 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
    `parent` - the application object that will become this object's parent
  Throws:
    `NodeHandlerException` - if an error occurs while initializing or validating the application object

Overview | Package | Class | Tree | Deprecated | Index | Help
| The PDK Java API is part of the Portal Developer Kit on Portal Studio
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2002, Oracle Corporation. All Rights Reserved.