Overview

The format and semantics of possible alert messages that an OMA DM client can send to the management server is not defined by the OMA specifications. For this reason, the system provides a mechanism for plugging custom components, called Alert Handlers, which are designed to interpret specific types of alert messages coming from the devices.

Alert Handlers are exported to the RM system in the form of OSGi-compliant services on a specific management server. The Mobile Device Manager of RM is responsible for tracking registered handlers and for dispatching the alerts received from the connected devices to the handlers.

Alert Handler API

The Alert Handler API is a part of RM OMA DM Server API represented by the com.prosyst.syncml.dm.server package. An Alert Handler is associated with the AlertHandler interface of the package.

The Alert Handler API is available on the OSGi frameworks of the RM hosts having the management server (MS) role. During application development, you can use the JAR file lib/api/syncmllib.jar and lib/api/mobile-api.jar for compilation and code assistance.

Implementing the Alert Handler

The AlertHandler interface has only one method - receivedAlert. It is called when the client devices sends an OMA DM alert to the backend with code 1224 for a client event or 1226 for a generic alert.

Via the com.prosyst.syncml.common.elements.Alert argument of the receivedAlert method, the Alert Handler can retrieve the properties, data and items of the alert (if any) defined in the OMA DM specifications in Java fashion.

The com.prosyst.syncml.dm.server.DMSession argument of the receivedAlert method provides access to the parameters of the OMA DM session established with the device.

The next example provides an Alert Handler, which processes custom generic alerts which simply contain the current time on the device. These alerts have code 1226 and each contain an item whose data is the device's current time in milliseconds. The following example of an Alert Handler retrieves the alert data and prints it using the default java.util.Date format.

import java.util.Date;
import java.util.Enumeration;
import java.util.Vector;
 
import com.prosyst.syncml.common.elements.Alert;
import com.prosyst.syncml.common.elements.ComplexData;
import com.prosyst.syncml.common.elements.Item;
import com.prosyst.syncml.dm.server.AlertHandler;
import com.prosyst.syncml.dm.server.DmSession;
 
public class MyAlertHandler implements AlertHandler {
 
  // Method inherited from AlertHandler.
  // Retrieves the items of the alert holding the device's current time
  public void receivedAlert(Alert alert, DmSession session) {
    Vector alertItems = alert.getItems();
    if (alertItems.size() > 0) {
      Enumeration alertItemsIndex = alertItems.elements();
      while (alertItemsIndex.hasMoreElements()) {
        Item item = (Item) alertItemsIndex.nextElement();
        ComplexData itemData = item.getData();
        if (itemData != null) {
          System.out.println("[MyAlertHandler] current time on the device is "
                             + formatTime(itemData));
        }
      }
    }
  }
 
  private String formatTime(ComplexData itemData) {
    Date date = new Date(Long.parseLong(itemData.getData()));
    return date.toString();
  }
}

Registering the Alert Handler as a Service

Having implemented the AlertHandler interface, you have to register the implementation as a service in the OSGi framework of the management server host so that the handler gets registered in the Mobile Device Manager.

The code snippet bellow demonstrates registering the Alert Handler as an OSGi-compliant service.

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceRegistration;
              
import com.prosyst.syncml.dm.server.AlertHandler;
 
public class MyAlertHandlerActivator implements BundleActivator {      
  private ServiceRegistration reg;
 
  // Methods inherited from BundleActivator
  public void start(BundleContext bc) throws Exception {
    AlertHandler alertHandler = new MyAlertHandler();
    // Registering the Alert Handler as an OSGi-compliant service
    reg = bc.registerService(AlertHandler.class.getName(), alertHandler, null);
  }
 
  public void stop(BundleContext bc) throws Exception {
    if (reg != null) {
      reg.unregister();
    }
  }
}

References