Code that wants to use one of the OSGi Framework implementations must provide the chosen framework implementation on the class path, or create a special class loader that loads the code and resources from that implementation. How this is achieved, is outside this specification.

A framework implementation must provide a factory class. A factory class is an indirection to create a framework implementation object. The implementation factory class must implement the FrameworkFactory interface. The launcher can use the following ways to get this class name:

The FrameworkFactory interface has a single method: newFramework(Map). The map provides the sole configuration properties for the framework object. The result of this method is a framework object, this object implements the Framework interface. The Framework interface extends the Bundle interface and adds methods to handle the issues unique to launching a framework. The framework object can be seen as the system bundle, though the framework object and the system bundle do not have to be identical, implementations are allowed to implement them in different objects.

Before the framework object can be used, the launcher must first initialize it by calling the init method. After initialization, the framework object can provide a valid Bundle Context and has registered any framework services, but any installed bundles must be in the INSTALLED state. The launcher can then configure the framework object by installing bundles, interacting with the framework services, or registering launcher services. The launcher can also start bundles, but these bundles will not be started until the framework object becomes ACTIVE.

After the framework object is properly configured, the launcher can start it by calling the start method. The framework object will become ACTIVE, and it will move the startlevel (if present) to the configured start level. This can then resolve and start any installed bundle. After a framework has become ACTIVE, it can be stopped from the framework object, or through the system bundle.

The launcher can wait for a framework object to be stopped with the waitForStop method. This method will block until the framework is completely stopped and return a Framework event indicating the cause of the stop. After the framework object has been shutdown, and the waitForStop method has returned, all installed bundles will be in the INSTALLED state. The same framework object can be re-initialized, and started again, any number of times.

The action diagram in Figure 4.2 shows a typical session. A new framework is created and initialized. The launcher then gets the Bundle Context, installs a bundle and starts the framework. It then gets a service, calls a method and then waits for the framework to stop. The service waits some time and calls stop on the System Bundle. The dotted lines indicate some non-specified interactions that are implementation dependent.

Figure 4.2 Action Diagram for Framework Launching

If security is enabled, then the launcher and the framework require All Permission. If All Permission is not available, then the framework must throw a Security Exception.

The following code shows how a framework can be launched.

void launch( String factoryName, File[] bundles) 
            throws Exception {
    Map p = new HashMap();
    p.put( "org.osgi.framework.storage",    
            System.getProperty("user.home")
        +   File.separator+"osgi");

    FrameworkFactory factory = 
        (FrameworkFactory) Class.forName( factoryName )
                                            .newInstance();
    Framework framework = factory.newFramework(p);
    framework.init();

    BundleContext context = framework.getBundleContext();

    for ( File bundle : bundles )
        context.installBundle( bundle.toURL().toString() );
    
    framework.start();
    framework.waitForStop(0);
}

The Map object given as a parameter to the newFramework method provides the configuration properties to the framework. This parameter may be null, in that case the framework must be started with reasonable defaults for the environment it is started in. For example, the framework should export the JRE packages as system packages and it should store its bundles in an appropriate place. The framework must not look in the System properties for configuration properties, the specified configuration properties are complete.

The configuration properties may contain any implementation specific properties. The properties in Table 4.1 must be supported by all conformant frameworks.

The configuration properties plus any defaults set by the framework and the fixed properties set by the framework all together form the launching properties for the framework.

org.osgi.framework.command.execpermission=«
   "chmod +rx ${abspath}"

CDC-1.1/Foundation-1.1,OSGi/Minimum-1.2

org.osgi.framework.library.extensions= a,so,dll

org.osgi.framework.security = osgi

org.osgi.framework.startlevel.beginning = 3

org.osgi.framework.storage.clean = onFirstInit

org.osgi.framework.system.packages.extra=«
   org.acme.foo; version=1.2, org.acme.foo.impl

org.osgi.framework.trust.repositories = «
   /var/trust/keystore.jks:~/.cert/certs.jks

