Package org.jainslee.resources.sip

Interface Proxy

  • public interface Proxy
    The Proxy is a SLEE activity that represents the proxying operation for a single SIP request. The activity starts when getProxy() or getProxy(true) is called on an initial IncomingSipRequest. SBBs then configure the proxy activity and add targets to the target set using proxyTo(URI).

    Proxy Configuration

    Each 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 true.
    • 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 true.
    • 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.
    Note: The supervised property 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 Branches

    After 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 IllegalStateException will 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 Processing

    The 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.
    When the proxy determines that a response should be forwarded upstream, it will fire an IncomingSipResponse event 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. The SipSession of 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 Activity

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

    • Method Detail

      • proxyTo

        void proxyTo​(URI uri)

      • proxyTo

        void proxyTo​(URI[] uris)

      • cancel

        void cancel()
        Cancel all remaining proxy branches by sending a CANCEL request on each branch.

      • cancel

        void cancel​(Parameterable... headers)
        Cancel all remaining proxy branches by sending a CANCEL request on each branch, with the given Reason headers.
        Parameters:
        headers - zero or more Parameterable values that will be added to the outgoing CANCEL as Reason headers.
        Since:
        EasySIP 1.7

      • getRecurse

        boolean getRecurse()

      • setRecurse

        void setRecurse​(boolean recurse)

      • getRecordRoute

        boolean getRecordRoute()

      • setRecordRoute

        void setRecordRoute​(boolean recordRoute)

      • getParallel

        boolean getParallel()

      • setParallel

        void setParallel​(boolean parallel)

      • getSequentialSearchTimeout

        int getSequentialSearchTimeout()

      • setSequentialSearchTimeout

        void setSequentialSearchTimeout​(int seconds)

      • getRecordRouteURI

        SipURI getRecordRouteURI()

      • proxyInternal

        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.
        Parameters:
        uri - The URI to proxy to.
        Returns:
        true if the target node was operational at the time

      • suppress503Responses

        void suppress503Responses​(boolean suppress)
        Enable or disable suppression of 503 responses to this request. If enabled, 503 responses will be converted to 500 before being delivered to the service or forwarded upstream. This is to avoid redundant retries towards other SIS nodes by the upstream client. The default is disabled (leave 503 responses unchanged) which may be changed using the Suppress503Responses config property. This method overrides the Suppress503Responses config property.
        Parameters:
        suppress - true to suppress 503 responses for this request, false to leave them unchanged.

      • is503SuppressionEnabled

        boolean is503SuppressionEnabled()
        Determine if 503 suppression is been enabled for this request. Will be true if suppress503Responses(true) has been called, or the RA config property Suppress503Responses is true.