javax.servlet.sip
Interface SipServletRequest

All Superinterfaces:

Cloneable, javax.servlet.ServletRequest, SipServletMessage

public interface SipServletRequest
extends SipServletMessage, javax.servlet.ServletRequest

Represents SIP request messages. When receiving an incoming SIP request the container creates a SipServletRequest and passes it to the handling servlet. For outgoing, locally initiated requests, applications call SipFactory.createRequest to obtain a SipServletRequest that can then be modified and sent.

Nested Class Summary

Nested classes/interfaces inherited from interface javax.servlet.sip.SipServletMessage

SipServletMessage.HeaderForm

Method Summary

void	addAuthHeader(SipServletResponse challengeResponse, AuthInfo authInfo) This method allows the addition of the appropriate authentication header(s) to the request that was challenged with a challenge response.
void	addAuthHeader(SipServletResponse challengeResponse, String username, String password) This method allows the addition of the appropriate authentication header(s) to the request that was challenged with a challenge response without needing the creation and/or maintenance of the AuthInfo object.
SipServletRequest	createCancel() Returns a CANCEL request object.
SipServletResponse	createResponse(int statuscode) Creates a response for this request with the specifies status code.
SipServletResponse	createResponse(int statusCode, String reasonPhrase) Creates a response for this request with the specifies status code and reason phrase.
B2buaHelper	getB2buaHelper() Returns the B2buaHelper associated with this request.
Address	getInitialPoppedRoute() If a top route header had been removed by the container upon initially receiving this request, then this method can be used to retrieve it.
javax.servlet.ServletInputStream	getInputStream() Always returns null.
int	getMaxForwards() Returns the value of the Max-Forwards header.
Address	getPoppedRoute() If a top route header had been removed by the container upon receiving this request, then this method can be used to retrieve it.
Proxy	getProxy() Returns the Proxy object associated with this request.
Proxy	getProxy(boolean create) Returns the Proxy object associated with this request.
BufferedReader	getReader() Always returns null.
SipApplicationRoutingRegion	getRegion() This method allows the application to obtain the region it was invoked in for this SipServletRequest.
URI	getRequestURI() Returns the request URI of this request.
SipApplicationRoutingDirective	getRoutingDirective() Returns the SipApplicationRoutingDirective associated with this request.
URI	getSubscriberURI() Returns the URI of the subscriber for which this application is invoked to serve.
boolean	isInitial() Returns true if this is an initial request.
void	pushPath(Address uri) Adds a Path header field value to this request.
void	pushRoute(Address uri) Adds a Route header field value to this request with Address argument.
void	pushRoute(SipURI uri) Adds a Route header field value to this request.
void	send() Causes this request to be sent.
void	setMaxForwards(int n) Sets the value of the Max-Forwards header.
void	setRequestURI(URI uri) Sets the request URI of this request.
void	setRoutingDirective(SipApplicationRoutingDirective directive, SipServletRequest origRequest) Sets the application routing directive for an outgoing request.

Methods inherited from interface javax.servlet.sip.SipServletMessage

addAcceptLanguage, addAddressHeader, addHeader, addParameterableHeader, getAcceptLanguage, getAcceptLanguages, getAddressHeader, getAddressHeaders, getApplicationSession, getApplicationSession, getAttribute, getAttributeNames, getCallId, getCharacterEncoding, getContent, getContentLanguage, getContentLength, getContentType, getExpires, getFrom, getHeader, getHeaderForm, getHeaderNames, getHeaders, getInitialRemoteAddr, getInitialRemotePort, getInitialTransport, getLocalAddr, getLocalPort, getMethod, getParameterableHeader, getParameterableHeaders, getProtocol, getRawContent, getRemoteAddr, getRemotePort, getRemoteUser, getSession, getSession, getTo, getTransport, getUserPrincipal, isCommitted, isSecure, isUserInRole, removeAttribute, removeHeader, setAcceptLanguage, setAddressHeader, setAttribute, setCharacterEncoding, setContent, setContentLanguage, setContentLength, setContentType, setExpires, setHeader, setHeaderForm, setParameterableHeader

Methods inherited from interface javax.servlet.ServletRequest