The properties in the following table are the fixed properties of the framework. The values of these properties are established by the framework implementation and added to the launching properties. If these properties are set in the configuration properties, the framework must ignore them.

All launching properties are available through the getProperty(String) method. See Environment Properties.

Once the frameworks is created, it must be in the INSTALLED state. In this state, the framework is not active and there is no valid Bundle Context. From this point on, the framework object can go through its life cycle with the following methods.

Figure 4.3 on page shows how the previous methods traverse the state diagram.

Figure 4.3 State diagram Framework

Before the framework can be used, it must be initialized. Initialization is caused by one of the init methods or implicitly by the start method. An initialized framework is operational, but none of its bundles are active. This is reflected in the STARTING state. As long as the framework is in this state, new bundles can be installed without any installed code interfering. Existing bundles must all be in the INSTALLED or RESOLVED state. In this state, the framework will run at start level 0.

A framework object can be initialized multiple times. After initialization:

After the framework has been initialized, it can be started with the start method. This start method must be called on the framework object. The start method moves the framework into the ACTIVE state. If the framework was not initialized, it must be initialized first.

In the active state, all installed bundles previously recorded as being started must be started as described in the Bundle.start method. Any exceptions that occur during startup must be wrapped in a BundleException and then published as a Framework ERROR event. Bundles, and their different states, are discussed in The Bundle Object. If the Framework implements the optional Start Level specification, this behavior can be different. See Start Level API Specification. Any bundles that specify an activation policy must be treated according to their activation policy, see Activation Policies.

After the system bundle enters the ACTIVE state, a Framework STARTED event is broadcast.

Shutdown can be initiated by stopping the system bundle, covered in The System Bundle or calling the stop method on the framework object. When the framework is shut down, it first enters the STOPPING state. All ACTIVE bundles are stopped as described in the Bundle.stop method, except that their persistently recorded start state is kept unchanged. Any exceptions that occur during shutdown must be wrapped in a BundleException and then published as a Framework event of type FrameworkEvent.ERROR. If the Framework implements the optional Start Level specification, this behavior can be different. See Start Level API Specification. During the shutdown, bundles with a lazy policy must not be activated even when classes are loaded from them and they are not yet activated.

The framework then moves to start level 0, calls stop on the Extension Bundle Activators (see Stop Extension Activators), stops event handling and releases any resources (like threads, class loaders, etc.) it held. The framework then enters the RESOLVED state and destroys the Bundle Context. The last action is to notify any threads that are waiting in the waitForStop method. The Framework must be re-initialized if it needs to be used again.

After a framework object is stopped and in the resolved state, it can be initialized and started again. Framework implementations must ensure that holding on to a framework object does not consume significant resources.

The launcher is not running as an OSGi bundle, it is a plain Java application. However, often this launcher needs to communicate with the bundles inside the framework. The launcher can use the Bundle Context of the framework object to get and register services. However, it must ensure that there is class compatibility between its objects and objects from the bundle. A framework will not automatically share packages between the launcher code and the bundles. Packages must be explicitly exported from the parent class loader. The org.osgi.framework.system.packages.extra is specifically designed to hold any application packages that needs to be shared between the OSGi bundles and the application. Packages in that property are added to the system packages of the framework, which are packages exported by the system bundle from its parent loader. Care should be taken to ensure that all these system packages are visible to the class loader that loaded the framework.

The OSGi Framework is running in a multi-threaded environment. After the framework is started, it will start bundles and these bundles will be activated. Activated bundles normally start background threads or react on events from other bundles. That is, after the start method returns, the framework has moved to the ACTIVE state and many bundles can be busy on different threads. At this point, the framework object can be stopped by the launcher through the framework object, or by a bundle through the System Bundle's stop method.

The waitForStop(long) method on the framework object is included to handle any launcher cleanup that is required after the framework has completely stopped. It blocks until the framework has been completely shutdown. It returns one of the following Framework events to indicate the reason for stopping:

