public interface ForkActivity
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
.
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.
Modifier and Type | Interface and Description |
---|---|
static class |
ForkActivity.State
Enum representing the current state of a
ForkActivity . |
Modifier and Type | Method and Description |
---|---|
boolean |
cancel()
Cancel the fork operation.
|
void |
cancel(List<SipURI> targets)
Used to cancel a fork that started on another node.
|
boolean |
cancel(TerminationReason reason)
Cancel the fork operation.
|
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<SipURI> targets)
Forks the initial INVITE to the given targets.
|
void |
forkTo(List<SipURI> targets,
SessionTimerOptions timerOptions)
Forks the initial INVITE to the given targets, and requests a session timer on
the resulting dialog.
|
void |
forkTo(List<SipURI> targets,
String name)
Forks the initial INVITE to the given targets.
|
void |
forkTo(List<SipURI> targets,
String name,
SessionTimerOptions timerOptions)
Forks the initial INVITE to the given targets, and requests a session timer on
the resulting dialog.
|
ServerTransaction |
getServerTransaction()
Get the server transaction that this activity was created with
|
ForkActivity.State |
getState()
Get the current state of this fork operation
|
void configureInitialRequests(UpdateRequest updaterFunction)
updaterFunction
- an UpdateRequest
function that will update
the initial request before it gets transmitted on a branch. Must not be null
.IllegalStateException
- if the fork activity was already started.void configureTerminationRequests(UpdateTerminationRequest updaterFunction)
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.updaterFunction
- an UpdateTerminationRequest
function that will update
a termination request before it gets transmitted on a branch. Must not be null
.IllegalStateException
- if the fork activity was already started.void configureTimeout(long timeout)
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.timeout
- the maximum time (ms) to wait for a success response from any branch. Must be greater than 0.IllegalStateException
- if the fork activity was already started.void forkTo(List<SipURI> targets)
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.targets
- the list of SIP targets that the initial INVITE will be forwarded to.void forkTo(List<SipURI> targets, SessionTimerOptions timerOptions)
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.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.void forkTo(List<SipURI> targets, String name)
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.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.void forkTo(List<SipURI> targets, String name, SessionTimerOptions timerOptions)
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.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.boolean cancel()
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.true
if the fork was successfully cancelled, or false
if it has already finishedIllegalStateException
- if the fork operation was not started.boolean cancel(TerminationReason reason)
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.reason
- a TerminationReason
value describing why the activity was cancelled.true
if the fork was successfully cancelled, or false
if it has already finishedIllegalStateException
- if the fork operation was not started.void cancel(List<SipURI> targets)
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).
targets
- the list of SIP targets that the CANCELs will be directed to.ForkActivity.State getState()
ForkActivity.State
value.ServerTransaction getServerTransaction()