SipServletRequest

The SipServletRequest interface represents SIP request messages. It extends the ServletRequest and SipServletMessage interfaces, inheriting their functionalities and providing additional methods specific to SIP requests.
This interface allows servlets to handle incoming SIP requests and manage outgoing SIP requests.
SIP request messages are used to initiate, modify, and terminate SIP sessions or transactions. The SipServletRequest interface encapsulates these requests and provides tools to handle incoming SIP requests, which are delivered by the container to the SIP servlet. And also create outgoing SIP requests using the SipFactory, enabling applications to modify and send them.
The SipServletRequest interface inherits methods and behaviors from the following interfaces:

• ServletRequest: Provides methods to interact with request-level properties, such as attributes and character encoding.
• SipServletMessage: Enables handling of common SIP message functionalities, including header and content management, session associations, and more.

By combining these functionalities, the SipServletRequest interface offers the advantages of both generic servlet capabilities and SIP-specific features.
Applications can initiate outgoing requests using the SipFactory in the following way:

1. Call SipFactory.createRequest to obtain a new SipServletRequest.
2. Modify the request by adding headers, setting content, and other customizations.
3. Use the send method to transmit the request.

Nested class:

SipServletMessage.HeaderForm
The class specifies the types of header formats (COMPACT and NORMAL) used in SIP messages. It allows control over how SIP headers are represented and processed. For more details, refer to the HeaderForm Enum Description.

Methods:

Authentication Management

addAuthHeader
void addAuthHeader(SipServletResponse challengeResponse,
                   AuthInfo authInfo)
The method adds the appropriate authentication header(s) to a SIP request that was challenged with a 401 (Unauthorized) or 407 (Proxy Authentication Required) response. The headers are generated based on the challenge and the provided authentication information.
Parameters:
challengeResponse: The challenge response (401 or 407) received from the UAS (User Agent Server) or Proxy.
authInfo: The object containing authentication information used to generate the appropriate authentication headers for the request.

addAuthHeader
void addAuthHeader(SipServletResponse challengeResponse,
                   java.lang.String username,
                   java.lang.String password)
The method adds the appropriate authentication header(s) to a SIP request that was challenged with a 401 (Unauthorized) or 407 (Proxy Authentication Required) response. This version of the method directly uses the provided username and password, eliminating the need to create or maintain an AuthInfo object.
Parameters:
challengeResponse: The challenge response (401 or 407) received from the UAS (User Agent Server) or Proxy.
username: The username used for authentication.
password: The password used for authentication.

Request Creation and Response Handling

createCancel
SipServletRequest createCancel()
The method creates a CANCEL request object, which applications can use to cancel outstanding SIP transactions where they act as a User Agent Client (UAC). The CANCEL request is sent when the application calls the send() method on the created request object. Proxy applications must use Proxy.cancel() to cancel outstanding branches, not this method.
Returns:
A CANCEL request object corresponding to this request.
Exception:
java.lang.IllegalStateException is thrown if the transaction is in a state that does not allow sending a CANCEL request.

createResponse
SipServletResponse createResponse(int statuscode)
The method creates a SipServletResponse object for the current request with the specified SIP status code. This response can then be customized further or sent back to the sender.
Parameters:
statuscode: The SIP status code for the response (e.g., 200 for OK, 404 for Not Found).
Returns:
A response object with the specified status code.
Exceptions:
java.lang.IllegalArgumentException is thrown if the provided statuscode is not a valid SIP status code.
java.lang.IllegalStateException is thrown if the request has already been responded to with a final status code.

createResponse
SipServletResponse createResponse(int statusCode,
                                  java.lang.String reasonPhrase)
The method creates a SipServletResponse object for the current request with the specified SIP status code and a custom reason phrase. The response can then be further customized or sent back to the sender.
Parameters:
statusCode: The SIP status code for the response (e.g., 200, 404).
reasonPhrase: A custom reason phrase to include in the response line.
Returns:
A response object with the specified status code and reason phrase.
Exceptions:
java.lang.IllegalArgumentException is thrown if the provided statusCode is not a valid SIP status code.
java.lang.IllegalStateException is thrown if the request has already been responded to with a final status code.

Proxy and Routing Management

getProxy
Proxy getProxy()
               throws TooManyHopsException
