Proxy

The Proxy interface represents the operation of proxying a SIP request in SIP servlet applications. To control how the proxying is carried out it uses a number of parameters: 

• The addToPath parameter determines whether the application adds a Path header to REGISTER requests, with a default value of false.
• The recurse parameter specifies whether the proxy automatically recurses to the next target on failure, and its default is true. 
• The recordRoute parameter controls whether the proxy includes a Record-Route header to ensure subsequent requests in the same dialog traverse the proxy, defaulting to false.
• The parallel parameter determines if the proxy operates in parallel (sending requests to multiple destinations simultaneously) or sequentially (trying one destination at a time), with the default set to true.
• The stateful parameter ensures that the proxy remains transaction stateful throughout the operation, providing reliability and consistency, with a default value of true.
• The supervised parameter specifies whether the application will be invoked for incoming responses related to the proxying operation and defaults to false.
• The proxyTimeout parameter sets the general timeout for the proxy operation, applying to both parallel and sequential proxying. In parallel proxying, it defines the maximum wait time for all branches before sending the best final response upstream, while in sequential proxying, it replaces the deprecated sequentialSearchTimeout parameter.
• The sequentialSearchTimeout, though deprecated, determines the time to wait for a final response from a branch before canceling and trying the next destination. 

These parameters collectively allow applications to customize key aspects of proxying, including failure handling, transaction state management, and routing behavior.

Methods:

getOriginalRequest
SipServletRequest getOriginalRequest()
The method retrieves the original SIP request that was received from the upstream caller before it was proxied. This method is useful when you need access to the details of the initial request for processing, such as headers, parameters, or other request-specific information.
Returns:
An object representing the incoming SIP request that was proxied. This object provides access to the original request's attributes, including headers, content, and parameters.

proxyTo
void proxyTo(URI uri)
The proxyTo method is used to proxy a SIP request to a specified destination. This allows the application to forward a SIP request to another endpoint, identified by the provided URI. It is a key function in implementing SIP proxy behavior, enabling routing and forwarding of requests within a SIP application.
Parameters:
uri: Specifies the destination where the SIP request should be proxied. Implementations are required to support SipURI arguments. They may optionally support other types of URIs, such as TelURI.
Exceptions:
java.lang.IllegalStateException: Thrown if the transaction has already been completed.
java.lang.IllegalArgumentException: Thrown when the provided URI is invalid for proxying.
java.lang.NullPointerException: Thrown when the uri parameter is null.

proxyTo
void proxyTo(java.util.List<? extends URI> uris)
The method proxies a SIP request to a specified list of destinations. This enables a SIP application to forward the same request to multiple URIs, which is useful for parallel forking, where the request is sent to multiple endpoints simultaneously.
Parameters:
uris: A list of URI objects representing the destinations to which the SIP request should be proxied. Each URI specifies a target, and implementations are required to support SipURI.
Exceptions:
java.lang.IllegalStateException: Thrown if the transaction has already been completed.
java.lang.IllegalArgumentException: Thrown if any of the destination URIs in the list has an unsupported scheme.
java.lang.NullPointerException: Thrown if any URI in the list is null.

cancel
void cancel()
The cancel method is used to cancel the proxy transaction, along with any child branches if recursion was enabled. This method is invoked to terminate ongoing proxy operations, ensuring that no further SIP signaling occurs on the associated branches.
Exception:
java.lang.IllegalStateException: Thrown if the transaction has already been completed.

cancel
void cancel(java.lang.String[] protocol,
            int[] reasonCode,
            java.lang.String[] reasonText)
This overloaded version of the cancel method allows for providing detailed reason information for canceling a proxy transaction by including appropriately formatted Reason headers as specified in RFC 3326. These headers inform downstream entities about the cause of the cancellation, which can be useful for debugging, logging, or routing decisions.
Parameters:
protocol: Specifies the protocol for the Reason header. Common values include:

• "SIP": Indicates the SIP protocol as the source of the cancellation cause.
• "Q.850": Used for ISDN cause codes.

