ServletInputStream getInputStream()
BufferedReader     getReader()

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:

• SDP (Session Description Protocol): A protocol to define multimedia sessions used between terminals. This protocol is defined in RFC2373.

• Presence Information: A message that describes presence information defined in CPIM.

• IM Messages: IM (instant message) body. User-input messages are stored in the message body.

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:

void   setContent(Object content, String contentType)
Object getContent()
byte[] getRawContent()

Like HTTP servlet containers, SIP servlet containers manage applications by servlet context (see Figure 2-6). Servlet contexts (applications) are normally archived in a WAR format and deployed in each application server.

Figure 2-6 Servlet Container and Servlet Context

A servlet context for a converged SIP and Web application can include multiple SIP servlets, HTTP servlets, and JSPs.

Converged application Server 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.

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 registrar is assigned all REGISTER methods.

 <servlet-mapping>
   <servlet-name>registrar</servlet-name>
   <pattern>
     <equal>
       <var>request.method</var>
       <value>REGISTER</value>
     </equal>
   </pattern>
 </servlet-mapping>

SIP messaging functions provided by a SIP servlet container are classified under the following types:

• Parsing received SIP messages.
• Delivering parsed messages to the appropriate SIP servlet.
• Sending SIP servlet-generated messages to the appropriate UA
• Automatically generating a response (such as “100 Trying").
• Automatically managing the SIP header field.

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.

• First SIP Request: When the SIP servlet container received a request that does not belong to any SIP session, it uses filter conditions in the sip.xml file (described in the previous section) to determine the target SIP servlet. Since the container creates a new SIP session when the initial request is delivered, any SIP requests within that SIP session received after that point are considered as subsequent requests.

  Note:

  Filtering should be done carefully. In Converged Application Server, when the received SIP message matches multiple SIP servlets, it is delivered only to any one SIP servlet.

  The use of additional criteria such as request parameters can be used to direct a request to a servlet.

• Subsequent SIP Request: When the SIP Servlet container receives a request that belongs to any SIP session, it delivers the request to a SIP Servlet associated with that session. Whether the request belongs to a session or not is determined using the SIP dialog ID.

  Each time a SIP Servlet processes messages, a lock is established by the container on the call ID. If a SIP Servlet is currently processing earlier requests for the same call ID when subsequent requests are received, the SIP Servlet container queues the subsequent requests. The queued messages are processed only after the Servlet has finished processing the initial message and has returned control to the SIP Servlet container.

  This concurrency control is guaranteed both in a single containers and in clustered environments. Application developers can code applications with the understanding that only one message for any particular call ID gets processed at a given time.

• SIP Response: When the received response is to a request that a SIP servlet proxied, the response is automatically delivered to the same servlet since its SIP session had been determined. When a SIP servlet sends its own request, you must first specify a servlet that receives a response in the SIP session. For example, if the SIP servlet sending a request also receives the response, the following handler setting must be specified in the SIP session.

  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:

Converged Application Server automatically execute the following response and retransmission processes:

• Sending “100 Trying": When Converged Application Server receives an INVITE request, it automatically creates and sends “100 Trying."
• Response to CANCEL: When Converged Application Server receives a CANCEL request, it executes the following processes if the request is valid.
  1. Sends a 200 response to the CANCEL request.
  2. Sends a 487 response to the INVITE request to be cancelled.
  3. Invokes a doCancel method on the SIP servlet. This allows the application to abort the process within the doCancel method, eliminating the need for explicitly sending back a response.
• Sends ACK to an error response to INVITE: When a 4xx, 5xx, or 6xx response is returned for INVITE that were sent by a SIP servlet, Converged Application Server automatically creates and sends ACK. This is because ACK is required only for a SIP sequence, and the SIP servlet does not require it.

  When the SIP servlet sends a 4xx, 5xx, or 6xx response to INVITE, it never receives ACK for the response.

• Retransmission process when using UDP: SIP defines that sent messages are retransmitted when a low-trust transport like UDP is used. Converged Application Server automatically retransmits according to the specification.

Applications typically do not need to explicitly set and see header fields in HTTP Servlet, as HTTP Servlet containers automatically manage fields such as Content-Length and Content-Type. SIP Servlet provides the same header management functions.

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.

JSR-359 defines the following utilities, which are available to SIP servlets:

1. SIP Session, Application Session
2. SIP Factory
3. Proxy
4. SipSessionsUtil
5. DnsResolver
6. TimerService
7. SipSecurity

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.

For SIP servlet POJOs, this is handled by the @SipServlet and @SipApplication annotations.

A SIP factory (SipFactory) is a factory class to create SIP Servlet-specific objects necessary for application execution. You can generate the following objects:

SipFactory is located in the servlet context attribute under the default name. You can retrieve it with the following code:

ServletContext context = getServletContext();
SipFactory factory =
    (SipFactory) context.getAttribute("javax.servlet.sip.SipFactory");

For SIP servlet POJOs, this functionality is handled by the @SipFactory annotation. The @SipFactory annotation can be used in place of a ServletContext lookup for the SipFactory from within a Servlet above. The injected SipFactory appears as sip/appname/SipFactory in the application-scoped JNDI tree, where the appname is the name of the application.

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:

• Recursive routing (recursive): When the destination of proxying returns a 3xx response, the request is proxied to the specified target.
• Record-Route setting: Sets a Record-Route header in the specified request.
• Parallel/Sequential (parallel): Determines whether forking is executed in parallel or sequentially.
• stateful: Determines whether proxying is transaction stateful. This parameter is not relevant because stateless proxy mode is deprecated in JSR-359.
• Supervising mode: In the event of the state change of proxying (response receipts), an application reports this.

For more information, see Forking SIP Requests.

A utility class providing additional support for converged HTTP/SIP applications and converged Java EE/SIP applications. This class can be accessed through the ServletContext parameter named javax.servlet.sip.SipSessionsUtil or it can be injected using the @Resource annotation. The injected SipSessionsUtil appears as sip/appname/SipSessionsUtil in the application-scoped JNDI tree, where the appname is the name of the application.

For more information, see the Java SIP Servlet API 2.0.

For information on the DnsResolver utility, see Annotation for DnsResolver Injection.

The @Resource annotation also can be used to inject an instance of the TimerService for scheduling timers. This annotation can replace the following ServletContext based lookup of the TimerService:

TimerService t = (TimerService) getServletContext().getAttribute(TIMER_SERVICE);

The injected TimerService appears as sip/appname/TimerService in the application-scoped JNDI tree, where the appname is the name of the application.

This annotation is used on a Servlet implementation class to specify security constraints to be enforced by the container on SIP protocol messages. The SIP servlet container will enforce these constraints on the annotated SIP servlet. The @SipSecurity annotation provides an alternative mechanism for defining access control constraints equivalent to those that could otherwise have been expressed declaratively via security-constraint elements in the portable deployment descriptor.

For information on using the @SipSecurity annotation see section 22.3.10.1 in JSR-359, https://jcp.org/en/jsr/detail?id=359.