Hierarchy Developer's Guide for Oracle Billing Insight > Extending Advanced Hierarchy Manager Use Cases > Making OMF Objects Work with Hierarchy Manager >

Implementing Hierarchy Manager Interfaces

This topic describes the Hierarchy Manager interfaces.

IHierarchyLinkTarget Hierarchy Interface

To link your business object through hierarchy, first implement the IHierarchyLinkTarget interface.

public interface IHierarchyLinkTarget extends IOMFObject
{
/**
* This is the link target identifier. This id is decided by the actually link target implementation.
* For example, the link target id for IAccount is account number, for IService is account number
* and service number. Note, this id only unique identify this object in a special domain. For example,
* the account number is guaranteed unique only for the accounts for a particular billing system.
* @return link target id string
*/
public String getLinkTargetId();

/**
* This is the link target name. This sometimes can be the same as the link target Id.
* But usually this is a short, descriptive name that can stand for the link target id,
* but looks nicer on the UI.
* @return link target name.
*/
public String getLinkTargetName();
/**
* Returns true if this object has one or more properties that are modifiable.
*
* @return true if this object is modifiable through hierarchy.
*/
public boolean isEditable();
/**
* Returns true if the specified property is modifiable through hierarchy.
* @param propertyName - the name of a property.
* @return true if property is modifiable.
*/
public boolean isEditable(String propertyName);
}

The values returned from the getLinkTargetId() and getLinkTargetName() methods will be persisted with the hierarchy tree node, and be used to display and quickly search the object inside the tree. The IsEditable() method indicates whether your object can be edited through the hierarchy tree. Method isEditable(String) specifies which attributes of the object can be edited if the object is editable.

IHierarchyXMLExchangeHandler Hierarchy Interface

Based on the schema provided by each application, Hierarchy Manager allows you to provide their own handlers to handle both import and export of the business objects. providing flexibility in deciding how the Hierarchy Manager importer is used in an application.

If you would like to interchange (import or export) your hierarchy data structure with another part of the application or with an external system through XML, you must implement this interface.

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, which determines whether the given business object must be created by the hierarchy importer, if the object does not already exist.

ILinkTargetEventHandler Hierarchy Interface

If you need to run reports against your link target through Hierarchy Manager, and your link target data are stored in OLAP, then you must implement this handler. When the hierarchy is changed on the OLTP side, the hierarchy OLAP synchronizer invokes your handler to synchronize hierarchy and the relationship with your link target on the OLAP side.

package com.edocs.common.api.hierarchy.connector;

public interface ILinkTargetEventHandler
{
/**
* Hook that is called when adding a new link target.
* @param event the event object
* @throws DataStoreException thrown if database errors occurred.
*/
public void processAddEvent(IEvent event) throws DataStoreException;

/**
* Hook that is called when adding a node to a period.
* @param event the event object
*/
public void processNodePeriodAddEvent(IEvent event);

/**
* Hook called when removing a link target from hierarchy tree.
* @param event the event object that contains information about the event.
* @throws DataStoreException thrown if database errors occurred.
*/
public void processRemoveEvent(IEvent event) throws DataStoreException;

/**
* Hook called when removing a hierarchy.
* @param event the event object that contains information about the event.
*/
public void processRemoveHierarchyEvent(IEvent event);

/**
* Hook called when a node is removed from a period.
* @param event the event object that contains information about the event.
*/
public void processNodePeriodRemoveEvent(IEvent event);

/**
* Hook called for moving a node to a different node.
* @param event the event object that contains information about the event.
*/
public void processMoveEvent(IEvent event);

/**
* Hook called when publishing hierarchy. Implementing class needs to override
this method
* to deal with any link target related operation.
* @param event the event object that contains information about the event.
*/
public void processPublishEvent(IEvent event);

/**
* Hook called when expiring a hierarchy.
* @param event the event object that contains information about the event.
*/
public void processExpireHierarchy(IEvent event);
}

Configuring Link Targets

Register link targets for new business objects with Hierarchy Manager by adding LinkTargetConfig beans to the hierarchy.cfg.xma.xml file.

Hierarchy Manager provides a framework that handles a variety of hierarchy-related operations, including object definition, creation, lookup, resolving a linkage, XML exchange, and OLTP to OLAP synchronization. Link targets are highly configurable so that application-specific business objects can provide their own implementations as needed.

Not all handlers are required for all business objects. You can decide which handlers to implement based on application requirements. Here are some examples in the hierarchy.cfg.xma.xml file:

<bean id="ServiceAgreementConfig" class="com.edocs.common.hierarchy.core.LinkTargetConfig" singleton="true">
<property name="targetType"><value>edx:omf:serviceagreement:</value></property>
<property name="targetTypeName"><value>Service Agreement</value></property>
<property name="displayName"><value>getLinkTargetName</value></property>
<property name="xmlTag"><value>ServiceAgreement</value></property>
<property name="storedHierXRef"><value>false</value></property>
<property name="xmlExchangeHandler">
<beanclass="com.edocs.common.omf.serviceagreement.ServiceAgreementXMLExchangeHandler"/>
</property>
<property name="linkTargetEventHandlers">
<list>
<bean class="com.edocs.common.hierarchy.connector.olap.OLAPServiceAgreementHandler"/>
</list>
</property>
</bean>