Each entry corresponds to one branch of the proxy being canceled.
reasonCode: The cause code associated with the Reason header. For "SIP", this is the SIP response status code (e.g., 486 for "Busy Here"). For "Q.850", this is the ISDN cause code.
Each entry must match the corresponding protocol array element.
reasonText: A human-readable text explaining the reason for cancellation. This is an optional descriptive field that can add clarity to the cancellation cause.
Each entry must match the corresponding protocol array element.

getRecurse
boolean getRecurse()
The method checks whether the proxy object is set to recurse. Recursion in the context of SIP proxying refers to the behavior where the proxy automatically tries the next set of destinations from the contact header if the previous destinations fail (e.g., return non-successful responses like 404 Not Found or 480 Temporarily Unavailable).
If recursion is enabled (true), the proxy object will attempt to resolve and forward requests to additional contacts as specified by the SIP logic (e.g., DNS SRV lookups, contact lists).
If recursion is disabled (false), the proxy will not attempt further destinations automatically.
Returns:
A boolean value. true if recursion is enabled. Returns false if recursion is disabled.

setRecurse
void setRecurse(boolean recurse)
The method configures whether the servlet engine should automatically handle recursion for proxying. When recursion is enabled, the servlet engine will automatically proxy to contact addresses received in redirect (3xx) responses. If recursion is disabled, the redirect response will be passed to the application and ultimately to the upstream client if no better response is available.
Parameters:
recurse: Specifies the recursion behavior.

• true: Enables recursion, allowing automatic proxying to additional contact addresses from a 3xx response.
• false: Disables recursion, passing the 3xx response to the application for manual handling.

getRecordRoute
boolean getRecordRoute()
The method retrieves the current state of the "recordroute" flag for the proxy object. This flag determines whether subsequent invocations of proxyTo(URI) will include a Record-Route header in the proxied request. The Record-Route header is used in SIP to ensure that all future requests for the session traverse the same set of proxies, enabling stateful behavior and maintaining the route for the session.
Returns:
A boolean value. true if the Record-Route header will be added to proxied requests. Returns false if the Record-Route header will not be added.

setRecordRoute
void setRecordRoute(boolean rr)
The method configures whether the Record-Route header should be included in branches created during the proxy operation. This setting applies to all branches initiated after the method is called. Enabling this feature is critical for stateful proxies that require ongoing participation in the dialog.
Parameters:
rr: A boolean value. true enables Record-Route, ensuring the proxy remains in the signaling path. false disables Record-Route, allowing future requests to bypass the proxy.
Exception:
java.lang.IllegalStateException: Thrown if the proxy has already been started.

getParallel
boolean getParallel()
The getParallel method checks whether the proxy object is configured to proxy requests in parallel or sequentially. This method retrieves the current value of the "parallel" flag, which determines the proxying behavior:

• Parallel Proxying (true): The proxy sends the request to all specified destinations at the same time.
• Sequential Proxying (false): The proxy sends the request to destinations one by one, waiting for a response before attempting the next.

Returns:
A boolean value. true - the proxy is set to proxy requests in parallel. false - the proxy is set to proxy requests sequentially.

setParallel
void setParallel(boolean parallel)
The method configures whether the proxy should operate in parallel or sequential mode. This setting determines how the proxy sends requests to multiple destinations:

• Parallel Proxying (true): The proxy sends the request to all specified destinations simultaneously. This is useful for achieving faster response times, such as in scenarios involving simultaneous ringing of devices (forking).
• Sequential Proxying (false): The proxy sends the request to one destination at a time, waiting for a response before attempting the next destination. This approach is useful when destinations are prioritized or ordered.

Parameters:
A boolean value. true enables parallel proxying (simultaneous requests to all destinations). false enables sequential proxying (one destination at a time).

getStateful
boolean getStateful()
Deprecated: stateless proxy is no longer supported
The method checks whether the proxy operation is transaction stateful or stateless. However, as stateless proxying is no longer supported in the SIP Servlet API, this method is effectively deprecated and always returns true.
Returns:
Always returns true.

setStateful
void setStateful(boolean stateful)
Deprecated: stateless proxy is no longer supported
The method was originally used to specify whether the server should proxy requests statelessly or statefully. When set to true, the server would maintain transaction state during the proxy operation. Conversely, setting it to false indicated that the proxy should operate statelessly.
However, as stateless proxying is no longer supported, this method is now deprecated. Modern implementations always operate in a stateful manner, regardless of the value of the stateful parameter.
Parameters:
A boolean value. true indicates that the proxy operation should be transaction stateful (this is now the default behavior). false intended to indicate stateless proxying, but this option is no longer supported.

