JBoss.orgCommunity Documentation
The Guide to the CDI Telco Framework
Copyright © 2009 Red Hat, Inc
Abstract
Mobicents is the first and only open source VoIP platform certified for JAIN SLEE 1.0 and SIP Servlets 1.1 compliance. Mobicents serves as a high-performance core for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSs) by leveraging J2EE to enable the convergence of data and video in Next-Generation Intelligent Network (NGIN) applications.
The Mobicents enables the composition of predefined Service Building Blocks (SBBs) such as Call-Control, Billing, User-Provisioning, Administration and Presence-Sensing. Out-of-the-box monitoring and management of Mobicents components is achieved through JMX Consoles. JSLEE allows popular protocol stacks such as SIP to be plugged in as Resource Adapters (RAs), and Service Building Blocks—which share many similarities with EJBs—allow the easy accommodation and integration of enterprise applications with end points such as the Web, Customer Relationship Management (CRM) systems and Service-Oriented Architectures (SOAs). The Mobicents is the natural choice for telecommunication Operations Support Systems (OSSs) and Network Management Systems (NMSs).
In addition to the telecommunication industry, the Mobicents is suitable for a variety of problem domains demanding an Event-Driven Architecture (EDA) for high-volume, low-latency signaling, such as financial trading, online gaming, (RFID) sensor network integration, and distributed control.
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:
To see the contents of the file
my_next_bestselling_novelin your current working directory, enter thecat my_next_bestselling_novelcommand at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.
Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to return to your X-Windows session.
The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:
File-related classes include
filesystemfor file systems,filefor files, anddirfor directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose from the main menu bar. Next, choose from the Character Map menu bar, type the name of the character in the Search field and click . The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the button. Now switch back to your document and choose from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.
Note the shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select from the sub-menu in the menu of the main menu bar' approach.
Mono-spaced Bold ItalicProportional Bold Italic
Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, type
sshat a shell prompt. If the remote machine isusername@domain.nameexample.comand your username on that machine is john, typessh john@example.com.The
mount -o remountcommand remounts the named file system. For example, to remount thefile-system/homefile system, the command ismount -o remount /home.To see the version of a currently installed package, use the
rpm -qcommand. It will return a result as follows:package.package-version-release
Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
When the Apache HTTP Server accepts requests, it dispatches child processes or threads to handle them. This group of child processes or threads is known as a server-pool. Under Apache HTTP Server 2.0, the responsibility for creating and maintaining these server-pools has been abstracted to a group of modules called Multi-Processing Modules (MPMs). Unlike other modules, only one module from the MPM group can be loaded by the Apache HTTP Server.
Two, commonly multi-line, data types are set off visually from the surrounding text.
Output sent to a terminal is set in Mono-spaced Roman and presented thus:
books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in Mono-spaced Roman but are presented and highlighted as follows:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object ref = iniCtx.lookup("EchoBean");
EchoHome home = (EchoHome) ref;
Echo echo = home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
Note
A note is a tip or shortcut or alternative approach to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring Important boxes won't cause data loss but may cause irritation and frustration.
Warning
A Warning should not be ignored. Ignoring warnings will most likely cause data loss.
CDI is the Java standard for dependency injection and contextual lifecycle management, led by Gavin King for Red Hat, Inc. and is a Java Community Process(JCP) specification that integrates cleanly with the Java EE platform. Any Java EE 6-compliant application server provides support for JSR-299 (even the web profile). It seemed a natural fit create a new framework based on CDI for the Telco world.
CDI-Telco-Framework (CTF) from Mobicents brings the power and productivity benefits of CDI into the Mobicents Sip Servlets platform providing dependency injection and contextual lifecycle management for converged HTTP/SIP applications. This new framework is intended to become a replacement for our previous Seam Telco Framework.
CTF mission statement is to simplify SipServlets development by introducing a component based programming model, ease of development by making available SIP utilities out of the box, and finally providing dependency injection and contextual lifecycle management to the SipServlets.
Container Support
CTF supports Mobicents Sip Servlets 1.x (JBoss AS5 - Tomcat 6.x) and Mobicents Sip Servlets 2.x (Tomcat 7.x).
Note
Support for JBoss AS5 is the same as in the Servlet environment (no EJB support, no transactions etc).
CTF consists of
Loose coupling and reusability of SIP Components across different applications are the most obvious advantages over the current SIP Servlets 1.1 specification. In addition to that, you get better integration with Java EE 6.
In the future we will try to explore further usage of this component-based approach to allow application developers to compose their applications in a new way and benefits from Modularization within a single application which should give additional performance improvements over SIP Servlets Application Routing and Chaining while you can still use the latter.
CTF starts by CDI enable your application providing all the advantages of CDI. While CTF can do more than that, just by adding the CTF listener in the web.xml or sip.xml of your application, you will be able to inject beans, produce beans and make use of the CDI contexts and scopes as you wish.
So for example, you can develop a sip registar module and make it available in the classpath of any application. From there you can inject the registar module and delegate registration request to it.
The SipRegistar could be like this:
@ApplicationScoped
public class SipRegistar {
private static Logger logger = Logger.getLogger(SipRegistar.class);
private static final String CONTACT_HEADER = "Contact";
@Produces HashMap<String, String> users = new HashMap<String, String>();
public void handleRegister(SipServletRequest req) throws ServletException,
IOException {
if(logger.isInfoEnabled()) {
logger.info("Received register request: " + req.getTo());
}
int response = SipServletResponse.SC_OK;
SipServletResponse resp = req.createResponse(response);
Address address = req.getAddressHeader(CONTACT_HEADER);
String fromURI = req.getFrom().getURI().toString();
int expires = address.getExpires();
if(expires < 0) {
expires = req.getExpires();
}
if(expires == 0) {
users.remove(fromURI);
if(logger.isInfoEnabled()) {
logger.info("User " + fromURI + " unregistered");
}
} else {
resp.setAddressHeader(CONTACT_HEADER, address);
users.put(fromURI, address.getURI().toString());
if(logger.isInfoEnabled()) {
logger.info("User " + fromURI +
" registered with an Expire time of " + expires);
}
}
resp.send();
}
}
Then in your application you can delegate all sip registration request to the SipRegistar module by doing:
@Inject
SipRegistar sipRegistar;
public void processRegister(@Observe @Register SipServletRequest req){
sipRegistar.handleRegister(req);
}
What is actually happening, is that CTF will replace the AnnotationProcessor, in the case of Tomcat 6.x, or InstanceManager in the case of JBoss Web (JBoss AS5) and Tomcat 7.x with CTF version of AnnotationProcessor or InstanceManager that allows CTF to bootstrap and enable your converged application for dependency injection and contextual lifecycle management.
Being the fundamental feature of the framework, CTF will "CDI-enable" a converged application providing:
CDI Telco Framework Features
Java EE 6 integration and providing a unified, contextual, programming model for Java Web and Converged Telco Applications.
Development of reusable (across different applications) sip modules and flexibility through the component based approach
Clean and simple programming model.
So CTF goes on step further to eliminate the Servlets layer from the SipServlet development. What that means is that the developer wont need to extend SipServlet anymore.
Pure Sip Servlets 1.1 specification programming model:
public class MySipMessagesHandlerClass extends SipServlet {
//override SipServlet methods to handle incoming SIP Messages
}
CTF programming model:
public class MySipMessagesHandlerClass {
//make use of annotations to specify which incoming SIP Messages your business is interested to handle
}
Note
CTF applications still need to define the app-name either through sip.xml or a package-info.java and of course to define the appropriate dar configuration so that the application can handle incoming SIP Messages.
During bootstrap CTF will register a sip servlet that main’s responsibility will be to propagate SIP request and responses in the form of CDI events. Therefore the developer will be able to do the following:
public class MySipMessagesHandlerClass {
public void handleRegister(@Observes @Register SipServletRequest req)
throws ServletParseException, IOException{
if(logger.isInfoEnabled()) {
logger.info("Received register request: " + req.getTo());
}
int response = SipServletResponse.SC_OK;
SipServletResponse resp = req.createResponse(response);
Address address = req.getAddressHeader(CONTACT_HEADER);
String fromURI = req.getFrom().getURI().toString();
int expires = address.getExpires();
if(expires < 0) {
expires = req.getExpires();
}
if(expires == 0) {
users.remove(fromURI);
if(logger.isInfoEnabled()) {
logger.info("User " + fromURI + " unregistered");
}
} else {
resp.setAddressHeader(CONTACT_HEADER, address);
users.put(fromURI, address.getURI().toString());
if(logger.isInfoEnabled()) {
logger.info("User " + fromURI +
" registered with an Expire time of " + expires);
}
}
resp.send();
}
In the above code snippet you will notice the CDI component doesn't need to extend SipServlet anymore and just need to specify 2 annotations @Observes and @Register to tell the framework that it is interested in REGISTER SIP Messages. This provide you with type safety, auto completion feature in the IDE and let you handle SIP Messages in any component be it from your application or from a third party CTF-enabled library or module included in your application.
Note
Future release will have a priority or weight mechanism so that 2 components interested in SIP REGISTER requests by example won't be able to process them at the same time or sequentially (except if the first one didn't make the message committed) and we still allow components composition from differents 3rd party modules.
CTF will propagate the following SIP request methods:
Table 4.1. CTF SIP Request Methods and Annotations
| SIP Request | CTF Observer |
|---|---|
| BYE | @Observes @Bye |
| ACK | @Observes @Ack |
| CANCEL | @Observes @Cancel |
| INFO | @Observes @Info |
| INVITE | @Observes @Invite |
| MESSAGE | @Observes @Message |
| NOTIFY | @Observes @Notify |
| OPTIONS | @Observes @Options |
| PRACK | @Observes @Prack |
| PUBLISH | @Observes @Publish |
| REFER | @Observes @Refer |
| REGISTER | @Observes @Register |
| SUBSCRIBE | @Observes @Subscribe |
| UPDATE | @Observes @Update |
To make use any of the CTF propagated request events, register the equivalent observer along with the SipServletRequest, that is:
public void handleUpdate (@Observes @Update SipServletRequest req){
}
and the following SIP responses:
Table 4.2. CTF SIP Responses and Annotations
| SIP Response | CTF Observer |
|---|---|
| SuccessResponse | @Observes @SuccessResponse |
| ErrorResponse | @Observes @ErrorResponse |
| RedirectResponse | @Observes @RedirectResponse |
| ProvisionalResponse | @Observes @ProvisionalResponse |
| BranchResponse | @Observes @BranchResponse |
To make use any of the CTF propagated response events, register the equivalent observer along with the SipServletResponse, that is:
public void handleErrorResponse (@Observes @ErrorResponse SipServletResponse resp) {
}
Note
As with all CDI observers, the name of the method is insignificant. The developer can choose any convenient method name as long as it uses the correct CTF Observer to receive the appropriate CTF event.
To ease the development of SIP Servlets applications, CTF goes all the way down and makes available for injection the following SIP elements:
Table 5.1. CTF Injectable SIP elements
| SIP Element | Injection |
|---|---|
| ServletContext | @Inject ServletContext servletContext; |
| SipFactory | @Inject SipFactory sipFactory; |
| TimerService | @Inject TimerService timerService; |
| SipSessionUtils | @Inject SipSessionsUtils sipSessionsUtils; |
| SipApplicationSession | @Inject SipApplicationSession sipApplicationSession; |
| SipSession | @Inject SipSession sipSession; |
You no longer need to retrieve SipFactory from JNDI (even though that was already made possible through the @Resource annotation) or SipSession from the request or the response. Just inject them in your application.
In order to get started with CTF, the only thing you have to do is to define few maven dependencies in your project and register the CTF listener in the sip.xml or web.xml or your application.
First dependency is Weld, the CDI reference implementation by JBoss and more specific the weld-servlet module.
<dependency>
<groupId>org.jboss.weld.servlet</groupId>
<artifactId>weld-servlet</artifactId>
<version>1.1.0.Final</version>
</dependency>
Second is the framework itself:
<dependency>
<groupId>org.mobicents.servlet.sip.weld</groupId>
<artifactId>sip-servlets-weld</artifactId>
<version>1.0.0.ALPHA1</version>
</dependency>
Note
Make sure you use the JBoss public maven repository:
<repository>
<id>jboss-public-repository-group</id>
<name>JBoss Public Maven Repository Group</name>
<url>https://repository.jboss.org/nexus/content/groups/public</url>
<layout>default</layout>
<releases>
<enabled>true</enabled>
<updatePolicy>never</updatePolicy>
</releases>
<snapshots>
<enabled>true</enabled>
<updatePolicy>never</updatePolicy>
</snapshots>
</repository>
The CTF listener that you have to register in your application is:
<listener> <listener-class> org.mobicents.servlet.sip.weld.environment.servlet.SipServletsWeldListener </listener-class> </listener>
To get the source code along with the examples:
checkout project from svn repository: svn co https://mobicents.googlecode.com/svn/trunk/frameworks/sip-servlets/cdi-telco-framework
In the folder core/sip-servlets-weld/ you will find the project responsible to bootstrap the framework, in order to build it: mvn clean compile install
In the folder core/sip-servlets-weld-jboss5/ you will find the the project responsible to bootstrap the framework for the JBoss AS5, in order to build it: mvn clean compile install
In the folder examples/ you will find the examples of the framework, build according to the notes of every example. The examples contain the following:
click2call-servlet3.0-cdi . The Click2Call application with asynchronous processing of request feature and CTF. Deploy to MSS 2.x Tomcat 7.0.8 only
click2call-servlet25-cdi. The Click2Call application with CTF. Deploy to Servlet 2.5 container such as MSS 1.x Tomcat 6.0.29. The example can be deployed to JBoss AS5 also, build using : mvn clean compile package -Pjboss5
SipRegistration.
SipRegistarClient - SIP registration example for java servlets 3.0. Deploy to MSS 2.x Tomcat 7.0.8 only.
SipRegistarClient25 - SIP registration example for java servlets 2.5. Deploy to MSS 1.x Tomcat 6.0.29. The example can be deployed to JBoss AS5 also, build using : mvn clean compile package -Pjboss5
To build issue mvn clean compile package for each project and deploy accordingly
Note
For JBoss AS5 special maven dependency needed for MSS 1.x JBoss AS5 version for the JBoss Weld dependency, that will be:
<dependency> <groupId>org.jboss.weld.servlet</groupId> <artifactId>weld-servlet</artifactId> <scope>runtime</scope> <classifier>jboss5</classifier> <version>1.1.0.Final</version> </dependency> <dependency> <groupId>org.mobicents.servlet.sip.weld</groupId> <artifactId>sip-servlets-weld-jboss5</artifactId> <version>1.0.0.ALPHA1</version> </dependency> </note>
CTF have been tested and verified working in the following MSS containers:
MSS 1.5 JBoss AS5
MSS 1.5 Tomcat 6.0.29
MSS 1.6-Trunk JBoss AS5
MSS 1.6-Trunk Tomcat 6.0.29
MSS 2.0-Trunk Tomcat 7.0.8
Summary of CTF dependencies to use
MSS 1.x on Tomcat 6.x
CDI
<dependency> <groupId>org.jboss.weld.servlet</groupId> <artifactId>weld-servlet</artifactId> <version>1.1.0.Final</version> </dependency>
CTF
<dependency> <groupId>org.mobicents.servlet.sip.weld</groupId> <artifactId>sip-servlets-weld</artifactId> <version>1.0.0.ALPHA1</version> </dependency>
MSS 1.x on JBoss AS5
CDI
<dependency> <groupId>org.jboss.weld.servlet</groupId> <artifactId>weld-servlet</artifactId> <scope>runtime</scope> <classifier>jboss5</classifier> <version>1.1.0.Final</version> </dependency>
CTF
<dependency> <groupId>org.mobicents.servlet.sip.weld</groupId> <artifactId>sip-servlets-weld-jboss5</artifactId> <version>1.0.0.ALPHA1</version> </dependency>
MSS 2.x on Tomcat 7.x
CDI
<dependency> <groupId>org.jboss.weld.servlet</groupId> <artifactId>weld-servlet</artifactId> <version>1.1.0.Final</version> </dependency>
CTF
<dependency> <groupId>org.mobicents.servlet.sip.weld</groupId> <artifactId>sip-servlets-weld</artifactId> <version>1.0.0.ALPHA1</version> </dependency>
With the advent of MSS 2.x, the Mobicents team made available asynchronous processing of requests feature in the world of SipServlets and demonstrated this feature with a new version of the traditional Click2Call example.
Now its time to get Click2Call one step further and demonstrate the CTF features with it.
In this new version of the Click2Call, the CDI programming model makes the application significant simpler by using beans as services. Redundant is the use of the ServletContext to store attributes such as registered users or calls. This is now being served by the CallStatusContainer and the SipRegistar modules. Several functions of the application are being delegated to beans also. Methods that need to fire an event are using the CDI event producer/observer model instead of a queue that was placed in the ServletContext and the SimpleSipServlet class is using the SipRegistar module to register users.
If you check out the Click2Call example you will notice the following major changes:
SimpleSipServlet is nothing more than a simple class. No more extend SipServlet and
@OverridedoRequest(SipServletRequest req) and such. All the methods of the class that needs to get notified for a SIP request or response have@Observe @SipEventand that enough to handle SIP messages.Everywhere in the project, when there is a need for the SipFactory we don’t take it using JNDI anymore. A simple
@InjectSipFactory sipFactory will do the job since CTF makes available SipFactory for injection.Several of the application’s functionality have been moved to stand alone modules. One of them is the SipRegistar module that will take care of SIP Registration requests. SimpleSipServlet injects SipRegistar module and delegates registration requests to it. Please note that these modules could reside in an external archive jar file placed in the classpath of the application, thus the beginning of reusable SIP modules.
You will also notice that SipSession or SipApplicationSession in the SimpleSipServlet wont be retrieved by the request or the response. If you include the following in the application
@InjectSipSession sipSession and@InjectSipApplicationSession sipAppSession CTF will make sure you will get the SipSession and SipApplicationSession from the request or the response accordingly, depending on the SIP event you observe.
The drawing below will give you the general idea of the application’s interactions with the serveral modules and the CTF.
Note
MSS 2.x comes with Click2CallAsync predeployed, make sure you undeploy this application and apply the correct dar configuration before you deploy the new version of Click2Call.
In the examples of the framework you will find a version of Click2Call with CTF, suitable for servlet 2.5 containers such as Tomcat 6.0.29 and JBoss AS5.
CTF provides an extensive set of features and advantages to the developer but we believe there are improvements to be done. Developers hold a vital role for the further improvement of the framework.
Please give it a try and provide early feedback !
This is a perfect time to offer any ideas for or contribute Telco modules/extensions that you would find useful in your applications.
Leave us your comments on the discussion started at mobicents google group