Introduction:
Mobicents 2.x.y series of the JAIN SLEE platform is fully compliant to JSR-240 specification. It has been released to the community recently and I have observed frequent queries by the community on creating and deploying JAIN SLEE services on this platform.
Some of the queries are a common concern to many community members.
Therefore, I decided to write this tutorial for providing a step-by-step process for developing and deploying components on the JAIN SLEE 2.x.y series of the Mobicents platform.
This post assumes that you have basic working experience with tools such as Eclipse and Maven and you are using the JAIN SLEE 2.0.0GA binary distribution. For getting JAIN SLEE 2.0.0 GA, please visit this link: JAIN SLEE 2.0.0 GA Download
This post will cover the following topics:
a) Setting up your environment.
b) Installing necessary plugins and software.
c) Developing a JAIN SLEE project using maven archetypes.
d) Launching Maven builds from command line and from eclipse.
e) Deploying and testing your JAIN SLEE services using an IMS client.
Setting up your environment and software installation:
Before you start, you need to set up your environment properly and need to download and install the requisite software. This includes the following steps:
1. Download the Java Development Kit and install it on your machine.
You can get the JDK from this link: JDK Download
Select the appropriate package depending upon your operating system and set the JAVA_HOME environment variable and set the PATH variable properly. Follow the instructions given on the SUN website for the same.
2. Download and install Maven-2 or higher.
All Mobicents components are ‘mavenized’. You need to get Maven 2 or higher and install it on your machine. Please download and install maven and set the required environment variables (M2, M2_HOME and M2_REPO). Also set the PATH correctly.
You can get maven 2 from this link: MAVEN2
3. Download and install Mobicents Maven plugins.
Mobicents provides some plugins for development. Even though these components are for the JAIN SLEE 1.x.y application components at the time of this post, the maven plugins for JAIN SLEE 2.x.y are expected to be released soon for use with the JAIN SLEE 2.x.y series.
You can download and install these plugins from here:
a. Mobicents maven library plugin
4. Install Maven archetypes and configure the Maven archetype catalog
You need to get the archetypes from the link provided:
Now the archetype-catalog.xml file needs to be configured to include these installed archetypes. This is done by including their entries in this file. This file should be present in the .m2 directory of your installation. An example file is shown below:
<?xml version=”1.0″ encoding=”UTF-8″?><archetype-catalog><archetypes><archetype><groupId>org.mobicents.tools.maven.archetype.slee</groupId><artifactId>jain-slee-11-service</artifactId><version>1.0.0.BETA2-SNAPSHOT</version><repository>http://repository.jboss.org/maven2</repository></archetype><archetype><groupId>org.mobicents.tools.maven.archetype.slee</groupId><artifactId>jain-slee-11-library</artifactId><version>1.0.0.BETA2-SNAPSHOT</version><repository>http://repository.jboss.org/maven2</repository></archetype><archetype><groupId>org.mobicents.tools.maven.archetype.slee</groupId><artifactId>jain-slee-11-ra</artifactId><version>1.0.0.BETA2-SNAPSHOT</version><repository>http://repository.jboss.org/maven2</repository></archetype><archetype><groupId>org.mobicents.tools.maven.archetype.slee</groupId><artifactId>jain-slee-11-profile</artifactId><version>1.0.0.BETA2-SNAPSHOT</version><repository>http://repository.jboss.org/maven2</repository></archetype></archetypes></archetype-catalog>
5. Download and install Eclipse Galileo
Please use Eclipse Galileo, as it supports launching MAVEN builds from inside eclipse and you will not need to use the command line interface. Eclipse Galileo can be downloaded from here:
Open eclipse and configure your default workbench location. You should see a screen like this for a new installation:
6. Install the m2Eclipse plugin
After downloading eclipse, you need to install the m2eclipse plugin for maven integration with eclipse.
You can use the update site URL given on this link to install this plugin: m2eclipse
Refer to the screenshot on how to do this below.
Go to help —> install new software and then add the update site url as shown below:
7. Download and install Mobicents JAIN SLEE 2.0.0 GA
Download and install the mobicents container from the link given earlier in this post.
8. Download and install a SIP/IMS client
For testing purposes for the sample project explained later in this post, you will need a SIP or IMS client. I have used the Mercuro IMS client for testing. It is freely available here
Creating a basic Mobicents JAIN SLEE project:
1. Create an maven eclipse project:
Create a new maven project in eclipse by going to File —> New —> Other –> Maven Project. The project wizard launched will guide you in the project creation progress as shown in the screenshot below. You can select the archetypes you need for module creation. You may click on the “configure” button to select your archetype-catalog.xml file to see a list of available archetypes.
In this example, we are using the jain-slee-basic-service archetype, as at the time of writing this post the jain-slee-11-archetype is not ready in SVN.
The project modules created will be of the following structure:
|-du
|—src
|—–main
|——-resources
|———services
|-sbb
|—src
|—–main
|——-java
|———…
|——-resources
|———META-INF
If you look in the filesystem, the project parent (root) will have the following content:
It will contain a parent POM file and two modules by the name of “sbb” and “du”
The parent POM file of our example project looks like this:
<project xmlns=”http://maven.apache.org/POM/4.0.0″ xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:schemaLocation=”http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd”>
<modelVersion>4.0.0</modelVersion>
<packaging>pom</packaging>
<artifactId>mobicents-tutorial-parent</artifactId>
<groupId>org.tutorial</groupId>
<version>0.0.1-SNAPSHOT</version>
<modules>
<module>sbb</module>
<module>du</module>
</modules>
<properties>
<!– JBOSS APP SERVER CONFIG RUNNING MOBICENTS –>
<jboss.config>default</jboss.config>
<mobicents.resources.sip11.version>2.0.0.GA</mobicents.resources.sip11.version>
<mobicents.servers.jainslee.version>2.0.0.GA</mobicents.servers.jainslee.version>
</properties>
<dependencyManagement>
<dependencies>
<!–
IMPORTS MOBICENTS JAIN SLEE SERVER
DEPENDENCY MANAGEMENT
–>
<dependency>
<groupId>org.mobicents.servers.jainslee.core</groupId>
<artifactId>mobicents-slee-core</artifactId>
<version>2.0.0-SNAPSHOT</version>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<!– MOBICENTS MAVEN ECLIPSE PLUGIN – use “mvn mobicents:eclipse” to generate eclipse project files –>
<plugin>
<artifactId>maven-eclipse-plugin</artifactId>
<groupId>org.mobicents.tools</groupId>
<version>1.0.0.BETA2</version>
<inherited>false</inherited>
<executions />
</plugin>
<!– JAVA COMPILER CONFIG –>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.5</source>
<target>1.5</target>
<debug>true</debug>
</configuration>
</plugin>
<!– JARS MANIFEST FILE SETUP –>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<configuration>
<archive>
<manifest>
<addDefaultSpecificationEntries>
true
</addDefaultSpecificationEntries>
<addDefaultImplementationEntries>
true
</addDefaultImplementationEntries>
</manifest>
</archive>
</configuration>
</plugin>
</plugins>
</build>
<!– JBOSS MAVEN REPOSITORIES –>
<repositories>
<repository>
<id>jboss</id>
<name>JBoss Repository</name>
<url>http://repository.jboss.org/maven2</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>jboss-snapshots</id>
<name>JBoss Snapshot Repository</name>
<url>http://snapshots.jboss.org/maven2</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>jboss</id>
<name>JBoss Plugin Repository</name>
<url>http://repository.jboss.org/maven2</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
<pluginRepository>
<id>jboss-snapshots</id>
<name>JBoss Snapshot Plugin Repository</name>
<url>http://snapshots.jboss.org/maven2</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
</project>
This POM files lists its two child modules, the JBOSS repository URLs, the configuration of the target JBOSS AS in which we want to deploy our components, the java compiler configurations and the plugins we need for generating the eclipse files for mobicents projects.
The SBB module will have the following content:
It consists of the src folder. Inside this folder we have a hierarchy. The src/main/java folder contains your source code. The src/main/resources folder contains your sbb-jar.xml deployment descriptor file.
The pom file of the SBB module is as follows:
<project xmlns=”http://maven.apache.org/POM/4.0.0″ xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:schemaLocation=”http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd”>
<modelVersion>4.0.0</modelVersion>
<parent>
<artifactId>mobicents-tutorial-parent</artifactId>
<groupId>org.tutorial</groupId>
<version>0.0.1-SNAPSHOT</version>
</parent>
<artifactId>mobicents-tutorial-sbb</artifactId>
<dependencies>
<dependency>
<groupId>org.mobicents.resources</groupId>
<artifactId>sip11-ratype</artifactId>
<version>2.0.0.BETA2</version>
<scope>runtime</scope>
</dependency>
</dependencies>
</project>
The deployable unit module will have the following structure:
It will consist of the src folder just like the sbb module did. Under the src/main/resources/services folder you will have your JAIN SLEE service.xml file.
The pom file looks like this for this module:
<project xmlns=”http://maven.apache.org/POM/4.0.0″ xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:schemaLocation=”http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd”> <modelVersion>4.0.0</modelVersion> <packaging>pom</packaging> <parent> <artifactId>mobicents-tutorial-parent</artifactId> <groupId>org.tutorial</groupId> <version>0.0.1-SNAPSHOT</version> </parent> <artifactId>mobicents-tutorial-du</artifactId> <dependencies> <dependency> <artifactId>mobicents-tutorial-sbb</artifactId> <groupId>${pom.groupId}</groupId> <version>${pom.version}</version> </dependency> </dependencies><build>
<plugins> <plugin> <groupId>org.mobicents.tools</groupId> <artifactId>maven-du-plugin</artifactId> <extensions>true</extensions> <configuration /> <executions> <execution> <phase>install</phase> <goals> <goal>create</goal> </goals> </execution> </executions> </plugin> <plugin> <artifactId>maven-antrun-plugin</artifactId> <executions> <execution> <id>deploy-DU</id> <phase>install</phase> <goals> <goal>run</goal> </goals> <configuration> <tasks> <copy overwrite=”true” file=”target/${project.build.finalName}.jar” todir=”${jboss.home}/server/${node}/deploy” /> </tasks> </configuration> </execution> <execution> <id>undeploy-DU</id> <phase>clean</phase> <goals> <goal>run</goal> </goals> <configuration> <tasks> <delete file=”${jboss.home}/server/${node}/deploy/${project.build.finalName}.jar” /> </tasks> </configuration> </execution> </executions> </plugin> </plugins> </build> </project>
The project structure is shown below:
2. Populate your SBB code:
Now, we are ready to do some coding. This example contains two event handler methods. The first event handler method is called when the service is first started by the JAIN SLEE container. It is marked as the onServiceStartedEvent (args).
In this event we check whether it is our service that is starting and attach to the service activity if that is the case.
This event is declared in the sbb-jar.xml file as follows:
<event event-direction=”Receive” initial-event=”True”>
<event-name>ServiceStartedEvent</event-name>
<event-type-ref>
<event-type-name>javax.slee.serviceactivity.ServiceStartedEvent</event-type-name>
<event-type-vendor>javax.slee</event-type-vendor>
<event-type-version>1.1</event-type-version>
</event-type-ref>
<initial-event-select variable=”ActivityContext” />
</event>
The source code for this event is generated by the maven plugin.
The second event handler of our project is the onRegisterEvent. This event is supposed to send back a 200 OK for the incoming request on the SIP server transaction activity and then construct and send a MESSAGE to the SIP client on the client transaction activity.
This method is declared in the sbb-jar.xml as follows:
<event event-direction=”Receive” initial-event=”True”>
<event-name>RegisterEvent</event-name>
<event-type-ref>
<event-type-name>javax.sip.message.Request.REGISTER</event-type-name>
<event-type-vendor>net.java.slee</event-type-vendor>
<event-type-version>1.2</event-type-version>
</event-type-ref>
<initial-event-select variable=”ActivityContext” />
</event>
The source code for this method is as follows:
public void onRegisterEvent(RequestEvent event, ActivityContextInterface ac)
{
tracer.info(“REGISTER REQUEST RECEIVED AT MY SBB”);
Request register = event.getRequest();
ServerTransaction st = event.getServerTransaction();
FromHeader from = (FromHeader) register.getHeader(FromHeader.NAME);
ContactHeader contact = (ContactHeader)register.getHeader(ContactHeader.NAME);
tracer.info(“SENDING REPONSE TO THE REGISTER REQUEST”);
try{
st.sendResponse(messageFactory.createResponse(Response.OK, register));
tracer.info(“SENDING AN INSTANT MESSAGE TO THE CLIENT”);
Address fromNameAddress = addressFactory
.createAddress(“sip:mobicents-jain-slee@mobicents.org”);
fromNameAddress.setDisplayName(“Mobicents JAIN SLEE 2.0.0”);
FromHeader fromHeader = headerFactory.createFromHeader(
fromNameAddress, Utils.getInstance().generateTag());
List<ViaHeader> viaHeaders = new ArrayList<ViaHeader>(1);
ListeningPoint listeningPoint = provider.getListeningPoints()[0];
ViaHeader viaHeader = provider.getHeaderFactory()
.createViaHeader(listeningPoint.getIPAddress(),
listeningPoint.getPort(),
listeningPoint.getTransport(), null);
viaHeaders.add(viaHeader);
ContentTypeHeader contentTypeHeader = headerFactory
.createContentTypeHeader(“text”, “plain”);
CSeqHeader cSeqHeader = headerFactory.createCSeqHeader(2L,
Request.MESSAGE);
MaxForwardsHeader maxForwardsHeader = headerFactory
.createMaxForwardsHeader(70);
provider.getNewClientTransaction(messageFactory.createRequest(contact.getAddress().getURI(),
Request.MESSAGE, headerFactory.createCallIdHeader(“mobicents”+System.currentTimeMillis()),
cSeqHeader, fromHeader, headerFactory.createToHeader(from.getAddress(),null),
viaHeaders, maxForwardsHeader, contentTypeHeader, “Welcome to Mobicents JAIN SLEE 2.0 series”))
.sendRequest();
}catch(Exception ex){
ex.printStackTrace();
}
tracer.info(“REQUEST GREETING SENT..”);
}
The other important method of this SBB is the setSbbContext method. This is where we populate the resources being used in the SBB including JAIN SLEE facilities and Resource Adapter factories.
The code for this method looks like this:
/** * Called when an sbb object is instantied and enters the pooled state. */ public void setSbbContext(SbbContext context) { this.sbbContext = context; this.tracer = context.getTracer(RootSbb.class.getSimpleName()); try { sbbEnv = (Context) new InitialContext().lookup(“java:comp/env”); provider = (SleeSipProvider) sbbEnv.lookup(“slee/resources/jainsip/1.2/provider”); messageFactory = provider.getMessageFactory(); headerFactory = provider.getHeaderFactory(); addressFactory = provider.getAddressFactory(); tracer.info(“setSbbContext(…)”); } catch (NamingException e) { // TODO Auto-generated catch block e.printStackTrace(); } }
3. Deployment descriptors:
There are two major deployment descriptors: sbb-jar.xml and service.xml
The sbb-jar.xml file looks like the one shown below. It contains the events that the SBB listens to and the SIP resource adapter configuration:
<?xml version=”1.0″?>
<!DOCTYPE sbb-jar PUBLIC “-//Sun Microsystems, Inc.//DTD JAIN SLEE SBB 1.1//EN”
“http://java.sun.com/dtd/slee-sbb-jar_1_1.dtd”>
<sbb-jar>
<sbb>
<description />
<sbb-name>mobicents-tutorial SBB</sbb-name>
<sbb-vendor>org.tutorial</sbb-vendor>
<sbb-version>0.0.1-SNAPSHOT</sbb-version>
<sbb-classes>
<sbb-abstract-class reentrant=”False”>
<sbb-abstract-class-name>org.tutorial.mobicents_tutorial.RootSbb</sbb-abstract-class-name>
</sbb-abstract-class>
</sbb-classes>
<event event-direction=”Receive” initial-event=”True”>
<event-name>RegisterEvent</event-name>
<event-type-ref>
<event-type-name>javax.sip.message.Request.REGISTER</event-type-name>
<event-type-vendor>net.java.slee</event-type-vendor>
<event-type-version>1.2</event-type-version>
</event-type-ref>
<initial-event-select variable=”ActivityContext” />
</event>
<event event-direction=”Receive” initial-event=”True”>
<event-name>ServiceStartedEvent</event-name>
<event-type-ref>
<event-type-name>javax.slee.serviceactivity.ServiceStartedEvent</event-type-name>
<event-type-vendor>javax.slee</event-type-vendor>
<event-type-version>1.1</event-type-version>
</event-type-ref>
<initial-event-select variable=”ActivityContext” />
</event>
<resource-adaptor-type-binding>
<resource-adaptor-type-ref>
<resource-adaptor-type-name>
JAIN SIP
</resource-adaptor-type-name>
<resource-adaptor-type-vendor>
javax.sip
</resource-adaptor-type-vendor>
<resource-adaptor-type-version>
1.2
</resource-adaptor-type-version>
</resource-adaptor-type-ref>
<activity-context-interface-factory-name>
slee/resources/jainsip/1.2/acifactory
</activity-context-interface-factory-name>
<resource-adaptor-entity-binding>
<resource-adaptor-object-name>
slee/resources/jainsip/1.2/provider
</resource-adaptor-object-name>
<resource-adaptor-entity-link>
SipRA
</resource-adaptor-entity-link>
</resource-adaptor-entity-binding>
</resource-adaptor-type-binding>
</sbb>
</sbb-jar>
The JAIN SLEE service.xml descriptor looks like the one shown below:
<?xml version=”1.0″ encoding=”utf-8″?>
<!DOCTYPE service-xml PUBLIC “-//Sun Microsystems, Inc.//DTD JAIN SLEE Service 1.1//EN”
“http://java.sun.com/dtd/slee-service-xml_1_1.dtd”>
<service-xml>
<service>
<description/>
<service-name>mobicents-tutorial SLEE Service</service-name>
<service-vendor>org.tutorial</service-vendor>
<service-version>1.1</service-version>
<root-sbb>
<description/>
<sbb-name>mobicents-tutorial SBB</sbb-name>
<sbb-vendor>org.tutorial</sbb-vendor>
<sbb-version>0.0.1-SNAPSHOT</sbb-version>
</root-sbb>
<default-priority>0</default-priority>
</service>
</service-xml>
4. Build your code:
For building the project, make sure JBOSS_HOME is set. Then right click on mobicents-tutorial-parent and go to run-as. Now click on maven install.
As a result of this operation, the DU will be compiled and deployed in the JBOSS AS.
Refer to the screenshot below:
5. Deploy your binaries:
If you JBOSS_HOME variable is not set, then the binaries will be copied to the mobicents-tutorial-parent\du\${jboss.home}\server\${node}\deploy directory. You can manually copy and paste this binary to the /deploy directory of JBOSS AS.
6. Test the service:
Use an IMS or a SIP client. I have used Mercuro. Configure 127.0.0.1:5060 as the outbound proxy for the client and then register with Mobicents JAIN SLEE server.
For Mercuro, you will see the result as shown in the screenshot below:
Conclusion:
If you have right tools by your side, then creating projects, developing, deploying and testing your logic can be a smooth process.
If you found this post useful, then please let me know. Your feedback is valuable.
Aayush: weblog 