getSupervised
boolean getSupervised()
The method checks whether the controlling servlet will be invoked on incoming responses for the current proxy operation. This setting determines whether the application has the opportunity to process responses (e.g., SIP 200 OK, 486 Busy Here) before they are forwarded upstream.

• Supervised Proxying (true): The servlet will be invoked for incoming responses, allowing the application to inspect, modify, or process them.
• Unsupervised Proxying (false): The servlet will not be invoked for responses. Responses are automatically forwarded upstream without application-level intervention.

Returns:
A boolean value. true - the controlling servlet will be invoked for incoming responses. false - the servlet will not be invoked for responses.

setSupervised
void setSupervised(boolean supervised)
The method configures whether the controlling servlet should be invoked for incoming responses associated with the proxy operation. This setting determines if the application will be notified of and given the ability to process responses before they are forwarded upstream.

• Supervised Proxying (true): The controlling servlet will be invoked to handle incoming responses, allowing application-level processing.
• Unsupervised Proxying (false): Responses will bypass the application and be forwarded automatically, without invoking the controlling servlet.

Parameters:
A boolean value. true - the controlling servlet will be notified and can process the "best" response received. false - the servlet will not be notified, and responses are forwarded automatically.

getProxyTimeout
int getProxyTimeout()
The method retrieves the current proxy timeout value for the proxy operation. This timeout value specifies the maximum duration, in seconds, that the proxy will wait for a response from all destinations before considering the operation as timed out.
Returns:
int: The current proxy timeout value in seconds.

getSequentialSearchTimeout
int getSequentialSearchTimeout()
Deprecated. Applications should transition to using getProxyTimeout() for a consistent timeout configuration.
The method retrieves the current value of the sequential search timeout parameter. This timeout specifies the duration, in seconds, that the proxy waits for a response from a destination before attempting the next destination in a sequential search scenario.
Returns:
int: The current value of the sequential search timeout parameter, measured in seconds.

setProxyTimeout
void setProxyTimeout(int seconds)
The method sets the overall timeout value for the proxy operation, measured in seconds. It behaves differently depending on whether the proxy operates in sequential or parallel mode:

• Sequential Proxy: Specifies the timeout for each branch before moving to the next destination. Overrides any previously set value using the deprecated setSequentialSearchTimeout(int) method.
• Parallel Proxy: Specifies the upper limit for the entire proxy operation. If the timeout expires before the proxy completes (e.g., a final response is received), the proxy operation is canceled automatically, and no response is sent upstream.

Parameters:
seconds: Specifies the timeout duration:

• For sequential proxies, the wait time for each branch.
• For parallel proxies, the maximum wait time for the entire operation.

