SipServlet

The SipServlet class is the core component of the SIP Servlet API. It handles incoming SIP messages and generates appropriate responses. It provides lifecycle methods that can be overridden to customize SIP request and response handling, similar to the HttpServlet in the HTTP Servlet API.
The SipServlet processes incoming SIP messages using the service method, which distinguishes between requests and responses:

• For requests, the doRequest method is invoked.
• For responses, the doResponse method is invoked.

These methods further dispatch processing to specific handler methods based on the SIP request type (e.g., INVITE, BYE) or response status code (e.g., 200 OK, 404 Not Found).
The SipServlet class provides specific methods to handle each type of SIP request and response. Developers can override these methods to define custom behavior.
The default implementation of doAck, doCancel and all the response handling methods are empty. All other request handling methods reject the request with a 500 error response. This behavior ensures that unhandled requests are safely rejected while allowing developers to override only the methods relevant to their application.
Subclasses of SipServlet will typically override one or more of the request and response handling methods to implement application-specific logic.

Fields in SipServlet

The SipServlet class defines several constants that represent names of attributes in the ServletContext. These attributes allow SIP servlets to access key utilities and configurations provided by the container.

SIP_FACTORY
public static final java.lang.String SIP_FACTORY
The SIP_FACTORY field is a constant string with the value "javax.servlet.sip.SipFactory". It represents the name of the ServletContext attribute that holds an instance of the SipFactory interface.

TIMER_SERVICE
public static final java.lang.String TIMER_SERVICE
The field is a constant string with the value "javax.servlet.sip.TimerService". It represents the name of the ServletContext attribute that holds an instance of the TimerService interface.
The TimerService interface allows applications to schedule asynchronous events for future execution.

SUPPORTED
public static final java.lang.String SUPPORTED
The field is a constant string with the value "javax.servlet.sip.supported". It represents the name of the ServletContext attribute that holds a list of strings, where each string is the name of a SIP extension supported by the SIP container. The SUPPORTED attribute allows applications to query the SIP container for the set of SIP extensions it supports.

SUPPORTED_RFCs
public static final java.lang.String SUPPORTED_RFCs
The field is a constant string with the value "javax.servlet.sip.supportedRfcs". It represents the name of the ServletContext attribute that holds a List of strings, where each string corresponds to an RFC number representing a SIP standard supported by the SIP container.

OUTBOUND_INTERFACES
public static final java.lang.String OUTBOUND_INTERFACES
The field is a constant string with the value "javax.servlet.sip.outboundInterfaces". It represents the name of the ServletContext attribute that holds a list of SipURI objects, where each SipURI represents an available outbound interface for sending SIP requests. The OUTBOUND_INTERFACES attribute provides information about the network interfaces available for sending SIP requests on a multihomed machine (a machine with multiple network interfaces). Applications can retrieve the list of outbound interfaces and use methods like SipSession.setOutboundInterface(java.net.InetSocketAddress) or Proxy.setOutboundInterface(java.net.InetSocketAddress) to choose a specific interface for sending requests.

SIP_SESSIONS_UTIL
public static final java.lang.String SIP_SESSIONS_UTIL
The field is a constant string with the value "javax.servlet.sip.SipSessionsUtil". It represents the name of the ServletContext attribute that holds an instance of the SipSessionsUtil utility class. The SipSessionsUtil class provides support for converged SIP/HTTP applications, enabling interaction between SIP and HTTP sessions.

PRACK_SUPPORTED
public static final java.lang.String PRACK_SUPPORTED
The field is a constant string with the value "javax.servlet.sip.100rel". It represents the name of the ServletContext attribute that indicates whether the SIP container supports the 100rel extension as defined by RFC 3262.
Deprecated: The use of PRACK_SUPPORTED is discouraged in favor of the more general "javax.servlet.sip.supported" attribute, which provides a list of supported SIP extensions.

Constructor

SipServlet
public SipServlet()
The SipServlet constructor is the default, no-argument constructor for the SipServlet class. This constructor is used to create instances of SIP servlets, which act as the main entry point for handling SIP requests and responses in a SIP application. The SipServlet constructor is typically not invoked directly but through the SIP container during application deployment.
Servlets created using this constructor serve as the backbone for SIP application logic, such as call processing, routing, and session management.

Core Lifecycle Methods

service
public void service(javax.servlet.ServletRequest req,
                    javax.servlet.ServletResponse resp)
             throws javax.servlet.ServletException,
                    java.io.IOException
The method is the entry point for handling incoming SIP messages, whether they are requests or responses. It determines the type of message and dispatches the call to either doRequest() or doResponse().
In most cases, you do not need to override this method directly. Instead, you should override the specialized request or response handling methods (doInvite, doResponse, etc.) provided by the SipServlet class.
Exactly one of the parameters, req or resp, is null:

• If the event is an incoming request, resp is null.
• If the event is an incoming response, req is null.

