A Managing Configuration Policies Using the OJDL API

This appendix outlines how to use the OJDL API to manage Configuration Policies in Oracle Communications IP Service Activator.

Initial Setup

The following JAR files are required in the application classpath in order to create configuration policies using the OJDL API. They are installed with the Network Processor.

servicemodelextensions.jar contains XML Bean Classes for the Configuration Policy Service Model Extensions.
xbean.jar contains Apache XML Beans API.
jsr173_api.jar contains streaming API for XML, provided as part of the Apache XML Beans API.
ojdl.jar contains IP Service Activator OSS Java Development Library (OJDL) API.

These files are located in the following IP Service Activator installation directory:

Solaris: /opt/OracleCommunications/ServiceActivator/lib/java-lib

If your development environment is on a separate PC you will have to copy the JAR files from an IP Service Activator machine.

Creating a Configuration Policy

Configuration policies are optional XML extensions to the IP Service Activator object model that are supported by the Network Processor cartridges.

A configuration policy can be created using the OJDL API by creating a RuleGeneric object. A RuleGeneric object must have two parent objects: a Policy Type object, and the object to which you want it to apply. The latter object can be an interface, or other applicable objects. For details, refer to the discussion of the RuleGeneric object and the external object model in IP Service Activator OSS Integration Manager Guide.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in samples\com\oracle\communications\ipsa\ojdlSamples. The Configuration Policy XML definition is set in the RuleGeneric ContentValue attribute.

The structure of the XML for each configuration policy is defined by an XML Schema specification in servicemodelextension-api-versionNum.buildNum.zip, which is installed with the IP Service Activator client in the Service_Activator_Home\SamplePolicy folder. An API is provided to programmatically construct the configuration policy XML data structures using Java XML Beans, using the Apache XML Beans technology available at the Apache web site:

http://xmlbeans.apache.org/

The following example includes code which interacts with configuration policy objects using the OJDL APIs.

Creating the Configuration Policy Data Type

Each configuration policy top level XML element is represented by an XML Beans Document class. For example, the StaticNats configuration policy is created as a StaticNatsDocument object. Refer to "Configuration Policy Classes" for the complete configuration policy class mapping.

The content of the StaticNats object is set using the XML Beans API.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in the samples directory.

Creating the RuleGeneric Object to Contain the Configuration Policy

Configuration Policy objects are represented in the IP Service Activator External Object Model (EOM) as RuleGeneric objects. The following two attributes must be set:

ContentType: the configuration policy type
ContentValue: the configuration policy xml string

The ContentValue configuration policy XML is generated by invoking the toString() function.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in the samples directory.

When passing XML strings into the EOM object attributes, some special characters need to be escaped by pre-pending an additional \ character. For example, \" and \' must be fully escaped to \\\" and \\\' respectively. This conversion is performed by the escapeForOIM() function provided in the example.

Assigning the Configuration Policy to the Required Device and Interface Roles

The RuleGeneric object can be created as a child of many objects in the object hierarchy (as documented in IP Service Activator OSS Integration Manager Guide). However, the policy object Concrete is applied on any of the Interface objects in the inheritance hierarchy that match the RuleGeneric Roles. The RuleGeneric device and interface roles must match the device and interface roles on the interface where the configuration policy is applied.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in the samples directory.

Modifying a Configuration Policy

Modification of a configuration policy involves querying the object model for the current configuration policy definition, modifying the configuration policy, and updating the whole definition back into the object model.

Querying the EOM for the Configuration Policy

The configuration policy XML can be obtained from the RuleGeneric ContentValue parameter. The XML is parsed back into the XML Beans object definition of the service model extension.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in the samples directory.

As with creating the configuration policy, the XML content of RuleGeneric is updated to handle the extra escape characters around the \" and \' characters. This conversion is performed by the unescapeFromOIM() function.

Modifying the Policy Definition

The configuration policy definition is modified using the XML Bean API for the service model extension documents.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the StaticNATsConfigurationPolicyExample file in the samples directory.

Registering an Interface Policy

Creating a new interface in IP Service Activator through the OIM and OJDL APIs involves a specialized use of configuration policies with the interface configuration management framework. As with interface management through IP Service Activator, there are three types of interface management interactions:

Main interface creation
Subinterface creation
Interface decoration

Each possible interaction must be registered as an Interface Policy Registration. The Interface Policy Registration objects can either be pre-configured in IP Service Activator, or created using the IP Service Activator APIs.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the nterfaceManagementPolicyExample file in the samples directory.

Once an Interface Policy Registration is used to create or decorate an interface it cannot be modified or deleted until all dependent parent interfaces have been deleted or unlinked from the policy registration.

Creating a Subinterface