The value must be non-negative and within the limits defined by the container.
Exception:
java.lang.IllegalArgumentException: Thrown if the timeout value is invalid (e.g., negative, excessively high, or below the container's allowed minimum).

setSequentialSearchTimeout
void setSequentialSearchTimeout(int seconds)
Deprecated. This method is deprecated in favor of the more general-purpose setProxyTimeout(int) method. Containers may choose to ignore this parameter and rely solely on setProxyTimeout(int).
The method sets the timeout value for sequential proxying operations. This timeout specifies how long the container waits for a final response from the current branch before canceling it and moving to the next destination in the target set. The method applies only when the proxy operates in sequential mode. When the timeout expires, the container cancels the current branch using a CANCEL request and attempts the next destination.
Parameters:
seconds: The amount of time, in seconds, the container waits for a final response before canceling the branch and moving to the next. Must be a non-negative value.

getRecordRouteURI
SipURI getRecordRouteURI()
The method returns a SipURI that can be used by the application to add custom parameters to the Record-Route header for the current proxy operation. This is useful for record-routing proxy applications that need to push application-specific state to the endpoints and retrieve it in subsequent requests belonging to the same dialog.
The returned SipURI allows the application to:

• Add custom parameters to the Record-Route header that will persist in the dialog.
• Retrieve these parameters later in the same dialog using ServletRequest.getParameter(java.lang.String).

The application must not modify SIP URI components defined by RFC 3261. This includes:

• Parameters: transport, user, method, ttl, maddr, and lr.
• Other URI components: host, port, URI scheme, etc.

Any attempt to modify these components will result in an IllegalArgumentException.
Changes to the Record-Route URI affect only branches created after the modification. Previously created branches retain their original Record-Route settings.
Returns:
A SipURI that allows the application to add parameters to the Record-Route header.
These parameters are accessible in subsequent requests within the same dialog.
Exceptions:
java.lang.IllegalStateException: Thrown if record-routing is not enabled for the proxy.
IllegalArgumentException: Thrown if the application attempts to modify restricted URI components or parameters.

createProxyBranches
java.util.List<ProxyBranch> createProxyBranches(java.util.List<? extends URI> targets)
The createProxyBranches method creates a list of ProxyBranch objects for a given set of target URIs. These branches represent potential proxy destinations but do not initiate client transactions until the startProxy() method is called. This allows for the configuration of branches before starting the actual proxying operation.
Implementations must support SipURI arguments. May optionally support other URI types (e.g., TelURI).
Parameters:
targets: A list of URI objects specifying the destinations to which the proxy will send requests.
Returns:
A list of ProxyBranch objects corresponding to the provided target URIs.
Exception:
java.lang.IllegalArgumentException: Thrown if any URI in the list contains a scheme that is not supported for proxying.

getProxyBranch
ProxyBranch getProxyBranch(URI uri)
Each ProxyBranch is uniquely tied to the URI used to create it. The getProxyBranch method retrieves the ProxyBranch object associated with a specific primary URI. The ProxyBranch may have been created via:

• The createProxyBranches(List<URI>) method.
• Implicitly, when proxyTo(URI) is called.
• Automatically, when a branch recurses as a result of a redirect response.

This method provides a way to retrieve and manage a specific ProxyBranch based on its URI.
Parameters:
uri: The URI used to create the ProxyBranch. This URI serves as a unique identifier for the branch.
Returns:
The ProxyBranch associated with the given URI. If no branch exists for the specified URI, the method may return null.

getProxyBranches
java.util.List<ProxyBranch> getProxyBranches()
The getProxyBranches method retrieves a list of all top-level branches associated with the proxy. These branches are created when:

• proxyTo(List<URI>) is called.
• createProxyBranches(List<URI>) is used.

This method does not return sub-branches created as a result of recursion. If recursion is enabled and a branch generates sub-branches (e.g., in response to a 3xx Redirect response), only the original top-level branches are included in the returned list.
Returns:
A list of ProxyBranch objects representing the top-level branches associated with the proxy.

startProxy
void startProxy()
The method begins the proxying operation for the set of destinations that were previously specified using the createProxyBranches(java.util.List) method. This method:

• Initiates all the proxy branches and their associated client transactions.
• Processes the destinations added to the target set through one or more calls to createProxyBranches(List).

The primary advantage of using startProxy over proxyTo(List) is that it allows for finer control over individual branches via the ProxyBranch class before starting the proxy operation. Using createProxyBranches followed by startProxy is equivalent to directly calling proxyTo(List) but provides more flexibility.
Exception:
java.lang.IllegalStateException: Thrown if no branches have been created using createProxyBranches(List), or the proxy operation has already completed (a final response has been sent upstream).

setOutboundInterface
void setOutboundInterface(java.net.InetSocketAddress address)
The method specifies the outbound interface and port number that the proxy should use for its branches in a multi-homed environment (where the machine has multiple network interfaces). This setting ensures that proxy branches originating from this proxy use the specified network interface and port for sending SIP messages.
The IP address must be one of the outbound interfaces configured in the SIP servlet container.
The port is interpreted as a suggestion for the container to use. If the port is unavailable, the container will fall back to its default port allocation scheme.
Parameters:
address: A socket address representing the desired outbound interface (IP address) and port.
Exceptions:
java.lang.IllegalArgumentException: Thrown if the provided address is not recognized as one of the container's outbound interfaces.
java.lang.NullPointerException: Thrown if the address parameter is null.

setOutboundInterface
void setOutboundInterface(java.net.InetAddress address)
The method specifies the outbound interface (identified by an IP address) to be used when sending SIP requests for proxy branches in a multi-homed environment. This is important for controlling which network interface is used for outgoing traffic on machines with multiple network interfaces.
The specified IP address impacts the system headers generated by the container. 
Record-Route via the getRecordRouteURI() method. 
Via - identifies the source of the SIP message. 
The chosen IP address is used to construct these headers, which may influence routing and response handling.
Parameters:
address: The IP address representing the desired outbound interface. The IP address must match one of the configured outbound interfaces in the SIP servlet container.
Exceptions:
java.lang.IllegalStateException: Thrown if the method is called on an invalidated session (e.g., after the session has been terminated).
java.lang.IllegalArgumentException: Thrown if the provided IP address is not recognized as one of the container's outbound interfaces.
java.lang.NullPointerException: Thrown if the address parameter is null.

getAddToPath
boolean getAddToPath()
The method checks whether the "addToPath" flag is enabled for the proxy object. This flag determines whether a Path header will be added to the proxied request when proxyTo(URI) or startProxy() is invoked.
The Path header is used in SIP to indicate the route that subsequent requests should follow to reach the registered entity. Adding this header ensures that the proxy remains in the signaling path for future requests.
Returns:
A boolean value. true if the proxy will add a Path header to proxied requests and false if the proxy will not add a Path header.

setAddToPath
void setAddToPath(boolean p)
The method specifies whether the proxy should include a Path header in the proxied REGISTER requests. This header ensures that the proxy remains in the signaling path for subsequent requests sent to the registered user agent (UA) from the home proxy. As defined in RFC 3327, the Path header is used in SIP to specify intermediate proxies that must remain in the signaling path for requests sent to the UA. This helps maintain consistent routing in SIP networks. When enabled, the Path header for the servlet container will be added on top of any application-pushed Path headers (e.g., those added using SipServletRequest.pushPath()). The Path header helps specify that the proxy must stay in the signaling path for future requests.
Before enabling the addition of the Path header, check whether the UA supports the Path extension by inspecting the Supported header field in the SIP request.
Parameters:
p: true value - the proxy will add a Path header to proxied REGISTER requests, false - the proxy will not add a Path header.

getPathURI
SipURI getPathURI()
The method retrieves a SipURI that the application can use to add custom parameters to the Path header. This is used in applications where the proxy needs to push specific state information to the SIP registrar. The parameters added to the Path header can be retrieved later in subsequent requests for the registered user agent (UA). Parameters added through the SipURI returned by Path method are accessible in future requests using ServletRequest.getParameter(String).
The returned URI is intended solely for adding parameters that the application can retrieve later. Other URI components, such as host, port, and scheme, are managed by the container and cannot be relied upon for accurate values. Modifications to restricted URI components will throw an IllegalArgumentException.
Returns:
A SipURI object whose parameters can be customized by the application and used in the Path header.
Exception:
java.lang.IllegalStateException: Thrown if the "addToPath" flag is not enabled for the proxy operation.

setNoCancel
void setNoCancel(boolean noCancel)
The method configures whether the proxy cancels outstanding branches upon receiving the first 2xx INVITE response. By default, as defined in RFC 3261, Section 16.7 point 10, the proxy cancels all other branches once the first 2xx response is received. This method allows for overriding the default behavior to forward all 2xx responses upstream, which is defined in RFC 3841.
Parameters:
noCancel: If set to true, the proxy will not cancel outstanding branches when the first 2xx response is received, forwarding all 2xx responses upstream instead. Otherwise, the proxy will cancel all outstanding branches upon receiving the first 2xx response (default behavior).

getNoCancel
boolean getNoCancel()
The method checks whether the proxy is configured to not cancel outstanding branches upon receiving the first 2xx INVITE response. This method reflects the behavior set by the setNoCancel(boolean noCancel) method, allowing applications to verify whether the proxy will handle branches according to RFC 3841 or the default RFC 3261 behavior.
Returns:
true: The proxy will not cancel outstanding branches and will forward all 2xx responses upstream.
false: The proxy will cancel all remaining branches upon receiving the first 2xx response (default behavior).