Package com.opencloud.sip.biggroup

Interface ForkActivity

  • public interface ForkActivity
    Represents the state of a fork operation. When the fork is forkTo(java.util.List) started}, the initial INVITE is forwarded to a number of targets. The RA initiates a client transaction ("branch") for each target, and waits for the responses.

    The first branch to respond with a success (200-299) response is the winner, and the winning response will be fired on this activity as a ForkSuccessEvent. All outstanding branches are cancelled.

    If all branches return failure responses, a ForkFailEvent containing a "503 Service Unavailable" response is fired on the activity.

    If the timeout expires before a success response is received, then a a ForkFailEvent containing a "408 Request Timeout" response is fired on the activity, and all outstanding branches are cancelled.

    The activity ends when the ForkSuccessEvent or ForkFailEvent is fired, or if it is cancelled.

    ForkActivity Replication

    When the SIP RA's ReplicatedDialogSupport config property is True, ForkActivity state is replicated as well, but with some restrictions.

    SIP transaction state is not replicated, so if a node starts a ForkActivity and then dies, the INVITE client transactions started by the ForkActivity are lost, and the fork operation cannot succeed. However, some state about the ForkActivity is replicated, so that a surviving node may attempt to clean up.

    When a ForkActivity is accessed on another node, its getState() method will return ForkActivity.State.FAILOVER. In this state, the only operation the node can perform on the activity is to call cancel(List<SipURI>). This method will generate CANCELs for each target URI, in order to proactively end any INVITE transactions started by the failed node. The ForkActivity is also ended.

    If a Rhino node fails, and ForkActivity replication is enabled, any ForkActivities started by the failed node will be adopted by a surviving node. The RA on the surviving node will fire a ForkFailoverEvent on each activity, so an application can be notified that a failover has occurred. After a failover it is recommended to cancel the ForkActivity as above.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static class  ForkActivity.State
      Enum representing the current state of a ForkActivity.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      boolean cancel()
      Cancel the fork operation.
      boolean cancel​(TerminationReason reason)
      Cancel the fork operation.
      void cancel​(List<javax.sip.address.SipURI> targets)
      Used to cancel a fork that started on another node.
      void configureInitialRequests​(UpdateRequest updaterFunction)
      Specify how the initial outgoing requests of this fork activity will be modified before they are transmitted.
      void configureTerminationRequests​(UpdateTerminationRequest updaterFunction)
      Specify how termination requests generated by this fork activity will be modified before they are transmitted.
      void configureTimeout​(long timeout)
      Specify the maximum time to wait for a success response from any branch.
      void forkTo​(List<javax.sip.address.SipURI> targets)
      Forks the initial INVITE to the given targets.
      void forkTo​(List<javax.sip.address.SipURI> targets, com.opencloud.javax.sip.sessiontimer.SessionTimerOptions timerOptions)
      Forks the initial INVITE to the given targets, and requests a session timer on the resulting dialog.
      void forkTo​(List<javax.sip.address.SipURI> targets, String name)
      Forks the initial INVITE to the given targets.
      void forkTo​(List<javax.sip.address.SipURI> targets, String name, com.opencloud.javax.sip.sessiontimer.SessionTimerOptions timerOptions)
      Forks the initial INVITE to the given targets, and requests a session timer on the resulting dialog.
      javax.sip.ServerTransaction getServerTransaction()
      Get the server transaction that this activity was created with
      ForkActivity.State getState()
      Get the current state of this fork operation

    • Method Detail

      • configureInitialRequests

        void configureInitialRequests​(UpdateRequest updaterFunction)
        Specify how the initial outgoing requests of this fork activity will be modified before they are transmitted. By default, no modifications are performed.
        Parameters:
        updaterFunction - an UpdateRequest function that will update the initial request before it gets transmitted on a branch. Must not be null.
        Throws:
        IllegalStateException - if the fork activity was already started.

      • configureTerminationRequests

        void configureTerminationRequests​(UpdateTerminationRequest updaterFunction)
        Specify how termination requests generated by this fork activity will be modified before they are transmitted. A termination request is a CANCEL or BYE generated by the RA when it needs to terminate a branch (either because cancel() was called, a success response was received, or a timeout or other error occurred). The reason for termination is passed to the function so it can set any required headers. By default, no modifications are performed.
        Parameters:
        updaterFunction - an UpdateTerminationRequest function that will update a termination request before it gets transmitted on a branch. Must not be null.
        Throws:
        IllegalStateException - if the fork activity was already started.

      • configureTimeout

        void configureTimeout​(long timeout)
        Specify the maximum time to wait for a success response from any branch. The timeout will begin on the first forkTo call, if the timeout expires before a success response is received, then a ForkFailEvent containing a "408 Request Timeout" response is fired on the activity, and all outstanding branches are cancelled.
        Parameters:
        timeout - the maximum time (ms) to wait for a success response from any branch. Must be greater than 0.
        Throws:
        IllegalStateException - if the fork activity was already started.

      • forkTo

        void forkTo​(List<javax.sip.address.SipURI> targets)
        Forks the initial INVITE to the given targets. This method will attempt to resolve the target addresses, those that can't be resolved are skipped and ignored. If unable to send to any of the target addresses, a ForkFailEvent containing a "503 Service Unavailable" response is fired on the activity, and the activity is ended. If the fork operation hasn't started, will start the fork operation.
        Parameters:
        targets - the list of SIP targets that the initial INVITE will be forwarded to.

      • forkTo

        void forkTo​(List<javax.sip.address.SipURI> targets,
            com.opencloud.javax.sip.sessiontimer.SessionTimerOptions timerOptions)
        Forks the initial INVITE to the given targets, and requests a session timer on the resulting dialog. This method will attempt to resolve the target addresses, those that can't be resolved are skipped and ignored. If unable to send to any of the target addresses, a ForkFailEvent containing a "503 Service Unavailable" response is fired on the activity, and the activity is ended. If the fork operation hasn't started, will start the fork operation.
        Parameters:
        targets - the list of SIP targets that the initial INVITE will be forwarded to.
        timerOptions - the session timer options to be applied to the resulting dialog, may not be null.

      • forkTo

        void forkTo​(List<javax.sip.address.SipURI> targets,
            String name)
        Forks the initial INVITE to the given targets. This method will attempt to resolve the target addresses, those that can't be resolved are skipped and ignored. If unable to send to any of the target addresses, a ForkFailEvent containing a "503 Service Unavailable" response is fired on the activity, and the activity is ended. If the fork operation hasn't started, will start the fork operation.
        Parameters:
        targets - the list of SIP targets that the initial INVITE will be forwarded to.
        name - the fork group name for the list of targets to be used for statistics. A statistic parameter set will be created for every new value; it is therefore advised to use a small defined set of values.

      • forkTo

        void forkTo​(List<javax.sip.address.SipURI> targets,
            String name,
            com.opencloud.javax.sip.sessiontimer.SessionTimerOptions timerOptions)
        Forks the initial INVITE to the given targets, and requests a session timer on the resulting dialog. This method will attempt to resolve the target addresses, those that can't be resolved are skipped and ignored. If unable to send to any of the target addresses, a ForkFailEvent containing a "503 Service Unavailable" response is fired on the activity, and the activity is ended. If the fork operation hasn't started, will start the fork operation.
        Parameters:
        targets - the list of SIP targets that the initial INVITE will be forwarded to.
        name - the fork group name for the list of targets to be used for statistics. A statistic parameter set will be created for every new value; it is therefore advised to use a small defined set of values.
        timerOptions - the session timer options to be applied to the resulting dialog, may not be null.

      • cancel

        boolean cancel()
        Cancel the fork operation. If the operation is still in progress (ForkActivity.State.PROCEEDING state), then a CANCEL is sent on all outstanding branches, and the activity is ended. If the operation has already finished then this method call does nothing.
        Returns:
        true if the fork was successfully cancelled, or false if it has already finished
        Throws:
        IllegalStateException - if the fork operation was not started.

      • cancel

        boolean cancel​(TerminationReason reason)
        Cancel the fork operation. If the operation is still in progress (ForkActivity.State.PROCEEDING state), then a CANCEL is sent on all outstanding branches, and the activity is ended. If the operation has already finished then this method call does nothing.
        Parameters:
        reason - a TerminationReason value describing why the activity was cancelled.
        Returns:
        true if the fork was successfully cancelled, or false if it has already finished
        Throws:
        IllegalStateException - if the fork operation was not started.

      • cancel

        void cancel​(List<javax.sip.address.SipURI> targets)
        Used to cancel a fork that started on another node. If called on the same node that created the activity, targets is ignored and this method behaves exactly like cancel(). Otherwise, the RA generates CANCEL requests to the given URIs, using information that was saved from the original fork to ensure the CANCELs match the earlier INVITEs.

        When this method is called on a surviving node after a failover, the RA will try to help the calling party to clean up by sending a 487 Request Terminated response towards the calling party, as if that response was sent by the original server transaction, which no longer exists. This is so that the caller's UAC does not keep retransmitting an INVITE to the failed node. This response may be lost when using UDP, but will be retransmitted if INVITE retransmits arrive at the surviving node (due to external load balancer etc).

        Parameters:
        targets - the list of SIP targets that the CANCELs will be directed to.

      • getServerTransaction

        javax.sip.ServerTransaction getServerTransaction()
        Get the server transaction that this activity was created with
        Returns:
        the initial server transaction