Category: Oracle SIP server

Oracle Communication Application Server ( OCAS)

Back in 2010 , there was a very resilient SIP server called BEA weblogic , essentially used to write B2BUA ( back to back user agent application ) using SIP servlets for SIP based call flows . It was later acquired by Oracle and termed as Oracle Weblogic , then OCAS – Oracle Communication application Server and now Oracle Communications Evolved Application Server (v7.1) .

This article describes what is OCAS and some applications that can be build over it . OCAS is Java EE-SIP-IMS application server.  It uses  SIP Servlet 2.0 built on Java EE 7  containing  concurrent session management, web sockets, CDI interface , POJO and
standard JSON, XML, JAX, JMS interfaces. Also 3GPP ISC (SIP), and Sh/Ro/Rf (Diameter).

Converged Web and JEE SIP Servlets 

OCAS is a Converged Web-telecom application container based on SIP Servlet, IMS, Java EE, Diameter, JSR 309 Media Server Control and Web Services . It can host IP-based, communication-enabled applications.

ocas

It is said to be a converged application server as it can host both web and sip project and even a hybrid project of both such as web page with click to dial options ( customer care ) , IPTV based web telecom ,  VoIP,  locations/ Registrar ,  UCC Unified Communicator an Collaborator , Rich CommunicationServices (RCS) including Voice over LTE (VoLTE), SIP OPTIONS, Presence, Instant Messaging (SIMPLE) , MSRP, XDMS, and media servers , multimedia conferencing, SIP/IMS-based call control etc.

Images are from Oracle sites

Screen Shot 2018-09-28 at 9.55.53 PM

Converged container-developer platform supporting modern tools such as Eclipse and programming techniques based on Java 8 (POJOs, Annotations, CDI).

API support includes  – SIP Servlet API (JSR 289) , Service Foundation Toolkit API  , Media server API , Diameter API , Converged Load Balancer API , JEE API

Scaling 

Application can be build once and run anywhere since build on open source tools and components . Additionally OCAS supports Function virtualization ( VNF)  can be integrated with NFV ( network function virtualization ) for automatic scaling and being hardware agnostic  in terms of computer , storage and network . This makes it suited for large scale deployment such as CSP ( communication Service Providers ) or Enterprise Comm Agents .

Standards and Platforms Support

  • SIP Servlet 1.0, 1.1, & 2.0
  • Java EE 7 , Java SE 8
  • Media
  • Web Sockets
  • JSR 116 & 289 & 359
  • Oracle WLS 12.1.3
  • JDK 1.8.0_31
  • JSR 309 , JSR 359
  • Telecom 3GPP IMS
  • IETF SIP
  • Diameter
    Release 11: 3GPP TS 23.228, 24.229,29.328
  • RFC 3251,3588,2543,3262,3515 ,3903,3311,61,41,5626
  • 3GPP TS 32.299

Operating systems –  Oracle Solaris 11 , Linux , Windows 7(64 bit) , HP-UX
Oracle 6+, Redhat

Virtual Machines – M Java Virtual Machine , Oracle Java VM, HP JVP, Oracle Virtual Machine

Service Creation Environment on Eclipse for SIP servlets and Debugging

SCE provides tools for building a Converged Application Project which may includes the following facets:
Dynamic Web Module
Java
JavaScript
Oracle Communication Converged Application Extensions, including:
– SIP Servlet
– SFT Communication Bean
Oracle WebLogic Web Application Extensions

It can also have standard JRE resources, system library files, such as sft-communication-api.jar and sipservlet.jar, as well as sft.xml, sip.xml, and web.xml deployment descriptor files. With this we can create SFT Communication Beans and SIP Servlets along with standard HTTP Servlets, JPSs, static files, and EJB-based classes. For Diameter applications enable the facet.

Register Sip Servlet Handler

import javax.servlet.ServletException ;
import javax.servlet.sip.SipApplicationSessionEvent;
import javax.servlet.sip.SipApplicationSessionListener;
import javax.servlet.sip.SipServlet ;
import javax.servlet.sip.SipServletContextEvent;
import javax.servlet.sip.SipServletListener;
import javax.servlet.sip.SipServletRequest ;

public class SipRegistrarServlet extends SipServlet {

public void init() throws ServletException {
   super.init(); 
   logger.debug("SIP Registrar Servlet..");
}

// Override SipServlet's default implementation.
@Override
public void doRegister(SipServletRequest request)
throws ServletException 
{
   // create instance of auitheticator class
   SipAuthenticator authenticator = SipAutheticatorFactory.getInstance();
   try{
       autheticate(authenticator, request);
       // Call the registration service 
       SipRegistrarService.processRegister(request);
   }
   catch (Exception e){
      // Perform Logging
   }
}
}

In most cases, converged applications are deployed as SAR or WAR files. However, you can choose to output to an EAR file if your project contains both SIP and enterprise JavaBean components. Target environment can be Oracle WebLogic Server 11gR1 (10.3.6). Environment variables like JAVA_HOME and BEA_HOME need to be set .

SIP Deployment Descriptor file is sip.xml . It can contain filter for sip request types that this application will handle . for example only to handle register

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

Web deployment descriptions are in web.xml

Ant build file is build.xml

Sample Servlet for handling message requests and responding 200 ok

import java.io.IOException;
import javax.servlet.*;
import javax.servlet.sip.*;
public class MessageServletApp extends SipServlet {
protected void doMessage(SipServletRequest req)
throws ServletException, IOException
{
SipServletResponse res = req.createResponse(200);
res.send();
}
}

Templates

SCE provides wizards ( SIP Servlet , SIP Listener , CommunicationBean )and templates for creating a variety of SIP and converged application types.

SIP servlets templates

Parent class to be extended is javax.servlet.sip.SipServlet

  1. SIP Proxy – providing routing capabilities and performing user authentication, accounting, registration, and security.
  2. B2BUA / back-to-back user agent – can act as both a user agent client and server. Uses the helper class, javax.servlet.sip.B2buaHelper
  3. Subscribe UAS – subscribes to a User Agent Server (UAS).
  4. Invite UAS – initiates communication sessions between UA peers.

After template selection , the wizard populates the new class with the stub methods appropriate for the type of SIP servlet . Therafter programmer can put their custom routing logic / business logic inside the functions .

doXXX methods of SIP servlets

  • 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);

doXXX reponses

  • protected void doProvisionalResponse(SipServletResponse res);
  • protected void doSuccessResponse(SipServletResponse res);
  • protected void doRedirectResponse(SipServletResponse res);
  • protected void doErrorResponse(SipServletResponse res);

Generic SIP servlet acting as adapter for all request types

import javax.servlet.ServletException;
import javax.servlet.sip.Address;
import javax.servlet.sip.SipApplicationSession;
import javax.servlet.sip.SipApplicationSessionEvent;
import javax.servlet.sip.SipApplicationSessionListener;
import javax.servlet.sip.SipFactory;
import javax.servlet.sip.SipServlet;
import javax.servlet.sip.SipServletContextEvent;
import javax.servlet.sip.SipServletListener;
import javax.servlet.sip.SipServletMessage;
import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.SipServletResponse;
import javax.servlet.sip.SipSession;
import javax.servlet.sip.SipSessionsUtil;
import javax.servlet.sip.TimerService;

public class SipCustomServlet extends SipServlet implements SipServletListener,
SipApplicationSessionListener
{


public void init() throws ServletException
{
super.init();
SipFactory sipFactory = (SipFactory) getServletContext().getAttribute( "javax.servlet.sip.SipFactory");
SipSessionsUtil sipSessionsUtil = (SipSessionsUtil)getServletContext().getAttribute( "javax.servlet.sip.SipSessionsUtil");
SessionTimerHandler.initializeSessionTimers((TimerService) getServletContext().getAttribute("javax.servlet.sip.TimerService"));
}

/** This is the entry point for all SIP Requests received by the servlet
* @see javax.servlet.sip.SipServlet#doRequest(javax.servlet.sip.SipServletRequest)
*/
protected void doRequest(SipServletRequest req) throws ServletException, IOException
{

if( ! serverStatus.isActive()){
SipServletResponse resp = req.createResponse(503, "Server Not Active");
sendResponse(resp);
return;
}

if (req.getMethod().equals("SUBSCRIBE"))
{
eventService.doSubscribe(req);
return;
}
else if (req.getMethod().equals("NOTIFY"))
{
String eventHeader = req.getHeader("Event");
// perform business logic 
eventService.doNotify(req);
return;
}

if (req.getMethod().equals("OPTIONS"))
{
SipServletResponse resp = null;

if(check some cond){
// send forbidden
resp = req.createResponse(403);
}
else
{
// send success
resp = req.createResponse(200);
}

sendResponse(resp);
return;
}

if (req.getMethod().equalsIgnoreCase("PUBLISH"))
{
PublishHandler handler = PublishHandler.getInstance();
handler.processPublish(req);
return;
}

doRequestInvite(req);
}

 

SIP Listener Wizard

listens for certain types of SIP-specific events, and typically performs some processing action in response to the event. For this select at least one application event to listen for. The available events are standard SIP-specified events, and include application events, session events, errors, timer events, and initialization events.

SFT Communication Bean Wizard

performs the functions of a SIP or HTTPservlet while hiding the complexities of SIP and communication protocol programming. CommunicationBeans use annotations to encapsulate common functions or roles fulfilled by communication applications. Instead of specifying the code that performs the function, you simply add the annotation to the source file. The SFT framework expands the annotation to the appropriate code.

Add methods to your communication bean that listen for specific events as
follows:

Step1 : From the Event Type list, choose the event category from these options:
CommunicationEvent, ParticipantEvent, or ProtocolEvent.

Step 2 : From the Event menu, choose the specific event on which you want the method to listen. The options vary depending on the event type. For instance, for ProtocolEvent, you can choose from these specific events: REQUESTRECEIVED, REQUESTSENT, RESPONSERECEIVED, or RESPONSESENT.

Step 3 : Optionally, modify the default priority for the method, 100.

Automatic Processes

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 WebLogic Communications 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.
  • Sends ACK to an error response to INVITE
  • Retransmission process when using UDP

System Headers

These cannot be changed by sip servlets applications and they are used for holding critical info about message delivery

  • Call-ID – ID information to associate multiple SIP messages as Call.
  • From, To – Information on the sender and receiver of the SIP request (SIP, URI, etc.). tag parameters are given by the servlet container.
  • CSeq – Sequence numbers and method names.
  • Via – Contains a list of servers the SIP message passed through , to keep track of the path to send a response to the request.
  • Record-Route – Route Used when the proxy server mediates subsequent requests.
  • Contact – Network information (such as IP address and port number) that is used for direct communication between terminals.
    Note : For a REGISTER message, 3xx, or 485 response, this is not considered as the system header and SIP servlets can directly edit the information.

SIP factory

Factory class to create SIP Servlet-specific objects for application execution. Class objects as URI, SipURI, Address , SipServletRequest , SipApplicationSession

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

Proxy Utility Class

settings for proxying are as follows

  • 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 JSR289.
  • Supervising mode: In the event of the state change of proxying (response receipts),an application reports this.

 

Changing SIP application session

Synchronous : Applications that need to read and update a session attribute in a transactional and synchronous manner must use the WlssAction API

Asynchronous : Applications that need to update a different SipApplicationSession while in the context of a locked SipApplicationSession can perform asynchronous updates using the WlssAsynchronousAction API.

Join header, defined in RFC 3911

Logically joins an existing SIP dialog with a new SIP dialog. Used in SIP Call Control and Multi-Party applications for enabling features such as Call Forwarding, Message Screening, and Call Center Monitoring.

Replaces header, defined in RFC 3891

Logically replaces an existing SIP dialog with a new SIP dialog. Used to enable features such as Attended Call Transfer and Call Pickup.

Note : To enable support for Join and Replaces headers, edit the entry for the –Dwlss.dialog.index.enabled=false command in the startWebLogic.sh script, and
set its value to true.

 

Testing , Debugging and Simulation

network components for simulation integration include – XDMS server , Diameter Ro server , Diameter Rf server , Diameter HSS server , Media server

Sipp plug-in for testing sip call routing logic

Media Server simulation  for applications as conferencing, audio prompting, and speech detection

Production Environment

For production scenarios, SIP applications are deployed to a cluster of Converged Application Server instances that form the engine tier cluster. A separate cluster of servers in the SIP data tier provides a replicated, in-memory database of the call states for active calls.

For production grade apps :

Use setAttribute() to Modify Session Data in “No-Call” Scope.
Send() Calls Are Buffered and transmitted in order after the SIP method returns
Mark SIP servlets as distributable in sip.xml also in the web.xml for a WAR file for depliying to cluster of enginer tier servers . Can be omitted for single non replicated deployment .

Non blocking , no threaded Applications

Converged Application Server architecture is a multi-threaded application server that manages resource allocation, concurrency, and thread synchronization for the modules it hosts. Since SIP servlet container automatically locks call state before calling doXXX methods. We shouldnt create new threads to avoid deadlock scenarios in doXXX methods ourselves.

String application data in session in a seriallizable way

Make use of Session attributes to store all application data of session .To serialize an object means to convert its state to a byte stream so that the byte stream can be reverted back into a copy of the object. Therefore to support in-memory replication of SIP application call states, all objects stored in the SIP Servlet session should be serializable. Also in a replicated configuration, engine tier servers maintains no cached information; all application data must be de-serialized from the session attribute available in SIP data tier servers.

 

 

Ref : 

Click to access e27707.pdf

https://www.ibm.com/support/knowledgecenter/en/SSAW57_liberty/com.ibm.websphere

https://www.jcp.org/en/jsr/detail?id=116wlp.nd.multiplatform.doc/ae/cwlp_sip_jsr289_overview.html