javax.servlet.sip

Interface SipServletRequest

All Superinterfaces:

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

Methods

Modifier and Type	Method and Description
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.
InviteBranch	createInviteBranch() This method will create a derived session and corresponding invite branch for a received initial INVITE.
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.
SipServletResponse	getAcknowledgedResponse() This method should only be called on an ACK or PRACK message at a UAS or UAC (not a proxy).
B2buaHelper	getB2buaHelper() Returns the B2buaHelper associated with this request.
SipServletResponse	getFinalResponse() This method will retrieve the final response that corresponds to the request or null if there is no such response.
String	getId() This method will return the id of the 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	getMaxBreadth() Returns the value of the Max-Breadth header.
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.
boolean	isRequestUriInternal() If the request-uri of the request is a SIP or SIPS URI and if it is addressed to the container, this method considers it as internal.
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	setMaxBreadth(int n) Sets the value of the Max-Breadth header.
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

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

Methods inherited from interface javax.servlet.sip.SipServletMessage

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

Methods inherited from interface javax.servlet.sip.AttributeStore

clearAttributes, getAttribute, getAttributeNameSet, removeAttribute, setAttribute

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:

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:

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

getMaxBreadth

int getMaxBreadth()

Returns the value of the Max-Breadth header.

Returns:

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

Since:

2.0

setMaxBreadth

void setMaxBreadth(int n)

Sets the value of the Max-Breadth header. Max-Breadth to limit the number of parallel forks that can be made on a SIP request by the downstream proxies. It consists of an integer that is distributed among the active parallel branches so that outgoing Max-Breadth is the sum of the Max-Breadth header field values in all forwarded requests in the response context that have not received a final response

This method is equivalent to:

   setHeader("Max-Breadth", String.valueOf(n));
 

Parameters:

n - new value of the Max-Breadth header

Throws:

IllegalArgumentException - if the argument is not a positive integer.

Since:

2.0

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 Proxy.proxyTo(javax.servlet.sip.URI) instead.

Specified by:

send in interface SipServletMessage

Throws:

InsufficientBreadthException - If the value of Max-Breadth header causes the sum of Max-Breadth of active parallel branches to exceed the Max-Breadth of the original incoming request, when the servlet act as a B2BUA.

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

IOException

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

Returns:

null

Throws:

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.

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.

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:

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

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

createResponse

SipServletResponse createResponse(int statusCode,
                                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:

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

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:

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

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:

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

IllegalStateException - when given directive cannot be set

Since:

1.1

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

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.

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

getId

String getId()

This method will return the id of the request. In the case of a CANCEL message it will return the id of the request being cancelled. The id will uniquely identify the request within the session. This id can be used to retrieve an active request using SipSession.getActiveRequest

Returns:

id uniquely representing the request within a session.

Since:

2.0

getFinalResponse

SipServletResponse getFinalResponse()

This method will retrieve the final response that corresponds to the request or null if there is no such response. For an initial invite there can be multiple final responses due to forking this method will return the last final response received or sent. To retrieve a final response to an initial invite for a specific dialogue the equivalent method on InviteBranch should be used instead.

Returns:

SipServletResponse object representing final response.

Since:

2.0

getAcknowledgedResponse

SipServletResponse getAcknowledgedResponse()

This method should only be called on an ACK or PRACK message at a UAS or UAC (not a proxy). When called for an ACK it will return the final response of the corresponding invite transaction. If there is no pending invite transaction it will return null. When called for a PRACK it will return the pending reliable provisional response which is being acknowledged. If there is no pending provisional response with a matching rseq header and transaction it will return null.

Returns:

SipServletResponse being acknowledged.

Throws:

IllegalStateException - if it is called on a request which is not an ACK or PRACK or if the servlet is acting as a proxy for the INVITE transaction.

Since:

2.0

createInviteBranch

InviteBranch createInviteBranch()

This method will create a derived session and corresponding invite branch for a received initial INVITE. The method will throw IllegalStateException if it is called on a request which is not an initial INVITE or if the container is not acting as the UAS for the INVITE transaction.

Returns:

newly created InviteBranch

Throws:

IllegalStateException - if it is called on a request which is not an initial INVITE or if the container is not acting as the UAS for the INVITE transaction

Since:

2.0

isRequestUriInternal

boolean isRequestUriInternal()

If the request-uri of the request is a SIP or SIPS URI and if it is addressed to the container, this method considers it as internal.

Returns:

True if the request uri is internal. False otherwise.

Since:

2.0