jain.protocol.ss7.tcap
Interface JainTcapProvider

All Superinterfaces:

java.util.EventListener

public interface JainTcapProvider

extends java.util.EventListener

This interface must be implemented by any Object representing the JAIN TCAP layer of any SS7 stack that interacts directly with a proprietary (stack vendor specific) implementation of the TCAP layer. This interface defines the methods that will be used by any registered TCAP User application implementing the JainTcapListener interface to send component primitives and dialogue handling primitives. It must be noted that any object that implements the:

• JainTcapListener Interface is referred to as JainTcapListenerImpl.
• JainTcapProvider Interface is referred to as JainTcapProviderImpl.
• JainTcapStack Interface is referred to as JainTcapStackImpl.

A TCAP User application may send a number of Component Request primitives as ComponentReqEvents to a Provider object. When the TCAP User application (JainTcapListenerImpl) sends a Dialogue handling request primitive as a DialogueReqEvent this will trigger the JainTcapProviderImpl object to send of all of the associated Component requests that have been previously passed to the JainTcapProviderImpl. Since the same JainTcapProviderImpl will be used to handle a particular transaction, Dialogue Request Events with the same Originating Transaction Id must be sent to the same JainTcapProviderImpl.

This interface defines methods for:

• Sending ComponentReqEvents . Numerous Component requests may be sent to a JainTcapProviderImpl before they are transmitted to the remote JainTcapProviderImpl.
• Sending DialogueReqEvents . This will trigger the transmission of the Dialogue request primitive along with any associated Component request primitives to the destination node
• Adding a JainTcapListener to its list of registered Event Listeners. The JainTcapListenerImpl will register with the JainTcapProviderImpl with an User Address and become an Event Listener of that JainTcapProviderImpl object. Once registered as an Event Listener, a JainTcapListenerImpl will receive any Dialogue Indication primitives, and Component Indication primitives addressed to its User Address as Events.
• Removing a JainTcapListener from the JainTcapProviderImpl's list of Event Listeners. Once a JainTcapListenerImpl is de-registered, it will no longer receive any Events from that JainTcapProviderImpl.
• Retrieving a new Dialogue Id from TCAP.
• Releasing a Dialogue Id back into TCAP.

Version:

1.1

Author:

Sun Microsystems Inc.

See Also:

JainTcapListener, JainTcapStack

Method Summary

void	addJainTcapListener(JainTcapListener listener, SccpUserAddress userAddress) Adds a JainTcapListener to the list of registered Event Listeners of this JainTcapProviderImpl.
void	addJainTcapListener(JainTcapListener listener, TcapUserAddress userAddress) Deprecated. As of JAIN TCAP version 1.1. This method is replaced by the addJainTcapListener(JainTcapListener, SccpUserAddress) method.
JainTcapStack	getAttachedStack() Deprecated. As of JAIN TCAP v1.1. This class is no longer needed as a result of the addition of the getStack() class. The reason for deprecating this method is that the provider is attached implicitly.
int	getNewDialogueId() Returns a unique Dialogue Id to initiate a dialogue with another TCAP user.
int	getNewInvokeId(int dialogueId) Returns a unique Invoke Id for identifying invoke requests within the dialogue identified by the supplied Dialogue Id.
JainTcapStack	getStack() Returns the JainTcapStackImpl that this JainTcapProviderImpl is attached to.
boolean	isAttached() Deprecated. As of JAIN TCAP v1.1. No replacement, the JainTcapProvider is attached implicitly within the createProvider method call in the JainTcapStack Interface.
void	releaseDialogueId(int dialogueId) Release the dialogue Id back to the system.
void	releaseInvokeId(int invokeId, int dialogueId) Releases the unique Invoke Id, allowing it to be reused within the dialogue identified by the supplied Dialogue Id.
void	removeJainTcapListener(JainTcapListener listener) Removes a JainTcapListener from the list of registered JainTcapListeners of this JainTcapProviderImpl.
void	sendComponentReqEvent(ComponentReqEvent event) Sends a Component Request primitive into the TCAP layer of the SS7 protocol stack.
void	sendDialogueReqEvent(DialogueReqEvent event) Sends a Dialogue Request primitive into the TCAP layer of the SS7 protocol stack.

Method Detail

getNewDialogueId

public int getNewDialogueId()
                     throws IdNotAvailableException

Returns a unique Dialogue Id to initiate a dialogue with another TCAP user.

Returns:

the new Dialogue Id returned by the underlying TCAP layer

Throws:

IdNotAvailableException - if a new Dialogue Id is not available

releaseDialogueId

public void releaseDialogueId(int dialogueId)
                       throws IdNotAvailableException

Release the dialogue Id back to the system.
Note: In some SS7 stacks the TCAP Dialogue Id is automatically released following the end of a TCAP transaction. In such instances the implementation of this method may be left null.

Parameters:

dialogueId - the dialogue Id supplied to the method

Throws:

IdNotAvailableException - if a new Dialogue Id is not available

getNewInvokeId

public int getNewInvokeId(int dialogueId)
                   throws IdNotAvailableException

