com.opencloud.slee.resources.cgin

Interface Dialog

All Known Subinterfaces:

CAP1Dialog, CAP2Dialog, CAP3Dialog, CAP4Dialog, CCDialog, CS1Dialog, MAPDialog

public interface Dialog

Activity object representing a TCAP dialog managed by CGIN.

This interface provides facilities common to all CGIN dialogs. It is the activity object interface for all activities generated by a CGIN resource adaptor.

The methods dealing with operations and errors take metadata instances, built by the specific protocol in use, to identify the operation or error to operate on.

Many of the methods on this interface are intended for use by generated code, or by generic code that is not aware of the exact protocol in use. For this reason, they are generally verbose and there are no "helper" convenience methods. Each protocol implemented via CGIN will implement an extension interface that extends Dialog and provides methods that are specific to the operations and errors of that protocol, which is a more convenient interface to use for general service development.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Dialog.State An enumeration of the states a dialog may be in.

Field Summary

Fields

Modifier and Type	Field and Description
static int	INVOKE_ID_UNSPECIFIED An invoke ID value that indicates that the invoke ID is either unspecified or could not be derived.

Method Summary

Methods

Modifier and Type	Method and Description
void	acceptDialog() Issue a dialog open request acceptance response on this dialog.
void	acceptDialog(SccpAddress responderAddress, Object... userInformation) Issue a dialog open request acceptance response on this dialog.
boolean	equals(Object o) Determine if this Dialog object is equal to another specified object.
TcapApplicationContext	getApplicationContext() Get the application context currently in use on this dialog
ObjectID	getApplicationContextName() Get the application context name currently in use on this dialog.
String	getDialogID() Get a unique dialog identifier for this dialog.
Dialog.State	getDialogState() Get the current state of the dialog.
byte[]	getLocalTransactionID() Get the local TCAP transaction ID for this dialog.
int	getMTPPriority() Get the MTP3 message priority in use by this dialog.
CGINProvider	getProvider() Get the provider that created this dialog.
byte[]	getRemoteTransactionID() Get the remote TCAP transaction ID for this dialog.
int	getSCCPClass() Get the current SCCP class in use by this dialog.
boolean	getSCCPReturnOption() Get the current SCCP Return Option in use by this dialog.
TcapVersion	getTcapVersion() Gets the TCAP version being used for this dialog.
int	hashCode() Get a hash code for this Dialog object.
boolean	isGeneratingComponentEvents()
boolean	isGeneratingMessageEvents()
boolean	isStateless() Determine if this Dialog object represents a stateless dialog.
boolean	isUnidirectionalInbound() Determine if this Dialog object represents a unidirectional inbound dialog.
boolean	isWithPermission() Determine if permission is currently granted to send a close on this dialog.
void	refuseDialog() Refuse an open dialog request.
void	refuseDialog(OpenRefuseReason reason, TcapApplicationContext applicationContext, Object userAbortInformation, SccpAddress responderAddress, Object... userInformation) Refuse an open dialog request.
void	refuseDialog(OpenRefuseReason reason, TcapApplicationContext applicationContext, SccpAddress responderAddress, Object... userInformation) Refuse an open dialog request.
void	sendClose(boolean prearrangedEnd) Close the dialog.
void	sendDelimiter() Flush the operation requests and/or responses that have been queued on this dialog out to the network and the remote Provider.
void	sendDelimiter(boolean withPermission) Flush the operation requests and/or responses that have been queued on this dialog out to the network and the remote Provider.
void	sendError(int invokeId, TcapError error, Object parameter) Issue a user error response for an invoked operation on the dialog.
int	sendInvoke(TcapOperation operation, boolean invokeIdPresent, int invokeId, boolean linkedIdPresent, int linkedId, long timeout, Object arg, boolean lastInvoke) Issue an operation request on the dialog.
void	sendResult(int invokeId, Object result, boolean lastResult) Issue a result to an operation on the dialog.
void	sendUserAbort(Object... userInformation) Abort the dialog.
void	sendUserAbortWithUserAbortInformation(Object userAbortInformation, Object... userInformation) Abort the dialog.
void	setActivityTimeout(long timeout) Set the dialog activity timeout for this dialog.
void	setMTPPriority(int priority) Set the MTP3 message priority to use.
void	setRemoteAddress(SccpAddress remoteAddress) Set the remote SCCP address for future outgoing messages.
void	setSCCPClass(int c) Set the SCCP class to use for future outgoing messages.
void	setSCCPReturnOption(boolean returnErrors) Set the SCCP Return Option to use for future outgoing messages.
void	setTcapVersion(TcapVersion tcapVersion) Set the TCAP version to use.
String	toString() Get a string representation of this Dialog object.
Dialog	useComponentEvents() Indicate that this dialog only needs to generate component-based events.
Dialog	useMessageEvents() Indicate that this dialog only needs to generate message-based events.

Field Detail

INVOKE_ID_UNSPECIFIED

static final int INVOKE_ID_UNSPECIFIED

An invoke ID value that indicates that the invoke ID is either unspecified or could not be derived. This is for use with:

• ITU and ANSI TCAP - in a Reject component to indicate that the invoke ID of the rejected component could not be derived
• ANSI TCAP - for class 4 invokes that have no invoke ID

See Also:

Constant Field Values

Method Detail

useComponentEvents

Dialog useComponentEvents()

Indicate that this dialog only needs to generate component-based events. Other event APIs will be disabled.

Typically, this will be used as an optimization after creating an outbound dialog. The resource adaptor does not generally know whether the caller of CGINProvider.issueOpenRequest(com.opencloud.slee.resources.cgin.TcapApplicationContext, com.opencloud.slee.resources.cgin.SccpAddress) is expecting component-based events or message-based events (except in the special case where only one type of service is deployed), so both types of event will be generated on the new dialog by default. By calling disableComponentEvents() after creating an outbound dialog, the service can indicate that only needs component-based events to be generated for the new dialog.

Returns:

this, for invocation chaining

Throws:

IllegalStateException - if component events are not being generated on this dialog

useMessageEvents

Dialog useMessageEvents()

Indicate that this dialog only needs to generate message-based events. Other event APIs will be disabled.

Typically, this will be used as an optimization after creating an outbound dialog. The resource adaptor does not generally know whether the caller of CGINProvider.issueOpenRequest(com.opencloud.slee.resources.cgin.TcapApplicationContext, com.opencloud.slee.resources.cgin.SccpAddress) is expecting component-based events or message-based events (except in the special case where only one type of service is deployed), so both types of event will be generated on the new dialog by default. By calling useMessageEvents() after creating an outbound dialog, the service can indicate that it only needs needs message-based events to be generated for the new dialog.

Returns:

this, for invocation chaining

Throws:

IllegalStateException - if message events are not being generated on this dialog

isGeneratingComponentEvents

boolean isGeneratingComponentEvents()

Returns:

true if component-based events will be generated for this dialog

isGeneratingMessageEvents

boolean isGeneratingMessageEvents()

Returns:

true if message-based events will be generated for this dialog

sendInvoke

int sendInvoke(TcapOperation operation,
             boolean invokeIdPresent,
             int invokeId,
             boolean linkedIdPresent,
             int linkedId,
             long timeout,
             Object arg,
             boolean lastInvoke)
               throws TooManyInvokesException,
                      ProtocolException

Issue an operation request on the dialog. The request is queued for sending on the dialog but does not actually get sent to the remote Provider until a dialog component primitive (such as a delimiter) is sent on the dialog. A new invoke ID may optionally be allocated by the local provider.

Parameters:

operation - operation metadata object that identifies the operation to send

invokeIdPresent - if true, use the specified invoke ID; otherwise, allow the local provider to allocate an ID

invokeId - the invoke ID to use, if invokeIdPresent == true; must be in the range [-128..127]

linkedIdPresent - if true, use a linked ID in this operation

linkedId - the linked ID to use, if linkedIdPresent == true; must be in the range [-128..127]

timeout - invoke timeout for the operation, in milliseconds; if 0, use the provider's default

arg - the operation argument, or null if there is no argument

lastInvoke - true if this is the last invoke for the linked operation (InvokeL); false otherwise (InvokeNL). This should always be set to true for ITU TCAP.

Returns:

the invoke id allocated by the local provider for this operation

Throws:

TooManyInvokesException - if invokeIdPresent == false and too many invokes are already active on the dialog

ProtocolException - if a problem occurred sending the request

sendResult

void sendResult(int invokeId,
              Object result,
              boolean lastResult)
                throws ProtocolException

Issue a result to an operation on the dialog. The result is queued for sending on the dialog but does not actually get sent to the remote Provider until a dialog component primitive (such as a delimiter) is sent on the dialog.

Parameters:

invokeId - the invoke ID that is being responded to

result - the operation result, or null if there is no result value

lastResult - true if this is the last result for this operation (TC-RESULT-L); false otherwise (TC-RESULT-NL)

Throws:

ProtocolException - if a problem occurred sending the result

sendError

void sendError(int invokeId,
             TcapError error,
             Object parameter)
               throws ProtocolException

Issue a user error response for an invoked operation on the dialog. The response is queued for sending on the dialog but does not actually get sent to the remote Provider until a dialog component primitive (such as a delimiter) is sent on the dialog.

Parameters:

invokeId - the invoke ID of the operation to respond to

error - a metadata object identifying the error to send

parameter - the error parameter, or null if there is no associated parameter

Throws:

ProtocolException - if a problem occurred sending the error

sendDelimiter

void sendDelimiter()
                   throws ProtocolException

Flush the operation requests and/or responses that have been queued on this dialog out to the network and the remote Provider. The peer may close the dialog.

Throws:

ProtocolException - if a problem occurred sending the delimiter

sendDelimiter

void sendDelimiter(boolean withPermission)
                   throws ProtocolException

Flush the operation requests and/or responses that have been queued on this dialog out to the network and the remote Provider.

Parameters:

withPermission - whether or not the peer is permitted to close the dialog

Throws:

ProtocolException - if a problem occurred sending the delimiter

sendClose

void sendClose(boolean prearrangedEnd)
               throws ProtocolException

Close the dialog. Closing a dialog with prearrangedEnd == false causes a message to be sent over the network containing all operation requests and/or responses that have been queued on the dialog since it was opened or the last delimiter was sent. If prearrangedEnd == true, no network message is sent and the dialog is torn down by the local Provider, discarding any queued operation requests and/or responses.

Parameters:

prearrangedEnd - true if the dialog closure was "prearranged", false if not (a "basic end"). The typical argument value is false.

Throws:

ProtocolException - if there was a problem sending the dialog close

sendUserAbort

void sendUserAbort(Object... userInformation)
                   throws ProtocolException

Abort the dialog. A dialog can be aborted at any time. Any operation requests and/or responses that have been queued on the dialog since it was opened or the last delimiter was sent are discarded. The dialog is torn down by the local Provider as a result of this method.

Note that for ANSI TCAP 1988 dialogs this will send a Response without pending components, if any.

Parameters:

userInformation - the user information to include in the abort dialogue portion

Throws:

ProtocolException - if there was a problem sending the user abort

sendUserAbortWithUserAbortInformation

void sendUserAbortWithUserAbortInformation(Object userAbortInformation,
                                         Object... userInformation)
                                           throws ProtocolException

Abort the dialog. A dialog can be aborted at any time. Any operation requests and/or responses that have been queued on the dialog since it was opened or the last delimiter was sent are discarded. The dialog is torn down by the local Provider as a result of this method.

Parameters:

userAbortInformation - (ANSI TCAP only) the user abort information to include in the abort message

userInformation - the user information to include in the abort dialogue portion

Throws:

ProtocolException - if there was a problem sending the user abort

acceptDialog

void acceptDialog(SccpAddress responderAddress,
                Object... userInformation)
                  throws ProtocolException

Issue a dialog open request acceptance response on this dialog. The response is queued for sending on the dialog but does not actually get sent to the remote Provider until a dialog component primitive (such as a delimiter) is sent on the dialog.

Parameters:

responderAddress - the SCCP Address to use as the responding address in the Open Response instead of the address provided by the stack, or null to leave the address unchanged

userInformation - the user information to include in the responding TC-CONTINUE or TC-END

Throws:

ProtocolException - if the open response could not be sent

acceptDialog

void acceptDialog()
                  throws ProtocolException

Issue a dialog open request acceptance response on this dialog. The response is queued for sending on the dialog but does not actually get sent to the remote Provider until a dialog component primitive (such as a delimiter) is sent on the dialog.

This is a convenience method that is equivalent to calling: acceptDialog(null)

Throws:

ProtocolException - if there was a problem accepting the dialog open request

refuseDialog

void refuseDialog(OpenRefuseReason reason,
                TcapApplicationContext applicationContext,
                SccpAddress responderAddress,
                Object... userInformation)
                  throws ProtocolException

Refuse an open dialog request. The response is immediately sent to the remote Provider and the dialog is torn down.

Parameters:

reason - the refusal reason (must be PROVIDER_* (except PROVIDER_ABORT) or USER_*)

applicationContext - an alternative application context to include in the open refuse message, or null to leave the ACN unchanged

responderAddress - the SCCP Address to use as the responding address in the Open Response instead of the address provided by the stack, or null to leave the address unchanged

userInformation - the user information to include in the responding TC-U-ABORT or Abort

Throws:

ProtocolException - if the open response could not be sent

refuseDialog

void refuseDialog(OpenRefuseReason reason,
                TcapApplicationContext applicationContext,
                Object userAbortInformation,
                SccpAddress responderAddress,
                Object... userInformation)
                  throws ProtocolException

Refuse an open dialog request. The response is immediately sent to the remote Provider and the dialog is torn down..

Parameters:

reason - the refusal reason (must be PROVIDER_* (except PROVIDER_ABORT) or USER_*)

applicationContext - an alternative application context to include in the open refuse message, or null to leave the ACN unchanged

userAbortInformation - (ANSI TCAP 2000 only) the user abort information to include in the abort message

responderAddress - the SCCP Address to use as the responding address in the Open Response instead of the address provided by the stack, or null to leave the address unchanged

userInformation - the user information to include in the responding TC-U-ABORT or Abort

Throws:

ProtocolException - if the open response could not be sent

refuseDialog

void refuseDialog()
                  throws ProtocolException

Refuse an open dialog request. The response is immediately sent to the remote Provider and the dialog is torn down.

This is a convenience method that is equivalent to calling: refuseDialog(OpenRefuseReason.USER_NO_REASON_GIVEN,null,null)

Throws:

ProtocolException - if the open response could not be sent

getDialogState

Dialog.State getDialogState()

Get the current state of the dialog.

This always reflects the most recent state of the dialog in the TCAP stack, so the state may change spontaneously during event delivery, or may reflect a future state compared to the event currently being delivered.

For example, if a TC-CONTINUE then a TC-END are received on the same dialog in quick succession, the dialog state may become IDLE (reflecting processing of the TC-END) before events corresponding to the TC-CONTINUE have been delivered.

Returns:

the current dialog state

getApplicationContext

TcapApplicationContext getApplicationContext()

Get the application context currently in use on this dialog

Returns:

the application context.

getApplicationContextName

ObjectID getApplicationContextName()

Get the application context name currently in use on this dialog. This reflects the actual ACN used on the network and can be used by remapping-aware services to distinguish different ACNs that have been mapped to a single protocol.

Returns:

the application context name.

getDialogID

String getDialogID()

Get a unique dialog identifier for this dialog.

Returns:

the dialog identifier.

getLocalTransactionID

byte[] getLocalTransactionID()

Get the local TCAP transaction ID for this dialog.

Returns:

the local transaction ID, or null if one has not yet been allocated

getRemoteTransactionID

byte[] getRemoteTransactionID()

Get the remote TCAP transaction ID for this dialog.

Returns:

the remote transaction ID, or null if one has not yet been allocated

getProvider

CGINProvider getProvider()

Get the provider that created this dialog.

Returns:

the provider that created this dialog.

equals

boolean equals(Object o)

Determine if this Dialog object is equal to another specified object.

Overrides:

equals in class Object

Returns:

true if the specified object is of the same type as this Dialog object and has the same provider and activity handle, false otherwise.

hashCode

int hashCode()

Get a hash code for this Dialog object.

Overrides:

hashCode in class Object

Returns:

a hash code determined from the Dialog's underlying activity handle.

toString

String toString()

Get a string representation of this Dialog object.

Overrides:

toString in class Object

Returns:

a string representation of this object, determined from the Dialog's underlying activity handle.

isStateless

boolean isStateless()

Determine if this Dialog object represents a stateless dialog.

Returns:

true if this Dialog is stateless, or false if this Dialog is stateful.

isUnidirectionalInbound

boolean isUnidirectionalInbound()

Determine if this Dialog object represents a unidirectional inbound dialog.

Returns:

true if and only if this Dialog is unidirectional inbound

isWithPermission

boolean isWithPermission()

Determine if permission is currently granted to send a close on this dialog. For ANSI TCAP, returns the latest permission received on the dialog. (Note there's a race condition: even if this returns true, permission could be revoked before a close is sent. That's a problem with ANSI TCAP, not restricted to this implementation.) For ITU TCAP, returns whether the dialog has reached a state where at least one message has been received and the dialog isn't unidirectional and the dialog hasn't been closed yet.

Returns:

true if and only if close could be sent at this moment

setSCCPClass

void setSCCPClass(int c)
                  throws ProtocolException

Set the SCCP class to use for future outgoing messages.

• SCCP Class 0 provides unsequenced connectionless message delivery.
• SCCP Class 1 provides sequenced connectionless message delivery.

Other SCCP classes, providing connection-oriented services, are not supported by this resource adaptor.

For incoming dialogs, this setting defaults to the class used by the received TC-BEGIN For outgoing dialogs, this setting defaults to Class 1.

Parameters:

c - the SCCP class to use

Throws:

ProtocolException - if the dialog no longer exists, or the specified SCCP class is not supported

getSCCPClass

int getSCCPClass()
                 throws ProtocolException

Get the current SCCP class in use by this dialog.

Returns:

the SCCP class in use

Throws:

ProtocolException - if the dialog no longer exists

setSCCPReturnOption

void setSCCPReturnOption(boolean returnErrors)
                         throws ProtocolException

Set the SCCP Return Option to use for future outgoing messages.

For incoming dialogs, this setting defaults to the setting used by the received TC-BEGIN For outgoing dialogs, this setting defaults to true (return errors)

Parameters:

returnErrors - true to request "return errors"; false to request "discard errors"

Throws:

ProtocolException - if the dialog no longer exists

getSCCPReturnOption

boolean getSCCPReturnOption()
                            throws ProtocolException

Get the current SCCP Return Option in use by this dialog.

Returns:

true if the SCCP return option in use is "return errors"; false if it is "discard errors"

Throws:

ProtocolException - if the dialog no longer exists

setMTPPriority

void setMTPPriority(int priority)
                    throws ProtocolException

Set the MTP3 message priority to use.

For incoming and outgoing dialogs, this setting defaults to 0.

Parameters:

priority - the MTP3 priority to use

Throws:

ProtocolException - if the dialog no longer exists, or the given priority is not supported

getMTPPriority

int getMTPPriority()
                   throws ProtocolException

Get the MTP3 message priority in use by this dialog.

Returns:

the MTP3 message priority in use

Throws:

ProtocolException - if the dialog no longer exists

setTcapVersion

void setTcapVersion(TcapVersion tcapVersion)
                    throws ProtocolException

Set the TCAP version to use. This may only be set for incoming dialogs for which the TCAP version could not be automatically derived (i.e. there was no dialog portion containing a TCAP version field). It may only be set prior to accepting or refusing the dialog.

Parameters:

tcapVersion - the TCAP version to use when sending TCAP messages on this dialog

Throws:

ProtocolException - if the dialog no longer exists, or the given TCAP version is not supported

getTcapVersion

TcapVersion getTcapVersion()
                           throws ProtocolException

Gets the TCAP version being used for this dialog.

Returns:

the TCAP version in use

Throws:

ProtocolException - if the dialog no longer exists

setActivityTimeout

void setActivityTimeout(long timeout)
                        throws ProtocolException

Set the dialog activity timeout for this dialog.

If no messages are received or sent on the dialog for the given period of time, then the TCAP stack is permitted to decide that the dialog is dead and abort it to free resources.

Dialog activity timeouts are a "best effort" and may not be implemented (or may take longer than expected) depending on the underlying TCAP stack. They are present to provide a last resort attempt at cleaning up dialogs that would otherwise be leaked. The correct operation of services should not rely on the timeout occuring in a timely manner (or at all).

In particular, activity timeouts are generally not implemented for stateless dialogs.

Parameters:

timeout - the new activity timeout, in milliseconds; must be greater than zero

Throws:

ProtocolException - if the dialog no longer exists, or the given timeout is not supported

setRemoteAddress

void setRemoteAddress(SccpAddress remoteAddress)
                      throws ProtocolException

Set the remote SCCP address for future outgoing messages.

For incoming dialogs, this defaults to the address included in the received TC-BEGIN For outgoing dialogs, this defaults to the address that the TC-BEGIN was sent to

Parameters:

remoteAddress - the remote SCCP address to use in future messages

Throws:

ProtocolException - if the dialog no longer exists