|
||||||||||||||||||||||||||||||||||||||||||||||||||||||
Overview of SIP ServletsWhat is a SIP Servlet?The SIP Servlet API is a part of JAIN APIs and being standardized as JSR116 of JCP (Java Community Process). The SIP Servlet API version 1.0 was published in February, 2003. In this document, the term "SIP Servlet" is used to represent the API, and "SIP servlet" is used to represent an application created with the API. J2EE provides Java Servlet that is a main technology of building Web applications. Although Java Servlet is used only to develop HTTP protocol-based applications on a Web application server, it basically has functions as a generic API for server applications. SIP Servlet is defined as the generic servlet API with SIP-specific functions added.
SIP Servlet is very similar to HTTP Servlet, and HTTP servlet developers can soon get used to it. Also, the service level defined by both Servlets is very similar, you can easily design applications supporting both HTTP and SIP. List 1 shows an example of a simple SIP servlet. List 1: EchoServlet01.java package com.oki.sip.echo; import java.io.IOException; import javax.servlet.*; import javax.servlet.sip.*; public class EchoServlet01 extends SipServlet { protected void doMessage(SipServletRequest req) throws ServletException, IOException { SipServletResponse res = req.createResponse(200); res.send(); } } The above example shows a simple SIP servlet that sends back a 200 OK response to the SIP MESSAGE request. As you can see from the list, SIP Servlet and HTTP Servlet have many things in common:
However, there are several differences between SIP and HTTP servlets. A major difference comes from protocols. The next section describes these differences as well as features of SIP servlets. Differences from HTTP Servletsa. Multiple ResponsesYou might notice from the List 1 that the doMessage method has only one argument. In HTTP, a transaction consists of a pair of request and response, so arguments of a doXxx method specify a request (HttpServletRequest) and its response (HttpServletResponse). An application takes information such as parameters from the request to execute it, and returns its result in the body of the response. protected void doGet(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException For SIP, more than one response may be returned to a single request.
The above figure shows an example of a response to the INVITE request. In this example, the server sends back three responses 100, 180, and 200 to the single INVITE request. To implement such sequence, in SIP Servlet, only a request is specified in a doXxx method, and an application generates and returns necessary responses in an overridden method. Currently, SIP Servlet defines the following doXxx methods: protected void doInvite(SipServletRequest req); protected void doAck(SipServletRequest req); protected void doOptions(SipServletRequest req); protected void doBye(SipServletRequest req); protected void doCancel(SipServletRequest req); protected void doSubscribe(SipServletRequest req); protected void doNotify(SipServletRequest req); protected void doMessage(SipServletRequest req); protected void doInfo(SipServletRequest req); protected void doPrack(SipServletRequest req); b. Receiving ResponsesOne of the major features of SIP is that roles of a client and server are not fixed. In HTTP, Web browsers always send HTTP requests and receive HTTP responses: They never receive HTTP requests and send HTTP responses. In SIP, however, each terminal needs to have functions of both a client and server. For example, both of two SIP phones must call to the other and disconnect the call.
The above example indicates that a calling or disconnecting terminal acts as a client. In SIP, roles of a client and server can be changed in one dialog. This client function is called UAC (User Agent Client) and server function is called UAS (User Agent Server), and the terminal is called UA (User Agent). SIP Servlet defines methods to receive responses as well as requests. protected void doProvisionalResponse(SipServletResponse res); protected void doSuccessResponse(SipServletResponse res); protected void doRedirectResponse(SipServletResponse res); protected void doErrorResponse(SipServletResponse res); These doXxx response methods are not the method name of the request. They are named by the type of the response as follows:
Existence of methods to receive responses indicates that in SIP Servlet requests and responses are independently transmitted an application in different threads. Applications must explicitly manage association of SIP messages. An independent request and response makes the process slightly complicated, but enables you to write more flexible processes. Also, SIP Servlet allows applications to explicitly create requests. Using these functions, SIP servlets can not only wait for requests as a server (UAS), but also send requests as a client (UAC). c. Proxy FunctionsAnother function that is different from the HTTP protocol is "forking." Forking is a process of proxying one request to multiple servers simultaneously (or sequentially) and used when multiple terminals (operators) are associated with one telephone number (such as in a call center).
SIP Servlet provides a utility to proxy SIP requests for applications that have proxy functions. d. Message BodyAs the figure below, the structure of SIP messages is the same as HTTP.
HTTP is basically a protocol to transfer HTML files and images. Contents to be transferred are stored in the message body. HTTP Servlet defines stream manipulation-based API to enable sending and receiving massive contents. ServletRequest ServletInputStream getInputStream() BufferedReader getReader() ServletResponse ServletOutputStream getOutputStream() PrintWriter getWriter() int getBufferSize() void setBufferSize(int size) void resetBuffer() void flushBuffer() In SIP, however, only low-volume contents are stored in the message body since SIP is intended for real-time communication. Therefore, above methods are provided only for compatibility, and their functions are disabled. In SIP, contents stored in the body include:
Since the message body is in a small size, processing it in a streaming way increases overhead. SIP Servlet re-defines API to manipulate the message body on memory as follows: SipServletMessage void setContent(Object content, String contentType) Object getContent() byte[] getRawContent() Roles of a Servlet ContainerThis section describes major functions provided by SIP Servlet Engine as a SIP servlet container.
Application ManagementLike HTTP servlet containers, SIP servlet containers manage applications by servlet context (see Figure 6). Servlet contexts (applications) are normally archived in a WAR format and deployed in each application server. The method of deploying in application servers varies depending on your product. Refer to the documentation of your application server.
A servlet context for a converged SIP and Web application can include multiple SIP servlets, HTTP servlets, and JSPs. SIP Servlet Engine can deploy applications using the same method as the application server you use as the platform. However, if you deploy applications including SIP servlets, you need a SIP specific deployment descriptor (sip.xml) defined by SIP servlets. The table below shows the file structure of a general converged SIP and Web application.
Table 1: File Structure Example of Application
Information specified in the sip.xml file is similar to that in the web.xml except <servlet-mapping> setting that is different from HTTP servlets. In HTTP you specify a servlet associated with the file name portion of URL. But SIP has no concept of the file name. You set filter conditions using URI or the header field of a SIP request. The following example shows that a SIP servlet called "register" is assigned all REGISTER methods.
List 1: Filter Condition Example of sip.xml <servlet-mapping> <servlet-name>registrar</servlet-name> <pattern> <equal> <var>request.method</var> <value>REGISTER</value> </equal> </pattern> </servlet-mapping> Once deployed, lifecycle of the servlet context is maintained by the servlet container. Although the servlet context is normally started and shutdown when the server is started and shutdown, the system administrator can explicitly start, stop, and reload the servlet context. SIP MassagingSIP messaging functions provided by a SIP servlet container are classified under the following four types:
All SIP messages that a SIP servlet handles are represented as a SipServletRequest or SipServletResponse object. A received message is first parsed by the parser and then translated to one of these objects and sent to the SIP servlet container. A SIP servlet container receives the following three types of SIP messages, for each of which you determine a target servlet.
Filtering should be done carefully. In SIP Servlet Engine 3.0, when the received SIP message matches multiple SIP servlets, it is delivered only to any one SIP servlet.
SipServletRequest req = getSipFactory().createRequest(appSession, ...); req.getSession().setHandler(getServletName()); Normally, in SIP a "session" means a real-time session by RTP/RTSP. On the other hand, in HTTP Servlet a "session" refers to a way of relating multiple HTTP transactions. In this document, session-related terms are defined as follows:
SIP Servlet Engine automatically execute the following response and retransmission processes.
Mostly, applications do not need to explicitly set and see header fields In HTTP Servlet since HTTP servlet containers automatically manage these fields such as Content-Length and Content-Type. SIP Servlet also has the same header management function. In SIP, however, since important information about message delivery exists in some fields, these headers are not allowed to change by applications. Headers that can not be changed by SIP servlets are called "system headers." The table below lists system headers: Table 2: System Headers
Utility FunctionsSIP Servlet defines the following utilities that are available to SIP servlets:
SIP Session, Application Session As stated before, SIP Servlet provides a "SIP session" whose concept is the same as a HTTP session. In HTTP, multiple transactions are associated using information like Cookie. In SIP, this association is done with header information (Call-ID and tag parameters in From and To). Servlet containers maintain and manage SIP sessions. Messages within the same dialog can refer to the same SIP session. Also, For a method that does not create a dialog (such as MESSAGE), messages can be managed as a session if they have the same header information. SIP Servlet has a concept of an "application session," which does not exist in HTTP Servlet. An application session is an object to associate and manage multiple SIP sessions and HTTP sessions. It is suitable for applications such as B2BUA. In SIP Servlet Engine 3.0, HTTP sessions are not associated with application sessions. SIP Factory A SIP factory (SipFactory) is a factory class to create SIP Servlet-specific objects necessary for application execution. You can generate the following objects: Table 3: Objects Generated with SipFactory
SipFactory is located in the servlet context attribute under the default name. You can take this with the following code. ServletContext context = getServletContext(); SipFactory factory = (SipFactory) context.getAttribute("javax.servlet.sip.SipFactory"); Proxy Proxy is a utility used by a SIP servlet to proxy a request. In SIP, proxying has its own sequences including forking. You can specify the following settings in proxying with Proxy:
Last Modified:Tue Mar 16 11:12:04 AM JST 2004 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||
|