SipServletResponse

The SipServletResponse interface represents SIP responses in the SIP Servlet API. It extends the ServletResponse and SipServletMessage interfaces, inheriting generic servlet response functionalities and shared SIP message behaviors. Additionally, it adds methods specific to SIP responses.
This interface allows servlets to handle incoming SIP responses received from the container and to generate SIP responses as User Agent (UA) servers or proxies. It provides tools for managing response status codes, headers, and content.
SIP responses indicate the outcome of a corresponding SIP request. Each SIP response is defined by a three-digit status code that describes the result of the request, providing information about its progress, success, redirection, or failure. Responses with a status code in the range 100–199 are called provisional or informational and indicate the progress of the request. Any response with a status code of 200 or higher is the final response. A UA server may send only one final response per request, but this may be preceded by any number of provisional responses.
1xx: Informational Responses – Provisional responses that indicate progress in processing the request.
2xx: Successful Responses – Indicate that the request was successfully processed.
3xx: Redirection Responses – Indicate that further action is needed to complete the request.
4xx: Client Error Responses – Indicate issues with the request that prevent it from being fulfilled.
5xx: Server Error Responses – Indicate that the server failed to process an apparently valid request.
6xx: Global Failure Responses – Indicate that the request cannot be fulfilled by any server.

When the SIP Servlet container receives an incoming SIP response, it creates a SipServletResponse object and passes it to the appropriate servlet. This allows the application to process the response, including headers, content, and status codes.
Servlets acting as UA servers or proxies can generate and send SIP responses. These responses may include provisional (1xx) and final (2xx–6xx) responses to indicate the outcome of the request.
The SipServletResponse interface adheres to the SIP specification as outlined in RFC 3261.
It also adds support for SIP-specific behaviors, such as generating responses with specific status codes and managing SIP transaction states.
Important Note:
The setCharacterEncoding() method in this interface does not throw java.io.UnsupportedEncodingException, unlike its counterpart in SipServletMessage. Instead, it inherits a more generic version of the method from the ServletResponse interface, in accordance with the Servlet specification version 2.4.

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.

Fields

Informational Responses (1xx):

SC_TRYING
static final int SC_TRYING
Status code 100: The server is trying to locate the callee.

SC_RINGING
static final int SC_RINGING
Status code 180: The server has found the callee, and their user agent is ringing.

SC_CALL_BEING_FORWARDED
static final int SC_CALL_BEING_FORWARDED
Status code 181: The call is being forwarded to another destination.

SC_CALL_QUEUED
static final int SC_CALL_QUEUED
Status code 182: The call has been placed in a queue.

SC_SESSION_PROGRESS
static final int SC_SESSION_PROGRESS
Status code 183: The response provides call progress information. Additional  details may be in the Reason-Phrase.

Successful Responses (2xx):

SC_OK
static final int SC_OK
Status code 200: The request was successful.

SC_ACCEPTED
static final int SC_ACCEPTED
Status code 202: The request was accepted for processing but is not yet completed. Processing might fail later.

Redirection Responses (3xx):

SC_MULTIPLE_CHOICES
static final int SC_MULTIPLE_CHOICES
Status code 300: The user can be reached at multiple locations.

SC_MOVED_PERMANENTLY
static final int SC_MOVED_PERMANENTLY
Status code 301: The callee has moved permanently.

SC_MOVED_TEMPORARILY
static final int SC_MOVED_TEMPORARILY
Status code 302: The callee has moved temporarily.

SC_USE_PROXY
static final int SC_USE_PROXY
Status code 305: The call can be handled better by the specified proxy server.

SC_ALTERNATIVE_SERVICE
static final int SC_ALTERNATIVE_SERVICE
Status code 380: An alternative service is available.

Client Error Responses (4xx):

SC_BAD_REQUEST
static final int SC_BAD_REQUEST
Status code 400: The request syntax is invalid or malformed.

SC_UNAUTHORIZED
static final int SC_UNAUTHORIZED
Status code 401: The caller is not authorized to make the request.

SC_PAYMENT_REQUIRED
static final int SC_PAYMENT_REQUIRED
Status code 402: Payment is required to process the request.