This section describes how to create a new interface in IP Service Activator so that the new interface configuration will also be correctly provisioned on the device.

As a prerequisite the appropriate subinterface creation Interface Policy Registration must be created.

Creating the Subinterface Object

Create a new subinterface object under the target interface. For consistency, it is recommended that you create the child subinterface with the correct ifType, although IP Service Activator will update this value on the next device discovery.

The following example shows the creation of a new subinterface:

// Create the new subinterface interface object
String subinterfaceName = "Serial1/3.100";
attributes = new EomAttributesSet();
attributes.setAttribute("Type", "32");
EomObject subinterface = tr.createObject(parentInterface, "Subinterface",
  subinterfaceName, attributes);

Linking the New Subinterface Object to the Interface Policy Registration

The created subinterface object is linked to the previously defined Interface Policy Registration. The act of linking the policy registration automatically creates a new RuleGeneric configuration policy object with the correct data type settings based on the Interface Policy Registration definition.

The following example shows the linking of the subinterface object with the interface policy registration:

 // Link the new subinterface object to the interface policy registration
 tr.linkObjects(subinterface, registrationPolicy);
 tr.commit();

The new RuleGeneric object name consists of the interface names with -Data appended to it.

Modifying the Interface Configuration Policy Data

The interface management configuration policy does not contain any default settings. These must be manually created using the appropriate XML data structure for the configuration policy data type defined in the interface registration policy. The XML content can be created manually or using the XML Beans API provided.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the InterfaceManagementPolicyExample file in the samples directory.

Linking the New Subinterface to an Interface Role

Up to this point the new subinterface has only been created in the IP Service Activator object model. Before committing the subinterface creation to the device, the new subinterface object must be linked to an appropriate interface role.

There are code examples available in the additional documentation included with the OJDL libraries. For more information, see the InterfaceManagementPolicyExample file in the samples directory.

Optionally Discovering the Device

Optionally, the device can be re-discovered to align any interface changes (such as to the ifType or VC objects) with the object model. For interface types that have child VC object created by the configuration (such as the framerelay DLCI) device re-discovery is recommended.

The following example shows the optional device discovery:

// Optionally rediscover the device the get any VC level objects (in this example
// the DLCI)
eomSession.sendCommandtoOIM("discover " + parentDeviceId);

Creating a Main Interface

The steps for main interface creation are largely the same as for subinterface creation. For a main interface, the new interface is created as a child of the device and is linked to an appropriate Interface type Interface Policy Registration object.

When creating a main interface, the Interface Policy Registration must define the default capabilities that the interface (and its sub-interfaces and VCs) will be assigned. If the default settings are used, the created interface will not have any capabilities assigned and a capabilities reset and re-discovery must be performed instead.

Decorating an Interface

For interface decoration, follow the same steps as with subinterface creation, with the exception that the interface does not need to be created first. For interface decoration, the existing interface must be linked to a Decorate type Interface Policy Registration object.

Comparing Created and Discovered Interfaces

It is possible to determine if an interface was created using the IP Service Activator interface configuration management framework or was initially discovered from the device by inspecting the IsConfigurable parameter on the Interface or SubInterface object.

If IsConfigurable is set to True then the interface was created within IP Service Activator. If it is set to False then the interface was added through discovery.

Configuration Policy Classes

Table A-1 lists the configuration policy classes.

Table A-1 Configuration Policy Classes

