jain.protocol.ss7.tcap
Interface JainTcapProvider


public abstract 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:

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 primitve 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:

Version:
1.0
Author:
Colm Hayden & Phelim O'Doherty
See Also:
JainTcapListener

Method Summary
 void addJainTcapListener(JainTcapListener listener, TcapUserAddress userAddress)
          Adds a JainTcapListener to the list of registered Event Listeners of this JainTcapProviderImpl.
 JainTcapStack getAttachedStack()
          Returns the JainTcapStackImpl that this JainTcapProviderImpl is attached to.
 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.
 boolean isAttached()
          Indicates if this JainTcapProviderImpl is attached to a JainTcapStackImpl.
 void releaseDialogueId(int dialogueId)
          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.
 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 there are no more available Invoke Ids

releaseDialogueId

public void releaseDialogueId(int dialogueId)
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 to be released

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 for which a new Invoke Id will be returned.
Returns:
a unique Invoke Id
Throws:
IdNotAvailableException - if there are no more available Invoke Ids

releaseInvokeId

public 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.
Parameters:
invokeId - the Invoke Id to be released back into the system.
dialogueId - the Dialogue Id identifying the dialogue in which the invoke Id is used.

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 Component Request event.
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 destionation 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 Dialogue Request event to be sent into the stack.
Throws:
MandatoryParameterNotSetException - thrown if all of the mandatory parameters required by this JainTcapProviderImpl to send the Dialogue Request are not set.
Note that 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,
                                SS7ListenerAlreadyRegisteredException
Adds a JainTcapListener to the list of registered Event Listeners of this JainTcapProviderImpl.
Parameters:
JainTcapListener - the JainTcapListenerImpl to be added.
userAddress - the User Address supported by the JainTcapListenerImpl.
Throws:
java.util.TooManyListenersException - thrown if a limit is placed on the allowable number of registered JainTcapListeners, and this limit is exceeded.

removeJainTcapListener

public void removeJainTcapListener(JainTcapListener listener)
                            throws SS7ListenerNotRegisteredException
Removes a JainTcapListener from the list of registered JainTcapListeners of this JainTcapProviderImpl.
Parameters:
JainTcapistener - the JainTcapListenerImpl to be removed from this JainTcapProviderImpl.
Throws:
ListenerNotRegisteredException - thrown if the JainTcapListenerImpl to be removed is not registered as an Event Listener of this JainTcapProviderImpl.

getAttachedStack

public JainTcapStack getAttachedStack()
                               throws ProviderNotAttachedException
Returns the JainTcapStackImpl that this JainTcapProviderImpl is attached to.
Returns:
the attached JainTcapStack.
Throws:
ProviderNotAttachedException - thrown if this method is invoked and this JainTcapProviderImpl is not attached to the JainTcapStackImpl.

isAttached

public boolean isAttached()
Indicates if this JainTcapProviderImpl is attached to a JainTcapStackImpl.
Returns:
  • true - this JainTcapProviderImpl is attached to a JainTcapStackImpl
  • false - this JainTcapProviderImpl is not attached to any JainTcapStackImpl


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

Copyright - 2000 Sun Microsystems