SC_FORBIDDEN
static final int SC_FORBIDDEN
Status code 403: The caller is forbidden from making this request.

SC_NOT_FOUND
static final int SC_NOT_FOUND
Status code 404: The user does not exist, or the domain in the request is unrecognized.

SC_METHOD_NOT_ALLOWED
static final int SC_METHOD_NOT_ALLOWED
Status code 405: The method specified in the Request-Line is not permitted for the address identified by the Request-URI. The response MUST include an Allow header field listing the valid methods available for the specified address.

SC_NOT_ACCEPTABLE
static final int SC_NOT_ACCEPTABLE
Status code 406: The resource cannot generate acceptable content for the request according to the accept headers sent in the request.

SC_PROXY_AUTHENTICATION_REQUIRED
static final int SC_PROXY_AUTHENTICATION_REQUIRED
Status code 407: The client MUST authenticate itself with the proxy before proceeding. The proxy MUST include a Proxy-Authenticate header field containing a challenge specific to the proxy and the requested resource. The client MAY resend the request with a valid Proxy-Authorization header field to complete authentication.
This status code is used when authentication is required to access the communication channel, rather than the callee.

SC_REQUEST_TIMEOUT
static final int SC_REQUEST_TIMEOUT
Status code 408: The server could not produce a response, such as resolving a user location, within the time specified in the Expires header field. The client MAY repeat the request without modifications at a later time.

SC_GONE
static final int SC_GONE
Status code 410: The requested resource is no longer available, and no forwarding address is known. This condition is considered permanent. If the server cannot confirm the permanence of the condition, it SHOULD return status code 404 (Not Found) instead.

SC_CONDITIONAL_REQUEST_FAILED
static final int SC_CONDITIONAL_REQUEST_FAILED
Status code 412: The precondition provided in the request has failed.

SC_REQUEST_ENTITY_TOO_LARGE
static final int SC_REQUEST_ENTITY_TOO_LARGE
Status code 413: The server is refusing to process the request because the request entity is too large. The server may close the connection to prevent further data from being sent.
If the condition is temporary, the server should include a Retry-After header field to indicate when the client may retry the request.

SC_REQUEST_URI_TOO_LONG
static final int SC_REQUEST_URI_TOO_LONG
Status code 414: The server is refusing to process the request because the Request-URI is longer than the server can interpret.

SC_UNSUPPORTED_MEDIA_TYPE
static final int SC_UNSUPPORTED_MEDIA_TYPE
Status code 415: The server is refusing to process the request because the message body format is not supported.
The server should return a list of acceptable formats in the Accept, Accept-Encoding, and Accept-Language headers.

SC_UNSUPPORTED_URI_SCHEME
static final int SC_UNSUPPORTED_URI_SCHEME
Status code 416: The server cannot process the request because the URI scheme in the Request-URI is unknown to the server.

SC_BAD_EXTENSION
static final int SC_BAD_EXTENSION
Status code 420: The server did not understand the protocol extension specified in the Require header field.

SC_EXTENSION_REQUIRED
static final int SC_EXTENSION_REQUIRED
Status code 421: The User Agent Server (UAS) requires an extension to process the request. This extension is not listed in the Supported header field of the request.

SC_SESSION_INTERVAL_TOO_SMALL
static final int SC_SESSION_INTERVAL_TOO_SMALL
Status code 422: The Session-Expires header in the request specifies a duration shorter than the server's minimum allowed timer.

SC_INTERVAL_TOO_BRIEF
static final int SC_INTERVAL_TOO_BRIEF
Status code 423: The server is rejecting the request because the resource expiration time in the request is too short.

SC_USE_IDENTITY_HEADER
static final int SC_USE_IDENTITY_HEADER
Status code 428: The request must be re-sent with an Identity header.

SC_PROVIDE_REFERER_IDENTITY
static final int SC_PROVIDE_REFERER_IDENTITY
Status code 429: The referee must provide a valid Referred-By token in the request.

SC_BAD_IDENTITY_INFO
static final int SC_BAD_IDENTITY_INFO
Status code 436: The Identity-Info header contains a URI that cannot be dereferenced. This may occur due to an unsupported URI scheme or an unavailable resource.

