javax.servlet.sip
Interface ProxyBranch

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

Method Summary

void	cancel() Cancels this branch and all the child branches if recursion is enabled and sends a CANCEL to the proxied INVITEs.
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 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.
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.
java.util.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	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 this proxy branch.
void	setOutboundInterface(java.net.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:

java.lang.IllegalStateException - if the transaction has already been completed and it has no child branches

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

java.lang.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:

java.lang.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:

java.lang.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:

java.lang.IllegalStateException - if addToPath is not enabled

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

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 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 attribute named 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:

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

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

java.util.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