Different types of applications can be accommodated in the Application Admin specification using a model of Application Containers. An Application Container typically follows an external specification, for example, the MIDP specification. In an OSGi environment, the implementer of such a specification can allow its applications (MIDlets in the previous example) to participate in the OSGi Application Model by registering an Application Descriptor service for each of its installed applications, and an Application Handle service for each of its running instances.

This model leverages the capabilities of the OSGi service registry. Installed applications and running applications can be found by enumerating the appropriate services, possibly using a filter if a specific application is sought. The service registry provides necessary isolation of the clients of the applications and their implementers. Typical clients of this specification are desktop/screen managers that provide the end user access to the installed applications.

The primary means of discovery is the Application Descriptor service. An Application Container must register an Application Descriptor service for each of its applications. An application manager can detect the installation and uninstallation of applications by listening to service events.

Service properties on the Application Descriptor carry most of the information that an application manager requires to present the application to the end user. The properties as defined in the following table.

Specialized application descriptors can offer further service properties and method. For example, a MIDP container can register a property that describes that the MIDLet comes from a specific JAD file, thereby allowing a MIDLet aware Application Manager to group these MIDLets.

Application Descriptor services must not be declarative. That is, they can be obtained from the service registry at any time without accidentally initializing a class loader.

The following example shows how to track all visible, launchable, and unlocked applications. These tracked applications are the ones that can be started.

public class TrackLaunchables {
    final static String filter=
        "(&(objectclass="
    +   ApplicationDescriptor.class.getName()
    + ")(application.launchable=true)"
    + "(application.visible=true)"
    + "(application.locked=false))";
    static ApplicationDescriptor[] EMPTY = 
        new ApplicationDescriptor[0];  
    ServiceTracker tracker;

    public void init(BundleContext cntxt) throws Exception {
        tracker = new ServiceTracker(cntxt, 
            cntxt.createFilter(filter), null);
        tracker.open();
    }

    public ApplicationDescriptor[] getActive() {
        Object [] result = tracker.getServices();
        List list = Arrays.asList(result);
        return (ApplicationDescriptor[]) list.toArray(EMPTY);
    }
}

The code is quite simple because the Service Tracker does the actual tracking. The most important part is therefore the filter. The filter selects all the Application Descriptor services that are visible, launchable, and not locked. The getActive method converts the Object[] that the Service Tracker maintains into an array of Application Descriptors.

The Application Descriptor object has an additional number of properties that are not available as service properties. These descriptor properties can be localized. The getProperties(String) method therefore takes a locale String object. This is a standard locale string as defined by the java.util.Locale class. The order for the locale constituents is:

For example, the following files provide manifest translations for English, Dutch (Belgium and the Netherlands) and Swedish.

en          nl_BE           
nl_NL       sv

It returns a Map object containing localized versions of the properties. This is a copy of the original objects so changes to this Map object are not reflected in the Application Descriptor properties.

If the locale string is null, the localization will be based on the default locale, as specified by the java.util.Locale.getDefault method. If the locale is the empty String object (""), no localization must be used. This will contain the raw values that are usually used as keys. If a specific locale has no appropriate translations, a less specific locale must be used, as described in the Locale class. As last resort, the raw values must be returned.

The key names in the Map object are case-sensitive. Application Containers can add additional properties to this Map object, however, they must avoid key names starting with application. They should use key names that have a prefix that does not collide with other Application Containers.

If no locale specific value of an application property is available then the default one must be returned. The following case-sensitive key names are treated as standard for locale specific values in the Map object. Additional elements may also be stored in the Map object. The specified properties are explained in the following table.

The Application Descriptor provides the launch(Map) methods for application managers to launch an application. Launching consists of creating the specific application object, starting it, registering an Application Handle service that represents that instance and return the Application Handle service.

The Map object parameter is application specific. Applications should use unique names for the keys in this map, for example com.acme.ringsignal. This specification does not specify any keys for this map except for:

When an application is started successfully the corresponding Application Handle service will be registered with the service registry.

An Application Handle service represents an instance of an application. The application handle is registered by the Application Container after successfully launching a new application instance.

An Application Handle service can be used to query the state and manipulate the application instance. It is the responsibility of the Application Handle service to maintain the application instance life cycle state by interacting with the implementation object of the application.

A running instance can have the following state according to this specification:

Application Containers can extend the number of states.

The Application Handle service maintains the service properties as listed in the following table. Specialized application handles may offer further service properties, but the key names specified in the table below must not be used for other purposes.

Specialized application handles may offer further application states. The name of additional states must be qualified names (dotted); non-qualified names are reserved for future specifications.

An application instance can be stopped with its associated Application Handle using the destroy() method. This first turns the state of the Application to STOPPING. The application instance may save its persistent data before termination and it must release all the used resources. The application instance's artifacts should not be reused any more. The Application Admin implementation and the application container should ensure (even forcefully) that all allocated resources are cleaned up.

