Tmftip Ri Userguide

7/31/2019 Tmftip Ri Userguide

1/29

TM Forum

Reference ImplementationUser Guide

Release

Month, Year


2/29

TM Forum Page 2 of 29

Notice

No recipient of this document and code shall in any way interpret this material as representing aposition or agreement of TM Forum or its members. This material is draft working material of TMForum and is provided solely for comments and evaluation. It is not Forum Approved and issolely circulated for the purposes of assisting TM Forum in the preparation of final material infurtherance of the aims and mission of TM Forum.

Although it is copyrighted material of TM Forum:

Members of TM Forum are only granted the limited copyright waiver to distribute thismaterial within their companies and may not make paper or electronic copies fordistribution outside of their companies.

Non-members of the TM Forum are not permitted to make copies (paper or electronic) ofthis draft material other than for their internal use for the sole purpose of makingcomments thereon directly to TM Forum.

If this material forms part of a supply of information in support of an Industry GroupLiaison relationship, the document may only be used as part of the work identified in theLiaison and may not be used or further distributed for any other purposes

Any use of this material by the recipient, other than as set forth specifically herein, is at its ownrisk, and under no circumstances will TM Forum be liable for direct or indirect damages or anycosts or losses resulting from the use of this material by the recipient.

This material is governed, and all recipients shall be bound, by all of the terms and conditions ofthe Intellectual Property Rights Policy of the TM Forum(http://www.tmforum.org/Bylaws/1094/home.html ) and may involve a claim of patent rights by

one or more TM Forum members or by non-members of TM Forum.Direct inquiries to the TM Forum office:

240 Headquarters Plaza,East Tower 10th Floor,Morristown, NJ 07960 USATel No. +1 973 944 5100Fax No. +1 973 944 5110TM Forum Web Page:www.tmforum.org
http://www.tmforum.org/Bylaws/1094/home.htmlhttp://www.tmforum.org/Bylaws/1094/home.htmlhttp://www.tmforum.org/Bylaws/1094/home.htmlhttp://www.tmforum.org/http://www.tmforum.org/http://www.tmforum.org/http://www.tmforum.org/Bylaws/1094/home.html


3/29


Table of Contents

Notice .................................................................................................................................................................. 2Table of Contents .............................................................................................................................................. 3List of Figures .................................................................................................................................................... 4List of Tables ...................................................................................................................................................... 4Executive Summary .......................................................................................................................................... 51.RI User Guide ................................................................................................................................................. 6

1.1. Installing JOSIF Tooling................................................................................................................... 61.2. Building the Model project ............................................................................................................... 61.3. Looking at the Generated Code ...................................................................................................... 6

1.3.1. Subsection 1............................................................................................................................. 61.3.2. Subsection 2............................................................................................................................. 6

1.4. Creating your RI Project ................................................................................................................ 61.5. Compiling your RI Project ............................................................................................................. 71.6. Using the Default Mockup Operation Implementations ................................................................ 71.7. Adding your Operation Implementations ........................................................................................ 71.8. Testing your Operation Implementations ....................................................................................... 71.9. Using the Hibernate Persistency Service ....................................................................................... 71.10. Running your RI Project ............................................................................................................. 81.11. Running the TIP WS Notification Service ..................................................................................... 81.12. Testing the TIP WS Notification Service....................................................................................... 91.13. Adding and Injecting Events to the WS Notification Service .................................................... 121.14. Testing Events ............................................................................................................................ 121.15. Implementing Iterators ................................................................................................................ 121.16. Testing Iterators .......................................................................................................................... 221.17. Configuring Heartbeat Events .................................................................................................... 241.18. Testing your Implementation ...................................................................................................... 251.19. Packaging and distributing the RI Project .............................................................................. 25

2.Summary and Open Issues ....................................................................................................................... 262.1. Summary ....................................................................................................................................... 262.2. Open Issues .................................................................................................................................. 26

3.Appendix A: Terms and Abbreviations Used within this Document ................................................. 27 3.1. Terminology................................................................................................................................... 273.2. Abbreviations and Acronyms ....................................................................................................... 27

4.Appendix B: References ............................................................................................................................ 284.1. References .................................................................................................................................... 284.2. Document History ......................................................................................................................... 28

4.2.1. Version History ...................................................................................................................... 284.2.2. Release History ..................................................................................................................... 28

4.3. Company Contact Details ............................................................................................................. 284.4. Acknowledgments ......................................................................................................................... 29


4/29


List of FiguresInsert if applicable

List of Tables

Table 1: IIS Term Definitions and Sources 27Table 2: IIS Abbreviations and Acronyms 27


5/29


Executive Summary

[Insert here an executive summary of the document covering not more than two pages oftext. This should summarize the main points from the document and highlight the problem

statement being addressed, the main results, the conclusions drawn and the next steps asappropriate. The purpose of the Executive Summary is to prepare the reader at an initialglance for what to expect in the document.]


6/29


1. RI User Guide

>

1.1. Installing JOSIF Tooling

1.2. Building the Model project

1.3. Looking at the Generated Code

1.3.1. Subsection 1

1.3.2. Subsection 2

1.4. Creating your RI Project


7/29


1.5. Compiling your RI Project

1.6. Using the Default MockupOperation Implementations

1.7. Adding your OperationImplementations

1.8. Testing your OperationImplementations

1.9. Using the Hibernate PersistencyService


8/29


1.10. Running your RI Project

1.11. Running the TIP WS NotificationService

The RI comes with an implementation of the Web Service Notification called the TIP Web ServiceNotification or simply TIP WSN.

The TIP WSN exposes 4 Web Services:

Notification Producer

Pausable Subscription Manager

Notification Consumer

Sinkconsumer

When implementing a TIP interface you need to bind the TIP WSN to your implementation. This donevia configuration by providing the following properties;

-Topic Name the name of the Topic your support

-The URL where the Notification Producer, Pausable Subscription Manager, Notification Consumerand SinkConsumer will run.

The SinkConsumer is used by your implementation to inject events in the WSN.

To run the Service go into the WS-Notification directory and type jetty:run-war. You should be able tosee the WSN Services underhttp://localhost:9090/RI/services
http://localhost:9090/RI/serviceshttp://localhost:9090/RI/serviceshttp://localhost:9090/RI/serviceshttp://localhost:9090/RI/services


9/29


1.12. Testing the TIP WS NotificationService

The following section describe how to use SOAP UI to test the WS Notification Service.

1.12.1. Create a Consumer Mockup Service

From within SOAP UI create a Consumer Mockup Service. You will use this Serviceto receive Events from the TIP WSN

Create a New Project and import the the WSN Consumer Service WSDL

For example

http://localhost:9090/RI/services/TIPNotificationService/NotificationConsumerService?wsdl


10/29


Then run the MockConsumerService and check it is running properly. Open abrowser on the Web Service name you specified and make sure you can display theWSDL for example at

http://pierre-pc:8088/mockTipConsumerService?WSDL

From now on we will use the mockconsumerService URL to subscribe for events .

1.12.2. Subscribe for Events

To Subscribe for Events you must send a Subscription request to theNotificationPoducer.

Create a New Project using the NotificationProducer WSDL.

Send the subscribe request to the Notification Producer URL for example

http://localhost:9090/RI/services/TIPNotificationService/NotificationProducerService

and use the mockup consumer as the consumer address for example

http://pierre-pc:8088/mockTipConsumerService?WSDL
http://localhost:9090/RI/services/TIPNotificationService/NotificationProducerServicehttp://localhost:9090/RI/services/TIPNotificationService/NotificationProducerServicehttp://localhost:9090/RI/services/TIPNotificationService/NotificationProducerService


11/29


You should see a response like the following:

The response contains the subscriptionId.


12/29


1.13. Adding and Injecting Events tothe WS Notification Service

The RI Framework provides a set of classes than you can use to inject events into WSN.

The classes are:

WSNotificationServiceEventPublisher

JVTNotificationAdapter

JVTEventTransformer

1.14. Testing Events

1.15. Implementing Iterators

The RI comes with an Alarm Retrieval Iterator example. The example provides a sampleimplementation of the RAM Alarm Retrieval getResourceAlarms operation.

The example is located at

1.15.1. Query Framework

The RI comes with a set of base classes for implementing named queries and inparticular the Iterator based queries.

The main classes used by the Query Framework are found in theorg.openoss.tip.iterator package.

Query

Base Class for Named Query. This object is associated with a named query andcontains information about the Query state.


13/29


Subclasses associated with specific types of named queries must be provided. Forexample QueryRI does provide an implementation of a getAlarms query.

QueryContext

The QueryContext does provide information about the context of a query mainly if thequery is completed via the getEndOfSequence() method.

QueryData

The QueryData class represent the results of a Query execution. It does containmethods to extract the data associated with the execution of a Query and its context(see QueryContext

QueryEngine

The engine in charge of executing the application queries. Its main method isexecuteQuery(query). The Query Engine is an interface that must be implemented bythe application. Different Query Engines may be associated with differen Query typesor the same Engine may be used for all the named queries. The main methods are

o executeQuery(Query query) a method to execute the Query

o QueryData getNextQueryData(Query query, int size) extracting the results ofthe Query.

QueryEngineFactory

A factory for the creation of the Query Engine associated with a type of Query. Asingle method

o QueryEngine makeQueryEngine(String queryType)

Different Query Engines may be associated with different Query types or the sameEngine may be used for all the named queries.

QueryManager

The QueryManager class is the core Query Framework class. It is responsible with itsassociated Query Engine for the execution and management of the queries. The mainmethods are

o String executeQuery(Query query) returning a Query ID associated with theexecution of a Query.

o Query buildQuery(String queryType) returning a Query object associatedwith a query type

1.15.2. Using the Query Framework Alarm Retrieval Example

The RI comes with an Alarm Retrieval Iterator example. The example provides asample implementation of the RAM Alarm Retrieval getResourceAlarms operation.


14/29


The steps involved in using the frameworks are :

o the creation of the required Query objects

o the creation of the QueryEngineFactory

o the creation of a QueryEngine supporting the execution of the

Queries.o the wring of the QueryEngineFactory to the QueryManager

The QueryManager uses the QueryEngine implementation for the query execution.

The classes used in this Example are the implementations and extensions of thebase framework classes mainly:

QueryEngineFactoryRIImpl implements QueryEngineFactory

An Engine factory for the creation of Query Engines associated with the RI query types.The same Engine is used for different query types.

QueryEngineRIImpl implements QueryEngine

Query Engine responsible for the execution of the RI queries and getting the results of theQueries. The main methods are:

o executeQuery(Query query) a method to execute the Query Create an Alarm Listof 30 alarms when the Query is executed and store them into the Query entity.

o QueryData getNextQueryData(Query query, int size) extracting the results of theQuery Get Next Batch of Results and removing them for the Query Data Update

the endOfSequence associated with the Query Context

QueryRI extends Query

A Query object representing a "getResourceAlarms" query. Stores a set of ResourceAlarms

The following illustrates how to use the framework and provides a walk through of the Main class.

1) First we get the QueryManager bean from the Spring context:

ApplicationContext context = newClassPathXmlApplicationContext("Model_IteratorAppContext.xml");QueryManager qm=( QueryManager ) context.getBean("queryManager");

2) Then build a Query for the getResourceAlarms query type :


