Castor XML to Java Function Component

The CastorXMLtoJava Function Component is the mirror-image counterpart to the Castor Java to XML Function Component, and the same section on Castor Overview applies.

Specifically, the CastorXMLtoJava FC creates an Entry or a general Java object from an XML document, and it provides the option to get data from certain parts of the XML tree when deserializing the XML document.

In addition to the Castor mapping mechanism which specifies how to build a Java object (possibly of a custom Java class) from an XML node/subtree, this Function Component provides its own logic to specify how to populate Entry Attributes from an XML document. By using XPath queries we can specify which parts of the XML document will be passed to the Castor APIs for deserializing.

This approach both provides ease of use in the IBM TDI context and gives more power when processing custom XML documents, for example XML documents generated by other systems. Through the XPath queries you are able to specify which parts of the XML you are interested in (and get them directly into Entry Attributes) and which are irrelevant for your process and should not be processed. In addition, the writing of the Castor XML Mapping Files is facilitated since we will only have to write mapping rules for the parts of the XML document you are interested in and not for the whole XML document.

The CastorXMLToJava Function Component uses Castor 0.9.5.4. Documentation and information for the Castor library can be obtained from the Castor project web site: http://www.castor.org/

Configuration

Parameters

Castor Mapping File

An XML Mapping File (as defined by the Castor syntax) that defines how XML is mapped to Java objects.

The mapping file as specified by this parameter should always include the mapping rules defined in the TDI_install_dir/etc/di_castor_mapping.xml file. This means that either specify "etc/di_castor_mapping.xml" as value of this parameter or make sure that the mapping file specified contains these rules (for example by using Castor's "include" clause to include "di_castor_mapping.xml" rules in another mapping file).

Attribute Specification

Each line specifies a single Attribute in the format: <AttributeName>,<XPath query>[,<type>] . This parameter is only taken into account when the Function Component is used in Entry mode. Within each line,

<AttributeName>

specifies the name of the Entry Attribute;

<XPath query>

specifies which part(s) of the XML to unmarshal and assign as value to this Attribute.

<type>

must be used whenever the type of the Attribute is not a complex Java class, but one of the following basic data types: string, date, boolean, integer, long, double, float, big-decimal, byte, short, character, strings (array of strings), chars (array of chars), bytes (array of bytes). In these cases the user must specify the type, because of a limitation in Castor - Castor cannot handle these types when they map to standalone objects (instead of being members of other objects) and so the Function Component needs to know the type and take special actions to make Castor produce the correct object.

XML Input as

This drop-down list specifies whether the Function Component will accept the input XML data in the form of a DOMElement object or as a String.

Detailed Log

Check to generate additional log messages.

Comment

Your own comments go here.

Using the FC

The CastorXMLToJava Function Component creates an Entry or a general Java object from an XML document, and can operate both with Entry objects and with custom Java objects.

When the Function Component is passed an Entry object on input, it will return an Entry object. This mode of operation is called Entry mode.

When the Function Component is passed an object that is not an Entry on input (String or a DOMelement) it returns the raw Java object as it is unmarshalled by Castor. This mode of operation is called non-Entry mode.

Entry mode

• If the XML Input as parameter specifies DOMelement, the Function Component will expect on input an Entry with an Attribute named "xmlDOMElement" with value of type "org.w3c.dom.Element".

• If the XML Input as parameter specifies String, an Entry with an Attribute named "xmlString" and value of type "java.lang.String" is expected on input.

• The output generated is an Entry whose Attributes are the unmarshalled XML elements as specified by the Attribute Specification parameter and the mapping file.

Non-Entry mode

• If the XML Input as parameter specifies DOMelement, the Function Component will expect on input a "org.w3c.dom.Element" object.

• If the XML Input as parameter specifies String, a "java.lang.String" object is expected on input.