|
Hierarchy Developer's Guide for Oracle Self-Service E-Billing > Extending Advanced Hierarchy Manager Use Cases > Making OMF Objects Work with Hierarchy Manager >
Supporting XML Exchange
The following topics describe how to configure XML exchanges in Hierarchy Manager. Configuring XML Schema for Your Business Object
The Hierarchy Manager importer is flexible enough to import hierarchy relationships as well as link target content. You can decide whether the importer and exporter handles only relationships or also handles link target content. To meet these requirements, Hierarchy Manager provides two XML schema definition files:
- Common-hierarchy-interchange-1.0.xsd. Specifies the format that is core to Hierarchy Manager. Do not change this file. Use the file as is.
- Instance-hierarchy-interchange-1.0.xsd. Customizes the hierarchy structure. You can add one or more sections to describe application-specific business objects, or link targets, in the import or export XML file.
The Instance-hierarchy-interchange-1.0.xsd file is referenced in the common-hierarchy-interchange-1.0.xsd schema file. So in preparing an XML data file, you only need to reference the common-hierarchy-interchange-1.0.xsd file as shown in the following example: <?xml version="1.0" encoding="ISO-8859-1"?>
<ListOfHierarchies xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="common-hierarchy-interchange-1.0.xsd">
Link target can be defined in the instance-hierarchy-interchange.1.0.xsd file, such as:
<xs:element name="CostCenter">
<xs:complexType>
<xs:attribute name="name" type="xs:string"/>
<xs:attribute name="fiscalCode" type="xs:string"/>
<xs:attribute name="manager" type="xs:string"/>
</xs:complexType>
</xs:element>
In the XML data file, a node that represents a cost object can be expressed as the following example: <Node>
<BusinessObject>
<CostCenter name="PS", fiscalCode="10001" manager="Joe Smith"/>
</BusinessObject>
<CanBeAccessedBy>
<userId>jsmith</userId>
<userId>jane</userId>
</CanBeAccessedBy>
</Node>
Example of Writing Your Own Link Target Exchange Handler
The following example shows how to define your own link target exchange handler: package com.edocs.common.api.hierarchy.connector;
public interface IHierarchyXMLExchangeHandler
{
/**
* Processes the information passed through a domObject to see if
* it can be added to the Hierarchy.
* @param domObject XML DOM representation of the OMF object
* @param period that will be used to validate link target
* @return An Instance of {@link ImportLinkTargetValidationStatus} to indicate
* what action should be taken by the XMLContentHandler
*/
public ILinkTargetImportResult validateLinkTarget(Document domObject,
IPeriod period);
/**
* Processes the information passed through a domObject. Either find
* the specified link target object or create a new link target with
* the supplied information.
* @param domObject XML DOM representation of the OMF object
* @return created or found link target (OMF object)
*/
public IHierarchyLinkTarget importLinkTarget(Document domObject)
throws HierarchyException;
/**
* Used for delta hierarchy import processing
* @param domObject object representing the link target.
* @param isNew boolean indicating whether the hierarhcy to be imported is a new.
* @return a converted link target object.
* @throws HierarchyException
*/
public IHierarchyLinkTarget importDeltaLinkTarget(Document domObject,
boolean isNew) throws HierarchyException;
/**
* Converts the link target (OMF object) into XML.
*
* @param linkTarget the link target object to be exported.
* @return XML representation of the OMF object.
*/
public String exportLinkTarget(IHierarchyLinkTarget linkTarget)
throws HierarchyException;
/**
* Initializes this exchange handler with the XmlTag to use.
* @param xmlTag the tag string for given type of link target class.
*/
public void initialise(String xmlTag);
}
By implementing this interface, you can decide the rule for valid objects; whether the business object must be created by the Hierarchy Manager importer when the object does not already exist. The ValidateLinkTarget() method is the first one called on your XMLExchangeHandler during the process of importing. You can put your own logic in the validation. For example, if the object you are handling does not exist when the hierarchy is imported, you can decide whether to stop the importer from continuing, or just skip over the object and continue to import the rest of the hierarchy. ILinkTargetImportResult returns validation results and other context information for each link target being imported: package com.edocs.common.api.hierarchy.connector.exchange;
public interface ILinkTargetImportResult
{
/**
* Returns the link target element tag.
* @return the link target element tag.
*/
public String getTag();
/**
* Returns the status of import.
* @return the status of import.
*/
public ImportLinkTargetValidationStatus getStatus();
/**
* Returns a list of attribute errors, if any.
* @return a list of attribute errors, if any.
*/
public List getAttributeErrors();
/**
* Returns the identifier.
* @return the identifier.
*/
String getIdentifier();
}
ImportLinkTargetValidationStatus contains the result of link target validation with the following possible values:
- PASS. Indicates that validation passed.
- WARN_SKIP. Indicates that there is a warning message. The link target to be imported must be skipped. For example, will not be linked into the hierarchy.
- WARN_INCLUDE. Indicates that there is a warning message. However, the link target to be imported will be included in the hierarchy tree.
- FAIL_END. Indicates that there is an error. However, the importer process can continue with a failure message at the end.
- FAIL_NOW. Indicates that there is a fatal error and the importer process must end immediately.
By returning different status code, your validation method can tell the importer what to do next. Transactions in Hierarchy Manager Importer
Operations that create data using the importer are bounded into a single database transaction. Changes made to the database are not committed until the importer commits the changes. You can configure the commit size and approach. Modify the HierarchyImporter.xma.xml file: <bean id="HierarchyXMLContentHandler" class="com.edocs.common.hierarchy.connector.exchange.HierarchyXMLContentHandler" singleton="false">
<constructor-arg index="0">
<ref bean="IHierarchyManager"/>
</constructor-arg>
<constructor-arg index="1">
<ref bean="IHierarchyTypeManager"/>
</constructor-arg>
<constructor-arg index="2">
<ref bean="TransactionManager"/>
</constructor-arg>
<constructor-arg index="3">
<ref bean="IHierarchyPeriodValidationManager"/>
</constructor-arg>
<constructor-arg index="4">
<bean class="com.edocs.common.xma.api.LookupBeanFactoryBean">
<property name="beanUri">
<value>edx:platform://modules/omf?id=periodManager</value>
</property>
</bean>
</constructor-arg>
<property name="commitedBatchSize"><value>200</value><!-- 200 records --></property>
<property name="batchCommitEnable"><value>true</value></property>
<property name="transactionHoldingTime"><value>5</value><!-- holding the transaction for 5 minutes max --></property>
</bean>
| 