15/29


Query query = null;

//Build the Querytry {

query = qm.buildQuery("getResourceAlarms");} catch (QueryException e) {

// TODO Auto-generated catch blocke.printStackTrace();

}

3) Execute the query

String id = null;

//Execute the Querytry {

id = qm.executeQuery(query);} catch (QueryException e) {

// TODO Auto-generated catch blocke.printStackTrace();}

This will translate into a call to the RI QueryEngine executing the Query and settingup the Alarms in the associated Query object.

//Create an Alarm List of 30 alarms when the Query is executed//and store them into the Query entity.public void executeQuery(Query query) {

// populate Query with list of Alarms

org.tmforum.xml.tip.resource.trouble.alarm.ResourceAlarm resourceAlarm = newResourceAlarm();

ArrayOfResourceAlarm results = new ArrayOfResourceAlarm();resourceAlarm.setAdditionalText("AdditionalText");for (int i = 0; i


16/29


}

5) Retrieve the first results of the Query by calling the QueryManager getNextQueryDataoperation

QueryData qd = null;boolean endOfSequence = false;

//Retrieve the ResultsArrayOfResourceAlarm results = null;

try {

qd = qm.getNextQueryData(id, 10);QueryContext qcontext = qd.getQueryContext();endOfSequence = qd.getQueryContext().getEndOfSequence();results = (ArrayOfResourceAlarm ) qd.getData();

} catch (QueryException e) {// TODO Auto-generated catch block

e.printStackTrace();}List resultItems = results.getItem();ListIterator iterator = resultItems.listIterator();

