ProxyBranch

The ProxyBranch interface represents a single branch created by a Proxy for sending a SIP request to a specific target. It models the concept of a branch as described in RFC 3261, specifically within the context of stateful proxying. Each ProxyBranch is responsible for handling the unique transaction state associated with the request sent to its target, allowing applications to manage branch-specific behavior such as timeouts or retries. For example, in an application handling an INVITE request, a Proxy can generate multiple ProxyBranch objects, each targeting a different destination. You can customize each branch, such as setting a specific timeout for one branch while assigning a different timeout for another, before starting the proxying operation using the startProxy() method. The ProxyBranch interface is a key component in the SIP Servlet API for managing the branching behavior of SIP proxies.

Methods:

getRequest
SipServletRequest getRequest()
The method retrieves the SIP request associated with a specific ProxyBranch. This method allows access to the original request that is being proxied or will be proxied through this branch. It provides the application with details about the SIP message for inspection, modification, or logging purposes.
Returns:
An object representing the SIP request associated with the branch.

cancel
void cancel()
The cancel method cancels the specific ProxyBranch and any child branches created as a result of recursion. It sends a CANCEL SIP request to all proxied INVITE requests associated with this branch, terminating the proxy operation for this branch and its children. This method provides control over canceling individual branches, as opposed to the Proxy.cancel() method, which operates on all branches of the proxy.
Exception:
java.lang.IllegalStateException: Thrown if the transaction associated with this branch has already been completed (e.g., a final response has been sent) and the branch has no child branches to cancel.

cancel
void cancel(java.lang.String[] protocol,
            int[] reasonCode,
            java.lang.String[] reasonText)
This overloaded cancel method allows the application to specify the reason for canceling a specific ProxyBranch by including detailed Reason headers, as defined in RFC 3326. If the branch has child branches (e.g., due to recursion), they are also canceled with the specified reasons. These headers provide additional context for downstream entities, clarifying why the branch is being canceled. 
Parameters:
protocol: Specifies the source of the cause field in the Reason header.

• "SIP": Indicates the SIP protocol.
• "Q.850": Indicates ISDN cause codes.

reasonCode: The value of the cause field in the Reason header.

• For "SIP", this corresponds to the SIP response status code (e.g., 486 for "Busy Here").
• For "Q.850", this corresponds to an ISDN cause code (e.g., 16 for "Normal Call Clearing").

reasonText: A human-readable explanation of the reason for the cancellation.

getProxyBranchTimeout
int getProxyBranchTimeout()
The method retrieves the search timeout value associated with a specific ProxyBranch. This timeout determines how long the branch waits for a response before considering the operation as timed out. If the timeout value has not been explicitly set for the branch using setProxyBranchTimeout(int), it inherits the timeout value from the parent Proxy object.
Returns:
The current timeout value for the branch, in seconds.

setProxyBranchTimeout
void setProxyBranchTimeout(int seconds)
The method sets a custom search timeout value for a specific ProxyBranch object. This timeout determines how long the container waits for a final response from this branch before taking action, such as canceling the branch or moving to the next target in sequential proxying. This method allows overriding the default timeout inherited from the parent Proxy object.

• Sequential Proxying: When the timeout expires, the container cancels this branch and proxies to the next element in the target set.
• Parallel Proxying: The branch-specific timeout must be less than or equal to the overall proxy timeout (Proxy.getProxyTimeout()). When the branch-specific timeout expires, the branch is canceled, equivalent to an explicit call to cancel() for that branch, without affecting other branches.

Parameters: 
seconds: The new timeout value, in seconds, for this branch. Must be a positive integer. For parallel proxying, the value cannot exceed the overall proxy timeout.
Exception:
java.lang.IllegalArgumentException: Thrown if:

• The timeout value is negative.
• The value is too high or too low for the container’s configuration.
• In parallel proxying, the value exceeds the overall proxy timeout.

getRecurse
boolean getRecurse()
The method checks whether the recurse flag is enabled for the specific ProxyBranch. Recursion in this context refers to the behavior where the branch automatically handles redirect (3xx) responses by creating sub-branches to proxy the request to the addresses in the Contact header of the redirect response.

