Binod P.G is a senior staff engineer at Sun Microsystems, where he work as the architect of the GlassFish Communication Server (http://sailfin.dev.java.net). Binod has vast experience in Java EE, distributed enterprise computing and telecommunication both in legacy platforms like Mainframes and also in Unix/Linux and Microsoft. He has been researching on convergence of different communication technologies with enterprise distributed computing for the last few years. Binod has posted 2 posts at DZone. View Full User Profile

SailFin CAFE Fundamentals Part II: Communications and UserProcedures (with an example)

05.18.2010
| 5579 views |
  • submit to reddit

Here is the second part of the CAFE fundamentals blog series. This time, I am explaining two important interfaces called Communication and UserProcedure with an example. If this is the first time you are hearing about SailFin CAFE, I recommend reading the CAFE fundamentals article and the blog on writing your first CAFE application. The core of this discussion is an example which shows triggering a Conversation when the callee comes online. Just like the earlier examples in my previous blogs, this one also doesn't have any SIP Servlets and is written using the higher level API provided by SailFin CAFE.

At first, lets take a look at Communication interface in CAFE. Just as the name implies it is any form of Communication between 2 or more Participants. It can be text/audio/video/filetransfer etc. There are 6 kinds of Communication interfaces exposed by CAFE at the moment.
  1. Conversation : Communication between two Participants. Typically this is between two user agents (or sip phones). It can also be between a sip phone and a Player/Recorder
  2. Conference: As the name implies it is a communication between more than two user agents, which mandates the use of a media mixer in the media server always. 
  3. IMConversation: This is a text chat between two user agents. 
  4. IMConference: A text chat between more than two participants, which is brokered by the server.
  5. MSRPConversation. A two-party communication that uses MSRP protocols, mainly to transfer files and sending messages. 
  6. MSRPConference: A multi-party communication that uses MSRP protocol internally. This is always brokered by an MSRP relay server in CAFE.
A Communication can be created as a result of arrival of a SIP Message from a user agent or it can be created explicitly by the application (eg: web application). If the Communication is created as a result of an incoming SIP request, CAFE will always treat it as a two party communication. Application can then use the INITIALIZATION event in the CommunicationBean to convert such a two party communication to a multi-party communication. Take a look at this blog for an example.  

On the other hand, any interaction or a procedure between a user agent and the server is represented as the interface UserProcedure. Registration, PresenceSource, PresenceWatcher and WatcherInfoSubscriber are the types of UserProcedures. Each UserProcedure has a certain life span associated with it, after which it will expire. Application can refresh the UserProcedure to extend its life. For example, a Registration created by the application would timeout after a period of time. Application can refresh the registration during the ABOUTTOEXPIRE event. Erik has explained UserProcedures in his blogs here and here.   Now, lets take a look at a real example. In this example, a Conversation is initiated either by sip user agent or a web application. However lets imagine that the callee's phone is not online yet. In this service, application creates a PresenceWatcher to watch the Presence status of the callee for for a stipulated period of time. If the callee bring up his phone by that time, the CommunicationBean is notified with a NOTIFICATION pertaining to the PresenceWatcher and the call is then initiated.

The example application contains two CommunicationBeans. First one, CallBean is of the type Conversation for handling events related to Conversation and another (PresenceBean) with type PresenceWatcher to handle the presence notifications.  

As you can see in the code, when the Conversation is rejected by the callee, the ParticipantEvent.Type.REJECTED will be invoked. There the application, creates a PresenceWatcher with an expiration time of 5 minutes. So, if the callee switch on his phone in next five minutes, the UserProcedureEvent.Type.NOTIFICATION is triggered in the PresenceBean. And the application in the event creates a Conversation to establish the call again between the parties.   Full source code of the application is checked into the SailFin CAFE SVN repository. Here are the steps to run the sample
  1. Install SailFin and SailFin CAFE as mentioned in this blog.
  2. Checkout the sample and build using maven 2. 
  3. Start the SIP client of one user (eg: Alice) and Make a call to Bob. [For X-Lite tips, see this blog]
  4. Since Bob's phone is not active, after a while, the call will be rejected by the server.
  5. Now start Bob's phone. The moment it starts, a call will be established between the Alice and Bob. 

 Play with SailFin CAFE and let us know your feedback at users@sailfin.dev.java.net.

From http://weblogs.java.net/blog/binod/archive/2010/05/14/sailfin-cafe-using-presence-and-conversation-together

Published at DZone with permission of its author, Binod Pg.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)