javax.servlet.sip
Interface SipServletRequest

All Superinterfaces:

java.lang.Cloneable, javax.servlet.ServletRequest, SipServletMessage

public interface SipServletRequest
extends javax.servlet.ServletRequest, SipServletMessage

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, java.lang.String username, java.lang.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, java.lang.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.
java.io.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.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

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

Method Detail

getRequestURI

URI getRequestURI()

Returns the request URI of this request.

Returns:

request URI of this SipServletRequest

setRequestURI

void setRequestURI(URI uri)

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

Parameters:

uri - new request URI of this SipServletRequest

Throws:

java.lang.NullPointerException - on null uri

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.

Parameters:

uri - the address that is added as a Route header value

See Also:

"RFC 3261, section 16.6", pushRoute(Address)

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.

Parameters:

uri - the address that is added as a Route header value

Since:

1.1

See Also:

"RFC 3261, section 16.6", pushRoute(SipURI)

getMaxForwards

int getMaxForwards()

Returns the value of the Max-Forwards header.

Returns:

the value of the Max-Forwards header, or -1 if there is no such header in this message

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));
 

Parameters:

n - new value of the Max-Forwards header

Throws:

java.lang.IllegalArgumentException - if the argument is not in the range 0 to 255

send

void send()
          throws java.io.IOException

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

Specified by:

send in interface SipServletMessage

Throws:

java.io.IOException - if a transport error occurs when trying to send 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.

Returns:

true if this is an initial request

getInputStream

javax.servlet.ServletInputStream getInputStream()
                                                throws java.io.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

Returns:

null

Throws:

java.io.IOException

getReader

java.io.BufferedReader getReader()
                                 throws java.io.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

Returns:

null

Throws:

java.io.IOException

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.

Returns:

Proxy object associated with this request

Throws:

TooManyHopsException - if the request has a Max-Forwards header field value of 0.

java.lang.IllegalStateException - if the transaction underlying this message isn't already associated with a Proxy object and its state disallows proxying to be initiated, for example, because a final response has already been generated. Also if the application previously accessed the B2buaHelper by invoking getB2buaHelper().

See Also:

getProxy(boolean)

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.

Parameters:

create - indicates whether the servlet engine should create a new Proxy object if one does not already exist

Returns:

Proxy object associated with this request

Throws:

TooManyHopsException - if this request has a Max-Forwards header field value of 0.

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

createResponse

SipServletResponse createResponse(int statuscode)

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

Parameters:

statuscode - status code for the response

Returns:

response object with specified status code

Throws:

java.lang.IllegalArgumentException - if the statuscode is not a valid SIP status code

java.lang.IllegalStateException - if this request has already been responded to with a final status code

createResponse

SipServletResponse createResponse(int statusCode,
                                  java.lang.String reasonPhrase)

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

Parameters:

statusCode - status code for the response

reasonPhrase - reason phrase to appear in response line

Returns:

response object with specified status code and reason phrase

Throws:

java.lang.IllegalArgumentException - if the statuscode is not a valid SIP status code

java.lang.IllegalStateException - if this request has already been responded to with a final status code

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 send() on it.

Note that proxy applications MUST use Proxy.cancel() to cancel outstanding branches.

Returns:

CANCEL request object corresponding to this request

Throws:

java.lang.IllegalStateException - if the transaction state is such that it doesn't allow a CANCEL request to be sent

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 contain 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.

Parameters:

uri - The address that is added as a Route header value

Throws:

java.lang.IllegalStateException - if invoked on non-REGISTER Request.

Since:

1.1

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 getProxy() will result in IllegalStateException.

Returns:

the B2buaHelper for this request

Throws:

java.lang.IllegalStateException - if getProxy() had already been called

Since:

1.1

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.

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().

Returns:

the popped top route header, or null if none

Since:

1.1

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

setRoutingDirective

void setRoutingDirective(SipApplicationRoutingDirective directive,
                         SipServletRequest origRequest)
                         throws java.lang.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.

Parameters:

directive - Routing directive

origRequest - An initial request that the application received

Throws:

java.lang.IllegalStateException - when given directive cannot be set

Since:

1.1

getRoutingDirective

SipApplicationRoutingDirective getRoutingDirective()
                                                   throws java.lang.IllegalStateException

Returns the SipApplicationRoutingDirective associated with this request.

Returns:

SipApplicationRoutingDirective associated with this request.

Throws:

java.lang.IllegalStateException - if called on a request that is not initial

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:

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

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

Since:

1.1

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,
                   java.lang.String username,
                   java.lang.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 -