If the application instance has completely stopped, then its Application Handle must be unregistered.

Many application containers allow an application to specify a value when the application is stopped. This value is called the exit value. The Application Handle can therefore return the exit value when this is supported by the underlying application model. It is possible to find out if the underlying container support exit values because not all application containers support exit values.

The Application Descriptor has a special service property that it must set when it supports exit values. This service property name is defined on the ApplicationHandle class as APPLICATION_SUPPORTS_EXITVALUE. Setting this property to any value signals that the application instance supports an exit value return.

The getExitValue(long) method on the ApplicationHandle class returns the exit value object from the underlying application container. If the application container does not support exit values, then this method must always throw an Unsupported Operation Exception.

The method takes a time out value which allows it to wait for the application instance to finish. This time-out can take the following values:

The type of the exit value is undefined, it is a generic Java object. It is up to the application container to define the actual type for this Object.

Applications represented by the application descriptors can be locked. If an application is locked then no new instance of the represented application can be started until it is unlocked. The locking state of the application has no effect on the already launched instance(s). The Application Descriptor provides the methods lock and unlock to set, unset the locking state. Locking and unlocking an application represented by an Application Descriptor requires the proper Application Admin Permission. The methods to lock, unlock, and query the locked status of an application are implemented as final methods of the abstract application descriptor class to ensure that an application container implementation will not be able to circumvent this security policy.

Scheduling can be used to launch an a new application instance in the future when a specific event occurs, if needed on a recurring basis.

The Application Descriptor service provides the schedule(String,Map,String,String,boolean) method to schedule an application to be launched when an specific event occurs. The parameters to this method are:

The schedule method must register a Scheduled Application service with the service registry and return the Schedule Application service object.

For example, the invocation

appDesc.schedule(
    null,       // System generates schedule id
    null,       // No arguments
    "org/osgi/application/timer",
    "(&(hour_of_day=0)(minute=0))",
    true) 

Schedules the application to be launched when a timer event is received and the hour_of_day and minute properties are zero.

The Scheduled Application service must have the following properties:

The list of active Scheduled Application services can be obtained from the service registry. A non-recurrent Scheduled Application service is unregistered once the application is successfully launched.

The timer used to start an application from a schedule has a resolution of one minute. It is therefore possible that an application is delayed up to a minute before it is started.

Exceptional conditions that arise during processing of application requests. The Exception identifies the actual error with an integer code. The following codes are supported:

The event mechanism of the Application Admin specification is based on the OSGi service registry event model. Both Application Descriptor and Application Handle are services. Bundles can listen to these events registering a ServiceListener object with a Bundle Context or they can listen to events from the Event Admin, see for more information Service Event.

The first responsibility of the Application Container is to register an Application Descriptor for each available application. The Application Container must therefore extend the ApplicationDescriptor base class that is provided by the Application Admin implementer and provided in the org.osgi.service.application package. The base class is defined as an abstract class in this specification with only minimal implementation code. Implementers of the Application Admin implementation can replace this class with an implementation that enforces their desired policies.

The Application Container must override the methods that have a Specific suffix. These methods are:

The specific methods must be made protected because the specific Application Descriptor is registered as a service and is intended to be used by a wide array of clients. These clients can call public methods so care should be taken to ensure that no intrusion can take place this way. The Application Admin implementer must provide the implementation for the public methods and perform the appropriate security checks.

The specific Application Descriptor must be registered for each possible application with the set of service properties listed in Table 116.1 on page .

An application is launched with the launchSpecific method. This method is called by the Application Admin implementation, as implemented in the ApplicationDescriptor base class. The implementation of the launchSpecific method must return expediently. The Application Descriptor must perform the following steps (in the given order):

The Application Handle represents the running instance. The Application Container must extend the provided base class and implement the following methods:

The most important method is destroySpecific. This method must perform the following actions in the given order:

The Application container should monitor the progress of its instances. If an instance stops, for example due an exception or it quits voluntarily, the Application Container must call the destroy method on the Application Handle itself and handle the fact correctly that the instance is already stopped in the destroySpecific method.

The following method on the Application Descriptor provides access to the certificate chain that was used to sign the application. This method is used by the Application Permission.

This is an Application Container that scans a directory for executables. Each executable is registered as an Application Descriptor. The example assumes that there is a bundle activator that creates the Application Descriptor services. This activator must also ensure that when it is stopped no handles remain.

The example is not an robust implementation, its only intention is to show the concepts of the Application Admin specification in practice.

The (simple) Application Descriptor could look like:

public class SimpleDescriptor extends ApplicationDescriptor{
    ServiceRegistration registration;
    File                executable;
    SimpleModel         model;
    boolean             locked;
    static URL          genericIcon = SimpleDescriptor.class
                                            .getResource("icon.png");

