Foreign application JAR files can be installed in an OSGi Framework as if they were normal bundles. Application containers running on the OSGi Framework must detect the installation of recognized foreign applications and provide a bridge to the OSGi Environment. This bridge can include interaction with the Application Admin Specification, as well as provide access to the OSGi services and Framework events.

The Application container reads the application XML resource from the JAR file and treats the foreign application according to this information. When the foreign application is launched, the application container creates an application instance.

Foreign application instances can get an application context through a static method on the Framework class. The Application Context provides access to getting services, registering services and registering listeners.

The foreign application instance's life cycle can be influenced by the application declaration. If desired, an application can be prevented from launching or stopping when required services are, or become, unavailable.

There are different types of metadata associated with application models. Descriptive information, for example the name, icon, documentation etc. of the application, is usually provided in an application model specific way. Application models can also define behavioral metadata, that is, prescribe that the application needs to be started automatically at device startup (auto start) or whether multiple instances of an application can be executed concurrently (singleton). These kinds of metadata are supported by different application models to different extent and are not in the scope of this specification. The application container is responsible for interpreting this metadata and treating the foreign application in the appropriate way.

Foreign applications can import packages by specifying the appropriate OSGi module headers in the manifest. These headers are fully described in OSGi Core Release 7. Their semantics remain unchanged. The following headers must not be used in foreign applications:

Foreign applications that intend to use the OSGi Framework features should have Bundle-SymbolicName and Bundle-Version headers. If they do not have such a header, they can be deployed with Deployment Package, which can assign these headers in the Deployment Package manifest.

Any JAR that uses these headers must not be recognized as a foreign application, even if their manifest is conforming and valid with respect to the foreign application model. This entails that a JAR cannot both be a bundle with activator or exports and a foreign application.

For example, a MIDlet can be extended to import the org.osgi.application package from the OSGi environment. The Import-Package header is used to describe such an import:

Manifest-Version: 1.0
MIDlet-Name: Example
MIDlet-1: Example, , osgi.ExampleMidlet
MIDlet-Version: 1.1.0
MIDlet-Vendor: OSGi
MicroEdition-Configuration: CDC-1.0
MicroEdition-Profile: MIDP-1.0
Bundle-ManifestVersion: 2
Bundle-SymbolicName: osgi.example 
Import-Package: org.osgi.application;version=1.0,
  org.osgi.framework;version=1.3

The application container must maintain an application context for each started application, that is, the application instance. This context is related to the application's activator. The Application Context can be acquired using a static getApplicationContext(Object) method on the Framework class. The parameter of this method is the application's activator itself. The getApplicationContext method cannot check if the caller is really the given application; the application activator is therefore a capability, any application that has this object can get the Application Context. The application activator should never be shared with other applications. The Application Context must therefore deny the application activator to be used as a service object.

The getApplicationContext method must not be called from the application activator's constructor; at that time it must not be available yet.

For example, a MIDlet could acquire the application context with the following code:

import org.osgi.framework.*;
import org.osgi.application.*;
import javax.microedition.midlet.*;

public class Example extends MIDlet {
    ApplicationContext     context;
    public void startApp() {
            context = Framework.getApplicationContext(this);
    }

    public void pauseApp() { ... }

    public void destroyApp(boolean unconditional) { ... }
}  

The getApplicationContext method must throw an Illegal Argument Exception if it is called with an object that is not an application's activator.

The ApplicationContext object is singleton for the corresponding application's activator. Subsequent calls to the getApplicationContext method with the same application's activator must return the same ApplicationContext object; therefore, applications are free to forget and get the object any number of times during their lifetime. However, it is an error to get the ApplicationContext object for an application that is already stopped. Existing ApplicationContext objects must be invalidated once the application's activator is stopped.

The Application Context provides the following methods about the application:

Foreign applications do not have direct access to the OSGi service registry. However, the application context provides the mechanism to interact with this service registry.

Access to services is more protected and controlled than traditional OSGi access that uses the BundleContext object. The service model is conceptually based on the Declarative Services Specification. It uses the same concepts as that specification. Albeit there are a number of differences due the nature of foreign applications.