Each framework must have a unique identity every time before the framework is started. This identity is reflected in the framework property:

org.osgi.framework.uuid

The value of this property must reflect a string defined in [14] IETF RFC 1422 A Universally Unique IDentifier (UUID) URN Namespace with the urn:uuid: prefix. For example:

f81d4fae-7dec-11d0-a765-00a0c91e6bf6

The Java UUID class is capable of generating such a UUID. However, as long as the external representation is maintained frameworks are free to create a unique global id in another way.

Setting this property in the configuration properties has no effect, the framework must override it.

A Java VM will automatically exit when there are only daemon threads running. This can create the situation where the VM exits when the Framework uses only daemon threads and all threads created by bundles are also daemon threads. A Framework must therefore ensure that the VM does not exit when there are still active bundles. One way to achieve this, is to keep at least one non-daemon thread alive at all times.

The Java Service Provider Configuration model, as described in [13] Java Service Provider Configuration, provides a way to obtain the name of the framework factory by reading a resource in the JAR. In this specification, it is assumed that the framework implementation is on the class path. The name is obtained by reading the content of the configuration resource with the path META-INF/services/org.osgi.framework.launch.FrameworkFactory.

For example, if the com.acme.osgi framework has a factory class com.acme.osgi.Factory, then it should have the following resource:

META-INF/services/org.osgi.framework.launch.FrameworkFactory

And the contents should be:

# ACME Impl. for OSGi framework
com.acme.osgi.Factory

In contrast with the [13] Java Service Provider Configuration, there must only be one class name listed in the resource. However, launchers should be aware that the class path could contain multiple resources with the same name.

Java 6 has introduced the java.util.ServiceLoader class that simplifies creating objects through these types of factories. The following code assumes there is a framework implementation JAR on the class path:

ServiceLoader<FrameworkFactory> sl =
    ServiceLoader.load(FrameworkFactory.class);

Iterator<FrameworkFactory> it = sl.iterator();
if ( it.hasNext() ) {
    Framework fw = it.next().newFramework(null);
    ...
}

A bundle is identified by a number of names that vary in their scope:

A bundle can be in one of the following states:

Figure 4.4 State diagram Bundle

When a bundle is installed, it is stored in the persistent storage of the Framework and remains there until it is explicitly uninstalled. Whether a bundle has been started or stopped must be recorded in the persistent storage of the Framework. A bundle that has been persistently recorded as started must be started whenever the Framework starts until the bundle is explicitly stopped. The Start Level API influences the actual starting and stopping of bundles. See Start Level API Specification.

The Bundle interface defines a getState() method for returning a bundle's state.

If this specification uses the term active to describe a state, then this includes the STARTING and STOPPING states.

Bundle states are expressed as a bit-mask though a bundle can only be in one state at any time. The following code sample can be used to determine if a bundle is in the STARTING, ACTIVE, or STOPPING state:

if ((b.getState() & (STARTING | ACTIVE| STOPPING)) != 0)
    doActive()

The BundleContext interface, which is given to the Bundle Activator of a bundle, defines the following methods for installing a bundle:

A bundle must be valid before it is installed, otherwise the install must fail. The validity of a bundle is discussed in Bundle Validity.

If the to be installed bundle has a bundle symbolic name and version pair that is already installed in the framework then the installation is only valid when the org.osgi.framework.bsnversion framework launching property is set to multiple or managed. See Bundle Collision Hook for more information.

Every bundle is uniquely identified by its location string. If an installed bundle is using the specified location, the installBundle methods must return the Bundle object for that installed bundle and not install a new bundle.

The Framework must assign a unique bundle identifier that is higher than any previous bundle identifier.

The installation of a bundle in the Framework must be:

Once a bundle has been installed, a Bundle object is created and all remaining life cycle operations must be performed upon this object. The returned Bundle object can be used to start, stop, update, and uninstall the bundle.

