ProxyBranch (SIP Servlet API 2.0 API)

public interface ProxyBranch

A ProxyBranch represents a branch which the Proxy sends out the request on. The ProxyBranch object models the branch as used in RFC3261 while describing a stateful proxy. For example,

   public void doInvite(SipServletRequest req) {
     ...
     Proxy p = req.getProxy();
     p.setRecordRoute(true);
     List branches = p.createProxyBranches(getTargets(req));
     branches.get(0).setProxyBranchTimeout(5);
     branches.get(1).setProxyBranchTimeout(10);
     p.startProxy();
     ...
   }

Since:: 1.1

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static interface ProxyBranch.Callback
Application may use an implementation of this interface to be called back by the container.

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`ProxyBranch.Callback` Application may use an implementation of this interface to be called back by the container.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`cancel()` Cancels this branch and all the child branches if recursion is enabled and sends a CANCEL to the proxied INVITEs.
`void`	`cancel(String[] protocol, int[] reasonCode, String[] reasonText)` This overloaded method of `cancel()` provides a way to specify the reason for cancelling this branch by including the appropriate Reason headers [RFC 3326].
`boolean`	`getAddToPath()` Returns true if subsequent invocations of `startProxy()` will add a Path header to the proxied request, false otherwise.
`Flow`	`getFlow()` Returns the flow used for sending or receiving messages on this `ProxyBranch`.
`SipURI`	`getPathURI()` Returns a `SipURI` that the application can use to add parameters to the Path header.
`Proxy`	`getProxy()`
`int`	`getProxyBranchTimeout()` Returns the current value of the search timeout associated with this `ProxyBranch` object.
`boolean`	`getRecordRoute()` Returns true if subsequent invocations of `proxyTo(URI)` will add a Record-Route header to the proxied request, false otherwise.
`SipURI`	`getRecordRouteURI()` Returns a `SipURI` that the application can use to add parameters to the Record-Route header.
`boolean`	`getRecurse()` Returns true if this proxy branch object is set to recurse, or false otherwise.
`List<ProxyBranch>`	`getRecursedProxyBranches()` Receipt of a 3xx class redirect response on a branch can result in recursed branches if the proxy or the branch has recursion enabled.
`SipServletRequest`	`getRequest()` Returns the request associated with this branch.
`SipServletResponse`	`getResponse()` Returns the last response received on this branch.
`boolean`	`isStarted()` The branch can be created using `Proxy.createProxyBranches(java.util.List)` and may be started at a later time by using `Proxy.startProxy()`.
`void`	`setAddToPath(boolean p)` Specifies whether this branch should include a Path header for the REGISTER request for this servlet container or not.
`void`	`setFlow(Flow flow)` Indicate that the specified flow be used while sending messages on this `ProxyBranch`.
`void`	`setOutboundInterface(InetAddress address)` In multi-homed environment this method can be used to select the outbound interface to use when sending requests for this proxy branch.
`void`	`setOutboundInterface(InetSocketAddress address)` In multi-homed environment this method can be used to select the outbound interface and source port number when forwarding requests for this proxy branch.
`void`	`setProxyBranchTimeout(int seconds)` Sets the search timeout value for this `ProxyBranch` object.
`void`	`setRecordRoute(boolean rr)` Specifies whether this branch should include a Record-Route header for this servlet engine or not.
`void`	`setRecurse(boolean recurse)` Specifies whether the servlet engine will automatically recurse or not.

- Method Detail
  - getRequest
```
SipServletRequest getRequest()
```
    Returns the request associated with this branch.
    
    Returns:
    object representing the request that is or to be proxied.
  - cancel
```
void cancel()
```
    Cancels this branch and all the child branches if recursion is enabled and sends a CANCEL to the proxied INVITEs. The effect is similar to Proxy.cancel() except that it is limited to this branch and its children only.
    
    Throws:
    
    IllegalStateException - if the transaction has already been completed and it has no child branches
  - cancel
```
void cancel(String[] protocol,
          int[] reasonCode,
          String[] reasonText)
```
    This overloaded method of cancel() provides a way to specify the reason for cancelling this branch by including the appropriate Reason headers [RFC 3326].
    
    Parameters:
    protocol - describes the source of the 'cause' field in the Reason header field.
    reasonCode - corresponds to the 'cause' field. For eg, if protocol is SIP, the reasonCode would be the status code of the response which caused the cancel
    reasonText - describes the reason for cancelling the Proxy.
    Since:
    
    1.1
  - getProxyBranchTimeout