Extension	Configuration Policy	Java XMLBeans Class
AlcatelSamAccessInterfaceModule	alcatelSRL3Interface	com.metasolv.serviceactivator.alcatelSamAccessInterface.AlcatelSRL3InterfaceDocument
AlcatelSamAggregatedSchedulerModule	alcatelSamAggregatedScheduler	com.metasolv.serviceactivator.alcatelSamAggregatedScheduler.AlcatelSamAggregatedSchedulerDocument
AlcatelSamQosOverridePolicyModule	alcatelSamQosOverridePolicy	com.metasolv.serviceactivator.alcatelSamQosOverridePolicy.AlcatelSamQosOverridePolicyDocument
alcatelSamQosPoolModule	alcatelSamQosPool	com.metasolv.serviceactivator.alcatelSamQosPool.AlcatelSamQosPoolDocument
alcatelSamSchedulerOverridePolicyModule	alcatelSamSchedulerOverridePolicy	com.metasolv.serviceactivator.alcatelSamSchedulerOverridePolicy.AlcatelSamSchedulerOverridePolicyDocument
AtmPvcVcClassModule	atmPvcVcClass	com.metasolv.serviceactivator.atmpvcvcclass.AtmPvcVcClassDocument
CatOSPolicingRuleModule	catOSPolicingRule	com.metasolv.serviceactivator.catospolicingrule.CatOSPolicingRuleDocument
CiscoEthernetPortCharacteristicsModule	ciscoEthernetPortCharacteristics	com.metasolv.serviceactivator.ciscoEthernetPortCharacteristics.CiscoEthernetPortCharacteristicsDocument
CiscoQosPfcTxPortQueuesModule	ciscoQosPfcTxPortQueues	com.metasolv.serviceactivator.ciscoqospfctxportqueues.CiscoQosPfcTxPortQueuesDocument
DlswModule	dlswDevice	com.metasolv.serviceactivator.dlsw.DlswDeviceDocument
DlswModule	dlswEthernetInterface	com.metasolv.serviceactivator.dlsw.DlswEthernetInterfaceDocument
DlswModule	dlswTokenRingInterface	com.metasolv.serviceactivator.dlsw.DlswTokenRingInterfaceDocument
InterfaceConfigMgmtModule	atmSubInterfaceData	com.metasolv.serviceactivator.subinterface.AtmSubInterfaceDataDocument
InterfaceConfigMgmtModule	backUpInterfacePolicy	com.metasolv.serviceactivator.subinterface.BackUpInterfacePolicyDocument
InterfaceConfigMgmtModule	basicRateInterfaceData	com.metasolv.serviceactivator.subinterface.BasicRateInterfaceDataDocument
InterfaceConfigMgmtModule	ciscoUniversalInterface	com.metasolv.serviceactivator.subinterface.CiscoUniversalInterfaceDocument
InterfaceConfigMgmtModule	dialerInterface	com.metasolv.serviceactivator.subinterface.DialerInterfaceDocument
InterfaceConfigMgmtModule	e1ChannelizedSerialInterface	com.metasolv.serviceactivator.subinterface.E1ChannelizedSerialInterfaceDocument
InterfaceConfigMgmtModule	e1Controller	com.metasolv.serviceactivator.controller.E1ControllerDocument
InterfaceConfigMgmtModule	e3ChannelizedSerialInterface	com.metasolv.serviceactivator.subinterface.E3ChannelizedSerialInterfaceDocument
InterfaceConfigMgmtModule	e3Controller	com.metasolv.serviceactivator.controller.E3ControllerDocument
InterfaceConfigMgmtModule	frSubInterfaceData	com.metasolv.serviceactivator.subinterface.FrSubInterfaceDataDocument
InterfaceConfigMgmtModule	hsrp	com.metasolv.serviceactivator.hsrp.HsrpDocument
InterfaceConfigMgmtModule	loopbackInterfaceData	com.metasolv.serviceactivator.subinterface.LoopbackInterfaceDataDocument
InterfaceConfigMgmtModule	multilinkInterface	com.metasolv.serviceactivator.subinterface.MultilinkInterfaceDocument
InterfaceConfigMgmtModule	plPosInterfaceData	com.metasolv.serviceactivator.subinterface.PlPosInterfaceDataDocument
InterfaceConfigMgmtModule	pppMultilink	com.metasolv.serviceactivator.subinterface.PppMultilinkDocument
InterfaceConfigMgmtModule	stm1ChannelizedSerialInterface	com.metasolv.serviceactivator.subinterface.Stm1ChannelizedSerialInterfaceDocument
InterfaceConfigMgmtModule	stm1Controller	com.metasolv.serviceactivator.controller.Stm1ControllerDocument
InterfaceConfigMgmtModule	t1ChannelizedSerialInterface	com.metasolv.serviceactivator.subinterface.T1ChannelizedSerialInterfaceDocument
InterfaceConfigMgmtModule	t1Controller	com.metasolv.serviceactivator.controller.T1ControllerDocument
InterfaceConfigMgmtModule	t3ChannelizedSerialInterface	com.metasolv.serviceactivator.subinterface.T3ChannelizedSerialInterfaceDocument
InterfaceConfigMgmtModule	t3Controller	com.metasolv.serviceactivator.controller.T3ControllerDocument
InterfaceConfigMgmtModule	virtualTemplateInterface	com.metasolv.serviceactivator.subinterface.VirtualTemplateInterfaceDocument
InterfaceConfigMgmtModule	vlanSubInterface	com.metasolv.serviceactivator.subinterface.VlanSubInterfaceDataDocument
InterfaceConfigMgmtModule	vrfExportRouteFilter	com.metasolv.serviceactivator.vrfexportroutefilter.VrfExportRouteFilterDocument
IpsecModule	IPsecModule	com.metasolv.serviceactivator.ipsecmodule.IpsecmoduleDocument
LspModule	lspTunnel	com.metasolv.serviceactivator.lsp.LspTunnelDocument
L2QosModule	rateLimit	com.metasolv.serviceactivator.l2Qos.RateLimitDocument
JuniperQosCosAttachmentModule	juniperQosCosAttachment	com.metasolv.serviceactivator.juniperqoscosattachment.JuniperQosCosAttachmentDocument
MiscPluginsModule	atmVcClass	com.metasolv.serviceactivator.vcclass.AtmVcClassDocument
MiscPluginsModule	banners	com.metasolv.serviceactivator.banner.BannersDocument
MiscPluginsModule	bgpCE	com.metasolv.serviceactivator.bgpce.BgpCEDocument
MiscPluginsModule	dailerList	com.metasolv.serviceactivator.dialerList.DialerListDocument
MiscPluginsModule	dslInterfaceData	com.metasolv.serviceactivator.subinterface.DslInterfaceDataDocument
MiscPluginsModule	extendedAcl	com.metasolv.serviceactivator.extendedAcl.ExtendedAclDocument
MiscPluginsModule	ipPools	com.metasolv.serviceactivator.ippool.IpPoolsDocument
MiscPluginsModule	keyChains	com.metasolv.serviceactivator.keyChain.KeyChainsDocument
MiscPluginsModule	saveConfig	com.metasolv.serviceactivator.saveConfig.SaveConfigDocument
MiscPluginsModule	staticNats	com.metasolv.serviceactivator.staticnat.StaticNatsDocument
MiscPluginsModule	staticRoutes	com.metasolv.serviceactivator.staticroute.StaticRoutesDocument
MiscPluginsModule	userAuth	com.metasolv.serviceactivator.userAuth.UserAuthDocument
MiscPluginsModule	userData	com.metasolv.serviceactivator.userData.UserDataDocument
MulticastModule	multicastAutoRp	com.metasolv.serviceactivator.multicast.MulticastAutoRpDocument
MulticastModule	multicastBootstrapRouter	com.metasolv.serviceactivator.multicast.MulticastBootstrapRouterDocument
MulticastModule	multicastDevice	com.metasolv.serviceactivator.multicast.MulticastDeviceDocument
MulticastModule	multicastInterface	com.metasolv.serviceactivator.multicast.MulticastInterfaceDocument
MulticastModule	multicastVrf	com.metasolv.serviceactivator.multicast.MulticastVrfDocument
PrefixListModule	prefixListEntries	com.metasolv.serviceactivator.prefixlist.PrefixListEntriesDocument
QosCosAttachmentModule	qosCosAttachment	com.metasolv.serviceactivator.qoscosattachment.QosCosAttachmentDocument
RoutePolicyModule	bgpRoutePolicy	com.metasolv.serviceactivator.routePolicy.BgpRoutePolicyDocument
RoutePolicyModule	vrfRoutePolicy	com.metasolv.serviceactivator.routePolicy.VrfRoutePolicyDocument
SubInterfaceModule	plSerialInterfaceData	com.metasolv.serviceactivator.subinterface.PlSerialInterfaceDataDocument
ServiceAssuranceModule	collectorParameters	com.metasolv.serviceactivator.collectorParameters.CollectorParametersDocument
ServiceAssuranceModule	netflowParameters	com.metasolv.serviceactivator.netflowParameters.NetflowParametersDocument
ServiceAssuranceModule	rtrResponder	com.metasolv.serviceactivator.rtrr.RtrResponderDocument
SgbpModule	sgbp	com.metasolv.serviceactivator.sgbp.SgbpDocument
SnmpModule	snmpCommunities	com.metasolv.serviceactivator.snmp.SnmpCommunitiesDocument
SnmpModule	snmpHosts	com.metasolv.serviceactivator.snmp.SnmpHostsDocument
VlanModule	vlanDefinitions	com.metasolv.serviceactivator.vlanModule.VlanDefinitionsDocument
VlanInterfaceModule	mgmtVlanInterface	com.metasolv.serviceactivator.vlanInterface.MgmtVlanInterfaceDocument
VlanInterfaceModule	vlanInterface	com.metasolv.serviceactivator.vlanInterface.VlanInterfaceDocument
VrfCustomNamingModule	vrfCustomNaming	com.metasolv.serviceactivator.vrfCustomNaming.VrfCustomNamingDocument
VrfIPsecModule	customerIPsec	com.metasolv.serviceactivator.vrfipsec.CustomerIPsecDocument
VrfIPsecModule	publicIPsec	com.metasolv.serviceactivator.vrfipsec.PublicIPsecDocument

Example Source Code

There are code examples available in the additional documentation included with the OJDL libraries.

For configuration policy example source code, see the StaticNATsConfigurationPolicyExample file in the samples directory.

For interface management example source code, see the InterfaceManagementPolicyExample file in the samples directory.