javax.servlet.sip
Interface Proxy

public interface Proxy

Represents the operation of proxying a SIP request.

A number of parameters control how proxying is carried out:

addToPath:

addToPath: Whether the application adds a Path header to the REGISTER request. The default is false.

recurse:

Whether to autmotically recurse or not. The default is true.

recordRoute:

Whether to record-route or not. The default is false.

parallel:

Whether to proxy in parallel or sequentially. The default is true.

stateful:

Whether to remain transaction stateful for the duration of the proxying operation. The default is true.

supervised:

Whether the application will be invoked on incoming responses related to this proxying.

proxyTimeout:

The timeout for the proxy in general. In case the proxy is a sequential proxy then this value behaves like the sequential-search-timeout which is deprecated since v1.1. In case the proxy is a parallel proxy then this timeout acts as the timeout for the entire proxy i.e each of its parallel branches before it starts to send out CANCELs waiting for final responses on all INVITE branches and sends the best final response upstream.

sequentialSearchTimeout:

The time the container waits for a final response before it CANCELs the branch and proxies to the next destination in the target set. The usage of this explicit sequential timeout setting is deprecated and replaced by a general proxyTimeout parameter.

The effect of the various parameters is explained further below.

Method Summary

void	cancel() Cancels this proxy transaction and any of its child branches if recursion was enabled.
void	cancel(java.lang.String[] protocol, int[] reasonCode, java.lang.String[] reasonText) This overloaded method of cancel() provides a way to specify the reason for cancelling this Proxy by including the appropriate Reason headers [RFC 3326].
java.util.List<ProxyBranch>	createProxyBranches(java.util.List<? extends URI> targets) Returns the list of ProxyBranch objects given a set of targets.
boolean	getAddToPath() Returns true if subsequent invocations of proxyTo(URI) or startProxy() will add a Path header to the proxied request, false otherwise.
boolean	getNoCancel() Returns true if the proxy will not cancel outstanding branches upon receiving the first 2xx INVITE response as in RFC 3841
SipServletRequest	getOriginalRequest() Returns the request received from the upstream caller.
boolean	getParallel() Returns true if this proxy object is set to proxy in parallel, or false if it is set to proxy sequentially.
SipURI	getPathURI() Returns a SipURI that the application can use to add parameters to the Path header.
ProxyBranch	getProxyBranch(URI uri) Any branch has a primary URI associated with it, using which it was created.
java.util.List<ProxyBranch>	getProxyBranches() More than one branches are associated with a proxy when proxyTo(List) or createProxyBranches(List) is used.
int	getProxyTimeout() The current value of the overall proxy timeout value.
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 object is set to recurse, or false otherwise.
int	getSequentialSearchTimeout() Deprecated. use a more general purpose getProxyTimeout()
boolean	getStateful() Deprecated. stateless proxy is no longer supported
boolean	getSupervised() Returns true if the controlling servlet will be invoked on incoming responses for this proxying operation, and false otherwise.
void	proxyTo(java.util.List<? extends URI> uris) Proxies a SIP request to the specified set of destinations.
void	proxyTo(URI uri) Proxies a SIP request to the specified destination.
void	setAddToPath(boolean p) Specifies whether branches initiated in this proxy operation should include a Path header for the REGISTER request for this servlet container or not.
void	setNoCancel(boolean noCancel) Specifies whether the proxy should, or should not cancel outstanding branches upon receiving the first 2xx INVITE response as defined in RFC 3841.
void	setOutboundInterface(java.net.InetAddress address) In multi-homed environment this method can be used to select the outbound interface to use when sending requests for proxy branches.
void	setOutboundInterface(java.net.InetSocketAddress address) In multi-homed environment this method can be used to select the outbound interface and port number to use for proxy branches.
void	setParallel(boolean parallel) Specifies whether to proxy in parallel or sequentially.
void	setProxyTimeout(int seconds) Sets the overall proxy timeout.
void	setRecordRoute(boolean rr) Specifies whether branches initiated in this proxy operation 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.
void	setSequentialSearchTimeout(int seconds) Deprecated. use a more general purpose setProxyTimeout(int)
void	setStateful(boolean stateful) Deprecated. stateless proxy is no longer supported
void	setSupervised(boolean supervised) Specifies whether the controlling servlet is to be invoked for incoming responses relating to this proxying.
void	startProxy() Proxies a SIP request to the set of destinations previously specified in createProxyBranches(java.util.List).

Method Detail

getOriginalRequest

SipServletRequest getOriginalRequest()

Returns the request received from the upstream caller.

Returns:

object representing the incoming request that was proxied

proxyTo

void proxyTo(URI uri)

Proxies a SIP request to the specified destination.

Implementations are required to support SipURI arguments and may support other types of URIs.

