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:

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 for events (best response received, CANCEL, or ACK received).

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 effect of the various parameters is explained further below.

Method Summary

void	cancel() Cancels this proxy transaction.
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.
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() Returns the current value of the sequential search timeout parameter.
boolean	getStateful() Returns true if this proxy operation is transaction stateful (the default), or false if it is stateless.
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 uris) Proxies a SIP request to the specified set of destinations.
void	proxyTo(URI uri) Proxies a SIP request to the specified destination.
void	setParallel(boolean parallel) Specifies whether to proxy in parallel or sequentially.
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) Sets the sequential search timeout value for this Proxy object.
void	setStateful(boolean stateful) Specifies whether the server should proxy statelessly or not, that is whether it should maintain transaction state whilst the proxying operation is in progress.
void	setSupervised(boolean supervised) Specifies whether the controlling servlet is to be invoked for subsequent events relating to this proxying transaction, i.e.

Method Detail

getOriginalRequest

public SipServletRequest getOriginalRequest()

Returns the request received from the upstream caller.

Returns:

object representing the incoming request that was proxied

proxyTo

public 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

proxyTo

public void proxyTo(java.util.List 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

cancel

public void cancel()

Cancels this proxy transaction.

Throws:

java.lang.IllegalStateException - if the transaction has completed

getRecurse

public boolean getRecurse()

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

Returns:

true if proxying is enabled, false otherwise

setRecurse

public 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

public 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

public void setRecordRoute(boolean rr)

Specifies whether branches initiated in this proxy operation 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

getParallel

public 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

public 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

public boolean getStateful()

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

Returns:

value of the "stateful" flag

setStateful

public void setStateful(boolean stateful)

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

public 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

public void setSupervised(boolean supervised)

Specifies whether the controlling servlet is to be invoked for subsequent events relating to this proxying transaction, i.e. for incoming responses, CANCELs, and ACKs.

Parameters:

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

getSequentialSearchTimeout

public int getSequentialSearchTimeout()

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

Returns:

current value of the sequential search timeout parameter

setSequentialSearchTimeout

public void setSequentialSearchTimeout(int seconds)

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

public 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:

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