A bundle can enter the RESOLVED state when the Framework has successfully resolved the bundle's dependencies as described in the manifest. These dependencies are described in Resolving Process.

A bundle can be started by calling one of the start methods on its Bundle object or the Framework can automatically start the bundle if the bundle is ready and the autostart setting of the bundle indicates that it must be started.

A bundle is ready if following conditions are all met:

Once a bundle is started, a bundle must be activated, see Activation, to give control to the bundle so that it can initialize. This activation can take place immediately (eager activation), or upon the first class load from the bundle (lazy activation). A started bundle may need to be automatically started again by the framework after a restart or changes in the start level. The framework therefore maintains a persistent autostart setting for each bundle. This autostart setting can have the following values:

The Bundle interface defines the start(int) method for starting a bundle and controlling the autostart setting. The start(int) method takes an integer option, the following values have been defined for this option:

The Framework must attempt to resolve the bundle, if not already resolved, when trying to start the bundle. If the bundle fails to resolve, the start method must throw a BundleException. In this case, the bundle's autostart setting must still be set unless START_TRANSIENT is used.

When the start method returns without an exception, the state of the bundle will either be ACTIVE or STARTING, depending on the declared activation policy and whether it was used. If the start method throws an exception, then the bundle will not be in either of these states and the stop method will not be called for this Bundle Activator instance.

The start() method calls start(0).

The optional Start Level API influences the actual order of starting and stopping of bundles. See Start Level API Specification. Fragment bundles can not be started and must cause a Bundle Exception when there is an attempt to start them.

A bundle is activated by calling its Bundle Activator object, if one exists. The BundleActivator interface defines methods that the Framework invokes when it starts and stops the bundle.

To inform the OSGi environment of the fully qualified class name serving as its Bundle Activator, a bundle developer must declare a Bundle-Activator manifest header in the bundle's manifest file. The Framework must instantiate a new object of this class and cast it to a BundleActivator instance. It must then call the BundleActivator.start method to start the bundle.

The following is an example of a Bundle-Activator manifest header:

Bundle-Activator: com.acme.Activator

A class acting as a Bundle Activator must implement the BundleActivator interface, be declared public, and have a public default constructor so an instance of it may be created with Class.newInstance.

Supplying a Bundle Activator is optional. For example, a library bundle that only exports a number of packages does not need to define a Bundle Activator. In addition, other mechanism exists to obtain control and get a Bundle Context, like for example the Service Component Runtime.

The BundleActivator interface defines these methods for starting and stopping a bundle:

A Bundle Activator must be created when a Bundle is started, implying the creation of a class loader. For larger systems, this greedy strategy can significantly increase startup times and unnecessarily increase the memory footprint. Mechanisms such as the Service Component Runtime and activation policies can mitigate these problems.

Fragment bundles must not have a Bundle Activator specified.

Bundle-ActivationPolicy ::= policy ( ';' directive )*
policy ::= 'lazy'

4.4.6.2 Lazy Activation Policy

A lazy activation policy indicates that the bundle, once started, must not be activated until it receives the first request to load a class. This request can originate either during normal class loading or via the Bundle loadClass method. Resource loading and a request for a class that is re-directed to another bundle must not trigger the activation. The first request is relative to the bundle class loader, a bundle will not be lazily started if it is stopped and then started again without being refreshed in the mean time.

This change from the default eager activation policy is reflected in the state of the bundle and its events. When a bundle is started using a lazy activation policy, the following steps must be taken:

• A Bundle Context is created for the bundle.

• The bundle state is moved to the STARTING state.

• The LAZY_ACTIVATION event is fired.

• The system waits for a class load from the bundle to occur.

• The normal STARTING event is fired.

• The bundle is activated.

• The bundle state is moved to ACTIVE.

• The STARTED event is fired.

If the activation fails because the Bundle Activator start method has thrown an exception, the bundle must be stopped without calling the Bundle Activator stop method. These steps are pictured in a flow chart in Figure 4.5. This flow chart also shows the difference in activation policy of the normal eager activation and the lazy activation.