Parameters:

uri - specifies the destination to proxy to

Throws:

java.lang.IllegalStateException - if the transaction has already completed

java.lang.IllegalArgumentException - e.g. if the scheme of the specified URI is not supported for proxying

java.lang.NullPointerException - if the uri is null

proxyTo

void proxyTo(java.util.List<? extends URI> uris)

Proxies a SIP request to the specified set of destinations.

Parameters:

uris - a list of URI objects to proxy to

Throws:

java.lang.IllegalStateException - if the transaction has already completed

java.lang.IllegalArgumentException - if any of the destination URIs contains a scheme that is not supported for proxying

java.lang.NullPointerException - if any of the URI in the List is null.

cancel

void cancel()

Cancels this proxy transaction and any of its child branches if recursion was enabled.

Throws:

java.lang.IllegalStateException - if the transaction has completed

cancel

void cancel(java.lang.String[] protocol,
            int[] reasonCode,
            java.lang.String[] reasonText)

This overloaded method of cancel() provides a way to specify the reason for cancelling this Proxy 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

getRecurse

boolean getRecurse()

Returns true if this proxy object is set to recurse, or false otherwise.

Returns:

true if proxying 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 branches initiated in this proxy operation should include a Record-Route header for this servlet engine or not. This shall affect all the branches created after its invocation.

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:

java.lang.IllegalStateException - if the proxy has already been started

getParallel

boolean getParallel()

Returns true if this proxy object is set to proxy in parallel, or false if it is set to proxy sequentially.

Returns:

value of the "parallel" flag

setParallel

void setParallel(boolean parallel)

Specifies whether to proxy in parallel or sequentially.

Parameters:

parallel - if true the servlet engine will proxy to all destinations in parallel, otherwise it will proxy to one at a time

getStateful

boolean getStateful()

Deprecated. stateless proxy is no longer supported

Returns true if this proxy operation is transaction stateful (the default), or false if it is stateless.

Returns:

always returns true

setStateful

void setStateful(boolean stateful)

Deprecated. stateless proxy is no longer supported

Specifies whether the server should proxy statelessly or not, that is whether it should maintain transaction state whilst the proxying operation is in progress.

This proxy parameter is a hint only. Implementations may choose to maintain transaction state regardless of the value of this flag, but if so the application will not be invoked again for this transaction.

Parameters:

stateful - if true the proxy operation will be stateful

getSupervised

boolean getSupervised()

Returns true if the controlling servlet will be invoked on incoming responses for this proxying operation, and false otherwise.

Returns:

true if the application will be invoked for responses, and false if not

setSupervised

void setSupervised(boolean supervised)

Specifies whether the controlling servlet is to be invoked for incoming responses relating to this proxying.

Parameters:

supervised - if true, the servlet invoked to handle the request originally received will be notified when the "best" response is received.

getProxyTimeout

int getProxyTimeout()

The current value of the overall proxy timeout value. This is measured in seconds.

Returns:

current value of proxy timeout in seconds.

Since:

1.1

getSequentialSearchTimeout

int getSequentialSearchTimeout()

Deprecated. use a more general purpose getProxyTimeout()

Returns the current value of the sequential search timeout parameter. This is measured in seconds.

Returns:

current value of the sequential search timeout parameter

setProxyTimeout

void setProxyTimeout(int seconds)

Sets the overall proxy timeout. If this proxy is a sequential proxy then the behavior is same as the erstwhile setSequentialSearchTimeout(int). Further the value set through this method shall override any explicit sequential value set through deprecated setSequentialSearchTimeout(int). On the other hand if the proxy is parallel then this acts as the upper limit for the entire proxy operation resulting in equivalent of invoking cancel() if the the proxy did not complete during this time, which means that a final response was not sent upstream.

Parameters:

seconds - seconds waited for each branch in case proxy is sequential and overall wait for parallel proxy.

Throws:

java.lang.IllegalArgumentException - if the container cannot set the value as requested because it is too high, too low or negative

Since:

1.1

setSequentialSearchTimeout

void setSequentialSearchTimeout(int seconds)

Deprecated. use a more general purpose setProxyTimeout(int)

Sets the sequential search timeout value for this Proxy object. This is the amount of time the container waits for a final response when proxying sequentially. When the timer expires the container CANCELs the current branch and proxies to the next element in the target set.

The container is free to ignore this parameter.

Parameters:

seconds - seconds waited for a final responses when proxying sequentially

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.

