JAIN(tm) TCAP API

Standard Java(tm) Interface to the Transaction Capabilities Application Part (TCAP)

Release 1.0c

See:
          Description

Packages
jain.protocol.ss7 This package contains the JAIN SS7 Factory, which is the central creation point for all high level proprietary JAIN SS7 objects, for example JainTcapStack Objects.
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 messages.
jain.protocol.ss7.tcap.component This package contains the Event classes representing the component primitives and their specified parameters, if a paramater is not included in any specific primitive, 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.

 

This document provides an overview of the JAIN TCAP API, which is part of the JAIN TCAP 1.0 Specification. .

 

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.


 

This document provides an overview of the JAIN TCAP API, which is part of the JAIN TCAP 1.0 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 API Requirements Specification, the JAIN TCAP Reference Implementation (RI) Specification and the JAIN TCAP Technology Compatability Kit (TCK) Specification (described below) comprise the JAIN TCAP 1.0 Specification.


 

The JAIN TCAP API Requirements Specification

The Requirements Specification provides a high level overview of JAIN and the JAIN TCAP API Specification as well as explaining the JAIN Architecture, Transaction Capabilities and the functionality provided by each of the requirements defined within the document.


 

The JAIN TCAP Reference Implementation (RI) Specification

The JAIN TCAP Reference Implementation (RI) is a an example Java program that emulates the functions of an SS7 stack in order to verify that JAIN TCAP applications are compatible with the JAIN TCAP specification. The RI can therefore be used to help develop and debug a JAIN TCAP application in the absence of an JAIN TCAP Compliant SS7 Stack. The purpose of the the RI Specification is to outline the requirements for setting up the RI and to list the scope, limitations and restrictions of the RI.


 

The JAIN TCAP Technology Compatability Kit (TCK) Specification

The purpose of the JAIN TCAP CTS is to verify that a JAIN TCAP implementation is compatible with the JAIN TCAP API Specification. The CTS Specification details the test cases which an implementation of JAIN interfaces must pass in order to be considered compliant with the JAIN TCAP Specification.


 

Overview of JAIN TCAP API

The implementation of this API focuses around the JainTcapListener and JainTcapProvider interfaces.A Listener could be any TCAP User application, and would use a Provider to send dialogue and component primitives into the TCAP layer. To send a TCAP message, a Listener would send component Events to a Provider, interspersed with dialogue Events.

Diagram 1 - JAIN TCAP setup

The JainTcapProvider interface defines the methods required to send TCAP dialogue and component primitives. This interface also defines the methods required to maintain a list of Event Listeners. An implementation of this interface would listen for TCAP messages from the stack and forward these messages as Events to a specified registered Event Listener by means of the User Address. The TCAP messages would be sent as dialogue primitive Events and component primitive Events.

Diagram 2 - Jain TCAP message passing

An object implementing the JainTcapProvider interface (a Provider) could be vendor specific and would act as a proxy for the TCAP layer of an SS7 Stack. Zero or more Event Listeners could register with a Provider, however the JAIN TCAP API provides the ability to limit the number of Event Listeners that may register  at any one time.

Diagram 3 - Listener registration with multiple Providers

The JainTcapProvider interface defines the methods required to process any of the Events sent from a Provider.  An object implementing the JainTcapListener interface (a Listener) would register as an Event Listener of a Provider and would subsequently be able to receive Events from that Provider.

When a received TCAP message arrives at the SS7 Stack, the Provider forwards the TCAP message as dialogue and component Events to its registered Listeners. This Event is sent out as a Unicast Event to a particular Listener, depending on the TCAP message's and Listeners address . Diagram 4.0 illustrates how an Event is distributed to a Listener.

Diagram 4 - Event Distribution


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.
 

JainSS7Factory singleton = JainSS7Factory.getInstance();

singleton.setPath("com.xxxx");

JainTcapStack myStack = null;

try {

} catch (SS7PeerUnavailableException e) {
   

}


 
 
 

public JainTcapListenerImpl(JainTcapProvider provider) {

// set this JainTcapListener for this address
userAddressList = new Vector();
ownAddress = new TcapUserAddress(signallingPointCode, ownSsn);
this.addUserAddress(ownAddress);

// 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.getJainTcapStackList();

if (availableStacks != null) {

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

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

JainTcapStack tmpStack = (JainTcapStack)availableStacks.elementAt(s);
try {
if ( tmpStack.getStackProtocol() == JainTcapStack.ITU_97_SUN) &&
tmpStack.getSignalingPointCode() == signallingPointCode){
// this is the stack we want to use
stack = tmpStack;

}

} catch (ParameterNotSetException pExcept) {
String errMsg = exception.getMessage();
}
}

if (stack == null){

// we haven't found a suitable stack so create one

myFactory.setPathName("com.sun");
stack = createJainTcapStack(JainTcapStack);

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

JainTcapProvider myprovider = stack.createAttachedProvider();

try {

myProvider.addJainTcapListener(this, ownAddress);
connectedToProvider = true;
} catch (TooManyListenersException tooManyListeners) {
String errMsg = tooManyListeners.getMessage();
}
}

// Processing of the ComponentIndEvent passed.

public void processComponentIndEvent(ComponentIndEvent event){

JainTcapProvider eventSource = event.getSource();

// At this stage we only that the event is a ComponentIndEvent
// therfore we find out the primitive type.

switch (event.getPrimitiveType()) {
case JainTcapProvider.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

String errMsg = exception.getMessage();

}
try {
Operation op = receivedInvoke.getOperationType();
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

String errMsg = 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

}
 

// Adds a TcapUserAddress 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(TcapUserAddress userAddress){

userAddressList.addElement(userAddress);
}

// Removes a TcapUserAddress from the list of User Addresses used by this JainTcapListener.

public void removeUserAddress(TcapUserAddress userAddress){

userAddressList.removeElement(userAddress);
}

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

public Vector getUserAddressList(){

return(this.userAddressList);
}

public void run() {

// create a new Invoke Request Event

Operation myOperation = new Operation();

// set appropriate Operation values
// .....................

InvokeReqEvent invokeComp = new InvokeReqEvent(this, myDialogueId, myOperation);

// now set the JAIN TCAP optional parameters of the component

invokeComp.setInvokeId(100);

Parameter params = new Parameter();

// set appropriate Parameter values
// .....................

invokeComp.setParameter(params);

// finally send the Invoke Component Event

myProvider.sendComponent(invokeComp);

//............

}

// initialise all variables

}



28 June 00
If you have any comments or queries, please mail them to JainTcapApiFeedback@aepona.Com

Copyright - 2000 Sun Microsystems