Figure 4.5 Starting with eager activation versus lazy activation

The lazy activation policy allows a Framework implementation to defer the creation of the bundle class loader and activation of the bundle until the bundle is first used; potentially saving resources and initialization time during startup.

By default, any class loaded from the bundle can trigger the lazy activation, however, resource loads must not trigger the activation. The lazy activation policy can define which classes cause the activation with the following directives:

• include - A list of package names that must trigger the activation when a class is loaded from any of these packages. The default is all package names present in the bundle.

• exclude - A list of package names that must not trigger the activation of the bundle when a class is loaded from any of these packages. The default is no package names.

For example:

Bundle-ActivationPolicy: lazy; «
    include:="com.acme.service.base,com.acme.service.help"

When a class load triggers the lazy activation, the Framework must first define the triggering class. This definition can trigger additional lazy activations. These activations must be deferred until all transitive class loads and defines have finished. Thereafter, the activations must be executed in the reverse order of detection. That is, the last detected activation must be executed first. Only after all deferred activations are finished must the class load that triggered the activation return with the loaded class. If an error occurs during this process, it should be reported as a Framework ERROR event. However, the class load must succeed normally. A bundle that fails its lazy activation should not be activated again until the framework is restarted or the bundle is explicitly started by calling the Bundle start method.

The Bundle interface defines the stop(int) method for stopping a bundle. This calls the stop method when the bundle is in the ACTIVE state and sets the bundle's state to RESOLVED. The stop(int) takes an integer option. The following value has been defined for this option:

The stop() method calls stop(0).

The optional Start Level API influences the actual order of starting and stopping of bundles. See Start Level API Specification.

Attempting to stop a Fragment bundle must result in a Bundle Exception.

The BundleActivator interface defines a stop(BundleContext) method, which is invoked by the Framework to stop a bundle. This method must release any resources allocated since activation. All threads associated with the stopping bundle should be stopped immediately. The threaded code may no longer use Framework-related objects (such as services and BundleContext objects) once the stop method returns.

If the stopping bundle had registered any services or Framework listeners during its lifetime, then the Framework must automatically unregister all registered services and Framework listeners when the bundle is stopped. It is therefore unnecessary from the Framework's point of view to unregister any services or Framework listeners in the stop method.

The Framework must guarantee that if a BundleActivator. start method has executed successfully, that same BundleActivator object must be called with its BundleActivator.stop method when the bundle is deactivated. After calling the stop method, that particular BundleActivator object must never be used again.

Packages exported by a stopped bundle continue to be available to other bundles. This continued export implies that other bundles can execute code from a stopped bundle, and the designer of a bundle should assure that this is not harmful. Exporting interfaces only is one way to prevent such unwanted execution when the bundle is not started. Generally, to ensure they cannot be executed, interfaces should not contain executable code.

The Bundle interface defines two methods for updating a bundle:

The update process supports migration from one revision of a bundle to a newer revision of the same bundle. The capabilities provided by the new revision must be immediately available to the Framework. If the old bundle revision has an isInUse() bundle wiring then all capabilities provided by the old bundle wiring must remain available for existing bundles and future resolves until the bundle is refreshed, see Refreshing, or the Framework is restarted. Otherwise the capabilities provided by the old revision must be removed.

After the update operation is complete, the framework must attempt to move the bundle to the same state as it was before the operation taking the activation policy into account, without changing the autostart setting. This is described in more detail in Restoring State After Refresh or Update.

An updater of a bundle must have AdminPermission[<bundle>,LIFECYCLE] for both the installed bundle as well as the new bundle. The parameters of AdminPermission are explained in Admin Permission.

The Bundle interface defines the uninstall() method for uninstalling a bundle from the Framework. This method causes the Framework to notify other bundles that the bundle is being uninstalled, and sets the bundle's state to UNINSTALLED. To whatever extent possible, the Framework must remove any resources related to the bundle. This method must always uninstall the bundle from the persistent storage of the Framework.