Applications must not set SIP URI parameters defined in RFC3261. This includes transport, user, method, ttl, maddr, and lr. Other components of the URI, e.g. host, port, and URI scheme must also not by modified by the application. These Record-Route URI components will be populated by the container and may or may not have valid values at the time an application proxies a request. Any attempt to set these parameters or URI contents will thrown an IllegalArgumentException. Record Route parameters thus added affect the branches created right after. If there are branches that were created prior to this modification then they MUST continue to have the Record-Route header as was when they were created. This means that the ProxyBranch gets a cloned copy of the header.

Returns:

SIP URI whose parameters can be modified and then retrieved by this application when processing subsequent requests in the same SIP dialog

Throws:

java.lang.IllegalStateException - if record-routing is not enabled

createProxyBranches

java.util.List<ProxyBranch> createProxyBranches(java.util.List<? extends URI> targets)

Returns the list of ProxyBranch objects given a set of targets. The resulting branches will not have associated client transactions until startProxy() is invoked.

Implementations are required to support SipURI arguments and may support other types of URIs.

Parameters:

targets - a list of URI objects to proxy to

Throws:

java.lang.IllegalArgumentException - if any of the destination URIs contains a scheme that is not supported for proxying

Since:

1.1

getProxyBranch

ProxyBranch getProxyBranch(URI uri)

Any branch has a primary URI associated with it, using which it was created. The ProxyBranch may have been created using createProxyBranches(List) method, implicitly when proxyTo() is called or when any of the proxy branch recurses as a result of a redirect response. A URI uniquely identifies a branch.

Parameters:

uri - URI using which the ProxyBranch may have been created

Returns:

ProxyBranch associated with the uri

Since:

1.1

getProxyBranches

java.util.List<ProxyBranch> getProxyBranches()

More than one branches are associated with a proxy when proxyTo(List) or createProxyBranches(List) is used. This method returns the top level branches thus created. If recursion is enabled on proxy or on any of its branches then on receipt of a 3xx class response on that branch, the branch may recurse into sub-branches. This method returns just the top level branches started.

Returns:

all the the top level branches associated with this proxy

Since:

1.1

startProxy

void startProxy()

Proxies a SIP request to the set of destinations previously specified in createProxyBranches(java.util.List). This method will actually start the proxy branches and their associated client transactions. For example,

   List branches = proxy.createProxyBranches(targets);
   proxy.startProxy();
 

is essentially equivalent to Proxy.proxyTo(targets), with the former giving the application finer control over the individual proxy branches through the ProxyBranch class. Since the createProxyBranches(List) can be invoked multiple times before the startProxy method the effect of startProxy is to start all the branches added in the target set.

Throws:

java.lang.IllegalStateException - if the branches have not yet been created or the proxy is already completed (final response sent upstream).

Since:

1.1

setOutboundInterface

void setOutboundInterface(java.net.InetSocketAddress address)

In multi-homed environment this method can be used to select the outbound interface and port number to use for proxy branches. 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 attribute named 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 Proxy, 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

Throws:

java.lang.IllegalArgumentException - if the address is not understood by the container as one of its outbound interface

java.lang.NullPointerException - on null address

Since:

1.1

setOutboundInterface

void setOutboundInterface(java.net.InetAddress address)

In multi-homed environment this method can be used to select the outbound interface to use when sending requests for proxy branches. 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 attribute named javax.servlet.sip.outboundInterfaces.

Invocation of this method also impacts the system headers generated by the container for the branches, such as the Record-Route header (getRecordRouteURI()) and the Via. The specified IP address is used to construct these system headers.

Parameters:

address - the address which represents the outbound interface

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

java.lang.IllegalArgumentException - if the address does not represent one of the container's outbound interfaces

java.lang.NullPointerException - on null address

Since:

1.1

getAddToPath

boolean getAddToPath()

Returns true if subsequent invocations of proxyTo(URI) or 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 branches initiated in this proxy operation should include a Path header for the REGISTER request for this servlet container or not. The Path header field for the container should be on top of any application pushed Path header fields (pushed using the SipServletRequest.pushPath() API).

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

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:

java.lang.IllegalStateException - if addToPath is not enabled

Since:

1.1

setNoCancel

void setNoCancel(boolean noCancel)

Specifies whether the proxy should, or should not cancel outstanding branches upon receiving the first 2xx INVITE response as defined in RFC 3841.

The default proxy behavior, as per RFC 3261 section 16.7 point 10, is to cancel outstanding branches upon receiving the first 2xx response; this method allows configuring the proxy to keep the branches and forward all 2xx responses upstream.

Default is false.

Parameters:

noCancel - when true, the proxy will not cancel outstanding branches upon receiving the first 2xx response

Since:

1.1

getNoCancel

boolean getNoCancel()

Returns true if the proxy will not cancel outstanding branches upon receiving the first 2xx INVITE response as in RFC 3841

Returns:

true if the proxy will not cancel outstanding branches upon receiving the first 2xx response, false otherwise

Since:

1.1