getAttribute, getAttributeNames, getCharacterEncoding, getContentLength, getContentType, getLocalAddr, getLocale, getLocales, getLocalName, getLocalPort, getParameter, getParameterMap, getParameterNames, getParameterValues, getProtocol, getRealPath, getRemoteAddr, getRemoteHost, getRemotePort, getRequestDispatcher, getScheme, getServerName, getServerPort, isSecure, removeAttribute, setAttribute, setCharacterEncoding

Method Detail

addAuthHeader

void addAuthHeader(SipServletResponse challengeResponse,
                   AuthInfo authInfo)

This method allows the addition of the appropriate authentication header(s) to the request that was challenged with a challenge response.

Parameters:

challengeResponse - The challenge response (401/407) receieved from a UAS/Proxy.

authInfo - The AuthInfo object that will add the Authentication headers to the request.

addAuthHeader

void addAuthHeader(SipServletResponse challengeResponse,
                   String username,
                   String password)

This method allows the addition of the appropriate authentication header(s) to the request that was challenged with a challenge response without needing the creation and/or maintenance of the AuthInfo object.

Parameters:

challengeResponse - the challenge response (401/407) receieved from a UAS/Proxy.

username -

password -

createCancel

SipServletRequest createCancel()

Returns a CANCEL request object. This method is used by applications to cancel outstanding transactions for which they act as a user agent client (UAC). The CANCEL request is sent when the application invokes on it. Note that proxy applications MUST use Proxy.cancel() to cancel outstanding branches.

createResponse

SipServletResponse createResponse(int statuscode)

Creates a response for this request with the specifies status code.

createResponse

SipServletResponse createResponse(int statusCode,
                                  String reasonPhrase)

Creates a response for this request with the specifies status code and reason phrase.

getB2buaHelper

B2buaHelper getB2buaHelper()

Returns the B2buaHelper associated with this request. Invocation of this method also indicates to the container that the application wishes to be a B2BUA, and any subsequent call to will result in IllegalStateException.

getInitialPoppedRoute

Address getInitialPoppedRoute()

If a top route header had been removed by the container upon initially receiving this request, then this method can be used to retrieve it. Otherwise, if no route header had been popped then this method will return null. Unlike getPoppedRoute(), this method returns the same value regardless of which application invokes it in the same application composition chain. Note that the URI parameters added to the Record-Route header using Proxy.getRecordRouteURI() should be retrieved from the URI of the popped route Address using initialPoppedRoute.getURI().getParameter() and not using initialPoppedRoute.getParameter().

Returns:

the popped top route header, or null if none

Since:

1.1

getInputStream

javax.servlet.ServletInputStream getInputStream()
                                                throws IOException

Always returns null. SIP is not a content transfer protocol and having stream based content accessors is of little utility. Message content can be retrieved using SipServletMessage.getContent() and SipServletMessage.getRawContent().

Specified by:

getInputStream in interface javax.servlet.ServletRequest

Throws:

IOException

getMaxForwards

int getMaxForwards()

Returns the value of the Max-Forwards header.

getPoppedRoute

Address getPoppedRoute()

If a top route header had been removed by the container upon receiving this request, then this method can be used to retrieve it. Otherwise, if no route header had been popped then this method will return null.

getProxy

Proxy getProxy()
               throws TooManyHopsException

Returns the Proxy object associated with this request. A Proxy instance will be created if one doesn't already exist. This method behaves the same as getProxy(true). Note that the container must return the same Proxy instance whenever a servlet invokes getProxy on messages belonging to the same transaction. In particular, a response to a proxied request is associated with the same Proxy object as is the original request. This method throws an IllegalStateException if the Proxy object didn't already exist and the transaction underlying this SIP message is in a state which doesn't allow proxying, for example if this is a SipServletRequest for which a final response has already been generated. If the request contains a Max-Forwards header field value of 0, then this method will generate a 483 (Too many hops) error response and throw TooManyHopsException.

Note that the URI parameters added to the Record-Route header using Proxy.getRecordRouteURI() should be retrieved from the URI of the popped route Address using poppedRoute.getURI().getParameter() and not using poppedRoute.getParameter().

Throws:

TooManyHopsException

getProxy

Proxy getProxy(boolean create)
               throws TooManyHopsException

Returns the Proxy object associated with this request. If no Proxy object has yet been created for this request, the create argument specifies whether a Proxy object is to be created or not. Once a Proxy object has been associated with a request subsequent invocations of this method will yield the same Proxy object, as will the no-argument getProxy() method and SipServletResponse.getProxy() for responses received to proxied requests.

Throws:

