JAIN^TM: APIs for the Integrated Network

JAIN Transaction and Capabilities Part (TCAP) Specification
Version 1.1

See:
Description

Packages

jain	This package contains the common JAIN Exceptions, which are used throughout all the JAIN specifications.
jain.protocol.ss7	This package contains the JAIN SS7 Factory and the JAIN SS7 Addressing.
jain.protocol.ss7.tcap	This package contains the main interfaces required to represent JAIN TCAP protocol stacks, JAIN TCAP applications, as well as the Classes and Exceptions needed to send and receive JAIN TCAP primitives.
jain.protocol.ss7.tcap.component	This package contains the Event classes representing the component primitives and their specified parameters, if the coding of a paramater is not included in any specific class, it is common to all the specified components and therefore coded within that components parent class.
jain.protocol.ss7.tcap.dialogue	This package contains the Event classes representing the JAIN TCAP Dialogue Handling primitives and their specific parameters, if a paramater is not included in any specific primitive, it is common to all the specified dialogues and therefore coded within that dialogues parent class.

Copyrights

Copyright - 1999 Sun Microsystems, Inc. All rights reserved.
901 San Antonio Road, Palo Alto, California 94043, U.S.A.

This product and related documentation are protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any.

RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19.

The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications.

TRADEMARKS

Sun, the Sun logo, Sun Microsystems, Java, Java Compatible, JavaBeans, Solaris,Write Once, Run Anywhere, JDK, Java Development Kit, and JavaStation are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. All other product names mentioned herein are the trademarks of their respective owners.

THIS PUBLICATION IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

Overview of JAIN TCAP API v1.1

This document provides an overview of the JAIN TCAP API v1.1, which is part of the JAIN TCAP 1.1 Specification. It is not a tutorial, readers should have a good understanding of TCAP and be comfortable reading the JAIN TCAP API. This document, combined with the JAIN TCAP Reference Implementation (RI) Specification v1.1, the JAIN TCAP Technology Compatability Kit (TCK) Specification v1.1 and the JAIN TCAP API Requirements Specification v1.3 complete the JAIN TCAP 1.1 Specification.

The implementation of this API focuses around the JainTcapListener, JainTcapProvider, JainTcapStack interfaces and the JainSS7Factory. A JainTcapListener can be any TCAP User application that implements the JainTcapListener Java Interface, a JainTcapProvider and a JainTcapStack can be any TCAP Layer of an SS7 stack that implements the JainTcapProvider and JainTcapStack Java Interfaces, see Figure 1. The JainTcapStack is the management encapsulation of a Tcap Layer, which also manages and exposes the JainTcapProvider Interfaces, which encapsulate the messaging features of the Tcap Layer. A JainTcapListener would then use a JainTcapProvider to send dialogue and component primitives into the TCAP layer. In order to send a TCAP message, a Listener would have to register with a JainTcapProvider and send component events to a JainTcapProvider, interspersed with dialogue events based on the JavaBean Event model, see Figure 2.

The JAIN SS7 factory is a central repositary from which a JainTcapListener application can obtain a proprietary JainTcapStack implemenation cast to the JainTcapStack Java Interface. This is achieved by setting the path to the vendors proprietary implementation and calling the create SS7 object functionality implemented within the Jain SS7 Factory.

Figure 1 - JAIN TCAP Architecture

The JAIN TCAP Event model is based on the JavaBean Event model as outlined in Figure 2. The JAIN TCAP API architecture is JavaBean compliant, however it not mandated that an implementation of the JAIN TCAP API must be JavaBean compliant.

Figure 2 - Jain Tcap Event delivery based on the JavaBean Event Model

Each JainTcapProvider and JainTcapStack implementation will be SS7 vendor specific. The JainTcapStack implementation will maintain the list JainTcapProviders for that SS7 stack see Figure 3, as well as providing the hooks for the proprietary management of subsystems for that TCAP Layer. The JainTcapProvider implementation acts as a messaging proxy for the TCAP layer of that vendors SS7 Stack. It listens for incoming TCAP messages from the TCAP layer of the SS7 stack and encapsulates these messages as a combination of dialogue and component events and fires them to the appropraite JainTcapListener. As the JainTcapProvider has the methods required to maintain a list of JainTcapListeners, it can inspect the messages' destination addess and match this to the SccpUserAddress of the various JainTcapListeners maintained by that JainTcapProvider, see Figure 4.

Figure 3 - JainTcapStack with managing multiple JainTcapProviders

The JainTcapListener interface defines the methods required to process any of the Events sent from a JainTcapProvider. An object implementing the JainTcapListener interface (a Listener) would register as an Event Listener of a Provider with a SccpUserAddress and would subsequently be able to receive Events from that Provider for that address. The current JAIN TCAP architecture enables:

