SDOToXML Function Component

The EMF SDOToXML Function Component converts Service Data Objects to XML. This component uses an XML Schema definition to build an Ecore model.

The Function Component receives an Entry whose Attributes represent an XML document. The types of the Entry Attribute values are either Java classes representing primitive types or Service Data Objects (org.eclipse.emf.ecore.sdo.EDataObject) representing complex XML elements.

The Entry Attribute names describe the XML hierarchy in exactly the same manner as the EMF XMLToSDO Function Component constructs Attribute names. All Attribute names start with "DocRoot" which represents the XML root. Subsequent elements down the XML hierarchy are separated with the "@" character. If the Tivoli Directory Integrator Entry Attribute represents an XML attribute the "#' character is used to separate the name of the XML attribute from the name of the XML element containing this attribute.

It is possible that the Tivoli Directory Integrator Entry passed contains only Entry Attributes corresponding to the real data. For example, the Entry may contain an Attribute "DocRoot@database@person" without containing an Attribute "DocRoot@database" - the EMF SDOToXML Function Component will automatically create the "database" XML element in the XML document it builds. The EMF SDOToXML Function Component uses the XML Schema to track and create all XML elements that are ancestors of the specified XML element or attribute.

It might happen that the Entry contains Attributes specifying XML elements that are contained in other XML elements specified by Entry Attributes, for example the Entry contains both "DocRoot@database@person" and "DocRoot@database" Attributes. In this case the Attributes are processed starting from the one that is closest to the root, continuing with the one closest to it and so on - the last one will be the most specific XML element that is contained in all the other. This order of processing provides the option to change specific details in a bigger XML context.

For example, if you want to change just the "DocRoot@database@person" element but you want to leave the other parts of the "DocRoot@database" element untouched, you might read the XML document with the EMF XMLToSDO Function Component, map the "DocRoot@database" attribute and provide it to the EMF SDOToXML Function Component as is. Then you will also provide the "DocRoot@database@person" Attribute that contains the specific updates you want to make on the "person" XML element(s). The EMF SDOToXML Function Component will first process the "DocRoot@database" applying all the content to the resulting XML and it will then override the "person" child of the "database" element with whatever is provided in the "DocRoot@database@person" Entry Attribute.

In case a multi-valued Attribute is provided together with an Attribute specifying a child or other successor of that element, the function Component will signal an error (throw exception) because it cannot be determined to which of the sibling XML elements, this successor applies. For example, if "DocRoot@database@person" is provided and contains two values (thus specifying two XML "person" elements at the same level) and also "DocRoot@database@person@name" is provided, the Function Component would not know to which "person" element of the two existing this "name" element applies to. The names of the elements in the Entry Attribute can be XML namespace prefixed.

The names of the elements are prefixed with the namespace URI or with the prefixes defined in the "namespaceMap" parameter.

For example, in order to construct the following XML document:

<?xml version="1.0"?>
<database xmlns="www.ibm.com" xmlns:tmp="www.tmp.com" name="employees">
	<person>
		<name>Ivan</name>
		<tmp:age>21</tmp:age>
	</person>
</database>

the following Tivoli Directory Integrator Entry can be passed to the EMF SDOToXML Function Component:

• DocRoot@ibm:database#ibm:name
• DocRoot@ibm:database@ibm:person@ibm:name
• DocRoot@ibm:database@ibm:person@www.tmp.com:age

The namespace prefixes used assume that the "namespaceMap" parameter contains the "ibm" prefix set to "www.ibm.com" and no namespace prefix is defined for "www.tmp.com" (that is why it is used directly in the Attribute name).

Configuration

XSD File

The parameter specifies the location of the XML Schema File. The XML Schema File is used in the process of generating the XML document and in the Discover Schema functionality. This parameter is required. The extension of the XML Schema File specified must be ".xsd".

Use Namespaces

Specifies whether the Discover Schema functionality will use XML namespaces to prefix the Entry Attribute names. When this parameter is checked XML elements and attributes will be prefixed either with a prefix defined in the "namespaceMap" parameter or with the namespace URI if no prefix is defined in "namespaceMap".

Namespace Map

Defines a mapping between namespace prefixes and namespace URIs. Each pair is specified on a new line. The prefix is delimited from the URI with an equal sign, for example "ibm=http://www.ibm.com". Preceding and trailing white space for both the prefix and the URI is ignored.

Return XML as

Specifies the type of the XML document that will be returned by the Function Component. It can be a java.lang.String object or an org.w3c.dom.Element object.

Encoding

Specifies the character set to use for encoding converting to and from XML. If left blank the default system charset is used.

Debug

Turns on debug messages.

Using the FC

Migration

The EMF XMLToSDO and SDOToXML Function Components are not compatible with the Tivoli Directory Integrator 6.0 Castor Function Components. That is why any solution which uses the Castor Function Components needs to be re-implemented in order to work with the EMF XMLToSDO and EMF SDOToXML Function Components. The Castor XML To Java Function Component used to support a mapping file. This mapping file could be used to specify how a complex custom XML is to be parsed and converted to a complex custom Java object. This feature is not supported by the EMF XMLToSDO Function Component. However by following the next broad guidelines such a Tivoli Directory Integrator 6.0 configuration can be re-implemented to work with the EMF XMLToSDO Function Component:

1. Insert the EMF XMLToSDO Function Component into an AssemblyLine.
2. Set its parameters accordingly.
3. Insert a Script Component into the AssemblyLine right after the EMF XMLToSDO Function Component.
4. Write Javascript code in this Script Component, which extracts the desired data from the SDO DataObject returned by the EMF XMLToSDO Function Component and populates the custom Java Object needed.

The Castor XML To Java Function Component used to support a mechanism which allowed a specific portion of the XML to be mapped to Entry Attributes. The EMF XMLToSDO Function Component does not support this feature. The EMF XMLToSDO Function Component always parses and maps the entire XML to Entry Attribute. By using the Input Attribute Map of the EMF XMLToSDO Function Component, however, only the desired Attributes can be mapped thus emulating the behavior of the Castor XML To Java Function Component.

The Castor Java To XML Function Component used to support a mapping file, which could be used to specify how to serialize a complex Java object into XML (element/attribute names, etc.). The EMF SDOToXML Function Component serializes into XML based on an XML Schema file, that is, the names of elements/attributes, etc. are specified in the XML Schema file specified as a Function Component parameter.