TooManyHopsException

getReader

BufferedReader getReader()
                         throws IOException

Always returns null. SIP is not a content transfer protocol and having stream based content accessors is of little utility. Message content can be retrieved using SipServletMessage.getContent() and SipServletMessage.getRawContent().

Specified by:

getReader in interface javax.servlet.ServletRequest

Throws:

IOException

getRegion

SipApplicationRoutingRegion getRegion()

This method allows the application to obtain the region it was invoked in for this SipServletRequest. This information helps the application to determine the location of the subscriber returned by SipServletRequest.getSubscriberURI(). If this SipServletRequest is an initial request, this method returns the region in which this servlet is invoked. The SipApplicationRoutingRegion is only available for initial requests. For all other requests, this method throws IllegalStateException.

Returns:

The routing region (ORIGINATING, NEUTRAL, TERMINATING or their sub-regions)

Throws:

IllegalStateException - if this method is called on a request that is not initial.

Since:

1.1

getSubscriberURI

URI getSubscriberURI()

Returns the URI of the subscriber for which this application is invoked to serve. This is only available if this SipServletRequest received is an initial request. For all other requests, this method throws IllegalStateException.

Returns:

URI of the subscriber

Throws:

IllegalStateException - if this method is called on a request that is not initial.

getRoutingDirective

SipApplicationRoutingDirective getRoutingDirective()
                                                   throws IllegalStateException

Returns the SipApplicationRoutingDirective associated with this request.

Returns:

SipApplicationRoutingDirective associated with this request.

Throws:

IllegalStateException - if called on a request that is not initial

getRequestURI

URI getRequestURI()

Returns the request URI of this request.

isInitial

boolean isInitial()

Returns true if this is an initial request. An initial request is one that is dispatched to applications based on the containers configured rule set, as opposed to subsequent requests which are routed based on the application path established by a previous initial request.

pushPath

void pushPath(Address uri)

Adds a Path header field value to this request. The new value is added ahead of any existing Path header fields. If this request does not already container a Path header, one is added with the value specified in the argument. This method allows a UAC or a proxy to add Path on a REGISTER Request.

pushRoute

void pushRoute(Address uri)

Adds a Route header field value to this request with Address argument. The new value is added ahead of any existing Route header fields. If this request does not already contains a Route header, one is added with the value as specified in the argument. This method allows a UAC or a proxy to specify that the request should visit one or more proxies before being delivered to the destination.

pushRoute

void pushRoute(SipURI uri)

Adds a Route header field value to this request. The new value is added ahead of any existing Route header fields. If this request does not already contains a Route header, one is added with the value as specified in the argument. This method allows a UAC or a proxy to specify that the request should visit one or more proxies before being delivered to the destination.

send

void send()
          throws IOException

Causes this request to be sent. This method is used by SIP servlets acting as user agent clients (UACs) only. Proxying applications use instead.

Specified by:

send in interface SipServletMessage

Throws:

IOException

setMaxForwards

void setMaxForwards(int n)

Sets the value of the Max-Forwards header. Max-Forwards serves to limit the number of hops a request can make on the way to its destination. It consists of an integer that is decremented by one at each hop. This method is equivalent to: setHeader("Max-Forwards", String.valueOf(n));

setRequestURI

void setRequestURI(URI uri)

Sets the request URI of this request. This then becomes the destination used in a subsequent invocation of .

setRoutingDirective

void setRoutingDirective(SipApplicationRoutingDirective directive,
                         SipServletRequest origRequest)
                         throws IllegalStateException

Sets the application routing directive for an outgoing request. By default, a request created by SipFactory.createRequest(SipServletRequest origRequest, boolean sameCallId) continues the application selection process from origRequest, i.e. directive is CONTINUE. A request created by the other SipFactory.createRequest() methods starts the application selection process afresh, i.e. directive is NEW. This method allows the servlet to assign a routing directive different from the default. If directive is NEW, origRequest parameter is ignored. If directive is CONTINUE or REVERSE, the parameter origRequest must be an initial request dispatched by the container to this application, i.e. origRequest.isInitial() must be true. This request must be a request created in a new SipSession or from an initial request, and must not have been sent. If any one of these preconditions are not met, the method throws an IllegalStateException. Note that when a servlet acts as a proxy and calls Proxy.proxyTo() to proxy a request, the request is always a continuation.

Throws:

IllegalStateException