|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Proxy
Represents the operation of proxying a SIP request.
A number of parameters control how proxying is carried out:
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 extends javax.servlet.sip.URI>
) . |
Method Detail |
---|
SipServletRequest getOriginalRequest()
void proxyTo(URI uri)
Implementations are required to support SipURI
arguments and may support other types of URIs.
uri
- specifies the destination to proxy tojava.lang.IllegalStateException
- if the transaction has already completedjava.lang.IllegalArgumentException
- e.g. if the scheme of the specified URI is not supported for proxyingjava.lang.NullPointerException
- if the uri is nullvoid proxyTo(java.util.List<? extends URI> uris)
uris
- a list of URI
objects to proxy tojava.lang.IllegalStateException
- if the transaction has already completedjava.lang.IllegalArgumentException
- if any of the destination URIs contains a scheme that is not supported for proxyingjava.lang.NullPointerException
- if any of the URI in the List is null.void cancel()
java.lang.IllegalStateException
- if the transaction has completedvoid cancel(java.lang.String[] protocol, int[] reasonCode, java.lang.String[] reasonText)
cancel()
provides a way to specify the reason for cancelling this Proxy
by including the appropriate Reason headers [RFC 3326].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 cancelreasonText
- describes the reason for cancelling the Proxy
.boolean getRecurse()
void setRecurse(boolean recurse)
recurse
- if true enables recursion, otherwise disables itboolean getRecordRoute()
proxyTo(URI)
will add a Record-Route header to the proxied request, false otherwise.void setRecordRoute(boolean rr)
Record-routing is used to specify that this servlet engine must stay on the signaling path of subsequent requests.
rr
- if true the engine will record-route, otherwise it won'tjava.lang.IllegalStateException
- if the proxy has already been startedboolean getParallel()
void setParallel(boolean parallel)
parallel
- if true the servlet engine will proxy to all destinations in parallel, otherwise it will proxy to one at a timeboolean getStateful()
true
void setStateful(boolean stateful)
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.
stateful
- if true the proxy operation will be statefulboolean getSupervised()
void setSupervised(boolean supervised)
supervised
- if true, the servlet invoked to handle the request originally received will be notified when the "best" response is received.int getProxyTimeout()
int getSequentialSearchTimeout()
getProxyTimeout()
void setProxyTimeout(int seconds)
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.seconds
- seconds waited for each branch in case proxy is sequential and overall wait for parallel proxy.java.lang.IllegalArgumentException
- if the container cannot set the value as requested because it is too high, too low or negativevoid setSequentialSearchTimeout(int seconds)
setProxyTimeout(int)
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.
seconds
- seconds waited for a final responses when proxying sequentiallySipURI getRecordRouteURI()
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 SipServletRequest#getParameter
.
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.
java.lang.IllegalStateException
- if record-routing is not enabledjava.util.List<ProxyBranch> createProxyBranches(java.util.List<? extends URI> targets)
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.
targets
- a list of URI
objects to proxy tojava.lang.IllegalArgumentException
- if any of the destination URIs contains a scheme that is not supported for proxyingProxyBranch getProxyBranch(URI uri)
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.uri
- URI using which the ProxyBranch may have been createdjava.util.List<ProxyBranch> getProxyBranches()
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.void startProxy()
createProxyBranches(java.util.List extends javax.servlet.sip.URI>
)
. This method will actually start the proxy branches and their associated client transactions. For example,
List<ProxyBranch> 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.java.lang.IllegalStateException
- if the branches have not yet been created or the proxy is already completed (final response sent upstream).void setOutboundInterface(java.net.InetSocketAddress address)
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.
address
- the socket address representing the outbound interface to use when forwarding requests with this proxyjava.lang.IllegalArgumentException
- if the address
is not understood by the container as one of its outbound interfacejava.lang.NullPointerException
- on null address
void setOutboundInterface(java.net.InetAddress address)
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.
address
- the address which represents the outbound interfacejava.lang.IllegalStateException
- if this method is called on an invalidated sessionjava.lang.IllegalArgumentException
- if the address
does not represent one of the container's outbound interfacesjava.lang.NullPointerException
- on null address
boolean getAddToPath()
proxyTo(URI)
or startProxy()
will add a Path header to the proxied request, false otherwise.void setAddToPath(boolean p)
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.
p
- if true the container will add Path headerSipURI getPathURI()
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 SipServletRequest#getParameter
.
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.
java.lang.IllegalStateException
- if addToPath is not enabledvoid setNoCancel(boolean noCancel)
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
.
noCancel
- when true, the proxy will not cancel outstanding branches upon receiving the first 2xx responseboolean getNoCancel()
true
if the proxy will not cancel outstanding branches upon receiving the first 2xx INVITE response as in RFC 3841true
if the proxy will not cancel outstanding branches upon receiving the first 2xx response, false
otherwise
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1996, 2010, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
Java SIP Servlet API 1.1 Reference
Part Number E17883-01