• Recursion Enabled (true): The branch automatically proxies to the destinations specified in the Contact headers of the redirect response.
• Recursion Disabled (false): The redirect response is passed to the application, and the application must handle it explicitly.

Returns:
A boolean value. true if recursing is enabled, and the branch will handle 3xx responses automatically. false if recursing is disabled, and 3xx responses are passed to the application for manual handling.

setRecurse
void setRecurse(boolean recurse)
The method configures whether the servlet engine should automatically handle recursion for a ProxyBranch. Recursion refers to the behavior where the branch automatically processes redirect (3xx) responses by creating sub-branches to proxy the request to the contact addresses specified in the Contact header of the response.

• Recursion Enabled (true): The branch automatically proxies to the destinations provided in the Contact headers of the redirect response.
• Recursion Disabled (false): The redirect response is passed to the application for manual handling. The application can choose to process the 3xx response, create new branches, or forward the redirect response upstream.

Parameters:
recurse: true enables recursion, allowing the branch to handle 3xx responses automatically. false disables recursion, passing 3xx responses to the application.

getRecordRoute
boolean getRecordRoute()
The method checks whether the "recordroute" flag is enabled for the ProxyBranch. This flag determines if a Record-Route header will be added to the proxied request. Record-Route header is used in SIP to ensure that subsequent requests in the same dialog traverse the same set of proxies. If enabled, the proxy inserts its URI into the Record-Route header of the proxied request.
Returns:
A boolean value. true indicates that a Record-Route header will be added to proxied requests. false indicates that no Record-Route header will be added.

setRecordRoute
void setRecordRoute(boolean rr)
The setRecordRoute method specifies whether a Record-Route header should be included in the requests proxied by this ProxyBranch. This header ensures that the proxy remains in the signaling path for all subsequent requests in the same session, enabling stateful handling and consistent routing.
Parameters:
rr: true adds a Record-Route header to proxied requests, ensuring the proxy remains in the signaling path. false omits the Record-Route header, allowing subsequent requests to bypass the proxy.
Exception:
java.lang.IllegalStateException: Thrown if the proxy branch has already been started (e.g., after calling startProxy).

getAddToPath
boolean getAddToPath()
The method retrieves the current state of the "addToPath" flag for the ProxyBranch. This flag determines whether a Path header will be added to the proxied requests when startProxy() is invoked. Path header is used in SIP to ensure that the proxy remains in the signaling path for requests sent to a registered user agent (UA) from the home proxy. The header is defined in RFC 3327.
Returns:
A boolean value. true if Path header will be added to proxied requests. false if Path header will not be added.

setAddToPath
void setAddToPath(boolean p)
The method configures whether the proxy should include a Path header in the REGISTER request for this ProxyBranch. The Path header ensures that the proxy remains in the signaling path for subsequent requests sent to the registered user agent (UA) by the home proxy. Defined in RFC 3327, the Path header specifies intermediate proxies that should remain in the signaling path for requests sent to a registered UA.
Parameters:
p: true adds a Path header to the proxied request, ensuring the proxy stays in the signaling path. false does not add a Path header, allowing subsequent requests to bypass the proxy.

getRecordRouteURI
SipURI getRecordRouteURI()
The method retrieves a SipURI that can be used by the application to add custom parameters to the Record-Route header for the current ProxyBranch. The Record-Route header ensures the proxy remains in the signaling path for all subsequent requests in the same SIP dialog. Parameters added to the returned SipURI can be used to persist application-specific state. These parameters will be sent to the endpoints and returned in subsequent requests for the dialog.
Only the parameters added to the returned URI are relevant and retrievable later. Other components of the URI, such as host, port, or scheme, are managed by the container and should not be modified.
Returns: 
A SipURI object whose parameters can be modified by the application. The parameters added to this URI will be accessible in subsequent requests via ServletRequest.getParameter(String).
Exceptions:
java.lang.IllegalStateException: Thrown if record-routing is not enabled for the proxy.

