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.
- 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.
- 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.
- IMConversation: This is a text chat between two user agents.
- IMConference: A text chat between more than two participants, which is brokered by the server.
- MSRPConversation. A two-party communication that uses MSRP protocols, mainly to transfer files and sending messages.
- MSRPConference: A multi-party communication that uses MSRP protocol internally. This is always brokered by an MSRP relay server in CAFE.
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
- Install SailFin and SailFin CAFE as mentioned in this blog.
- Checkout the sample and build using maven 2.
- Start the SIP client of one user (eg: Alice) and Make a call to Bob. [For X-Lite tips, see this blog]
- Since Bob's phone is not active, after a while, the call will be rejected by the server.
- Now start Bob's phone. The moment it starts, a call will be established between the Alice and Bob.