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.
 Proxy getProxy(boolean create)
          Returns the Proxy object associated with this request.
 URI getRequestURI()
          Returns the request URI of this request.
 boolean isInitial()
          Returns true if this is an initial request.
 void pushRoute(SipAddress proxyAddr)
          Adds a Route header field value to this request.
 void pushRoute(SipURI proxyAddr)
          Adds a Route header field value to this request.
 void send()
          Causes this request to be sent to the destination identified by the request URI.
 void setRequestURI(URI uri)
          Sets the request URI of this request.
 
Methods inherited from interface javax.servlet.ServletRequest
getAttribute, getAttributeNames, getCharacterEncoding, getContentLength, getContentType, getInputStream, getLocale, getLocales, getParameter, getParameterMap, getParameterNames, getParameterValues, getProtocol, getReader, getRealPath, getRemoteAddr, getRemoteHost, getRequestDispatcher, getScheme, getServerName, getServerPort, isSecure, removeAttribute, setAttribute, setCharacterEncoding
 
Methods inherited from interface javax.servlet.sip.SipServletMessage
addAcceptLanguage, addHeader, getAcceptLanguage, getAcceptLanguages, getApplicationSession, getApplicationSession, getAttribute, getAttributeNames, getCharacterEncoding, getContacts, getContent, getContentLanguage, getContentLength, getContentType, getExpires, getFrom, getHeader, getHeaderNames, getHeaders, getInputStream, getMaxForwards, getMethod, getOutputStream, getProtocol, getProxy, getRawContent, getRemoteUser, getSession, getSession, getTo, getUserPrincipal, isCommitted, isRequestedSessionIdValid, isSecure, isUserInRole, removeHeader, setAcceptLanguage, setAttribute, setContacts, setContent, setContentLanguage, setContentLength, setContentType, setExpires, setHeader, setMaxForwards
 

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(SipAddress proxyAddr)
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:
proxyAddr - the address that is added as a Route header value
Throws:
java.lang.IllegalArgumentException - if the URI of the SipAddress argument does not contain a SipURI
See Also:
"bis-09, section 16.6"

pushRoute

public void pushRoute(SipURI proxyAddr)
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:
proxyAddr - the address that is added as a Route header value
See Also:
"bis-09, section 16.6"

send

public void send()
Causes this request to be sent to the destination identified by the request URI. This method is used by SIP servlets acting as user agent clients (UACs) only. Proxying applications use Proxy.proxy(javax.servlet.sip.URI) instead.
Specified by:
send in interface SipServletMessage
Following copied from interface: javax.servlet.sip.SipServletMessage
Throws:
java.lang.IllegalStateException - if this message cannot legally be sent in the current state of the underlying SIP transaction

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

getProxy

public Proxy getProxy(boolean create)
Returns the Proxy object associated with this request. If no Proxy object has yet been created for this request, meaning that the applciation hasn't yet committed itself to proxying, the create argument specifies whether a Proxy object is created or if null is to be returned.

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 SipServletMessage.getProxy() method and SipServletMessage.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:
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