Delegates to doRequest(SipServletRequest request) for requests and to doResponse(SipServletResponse response) for responses.
Parameters:
req: Represents the SIP request to handle. This is null for incoming responses.
resp: Represents the SIP response to handle. This is null for incoming requests.
Exceptions:
javax.servlet.ServletException: Thrown if an exception occurs that interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.
 
doRequest
protected void doRequest(SipServletRequest req)
                  throws javax.servlet.ServletException,
                         java.io.IOException
The method is invoked by the SIP container to handle incoming SIP requests. It dispatches the request to one of the specialized doXxx methods, where Xxx corresponds to the SIP method of the incoming request (e.g., doInvite, doBye, doCancel).
Usually, you do not need to override this method directly. Instead, you should implement specific behavior by overriding the appropriate doXxx methods.
Delegates to specialized methods based on the SIP request method (e.g., INVITE, BYE, OPTIONS). If a specific doXxx method is not implemented, the default behavior in SipServlet will handle the request.
Parameters:
req: Represents the incoming SIP request that triggered this method.
Exceptions:
javax.servlet.ServletException: Thrown if an exception occurs that interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing. 

doResponse
protected void doResponse(SipServletResponse resp)
                   throws javax.servlet.ServletException,
                          java.io.IOException
The method is invoked by the SIP container to handle incoming SIP responses. It dispatches the response to one of the specialized methods, such as:

• doProvisionalResponse() – For 1xx responses (e.g., 180 Ringing).
• doSuccessResponse() – For 2xx responses (e.g., 200 OK).
• doRedirectResponse() – For 3xx responses (e.g., 302 Moved Temporarily).
• doErrorResponse() – For 4xx, 5xx, or 6xx responses (e.g., 404 Not Found).
• doBranchResponse() – For intermediate final responses received on a ProxyBranch.

Usually, you do not need to override doResponse directly. Instead, override the specialized methods for handling specific response types.
Delegates to a specific handler based on the SIP response type or status code. Handles responses related to both client and server transactions. Supports handling of responses generated during proxying (via doBranchResponse).
Parameters:
resp: Represents the incoming SIP response.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet’s normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing. 

Request Handling Methods

doInvite
protected void doInvite(SipServletRequest req)
                 throws javax.servlet.ServletException,
                        java.io.IOException
The method is invoked by the SIP container to handle incoming SIP INVITE requests. INVITE requests are used to initiate SIP sessions or dialogs, such as establishing a voice or video call. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP INVITE request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doAck
protected void doAck(SipServletRequest req)
              throws javax.servlet.ServletException,
                     java.io.IOException
The method is invoked by the SIP container to handle incoming SIP ACK requests. ACK requests are used to confirm the receipt of a successful response (e.g., 200 OK) to an INVITE request in a SIP dialog. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP ACK request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doOptions
protected void doOptions(SipServletRequest req)
                  throws javax.servlet.ServletException,
                         java.io.IOException
The method is invoked by the SIP container to handle incoming SIP OPTIONS requests. OPTIONS requests are used for querying capabilities or testing the availability of a SIP endpoint. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP OPTIONS request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doBye
protected void doBye(SipServletRequest req)
              throws javax.servlet.ServletException,
                     java.io.IOException
The method is invoked by the SIP container to handle incoming SIP BYE requests. A BYE request is used to terminate an existing SIP session or dialog, typically indicating the end of a call or session. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP BYE request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doCancel
protected void doCancel(SipServletRequest req)
                 throws javax.servlet.ServletException,
                        java.io.IOException
The method is invoked by the SIP container to handle incoming SIP CANCEL requests. A CANCEL request is used to terminate a pending SIP transaction, such as an uncompleted INVITE. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP CANCEL request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doRegister
protected void doRegister(SipServletRequest req)
                   throws javax.servlet.ServletException,
                          java.io.IOException
The method is invoked by the SIP container to handle incoming SIP REGISTER requests. A REGISTER request is used to register a SIP user's current location (e.g., device or IP address) with a registrar server. This allows SIP calls or messages to be routed to the user. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP REGISTER request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doSubscribe
protected void doSubscribe(SipServletRequest req)
                    throws javax.servlet.ServletException,
                           java.io.IOException
The method is invoked by the SIP container to handle incoming SIP SUBSCRIBE requests. A SUBSCRIBE request is used to request asynchronous notification of an event or resource's state, such as presence, voicemail updates, or dialog changes. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP SUBSCRIBE request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doNotify
protected void doNotify(SipServletRequest req)
                 throws javax.servlet.ServletException,
                        java.io.IOException
The method is invoked by the SIP container to handle incoming SIP NOTIFY requests. A NOTIFY request is used to inform a subscriber of an event's state or a change in the state of a resource, following a SUBSCRIBE request. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP NOTIFY request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doMessage
protected void doMessage(SipServletRequest req)
                  throws javax.servlet.ServletException,
                         java.io.IOException
