JAIN TCAP Requirements Specification - Requirements Definition

3 Requirements Definition

3.1 The JAIN TCAP Object Model

JAIN is built upon standardized Java APIs and Object technology. In Object Technology, data and programming logic are treated as objects. Unlike traditional computer programs, objects can be readily integrated into a running environment, accessed and managed remotely, debugged and maintained in live systems by standardized interfaces, etc.

A JAIN TCAP application can be either a traditional Java program or a JavaBean, where a JavaBean is a reusable software component/object. While JAIN does not mandate that all applications must be built as JavaBeans, the design of the API specification will not exclude any application from executing as a JavaBean. [Reference 6] The unifying features of a JavaBean are explained with examples at http://java.sun.com/beans/doc/beans.101.pdf. The main points are:

Introspection: Can be used by an application builder tool to discover the properties, methods and events of a JAIN TCAP object.
Customization: Allows an operator to dynamically change the properties of a JAIN TCAP object at run time using an application builder tool.
Events: Can be used to send TCAP messages between JAIN TCAP objects.
Persistence: Allows the state of a JAIN TCAP object to be stored for retrieval at a later time.

The three most important features of a JavaBean are:

Property Management: Properties are named attributes associated with a bean that can be read or written by calling appropriate methods on the bean.

Method Management: The methods a JavaBean exports are standard and extended Java methods which can be called from other objects or from a scripting environment, such as HTML invoking an applet. By default, all of the bean's public methods will be exported.

State Management: Events provide a way for one object to notify other objects that a change in state has occurred. Under the Java event model an event listener object can be registered with an event source. When the event source detects a state change it will call the appropriate method on the event listener object.

REQ-OM-01-01: The API specification shall adhere to the JavaBeans Model. [Reference 6]

If the JAIN TCAP API specification is implemented using JavaBeans it offers the advantage of using reusable objects in a plug and play fashion.

REQ-OM-02-01: The API implementation shall not be restricted to JavaBeans.

This permits the JAIN TCAP API specification to be implemented in standard Java code, such as a program, applet or servlet.

3.2 JAIN TCAP Naming Convention

JAIN TCAP objects must conform to a specific naming convention in order to support JavaBean implementation. [Reference 6] For a JavaBean to expose a property i.e. within a visual tool, it must supply an access method "get" to read the property value and/or a "set" method to write the property value. These "get" and "set" methods have the following signature:

public < PropertyType> get< PropertyName>();
public void set< PropertyName>(< PropertyType> a);

If we discover a matching pair of "get<PropertyName>" and "set<PropertyName>" methods that take and return the same type, then we regard these methods as defining a read-write property whose name will be "<propertyName>". For a Boolean property the access method "get" signature changes to:

public boolean is< PropertyName>();

REQ-NC-01-01: The API specification shall follow the JavaBean naming convention. [Reference 6]

REQ-NC-02-01: All access methods shall throw an exception when accessing a parameter that has not previously been set or is not supported by a specific implementation.

This will provide an efficient technique of inspecting whether a parameter has been set, or is not supported by an implementation as well as adhering to the Java language programming style.

3.3 JAIN TCAP Architecture

The JAIN TCAP API specification can be mapped onto the ATM example in Appendix IV. This is illustrated in Figure 3.1.

The JAIN TCAP API specification provides a Java specification that enables the Listener and the Provider to communicate by Event passing, as well as providing the added advantage of portable Listeners. A vendor dependent implementation (for example JNI) will enable the Provider to communicate with the SS7 stack.

The TCK and the RI will test the JAIN TCAP API specification similar to the way a human and an ATM machine test their interface to each other, where the TCK is equivalent to the human and the RI is equivalent to the machine. It is important to notice that the RI does not communicate with the bank, in that the RI will not try to emulate a SS7 stack.

The implementation of the JAIN TCAP API specification is dependent on three main entities.

JAIN TCAP Events: - within the API, Events are TCAP messages which have been encapsulated as JAIN TCAP Events that are passed between the Listener and the Provider.
JAIN TCAP Provider: - within the API, the Provider is defined as a Java interface, the implementation of this interface is the main communication point to the TCAP layer of any JAIN compliant stack.
JAIN TCAP Listener: - within the API, the Listener is defined as a Java interface, the implementation of this interface may be any TCAP User (TC-User) application.

The relationship between these three sections is illustrated in Figure 3.2:

3.3.1 Event Requirements

3.3.1.1 JAIN TCAP Event Processing

JAIN TCAP messages are passed from the protocol stack to the applications as Event Objects. Event handling methods defined in the EventListener interface conform to a standard naming convention: void <eventOccurenceMethodName>(<EventStateObjectType> event);

