Skip to main content

[CAFE] UserProcedures integrated in trunk

Posted by erikvandervelden on January 25, 2010 at 1:03 AM PST




Last week we have merged the userprocedures branch into the trunk of sailfin-cafe.
This blog will give a bit of background on what the userprocedures are, how they work in generally and what you can expect in the future.
There will be some separate blogs highlighting the different procuedures individually.

What are user procedures ?

The user procedures are a name for a collection of IMS related communication service APIs which are not related to invite sessions (calls).
What they have in common is that all of these share a similar life-cycle and a have a similar API from the applications point of view.
In a sense they all describe a procedure that the application can invoke on behalf of a user, like publishing the status of a subscriber.

Which user procedure are there ?

The following user procedures exist, are in progress or are planned.

  • Registration
    Registers a user (or a URI) to an SIP or IMS network.

  • PresenceSource
    Create a document describing the status of a user and publish this to the presence server.

  • PresenceWatcher
    Query the status of a users' friends and be notified when their status changes.

  • WatcherInfoSubscriber [in progress]
    Check who is watching a users' status and be notified when people start or stop watching.

  • GroupWatcher [planned]
    Be notified of changes to the list of friends of a user.

In order to be able to use the presence related user procedures it is also needed that you can create a list of friends of a user that can be "watched".
Also you will need to define rules to be able to decide who is allowed to see a users' status.
For this reason also the following things are implemented:

  • Group Management
    Create, modify and delete group(s) of entities that a user can watch.

  • Rules Management
    Create a set of rules on who is allowed to watch a users' status. Also makes it possible to add people (or entities) to a black or a white list.

  • XCAP client library
    The group and rules management manipulates the XDM/XCAP data on the XDM server. For this an XCAP client is used. This is also usable by the application directly to manipulate documents not supported (yet) by sailfin-cafe.

In order to use the user procedures you will need an IMS network or a simulated IMS network.
Work to create a very basic simulator that is delivered with sailfin cafe and works out-of-the-box for most scenarios is ongoing.
 

Life cycle of a user procedure

All the user procedures share the same lifecycle characteristics. When they are created the applicaiton can request expiration time.
The network can either accept this time or shorten it. Before it expires the application has to refresh the procedure by sending an update.

user procedures state machine

This shows the general flow.
So once the procedure is started you usually set the expiration time and other data related to the procedure.
Then you call update(). This will initiate the start of the user procedure.
The network can will respond to this.

If all went well, the application will receive a UserProcedureEvent of type STARTED.
Note that the network may have shortened the expiration time (you can check this by getting the expiration time).

Now several things can happen.

  1. The application gets new data and wants to update the user procedure.
    E.g., for presenceSource, your status may have changed.
    This is handled very similar to the start. You change your data and call update().

  2. The expiration time is about to expire.
    If the application does not do anything, the network will terminate the procedure.
    Just before the expiration time is up (at about 90%) the application is informed with the ABOUT_TO_EXPIRE event.
    The application can decide to let the the procedure expire, it may decide to explicitly end the procedure or it may decide to refresh the procedure.
    To refresh the application just invokes update() without changing the data (you could change the expiration time if you want to).
    Some procedures have an optimal way of doing a refresh if the data was not changed.

  3. The application can decide that the procedure is done.
    It invoked end() on the user procedure instance.

  4. For some user procedures (presenceWatcher, watcherInfoSubscriber, groupWatcher) there can be a spontaneous NOTIFICATION event when data in the network changes.

There are some error cases as well, but they should be self-evident.

Example

I'll give a very short example on how to create and start a user procedure. UserProcedures are created from the CommunicationSession.


package org.glassfish.cafe.testapp;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.glassfish.cafe.api.CommunicationSession;
import org.glassfish.cafe.api.Context;
import org.glassfish.cafe.api.Registration;

public class SimpleTestServlet extends HttpServlet {
        private static final long serialVersionUID = 1L;

        @Context
        CommunicationSession session;

        @Override
        protected void doGet(HttpServletRequest request,
                        HttpServletResponse response) throws ServletException,
                        java.io.IOException {

                java.io.PrintWriter out = response.getWriter();
                final String party1 = request.getParameter("party1");
                try {
                        out.println("<html>");
                        Registration reg = session.createRegistration(party1);
                        reg.update();
                        out.println("Registration started for " + party1);
                } catch (Exception e) {
                        out.println(e);
                } finally {
                        out.println("</html>");
                        out.close();
                }
        }
}

Registration example



Next time I'll blog about the individual user procedures, starting with registration (e.g., how to configure the connection with the IMS network, how to handle authentication, how to handle the lifecycle events).

Watch this space....

AttachmentSize
userprocedures.jpg85.28 KB
Related Topics >>