If the uninstalled bundle has one or more revisions with isInUse() bundle wirings then all capabilities provided by the old in use bundle wirings must remain available for existing bundles and future resolves until the bundle is refreshed, see Refreshing, or the Framework is restarted. Otherwise the capabilities provided by the old revision must be removed.

The Bundle object provides a convenient way to detect modifications in a bundle. The Framework must keep the time that a bundle is modified by any of the life cycle operations or, in the case of multi-release JARs, by changing the version of Java platform being used. See Multi-release JAR. The getLastModified() method will return the last time the bundle was effectively modified. This last modified time must be stored persistently.

The method must return the number of milliseconds since midnight Jan. 1, 1970 UTC with the condition that a modification must always result in a higher value than the previous last modified time of any bundle.

The getLastModified() method is very useful when a bundle is caching resources from another bundle and needs to refresh the cache when the other bundle is effectively modified. A modification in the other bundle can happen while the caching bundle is not active. The last modified time is therefore a convenient way to track modifications in bundles.

The Bundle interface defines two methods to return manifest header information: getHeaders() and getHeaders(String).

If the bundle is a multi-release JAR, see Multi-release JAR, then the returned manifest header information must be the supplemented manifest information. That is, the main manifest with the replacement values from a supplemental manifest, if any, for the current Java platform version.

Localization is performed according to the description in Localization. If no translation is found for a specific key, the Dictionary returned by Bundle.getHeaders will return the raw values as specified in the manifest header values without the leading '%' character.

These methods require AdminPermission[<bundle>, METADATA] because some of the manifest header information may be sensitive, such as the packages listed in the Export-Package header. Bundles always have permission to read their own headers.

The getHeaders methods must continue to provide the manifest header information after the bundle enters the UNINSTALLED state. After the bundle has been uninstalled, this method will only return manifest headers that are raw or localized for the default locale at the time the bundle was uninstalled.

A framework implementation must use only the raw (unlocalized) manifest headers when processing manifest headers. Localizations must not influence the operations of the Framework.

In certain cases, it is necessary to load classes as if they were loaded from inside the bundle. The loadClass(String) method gives access to the bundle class loader. This method can be used to:

For example, an application model could use this feature to load the initial class from the bundle and start it according to the rules of the application model.

void appStart() {
    Class initializer =  bundle.loadClass(activator);
    if ( initializer != null ) {
      App app = (App) initializer.newInstance();
      app.activate();
   }
}

Loading a class from a bundle can cause it to be activated if the bundle uses a lazy activation policy.

The resources from a bundle can come from different sources. They can come from the raw JAR file, Fragment bundles, imported packages, or the bundle class path. Different use cases require a different resource search strategy. The Bundle interface provides a number of methods that access resources but use different strategies. The following search strategies are supported:

For example, consider the following setup:

A: Require-Bundle: D
   Import-Package: q,t
   Export-Package: t
B: Export-Package: q,t
C: Fragment-Host: A
D: Export-Package: s

This setup is depicted in Figure 4.6.

Figure 4.6 Setup for showing the difference between getResource and getEntry

The following table shows the effect of getting a resource from this setup when bundle A is resolved.

The following table shows the same cases as the previous table but now for an unresolved bundle A.

The Bundle interface defines a method for returning information pertaining to a bundle's permissions: hasPermission(Object). This method returns true if the bundle's Protection Domain has the specified permission, and false if it does not, or if the object specified by the argument is not an instance of java.security.Permission. Fragments also have their own Protection Domain.

The parameter type is Object so that the Framework can be implemented on Java platforms that do not support Java based security.

See The Permission Check for more information about the permission checks.