where the <EventStateObjectType> is a subclass of java.util.EventObject.
Event Provider classes provide methods for registering and de-registering event listeners, which allow potential EventListeners to establish an event flow from that Provider to the Listener. The standard naming convention for EventListener registration is: public void add< ListenerType>(< ListenerType> listener)                         throws java.util.TooManyListenersException,
                        throws java.util.ListenerAlreadyRegisteredException;
When this method is invoked, it depends on the implementation of the JAIN TCAP specification, whether or not the TooManyListenersException is thrown, however the ListenerAlreadyRegisteredException should always be thrown if the same primary JAIN TCAP Listener, tries to re-register with the same JAIN TCAP Provider with the same User Address. public void remove< ListenerType>(< ListenerType> listener);                         throws java.util.ListenerNotRegisteredException;
The ListenerNotRegisteredException should always be thrown if this method is invoked on a specific JAIN TCAP Listener, which is not registered with that JAIN TCAP Provider. An overview of the JAIN TCAP Event Processing model is illustrated in Figure 3.3.

Invoking the add<ListenerType> method adds the given listener to the set of Event Listeners registered for events associated with the <ListenerType>. Similarly invoking the remove<ListenerType> method removes the given Listener from the set of Event Listeners registered for Events associated with the <ListenerType>.

The error handling of the possible exceptions are all specific to the implementation of the JAIN TCAP specification, for example:

Adding the same JAIN TCAP Listener more than once to the same JAIN TCAP Provider.

Removing a JAIN TCAP Listener more than once from the same JAIN TCAP Provider.

Removing a JAIN TCAP Listener that is not registered with a JAIN TCAP Provider.

Adding more JAIN TCAP Listeners than a JAIN TCAP Provider can handle.

It should be noted that although JAIN TCAP Events are passed between the JAIN TCAP Provider and the JAIN TCAP Listener in both directions, the Event Listener relationship exists in one direction only. JAIN TCAP Listeners register as listeners of the Provider (Event source) and will receive Events from that Provider. The Provider, on the other hand, does not register as an Event Listener and does not 'listen' for Events. The Provider's send method is simply invoked by the Listener.

3.3.1.2 JAIN TCAP Events

JAIN TCAP Events, which are encapsulated TCAP messages, can contain dialogue or component information and the necessary operations to extract it.

REQ-ER-01-01: The API implementation shall send Component and Dialogue handling primitives between the JAIN TCAP Provider and the JAIN TCAP Listener as Events.

This will provide TCAP message passing from object to object, by following the JavaBean event model. [Reference 6]

REQ-ER-02-01: Events representing Component and Dialogue handling primitives shall be sent separately between the JAIN TCAP Provider and JAIN TCAP Listener.

Truer to TCAP processing, a TC-User must have the ability to send Component primitives to TCAP independently of Dialogue Handling primitives.

REQ-ER-03-01: Indication Events shall only be sent from the JAIN TCAP Provider to the JAIN TCAP Listener.

Only indication primitives can be sent from TCAP to the TC-User while only Request primitives may be sent from the TC-User to TCAP. It is important to distinguish between Request and Indication primitives, as a Request primitive might not have the same parameters as its corresponding Indication primitive. Furthermore, there are Indication primitives for which there are no corresponding Request primitives. By enforcing the same restriction on the API specification, the possibility of the JAIN TCAP Listener incorrectly sending an Event Indication to the JAIN TCAP Provider is avoided.

REQ-ER-04-01: Request Events shall only be sent from the JAIN TCAP Listener to the JAIN TCAP Provider.

This requirement prevents the possibility of the JAIN TCAP Provider incorrectly sending an Event Request to the JAIN TCAP Listener [See explanation for REQ-ER-03-01].

REQ-ER-05-01: Events with the same Dialogue Id shall be passed to the same JAIN TCAP Listener.

Dialogue Ids are independently assigned by each of the two nodes in communication via a transaction, enabling each node to uniquely identify the dialogue and associate the entire contents of the message with that particular dialogue. Since only one JAIN TCAP Listener will be used to handle a particular dialogue, all Request Events associated with that dialogue (identified by the Dialogue Id) should be passed to that JAIN TCAP Listener.

When a received TCAP message arrives at the SS7 Stack, the JAIN TCAP Provider forwards the TCAP message as a JAIN TCAP Event to the appropriate registered JAIN TCAP Listener(s). This event is sent as a Multicast Event to all JAIN TCAP Listeners associated with that User Address. Figure 3.4 shows a Provider "firing" an Event to a registered Listener.

