|
||||||||||
PREV NEXT | FRAMES NO FRAMES |
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 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) 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 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.
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
public class Listener implements JainTcapListener {
// Obtain an instance of the Factory and set the path
JainSS7Factory singleton = JainSS7Factory.getInstance();
singleton.setPath("com.xxxx");
JainTcapStack myStack = null;
try {
myStack = (JainTcapStack)singleton.createSS7Object("jain.protocol.ss7.tcap.JainTcapStack");
myStack.setName("ANSI-96-SUN-255-255-255);
} catch (SS7PeerUnavailableException e) {
// Couldn't find the class com.xxxx.jain.protocol.ss7.tcap.JainTcapStack
System.err.println("The specified class could not be found in the CLASSPATH");
}
JainTcapProvider myProvider = myStack.createDetachedProvider();
// Note: this Provider is not attached (bound) to the underlying stack
// so I can now perform some initialization code before explicitly
// attaching to the stack
myStack.attach(myProvider);
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.
// set the user address for this User Application
TcapUserAddress myUserAddress = new TcapUserAddress(mySignallingPointCode, mySubSystemNumber);
// Register this User Application as an event Listener of the Provider
try {
myProvider.addJainTcapListener(this,
myUserAddress);
} catch(TooManyListenersException e) {
/* A limit has been reached
on the number */
/* of Listeners allowed
per provider */
};
This class will use the processDialogueIndEvent()
method to process the incomming dialogue indication primitives, and processComponentIndEvent()
method to process the incomming component indication primitives.
Request Component Events are created and sent to the Provider, interspersed
with dialogue request Events. First a request component 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.
// get a new Dialogue Id for use in this Dialogue
int myNewDialogueId = myProvider.getDialogueId();
// get a new Invoke Id for use within the Dialogue
int myNewInvokeId = myProvider.getInvokeId(myNewDialogueId);
Operation myOperation = new Operation();
myOperation.setOperationType(2);
myOperation.setOperationFamily(4);
myOperation.setOperationSpecifier(1);
InvokeReqEvent myInvokeReqEvent = new InvokeReqEvent(this, myNewDialogueId, myOperation);
// set the JAIN TCAP optional parameters of
the Invoke Event
myInvokeReqEvent.setInvokeId(myNewInvokeId);
myInvokeReqEvent.setTimeout(5000);
myInvokeReqEvent.setLastInvoke(true); // this
is the last Invoke
The component request primitive is then sent to the Provider.
try{
myProvider.sendComponentReqEvent(myInvokeReqEvent);
} catch (MandatoryParametersNotSetException 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, myUserAddress,
destinationAddress);
JAIN TCAP optional Parameters may then be set using the appropriate 'set'
methods:
myBeginRequestEvent.setQualityOfService(qos);
try {
myProvider.sendDialogueReqEvent(myBeginRequestEvent);
} catch (MandatoryParametersNotSetException e){
System.err.println("Some
of the required parameters were not set");
Tcap messages will be processed by the User Application's processComponentIndEvent
and processDialogueIndEvent() methods.
public class JainTcapListenerImpl implements JainTcapListener, Runnable {
Constructs a new JainTcapListenerImpl, sets its User Address, creates a new Provider and registers with it.
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 TcapStackJainSS7Factory 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 protocolfor (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} catch (ParameterNotSetException pExcept) {
stack = tmpStack;}
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 EventListenerJainTcapProvider 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();switch (event.getPrimitiveType()) {// At this stage we only that the event is a ComponentIndEvent
// therfore we find out the primitive type.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();} catch (ParameterNotSetException exception) {
int invokeId = receivedInvoke.getInvokeId();// Access the error MessageString errMsg = exception.getMessage();
try {} // end of processComponentIndEvent() methodOperation op = receivedInvoke.getOperationType();// Execute the Invoke primitive
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();
}
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
}
// 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() {
// initialise all variables// 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);
//............
}
}
|
||||||||||
PREV NEXT | FRAMES NO FRAMES |