javax.servlet.sip
Interface SipServletRequest

All Superinterfaces:

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.

Method Summary

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.
javax.servlet.ServletInputStream	getInputStream() Always returns null.
int	getMaxForwards() Returns the value of the Max-Forwards header.
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.
URI	getRequestURI() Returns the request URI of this request.
boolean	isInitial() Returns true if this is an initial request.
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.

Methods inherited from interface javax.servlet.ServletRequest

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

Methods inherited from interface javax.servlet.sip.SipServletMessage

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

Method Detail

getRequestURI

public URI getRequestURI()

Returns the request URI of this request.

Returns:

request URI of this SipServletRequest

setRequestURI

public 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

pushRoute

public 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 container a Route header, one is added with the value 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"

getMaxForwards

public 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

public 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

public 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

public 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

public 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

getReader

public 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

getProxy

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

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

See Also:

getProxy(boolean)

getProxy

public 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

public 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

public 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

public SipServletRequest createCancel()
                               throws java.lang.IllegalStateException

Returns a CANCEL request object. This method is used by servlets to cancel outstanding transactions when acting as a UAC. Proxy applications should use Proxy.cancel() instead.

Returns:

CANCEL request object corresponding to this request

Throws:

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