Returns a unique Invoke Id for identifying invoke requests within the dialogue identified by the supplied Dialogue Id. Each dialogue between two JainTcapListeners is identified by a unique Dialogue Id. Note that the returned Invoke Id will be unique for a particular Dialogue Id.

Parameters:

dialogueId - the dialogue Id supplied to the method

Returns:

an unused unique Invoke Id

Throws:

IdNotAvailableException - if an invoke Id is not available to the specified dialogue Id

releaseInvokeId

public void releaseInvokeId(int invokeId,
                            int dialogueId)
                     throws IdNotAvailableException

Releases the unique Invoke Id, allowing it to be reused within the dialogue identified by the supplied Dialogue Id.

Parameters:

invokeId - the invoke Id to be released

dialogueId - the dialogue Id from which to release the dialogue Id

Throws:

IdNotAvailableException - if an invoke Id is not available to the specified dialogue Id

sendComponentReqEvent

public void sendComponentReqEvent(ComponentReqEvent event)
                           throws MandatoryParameterNotSetException

Sends a Component Request primitive into the TCAP layer of the SS7 protocol stack.

Parameters:

event - the new component event supplied to the method

Throws:

MandatoryParameterNotSetException - thrown if all of the mandatory parameters required by this JainTcapProviderImpl, to send the Component Request are not set.
Note that different implementations of this JainTcapProvider interface will mandate that different parameters must be set for each ComponentReqEvent . It is recommended that the message detail returned in the MandatoryParameterNotSetException should be a String of the form:
"Parameter: not set"

sendDialogueReqEvent

public void sendDialogueReqEvent(DialogueReqEvent event)
                          throws MandatoryParameterNotSetException

Sends a Dialogue Request primitive into the TCAP layer of the SS7 protocol stack. This will trigger the transmission to the destination node of the Dialogue request primitive along with any associated Component request primitives that have previously been passed to this JainTcapProviderImpl. Since the same JainTcapProviderImpl will be used to handle a particular transaction, Dialogue Request Events with the same Originating Transaction Id must be sent to the same JainTcapProviderImpl.

Parameters:

event - the new dialogue event supplied to the method

Throws:

MandatoryParameterNotSetException - thrown if all of the mandatory parameters required by this JainTcapProviderImpl to send the Dialogue Request are not set.

Note to developers :- different implementations of this JainTcapProvider interface will mandate that different parameters must be set for each DialogueReqEvent . It is recommended that the detail message returned in the MandatoryParameterNotSetException should be a String of the form:

"Parameter: not set"

addJainTcapListener

public void addJainTcapListener(JainTcapListener listener,
                                TcapUserAddress userAddress)
                         throws java.util.TooManyListenersException,
                                ListenerAlreadyRegisteredException,
                                InvalidUserAddressException

Deprecated. As of JAIN TCAP version 1.1. This method is replaced by the addJainTcapListener(JainTcapListener, SccpUserAddress) method.

Adds a JainTcapListener to the list of registered Event Listeners of this JainTcapProviderImpl.

Parameters:

listener - the feature to be added to the JainTcapListener attribute

userAddress - the feature to be added to the JainTcapListener attribute

Throws:

java.util.TooManyListenersException - thrown if a limit is placed on the allowable number of registered JainTcapListeners, and this limit is exceeded.

ListenerAlreadyRegisteredException - thrown if the listener listener supplied is already registered

InvalidUserAddressException - thrown if the user address supplied is not a valid address

addJainTcapListener

public void addJainTcapListener(JainTcapListener listener,
                                SccpUserAddress userAddress)
                         throws java.util.TooManyListenersException,
                                ListenerAlreadyRegisteredException,
                                InvalidAddressException

Adds a JainTcapListener to the list of registered Event Listeners of this JainTcapProviderImpl.

Parameters:

listener - the feature to be added to the JainTcapListener attribute

userAddress - the feature to be added to the JainTcapListener attribute

Throws:

java.util.TooManyListenersException - thrown if a limit is placed on the allowable number of registered JainTcapListeners, and this limit is exceeded.

ListenerAlreadyRegisteredException - thrown if the listener listener supplied is already registered

InvalidAddressException - thrown if the user address supplied is not a valid address

removeJainTcapListener

public void removeJainTcapListener(JainTcapListener listener)
                            throws ListenerNotRegisteredException

Removes a JainTcapListener from the list of registered JainTcapListeners of this JainTcapProviderImpl.

Parameters:

listener - the listener to be removed from this provider

Throws:

ListenerNotRegisteredException - thrown if there is no such listener registered with this provider

getAttachedStack

public JainTcapStack getAttachedStack()

Deprecated. As of JAIN TCAP v1.1. This class is no longer needed as a result of the addition of the getStack() class. The reason for deprecating this method is that the provider is attached implicitly.

Returns the JainTcapStackImpl that this JainTcapProviderImpl is attached to.

Returns:

the attached JainTcapStack.

getStack

public JainTcapStack getStack()

Returns the JainTcapStackImpl that this JainTcapProviderImpl is attached to.

Returns:

the attached JainTcapStack.

Since:

version 1.1

isAttached

public boolean isAttached()

Deprecated. As of JAIN TCAP v1.1. No replacement, the JainTcapProvider is attached implicitly within the createProvider method call in the JainTcapStack Interface.