REQ-ER-06-01: Events shall only be passed to the JAIN TCAP Listener(s) with the corresponding User Address.

Since a JAIN TCAP Listener (or set of Listeners in a loadshare configuration) can be identified within a particular node by a User Address, the Events intended for the JAIN TCAP Listener(s) should only be passed to the JAIN TCAP Listener(s) with that User Address.

3.3.2 JAIN TCAP Provider requirements

The implementation of the JAIN TCAP Provider interface provides the ability to communicate with the TCAP layer of the SS7 stack with the aid of vendor specific code. It is responsible for sending messages down the stack, keeping and maintaining a list of registered JAIN TCAP Listeners.

REQ-PR-01-01: One or more JAIN TCAP Providers shall have the capability to be attached or detached to a TCAP layer at any time.

This is necessary to handle the situation where a TCAP layer has been broken down into a number of signaling point codes within the SS7 stack. The "attach" functionality is part of the JAIN TCAP API specification, and enables the JAIN TCAP Provider to bind with the TCAP layer, which will initiate communication between the TCAP layer and the JAIN TCAP Provider. The JAIN TCAP Provider can attach to a stack during construction, attach after construction and detach at any time.

REQ-PR-02-01: The JAIN TCAP Provider shall have the capability to pass one or more Events to one or more registered JAIN TCAP Listeners.

A JAIN TCAP Provider may need the capability to communicate with one or more JAIN TCAP Listeners objects, even if the Listener objects are distributed [See Figure 4.1]. This is necessary to enable more than one JAIN TCAP Listener (TC-User) to use the services of a JAIN TCAP Provider (TCAP Layer of a SS7 stack). [See REQ-ER-03-01]

REQ-PR-03-01: A JAIN TCAP Provider shall be able to route messages to all JAIN TCAP Listeners registered with it.

When a JAIN TCAP Listener registers with one or more User Addresses the JAIN TCAP Provider must be able to route messages to those User Addresses.

REQ-PR-04-01: Only one JAIN TCAP Provider shall be used to handle a particular Dialogue.

This will ensure that a specific dialogue will always communicate via the same JAIN TCAP Provider.

REQ-PR-05-01: All Request Events associated with a Dialogue (identified by the Dialogue ID) shall be passed to that Dialogue's JAIN TCAP Provider.

[See Requirement REQ-ER-05-01].

3.3.2.1 JAIN TCAP Provider Peer Requirements

Within Java a Peer is a platform specific implementation of a Java Interface or API, therefore a JAIN TCAP Provider Peer is a stack vendor specific implementation of the JAIN TCAP Provider Interface.

REQ-PR-06-01: All TCAP messages shall be passed by the JAIN TCAP Provider peer to the JAIN TCAP Listener as Indication Events.

This will ensure that API specification will follow the JavaBean Event model. [See section 3.3.1.1]

REQ-PR-07-01: The JAIN TCAP Provider peer shall ensure that the order in which associated components encapsulated as Events are received by it, is the same order at, which they are passed to the TCAP layer.

This is necessary to prevent related components within a message arriving in the wrong order to the TCAP Layer. Within TCAP linked components must arrive to the layer in the correct sequential order.

REQ-PR-09-01: The API specification shall provide a common interface to access JAIN TCAP Provider peers.

This will ensure that additional JAIN TCAP Provider peer functionality is hidden from the JAIN TCAP Listener implementation, as well as providing a common method of instantiating JAIN TCAP Provider objects. A common Object Orientated design pattern used to handle this in other API's i.e. JTAPI, is the Peer Factory.

3.3.3 JAIN TCAP Listener Requirements

The implementation of the JAIN TCAP Listener interface provides the ability to register with the JAIN TCAP Provider, enabling the JAIN TCAP Listener to receive messages from the JAIN TCAP Provider. The JAIN TCAP Listener is responsible for receiving and processing these messages emitted by the JAIN TCAP Provider in the form of Events. To send a TCAP message the JAIN TCAP Listener creates a new Component or Dialogue handling primitive. The JAIN TCAP Listener passes the primitive as a JAIN TCAP Event to the JAIN TCAP Provider, which sends the JAIN TCAP Message into the SS7 Stack.

REQ-LR-01-01: All JAIN TCAP JAIN TCAP Listeners shall be able to register with all JAIN TCAP Providers.

This ensures that all JAIN TCAP Listeners are portable over all JAIN TCAP Providers, which is a fundamental requirement of the Java programming language i.e. write-once, run-anywhere.

3.3.3.1 JAIN TCAP Listener Events

REQ-LR-02-01: A JAIN TCAP Listener shall have the capability to pass one or more Events to one or more JAIN TCAP Providers. However, a JAIN TCAP Listener shall send an event to only one JAIN TCAP Provider at any specific time.

