Features of the Application Management Agent API

The Application Management Agent API on the device allows the following tasks to be performed:

  • List suitable service applications

  • Use available service applications

  • Install and uninstall a service application on user devices

  • Activate/deactivate already installed service application

Accessing the Device-Side Agents API on Devices

The Application Management Agent API becomes accessible on a device when the device is registered with the Application Management Agent and CU Application Remote Management Agent optional features in the Device Register Wizard (in case of an OSGi device).

OSGi Bundle Component Plug-in and/or Subscription Deployment Package Plug-in optional features may be checked too depending on the type of service applications the user intends to use.

If Backup Provider for Service Applications optional feature is checked, backup and restore functionality for service applications will be provided on the device.

If the device has been already registered and conneceted to the RM, Application Management Agent can be activated on the device when the following bundles are installed and started manually on the device:

  • The Application Agent bundle (packages/ssm/ssm.application.agent.jar) registers the ApplicationManagementAgent interface as a service on the end user device.

  • Suitable Communication Adapter for Application Agent depending on the device type:

  • The Messaging Adapter for Application Agent bundle (packages/ssm/ ssm.application.comm.msg.agent.jar) allows the communication between the RM backend and the device over the Messaging API.

  • The HTTP Adapter for Application Agent bundle (packages/ssm/ ssm.application.comm.http.agent.jar) allows the communication between the backend and the device over the HTTP protocol.

  • Suitable Component Adapter:

  • The Deployment Package Plugin bundle (packages/ssm/ssm.application.plugin.dp.agent.jar) ensuring the proper management of deployment packages for devices which have a framework implementation of the OSGi Service Platform Mobile Specification, Release 4 version 4.0.1. along with Service Application DMT Plugin bundle (packages/ssm/ssm.application.dmt.agent.jar) which provides management of service applications meant for deployment on devices compatible with the device management model defined by the Open Mobile Alliance, or the so-called OMA DM model.

  • The OSGi Bundle Component Plugin bundle (packages/ssm/ssm.application.plugin.osgibundle.agent.jar) provides the proper management of OSGi bundles marked as service applications and provided for device frameworks compatible with the OSGi Service Platform Core Specification, Release 4.

  • The CU Application Remote Management Interface bundle (packages/ssm/ssm.application.cu.agent.jar) provides control unit factories for representing and managing the custom client bundle attributes of the service applications.

  • Backup Provider for Service Applications bundle (packages/ssm/ssm.application.backup.agent.jar) provides backup and restore functionality for service applications.

Structure of the Device-Side Agents API

The Device-Side Agents API is concentrated in the com.prosyst.mprm.gateway.appagent package. This can be accomplished by using the install(String id) method of the Application Management Agent interface. --- change to This can be accomplished by using the install(String id)/install(String id, String version, boolean sync) method of the Application Management Agent interface.

Application Management Agent

The main interface of the API is ApplicationManagementAgent, which is registered as a service on the device framework by the Application Management Agent bundle. ApplicationManagementAgent provides the ServiceApplication interface as a result of a method invocation of getInstalledApplications(). Information about all available service applications on the backend can be received by using the listApplications(String filter) method. The received ServiceApplicationInfos can be later used to get the service application attributes. The most important feature of the ApplicationManagementAgent allows the device operator to install the desired service applications on the device. This can be accomplished by using the install(String id) method of the Application Management Agent interface.

Service Application

A ServiceApplication object represents a service application which is already installed on a registered device. Through the ServiceApplication interface, the logged-in end user can:

  • Get the current state of the service application by calling the getState() method.

  • Start or stop the application by using respectively the start() or stop() method.

  • Uninstall the application from the device by using the uninstall()method.

Service Application Info

The ServiceApplicationInfo object represents a service application which resides on the RM Software Repository and is ready to be delivered to a device. It provides the getXXX methods through which the user can obtain information about the service application.

By calling the methods of a ServiceApplicationInfo, you can receive information about the name (getName), description (getDescription), service identifier (getServiceID), version (getVersion), service properties (getProperties) and other application attributes.

Service Application Discovery

