javax.servlet.sip

Class SipServlet

java.lang.Object

javax.servlet.GenericServlet

javax.servlet.sip.SipServlet

All Implemented Interfaces:

Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

public abstract class SipServlet
extends javax.servlet.GenericServlet

Provides an abstract class to be subclassed to create a SIP servlet.

This class receives incoming messages through the service method. This method calls doRequest or doResponse for incoming requests and responses, respectively. These two methods in turn dispatch on request method or status code to one of the following methods:

• doInvite - for SIP INVITE requests
• doAck - for SIP ACK requests
• doOptions - for SIP OPTIONS requests
• doBye - for SIP BYE requests
• doCancel - for SIP CANCEL requests
• doRegister - for SIP REGISTER requests
• doSubscribe - for SIP SUBSCRIBE requests
• doNotify - for SIP NOTIFY requests
• doMessage - for SIP MESSAGE requests
• doInfo - for SIP INFO requests
• doPrack - for SIP PRACK requests
• doUpdate - for SIP UPDATE requests
• doRefer - for SIP REFER requests
• doPublish - for SIP PUBLISH requests
• doProvisionalResponse - for SIP 1xx informational responses except 100.
• doSuccessResponse - for SIP 2xx responses
• doRedirectResponse - for SIP 3xx responses
• doErrorResponse - for SIP 4xx, 5xx, and 6xx responses

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.

Subclasses of SipServlet will usually override one or more of these methods.

See Also:

RFC 2976, The SIP INFO Method, RFC 3262, Reliability of Provisional Responses in the Session Initiation Protocol (SIP), RFC 3265, Session Initiation Protocol (SIP)-Specific Event Notification, SIP Extensions for Instant Messaging, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static String	DNS_RESOLVER The string "javax.servlet.sip.DnsResolver".
static String	OUTBOUND_ADDRESSES The string "javax.servlet.sip.outboundAddresses".
static String	OUTBOUND_INTERFACES The string "javax.servlet.sip.outboundInterfaces".
static String	PRACK_SUPPORTED Deprecated. in favor of using the "javax.servlet.sip.supported" attribute
static String	SIP_APPLICATIONSESSION_CREATE The string "javax.servlet.sip.ApplicationSession.create".
static String	SIP_APPLICATIONSESSION_ID The string "javax.servlet.sip.ApplicationSessionId".
static String	SIP_APPLICATIONSESSION_KEY The string "javax.servlet.sip.ApplicationSessionKey".
static String	SIP_FACTORY The string "javax.servlet.sip.SipFactory".
static String	SIP_SESSIONS_UTIL The string "javax.servlet.sip.SipSessionsUtil".
static String	SUPPORTED The string "javax.servlet.sip.supported".
static String	SUPPORTED_RFCs The string "javax.servlet.sip.supportedRfcs".
static String	TIMER_SERVICE The string "javax.servlet.sip.TimerService".

Constructor Summary

Constructors

Constructor and Description
SipServlet()

Method Summary

Methods