Table 2 describes the link target properties in the hierarchy.cfg.xma.xml file.

The following code from the hierarchy.cfg.xma.xml file shows an example of the linkTargetEventHandler:

<bean id="ChargeTypeConfig" class="com.edocs.common.hierarchy.core.LinkTargetConfig" singleton="true">
<property name="targetType"><value>edx:omf:chargetype:</value></property>
<property name="targetTypeName"><value>Charge</value></property>
<property name="displayName"><value>getLinkTargetName</value></property>
<!-- my list of customize handlers to handle charge type. -->
<property name="linkTargetAddEventHandlers">
<list>

lass="com.edocs.common.hierarchy.connector.olap.OLAPChargeTypeHandler"/>
</list>
</property>
</bean>

<bean id="HierarchyFolderConfig" class="com.edocs.common.hierarchy.core.LinkTargetConfig" singleton="true">
<property name="targetType"><value>edx:hierarchy:folder:</value></property>
<property name="targetTypeName"><value>Hierarchy Folder</value></property>
<property name="displayName"><value>getLinkTargetName</value></property>
<property name="xmlTag"><value>Folder</value></property>
<property name="xmlExchangeHandler">
<bean

<bean cclass="com.edocs.common.hierarchy.connector.exchange.FolderXMLExchangeHandler"/>
</property>
</bean>

ean id="CompanyConfig" class="com.edocs.common.hierarchy.core.LinkTargetConfig" singleton="true">
<property name="targetType"><value>edx:omf:company:</value></property>
<property name="targetTypeName"><value>Company</value></property>
<property name="displayName"><value>getLinkTargetName</value></property>
<property name="xmlTag"><value>Company</value></property>
<property name="xmlExchangeHandler">
<bean class="com.edocs.common.omf.company.CompanyXMLExchangeHandler">
<constructor-arg index="0">
<bean class="com.edocs.common.xma.api.LookupBeanFactoryBean">
<property name="beanUri">
<value>edx:platform://modules/omf?id=companyManager</value>
</property>
</bean>
</constructor-arg>
</bean>
</property>
</bean>

<bean id="AccountConfig" class="com.edocs.common.hierarchy.core.LinkTargetConfig" singleton="true">
<property name="targetType"><value>edx:amf:billingaccount:</value></property>
<property name="targetTypeName"><value>hierarchy.element.class.Account</value></property>
<property name="displayName"><value>getLinkTargetName</value></property>
<property name="xmlTag"><value>Account</value></property>
<property name="xmlExchangeHandler">
<bean class="com.edocs.domain.telco.amf.defaultimpl.BillingAccountXMLExchangeHandler">
<constructor-arg index="0">
<bean class="com.edocs.domain.telco.amf.defaultimpl.BillingAccountManager" singleton="true"/>
</constructor-arg>
</bean>
</property>
<property name="linkTargetEventHandlers">
<list>
<bean class="com.edocs.common.hierarchy.connector.olap.OLAPAccountHandler"/>
</list>
</property>
</bean>

<bean id="ServiceChargeConfig" class="com.edocs.common.hierarchy.core.LinkTargetConfig" singleton="true">
<property name="targetType"><value>edx:omf:servicecharge:</value></property>
<property name="targetTypeName"><value>hierarchy.element.class.ServiceCharge</value></property>
<property name="displayName"><value>getLinkTargetName</value></property>
<property name="xmlTag"><value>ServiceCharge</value></property>
<property name="xmlExchangeHandler">
<bean class="com.edocs.common.omf.servicecharge.ServiceChargeXMLExchangeHandler"/>
</property>
<!-- my list of customize handlers to handle charge type. -->
<property name="linkTargetEventHandlers">
<list>
<bean class="com.edocs.common.hierarchy.connector.olap.OLAPServiceChargeHandler"/>
</list>
</property>
</bean>

Configuring the Link Target into a Hierarchy Type

Add the new config bean for the new link target to the hierarchy type config where the business object must be linked. See the following example code in the hierarchy.cfg.xma.xml file:

<bean id="BusinessHierarchyType" class="com.edocs.common.hierarchy.core.HierarchyTypeConfig">
<property name="name"><value>hierarchy.type.Business</value></property>
<property name="code"><value>BUSINESS</value></property>
<property name="description"><value>Business hierarchy</value></property>
<property name="validLinkTargets">
<list>
<ref bean="HierarchyFolderConfig"/>
<ref bean="CompanyConfig"/>
<ref bean="ServiceAgreementConfig"/>
<ref bean="ServiceChargeConfig"/>
</list>
</property>
<property name="linkTargetRelationship">
<list>
<!-- if any of the link target is not defined below, then by default it can have any type of valid -->
<!-- link target defined above as it children -->
<!-- Service agreement is a leaf node -->
<bean class="com.edocs.common.hierarchy.core.LinkTargetRelationship">
<property name="parent"><ref bean="ServiceAgreementConfig"/></property>
</bean>
<!-- Company can have folder, and account as it children -->
<bean class="com.edocs.common.hierarchy.core.LinkTargetRelationship">
<property name="parent"><ref bean="CompanyConfig"/></property>
<property name="validChildren">
<list><ref bean="HierarchyFolderConfig"/></list>
</property>
</bean>
</list>
</property>
</bean>