while ( iterator.hasNext() ) {ResourceAlarm alarm = iterator.next();

System.out.println("Alarm= " + alarm);

}

6) And then extracts the remaining results. Note how the endOfSequence is used tocontrol the iteration

//Check the endOfSequence and Iterate over the next resultswhile( endOfSequence == false ) {

try {qd = qm.getNextQueryData(id, 10);

} catch (QueryException e) {// TODO Auto-generated catch blocke.printStackTrace();

}QueryContext qcontext = qd.getQueryContext();endOfSequence = qd.getQueryContext().getEndOfSequence();results = (ArrayOfResourceAlarm ) qd.getData();

resultItems = results.getItem();iterator = resultItems.listIterator();

while ( iterator.hasNext() ) {ResourceAlarm alarm = iterator.next();

System.out.println("Alarm= " + alarm);

}

}


17/29


Note that the call to the QueryManager getNextQueryData are delegated to theQueryEngine as follow:

// Get Next Batch of Results and removing them for the Query Data.//Update the endOfSequence associated with the Query Contextpublic QueryData getNextQueryData(Query query, int size) {

ArrayOfResourceAlarm results = ((QueryRI) query).getResourceAlarms();

if (results.getItem().size()


18/29


The following section use the RI sample to illustarate the process.

1.15.4. Web Services Alarm Retrieval Example

You use the Query Framework when implementing Web Services that are returningIterators.

For example the RAM ResourceAlarmRetrievalService Web service provides anoperation called

org.tmforum.xml.tip.resource.trouble.alarm.GetResourceAlarmsResponsegetResourceAlarms(org.tmforum.xml.tip.resource.trouble.alarm.GetResourceAlarmsRequest xmlRequest)

This operation returns a response which contains an initial list of alarms and aniterator ID.

The Iterator ID is used to retrieve the next results from another Web Service calledthe ResourceAlarmIterator

The ResourceAlarmIterator eposes a method called

GetNextResourceAlarmIterationResponse getNextResourceAlarmIteration(

GetNextRequest body)

That you can use to extract the remaining alarms.

When using the Query Framework you:

-Associate a QueryManager with your Web Sevices via Spring wiring

-Use the initial call to the Retrieval Service to setup a Query , start the execution ofthe Query and then return the initial results with an Iterator ID being the same thanthe Query ID.

-In the Iterator you lookup the QueryManager for a Query matching the Query ID andthen extracts the result by calling getNextQueryData.

The association of the QueryManager with your Web Service implementation classesis done via Spring injection in the associated Spring Configuration files:


19/29


The following code extract shows how the processing of the initial request in the WebServiev implementation class. Note how the call is delegated to the QueryManager.Note how the QueryID and the endOfSequence are returned.


20/29


public org.tmforum.xml.tip.resource.trouble.alarm.GetResourceAlarmsResponsegetResourceAlarms( org.tmforum.xml.tip.resource.trouble.alarm.GetResourceAlarmsRequestxmlRequest)

throwsorg.tmforum.xml.tip.resource.trouble.alarm.GetResourceAlarmsException_Exception {

org.tmforum.tip.org.tmforum.tip.resource.trouble.alarm.ResourceAlarmRetrievalService

jvtInterface = getResourceAlarmRetrievalService();if(jvtInterface==null) {

log.error("ERROR: "+this.getClass().getName()+": methodgetResourceAlarms mapped jvtInterface has not been set");

throw neworg.tmforum.xml.tip.resource.trouble.alarm.GetResourceAlarmsException_Exception("ERROR:"+this.getClass().getName()+": method getResourceAlarms mapped jvtInterface has not beenset");

}else {try {

GetResourceAlarmsResponse getResourceAlarmsResponse = newGetResourceAlarmsResponse();

ResourceAlarmResultWithIterator iterator = newResourceAlarmResultWithIterator();

QueryManager qm = getQueryManager();

Query query = qm.buildQuery("getResourceAlarms");String id = qm.executeQuery(query);

IteratorInfo iteratorInfo = new IteratorInfo() ;iteratorInfo.setIteratorId(String.valueOf(id));iterator.setIterator(iteratorInfo);

int size = 10; //default

if(xmlRequest != null )if( xmlRequest.getMaxElements() !=null) size =

xmlRequest.getMaxElements();

QueryData data = qm.getNextQueryData(id, size);

ArrayOfResourceAlarm results = (ArrayOfResourceAlarm ) data.getData();iterator.setResult(results);

QueryContext qcontext = data.getQueryContext();getResourceAlarmsResponse.setEndOfSequence(qcontext.getEndOfSequence());getResourceAlarmsResponse.setStartIndex(qcontext.getStartIndex());getResourceAlarmsResponse.setEndIndex(qcontext.getEndIndex());getResourceAlarmsResponse.setObjects(iterator);

return getResourceAlarmsResponse;

} catch (Exception e) {log.error("ERROR: "+this.getClass().getName()+": method

getResourceAlarms Exception: ",e);throw new

org.tmforum.xml.tip.resource.trouble.alarm.GetResourceAlarmsException_Exception("ERROR:"+this.getClass().getName()+": method getResourceAlarms Exception", e);

}}

}


21/29


The following code extract shows how the Iterator Web Service implementation classreuse the QueryManager instance to get the next results.

public GetNextResourceAlarmIterationResponse getNextResourceAlarmIteration(GetNextRequest body)throws GetNextResourceAlarmIterationException_Exception {

GetNextResourceAlarmIterationResponse resp = newGetNextResourceAlarmIterationResponse();

String id = body.getIteratorId();int size = body.getMaxElements();QueryManager qm = getQueryManager();

QueryData qd = null;try {

qd = qm.getNextQueryData(id, size);} catch (QueryException e) {

// TODO Auto-generated catch blocke.printStackTrace();

}ArrayOfResourceAlarm results = (ArrayOfResourceAlarm) qd.getData();resp.setResult(results);

resp.setEndOfSequence(qd.getQueryContext().getEndOfSequence());

return resp;}

Finally how the release iterator call it translated into a QueryManager call.

public ReleaseResponse releaseResourceAlarmIterator(ReleaseRequest body)throws ReleaseResourceAlarmIteratorException_Exception {

String id = body.getIteratorId();

QueryManager qm = getQueryManager();Query query;try {

query = qm.qetQuery(id);qm.releaseQuery(id);

} catch (QueryException e) {ReleaseResourceAlarmIteratorException_Exception exception = new

ReleaseResourceAlarmIteratorException_Exception();throw exception;

}

ReleaseResponse resp = new ReleaseResponse();return resp;

}

1.15.5. Implementing your Iterators

The steps involved in using the frameworks are :

o the creation of the required Query objects


22/29


o the creation of the QueryEngineFactory

o the creation of a QueryEngine supporting the execution of the Queries.

o the wring of the QueryEngineFactory to the QueryManager

The association and use of the QueryManager with the Web Service retrieval anditerator implementation classes.

1.16. Testing Iterators

1.16.1. Using the Query Framework Alarm Retrieval Example

You can take a look at the org.openoss.tip.iterator.ri.client.Main class for an example clientcode.

1.16.2. Using the Query Framework Alarm Web Service Retrieval Example

The following are snapshots of the SOAP UI requests and replies running against theRI sample implementation

You can also take a look at the org.openoss.tip.iterator.ri.client.Main class for clientcode.

5

And the response


23/29


false

AdditionalText

AdditionalText

AdditionalText

AdditionalText

AdditionalText

falsee25819c1-7948-407a-9ab0-9e649058145a

Note the e25819c1-7948-407a-9ab0-9e649058145a

We reuse the same iteratorId to extract the remaining alarms.

5e25819c1-7948-407a-9ab0-9e649058145a


24/29


A sample of the Iterator response:

false

AdditionalText

AdditionalText

AdditionalText

AdditionalText

AdditionalText.

1.17. Configuring Heartbeat Events


25/29


1.18. Testing your Implementation

1.19. Packaging and distributing theRI Project


26/29


2. Summary and Open Issues

>

2.1. Summary

2.2. Open Issues


27/29


3. Appendix A: Terms and Abbreviations Used within thisDocument

3.1. Terminology

Term Definition TMF or Outside Source

>

Table 1: IIS Term Definitions and Sources

3.2. Abbreviations and AcronymsAbbreviation/

AcronymAbbreviation/

Acronym Spelled OutDefinition TMF or External Sou

Table 2: IIS Abbreviations and Acronyms


28/29


4. Appendix B: References

4.1. ReferencesReference Description Brief Use Summary

Project Charter Project Charter

>

4.2. Document History

4.2.1. Version History

Version Number Date Modified Modified by: Description ofchanges

DD/MMM/YY Pierre GauthierTM Forum

Description e.g. firstissue of document

4.2.2. Release History

Release Number Date Modified Modified by: Description ofchanges

DD/MMM/YY Description e.g. firstissue of document

4.3. Company Contact Details

Company Team Member


29/29

Representative

Include all involved companiesadding lines as necessary.

NameTitleEmailPhoneFax

NameTitleEmailPhoneFax

4.4. Acknowledgments

This document was prepared by the members of the TeleManagement Forum team:

Name, Company, Editor

Name, Company, position if appropriate (e.g. team leader)

Additional input was provided by the following people:

Name, Company

Documents

Tmftip Ri Userguide