Modifier and Type	Method and Description
protected void	doAck(SipServletRequest req) Invoked by the server (via the service method) to handle incoming ACK requests.
protected void	doBranchResponse(SipServletResponse resp) Invoked by the server to handle intermediate final responses only if this Servlet behaves as a proxy.
protected void	doBye(SipServletRequest req) Invoked by the server (via the service method) to handle incoming BYE requests.
protected void	doCancel(SipServletRequest req) Invoked by the server (via the service method) to handle incoming CANCEL requests.
protected void	doErrorResponse(SipServletResponse resp) Invoked by the server (via the doResponse method) to handle incoming 4xx - 6xx class responses.
protected void	doInfo(SipServletRequest req) Invoked by the server (via the service method) to handle incoming INFO requests.
protected void	doInvite(SipServletRequest req) Invoked by the server (via the service method) to handle incoming INVITE requests.
protected void	doMessage(SipServletRequest req) Invoked by the server (via the service method) to handle incoming MESSAGE requests.
protected void	doNotify(SipServletRequest req) Invoked by the server (via the service method) to handle incoming NOTIFY requests.
protected void	doOptions(SipServletRequest req) Invoked by the server (via the service method) to handle incoming OPTIONS requests.
protected void	doPrack(SipServletRequest req) Invoked by the server (via the service method) to handle incoming PRACK requests.
protected void	doProvisionalResponse(SipServletResponse resp) Invoked by the server (via the doResponse method) to handle incoming 1xx class responses except 100.
protected void	doPublish(SipServletRequest req) Invoked by the server (via the service method) to handle incoming PUBLISH requests.
protected void	doRedirectResponse(SipServletResponse resp) Invoked by the server to notify the servlet of incoming 3xx class responses.
protected void	doRefer(SipServletRequest req) Invoked by the server (via the service method) to handle incoming REFER requests.
protected void	doRegister(SipServletRequest req) Invoked by the server (via the service method) to handle incoming REGISTER requests.
protected void	doRequest(SipServletRequest req) Invoked to handle incoming requests.
protected void	doResponse(SipServletResponse resp) Invoked to handle incoming responses.
protected void	doSubscribe(SipServletRequest req) Invoked by the server (via the service method) to handle incoming SUBSCRIBE requests.
protected void	doSuccessResponse(SipServletResponse resp) Invoked by the server (via the doResponse method) to handle incoming 2xx class responses.
protected void	doUpdate(SipServletRequest req) Invoked by the server (via the service method) to handle incoming UPDATE requests.
void	log(String message) Writes the specified message to a servlet log file.
void	log(String message, Throwable t) Writes an explanatory message and a stack trace for a given Throwable exception to the servlet log file.
void	service(javax.servlet.ServletRequest req, javax.servlet.ServletResponse resp) Invoked to handle incoming SIP messages: requests or responses.

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

Field Detail

SIP_FACTORY

public static final String SIP_FACTORY

The string "javax.servlet.sip.SipFactory". This is the name of the ServletContext attribute whose value is an instance of the SipFactory interface.

See Also:

SipFactory, Constant Field Values

TIMER_SERVICE

public static final String TIMER_SERVICE

The string "javax.servlet.sip.TimerService". This is the name of the ServletContext attribute whose value is an instance of the TimerService interface.

See Also:

TimerService, Constant Field Values

DNS_RESOLVER

public static final String DNS_RESOLVER

The string "javax.servlet.sip.DnsResolver". This is the name of the ServletContext attribute whose value is an instance of the DnsResolver interface.

Since:

2.0

See Also:

DnsResolver, Constant Field Values

SUPPORTED

public static final String SUPPORTED

The string "javax.servlet.sip.supported". This is the name of the ServletContext attribute whose value is a List containing the names of SIP extensions supported by the container.

See Also:

Constant Field Values

SUPPORTED_RFCs

public static final String SUPPORTED_RFCs

The string "javax.servlet.sip.supportedRfcs". This is the name of the ServletContext attribute whose value is a List containing the RFC numbers represented as Strings of SIP RFCs supported by the container. For e.g., if the container supports RFC 3261, RFC 3262 and RFC 3265, the List associated with this attribute should contain the Strings "3261", "3262" and "3265".

Since:

1.1

See Also:

Constant Field Values

OUTBOUND_INTERFACES

public static final String OUTBOUND_INTERFACES

The string "javax.servlet.sip.outboundInterfaces". This is the name of the ServletContext attribute whose value is a list of SipURI objects which represent the available outbound interfaces for sending SIP requests. On a multihomed machine, a specific outbound interface can be selected for sending requests by calling the the SipSession.setOutboundInterface(java.net.InetSocketAddress) or Proxy.setOutboundInterface(java.net.InetSocketAddress) with an available interface address chosen from this list.

Since:

1.1

See Also:

Constant Field Values

OUTBOUND_ADDRESSES

public static final String OUTBOUND_ADDRESSES

The string "javax.servlet.sip.outboundAddresses". This is the name of the ServletContext attribute whose value is a list of InetAddress objects which represent the available outbound interfaces for sending SIP requests. On a multihomed machine, a specific outbound interface can be selected for sending requests by calling the the SipSession.setOutboundInterface(java.net.InetSocketAddress) or Proxy.setOutboundInterface(java.net.InetSocketAddress) with an available interface address chosen from this list.

Since:

2.0

See Also:

Constant Field Values

SIP_SESSIONS_UTIL

public static final String SIP_SESSIONS_UTIL

The string "javax.servlet.sip.SipSessionsUtil". This is the name of the ServletContext attribute whose value is the @{link Sessions} utility class providing support for converged SIP/HTTP applications.

Since:

1.1

See Also:

Constant Field Values

PRACK_SUPPORTED

public static final String PRACK_SUPPORTED

Deprecated. in favor of using the "javax.servlet.sip.supported" attribute

The string "javax.servlet.sip.100rel". This is the name of the ServletContext attribute whose value suggests whether the container supports the 100rel extension i.e. RFC 3262.

Since:

1.1

See Also:

Constant Field Values

SIP_APPLICATIONSESSION_KEY

public static final String SIP_APPLICATIONSESSION_KEY

The string "javax.servlet.sip.ApplicationSessionKey". This is the execution context property to indicate ID of the Sip Application Session, to be used as the context of the Managed Task, when it is executed.

Since:

2.0

See Also:

Constant Field Values

SIP_APPLICATIONSESSION_ID

public static final String SIP_APPLICATIONSESSION_ID

The string "javax.servlet.sip.ApplicationSessionId". This is the execution context property to indicate sip application key of the Sip Application Session, to be used as the context of the Managed Task, when it is executed.

Since:

2.0

See Also:

Constant Field Values

SIP_APPLICATIONSESSION_CREATE

public static final String SIP_APPLICATIONSESSION_CREATE

The string "javax.servlet.sip.ApplicationSession.create". This is the execution context property to indicate that the container creates a new Sip Application Session, to be used as the context of the Managed Task, when it is executed.

Since:

2.0

See Also:

Constant Field Values

Constructor Detail

SipServlet

public SipServlet()

Method Detail

service

public void service(javax.servlet.ServletRequest req,
           javax.servlet.ServletResponse resp)
             throws javax.servlet.ServletException,
                    IOException

Invoked to handle incoming SIP messages: requests or responses. Exactly one of the arguments is null: if the event is a request the response argument is null, and vice versa, if the event is a response the request argument is null.

This method dispatched to doRequest() or doResponse() as appropriate. Servlets will not usually need to override this method.

Specified by:

service in interface javax.servlet.Servlet

Specified by:

service in class javax.servlet.GenericServlet

Parameters:

req - the request to handle, or null if the triggering event was an incoming response

resp - incoming response or null if the triggering event was an incoming request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doRequest

protected void doRequest(SipServletRequest req)
                  throws javax.servlet.ServletException,
                         IOException

Invoked to handle incoming requests. This method dispatched requests to one of the doXxx methods where Xxx is the SIP method used in the request. Servlets will not usually need to override this method.

Parameters:

req - represents the incoming SIP request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doInvite

protected void doInvite(SipServletRequest req)
                 throws javax.servlet.ServletException,
                        IOException

Invoked by the server (via the service method) to handle incoming INVITE requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP INVITE request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doAck

protected void doAck(SipServletRequest req)
              throws javax.servlet.ServletException,
                     IOException

Invoked by the server (via the service method) to handle incoming ACK requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP ACK request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doOptions

protected void doOptions(SipServletRequest req)
                  throws javax.servlet.ServletException,
                         IOException

Invoked by the server (via the service method) to handle incoming OPTIONS requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP OPTIONS request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doBye

protected void doBye(SipServletRequest req)
              throws javax.servlet.ServletException,
                     IOException

Invoked by the server (via the service method) to handle incoming BYE requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP BYE request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doCancel

protected void doCancel(SipServletRequest req)
                 throws javax.servlet.ServletException,
                        IOException

Invoked by the server (via the service method) to handle incoming CANCEL requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP CANCEL request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doRegister

protected void doRegister(SipServletRequest req)
                   throws javax.servlet.ServletException,
                          IOException

Invoked by the server (via the service method) to handle incoming REGISTER requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP REGISTER request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doSubscribe

protected void doSubscribe(SipServletRequest req)
                    throws javax.servlet.ServletException,
                           IOException

Invoked by the server (via the service method) to handle incoming SUBSCRIBE requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP SUBSCRIBE request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doNotify

protected void doNotify(SipServletRequest req)
                 throws javax.servlet.ServletException,
                        IOException

Invoked by the server (via the service method) to handle incoming NOTIFY requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP NOTIFY request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doMessage

protected void doMessage(SipServletRequest req)
                  throws javax.servlet.ServletException,
                         IOException

Invoked by the server (via the service method) to handle incoming MESSAGE requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP MESSAGE request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doInfo

protected void doInfo(SipServletRequest req)
               throws javax.servlet.ServletException,
                      IOException

Invoked by the server (via the service method) to handle incoming INFO requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP INFO request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doPrack

protected void doPrack(SipServletRequest req)
                throws javax.servlet.ServletException,
                       IOException

Invoked by the server (via the service method) to handle incoming PRACK requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP PRACK request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doUpdate

protected void doUpdate(SipServletRequest req)
                 throws javax.servlet.ServletException,
                        IOException

Invoked by the server (via the service method) to handle incoming UPDATE requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP UPDATE request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

Since:

1.1

doRefer

protected void doRefer(SipServletRequest req)
                throws javax.servlet.ServletException,
                       IOException

Invoked by the server (via the service method) to handle incoming REFER requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP REFER request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

Since:

1.1

doPublish

protected void doPublish(SipServletRequest req)
                  throws javax.servlet.ServletException,
                         IOException

Invoked by the server (via the service method) to handle incoming PUBLISH requests.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

req - represents the incoming SIP PUBLISH request

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

Since:

1.1

doResponse

protected void doResponse(SipServletResponse resp)
                   throws javax.servlet.ServletException,
                          IOException

Invoked to handle incoming responses. This method dispatches responses to one of the doProvisionalResponse(), doSuccessResponse(), doBranchResponse(), doRedirectResponse() or doErrorResponse().

Intermediate final responses received on a ProxyBranch are dispatched to doBranchResponse(javax.servlet.sip.SipServletResponse). To handle such responses override the doBranchResponse. Servlets will not usually need to override this method.

Parameters:

resp - the response object

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

See Also:

SipServletResponse.isBranchResponse()

doProvisionalResponse

protected void doProvisionalResponse(SipServletResponse resp)
                              throws javax.servlet.ServletException,
                                     IOException

Invoked by the server (via the doResponse method) to handle incoming 1xx class responses except 100.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

resp - the response object

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doSuccessResponse

protected void doSuccessResponse(SipServletResponse resp)
                          throws javax.servlet.ServletException,
                                 IOException

Invoked by the server (via the doResponse method) to handle incoming 2xx class responses.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

resp - the response object

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doRedirectResponse

protected void doRedirectResponse(SipServletResponse resp)
                           throws javax.servlet.ServletException,
                                  IOException

Invoked by the server to notify the servlet of incoming 3xx class responses.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

resp - the response object

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doErrorResponse

protected void doErrorResponse(SipServletResponse resp)
                        throws javax.servlet.ServletException,
                               IOException

Invoked by the server (via the doResponse method) to handle incoming 4xx - 6xx class responses.

The default implementation is empty and must be overridden by subclasses to do something useful.

Parameters:

resp - the response object

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

doBranchResponse

protected void doBranchResponse(SipServletResponse resp)
                         throws javax.servlet.ServletException,
                                IOException

Invoked by the server to handle intermediate final responses only if this Servlet behaves as a proxy.

The default implementation is empty and must be overridden by subclasses to handle intermediate final responses received on a ProxyBranch.

Parameters:

resp - the response object

Throws:

javax.servlet.ServletException - if an exception occurs that interferes with the servlet's normal operation

IOException - if an input or output exception occurs

log

public void log(String message)

Writes the specified message to a servlet log file. See {link ServletContext#log(String)}.

Overrides:

log in class javax.servlet.GenericServlet

Parameters:

message - a String specifying the message to be written to the log file

log

public void log(String message,
       Throwable t)

Writes an explanatory message and a stack trace for a given Throwable exception to the servlet log file. See ServletContext.log(String, Throwable).

Overrides:

log in class javax.servlet.GenericServlet

Parameters:

message - a String that describes the error or exception

t - the java.lang.Throwable error or exception