```
int getProxyBranchTimeout()
```
    Returns the current value of the search timeout associated with this ProxyBranch object. If this value is not explicitly set using the setProxyBranchTimeout(int) then the value is inherited from the Proxy setting.
    
    Returns:
    the search timeout value in seconds
  - setProxyBranchTimeout
```
void setProxyBranchTimeout(int seconds)
```
    Sets the search timeout value for this ProxyBranch object. This is the amount of time the container waits for a final response when proxying on this branch. This method can be used to override the default timeout the branch obtains from the Proxy.setProxyTimeout(int) object. When the timer expires the container CANCELs this branch and proxies to the next element in the target set in case the proxy is a sequential proxy. In case the proxy is a parallel proxy then this can only set the timeout value of this branch to a value lower than the value in the proxy Proxy.getProxyTimeout(). The effect of expiry of this timeout in case of parallel proxy is just to cancel this branch as if an explicit call to cancel() has been made.
    
    Parameters:
    seconds - new search timeout in seconds
    
    Throws:
    
    IllegalArgumentException - if this value cannot be set by the container. Either it is too high, too low, negative or greater than the overall proxy timeout value in parallel case.
  - getRecurse
```
boolean getRecurse()
```
    Returns true if this proxy branch object is set to recurse, or false otherwise.
    
    Returns:
    true if recursing is enabled, false otherwise
  - setRecurse
```
void setRecurse(boolean recurse)
```
    Specifies whether the servlet engine will automatically recurse or not. If recursion is enabled the servlet engine will automatically attempt to proxy to contact addresses received in redirect (3xx) responses. If recursion is disabled and no better response is received, a redirect response will be passed to the application and will be passed upstream towards the client.
    
    Parameters:
    recurse - if true enables recursion, otherwise disables it
  - getRecordRoute
```
boolean getRecordRoute()
```
    Returns true if subsequent invocations of proxyTo(URI) will add a Record-Route header to the proxied request, false otherwise.
    
    Returns:
    value of the "recordroute" flag
  - setRecordRoute
```
void setRecordRoute(boolean rr)
```
    Specifies whether this branch should include a Record-Route header for this servlet engine or not.
    
    Record-routing is used to specify that this servlet engine must stay on the signaling path of subsequent requests.
    
    Parameters:
    rr - if true the engine will record-route, otherwise it won't
    
    Throws:
    
    IllegalStateException - if the proxy has already been started
  - getAddToPath
```
boolean getAddToPath()
```
    Returns true if subsequent invocations of startProxy() will add a Path header to the proxied request, false otherwise.
    
    Returns:
    value of the "addToPath" flag
    Since:
    
    1.1
  - setAddToPath
```
void setAddToPath(boolean p)
```
    Specifies whether this branch should include a Path header for the REGISTER request for this servlet container or not.
    Path header is used to specify that this Proxy must stay on the signaling path of subsequent requests sent to the Registered UA from the Home Proxy in the network. As a best practice, before calling this method a proxy should check if the UA has indicated support for the Path extension by checking the Supported header field value in the request being proxied. The detailed procedure of Path header handling is defined in RFC 3327.
    
    Parameters:
    p - if true the container will add Path header
    Since:
    
    1.1
  - getRecordRouteURI
```
SipURI getRecordRouteURI()
```
    Returns a SipURI that the application can use to add parameters to the Record-Route header. This is used by record-routing proxy applications in order to push state to the endpoints and have it returned in subsequent requests belonging to the same dialog.
    Parameters added through a URI returned by this method can be retrieved from a subsequent request in the same dialog by calling ServletRequest.getParameter(java.lang.String).
    Note that the URI returned is good only for specifying a set of parameters that the application can retrieve when invoked to handle subsequent requests in the same dialog. Other components of the URI are irrelevant and cannot be trusted to reflect the actual values that the container will be using when inserting a Record-Route header into proxied request.
    
    Returns:
    SIP URI whose parameters can be modified and then retrieved by this application when processing subsequent requests in the same SIP dialog
    
    Throws:
    
    IllegalStateException - if record-routing is not enabled
  - getPathURI
```
SipURI getPathURI()
```
    Returns a SipURI that the application can use to add parameters to the Path header. This may be used by Path header adding proxy applications in order to push state to the Registrar and have it returned in subsequent requests for the registered UA.
    Parameters added through a URI returned by this method can be retrieved from a subsequent request in the same dialog by calling ServletRequest.getParameter(java.lang.String).
    Note that the URI returned is good only for specifying a set of parameters that the application can retrieve when invoked to handle subsequent requests Other components of the URI are irrelevant and cannot be trusted to reflect the actual values that the container will be using when inserting a Path header into proxied request.
    
    Returns:
    SIP URI whose parameters can be modified and then retrieved by this application when processing subsequent requests for the UA
    
    Throws:
    
    IllegalStateException - if addToPath is not enabled
    Since:
    
    1.1
  - setOutboundInterface
