JSR-359 defines a standard method for creating SIP servlets using Java EE annotations in conjunction with POJOs, significantly reducing the amount of code required compared to the earlier 1.x API techniques. In addition, servlet descriptors such as web.xml and sip.xml are optional.

Example 2-1 illustrates a basic annotated SIP servlet POJO that handles a variety of SIP response and request methods.

import javax.inject.Inject;
import javax.servlet.sip.SipFactory;
import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.SipServletResponse;
import javax.servlet.sip.annotation.Ack;
import javax.servlet.sip.annotation.AnyMethod;
import javax.servlet.sip.annotation.Bye;
import javax.servlet.sip.annotation.ErrorResponse;
import javax.servlet.sip.annotation.Invite;
import javax.servlet.sip.annotation.SipApplication;
import javax.servlet.sip.annotation.SipServlet;
import javax.servlet.sip.annotation.SuccessResponse;
import java.io.IOException;

@SipServlet(loadOnStartup = 1)
public class CallHandler {

  @Inject SipFactory sipFactory;

  @Invite
  public void handleInvite(SipServletRequest request) throws IOException {
    // Handle a SIP invite on an incoming Request...
  }

  @Ack
  public void handleAck(SipServletRequest request) throws IOException {
    // Handle a SIP ACK on an incoming Request...
  }

  @AnyMethod
  public void handleAllRequests(SipServletRequest request) throws IOException {
    // Handle any generic method on an incoming Request...
  }

  @AnyMethod
  public void handleAllResponses(SipServletResponse resp) throws IOException {
    // Handle any other SIP response for any other method...
  }

  @SuccessResponse
  @ErrorResponse
  @Bye
  public void handleByeResponse(SipServletResponse resp) throws IOException {
    // Handle SIP responses in the case of success, error, or BYE...
  }
 
}

In Example 2-1, the class CallHandler imports the necessary SIP annotation libraries, and is itself annotated with @SipServlet indicating that it is a SIP Servlet. CallHandler then exposes the following public methods:

• handleInvite(request): Annotated with @Invite, handles any incoming SIP INVITE requests.

• handleAck(request): Annotated with @Ack, handles any incoming SIP ACK request.

• handleAllRequests(request): Annotated with @AnyMethod, handles any incoming SIP request method that is not an ACK or an INVITE. The methods annotated with @Invite and @Ack are more specific, and thus have higher precedence than @AnyMethod.

• handleAllResponses(response): Annotated with @AnyMethod, handles any incoming SIP response. Handles any responses other than success, error, or BYE which are handled by the more specifically annotated handleByeResponse().

• handleByeResponse(response): Annotated with @SuccessResponse, @ErrorResponse, and @Bye, and therefore handles any SIP success, error responses, or BYE. Any other SIP responses are handled by general handleAllResponses().

For more information on developing SIP servlet POJOs, see SIP Servlet POJOs.

Example 2-2 shows an example of a simple SIP servlet using the legacy 1.x SIP Java API.

package oracle.example.simple;
import java.io.IOException;
import javax.servlet.*;
import javax.servlet.sip.*;

public class SimpleSIPServlet extends SipServlet {
    protected void doMessage(SipServletRequest req)
       throws ServletException, IOException
    {
       SipServletResponse res = req.createResponse(200);
       res.send();
    }
}

1. Servlets must inherit the base class provided by the API. HTTP servlets must inherit HttpServlet, and SIP servlets must inherit SipServlet.

2. Methods doXxx must be overridden and implemented. HTTP servlets have doGet/doPost methods corresponding to GET/POST methods. Similarly, SIP servlets have doXxx methods corresponding to the method name (in Example 2-2, the MESSAGE method). Application developers override and implement necessary methods.

3. The life cycle and management methods (init, destroy) of SIP Servlet are exactly the same as HTTP Servlet. Manipulation of sessions and attributes is also the same.