Applications can use the locateService or locateServices methods of their associated application context to obtain service objects from the OSGi service registry. Just like OSGi Declarative services, these service objects must be declared a priori in the reference element of the metadata, see Application Descriptor Resource. This metadata declares a number of named references; References contain the criteria which services are eligible for use by the application and how these dependencies should be handled. The foreign application can only use services defined in references; the application context only takes the name of a reference as parameter in the locateService and locateServices methods. That is, a foreign application cannot indiscriminately use the service registry, it is restricted by the application declaration.

A reference selects a subset of services in the service registry. The primary selector is its interface. However, this subset can be further narrowed down with a target filter. The target specifies an OSGi filter expression that is used to additionally qualify the subset of appropriate services.

There are two different methods to access the services selected by the reference:

Once the application instance has obtained a service object, that service is said to be bound to the application instance. There is no method to unbind a service.

For example, a foreign application that wants to log via the Log Service, should declare the following metadata in OSGI-INF/app/apps.xml:

<?xml version="1.0" encoding="UTF-8"?>
    <descriptor xmlns="http://www.osgi.org/xmlns/app/v1.1.0">
        <application class="com.acme.app.SampleMidlet">
        <reference name="log" 
            interface="org.osgi.service.log.LogService"/> 
    </application>
</descriptor>

The code to log could look like:

void log(String msg) {
    ApplicationContext ctxt=    
        Framework.getApplicationContext(this);
    LogService log = (LogService) ctxt.locateService("log");
    log.log( LogService.LOG_INFO, msg );
}

The foreign applications receive the services objects they have access to directly. This means that they cannot access the service properties that are normally associated with the service registrations.

The getServiceProperties(Object) returns a Map object with a copy of these service properties.

The availability of services can influence the life cycle of the foreign application. The life cycle is influenced by the policy and the cardinality.

The policy defines how the unregistration of a bound service must be handled. The following policies are supported:

Additionally, the cardinality defines if a reference is optional. An optional reference does not influence the life cycle of an application, a mandatory reference does. The cardinality is expressed as one of the following values:

The multiplicity is only for compatibility with the Declarative Services. Both locateService and locateServices methods can be used regardless of the given multiplicity and return the selected subset for the given reference.

Mandatory references can influence the launching of an application. An application must only be started when a mandatory reference is satisfied. A reference is satisfied when there is at least one registered service selected by the reference.

If a mandatory reference of an application is about to become unsatisfied, due to unregistering a service, the application container must stop the application instance according to corresponding application model semantics.

A common pattern in the OSGi is registering a service to listen to certain events. For example, the Configuration Admin service requires their clients to register a callback Managed Service, so that the service can asynchronously update the client with new configurations. The ApplicationContext interface contains methods that allow the applications to register such services. These services must be automatically unregistered by the application container after the application has been stopped.

The available methods are:

Either method requires that the given object implements all the interfaces that are given. The Dictionary object provides the properties. See the OSGi registerService methods in the BundleContext class. These identical methods specifies the behavior in detail.

The use of the application activator as a service object is explicitly forbidden. Registering the application activator as a service allows other applications in the OSGi environment to access the Application Context using this object and the getApplicationContext method.

Both methods return a ServiceRegistration object that can be used to unregister the service. Services must be automatically unregistered when the application instance is stopped.

The Application Context provides the following methods to listen to service events:

If a Application Service Listener is registered more than once, then the previous registration is removed. Listeners can be removed with removeServiceListener(ApplicationServiceListener). When the application instance is stopped, the listeners are automatically unregistered.

Applications can use the getStartupArguments method on the application context to obtain their startup arguments. The startup arguments are represented as map with name and value pairs. The name is a non-null and non-empty ("") String object. The value can be any type of object.

The reason for providing the startup parameters through a special mechanism is that it allows foreign applications access to the parameters of a schedule application, see Scheduling.

This uniform access to the startup parameters provides a uniform way for applications of any foreign application model. This facility does not remove the need for any mechanisms required by the foreign application model for startup parameters access.

Most foreign application models allow an application to be launched multiple times, creating multiple instances. In OSGi, a bundle can only be started once, which creates certain assumptions. For example, the Service Factory concept creates a unique service object per bundle.

Each application instance must be seen as a unique bundle while it runs. That is, it should not share anything with other instances. The foreign application container is responsible for this isolation; implementing this isolation requires implementation dependent constructs.