The method is invoked by the SIP container to handle incoming SIP MESSAGE requests. MESSAGE requests are used for instant messaging in SIP applications, allowing the exchange of textual content or other payloads. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP MESSAGE request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doInfo
protected void doInfo(SipServletRequest req)
               throws javax.servlet.ServletException,
                      java.io.IOException
The method is invoked by the SIP container to handle incoming SIP INFO requests. INFO requests are used to exchange session-related information within an existing SIP dialog, such as application-specific signaling or DTMF tones. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP INFO request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doPrack
protected void doPrack(SipServletRequest req)
                throws javax.servlet.ServletException,
                       java.io.IOException
The method is invoked by the SIP container to handle incoming SIP PRACK (Provisional Response Acknowledgment) requests. PRACK is used to acknowledge reliable provisional responses (e.g., 1xx responses) sent with the 100rel extension, as specified in RFC 3262. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP PRACK request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doUpdate
protected void doUpdate(SipServletRequest req)
                 throws javax.servlet.ServletException,
                        java.io.IOException
The method is invoked by the SIP container to handle incoming SIP UPDATE requests. The UPDATE request is used to modify session parameters, such as SDP (Session Description Protocol), in an existing SIP dialog or during the early dialog phase. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP UPDATE request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doRefer
protected void doRefer(SipServletRequest req)
                throws javax.servlet.ServletException,
                       java.io.IOException
The method is invoked by the SIP container to handle incoming SIP REFER requests. A REFER request is used to instruct the recipient to contact a third party, initiating a transfer or other action as described in the Refer-To header. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP REFER request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doPublish
protected void doPublish(SipServletRequest req)
                  throws javax.servlet.ServletException,
                         java.io.IOException
The method is invoked by the SIP container to handle incoming SIP PUBLISH requests. PUBLISH requests are used to convey event state information to an event state compositor, as defined in RFC 3903. For example, it can be used to publish presence information in SIP applications. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
req: Represents the incoming SIP PUBLISH request.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

Response Handling Methods

doProvisionalResponse
protected void doProvisionalResponse(SipServletResponse resp)
                              throws javax.servlet.ServletException,
                                     java.io.IOException
The method is invoked by the SIP container to handle incoming provisional (1xx class) SIP responses. Provisional responses are sent to indicate call progress or temporary status before a final response (e.g., 180 Ringing or 183 Session Progress). This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
resp: Represents the incoming SIP provisional response.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doSuccessResponse
protected void doSuccessResponse(SipServletResponse resp)
                          throws javax.servlet.ServletException,
                                 java.io.IOException
The method is invoked by the SIP container to handle incoming successful (2xx class) SIP responses. These responses indicate that the request has been successfully processed, such as a 200 OK for an INVITE, OPTIONS, or BYE request. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
resp: Represents the incoming SIP successful response.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doRedirectResponse
protected void doRedirectResponse(SipServletResponse resp)
                           throws javax.servlet.ServletException,
                                  java.io.IOException
The method is invoked by the SIP container to handle incoming redirection (3xx class) SIP responses. Redirection responses indicate that the request should be redirected to one or more alternative destinations specified in the response. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
resp: Represents the incoming SIP redirection response.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

doErrorResponse
protected void doErrorResponse(SipServletResponse resp)
                        throws javax.servlet.ServletException,
                               java.io.IOException
The method is invoked by the SIP container to handle incoming error responses (4xx - 6xx class) SIP responses. These responses indicate that the request was not successful due to client, server, or global errors. This method is empty by default and must be overridden in subclasses to implement custom behavior.
Parameters:
resp: Represents the incoming SIP error response.
Exceptions:
javax.servlet.ServletException: Thrown if an exception interferes with the servlet's normal operation.
java.io.IOException: Thrown if an input or output exception occurs during processing.

Utility Methods

The SipServlet class provides two log methods to enable flexible logging. These methods are inherited from the javax.servlet.GenericServlet class and are tailored to handle different levels of detail in log messages.

log
public void log(java.lang.String message)
Logs a simple message to the servlet container’s log file or logging framework. This is the most basic form of logging and is used when there’s no need to include exception details. 
Parameter:
message: A String that specifies the log message.

log
log(String message, Throwable t)
Logs a detailed message along with an exception or error stack trace.
Parameters:
message: A String that describes the error or provides context.
t: A Throwable (e.g., Exception, Error) representing the error or exception to be logged.

Methods inherited from class javax.servlet.GenericServlet:
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, init.

Methods inherited from class java.lang.Object:
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait.

These methods are not overridden in this implementation.

Developers can use the @SipServlet annotation to define a SIP servlet without relying on the sip.xml deployment descriptor. This annotation simplifies configuration and makes the codebase easier to maintain (no need to rely on external *.xml files)