SC_UNSUPPORTED_CERTIFICATE
static final int SC_UNSUPPORTED_CERTIFICATE
Status code 437: The verifier cannot validate the certificate referenced in the Identity-Info URI. Reasons might include a self-signed certificate or a certificate issued by an unknown root certificate authority.

SC_INVALID_IDENTITY_HEADER
static final int SC_INVALID_IDENTITY_HEADER
Status code 438: The Identity signature in the message does not match the digest-string calculated by the verifier.

SC_TEMPORARLY_UNAVAILABLE
static final int SC_TEMPORARLY_UNAVAILABLE
Status code 480: The callee's end system was contacted but is currently unavailable (e.g., not logged in). A Retry-After header may indicate a better time to call.
This status does not terminate searches, as the user might be available elsewhere. If the reason for failure is more specific, status 486 (Busy Here) may be used instead. Redirect servers may also return this status if no valid forwarding location is known.

SC_CALL_LEG_DONE
static final int SC_CALL_LEG_DONE
Status code 481: The Call Leg or Transaction does not exist.
is returned under 2 conditions:
The server receives a BYE request that does not match an existing call leg.
The server receives a CANCEL request that does not match an existing transaction.
An ACK referring to an unknown transaction is simply discarded.

SC_LOOP_DETECTED
static final int SC_LOOP_DETECTED
Status code 482: The server received a request with a Via path containing itself, indicating a loop.

SC_TOO_MANY_HOPS
static final int SC_TOO_MANY_HOPS
Status code 483: The request has more Via entries (hops) than allowed by the Max-Forwards header field. This indicates the request exceeded the maximum allowable hops.

SC_ADDRESS_INCOMPLETE
static final int SC_ADDRESS_INCOMPLETE
Status code 484: The server received a request with an incomplete To address or Request-URI. Additional information should be provided to clarify the missing details.
This status code supports overlapped dialing, where the client sends progressively longer dialing strings until a complete address is provided, and the 484 response is no longer received.

SC_AMBIGUOUS
static final int SC_AMBIGUOUS
Status code 485: The callee address in the request is ambiguous. The response may include possible alternatives in Contact headers, listing unambiguous addresses.
Unlike 3xx responses, which assume all options lead to the same person or service, 485 responses require user intervention rather than automated handling. For privacy reasons, servers can be configured to return 404 (Not Found) or suppress the alternative listing.

SC_BUSY_HERE
static final int SC_BUSY_HERE
Status code 486: The callee's end system was contacted successfully, but the callee is not willing or able to take the call.

SC_REQUEST_TERMINATED
static final int SC_REQUEST_TERMINATED
Status code 487: The request was terminated by a BYE or CANCEL request.

SC_NOT_ACCEPTABLE_HERE
static final int SC_NOT_ACCEPTABLE_HERE
Status code 488: The request is not acceptable for the specific resource addressed by the Request-URI. However, the request may succeed elsewhere.

SC_BAD_EVENT
static final int SC_BAD_EVENT
Status code 489: The server did not recognize the event package specified in the Event header field.

SC_REQUEST_PENDING
static final int SC_REQUEST_PENDING
Status code 491: The request was received by a UAS, but a pending request exists within the same dialog.

SC_UNDECIPHERABLE
static final int SC_UNDECIPHERABLE
Status code 493: The request contained an encrypted MIME body that the recipient cannot decrypt or refuses to provide a decryption key for.

SC_SECURITY_AGREEMENT_REQUIRED
static final int SC_SECURITY_AGREEMENT_REQUIRED
Status code 494: The client must initiate a security mechanism as defined in RFC 3329.

Server Error Responses (5xx):

SC_SERVER_INTERNAL_ERROR
static final int SC_SERVER_INTERNAL_ERROR
Status code 500: The server encountered an unexpected condition that prevented it from fulfilling the request.

SC_NOT_IMPLEMENTED
static final int SC_NOT_IMPLEMENTED
Status code 501: The server does not support the functionality required to fulfill the request.

SC_BAD_GATEWAY
static final int SC_BAD_GATEWAY
Status code 502: The server, acting as a gateway or proxy, received an invalid response from the downstream server while trying to fulfill the request.

SC_SERVICE_UNAVAILABLE
static final int SC_SERVICE_UNAVAILABLE
Status code 503: The server is temporarily unable to handle the request due to overloading or maintenance.

SC_SERVER_TIMEOUT
static final int SC_SERVER_TIMEOUT
Status code 504: The server did not receive a timely response from an external server it accessed to process the request.

SC_VERSION_NOT_SUPPORTED
static final int SC_VERSION_NOT_SUPPORTED
Status code 505: The server does not support the SIP protocol version used in the request message.

SC_MESSAGE_TOO_LARGE
static final int SC_MESSAGE_TOO_LARGE
Status code 513: The server could not process the request because the message length exceeded its capabilities.

SC_PRECONDITION_FAILURE
static final int SC_PRECONDITION_FAILURE
Status code 580: The server could not fulfill the request because certain preconditions were not met.

Global Failure Responses (6xx):

SC_BUSY_EVERYWHERE
static final int SC_BUSY_EVERYWHERE
Status code 600: The callee's end system was successfully contacted, but the callee is busy and does not wish to take the call at this time.

SC_DECLINE
static final int SC_DECLINE
Status code 603: The callee's machine was successfully contacted, but the user explicitly does not wish to or cannot participate.
The response may include a Retry-After header to suggest a better time to call.

SC_DOES_NOT_EXIT_ANYWHERE
static final int SC_DOES_NOT_EXIT_ANYWHERE
Status code 604: The server has authoritative information that the user in the To field does not exist anywhere. Searching elsewhere will not yield results.

SC_NOT_ACCEPTABLE_ANYWHERE
static final int SC_NOT_ACCEPTABLE_ANYWHERE
Status code 606: The user's agent was successfully contacted, but some session aspects (e.g., media type, bandwidth, or addressing style) are not acceptable.

Methods

createAck
SipServletRequest createAck()
Creates an ACK request object corresponding to this response. This method is intended for servlets acting as User Agent Clients (UACs) to acknowledge 2xx final responses to INVITE requests.
Important: Applications do not generate ACKs for non-2xx responses. These are handled automatically by the container.
Returns:
An ACK request object corresponding to this response.
Exception: 
java.lang.IllegalStateException is thrown if:

• The transaction state does not allow sending an ACK at this time.
• The original request was not an INVITE.
• This response is provisional (not final).
• An ACK has already been generated for this response.

getRequest
SipServletRequest getRequest()
Retrieves the request associated with this response.
For responses received for proxied requests, this method returns a SipServletRequest object that represents the request as it was sent downstream. Proxying applications can use the Request-URI from this object to correlate the incoming response with one of the destinations the request was proxied to.
Returns:
The SipServletRequest object for which this response was generated.

createPrack
SipServletRequest createPrack()
    throws Rel100Exception
Creates a PRACK request object corresponding to this response. This method is used by servlets acting as User Agent Clients (UACs) to acknowledge reliable provisional responses to INVITE requests, as defined in RFC 3262.
Returns:
A PRACK request object corresponding to this response.
Exceptions:
java.lang.IllegalStateException is thrown if the transaction state does not allow a PRACK to be sent at this time or a PRACK has already been generated for this response.
Rel100Exception is thrown if the response is not a reliable provisional response or the original request was not an INVITE.

getChallengeRealms
java.util.Iterator<java.lang.String> getChallengeRealms()
Returns an Iterator over all the realms associated with this challenge response.
Returns:
Iterator over all the realms associated with this challenge response.

getOutputStream
javax.servlet.ServletOutputStream getOutputStream()
                                                  throws java.io.IOException
This method always returns null.
SIP is not a content transfer protocol, so stream-based content access is generally unnecessary. Message content should be set using the SipServletMessage.setContent(java.lang.Object, java.lang.String) method instead.
Specified by getOutputStream.
Returns: 
null
Exception:
java.io.IOException is thrown if an I/O error occurs, though this is rarely applicable due to the method's behavior.

getProxy
Proxy getProxy()
Retrieves the Proxy object associated with the transaction of this SIP response. A Proxy object exists if this response corresponds to a previously proxied request. If the response is not tied to a proxied request, this method returns null.
The container ensures that the same Proxy instance is returned for all messages related to the same transaction. For example, a response to a proxied request will be associated with the same Proxy object as the original proxied request.
Returns: 
The Proxy object associated with this response's transaction, or null if the response was not for a proxied request.

getProxyBranch
ProxyBranch getProxyBranch()
Retrieves the ProxyBranch object associated with the transaction of this SIP response. A ProxyBranch object exists if this response is related to a previously proxied request. If the response is not tied to a proxied request, this method returns null.
The container ensures that the same ProxyBranch instance is returned for all messages related to the same transaction. For example, a response to a proxied request is associated with the same ProxyBranch object as the request sent on that branch.
Returns:
The ProxyBranch object associated with this response's transaction, or null if the response was not for a proxied request.

getReasonPhrase
java.lang.String getReasonPhrase()
Retrieves the reason phrase for this response object. The reason phrase is a textual description accompanying the status code of the response. It provides additional context or explanation for the response status, often used for debugging or logging purposes. (Status code 200 might have the reason phrase "OK". Status code 404 might have the reason phrase "Not Found".)
Returns:
The reason phrase for this response.

getRequest
SipServletRequest getRequest()
Returns the request associated with this response. For responses received for proxied requests, this method returns a request object that represents the request as it was sent downstream.
Proxying applications can use the request URI obtained from the request object to correlate an incoming response to one of the several destinations it has been proxied to.
Returns: 
Request for which this response was generated

setStatus
void setStatus(int statusCode,
    java.lang.String reasonPhrase)
Sets the status code and reason phrase of this response object.
Parameters:
statusCode: status code of this response.
reasonPhrase: short textual description of the status code.
Exception:
java.lang.IllegalArgumentException is thrown if the code is not a SIP allowable status code.

getWriter
java.io.PrintWriter getWriter()
                              throws java.io.IOException
This method always returns null.
SIP is not a content transfer protocol, so stream-based content access methods like getWriter are not useful. Instead, message content should be set using the SipServletMessage.setContent(java.lang.Object, java.lang.String) method.
Returns:
null
Exception:
java.io.IOException is thrown if an I/O error occurs, though this is rarely applicable due to the method's behavior.

isBranchResponse
boolean isBranchResponse()
Determines if this response is an intermediate final response that arrived on a ProxyBranch.
This method is primarily used in the SipServlet.doResponse() method to identify intermediate final responses received on a ProxyBranch. These responses are then delegated to the SipServlet.doBranchResponse() method for handling.
Returns: 
true: If the response arrived on a ProxyBranch.
false: If the response did not arrive on a ProxyBranch, or if it is the best final response chosen by the Proxy.

send
void send()
          throws java.io.IOException
Sends this response. This method is used by servlets acting as User Agent Servers (UASs) to send both provisional and final responses. It is also used by proxies when generating provisional responses.
Exceptions:
java.io.IOException if a transport error occurs while trying to send the response.
java.lang.IllegalStateException if the response was received from downstream or if it has already been sent.

sendReliably
void sendReliably()
Requests that this response be sent reliably using the 100rel extension, as defined in RFC 3262.
This method must only be invoked for 1xx responses other than 100 Trying and only if the User Agent Client (UAC) indicated support for the 100rel extension in the request and the container supports it.
Applications can verify container support for the 100rel extension by:

• Checking if 100rel exists in the list of supported extensions available via the ServletContext attribute javax.servlet.sip.supported.
• Alternatively, using the v1.0 mechanism (deprecated in this version), which involves checking for the ServletContext attribute javax.servlet.sip.100rel with a value of Boolean.TRUE.

This method is specifically used for reliable provisional responses and should be employed only when all preconditions are met.
Exceptions:
Rel100Exception is thrown if the conditions for using the 100rel extension are not satisfied.
java.lang.IllegalStateException is thrown if the response was received from downstream or if the response has already been sent.

setStatus
void setStatus(int statusCode)
Sets the status code of this response object.
Parameters:
statusCode: The status code to be set for this response.

setStatus
void setStatus(int statusCode,
               java.lang.String reasonPhrase)
Sets the status code and reason phrase for this response object.
Parameters:
statusCode: The status code to be set for this response.
reasonPhrase: A short textual description of the status code.
Exception:
java.lang.IllegalArgumentException is thrown if the status code is not a valid SIP status code.