public interface ProxyThe Proxy is a SLEE activity that represents the proxying operation for a single SIP request. The activity starts when
getProxy(true)is called on an initial
IncomingSipRequest. SBBs then configure the proxy activity and add targets to the target set using
Proxy ConfigurationEach Proxy activity has the following properties, which can be changed using the respective setter methods:
recurse: If this property is
true, the proxy activity will automatically try any alternative contacts in a 3xx response. Defaults to
recordRoute: If this property is
true, the proxy will add itself to the Record-Route header, so that the service will be invoked on any future in-dialog requests. Defaults to
parallel: Determines whether to proxy in parallel (ie. multiple branches active at the same time) or sequentially. Defaults to
true, proxy in parallel.
sequentialSearchTimeout: If the proxy activity is operating sequentially, then this property determines how long the proxy will wait for a final response before considering the current branch to be failed and trying the next branch. Defaults to 15 seconds.
supervisedproperty from SIP Servlet is not replicated here, because that functionality is replaced by defining event handler methods for response events. See Response Processing below.
Adding BranchesAfter creating the proxy, SBBs add branches by calling
proxyTo(URI)one or more times. Branches can be added at any time, unless the proxy has already forwarded the final response. In this case an
IllegalStateExceptionwill be thrown. The proxy sends the request out on each branch immediately, unless
getParallel()is false, in which case the proxy will wait until a final response is received, or the branch times out before trying the next branch. Services must attach to the proxy activity context in order to see the responses forwarded by the proxy.
The proxy activity implements the "Timer C" behaviour as specified in RFC 3261 section 16. That is, for INVITE transactions, the proxy allows at least 3 minutes between provisional responses. If no provisional or final response is seen in this time then the branch is cancelled. For non-INVITE transactions, the normal timeout of 32s applies. If this expires then the proxy behaves as though it received a "408 Request Timeout" response on the branch, and adds it to the response context. If the proxy is operating sequentially then the sequential search timeout takes precedence if it is smaller than 32s.
Response ProcessingThe proxy activity follows the rules in RFC 3261 section 16.7 for processing responses:
- 100 responses are dropped
- 101-199 provisional responses are forwarded upstream immediately, if a final response has not been forwarded yet.
- 200-299 final responses are forwarded upstream immediately, and all outstanding branches are cancelled.
- 300-699 final responses are added to the "response context". 6xx responses cause all outstanding branches to be cancelled. When all branches have completed and there were no 2xx responses, the "best" error response is chosen from the response context and forwarded upstream.
IncomingSipResponseevent on the proxy activity. SBBs that want to be notified of responses must declare the relevant response event handlers and be attached to the proxy activity context. If the SBB does nothing the response will be forwarded upstream automatically. The SBB may also generate its own responses, using
IncomingSipRequest.createResponse(int)as usual. These are handled by the proxy as follows:
- 101-199 provisional responses are sent immediately. These do not affect dialog state.
- 200-299 final responses are sent immediately and all remaining branches are cancelled. The RA
assumes the SBB wants to be the UAS and inserts a To-tag and Contact header in the response.
SipSessionof the original request now represents the confirmed dialog between the caller UAC and the SBB.
- If there are still branches active, 300-699 final responses sent by the SBB are added to the response context as above.
- If the SBB generates its own response while it is processing the best response event, then the SBB's response takes priority and is sent immediately instead.
- If the SBB adds another branch while processing the best response event, then the response is not sent, and the proxy waits until the new branch completes before selecting and forwarding the new best response. This is to support services that try alternate contacts if the first is not available, eg. Find Me/Follow Me.
Ending the Proxy ActivityA SIP proxy has to deal with the possibility that requests may fork downstream, and multiple 2xx responses may arrive for a single INVITE. RFC 3261 requires that proxies must forward all of these responses. The proxy cancels all other branches when the first 2xx arrives, but it is possible that there will be a race and late 2xx responses may still get through. For this reason the proxy activity stays alive for an additional 32s after forwarding the first 2xx, and if any late 2xx responses are seen in this time then they will be forwarded upstream as well. After 32s expires then the proxy activity ends.
If no 2xx responses are received, then the proxy activity will select the best response and fire the response event. If the SBB does not add any more branches, then the activity ends after the response event is delivered.
Nested Class Summary
Nested Classes Modifier and Type Interface Description
All Methods Instance Methods Abstract Methods Modifier and Type Method Description
cancel()Cancel all remaining proxy branches by sending a CANCEL request on each branch.
cancel(Parameterable... headers)Cancel all remaining proxy branches by sending a CANCEL request on each branch, with the given Reason headers.
proxyInternal(URI uri)proxy to an internal URI i.e. another node in the same cluster.
void proxyTo(URI uri)
void proxyTo(URI uris)
void cancel()Cancel all remaining proxy branches by sending a CANCEL request on each branch.
void cancel(Parameterable... headers)Cancel all remaining proxy branches by sending a CANCEL request on each branch, with the given Reason headers.
headers- zero or more
Parameterablevalues that will be added to the outgoing CANCEL as Reason headers.
- EasySIP 1.7
void setRecurse(boolean recurse)
void setRecordRoute(boolean recordRoute)
void setParallel(boolean parallel)
void setSequentialSearchTimeout(int seconds)
Proxy.ProxyResult proxyInternal(URI uri)proxy to an internal URI i.e. another node in the same cluster. The SIS will first check that the target node is operational and return immediately if it is not. If the URI includes an "`oc-node`" URI parameter it is used to determine the target node to check. If the URI includes an "`oc-cluster`" URI parameter the cluster ID will be used to determine if the node should be checked.
uri- The URI to proxy to.
- true if the target node was operational at the time