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.

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.
int	hashCode() Get a hash code for this Dialog object.
boolean	isStateless() Determine if this Dialog object represents a stateless dialog.
void	refuseDialog() 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	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) 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	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.
String	toString() Get a string representation of this Dialog object.

Method Detail

sendInvoke

int sendInvoke(TcapOperation operation,
             boolean invokeIdPresent,
             int invokeId,
             boolean linkedIdPresent,
             int linkedId,
             long timeout,
             Object arg)
               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

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.

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.

Parameters:

userInformation - the user information to include in the abort

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

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

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.

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

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