This allows the JAIN TCAP Listener to communicate with more than one JAIN TCAP Provider. It needs to be assumed that the JAIN TCAP Listener will accept Events from the JAIN TCAP Provider and vice versa, this enables the JAIN TCAP Listener and the JAIN TCAP Provider to communicate with each other via Event passing. This is necessary to enable a JAIN TCAP Listener (TC-User) to use the services of more than one JAIN TCAP Provider (TCAP Layer of a SS7 stack). [See REQ-ER-04-01]

3.3.3.2 JAIN TCAP Listener Registration

REQ-LR-03-01: The JAIN TCAP Listener shall receive TCAP messages encapsulated as JAIN TCAP Events from a JAIN TCAP Provider by following the JavaBean Event model. [See Section 3.3.1.1]

The JAIN TCAP Provider routes TCAP messages from the protocol stack to a JAIN TCAP Listener based on the Listeners User Address. The User Address consists of a Sub-System Number, a Signaling Point Code, and optionally a Global Title.

If a JAIN TCAP Listener wishes to receive Events from multiple JAIN TCAP Providers then that JAIN TCAP Listener shall register with each of the available JAIN TCAP Providers. Once the JAIN TCAP Listener has registered with the numerous JAIN TCAP Providers it can receive JAIN TCAP Events from any of the JAIN TCAP Providers. Figure 3.5 shows a JAIN TCAP Listener registered with multiple JAIN TCAP Providers.

REQ-LR-04-01: A JAIN TCAP Listener shall have the capability to register with one or more JAIN TCAP Providers using a unique User Address to receive Events.

Any JAIN TCAP Listener needs the capability to communicate with one or more JAIN TCAP Providers within the network. [See Section 3.3.1.1]

REQ-LR-05-01: The API specification shall not restrict a JAIN TCAP Listener from having multiple backup and load-share JAIN TCAP Listeners.

Many JAIN TCAP Listeners may be associated with the one User Address.

3.4 Component and Dialogue Handling

A generic set of primitives shall be created that abstract the functionality of the Component and Dialogue handling primitives of the supported variants. The mapping between these generic primitives and the variant specific primitives they represent is illustrated in Table 3.1 and Table 3.2.

Generic Primitive	Req	Ind	ITU '93	ITU '97	ANSI '92	ANSI '96
Unidirectional	X	X	Tc_Uni		Tc_Uni
Begin	X	X	Tc_Begin		Tc_Qwp/Tc_Qwop
Continue	X	X	Tc_Continue		Tc_Cwp/Tc_Cwop
End	X	X	Tc_End		Tc_Response
ProviderAbort		X	Tc_P_Abort		Tc_P_Abort
UserAbort	X	X	Tc_U_Abort		Tc_U_Abort
Notice		X	Tc_Notice

Table 3.1 – Mapping of Dialogue handling primitives

Generic Primitive	Req	Ind	ITU '93	ITU '97	ANSI '92	ANSI '96
Invoke	X	X	Tc_Invoke		Tc_invoke/Tc_Invoke_NL
Result	X	X	Tc_Result_L/Tc_Result_NL		Tc_Result_L/Tc_Result_NL
Error	X	X	TC_U_Error		Tc_Error
LocalReject		X	Tc_L_Reject
UserReject	X	X	Tc_U_Reject		Tc_Reject
RemoteReject		X	Tc_R_Reject
LocalCancel		X	Tc_L_Cancel		Tc_L_Cancel
UserCancel	X		Tc_U_Cancel		Tc_U_Cancel
TimerReset	X			Tc_Timer_Reset

Table 3.2 – Mapping of Component primitives

REQ-CD-01-01: The API shall incorporate a common set of primitives that will map to protocol variant information. [See Reference 2-5]

This provides a higher level of abstraction within the API.

Similar to the ATM example, the JAIN TCAP API specification can be mapped to an example of the real working of TCAP, i.e. Figure 2.4 "A Message Exchange for a Structured Dialogue". In Figure 3.6, the JAIN TCAP API specification focuses on the transfer of Events between the JAIN TCAP Listener and the JAIN TCAP Provider in either direction. This can be mapped to the passing of TCAP messages from an application (User 1) to the TCAP Layer and similarly on the remote node (Node 2), passing TCAP messages from the TCAP layer to the application (User 2). It is important to notice that the JAIN TCAP API specification as shown, encompasses the specification of the JAIN TCAP Listener, the JAIN TCAP Provider and the Events sent between them.

If you have any comments or queries, please mail them to [email protected]