Bundles that have been started have a Bundle Context. This object is a capability; it is intended to be used only by the bundle. However, there are a number of cases where bundles must act on behalf of other bundles. For example, the Service Component Runtime registers services on behalf of other bundles. The framework therefore provides access to another bundle's context via the getBundleContext() method. If there is no Bundle Context for that Bundle because the bundle is a fragment bundle or the bundle state is not in { STARTING, ACTIVE, STOPPING }, then null must be returned.

This method is potentially harmful because it allows any bundle to act as any other bundle. In a secure system, the method is protected by requiring AdminPermission[*,CONTEXT].

The adapt(Class) method allows the Bundle to be adapted to different types. The purpose of this method is to provide more specialized access to the Bundle object, access that is not always needed by most clients of the interface. For example, the adapt method can be used to adapt a Bundle object to the current BundleWiring object (if resolved). The adapt method is used as follows:

BundleWiring bw = aBundle.adapt(BundleWiring.class);

The following table shows the minimum list of types that can be used in the adapt method. However, implementations and specifications can extend this list.

The BundleContext interface defines methods to retrieve information about bundles installed in the OSGi framework:

Bundle access is not restricted; any bundle can enumerate the set of installed bundles. Information that can identify a bundle, however (such as its location, or its header information), is only provided to callers that have AdminPermission[<bundle>,METADATA].

The Framework should provide a private persistent storage area for each installed bundle on platforms with some form of file system support.

The BundleContext interface defines access to this storage in terms of the File class, which supports platform-independent definitions of file and directory names.

The BundleContext interface defines a method to access the private persistent storage area: getDataFile(String). This method takes a relative file name as an argument. It translates this file name into an absolute file name in the bundle's persistent storage area. It then returns a File object. This method returns null if there is no support for persistent storage.

The Framework must automatically provide the bundle with FilePermission[<storage area>, READ | WRITE | DELETE] to allow the bundle to read, write, and delete files in that storage area.