The method retrieves the Proxy object associated with the SIP request. If no Proxy instance exists for the request, a new one is created unless the transaction is in a state that disallows proxying (e.g., a final response has already been generated). The same Proxy instance is returned for messages which belongs to the same transaction, including responses to proxied requests.
If the Max-Forwards header in the request has a value of 0, this method will generate a 483 (Too Many Hops) error response and throw a TooManyHopsException.
Returns:
The Proxy object associated with this request.
Exceptions:
TooManyHopsException is thrown if the Max-Forwards header field value in the request is 0.
java.lang.IllegalStateException is thrown if:

•  A Proxy object does not already exist and the transaction state disallows proxying (e.g., a final response has already been generated).
•  The B2buaHelper has already been accessed using getB2buaHelper().

getProxy
Proxy getProxy(boolean create)
               throws TooManyHopsException
The method retrieves the Proxy object associated with the SIP request. If no Proxy object exists, the create parameter determines whether a new Proxy instance should be created. Once a Proxy object is created, subsequent calls to this method (with or without arguments) and SipServletResponse.getProxy() for responses to the same request will return the same Proxy instance.
Parameters:
create: If true, creates a new Proxy object if none exists. If false, returns null if no Proxy object exists.
Returns:
The Proxy object associated with this request. Returns null if create is false and no Proxy object exists.
Exceptions:
TooManyHopsException is thrown if the Max-Forwards header field value in the request is 0.
java.lang.IllegalStateException is thrown if the transaction has already completed and a new Proxy object cannot be created.

getInitialPoppedRoute
Address getInitialPoppedRoute()
The method retrieves the top Route header that was removed (popped) by the container when it initially received the SIP request. If no route header was removed, this method returns null. Unlike getPoppedRoute(), the returned value remains consistent across all applications in the same application composition chain.
Returns:
The popped top route header, or null if no route header was popped.
Note:
To access URI parameters added to the Record-Route header, use initialPoppedRoute.getURI().getParameter() instead of initialPoppedRoute.getParameter().

getPoppedRoute
Address getPoppedRoute()
The method retrieves the top Route header that was removed (popped) by the container upon receiving the SIP request. If no Route header was popped, the method returns null.
Returns:
The popped top Route header, or null if none was removed.
Note:
To access URI parameters added to the Record-Route header, use poppedRoute.getURI().getParameter() instead of poppedRoute.getParameter().

pushPath
void pushPath(Address uri)
The method adds a Path header field value to the SIP request. The specified address is added as the first value in the Path header. If the request does not already have a Path header, one is created and populated with the provided value. This method is primarily used by User Agent Clients (UACs) or proxies for adding Path headers to REGISTER requests.
Parameters:
uri: The address to be added as a Path header value.
Exception:
java.lang.IllegalStateException is thrown if the method is invoked on a request other than a REGISTER request.

pushRoute
void pushRoute(Address uri)
The method adds a Route header field value to the SIP request using the provided Address. The new value is inserted at the beginning of the Route header field list. If the request does not already contain a Route header, a new Route header is created with the specified value. This method enables a User Agent Client or proxy to define intermediate proxies that the request should traverse before reaching its destination.
Parameters:
uri: The address to be added as a Route header value.

pushRoute
void pushRoute(SipURI uri)
The method adds a Route header field value to the SIP request using the specified SipURI. The new value is inserted at the beginning of the Route header list. If the request does not already have a Route header, a new Route header is created with the provided SipURI. This method allows a User Agent Client or proxy to define intermediate proxies that the request should traverse before being delivered to its destination.
Parameters:
uri: The URI to be added as a Route header value.

getRoutingDirective
SipApplicationRoutingDirective getRoutingDirective()
                                                   throws java.lang.IllegalStateException
The method retrieves the SipApplicationRoutingDirective associated with the SIP request. This directive determines how the container should handle routing for the request.
Returns:
The routing directive associated with this request.
Exception:
java.lang.IllegalStateException thrown if the method is called on a request that is not an initial request.

setRoutingDirective
void setRoutingDirective(SipApplicationRoutingDirective directive,
                         SipServletRequest origRequest)
                         throws java.lang.IllegalStateException
The method sets the application routing directive for an outgoing SIP request. The routing directive determines whether the request continues the application selection process, starts afresh, or reverses the flow. This method allows customization of the default behavior when creating requests.
Requests created using SipFactory.createRequest(SipServletRequest origRequest, boolean sameCallId) have a default directive of CONTINUE.
Requests created using other SipFactory.createRequest methods have a default directive of NEW.
Parameters:
directive: The routing directive to assign to the outgoing request. Possible values:

• NEW: Starts the application selection process afresh. Ignores the origRequest parameter.
• CONTINUE: Continues the application selection process from the original request.
• REVERSE: Reverses the application selection process.

origRequest: An initial request that the application received. This must be an initial request dispatched by the container and meet the following conditions:

• origRequest.isInitial() must return true.
• The request must either belong to a new SipSession or be created from an initial request.
• The request must not have been sent.

Exception:
java.lang.IllegalStateException thrown if the given directive cannot be set due to a violation of preconditions or origRequest does not satisfy the required criteria for CONTINUE or REVERSE directives.

URI and Address Handling

getRequestURI
URI getRequestURI()
The method retrieves the Request-URI of the SIP request. The Request-URI indicates the resource the request is targeting.
Returns:
The Request-URI of this SipServletRequest.

setRequestURI
void setRequestURI(URI uri)
The method sets the Request-URI of the SIP request to the specified URI. This updated URI will be used as the destination when the send method is invoked on the request.
Parameters:
uri: The new Request-URI for this SipServletRequest.
Exception: 
java.lang.NullPointerException is thrown if the provided uri is null.

getSubscriberURI
URI getSubscriberURI()
The method retrieves the URI of the subscriber for which the application has been invoked. This is only applicable for initial requests. For non-initial requests, an exception is thrown.
Returns:
The URI of the subscriber associated with the initial request.
Exception: 
java.lang.IllegalStateException is thrown if the method is called on a request that is not an initial request.

getInputStream
javax.servlet.ServletInputStream getInputStream()
                                                throws java.io.IOException
The method is not utilized in SIP servlets, as SIP is not a content transfer protocol. Therefore, this method always returns null. To retrieve message content, use getContent() or getRawContent() methods instead.
Returns:
Always returns null.
Exception:
java.io.IOException is thrown if an I/O error occurs, though this is unlikely due to the method's behavior.

getReader
java.io.BufferedReader getReader()
                                 throws java.io.IOException
The method is not applicable to SIP servlets, as SIP is not a content transfer protocol. This method always returns null. For retrieving message content, use the getContent() or getRawContent() methods instead.
Returns:
Always returns null.
Exception:
java.io.IOException is thrown if an I/O error occurs, although this is not commonly applicable given the method's behavior.

Session and Region Management

getB2buaHelper
B2buaHelper getB2buaHelper()
The method retrieves the B2buaHelper associated with the current SIP request. Calling this method signals to the container that the application intends to act as a Back-to-Back User Agent (B2BUA). Once this method is invoked, any subsequent call to getProxy() will throw an exception.
Returns:
The B2buaHelper associated with this request.
Exception:
java.lang.IllegalStateException is thrown if the getProxy() method has already been invoked.

getRegion
SipApplicationRoutingRegion getRegion()
The method retrieves the routing region in which the application was invoked for the current SipServletRequest. This information allows the application to determine the location of the subscriber identified by the getSubscriberURI() method.
This method is only applicable for initial requests. For non-initial requests, an exception is thrown.
Returns:
The routing region in which the servlet is invoked. Possible are ORIGINATING, NEUTRAL, TERMINATING and sub-regions of these.
Exception:
java.lang.IllegalStateException is thrown if the method is called on a request that is not an initial request.

Request Metadata

isInitial
boolean isInitial()
The method checks whether the current SipServletRequest is an initial request. An initial request is dispatched to applications based on the container's configured rule set, unlike subsequent requests that follow the application path established by a prior initial request.
Returns:
true if this is an initial request, false otherwise.

getMaxForwards
int getMaxForwards()
The method retrieves the value of the Max-Forwards header in the SIP message. This header indicates the remaining number of hops that a request can traverse before reaching its destination.
Returns:
The value of the Max-Forwards header. -1 if the header is not present in the message.

setMaxForwards
void setMaxForwards(int n)
The method sets the value of the Max-Forwards header in the SIP message. The Max-Forwards header limits the number of hops a request can take before being discarded. The value is decremented by one at each hop. This method is functionally equivalent to setHeader("Max-Forwards", String.valueOf(n));
Parameters:
n: The new value of the Max-Forwards header. Must be in the range 0 to 255.
Exception:
java.lang.IllegalArgumentException is thrown if the provided value is not in the valid range of 0 to 255.

Request Transmission

send
void send()
          throws java.io.IOException
The method is used to transmit the current SIP request. This method is applicable only for SIP servlets acting as User Agent Clients (UACs). For proxying applications, the Proxy.proxyTo(javax.servlet.sip.URI) method should be used instead to handle requests.
Exception:
java.io.IOException is thrown if a transport error occurs during the attempt to send the request.