Service applications available on user devices and on the backend can be retrieved through the Application Management Agent interface. The listing bellow shows the applications installed on the user's device and those available in the Software Repository.

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import com.prosyst.mprm.gateway.appagent.ApplicationManagementAgent;
import com.prosyst.mprm.gateway.appagent.ServiceApplication;
import com.prosyst.mprm.gateway.appagent.ServiceApplicationInfo;
 
public class ServiceApplicationManagementTest implements BundleActivator {
 
ApplicationManagementAgent ma;
ServiceReference Refma;
 
// Method inherited from the Bundle Activator
public void start(BundleContext bc) throws Exception {
 
// Retrieve the Application Management Agent as an OSGi service on the framework
Refma = bc.getServiceReference(ApplicationManagementAgent.class.getName());
if (Refma != null) {
ma = (ApplicationManagementAgent) bc.getService(Refma);
// List all available service applications on the backend
ServiceApplicationInfo[] list = ma.listApplications(null);
System.out.println("The Software Repository provides the following service applications: ");
for (int a = 0; a < list.length; a++) {
System.out.println(list[a].getServiceID());
}
// List all service applications installed on the device
ServiceApplication[] apps = ma.getInstalledApplications();
System.out.println("Service applications installed on the device are: ");
for (int b = 0; b < apps.length; b++) {
System.out.println(apps[b].getProperties());
}
}
}
 
// Method inherited from Bundle Activator
public void stop(BundleContext bc) throws Exception {
 
if (Refma != null) {
bc.ungetService(Refma);
}
}
}

Installation of Service Applications on Devices

The subscribed service application can be installed on the managed device by using the ApplicationManagementAgent interface. The listing bellow illustrates the installation of the "My OSGi Bundle" bundle on the registered device.

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import com.prosyst.mprm.gateway.appagent.ApplicationManagementAgent;
import com.prosyst.mprm.gateway.appagent.ServiceApplication;
....
 
public class InstallApplicaitonTest implements BundleActivator {
 
ApplicationManagementAgent ma;
ServiceReference Refma;
 
public void start(BundleContext bc) throws Exception {
 
// Retrieve the Application Management Agent as an OSGi service
...
ServiceApplication install = ma.install("My OSGi Bundle"); // the highest available
version of "My OSGi Bundle" will be installed
ServiceApplication install = ma.install("My OSGi Bundle", "2.0", true); // the exact
- "2.0" - version of "My OSGi Bundle" will be installed
}
public void stop(BundleContext bc) throws Exception {
// Release all used resources
}
}

The ApplicationManagementAgent processes the service application and generates proper events for the progress of the task. When the installation of the service application finishes successfully, an ApplicationManagementEvent is sent to an implemented and registered ApplicationManagementListener listening for the changes in the state of the application.

Life Cycle Management of Service Applications

The Device-Side Agents API provides features for managing the life cycle of the installed on a specific device service applications. The successful activation of a service is possible only in case an ApplicationManagementEvent for the completion of the application installation has been received first.

Operations executed over service applications like install/start/stop/uninstall may be done synchronously or asynchronously. To monitor service applications states when asynchronously operations are executed, ApplicationManagementListenermay be used. See the listing below.

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceRegistration;
 
import com.prosyst.mprm.gateway.appagent.ApplicationManagementEvent;
import com.prosyst.mprm.gateway.appagent.ApplicationManagementListener;
import com.prosyst.mprm.gateway.appagent.ServiceApplicationInfo;
 
public class AppListener implements BundleActivator, ApplicationManagementListener {
private ServiceRegistration registration;
public void start(BundleContext bc) throws Exception {
registration = bc.registerService(ApplicationManagementListener.class.getName(), this, null);
}
public void stop(BundleContext context) throws Exception {
if (registration != null) {
registration.unregister();
}
}
 
public void event(ApplicationManagementEvent event) {
System.out.println("Event : " + event.getEventType());
System.out.println("Application : " + event.getApplication().getName());
}
 
public void handleException(ServiceApplicationInfo app, Exception exp) {
System.out.println("Error for application : " + app + " : " + exp.getMessage());
}
}