getPathURI
SipURI getPathURI()
The method retrieves a SipURI that can be used by the application to add custom parameters to the Path header. The Path header ensures that the proxy remains in the signaling path for requests sent to a registered user agent (UA) by the SIP registrar.
The custom parameters added to the Path URI allow the application to push state information to the registrar. These parameters are then returned in subsequent requests to the registered UA, enabling stateful session handling. The returned URI is used solely for adding parameters. Other components of the URI, such as host, port, or scheme, are managed by the container and should not be modified.
Returns:
A SipURI object whose parameters can be modified to include application-specific state in the Path header.
Exception:
java.lang.IllegalStateException: Thrown if the "addToPath" flag is not enabled for the proxy.

setOutboundInterface
void setOutboundInterface(java.net.InetSocketAddress address)
The method configures the outbound network interface and source port that the ProxyBranch should use when forwarding SIP requests. This is useful in multi-homed environments where a machine has multiple network interfaces. The method allows control over the interface and port used for outgoing SIP traffic.
The IP address in the InetSocketAddress must match one of the outbound interfaces configured in the SIP servlet container.
The port in the InetSocketAddress is treated as a suggestion. If the port is specified and available, the container will use it for:

• UDP packets as the source port.
• TCP connections as the originating source port.

If the specified port is unavailable, the container falls back to its default port allocation scheme.
The selected interface and port are used to generate system headers for the proxied request, including:

• Record-Route header: Accessible via getRecordRouteURI().
• Via header: Specifies the proxy's network path.
• Contact header: Defines how responses should be routed back.

Parameters:
address: The socket address specifying the IP address and port of the outbound interface. The IP address must be one of the outbound interfaces recognized by the SIP servlet container. The port is optional and treated as advisory.
Exceptions:
java.lang.IllegalArgumentException: Thrown if the specified InetSocketAddress is not a recognized outbound interface for the container.
java.lang.NullPointerException: Thrown if the address parameter is null.

setOutboundInterface
void setOutboundInterface(java.net.InetAddress address)
The method allows the application to specify the outbound network interface (identified by an IP address) for forwarding SIP requests on this ProxyBranch. This method is useful in multi-homed environments, where the system has multiple network interfaces, enabling the application to control which interface is used for outgoing traffic. The specified IP address must correspond to one of the outbound interfaces configured in the SIP servlet container.
Parameters:
address: The IP address representing the desired outbound interface. Must be one of the outbound interfaces recognized by the container. Used to construct system headers such as Record-Route and Via.
Exceptions:
java.lang.IllegalStateException: Thrown if the session associated with the branch has been invalidated.
java.lang.IllegalArgumentException: Thrown if the specified IP address is not recognized as one of the container's configured outbound interfaces.
java.lang.NullPointerException: Thrown if the address parameter is null.

getResponse
SipServletResponse getResponse()
The method retrieves the last SIP response received on this ProxyBranch. This method is useful for inspecting the outcome of the branch's proxy operation, such as identifying the status or headers of the last response.
Returns:
The most recent SipServletResponse object received on this branch. If no response has been received, the method returns null.

isStarted
boolean isStarted()
The method checks whether a ProxyBranch has been started. A branch is considered started if it has been initiated for proxying by calling Proxy.startProxy(). Branches created with proxyTo(URI) are always started immediately upon creation, while those created using Proxy.createProxyBranches(List) may be started later.
Returns:
true, if the branch has been started (proxying is in progress or completed). false if the branch has not yet been started.

getRecursedProxyBranches
java.util.List<ProxyBranch> getRecursedProxyBranches()
The method retrieves the top-level recursed branches created under the current ProxyBranch in response to a 3xx redirect response. These branches are created automatically if recursion is enabled for the proxy or branch. Recursion occurs when the Contact headers in a redirect response (3xx class) are used to proxy requests to alternate destinations.
If recursion is enabled, redirect responses result in child branches being created dynamically, forming a tree-like structure. This method returns only the immediate child branches of the current ProxyBranch.
Returns:
A list of ProxyBranch objects representing the top-level recursed branches directly below the current branch. If no recursed branches exist, the list will be empty.

getProxy
Proxy getProxy()
The method retrieves the Proxy object associated with the current ProxyBranch. This provides access to the parent proxy that manages the overall proxying operation involving this branch.
Returns:
The Proxy object associated with the current ProxyBranch.