DynamicTMN® Java EBTA XML Manager Api

IEC61850/MMS OSI TL1 CMIP SNMP Agent Manager Simulator

Features | Classes | Examples | Standards | Related

The eBonding/TA XML Manager Gateway API is a high-level Java XML API for use in the implementation of CMIP Electronic Bonding Manager Gateways for Trouble Administration (EBTA) and Mechanized Loop Test (MLT). It provides an external ANSI T1.227/228/262 compliant CMIP eBonding Manager interface for communication with your trading partner's EBTA CMIP Agent Gateway and an ANSI T1.277/278 XML messaging backend for easy integration with your own internal trouble ticketing and administration system (eg. Remedy, Clarify, proprietary legacy, etc).

API Features

Some of the key features of the eBonding/TA XML Manager Gateway API are:

100% Java (Java 2 SDK version 1.2 or greater)
uses the eBonding/TA XML Translator API for XML to CMIS translations
ANSI standard compliant CMIP and XML interfaces.
transparent translation between XML and CMIS
encapsulates all GDMO, CMIS and ASN.1 API interaction
you only need to implement to XML transport interface
easy integration with existing trouble administration systems
generic API transparently handles all types of EBTA and MLT messages
may be used with other Java/XML technologies (SOAP,WSDL,JMS, etc)

eBonding/TA XML Manager Gateway API Classes

The eBonding/TA XML Manager Gateway API provides a high-level XML-oriented Java programming interface which uses the tML-TA and tML-ServiceTest XML request, response and notification messages as the primary messaging interface with the API user.

The XML manager API classes used directly by most manager gateway implementations are:

XmlEBTAManagerApi
XmlEBTAPendingRequest
XmlEBTANotificationListener
XmlEBTAPendingNotification

The XmlEBTAManagerApi class provides the top-level interface to the manager API functionality. It uses the eBonding/TA XML Translator API to provide automatic translation between tML-TA/tML-ServiceTest XML messages and CMIS messages. It includes a set of translation functions which accept an XML request message and return an XmlEBTAPendingRequest instance which represents that request.

The XmlEBTAPendingRequest instance returned by the XmlEBTAManagerApi is then used to send the translated CMIS request, receive the corresponding CMIS response and translate the CMIS response into the appropriate XML response message which is then made available to the API user. All of this is done without exposing the API user to the details of the CMIS messaging. The API user only works with the XML message elements.

The XmlEBTANotificationListener interface may be implemented by the application and registered with the XmlEBTAManagerApi in order to receive incoming EBTA notifications in the form of automatically translated XML notification elements. The listener defines a single method which accepts an XmlEBTAPendingNotificationinstance containing the translated tML-TA XML Notification message along with methods to send the notification confirmation as required by most eBonding gateways.

See the examples in the next section to get a better idea of just how simple it is to develop an EBTA manager using this API.

eBonding/TA XML Manager Gateway API Examples

The following example shows how to create and initialize an XmlEBTAManagerApi instance for use in an eBonding Manager Gateway application:


   // -- 
   // -- Create and initialize a Config object 
   // -- 
   XmlEBTATranslatorApi.Config config 
                     = new XmlEBTATranslatorApi.Config();
   config.isPackagesGenerated(true);
   config.isAutoSetSchemaInfo(true);
   

   // -- 
   // -- Create the translator API instance
   // -- 
   XmlEBTATranslatorApi trans_api =
			 XmlEBTATranslatorApi.newInstance(config);

   // -- 
   // -- Create the XML Manager API instance
   // -- 
   XmlEBTAManagerApi manager_api = 
                         new XmlEBTAManagerApi(trans_api);

   // -- 
   // -- Configure the response timeout value
   // -- 
   manager_api.setRequestTimeoutSecs(10);

The next code segment shows an example of the typical manager role XML to CMIS processing using the eBonding/TA XML Manager Gateway API.

   
   

   // -------------------------------------------------------
   // -- RECEIVE XML REQUEST FROM THE TROUBLE ADMIN SYSTEM --
   // -------------------------------------------------------
   

   // --
   // -- receive an XML request through your preferred transport
   // -- like JMS, SOAP, etc
   // --
   Element xml_req =  ...;

   // --
   // -- translate the XML request to an XML pending request 
   // -- (this includes translating the XML to CMIS Request) 
   // --
   XmlEBTAPendingRequest pr = 
                    manager_api.translateRequest(xml_req);

   // --
   // -- SEND the CMIS request to the CMIS EBTA agent gateway
   // --
   pr.send();

   // --
   // -- wait for the CMIS response from the agent gateway
   // --
   pr.awaitResponse();

   // --
   // -- get the translated tML-TA/ServiceTest XML response 
   // --
   Element xml_rsp = pr.getResponseElement();

   // --
   // -- now send the XML response back using your preferred 
   // -- transport ike JMS, SOAP, etc
   // --
   
   

   // ------------------------------------------------------
   // -- SEND XML RESPONSE TO YOUR TROUBLE ADMIN SYSTEM   --
   // ------------------------------------------------------

While this may not seem like much code, it is actually doing quite a large amount of work including:

translating an tML-TA/ServiceTest XML Request to a CMIS Request - uses the eBonding/TA XML Translator API - supports all tML-TA and tML-ServiceTest messages supported by translator
sending the CMIS request to the approriate eBonding Agent Gateway - uses the naming service to lookup the approriate agent gateway - will establish the secure association if needed - uses the CMIS API for underlying messaging
synchronously awaiting the response - waits for the CMIS response or message timeout - (note that you can also use a listener-based asynchronous API)
translates the CMIS response to a tML-TA/ServiceTest XML response
makes the tML-TA/ServiceTest XML response available to the API user

In order to use this API for your manager gateway development you simply need to implement the XML transport mechanism for communication with your trouble administration system then configure your trouble administration system to use the tML-TA and tML-ServiceTest XML messages.

For complete JavaDoc and implementation documentation for this API, please download the DynamicTMN® CMIP eBonding/TA Suite evaluation package.

EBTA/MLT Standards Supported

The eBonding/TA XML Manager Gateway API provides support for the following Electronic Bonding related standards:

ANSI T1.227: Trouble Administration Information Data Model
ANSI T1.228: Trouble Administration Service Interface
ANSI T1.262: Service Test Function/Mechanized Loop Test
ANSI T1.278-200X: Trouble Administration XML Schema (tML-TA)
ANSI T1.277-200X: ServiceTest XML Schema (tML-ServiceTest)
and all additional standards required by the above.

Related DynamicTMN® Components

The DynamicTMN® eBonding/TA XML Manager Gateway API uses the following DynamicTMN® Java APIs:

And is included in the following DynamicTMN® product: