Eduardo Martins: 2008

NOTE: This tutorial is now deprecated, since it doesn't work with current Mobicents JAIN SLEE platform, but the good news is that I made a new improved one, go for it.

A JAIN SLEE beginner's tutorial? That's a question I see frequently in Mobicents forums, and so I decided to write one that examples how to use Mobicents JAIN-SLEE Server and the last tools we made around Apache Maven2. You can call it "Developing a Hello World JAIN SLEE service in 30 minutes or less".
Of course, before we need a working environment, so you need to install Mobicents JAIN SLEE server binary (don't forget to add an environment variable JBOSS_HOME pointing to the jboss-4.2.2.GA directory of the Mobicents install), and for this tutorial you will also need the Eclipse IDE and Apache Maven2. Additionally you will need to setup Mobicents JAIN SLEE Maven Archetypes. Click on the links for instructions on how to do that.
Ready to rumble? Lets start by creating the Maven2 project using Mobicents JAIN SLEE Maven Archetypes.
Part 1 - Creating the Maven2 project
Open a bash/terminal/command line in the Eclipse workspace directory and type
mvn archetype:generate -DarchetypeCatalog=local
The Maven2 Archetype plugin will ask you what archetype you want to use, introduce the number for jain-slee-basic-service. Second it will ask you the values for some properties:

groupId - introduce org.mobicents.slee.example
artifactId - introduce hello-world
version - just press enter to accept default value
package - introduce org.mobicents.slee.example again

After defining those properties the plugin will ask you to confirm it, introduce y.
The process will finally build the project, which will be a directory named hello-world.
Part 2 - Create the Eclipse project and import it in the Eclipse workspace
Ensure Eclipse is closed, and in the bash/terminal/command line (Eclipse's workspace directory) do
mvn -Declipse.workspace=. eclipse:add-maven-repo
Maven will add a variable M2_REPO to Eclipse pointing to Maven2 local repository. Now change to hello-world directory and do
mvn mobicents:eclipse
Maven will create the Eclipse project files. Finally open Eclipse, in the File menu select Import, then "General->Existing Projects into Workspace", next and finally browse to the hello-world directory and Eclipse should find a project named ... hello-world, select it and press Finish.
Part 3 - JAIN SLEE coding
Lets start with a short overview of JAIN SLEE. A SLEE is an application server, a container for software components. JAIN SLEE is designed and optimized for event driven applications, also known as asynchronous applications.
A JAIN SLEE event represents an occurrence that requires application processing. Each event has a specified event type (name,vendor and version), and all applications define the event types they want to handle, on the application Xml descriptors. For each event type of interest an event handler method must be provided in the application.
Events occur in a resource, inside or outside of the container. We call "event firing" to the action of posting of an event into the container, and when this happens the container will route the event to all applications interested on it, that is, all application instances (entities) attached to the context of that event, in JAIN SLEE this context is named activity. This attachment can be explicit (lets leave that for another article) or implicit, when the application defines the event type of the event being routed as an initial event. This means that if an application defines an event type as "initial", then all events of that type will be handled by the application.
So JAIN SLEE applications, also known as Services, are pure logic, which is executed by the container when events are fired in the container, which means they don’t have any active resources. In that sense, a JAIN SLEE service is no different than a web page script executed by the browser.
Going deeper, a JAIN SLEE Service is a tree of Service Building Blocks (Sbb), containing one root Sbb which then can declare others as child Sbbs, which then can have their own childs, and so on. Each Sbb is a Java abstract class, and includes the following logic:

implementation of the event handler methods
implementation of the interface to be used by other Sbbs who declare it as a child
implementation of an entity/instance life-cyle
implementation of methods to manage persistence of instance data

A well designed JAIN SLEE application only has one initial event, since each event of that type creates a new logical and independent instance of the application.
Ok, now what we want for our service is that when it is activated a message "Hello World" will be printed on the console. The Maven archetype we used already made most of the job:

it created a Service, which is nothing more than a Xml descriptor, that you can find in du/src/main/resources/services/service.xml, that just defines it's id (name,vendor,version) and its root sbb:

<service-name>hello-world SLEE Service</service-name>
<service-vendor>org.mobicents.slee.example</service-vendor>
<service-version>1.0-SNAPSHOT</service-version>
<root-sbb>
<description>
<sbb-name>hello-world SBB</sbb-name>
<sbb-vendor>org.mobicents.slee.example</sbb-vendor>
<sbb-version>1.0-SNAPSHOT</sbb-version>
</description>
</root-sbb>
...

it created a Sbb that handles an internal event, ServiceStartedEvent, that is fired whenever a service is activated. How is this done you may ask, each Sbb class is packed in jar with a Xml descriptor (you can open it in eclipse please? sbb/src/main/resources/META-INF/sbb-jar.xml), this descriptor defines the Sbb id (name,vendor,version), its Java class and the events it handles, in this case ServiceStartedEvent:

<sbb-name>hello-world SBB</sbb-name>
<sbb-vendor>org.mobicents.slee.example</sbb-vendor>
<sbb-version>1.0-SNAPSHOT</sbb-version>

<sbb-classes>
<sbb-abstract-class reentrant="False">      
<sbb-abstract-class-name>
org.mobicents.slee.example.RootSbb
</sbb-abstract-class-name>            
</sbb-abstract-class> 
</sbb-classes> 

<event direction="Receive" 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.0</event-type-version>
</event-type-ref>
<initial-event-select variable="ActivityContext" />
</event>

The Sbb class itself you can open it in the source package of the eclipse project, with the name RootSbb, which includes the ServiceStartedEvent event handler:

public void onServiceStartedEvent(
javax.slee.serviceactivity.ServiceStartedEvent event,
ActivityContextInterface aci) {

try {
Context myEnv = (Context) new InitialContext().lookup("java:comp/env");
ServiceActivity sa = ((ServiceActivityFactory) myEnv
.lookup("slee/serviceactivity/factory")).getActivity();
if (sa.equals(aci.getActivity())) {
// it's this service that is starting
logger.info("service activated...");
}  
// don't want to receive further events on this activity
aci.detach(this.sbbContext.getSbbLocalObject());

} catch (Exception e) {
logger.error("Can't handle service started event.", e);
}
}

The logic in this event handler looks ugly but it's simple, it retrieves the ServiceActivity of the service from it's JNDI environment, and compares it with the ServiceActivity where the event was fired. If matches it means it's our service that is being activated. Great, now we just need to print the message in the console and in fact it's already printing something, "service activated", so all you need to do is change that code to

logger.info("hello world!!!");

Part 4 - Run the service
The end is close, let's start Mobicents JAIN SLEE Server, doing run.sh/run in server/bin folder of the Mobicents directory. Use another bash/terminal/command line window please.
Once it stops go to the window in the hello-world example directory and do
mvn install
Voila, Maven builds the Service's Deployable Unit jar on it's own, copies it to the Mobicents server deploy dir, and you should see the service being deployed on the window where Mobicents is running. In the end you should see
03:04:44,697 INFO [RootSbb] hello world!!!
That's it, have fun with JAIN SLEE specification document (the best knowledge source for sure) and don't forget to leave your feedback here.

Last week I attended JBoss World 2008 at Orlando, the biggest JBoss event ever, with around 750 attendees not working for JBoss/Red Hat.

One of the most interesting things I noticed, is that there is huge market of J2EE developers that can really make a difference with JBoss solutions, by leveraging Mobicents projects into their web applications.

We made a demo of a converged web 2.0 application using JBoss Seam and Mobicents (and much more actually) for a furniture store, that would call site users and admins according to order details, for order auth, confirmation, etc and the reaction was a big big "wow". Attendees left the room with the idea something must be changing.

It's a new world for them, using more than a browser to interact with users, and it's a new world for us, who have been targeting primarily the telco market.

The only not so good thing was the size of the audience for this demo, but the presentation title was somehow misleading and it was at 10h am after JBoss World party! Anyway, we will evolve this demo and for sure present it in more J2EE big events along the year.

Photo of the Mobicents team members present at JBW, left to right: Alexandre Mendonça (R&D), Vladimir Ralev (R&D), Bartosz Baranowski (R&D), Luis Barreiro (QA), me (R&D), Amit Bhayani (R&D), Jean Deruelle (R&D)

Eduardo Martins

Friday, October 03, 2008

Mobicents JAIN-SLEE Server 1.2.0.GA released!

Wednesday, October 01, 2008

Custom XCAP Application Usages on Mobicents XDMS

Friday, August 29, 2008

Thursday, August 14, 2008

Wednesday, August 13, 2008

Tuesday, June 10, 2008

Monday, February 18, 2008