If EXECUTE permissions is required, then a relative path name can be used in the File Permission definition. For example, FilePermission[bin/*,EXECUTE] specifies that the sub-directory in the bundle's private data area may contain executables. This only provides execute permission within the Java environment and does not handle the potential underlying operating system issues related to executables.

This special treatment applies only to FilePermission objects assigned to a bundle. Default permissions must not receive this special treatment. A FilePermission for a relative path name assigned via the setDefaultPermission method must be ignored.

The BundleContext interface defines a method for returning information pertaining to Framework properties: getProperty(String). This method can be used to return the Framework launching properties; see Launching Properties. This method will examine the System properties if the requested property is not available in the launching properties.

The capabilities of the system bundle are obtained by adapting the system bundle to a BundleWiring as described in Adaptations. This is in preference to parsing the system bundle's headers.

The system bundle's Bundle.getHeaders method returns a Dictionary object with implementation-specific manifest headers. The following headers of this OSGi specification can be returned in this dictionary. Headers not mentioned in this table should not be used.

A listener interface is associated with each type of event. The following list describes these listeners.

BundleContext interface methods are defined which can be used to add and remove each type of listener.

Events can be asynchronously delivered, unless otherwise stated, meaning that they are not necessarily delivered by the same thread that generated the event. The thread used to call an event listener is not defined.

The Framework must publish a FrameworkEvent.ERROR if a callback to an event listener generates an unchecked exception - except when the callback happens while delivering a FrameworkEvent.ERROR (to prevent an infinite loop).

Synchronous events have the unfortunate effect that, in rare cases, events can be delivered out of order to a listener. For example, a Service Event UNREGISTERING can be delivered before its corresponding Service Event REGISTERED. One pathological case is when a service listener (for example a Service Tracker) unregisters a service that it receives in the REGISTERED event for. If there are listeners queued behind the pathological listener then they see the unregistering before they see the registration.

If the Framework delivers an event asynchronously, it must:

If the Framework did not capture the current listener list when the event was published, but instead waited until just prior to event delivery, then the following error could occur: a bundle could have started and registered a listener, and then the bundle could see its own BundleEvent.INSTALLED event.

The following three scenarios illustrate this concept.

Generally, a bundle that calls a listener should not hold any Java monitors. This means that neither the Framework nor the originator of a synchronous event should be in a monitor when a callback is initiated.

The purpose of a Java monitor is to protect the update of data structures. This should be a small region of code that does not call any code the effect of which cannot be overseen. Calling the OSGi Framework from synchronized code can cause unexpected side effects. One of these side effects might be deadlock. A deadlock is the situation where two threads are blocked because they are waiting for each other.

Time-outs can be used to break deadlocks, but Java monitors do not have time-outs. Therefore, the code will hang forever until the system is reset (Java has deprecated all methods that can stop a thread). This type of deadlock is prevented by not calling the Framework (or other code that might cause callbacks) in a synchronized block.

If locks are necessary when calling other code, use the Java monitor to create semaphores that can time-out and thus provide an opportunity to escape a deadlocked situation.

The Admin Permission is a permission used to grant the right to manage the Framework with the option to restrict this right to a subset of bundles, called targets. For example, an Operator can give a bundle the right to only manage bundles of a signer that has a subject name of ACME:

org.osgi.framework.AdminPermission(
    "(signer=\*, o=ACME, c=us)", ... )

The actions of the Admin Permission are fine-grained. They allow the deployer to assign only the permissions that are necessary for a bundle. For example, an HTTP implementation could be granted access to all resources of all bundles.

org.osgi.framework.AdminPermission("*",
    "resource" )

Code that needs to check Admin Permission must always use the constructor that takes a bundle as parameter: AdminPermission(Bundle,String) with a single action.

For example, the implementation of the loadClass method must check that the caller has access to the class space:

public class BundleImpl implements Bundle{

    Class loadClass(String name) {
        securityManager.checkPermission( 
            new AdminPermission(this,"class") );
            ...
    }
}

The Admin Permission takes a filter as its name. Filter based permissions are described in Filter Based Permissions.

The following interfaces define bundle callbacks that are invoked by the Framework:

When any of these callbacks are invoked by the Framework, the bundle that caused the callback may still be on the stack. For example, when one bundle installs and then starts another bundle, the installer bundle may be on the stack when the BundleActivator.start method of the installed bundle is called. Likewise, when a bundle registers a service object, it may be on the stack when the Framework calls back the serviceChanged method of all qualifying ServiceListener objects.

Whenever any of these bundle callbacks try to access a protected resource or operation, the access control mechanism should consider not only the permissions of the bundle receiving the callback, but also those of the Framework and any other bundles on the stack. This means that in these callbacks, bundle programmers normally would use doPrivileged calls around any methods protected by a permission check (such as getting or registering service objects).

In order to reduce the number of doPrivileged calls by bundle programmers, the Framework must perform a doPrivileged call around any bundle callbacks. The Framework should have java.security.AllPermission. Therefore, a bundle programmer can assume that the bundle is not further restricted except for its own permissions.

Bundle programmers do not need to use doPrivileged calls in their implementations of any callbacks registered with and invoked by the Framework.

For any other callbacks that are registered with a service object and therefore get invoked by the service-providing bundle directly, doPrivileged calls must be used in the callback implementation if the bundle's own privileges are to be exercised. Otherwise, the callback must fail if the bundle that initiated the callback lacks the required permissions.

A framework must never load classes in a doPrivileged region, but must instead use the current stack. This means that static initializers and constructors must not assume that they are privileged. Any privileged code in a static initializer must be guarded with a doPrivileged region in the static initializer. Likewise, a framework must not instantiate a BundleActivator object in a doPrivileged region, but must instead use the current stack. This means that the BundleActivator constructor must not assume that it is privileged.

The activation policy, see Activation Policies, can indirectly cause the activation of a bundle. AdminPermission[*,CLASS ] therefore implies the EXECUTE action during a loadClass method call.

Normal class loading caused by executing Java class code must not require AdminPermission[*,EXECUTE ].