```
void setOutboundInterface(InetSocketAddress address)
```
    In multi-homed environment this method can be used to select the outbound interface and source port number when forwarding requests for this proxy branch. The specified address must be the address of one of the configured outbound interfaces. The set of SipURI objects which represent the supported outbound interfaces can be obtained from the servlet context attributes named javax.servlet.sip.outboundAddresses and javax.servlet.sip.outboundInterfaces.
    The port is interpreted as an advice by the app to the container. If the port of the socket address has a non-zero value, the container will make a best-effort attempt to use it as the source port number for UDP packets, or as a source port number for TCP connections it originates. If the port is not available, the container will use its default port allocation scheme.
    Invocation of this method also impacts the system headers generated by the container for this ProxyBranch, such as the Record-Route header (getRecordRouteURI()), the Via and the Contact header. The IP address part of the socket address is used to construct these system headers.
    
    Parameters:
    address - the socket address representing the outbound interface to use when forwarding requests with this proxy branch
    
    Throws:
    
    IllegalArgumentException - if the address is not understood by the container as one of its outbound interface
    
    NullPointerException - on null address
    Since:
    
    1.1
  - setFlow
```
void setFlow(Flow flow)
```
    Indicate that the specified flow be used while sending messages on this ProxyBranch.
    
    Parameters:
    flow - Flow instance to be used while sending the messages.
    
    Throws:
    
    IllegalArgumentException - if the Flow does not exist or the transport association represented by the flow is broken or not known to the container.
    Since:
    
    2.0
    
    See Also:
    Flow
  - getFlow
```
Flow getFlow()
```
    Returns the flow used for sending or receiving messages on this ProxyBranch.
    
    Returns:
    Flow Returns the instance flow that is used for sending or receiving the messages. Null, if there is no flow as per RFC 5626 is associated with this ProxyBranch.
    Since:
    
    2.0
    
    See Also:
    Flow
  - setOutboundInterface
```
void setOutboundInterface(InetAddress address)
```
    In multi-homed environment this method can be used to select the outbound interface to use when sending requests for this proxy branch. The specified address must be the address of one of the configured outbound interfaces. The set of SipURI objects which represent the supported outbound interfaces can be obtained from the servlet context attributes named javax.servlet.sip.outboundAddresses and javax.servlet.sip.outboundInterfaces.
    Invocation of this method also impacts the system headers generated by the container for the branch, such as the Record-Route header (getRecordRouteURI()) and the Via. The supplied IP address is used to construct these system headers.
    
    Parameters:
    address - the address which represents the outbound interface
    
    Throws:
    
    IllegalStateException - if this method is called on an invalidated session
    
    IllegalArgumentException - if the address does not represent one of the container's outbound interfaces
    
    NullPointerException - on null address
    Since:
    
    1.1
  - getResponse
```
SipServletResponse getResponse()
```
    Returns the last response received on this branch.
    
    Returns:
    the last SipServletResponse received, or null if no response has been received so far.
  - isStarted
```
boolean isStarted()
```
    The branch can be created using Proxy.createProxyBranches(java.util.List) and may be started at a later time by using Proxy.startProxy(). This method tells if the given branch has been started yet or not. The branches created as a result of proxyTo are always started on creation.
    
    Returns:
    whether the branch has been started or not
  - getRecursedProxyBranches
```
List<ProxyBranch> getRecursedProxyBranches()
```
    Receipt of a 3xx class redirect response on a branch can result in recursed branches if the proxy or the branch has recursion enabled. This can result in several levels of recursed branches in a tree like fashion. This method returns the top level branches directly below this ProxyBranch
    
    Returns:
    the top level branches below this ProxyBranch
  - getProxy
```
Proxy getProxy()
```
    Returns:
    the associated proxy with this branch

Interface ProxyBranch

Nested Class Summary

Method Summary

Method Detail

getRequest

cancel

cancel

getProxyBranchTimeout

setProxyBranchTimeout

getRecurse

setRecurse

getRecordRoute

setRecordRoute

getAddToPath

setAddToPath

getRecordRouteURI

getPathURI

setOutboundInterface

setFlow

getFlow

setOutboundInterface

getResponse

isStarted

getRecursedProxyBranches

getProxy