• One or more Event Listeners to register with any JainTcapProvider, as well as providing the ability to limit the number of JainTcapListeners that may register at any one time with a specific JainTcapProvider.
• A single JainTcapListener to register with one or more JainTcapProviders at any time, see Figure 3.
• More than one JainTcapListener to register with a JainTcapPovider with the same SccpUserAddress. This area is for further study but is aimed at providing a mechanism of load-sharing and failover in the application space.

Figure 4 illustrates how an Event is distributed to a specific Listener, when mulitple Listeners are registered with the one Provider. In order to send JainTcapEvents a JainTcapListener application would create new dialogue and component events and pass these events to the send methods defined in the JainTcapProvider Interface. It is important to note that the JainTcapProvider is not listening for these Events, as the JainTcapListener application is the initiating entity which usually waits on a undefined response.

Figure 4 - JainTcapEvent distribution between multiple JainTcapListeners

A JAIN TCAP example

The following points illustrate how the JAIN TCAP API can be used to send and receive TCAP Messages. The example looks at the code of a Jain Tcap User application and the steps the User application will use to create a JainTcapProvider for communicating with the proprietary TCAP stack.

• Any TCAP User application interested in receiving dialogue and component Events must implement the JainTcapListener interface:


public class JainTcapListenerImpl implements JainTcapListener, Runnable{ // start of Listener Implemenation class

public JainTcapListenerImpl () { // start of constructor

// set this JainTcapListener for this address, only one for simplicity
//Signaling Point Code number
int SPCode = 2300193;
short ownSSn = 10;
int[] spc = SignalingPointCode.convertSPCToMemberClusterZone(SPCode, variant);
SignalinPointCode signalingPointCode = new SignalingPointCode(spc[0], spc[1], spc[2]);
SubSystemAdress subSystemAddress = new SubSystemAddress(signalingPointCode, ownSSn);
SccpUserAddress senderAddress = new SccpUserAddress(subSystemAddress);


• Use the JainSS7Factory to set the desired PathName and obtain a reference to a JainTcapStack object and set its Stack Name if an appropriate stack does not already exist

// use the Stack Factory to establish if there are any stacks available
// If there is, select a suitable stack, if not create a Peer TcapStack

JainSS7Factory myFactory = JainSS7Factory.getInstance();
Vector availableStacks = myFactory.getJainObjectList();

if (availableStacks != null) {

// There are stacks available, select a stack with the signaling point code
// that supports the required protocol

for (int i=0; i<availableStacks.size(); i++){

try {

JainTcapStack tmpStack = (JainTcapStack)availableStacks.elementAt(i);

} catch (Exception e) {

// Do nothing not at a JainTcapStack Object

}

if ( tmpStack.getVendorName() == "com.sun") {

// this is the stack we want to use
myStack = tmpStack;

}

}

if (myStack == null){

// we haven't found a suitable stack so create one
myFactory.setPathName("com.sun");

try {

myStack = (JainTcapStack)myFactory.createSS7Object("jain.protocol.ss7.tcap.JainTcapStackImpl");
// Set Vendor name to enable Listeners to
// differentiate between vendors
// when using previously created stacks
myStack.setVendorName("com.sun");

} catch (SS7PeerUnavailableException e) {

// Couldn't find the class com.sun.jain.protocol.ss7.tcap.JainTcapStackImpl
System.err.println("The specified class could not be found in the CLASSPATH");

}

}

}

• Use the JainTcapStack Object to obtain a new JainTcapProvider. The JainTcapProvider class will be used to send TCAP Component and Dialogue handling primitives into the SS7 protocol stack, and will be used to listen for TCAP messages from the SS7 protocol stack. The User Application should register as a listener of the JainTcapProvider with an User Address. Once a TCAP message arrives, the Provider should inspect the Destination User Address of the message and send the message as Component and Dialogue handling Events to the JainTcapListener registered with the Provider with that User Address.

// create a new Provider attached to the stack
// and register with it as an EventListener

myprovider = myStack.createProvider();

try {

myProvider.addJainTcapListener(this, myUserAddressList[0]);

} catch (TooManyListenersException tooManyListeners) {

System.err.println("tooManyListeners.getMessage()");

}

} // End of constructor

• Receiving TCAP messages:- This class will use the processDialogueIndEvent() method to process the incoming dialogue indication primitives, and processComponentIndEvent()method to process the incoming component indication primitives.

/**
* Processing of the ComponentIndEvent passed.
*/

public void processComponentIndEvent(ComponentIndEvent event){

JainTcapProvider eventSource = (JainTcapProvider)event.getSource();

// At this stage we only that the event is a ComponentIndEvent
// therfore we find out the primitive type.
switch (event.getPrimitiveType()) {

case TcapConstants.PRIMITIVE_INVOKE : {

// cast to an Invoke Indication Event
InvokeIndEvent receivedInvoke = (InvokeIndEvent)event;

// now we can access the methods within the Invoke Indication Primitive.

try {

int dialogueId = receivedInvoke.getDialogueId();
int invokeId = receivedInvoke.getInvokeId();

} catch (ParameterNotSetException exception) {

// Access the error Message
System.err.println("exception.getMessage()");

}

try {

Operation op = receivedInvoke.getOperation();
if (op.getOperationType() == Operation.OPERATIONTYPE_LOCAL) {

// this is a local/private operation

} else {

// this is a global/national operation

} catch (ParameterNotSetException exception) {

// Access the error Message
System.err.println("exception.getMessage()");

}

// Execute the Invoke primitive

}

}

case TcapConstants.PRIMITIVE_ERROR : {......};
case TcapConstants.PRIMITIVE_REJECT : {......};
case TcapConstants.PRIMITIVE_RESULT : {......};
case TcapConstants.PRIMITIVE_LOCAL_CANCEL : {......};
case TcapConstants.PRIMITIVE_USER_CANCEL : {......};

default : // not a recognised component

}

} // end of processComponentIndEvent() method

/**
*Processing of DialogueIndEvent
*/

public void processDialogueIndEvent(DialogueIndEvent event){

// Processing a Dialogue Indication Event is similiar to
// the processing of Component Indication Event

}

• Methods to manage the Sccp User Addresse of this JainTcapListener

/**
* Adds a SccpUserAddress to the list of User Addresses used by this JainTcapListener. This
* JainTcapProvider can then choose to register as an Event Listener
* of the a JainTcapProvider for this set of User Addresses. Any Events addressed to one of the User Addresses
* belonging to the User Application will be passed to this JainTcapListener by
* the JainTcapProvider.
*/

public void addUserAddress(SccpUserAddress userAddress) throws UserAddressLimitException{

if (null == myUserAddressList[0]) {

myUserAddressList[0] = userAddress;

} else {

throw new UserAddressLimitException();

}

}

/**
* Removes a Jain User Address from the list of User Addresses used by this JainTcapListener.
*/

public void removeUserAddress(SccpUserAddress userAddress) throws NoSuchUserAddressException{

if (userAddress == myUserAddressList[0]) {

myUserAddressList[0] = null;

} else {

throw new NoSuchUserAddressException();

}

/**
* Returns the list of User Addresses used by this JainTcapListener.
*/

public SccpUserAddress[] getUserAddressList(){

return(myUserAddressList);

}

• To send TCAP messages:- Component Request Events are created and sent to the Provider, interspersed with Dialogue Request Events. First a component request is created as an Event, setting the Listener (this) as the Event source. Parameters of the component primitive may be set using the appropriate 'set' method.


public void run() {

// get a new Dialogue Id for use in this Dialogue
int myNewDialogueId = myProvider.getNewDialogueId();

// get a new Invoke Id for use within the Dialogue
int myNewInvokeId = myProvider.getNewInvokeId(myNewDialogueId);

byte[] operationCode = {1, 1, 1};
Operation myOperation = new Operation(Operation.OPERATIONTYPE_GLOBAL, operationCode);

InvokeReqEvent myInvokeReqEvent = new InvokeReqEvent(this, myNewDialogueId, myOperation);

// set the JAIN TCAP optional parameters of the Invoke Event

myInvokeReqEvent.setInvokeId(myNewInvokeId);
myInvokeReqEvent.setTimeout(INVOKE_TIMER_1);
myInvokeReqEvent.setLastInvokeEvent(true); // this is the last Invoke (ANSI Flag to show this is an INVOKE_L component)

The component request primitive is then sent to the Provider, the implementation of the JainTcapProvider send method can ensure all the mandatory paramters are set for that ANSI 92 specification.

try {

myProvider.sendComponentReqEvent(myInvokeReqEvent);

} catch (MandatoryParameterNotSetException e){

System.err.println("Some of the required parameters were not set");

}

Then a dialogue request Event is created in a similar manner and sent to the Provider.

BeginReqEvent myBeginRequestEvent = new BeginReqEvent(this, myNewDialogueId, myUserAddressList[0], destinationAddress);


JAIN TCAP optional Parameters may then be set using the appropriate 'set' methods and the dialogue request primitive is then sent to the Provider. Once again the implementation of the JainTcapProvider send method can ensure all the mandatory paramters are set for that ANSI 92 specification.

myBeginRequestEvent.setQualityOfService(QOS_1);

try {

myProvider.sendDialogueReqEvent(myBeginRequestEvent);

} catch (MandatoryParameterNotSetException e){

System.err.println("Some of the required parameters were not set");

}

} // end of run method

• Initialize all variables

private JainTcapStack myStack = null;
private SccpUserAddress[] myUserAddressList = null;
private JainTcapProvider myProvider = null;
public static final int INVOKE_TIMER_1 = 5000;
public static final int QOS_1 = 1;

} // End of Listener implementation class