Applications are installed into the system using OSGi bundle installation mechanism (i.e. installBundle method of the BundleContext interface). This allows including application JARs to Deployment Packages without any changes to the Deployment Package format or Deployment Admin behavior. It also allows the OSGi framework to process the dependency information (the package dependencies) included in the application metadata.

The application container can listen to the BundleEvent.INSTALLED events and examine the installed JARs whether they contain applications supported by the particular container. After the installation, the application container is responsible for registering the corresponding Application Descriptor as defined in the Application Admin Specification. Similarly, the container can recognize the removal of the package by listening to BundleEvent.UNINSTALLED events and then it can unregister the corresponding descriptors. Additionally, application container must check the bundle registry for changes when they are started.

Receiving BundleEvent.INSTALLED events via a Synchronous Bundle Listener makes it possible for the application container to examine the package content during installation. A foreign application must not become available for execution unless it is started as a bundle. This mechanism allows foreign applications to be installed but not yet recognized as a foreign application.

The descriptor is the top level element. The descriptor element has no attributes.

A JAR file can contain multiple application activators. The application element can therefore be repeated one or more times in the descriptor element.

The application element has the following attribute:

A reference element represents the applications use of a particular service. All services that an application uses must be declared in a reference element.

A reference element has the following attributes:

The following example is an application declaration for a MIDlet application that depends on the OSGi Log Service and another service:

<?xml version="1.0" encoding="UTF-8"?>
<descriptor xmlns="http://www.osgi.org/xmlns/app/v1.1.0">
  <application class="com.acme.apps.SampleMidlet">
    <reference name="log" interface="org.osgi.service.log"/> 
    <reference name="foo"   
      interface="com.acme.service.FooService" 
      policy="dynamic" 
      cardinality="0..n" /> 
  </application>
</descriptor>

A similar example for an imaginary Xlet, with different dependencies:

<?xml version="1.0" encoding="UTF-8"?>
<descriptor xmlns="http://www.osgi.org/xmlns/app/v1.1.0">
  <application class="com.acme.apps.SampleXlet">
    <reference name="log" interface="org.osgi.service.log"/> 
    <reference name="bar" 
          interface="com.acme.service.BarService"
          policy="static" cardinality="1..n" /> 
  </application>
</descriptor>

The getApplicationContext method provides access to the Application Context of a given application activator. The application activator is therefore a capability; any party that has access to this object can potentially get its related Application Context and use it in intended ways.

A common pattern in small applications is to (ab)use the application activator class for all tasks, among them as service object. However, registering the application activator as a service will allow any party that can use that service to use it as the parameter to the getApplicationContext method.

The Application Context must therefore be protected to not allow the registration of the application activator.

Application models can include the definition of a security model. For example, MIDP 2 defines a security model different from the standard Java 2 security model. If the foreign application model defines a security model different from Java 2 security, then it is the responsibility of the application container to implement this model and enforce it.

OSGi services are protected by Java 2 permissions. Applications wishing to use such services must have the appropriate permissions for those services.

Java 2 permissions are assigned during class loading based on the location of the code, the JAR signatures, and possibly based on other conditions, when using the Conditional Permission framework.

Signing is a very common technique to handle the granting of permissions. It requires that the JAR be signed according to the JAR Signing model. Therefore, OSGi-aware application packages should be signed by JAR signing. However, some foreign application models have alternative signing models in place. However, it is unlikely that this conflicts because JAR signing uses well defined separate files and manifest headers. If the foreign application model changes the JAR file outside the META-INF directory, then the signing according to the foreign application model must be performed before the standard JAR signing.

For example, in the case of MIDP signing and both models are used, the JAR signature should be put to the file first as it modifies the content of the file, and MIDP signing should be applied afterwards.

Applications that use OSGi services must have the corresponding Java 2 permissions granted. In order to simplify the policy management, and ensure that the overall device policy is consistent, application containers should not define separate policy management for each application model; rather they should use the existing OSGi policy management and express the complete security policy by the means of Java 2 permissions with the Conditional Permission Admin service. This way, policy administrator can define the boundaries of the sandbox available for a particular application based on its location, signer or other condition. The application container is responsible for enforcing both the foreign application specific security mechanisms as well as the OSGi granted permissions.

Applications can package permissions as described in the Conditional Permission Admin. These permissions will restrict the foreign application's permissions to maximally the permissions in this file scoped by the signer's permissions.