Package 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.

    • 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

      • 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