    SimpleDescriptor(SimpleModel model, File executable) {
        super("com.acme." + executable.getName());
        this.model = model;
        this.executable = executable;
    }

    public Map getPropertiesSpecific(String locale) {
        Map map = new Hashtable();
        map.put(APPLICATION_ICON, genericIcon);
        map.put(APPLICATION_NAME, executable.getName());
        return map;
    }

    protected ApplicationHandle launchSpecific(
        final Map args) throws Exception {
        final SimpleDescriptor descriptor = this;

        return (ApplicationHandle) AccessController
                .doPrivileged(new PrivilegedExceptionAction() {
                    public Object run() throws Exception {
                        SimpleHandle handle = 
                            new SimpleHandle(descriptor, args);
                        handle.registration =
                            model.register(handle);
                        return handle;
                    }
                });
    }

    Dictionary getServiceProperties() {
        Hashtable p = new Hashtable();
        p.put(APPLICATION_LAUNCHABLE, Boolean.TRUE);
        p.put(APPLICATION_LOCKED, Boolean.valueOf(locked));
        p.put(Constants.SERVICE_PID, getApplicationId());
        return p;
    }

    protected void lockSpecific() { locked = true; }
    protected void unlockSpecific() { locked = false; }
    public boolean matchDNChain(String arg) { return false; }
    protected boolean isLaunchableSpecific() { return true; }
}

The associated Application Handle must launch the external executable and track its process. If the process dies autonomously or is stopped via the destroy method, it must unregister the Application Handle service. The class could be implemented like:

public class SimpleHandle extends 
    ApplicationHandle implements Runnable {

    ServiceRegistration registration;
    Process             process;
    int                 instance;
    String              state = RUNNING;
    static int          INSTANCE = 0;
    Thread              thread;

    public SimpleHandle(SimpleDescriptor descriptor, 
        Map arguments) throws IOException {
        super(descriptor.getApplicationId() 
            + ":" + (INSTANCE++), descriptor);
        String path = descriptor.executable.getAbsolutePath();
        process = Runtime.getRuntime().exec(path);
        thread = new Thread(this, getInstanceId());
        thread.start();
    }

    public String getState() {  return state; }

    protected void destroySpecific() throws Exception {
        state = STOPPING;
        registration.setProperties(getServiceProperties());
        thread.interrupt();
    }

    // Wait until process finishes or when
    // interrupted
    public void run() {
        try {
            process.waitFor();
            destroy();
        }
        catch (InterruptedException ie) {
            process.destroy();
            try {
                process.waitFor();
            }
            catch (InterruptedException iee) {
                // Ignore
            }
        }
        catch( Exception e ) {
            .. logging
        }
        registration.unregister();
    }

    Dictionary getServiceProperties() {
        Hashtable p = new Hashtable();
        p.put(APPLICATION_PID, getInstanceId());
        p.put(APPLICATION_STATE, state);
        p.put(APPLICATION_DESCRIPTOR,
            getApplicationDescriptor().getApplicationId());
        return p;
    }
}

The Application Container must create the Application Descriptor services from some source. Care should be taken to optimize this scanning so that the initialization time is not significantly increased. Running application instances should be stopped if the Application Container is stopped. The following code shows a possible implementation:

public class SimpleModel implements BundleActivator{
    BundleContext context;
    Set           handles = new HashSet();

    public ServiceRegistration register(SimpleHandle handle){
        handles.add(handle);
        return context.registerService(
            ApplicationHandle.class.getName(),
            handle, handle.getServiceProperties());
    }

    public void start(BundleContext context) throws Exception 
    {
        this.context = context; 

        File file = new File("c:/windows");
        final SimpleModel me = this;

        file.list(new FilenameFilter() {
            public boolean accept(File dir, String name) {
                if (name.endsWith(".exe")) {
                    SimpleDescriptor sd = new SimpleDescriptor(me,
                        new File(dir, name));
                    sd.registration = me.context.registerService(
                            ApplicationDescriptor.class.getName(),
                                sd, sd.getServiceProperties());
                }
                // We ignore the return anyway
                return false;
    }});}

    public void stop(BundleContext context) throws Exception{
        for (Iterator handle = handles.iterator();
            handle.hasNext();) {
            SimpleHandle sh = (SimpleHandle) handle.next();
            try {
                sh.destroy();
            }
            catch (Exception e) {
                // We are cleaning up ...
            }
}}}

The OSGi specified org.osgi.service.application package that is delivered with the specification in a JAR file is a dummy implementation. The intention of this package is to be replaced by an Application Admin implementation. This implementation can then enforce policies by intercepting the calls from any Application Managers to the Application Containers.

The Application Admin implementer must re-implement the following methods in the ApplicationDescriptor class:

The Application Admin implementer must also implement the following method in the ApplicationHandle class:

Implementers must not change the signature of the public and protected parts of the ApplicationDescriptor and ApplicationHandle classes. Adding fields or methods, either public or protected is explicitly forbidden.

The implementation of the container must ensure that Security Exceptions are only thrown during the invocation of any of the Application Descriptor methods when the required permissions are lacking. If the Application Descriptor is not valid, an Illegal State Exception must be thrown and never a Security Exception.

The launch method of the Application Descriptor must be implemented by the Application Admin implementer. Launching must be performed in the following steps:

The implementation of the ApplicationHandle destroy method must follow the following steps:

Application Descriptor services can be scheduled by calling the schedule method, as described in Scheduling. This method must be implemented by the Application Admin implementer.

Application Admin implementations must make a reasonable effort to launch scheduled applications in a timely manner. However, launching is not guaranteed, implementations can drop and forget events if it is necessary in order to preserve the stability and integrity of the device. The granularity of the timer should also be taken into account, this granularity is one minute so the actual time an application will be launched can be shifted up to 60 seconds.

If an event would launch multiple applications then the order of launching is not defined, it is implementation specific.

Launching a scheduled application is constrained by the same rules as application launching. Thus, attempting to launch a locked application on the specified event must fail to launch. Launching can only succeed when the application is unlocked.

If the scheduling is non-recurring and launching a new instance fails then when the specified event occurs again launching the application must be attempted again until it succeeds. Non recurring schedules must be removed once the launch succeeds.

The triggering event will be delivered to the starting application instance as an additional item identified by the org.osgi.triggeringevent argument in its startup parameters. This property must not be used for other purposes in the startup parameters. To ensure that no events are leaked to applications without the appropriate permission, the event is delivered in a java.security.GuardedObject, where the guarding permission is the Topic Permission for the topic to which the event was posted.

Scheduling and unscheduling an application, or retrieving information about scheduled applications requires the Application Admin Permission for the target application to be scheduled. If the target is the unique identifier of the scheduling application itself then it can schedule itself. In addition, the scheduling entity must have Topic Permission for the specified topic.

The application scheduler can use a virtual timer event for time scheduled applications. This event is not actually sent out by the Event Admin; this virtual event is only used for the syntax to specify a recurring launch.

The topic name of this virtual timer event is:

org/osgi/application/timer

The properties of the virtual timer event are:

The timer has a resolution of a minute. That is, it is not possible to schedule per second.

A property that is not included into the filter matches any value. Not including a field implies that it always matches. For example, if the minute=0 clause from the filter is missing, the timer event will be fired every minute.

The following examples are filters for the timer event to specify certain time in the device local time. The topic is always org/osgi/application/timer.

Noon every day:

(&(hour_of_day=12)(minute=0))

Every whole hour, on every Sunday:

(&(day_of_week=0)(minute=0))

Every whole hour:

(minute=0)

Figure 116.3 shows how an application manager can be notified about the installation of a new application. The actual installation may be done prior to the notification or may be done by the application container. At the end of the successful installation the application container must register a specialized Application Descriptor service which properly represents the installed application. If the installed application's dependencies are fulfilled (which are container specific) then the application descriptor's application.visible and application.launchable properties should be set to true.

Figure 116.3 Installing a bundle that is managed by an Application Container

Firstly the appropriate Application Descriptor service on which the operation will be made is fetched from the service registry. This Application Descriptor is a container specific sub-class of the Application Descriptor class. Its launch method is called which is in the base class.

The application instance may not receive the startup arguments if its application container does not support startup arguments. The launch method checks if the a new application instance can be launched, for example, that the necessary rights are granted, the application is not locked and the application is not a singleton that already has an instance.

If the application can be launched then the launchSpecific method, which is in the subclass, will create and start a new application instance according to its application container. It will create a specific application handle and associate the newly created application instance to it. The launchSpecific method will register the application handle with proper service properties. The value of application.state service property must be RUNNING. The call chain returns the application handle.

Figure 116.4 Launching an application

To destroy an application, the proper application handle has to be fetched from the service registry to call its destroy() method. It checks if the instance can be destroyed, for example that the necessary permissions are granted, it then calls the destroySpecific method to let its implementation destroy the instance in an application container specific way. First, it sets the application.state service property to STOPPING then stops the application instance. Finally it unregisters the application handle.

This ApplicationAdminPermission class implements permissions for manipulating applications and their instances. The permission must be held by any bundle that manipulates application descriptors or application handles.

The target of the Application Admin Permission is an OSGi filter that matches a number of properties. This is similar to the Admin Permission in the Framework. Alternatively, instead of the filter the pseudo target <<SELF>> can be used.

The following properties can be tested in the filter:

The pseudo target <<SELF>> indicates that the calling application is allowed to manipulate its own descriptors and handlers.

The following actions can be granted: