10 Framework API

10.1 org.osgi.framework

Version 1.10

Framework Package Version 1.10.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest.

Example import for consumers using the API in this package:

Import-Package: org.osgi.framework; version="[1.10,2.0)"

10.1.1 Summary

10.1.2 public final class AdaptPermission
extends BasicPermission

A bundle's authority to adapt an object to a type.

AdaptPermission has one action: adapt.

Thread-safe

10.1.2.1 public static final String ADAPT = "adapt"

The action string initiate.

10.1.2.2 public AdaptPermission(String filter, String actions)

A filter expression. Filter attribute names are processed in a case sensitive manner. A special value of "*" can be used to match all adaptations.

adapt.

Creates a new granted AdaptPermission object. This constructor must only be used to create a permission that is going to be checked.

Examples:

 (adaptClass=com.acme.*)
 (&(signer=\*,o=ACME,c=US)(adaptClass=com.acme.*))
 (signer=\*,o=ACME,c=US)

When a signer key is used within the filter expression the signer value must escape the special filter chars ('*', '(', ')').

The name is specified as a filter expression. The filter gives access to the following attributes:

  • signer - A Distinguished Name chain used to sign the exporting bundle. Wildcards in a DN are not matched according to the filter string rules, but according to the rules defined for a DN chain.

  • location - The location of the exporting bundle.

  • id - The bundle ID of the exporting bundle.

  • name - The symbolic name of the exporting bundle.

  • adaptClass - The name of the type to which an object can be adapted.

Filter attribute names are processed in a case sensitive manner.

IllegalArgumentException– If the filter has an invalid syntax.

10.1.2.3 public AdaptPermission(String adaptClass, Bundle adaptableBundle, String actions)

The name of the type to which an object can be adapted.

The bundle associated with the object being adapted.

adapt.

Creates a new requested AdaptPermission object to be used by the code that must perform checkPermission. AdaptPermission objects created with this constructor cannot be added to an AdaptPermission permission collection.

10.1.2.4 public boolean equals(Object obj)

The object to test for equality with this AdaptPermission object.

Determines the equality of two AdaptPermission objects. This method checks that specified permission has the same name and AdaptPermission actions as this AdaptPermission object.

true if obj is a AdaptPermission, and has the same name and actions as this AdaptPermission object; false otherwise.

10.1.2.5 public String getActions()

Returns the canonical string representation of the AdaptPermission actions.

Always returns present AdaptPermission actions in the following order: adapt.

Canonical string representation of the AdaptPermission actions.

10.1.2.6 public int hashCode()

Returns the hash code value for this object.

A hash code value for this object.

10.1.2.7 public boolean implies(Permission p)

The requested permission.

Determines if the specified permission is implied by this object.

This method checks that the filter of the target is implied by the adapt class name of this object. The list of AdaptPermission actions must either match or allow for the list of the target object to imply the target AdaptPermission action.

true if the specified permission is implied by this object; false otherwise.

10.1.2.8 public PermissionCollection newPermissionCollection()

Returns a new PermissionCollection object suitable for storing AdaptPermission objects.

A new PermissionCollection object.

10.1.3 public final class AdminPermission
extends BasicPermission

A bundle's authority to perform specific privileged administrative operations on or to get sensitive information about a bundle. The actions for this permission are:

 Action             Methods
 class              Bundle.loadClass
 execute            Bundle.start
                    Bundle.stop
                    BundleStartLevel.setStartLevel
 extensionLifecycle BundleContext.installBundle for extension bundles
                    Bundle.update for extension bundles
                    Bundle.uninstall for extension bundles
 lifecycle          BundleContext.installBundle
                    Bundle.update
                    Bundle.uninstall
 listener           BundleContext.addBundleListener for
                      SynchronousBundleListener
                    BundleContext.removeBundleListener for
                      SynchronousBundleListener
 metadata           Bundle.getHeaders
                    Bundle.getLocation
 resolve            FrameworkWiring.refreshBundles
                    FrameworkWiring.resolveBundles
 resource           Bundle.getResource
                    Bundle.getResources
                    Bundle.getEntry
                    Bundle.getEntryPaths
                    Bundle.findEntries
                    Bundle resource/entry URL creation
 startlevel         FrameworkStartLevel.setStartLevel
                    FrameworkStartLevel.setInitialBundleStartLevel
 context            Bundle.getBundleContext
 weave              WovenClass.getBytes
                    WovenClass.setBytes
                    WovenClass.getDynamicImports for modification

The special action "*" will represent all actions. The resolve action is implied by the class, execute and resource actions.

The name of this permission is a filter expression. The filter gives access to the following attributes:

  • signer - A Distinguished Name chain used to sign a bundle. Wildcards in a DN are not matched according to the filter string rules, but according to the rules defined for a DN chain.

  • location - The location of a bundle.

  • id - The bundle ID of the designated bundle.

  • name - The symbolic name of a bundle.

Filter attribute names are processed in a case sensitive manner.

Thread-safe

10.1.3.1 public static final String CLASS = "class"

The action string class. The class action implies the resolve action.

1.3

10.1.3.2 public static final String CONTEXT = "context"

The action string context.

1.4

10.1.3.3 public static final String EXECUTE = "execute"

The action string execute. The execute action implies the resolve action.

1.3

10.1.3.4 public static final String EXTENSIONLIFECYCLE = "extensionLifecycle"

The action string extensionLifecycle.

1.3

10.1.3.5 public static final String LIFECYCLE = "lifecycle"

The action string lifecycle.

1.3

10.1.3.6 public static final String LISTENER = "listener"

The action string listener.

1.3

10.1.3.7 public static final String METADATA = "metadata"

The action string metadata.

1.3

10.1.3.8 public static final String RESOLVE = "resolve"

The action string resolve. The resolve action is implied by the class, execute and resource actions.

1.3

10.1.3.9 public static final String RESOURCE = "resource"

The action string resource. The resource action implies the resolve action.

1.3

10.1.3.10 public static final String STARTLEVEL = "startlevel"

The action string startlevel.

1.3

10.1.3.11 public static final String WEAVE = "weave"

The action string weave.

1.6

10.1.3.12 public AdminPermission()

Creates a new AdminPermission object that matches all bundles and has all actions. Equivalent to AdminPermission("*","*");

10.1.3.13 public AdminPermission(String filter, String actions)

A filter expression that can use signer, location, id, and name keys. A value of "*" or null matches all bundle. Filter attribute names are processed in a case sensitive manner.

class, execute, extensionLifecycle , lifecycle, listener, metadata, resolve , resource, startlevel, context or weave. A value of "*" or null indicates all actions.

Create a new AdminPermission. This constructor must only be used to create a permission that is going to be checked.

Examples:

 (signer=\*,o=ACME,c=US)
 (&(signer=\*,o=ACME,c=US)(name=com.acme.*)
   (location=http://www.acme.com/bundles/*))
 (id>=1)

When a signer key is used within the filter expression the signer value must escape the special filter chars ('*', '(', ')').

Null arguments are equivalent to "*".

IllegalArgumentException– If the filter has an invalid syntax.

10.1.3.14 public AdminPermission(Bundle bundle, String actions)

A bundle.

class, execute, extensionLifecycle , lifecycle, listener, metadata, resolve , resource, startlevel, context, weave. A value of "*" or null indicates all actions.

Creates a new requested AdminPermission object to be used by the code that must perform checkPermission. AdminPermission objects created with this constructor cannot be added to an AdminPermission permission collection.

1.3

10.1.3.15 public boolean equals(Object obj)

The object being compared for equality with this object.

Determines the equality of two AdminPermission objects.

true if obj is equivalent to this AdminPermission; false otherwise.

10.1.3.16 public String getActions()

Returns the canonical string representation of the AdminPermission actions.

Always returns present AdminPermission actions in the following order: class, execute, extensionLifecycle, lifecycle, listener, metadata, resolve, resource, startlevel, context, weave.

Canonical string representation of the AdminPermission actions.

10.1.3.17 public int hashCode()

Returns the hash code value for this object.

Hash code value for this object.

10.1.3.18 public boolean implies(Permission p)

The requested permission.

Determines if the specified permission is implied by this object. This method throws an exception if the specified permission was not constructed with a bundle.

This method returns true if the specified permission is an AdminPermission AND

  • this object's filter matches the specified permission's bundle ID, bundle symbolic name, bundle location and bundle signer distinguished name chain OR

  • this object's filter is "*"

AND this object's actions include all of the specified permission's actions.

Special case: if the specified permission was constructed with "*" filter, then this method returns true if this object's filter is "*" and this object's actions include all of the specified permission's actions

true if the specified permission is implied by this object; false otherwise.

10.1.3.19 public PermissionCollection newPermissionCollection()

Returns a new PermissionCollection object suitable for storing AdminPermissions.

A new PermissionCollection object.

10.1.4 public interface AllServiceListener
extends ServiceListener

A ServiceEvent listener that does not filter based upon package wiring. AllServiceListener is a listener interface that may be implemented by a bundle developer. When a ServiceEvent is fired, it is synchronously delivered to an AllServiceListener. The Framework may deliver ServiceEvent objects to an AllServiceListener out of order and may concurrently call and/or reenter an AllServiceListener.

An AllServiceListener object is registered with the Framework using the BundleContext.addServiceListener method. AllServiceListener objects are called with a ServiceEvent object when a service is registered, modified, or is in the process of unregistering.

ServiceEvent object delivery to AllServiceListener objects is filtered by the filter specified when the listener was registered. If the Java Runtime Environment supports permissions, then additional filtering is done. ServiceEvent objects are only delivered to the listener if the bundle which defines the listener object's class has the appropriate ServicePermission to get the service using at least one of the named classes under which the service was registered.

Unlike normal ServiceListener objects, AllServiceListener objects receive all ServiceEvent objects regardless of whether the package source of the listening bundle is equal to the package source of the bundle that registered the service. This means that the listener may not be able to cast the service object to any of its corresponding service interfaces if the service object is retrieved.

ServiceEvent, ServicePermission

1.3

Thread-safe

10.1.5 public interface Bundle
extends Comparable<Bundle>

An installed bundle in the Framework.

A Bundle object is the access point to define the lifecycle of an installed bundle. Each bundle installed in the OSGi environment must have an associated Bundle object.

A bundle must have a unique identity, a long, chosen by the Framework. This identity must not change during the lifecycle of a bundle, even when the bundle is updated. Uninstalling and then reinstalling the bundle must create a new unique identity.

A bundle can be in one of six states:

Values assigned to these states have no specified ordering; they represent bit values that may be ORed together to determine if a bundle is in one of the valid states.

A bundle should only have active threads of execution when its state is one of STARTING,ACTIVE, or STOPPING. An UNINSTALLED bundle can not be set to another state; it is a zombie and can only be reached because references are kept somewhere.

The Framework is the only entity that is allowed to create Bundle objects, and these objects are only valid within the Framework that created them.

Bundles have a natural ordering such that if two Bundles have the same bundle id they are equal. A Bundle is less than another Bundle if it has a lower bundle id and is greater if it has a higher bundle id.

Thread-safe

Consumers of this API must not implement this type

10.1.5.1 public static final int ACTIVE = 32

The bundle is now running.

A bundle is in the ACTIVE state when it has been successfully started and activated.

The value of ACTIVE is 0x00000020.

10.1.5.2 public static final int INSTALLED = 2

The bundle is installed but not yet resolved.

A bundle is in the INSTALLED state when it has been installed in the Framework but is not or cannot be resolved.

This state is visible if the bundle's code dependencies are not resolved. The Framework may attempt to resolve an INSTALLED bundle's code dependencies and move the bundle to the RESOLVED state.

The value of INSTALLED is 0x00000002.

10.1.5.3 public static final int RESOLVED = 4

The bundle is resolved and is able to be started.

A bundle is in the RESOLVED state when the Framework has successfully resolved the bundle's code dependencies. These dependencies include:

Note that the bundle is not active yet. A bundle must be put in the RESOLVED state before it can be started. The Framework may attempt to resolve a bundle at any time.

The value of RESOLVED is 0x00000004.

10.1.5.4 public static final int SIGNERS_ALL = 1

Request that all certificates used to sign the bundle be returned.

getSignerCertificates(int)

1.5

10.1.5.5 public static final int SIGNERS_TRUSTED = 2

Request that only certificates used to sign the bundle that are trusted by the framework be returned.

getSignerCertificates(int)

1.5

10.1.5.6 public static final int START_ACTIVATION_POLICY = 2

The bundle start operation must activate the bundle according to the bundle's declared activation policy.

This bit may be set when calling start(int) to notify the framework that the bundle must be activated using the bundle's declared activation policy.

Constants.BUNDLE_ACTIVATIONPOLICY, start(int)

1.4

10.1.5.7 public static final int START_TRANSIENT = 1

The bundle start operation is transient and the persistent autostart setting of the bundle is not modified.

This bit may be set when calling start(int) to notify the framework that the autostart setting of the bundle must not be modified. If this bit is not set, then the autostart setting of the bundle is modified.

start(int)

1.4

10.1.5.8 public static final int STARTING = 8

The bundle is in the process of starting.

A bundle is in the STARTING state when its start method is active. A bundle must be in this state when the bundle's BundleActivator.start(BundleContext) is called. If the BundleActivator.start method completes without exception, then the bundle has successfully started and must move to the ACTIVE state.

If the bundle has a lazy activation policy, then the bundle may remain in this state for some time until the activation is triggered.

The value of STARTING is 0x00000008.

10.1.5.9 public static final int STOP_TRANSIENT = 1

The bundle stop is transient and the persistent autostart setting of the bundle is not modified.

This bit may be set when calling stop(int) to notify the framework that the autostart setting of the bundle must not be modified. If this bit is not set, then the autostart setting of the bundle is modified.

stop(int)

1.4

10.1.5.10 public static final int STOPPING = 16

The bundle is in the process of stopping.

A bundle is in the STOPPING state when its stop method is active. A bundle must be in this state when the bundle's BundleActivator.stop(BundleContext) method is called. When the BundleActivator.stop method completes the bundle is stopped and must move to the RESOLVED state.

The value of STOPPING is 0x00000010.

10.1.5.11 public static final int UNINSTALLED = 1

The bundle is uninstalled and may not be used.

The UNINSTALLED state is only visible after a bundle is uninstalled; the bundle is in an unusable state but references to the Bundle object may still be available and used for introspection.

The value of UNINSTALLED is 0x00000001.

10.1.5.12 public A adapt(Class<A> type)

<A>

The type to which this bundle is to be adapted.

Class object for the type to which this bundle is to be adapted.

Adapt this bundle to the specified type.

Adapting this bundle to the specified type may require certain checks, including security checks, to succeed. If a check does not succeed, then this bundle cannot be adapted and null is returned.

The object, of the specified type, to which this bundle has been adapted or null if this bundle cannot be adapted to the specified type.

SecurityException– If the caller does not have the appropriate AdaptPermission[type,this,ADAPT], and the Java Runtime Environment supports permissions.

1.6

10.1.5.13 public Enumeration<URL> findEntries(String path, String filePattern, boolean recurse)

The path name in which to look. The path is always relative to the root of this bundle and may begin with "/". A path value of "/" indicates the root of this bundle.

The file name pattern for selecting entries in the specified path. The pattern is only matched against the last element of the entry path. If the entry is a directory then the trailing "/" is not used for pattern matching. Substring matching is supported, as specified in the Filter specification, using the wildcard character ("*"). If null is specified, this is equivalent to "*" and matches all files.

If true, recurse into subdirectories. Otherwise only return entries from the specified path.

Returns entries in this bundle and its attached fragments. This bundle's class loader is not used to search for entries. Only the contents of this bundle and its attached fragments are searched for the specified entries. If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to find entries.

This method is intended to be used to obtain configuration, setup, localization and other information from this bundle. This method takes into account that the "contents" of this bundle can be extended with fragments. This "bundle space" is not a namespace with unique members; the same entry name can be present multiple times. This method therefore returns an enumeration of URL objects. These URLs can come from different JARs but have the same path name. This method can either return only entries in the specified path or recurse into subdirectories returning entries in the directory tree beginning at the specified path. Fragments can be attached after this bundle is resolved, possibly changing the set of URLs returned by this method. If this bundle is not resolved, only the entries in the JAR file of this bundle are returned.

Examples:

 // List all XML files in the OSGI-INF directory and below
 Enumeration e = b.findEntries("OSGI-INF", "*.xml", true);
 
 // Find a specific localization file
 Enumeration e = b.findEntries("OSGI-INF/l10n",
     "bundle_nl_DU.properties", false);
 if (e.hasMoreElements())
     return (URL) e.nextElement();

URLs for directory entries must have their path end with "/".

Note: Jar and zip files are not required to include directory entries. URLs to directory entries will not be returned if the bundle contents do not contain directory entries.

An enumeration of URL objects for each matching entry, or null if no matching entry could be found or if the caller does not have the appropriate AdminPermission[this,RESOURCE], and the Java Runtime Environment supports permissions. The URLs are sorted such that entries from this bundle are returned first followed by the entries from attached fragments in attachment order. If this bundle is a fragment, then only matching entries in this fragment are returned.

IllegalStateException– If this bundle has been uninstalled.

1.3

10.1.5.14 public BundleContext getBundleContext()

Returns this bundle's BundleContext. The returned BundleContext can be used by the caller to act on behalf of this bundle.

If this bundle is not in the STARTING, ACTIVE, or STOPPING states or this bundle is a fragment bundle, then this bundle has no valid BundleContext. This method will return null if this bundle has no valid BundleContext.

A BundleContext for this bundle or null if this bundle has no valid BundleContext.

SecurityException– If the caller does not have the appropriate AdminPermission[this,CONTEXT], and the Java Runtime Environment supports permissions.

1.4

10.1.5.15 public long getBundleId()

Returns this bundle's unique identifier. This bundle is assigned a unique identifier by the Framework when it was installed in the OSGi environment.

A bundle's unique identifier has the following attributes:

  • Is unique and persistent.

  • Is a long.

  • Its value is not reused for another bundle, even after a bundle is uninstalled.

  • Does not change while a bundle remains installed.

  • Does not change when a bundle is updated.

This method must continue to return this bundle's unique identifier while this bundle is in the UNINSTALLED state.

The unique identifier of this bundle.

10.1.5.16 public File getDataFile(String filename)

A relative name to the file to be accessed.

Creates a File object for a file in the persistent storage area provided for this bundle by the Framework. This method will return null if the platform does not have file system support or this bundle is a fragment bundle.

A File object for the base directory of the persistent storage area provided for this bundle by the Framework can be obtained by calling this method with an empty string as filename.

If the Java Runtime Environment supports permissions, the Framework will ensure that this bundle has the java.io.FilePermission with actions read,write,delete for all files (recursively) in the persistent storage area provided for this bundle.

A File object that represents the requested file or null if the platform does not have file system support or this bundle is a fragment bundle.

IllegalStateException– If this bundle has been uninstalled.

1.6

10.1.5.17 public URL getEntry(String path)

The path name of the entry.

Returns a URL to the entry at the specified path in this bundle. This bundle's class loader is not used to search for the entry. Only the contents of this bundle are searched for the entry.

The specified path is always relative to the root of this bundle and may begin with "/". A path value of "/" indicates the root of this bundle.

Note: Jar and zip files are not required to include directory entries. URLs to directory entries will not be returned if the bundle contents do not contain directory entries.

A URL to the entry, or null if no entry could be found or if the caller does not have the appropriate AdminPermission[this,RESOURCE] and the Java Runtime Environment supports permissions.

IllegalStateException– If this bundle has been uninstalled.

1.3

10.1.5.18 public Enumeration<String> getEntryPaths(String path)

The path name for which to return entry paths.

Returns an Enumeration of all the paths (String objects) to entries within this bundle whose longest sub-path matches the specified path. This bundle's class loader is not used to search for entries. Only the contents of this bundle are searched.

The specified path is always relative to the root of this bundle and may begin with a "/". A path value of "/" indicates the root of this bundle.

Returned paths indicating subdirectory paths end with a "/". The returned paths are all relative to the root of this bundle and must not begin with "/".

Note: Jar and zip files are not required to include directory entries. Paths to directory entries will not be returned if the bundle contents do not contain directory entries.

An Enumeration of the entry paths (String objects) or null if no entry could be found or if the caller does not have the appropriate AdminPermission[this,RESOURCE] and the Java Runtime Environment supports permissions.

IllegalStateException– If this bundle has been uninstalled.

1.3

10.1.5.19 public Dictionary<String, String> getHeaders()

Returns this bundle's Manifest headers and values. This method returns all the Manifest headers and values from the main section of this bundle's Manifest file; that is, all lines prior to the first blank line.

Manifest header names are case-insensitive. The methods of the returned Dictionary object must operate on header names in a case-insensitive manner. If a Manifest header value starts with "%", it must be localized according to the default locale. If no localization is found for a header value, the header value without the leading "%" is returned.

For example, the following Manifest headers and values are included if they are present in the Manifest file:

     Bundle-Name
     Bundle-Vendor
     Bundle-Version
     Bundle-Description
     Bundle-DocURL
     Bundle-ContactAddress

This method must continue to return Manifest header information while this bundle is in the UNINSTALLED state.

An unmodifiable Dictionary object containing this bundle's Manifest headers and values.

SecurityException– If the caller does not have the appropriate AdminPermission[this,METADATA], and the Java Runtime Environment supports permissions.

Constants.BUNDLE_LOCALIZATION

10.1.5.20 public Dictionary<String, String> getHeaders(String locale)

The locale name into which the header values are to be localized. If the specified locale is null then the locale returned by java.util.Locale.getDefault is used. If the specified locale is the empty string, this method will return the raw (unlocalized) manifest headers including any leading "%".

Returns this bundle's Manifest headers and values localized to the specified locale.

This method performs the same function as Bundle.getHeaders() except the manifest header values are localized to the specified locale.

If a Manifest header value starts with "%", it must be localized according to the specified locale. If a locale is specified and cannot be found, then the header values must be returned using the default locale. Localizations are searched for in the following order:

   bn + "_" + Ls + "_" + Cs + "_" + Vs
   bn + "_" + Ls + "_" + Cs
   bn + "_" + Ls
   bn + "_" + Ld + "_" + Cd + "_" + Vd
   bn + "_" + Ld + "_" + Cd
   bn + "_" + Ld
   bn

Where bn is this bundle's localization basename, Ls, Cs and Vs are the specified locale (language, country, variant) and Ld, Cd and Vd are the default locale (language, country, variant). If null is specified as the locale string, the header values must be localized using the default locale. If the empty string ("") is specified as the locale string, the header values must not be localized and the raw (unlocalized) header values, including any leading "%", must be returned. If no localization is found for a header value, the header value without the leading "%" is returned.

This method must continue to return Manifest header information while this bundle is in the UNINSTALLED state, however the header values must only be available in the raw and default locale values.

An unmodifiable Dictionary object containing this bundle's Manifest headers and values.

SecurityException– If the caller does not have the appropriate AdminPermission[this,METADATA], and the Java Runtime Environment supports permissions.

getHeaders(), Constants.BUNDLE_LOCALIZATION

1.3

10.1.5.21 public long getLastModified()

Returns the time when this bundle was last modified. A bundle is considered to be modified when it is installed, updated or uninstalled.

The time value is the number of milliseconds since January 1, 1970, 00:00:00 UTC.

The time when this bundle was last modified.

1.3

10.1.5.22 public String getLocation()

Returns this bundle's location identifier.

The location identifier is the location passed to BundleContext.installBundle when a bundle is installed. The location identifier does not change while this bundle remains installed, even if this bundle is updated.

This method must continue to return this bundle's location identifier while this bundle is in the UNINSTALLED state.

The string representation of this bundle's location identifier.

SecurityException– If the caller does not have the appropriate AdminPermission[this,METADATA], and the Java Runtime Environment supports permissions.

10.1.5.23 public ServiceReference<?>[] getRegisteredServices()

Returns this bundle's ServiceReference list for all services it has registered or null if this bundle has no registered services.

If the Java runtime supports permissions, a ServiceReference object to a service is included in the returned list only if the caller has the ServicePermission to get the service using at least one of the named classes the service was registered under.

The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

An array of ServiceReference objects or null.

IllegalStateException– If this bundle has been uninstalled.

ServiceRegistration, ServiceReference, ServicePermission

10.1.5.24 public URL getResource(String name)

The name of the resource. See ClassLoader.getResource for a description of the format of a resource name.

Find the specified resource from this bundle's class loader. This bundle's class loader is called to search for the specified resource. If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to get the specified resource. If this bundle cannot be resolved, then only this bundle must be searched for the specified resource. Imported packages cannot be searched when this bundle has not been resolved. If this bundle is a fragment bundle then null is returned.

Note: Jar and zip files are not required to include directory entries. URLs to directory entries will not be returned if the bundle contents do not contain directory entries.

A URL to the named resource, or null if the resource could not be found or if this bundle is a fragment bundle or if the caller does not have the appropriate AdminPermission[this,RESOURCE], and the Java Runtime Environment supports permissions.

IllegalStateException– If this bundle has been uninstalled.

getEntry(String), findEntries(String, String, boolean)

1.1

10.1.5.25 public Enumeration<URL> getResources(String name) throws IOException

The name of the resource. See ClassLoader.getResources for a description of the format of a resource name.

Find the specified resources from this bundle's class loader. This bundle's class loader is called to search for the specified resources. If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to get the specified resources. If this bundle cannot be resolved, then only this bundle must be searched for the specified resources. Imported packages cannot be searched when a bundle has not been resolved. If this bundle is a fragment bundle then null is returned.

Note: Jar and zip files are not required to include directory entries. URLs to directory entries will not be returned if the bundle contents do not contain directory entries.

An enumeration of URLs to the named resources, or null if the resource could not be found or if this bundle is a fragment bundle or if the caller does not have the appropriate AdminPermission[this,RESOURCE], and the Java Runtime Environment supports permissions.

IllegalStateException– If this bundle has been uninstalled.

IOException– If there is an I/O error.

1.3

10.1.5.26 public ServiceReference<?>[] getServicesInUse()

Returns this bundle's ServiceReference list for all services it is using or returns null if this bundle is not using any services. A bundle is considered to be using a service if it has any unreleased service objects.

If the Java Runtime Environment supports permissions, a ServiceReference object to a service is included in the returned list only if the caller has the ServicePermission to get the service using at least one of the named classes the service was registered under.

The list is valid at the time of the call to this method, however, as the Framework is a very dynamic environment, services can be modified or unregistered at anytime.

An array of ServiceReference objects or null.

IllegalStateException– If this bundle has been uninstalled.

ServiceReference, ServicePermission

10.1.5.27 public Map<X509Certificate, List<X509Certificate>> getSignerCertificates(int signersType)

If SIGNERS_ALL is specified, then information on all signers of this bundle is returned. If SIGNERS_TRUSTED is specified, then only information on the signers of this bundle trusted by the framework is returned.

Return the certificates for the signers of this bundle and the certificate chains for those signers.

The X509Certificates for the signers of this bundle and the X509Certificate chains for those signers. The keys of the Map are the X509Certificates of the signers of this bundle. The value for a key is a List containing the X509Certificate chain for the signer. The first item in the List is the signer's X509Certificate which is then followed by the rest of the X509Certificate chain. The returned Map will be empty if there are no signers. The returned Map is the property of the caller who is free to modify it.

IllegalArgumentException– If the specified signersType is not SIGNERS_ALL or SIGNERS_TRUSTED.

1.5

10.1.5.28 public int getState()

Returns this bundle's current state.

A bundle can be in only one state at any time.

An element of UNINSTALLED,INSTALLED, RESOLVED, STARTING, STOPPING, ACTIVE.

10.1.5.29 public String getSymbolicName()

Returns the symbolic name of this bundle as specified by its Bundle-SymbolicName manifest header. The bundle symbolic name should be based on the reverse domain name naming convention like that used for java packages.

This method must continue to return this bundle's symbolic name while this bundle is in the UNINSTALLED state.

The symbolic name of this bundle or null if this bundle does not have a symbolic name.

1.3

10.1.5.30 public Version getVersion()

Returns the version of this bundle as specified by its Bundle-Version manifest header. If this bundle does not have a specified version then Version.emptyVersion is returned.

This method must continue to return this bundle's version while this bundle is in the UNINSTALLED state.

The version of this bundle.

1.5

10.1.5.31 public boolean hasPermission(Object permission)

The permission to verify.

Determines if this bundle has the specified permissions.

If the Java Runtime Environment does not support permissions, this method always returns true.

permission is of type Object to avoid referencing the java.security.Permission class directly. This is to allow the Framework to be implemented in Java environments which do not support permissions.

If the Java Runtime Environment does support permissions, this bundle and all its resources including embedded JAR files, belong to the same java.security.ProtectionDomain; that is, they must share the same set of permissions.

true if this bundle has the specified permission or the permissions possessed by this bundle imply the specified permission; false if this bundle does not have the specified permission or permission is not an instanceof java.security.Permission.

IllegalStateException– If this bundle has been uninstalled.

10.1.5.32 public Class<?> loadClass(String name) throws ClassNotFoundException

The name of the class to load.

Loads the specified class using this bundle's class loader.

If this bundle is a fragment bundle then this method must throw a ClassNotFoundException.

If this bundle's state is INSTALLED, this method must attempt to resolve this bundle before attempting to load the class.

If this bundle cannot be resolved, a Framework event of type FrameworkEvent.ERROR is fired containing a BundleException with details of the reason this bundle could not be resolved. This method must then throw a ClassNotFoundException.

If this bundle's state is UNINSTALLED, then an IllegalStateException is thrown.

The Class object for the requested class.

ClassNotFoundException– If no such class can be found or if this bundle is a fragment bundle or if the caller does not have the appropriate AdminPermission[this,CLASS], and the Java Runtime Environment supports permissions.

IllegalStateException– If this bundle has been uninstalled.

1.3

10.1.5.33 public void start(int options) throws BundleException

The options for starting this bundle. See START_TRANSIENT and START_ACTIVATION_POLICY. The Framework must ignore unrecognized options.

Starts this bundle.

If this bundle's state is UNINSTALLED then an IllegalStateException is thrown.

If the current start level is less than this bundle's start level:

  • If the START_TRANSIENT option is set, then a BundleException is thrown indicating this bundle cannot be started due to the Framework's current start level.

  • Otherwise, the Framework must set this bundle's persistent autostart setting to Started with declared activation if the START_ACTIVATION_POLICY option is set or Started with eager activation if not set.

When the Framework's current start level becomes equal to or more than this bundle's start level, this bundle will be started.

Otherwise, the following steps are required to start this bundle:

  1. If this bundle is in the process of being activated or deactivated then this method must wait for activation or deactivation to complete before continuing. If this does not occur in a reasonable time, a BundleException is thrown to indicate this bundle was unable to be started.

  2. If the START_TRANSIENT option is not set then set this bundle's autostart setting to Started with declared activation if the START_ACTIVATION_POLICY option is set or Started with eager activation if not set. When the Framework is restarted and this bundle's autostart setting is not Stopped, this bundle must be automatically started.

  3. If this bundle's state is ACTIVE then this method returns immediately.

  4. If this bundle's state is not RESOLVED, an attempt is made to resolve this bundle. If the Framework cannot resolve this bundle, a BundleException is thrown.

  5. If the START_ACTIVATION_POLICY option is set and this bundle's declared activation policy is lazy then:

    • If this bundle's state is STARTING then this method returns immediately.

    • This bundle's state is set to STARTING.

    • A bundle event of type BundleEvent.LAZY_ACTIVATION is fired.

    • This method returns immediately and the remaining steps will be followed when this bundle's activation is later triggered.

  6. This bundle's state is set to STARTING.

  7. A bundle event of type BundleEvent.STARTING is fired.

  8. The BundleActivator.start(BundleContext) method of this bundle's BundleActivator, if one is specified, is called. If the BundleActivator is invalid or throws an exception then:

    • This bundle's state is set to STOPPING.

    • A bundle event of type BundleEvent.STOPPING is fired.

    • Any services registered by this bundle must be unregistered.

    • Any services used by this bundle must be released.

    • Any listeners registered by this bundle must be removed.

    • This bundle's state is set to RESOLVED.

    • A bundle event of type BundleEvent.STOPPED is fired.

    • A BundleException is then thrown.

  9. This bundle's state is set to ACTIVE.

  10. A bundle event of type BundleEvent.STARTED is fired.

Preconditions

  • getState() in { INSTALLED, RESOLVED } or { INSTALLED, RESOLVED, STARTING } if this bundle has a lazy activation policy.

Postconditions, no exceptions thrown

  • Bundle autostart setting is modified unless the START_TRANSIENT option was set.

  • getState() in { ACTIVE } unless the lazy activation policy was used.

  • BundleActivator.start() has been called and did not throw an exception unless the lazy activation policy was used.

Postconditions, when an exception is thrown

  • Depending on when the exception occurred, bundle autostart setting is modified unless the START_TRANSIENT option was set.

  • getState() not in { STARTING, ACTIVE }.

BundleException– If this bundle could not be started. BundleException types thrown by this method include: BundleException.START_TRANSIENT_ERROR, BundleException.NATIVECODE_ERROR, BundleException.RESOLVE_ERROR, BundleException.STATECHANGE_ERROR, and BundleException.ACTIVATOR_ERROR.

IllegalStateException– If this bundle has been uninstalled.

SecurityException– If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

1.4

10.1.5.34 public void start() throws BundleException

Starts this bundle with no options.

This method performs the same function as calling start(0).

BundleException– If this bundle could not be started. BundleException types thrown by this method include: BundleException.NATIVECODE_ERROR, BundleException.RESOLVE_ERROR, BundleException.STATECHANGE_ERROR, and BundleException.ACTIVATOR_ERROR.

IllegalStateException– If this bundle has been uninstalled.

SecurityException– If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

start(int)

10.1.5.35 public void stop(int options) throws BundleException

The options for stopping this bundle. See STOP_TRANSIENT. The Framework must ignore unrecognized options.

Stops this bundle.

The following steps are required to stop a bundle:

  1. If this bundle's state is UNINSTALLED then an IllegalStateException is thrown.

  2. If this bundle is in the process of being activated or deactivated then this method must wait for activation or deactivation to complete before continuing. If this does not occur in a reasonable time, a BundleException is thrown to indicate this bundle was unable to be stopped.

  3. If the STOP_TRANSIENT option is not set then set this bundle's persistent autostart setting to Stopped. When the Framework is restarted and this bundle's autostart setting is Stopped, this bundle must not be automatically started.

  4. If this bundle's state is not STARTING or ACTIVE then this method returns immediately.

  5. This bundle's state is set to STOPPING.

  6. A bundle event of type BundleEvent.STOPPING is fired.

  7. If this bundle's state was ACTIVE prior to setting the state to STOPPING, the BundleActivator.stop(BundleContext) method of this bundle's BundleActivator, if one is specified, is called. If that method throws an exception, this method must continue to stop this bundle and a BundleException must be thrown after completion of the remaining steps.

  8. Any services registered by this bundle must be unregistered.

  9. Any services used by this bundle must be released.

  10. Any listeners registered by this bundle must be removed.

  11. If this bundle's state is UNINSTALLED, because this bundle was uninstalled while the BundleActivator.stop method was running, a BundleException must be thrown.

  12. This bundle's state is set to RESOLVED.

  13. A bundle event of type BundleEvent.STOPPED is fired.

Preconditions

  • getState() in { ACTIVE }.

Postconditions, no exceptions thrown

  • Bundle autostart setting is modified unless the STOP_TRANSIENT option was set.

  • getState() not in { ACTIVE, STOPPING }.

  • BundleActivator.stop has been called and did not throw an exception.

Postconditions, when an exception is thrown

  • Bundle autostart setting is modified unless the STOP_TRANSIENT option was set.

BundleException– BundleException types thrown by this method include: BundleException.STATECHANGE_ERROR and BundleException.ACTIVATOR_ERROR.

IllegalStateException– If this bundle has been uninstalled.

SecurityException– If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

1.4

10.1.5.36 public void stop() throws BundleException

Stops this bundle with no options.

This method performs the same function as calling stop(0).

BundleException– BundleException types thrown by this method include: BundleException.STATECHANGE_ERROR and BundleException.ACTIVATOR_ERROR.

IllegalStateException– If this bundle has been uninstalled.

SecurityException– If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

start(int)

10.1.5.37 public void uninstall() throws BundleException

Uninstalls this bundle.

This method causes the Framework to notify other bundles that this bundle is being uninstalled, and then puts this bundle into the UNINSTALLED state. The Framework must remove any resources related to this bundle that it is able to remove.

If this bundle has exported any packages, the Framework must continue to make these packages available to their importing bundles until the FrameworkWiring.refreshBundles method has been called or the Framework is relaunched.

The following steps are required to uninstall a bundle:

  1. If this bundle's state is UNINSTALLED, then this method does nothing and returns.

  2. If this bundle's state is ACTIVE, STARTING or STOPPING, this bundle is stopped as described in the Bundle.stop method. If Bundle.stop throws an exception, a Framework event of type FrameworkEvent.ERROR is fired containing the exception.

  3. This bundle's state is set to UNINSTALLED.

  4. A bundle event of type BundleEvent.UNINSTALLED is fired.

  5. This bundle and any persistent storage area provided for this bundle by the Framework are removed.

Preconditions

  • getState() not in { UNINSTALLED }.

Postconditions, no exceptions thrown

  • getState() in { UNINSTALLED }.

  • This bundle has been uninstalled.

Postconditions, when an exception is thrown

  • getState() not in { UNINSTALLED }.

  • This Bundle has not been uninstalled.

BundleException– If the uninstall failed. This can occur if another thread is attempting to change this bundle's state and does not complete in a timely manner. BundleException types thrown by this method include: BundleException.STATECHANGE_ERROR

SecurityException– If the caller does not have the appropriate AdminPermission[this,LIFECYCLE], and the Java Runtime Environment supports permissions.

stop()

10.1.5.38 public void update(InputStream input) throws BundleException

The InputStream from which to read the new bundle or null to indicate the Framework must create the input stream from this bundle's Bundle-UpdateLocation Manifest header, if present, or this bundle's original location. The input stream must always be closed when this method completes, even if an exception is thrown.

Updates this bundle from an InputStream.

If the specified InputStream is null, the Framework must create the InputStream from which to read the updated bundle by interpreting, in an implementation dependent manner, this bundle's Bundle-UpdateLocation Manifest header, if present, or this bundle's original location.

If this bundle's state is ACTIVE, it must be stopped before the update and started after the update successfully completes.

If this bundle has exported any packages that are imported by another bundle, these packages must remain exported until the FrameworkWiring.refreshBundles method has been has been called or the Framework is relaunched.

The following steps are required to update a bundle:

  1. If this bundle's state is UNINSTALLED then an IllegalStateException is thrown.

  2. If this bundle's state is ACTIVE, STARTING or STOPPING, this bundle is stopped as described in the Bundle.stop method. If Bundle.stop throws an exception, the exception is rethrown terminating the update.

  3. The updated version of this bundle is read from the input stream and installed. If the Framework is unable to install the updated version of this bundle, the original version of this bundle must be restored and a BundleException must be thrown after completion of the remaining steps.

  4. This bundle's state is set to INSTALLED.

  5. If the updated version of this bundle was successfully installed, a bundle event of type BundleEvent.UPDATED is fired.

  6. If this bundle's state was originally ACTIVE, the updated bundle is started as described in the Bundle.start method. If Bundle.start throws an exception, a Framework event of type FrameworkEvent.ERROR is fired containing the exception.

Preconditions

  • getState() not in { UNINSTALLED }.

Postconditions, no exceptions thrown

  • getState() in { INSTALLED, RESOLVED, ACTIVE }.

  • This bundle has been updated.

Postconditions, when an exception is thrown

  • getState() in { INSTALLED, RESOLVED, ACTIVE }.

  • Original bundle is still used; no update occurred.

BundleException– If this bundle could not be updated. BundleException types thrown by this method include: BundleException.READ_ERROR, BundleException.DUPLICATE_BUNDLE_ERROR, BundleException.MANIFEST_ERROR, BundleException.NATIVECODE_ERROR, BundleException.RESOLVE_ERROR, BundleException.STATECHANGE_ERROR, and BundleException.ACTIVATOR_ERROR.

IllegalStateException– If this bundle has been uninstalled.

SecurityException– If the caller does not have the appropriate AdminPermission[this,LIFECYCLE] for both the current bundle and the updated bundle, and the Java Runtime Environment supports permissions.

stop(), start()

10.1.5.39 public void update() throws BundleException

Updates this bundle.

This method performs the same function as calling update(InputStream) with a null InputStream.

BundleException– If this bundle could not be updated. BundleException types thrown by this method include: BundleException.READ_ERROR, BundleException.DUPLICATE_BUNDLE_ERROR, BundleException.MANIFEST_ERROR, BundleException.NATIVECODE_ERROR, BundleException.RESOLVE_ERROR, BundleException.STATECHANGE_ERROR, and BundleException.ACTIVATOR_ERROR.

IllegalStateException– If this bundle has been uninstalled.

SecurityException– If the caller does not have the appropriate AdminPermission[this,LIFECYCLE] for both the current bundle and the updated bundle, and the Java Runtime Environment supports permissions.

update(InputStream)

10.1.6 public interface BundleActivator

Customizes the starting and stopping of a bundle.

BundleActivator is an interface that may be implemented when a bundle is started or stopped. The Framework can create instances of a bundle's BundleActivator as required. If an instance's BundleActivator.start method executes successfully, it is guaranteed that the same instance's BundleActivator.stop method will be called when the bundle is to be stopped. The Framework must not concurrently call a BundleActivator object.

BundleActivator is specified through the Bundle-Activator Manifest header. A bundle can only specify a single BundleActivator in the Manifest file. Fragment bundles must not have a BundleActivator. The form of the Manifest header is:

Bundle-Activator: class-name

where class-name is a fully qualified Java classname.

The specified BundleActivator class must have a public constructor that takes no parameters so that a BundleActivator object can be created by Class.newInstance().

Not Thread-safe

10.1.6.1 public void start(BundleContext context) throws Exception

The execution context of the bundle being started.

Called when this bundle is started so the Framework can perform the bundle-specific activities necessary to start this bundle. This method can be used to register services or to allocate any resources that this bundle needs.

This method must complete and return to its caller in a timely manner.

Exception– If this method throws an exception, this bundle is marked as stopped and the Framework will remove this bundle's listeners, unregister all services registered by this bundle, and release all services used by this bundle.

10.1.6.2 public void stop(BundleContext context) throws Exception

The execution context of the bundle being stopped.

Called when this bundle is stopped so the Framework can perform the bundle-specific activities necessary to stop the bundle. In general, this method should undo the work that the BundleActivator.start method started. There should be no active threads that were started by this bundle when this bundle returns. A stopped bundle must not call any Framework objects.

This method must complete and return to its caller in a timely manner.

Exception– If this method throws an exception, the bundle is still marked as stopped, and the Framework will remove the bundle's listeners, unregister all services registered by the bundle, and release all services used by the bundle.

10.1.7 public interface BundleContext
extends BundleReference

A bundle's execution context within the Framework. The context is used to grant access to other methods so that this bundle can interact with the Framework.

BundleContext methods allow a bundle to:

  • Subscribe to events published by the Framework.

  • Register service objects with the Framework service registry.

  • Retrieve ServiceReferences from the Framework service registry.

  • Get and release service objects for a referenced service.

  • Install new bundles in the Framework.

  • Get the list of bundles installed in the Framework.

  • Get the Bundle object for a bundle.

  • Create File objects for files in a persistent storage area provided for the bundle by the Framework.

A BundleContext object will be created for a bundle when the bundle is started. The Bundle object associated with a BundleContext object is called the context bundle.

The BundleContext object will be passed to the BundleActivator.start(BundleContext) method during activation of the context bundle. The same BundleContext object will be passed to the BundleActivator.stop(BundleContext) method when the context bundle is stopped. A BundleContext object is generally for the private use of its associated bundle and is not meant to be shared with other bundles in the OSGi environment.

The BundleContext object is only valid during the execution of its context bundle; that is, during the period from when the context bundle is in the STARTING, STOPPING, and ACTIVE bundle states. However, the BundleContext object becomes invalid after BundleActivator.stop(BundleContext) returns (if the bundle has a Bundle Activator). The BundleContext object becomes invalid before disposing of any remaining registered services and releasing any remaining services in use. Since those activities can result in other bundles being called (for example, ServiceListeners for ServiceEvent.UNREGISTERING events and ServiceFactorys for unget operations), those other bundles can observe the stopping bundle in the STOPPING state but with an invalid BundleContext object. The BundleContext object must never be reused after its context bundle is stopped.

Two BundleContext objects are equal if they both refer to the same execution context of a bundle. The Framework is the only entity that can create BundleContext objects and they are only valid within the Framework that created them.

A Bundle can be adapted to its BundleContext. In order for this to succeed, the caller must have the appropriate AdminPermission[bundle,CONTEXT] if the Java Runtime Environment supports permissions.

Thread-safe

Consumers of this API must not implement this type

10.1.7.1 public void addBundleListener(BundleListener listener)

The BundleListener to be added.

Adds the specified BundleListener object to the context bundle's list of listeners if not already present. BundleListener objects are notified when a bundle has a lifecycle state change.

If the context bundle's list of listeners already contains a listener l such that (l==listener), this method does nothing.

IllegalStateException– If this BundleContext is no longer valid.

SecurityException– If listener is a SynchronousBundleListener and the caller does not have the appropriate AdminPermission[context bundle,LISTENER], and the Java Runtime Environment supports permissions.

BundleEvent, BundleListener

10.1.7.2 public void addFrameworkListener(FrameworkListener listener)

The FrameworkListener object to be added.

Adds the specified FrameworkListener object to the context bundle's list of listeners if not already present. FrameworkListeners are notified of general Framework events.

If the context bundle's list of listeners already contains a listener l such that (l==listener), this method does nothing.

IllegalStateException– If this BundleContext is no longer valid.

FrameworkEvent, FrameworkListener

10.1.7.3 public void addServiceListener(ServiceListener listener, String filter)

The ServiceListener object to be added.

The filter criteria.

Adds the specified ServiceListener object with the specified filter to the context bundle's list of listeners. See Filter for a description of the filter syntax. ServiceListener objects are notified when a service has a lifecycle state change.

If the context bundle's list of listeners already contains a listener l such that (l==listener), then this method replaces that listener's filter (which may be null) with the specified one (which may be null).

The listener is called if the filter criteria is met. To filter based upon the class of the service, the filter should reference the Constants.OBJECTCLASS property. If filter is null , all services are considered to match the filter.

When using a filter, it is possible that the ServiceEvent s for the complete lifecycle of a service will not be delivered to the listener. For example, if the filter only matches when the property x has the value 1, the listener will not be called if the service is registered with the property x not set to the value 1. Subsequently, when the service is modified setting property x to the value 1, the filter will match and the listener will be called with a ServiceEvent of type MODIFIED. Thus, the listener will not be called with a ServiceEvent of type REGISTERED.

If the Java Runtime Environment supports permissions, the ServiceListener object will be notified of a service event only if the bundle that is registering it has the ServicePermission to get the service using at least one of the named classes the service was registered under.

InvalidSyntaxException– If filter contains an invalid filter string that cannot be parsed.

IllegalStateException– If this BundleContext is no longer valid.

ServiceEvent, ServiceListener, ServicePermission

10.1.7.4 public void addServiceListener(ServiceListener listener)

The ServiceListener object to be added.

Adds the specified ServiceListener object to the context bundle's list of listeners.

This method is the same as calling BundleContext.addServiceListener(ServiceListener listener, String filter) with filter set to null.

IllegalStateException– If this BundleContext is no longer valid.

addServiceListener(ServiceListener, String)

10.1.7.5 public Filter createFilter(String filter)

The filter string.

Creates a Filter object. This Filter object may be used to match a ServiceReference object or a Dictionary object.

If the filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

A Filter object encapsulating the filter string.

InvalidSyntaxException– If filter contains an invalid filter string that cannot be parsed.

NullPointerException– If filter is null.

Framework specification for a description of the filter string syntax., FrameworkUtil.createFilter(String)

1.1

10.1.7.6 public ServiceReference<?>[] getAllServiceReferences(String clazz, String filter)

The class name with which the service was registered or null for all services.

The filter expression or null for all services.

Returns an array of ServiceReference objects. The returned array of ServiceReference objects contains services that were registered under the specified class and match the specified filter expression.

The list is valid at the time of the call to this method. However since the Framework is a very dynamic environment, services can be modified or unregistered at any time.

The specified filter expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See Filter for a description of the filter syntax. If the specified filter is null, all registered services are considered to match the filter. If the specified filter expression cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

The result is an array of ServiceReference objects for all services that meet all of the following conditions:

  • If the specified class name, clazz, is not null, the service must have been registered with the specified class name. The complete list of class names with which a service was registered is available from the service's objectClass property.

  • If the specified filter is not null, the filter expression must match the service.

  • If the Java Runtime Environment supports permissions, the caller must have ServicePermission with the GET action for at least one of the class names under which the service was registered.

An array of ServiceReference objects or null if no services are registered which satisfy the search. There is no guarantee that the ServiceReference objects in the array will be in any specific order.

InvalidSyntaxException– If the specified filter contains an invalid filter expression that cannot be parsed.

IllegalStateException– If this BundleContext is no longer valid.

1.3

10.1.7.7 public Bundle getBundle()

Returns the Bundle object associated with this BundleContext. This bundle is called the context bundle.

The Bundle object associated with this BundleContext.

10.1.7.8 public Bundle getBundle(long id)

The identifier of the bundle to retrieve.

Returns the bundle with the specified identifier.

A Bundle object or null if the identifier does not match any installed bundle.

IllegalStateException– If this BundleContext is no longer valid.

10.1.7.9 public Bundle getBundle(String location)

The location of the bundle to retrieve.

Returns the bundle with the specified location.

A Bundle object or null if the location does not match any installed bundle.

IllegalStateException– If this BundleContext is no longer valid.

1.6

10.1.7.10 public Bundle[] getBundles()

Returns a list of all installed bundles.

This method returns a list of all bundles installed in the OSGi environment at the time of the call to this method. However, since the Framework is a very dynamic environment, bundles can be installed or uninstalled at anytime.

An array of Bundle objects, one object per installed bundle.

IllegalStateException– If this BundleContext is no longer valid.

10.1.7.11 public File getDataFile(String filename)

A relative name to the file to be accessed.

Creates a File object for a file in the persistent storage area provided for the bundle by the Framework. This method will return null if the platform does not have file system support.

A File object for the base directory of the persistent storage area provided for the context bundle by the Framework can be obtained by calling this method with an empty string as filename.

If the Java Runtime Environment supports permissions, the Framework will ensure that the bundle has the java.io.FilePermission with actions read,write,delete for all files (recursively) in the persistent storage area provided for the context bundle.

A File object that represents the requested file or null if the platform does not have file system support.

IllegalStateException– If this BundleContext is no longer valid.

10.1.7.12 public String getProperty(String key)

The name of the requested property.

Returns the value of the specified property. If the key is not found in the Framework properties, the system properties are then searched. The method returns null if the property is not found.

All bundles must have permission to read properties whose names start with "org.osgi.".

The value of the requested property, or null if the property is undefined.

SecurityException– If the caller does not have the appropriate PropertyPermission to read the property, and the Java Runtime Environment supports permissions.

10.1.7.13 public S getService(ServiceReference<S> reference)

<S>

Type of Service.

A reference to the service.

Returns the service object for the service referenced by the specified ServiceReference object.

A bundle's use of a service object obtained from this method is tracked by the bundle's use count of that service. Each time the service object is returned by getService(ServiceReference) the context bundle's use count for the service is incremented by one. Each time the service object is released by ungetService(ServiceReference) the context bundle's use count for the service is decremented by one.

When a bundle's use count for the service drops to zero, the bundle should no longer use the service object.

This method will always return null when the service associated with the specified reference has been unregistered.

The following steps are required to get the service object:

  1. If the service has been unregistered, null is returned.

  2. If the context bundle's use count for the service is currently zero and the service has bundle or prototype scope, the ServiceFactory.getService(Bundle, ServiceRegistration) method is called to supply the service object for the context bundle. If the service object returned by the ServiceFactory object is null, not an instanceof all the classes named when the service was registered or the ServiceFactory object throws an exception or will be recursively called for the context bundle, null is returned and a Framework event of type FrameworkEvent.ERROR containing a ServiceException describing the error is fired. The supplied service object is cached by the Framework. While the context bundle's use count for the service is greater than zero, subsequent calls to get the service object for the context bundle will return the cached service object.

  3. The context bundle's use count for the service is incremented by one.

  4. The service object for the service is returned.

A service object for the service associated with reference or null if the service is not registered, the service object returned by a ServiceFactory does not implement the classes under which it was registered or the ServiceFactory threw an exception.

SecurityException– If the caller does not have the ServicePermission to get the service using at least one of the named classes the service was registered under and the Java Runtime Environment supports permissions.

IllegalStateException– If this BundleContext is no longer valid.

IllegalArgumentException– If the specified ServiceReference was not created by the same framework instance as this BundleContext.

ungetService(ServiceReference), ServiceFactory

10.1.7.14 public ServiceObjects<S> getServiceObjects(ServiceReference<S> reference)

<S>

Type of Service.

A reference to the service.

Returns the ServiceObjects object for the service referenced by the specified ServiceReference object.

The ServiceObjects object can be used to obtain multiple service objects for services with prototype scope.

For services with singleton or bundle scope, the ServiceObjects.getService() method behaves the same as the getService(ServiceReference) method and the ServiceObjects.ungetService(Object) method behaves the same as the ungetService(ServiceReference) method. That is, only one, use-counted service object is available from the ServiceObjects object.

This method will always return null when the service associated with the specified reference has been unregistered.

A ServiceObjects object for the service associated with the specified reference or null if the service is not registered.

SecurityException– If the caller does not have the ServicePermission to get the service using at least one of the named classes the service was registered under and the Java Runtime Environment supports permissions.

IllegalStateException– If this BundleContext is no longer valid.

IllegalArgumentException– If the specified ServiceReference was not created by the same framework instance as this BundleContext.

PrototypeServiceFactory

1.8

10.1.7.15 public ServiceReference<?> getServiceReference(String clazz)

The class name with which the service was registered.

Returns a ServiceReference object for a service that implements and was registered under the specified class.

The returned ServiceReference object is valid at the time of the call to this method. However as the Framework is a very dynamic environment, services can be modified or unregistered at any time.

This method is the same as calling getServiceReferences(String, String) with a null filter expression and then finding the reference with the highest priority. It is provided as a convenience for when the caller is interested in any service that implements the specified class.

If multiple such services exist, the service that is first in the ranking order is returned.

A ServiceReference object, or null if no services are registered which implement the named class.

IllegalStateException– If this BundleContext is no longer valid.

getServiceReferences(String, String)

10.1.7.16 public ServiceReference<S> getServiceReference(Class<S> clazz)

<S>

Type of Service.

The class under whose name the service was registered. Must not be null.

Returns a ServiceReference object for a service that implements and was registered under the name of the specified class.

The returned ServiceReference object is valid at the time of the call to this method. However as the Framework is a very dynamic environment, services can be modified or unregistered at any time.

This method is the same as calling getServiceReferences(Class, String) with a null filter expression. It is provided as a convenience for when the caller is interested in any service that implements the specified class.

If multiple such services exist, the service that is first in the ranking order is returned.

A ServiceReference object, or null if no services are registered which implement the specified class.

IllegalStateException– If this BundleContext is no longer valid.

getServiceReferences(Class, String)

1.6

10.1.7.17 public ServiceReference<?>[] getServiceReferences(String clazz, String filter)

The class name with which the service was registered or null for all services.

The filter expression or null for all services.

Returns an array of ServiceReference objects. The returned array of ServiceReference objects contains services that were registered under the specified class, match the specified filter expression, and the packages for the class names under which the services were registered match the context bundle's packages as defined in ServiceReference.isAssignableTo(Bundle, String).

The list is valid at the time of the call to this method. However since the Framework is a very dynamic environment, services can be modified or unregistered at any time.

The specified filter expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See Filter for a description of the filter syntax. If the specified filter is null, all registered services are considered to match the filter. If the specified filter expression cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

The result is an array of ServiceReference objects for all services that meet all of the following conditions:

  • If the specified class name, clazz, is not null, the service must have been registered with the specified class name. The complete list of class names with which a service was registered is available from the service's objectClass property.

  • If the specified filter is not null, the filter expression must match the service.

  • If the Java Runtime Environment supports permissions, the caller must have ServicePermission with the GET action for at least one of the class names under which the service was registered.

  • For each class name with which the service was registered, calling ServiceReference.isAssignableTo(Bundle, String) with the context bundle and the class name on the service's ServiceReference object must return true

An array of ServiceReference objects or null if no services are registered which satisfy the search. There is no guarantee that the ServiceReference objects in the array will be in any specific order.

InvalidSyntaxException– If the specified filter contains an invalid filter expression that cannot be parsed.

IllegalStateException– If this BundleContext is no longer valid.

10.1.7.18 public Collection<ServiceReference<S>> getServiceReferences(Class<S> clazz, String filter)

<S>

Type of Service

The class under whose name the service was registered. Must not be null.

The filter expression or null for all services.

Returns a collection of ServiceReference objects. The returned collection of ServiceReference objects contains services that were registered under the name of the specified class, match the specified filter expression, and the packages for the class names under which the services were registered match the context bundle's packages as defined in ServiceReference.isAssignableTo(Bundle, String).

The collection is valid at the time of the call to this method. However since the Framework is a very dynamic environment, services can be modified or unregistered at any time.

The specified filter expression is used to select the registered services whose service properties contain keys and values which satisfy the filter expression. See Filter for a description of the filter syntax. If the specified filter is null, all registered services are considered to match the filter. If the specified filter expression cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

The result is a collection of ServiceReference objects for all services that meet all of the following conditions:

  • The service must have been registered with the name of the specified class. The complete list of class names with which a service was registered is available from the service's objectClass property.

  • If the specified filter is not null, the filter expression must match the service.

  • If the Java Runtime Environment supports permissions, the caller must have ServicePermission with the GET action for at least one of the class names under which the service was registered.

  • For each class name with which the service was registered, calling ServiceReference.isAssignableTo(Bundle, String) with the context bundle and the class name on the service's ServiceReference object must return true

A collection of ServiceReference objects. May be empty if no services are registered which satisfy the search. There is no guarantee that the ServiceReference objects in the collection will be in any specific order.

InvalidSyntaxException– If the specified filter contains an invalid filter expression that cannot be parsed.

IllegalStateException– If this BundleContext is no longer valid.

1.6

10.1.7.19 public Bundle installBundle(String location, InputStream input) throws BundleException

The location identifier of the bundle to install.

The InputStream object from which this bundle will be read or null to indicate the Framework must create the input stream from the specified location identifier. The input stream must always be closed when this method completes, even if an exception is thrown.

Installs a bundle from the specified InputStream object.

If the specified InputStream is null, the Framework must create the InputStream from which to read the bundle by interpreting, in an implementation dependent manner, the specified location.

The specified location identifier will be used as the identity of the bundle. Every installed bundle is uniquely identified by its location identifier which is typically in the form of a URL.

The following steps are required to install a bundle:

  1. If a bundle containing the same location identifier is already installed, the Bundle object for that bundle is returned.

  2. The bundle's content is read from the input stream. If this fails, a BundleException is thrown.

  3. The bundle's associated resources are allocated. The associated resources minimally consist of a unique identifier and a persistent storage area if the platform has file system support. If this step fails, a BundleException is thrown.

  4. The bundle's state is set to INSTALLED.

  5. A bundle event of type BundleEvent.INSTALLED is fired.

  6. The Bundle object for the newly or previously installed bundle is returned.

Postconditions, no exceptions thrown

  • getState() in { INSTALLED, RESOLVED }.

  • Bundle has a unique ID.

Postconditions, when an exception is thrown

  • Bundle is not installed. If there was an existing bundle for the specified location, then that bundle must still be in the state it was prior to calling this method.

The Bundle object of the installed bundle.

BundleException– If the installation failed. BundleException types thrown by this method include: BundleException.READ_ERROR , BundleException.DUPLICATE_BUNDLE_ERROR, BundleException.MANIFEST_ERROR, and BundleException.REJECTED_BY_HOOK.

SecurityException– If the caller does not have the appropriate AdminPermission[installed bundle,LIFECYCLE], and the Java Runtime Environment supports permissions.

IllegalStateException– If this BundleContext is no longer valid.

10.1.7.20 public Bundle installBundle(String location) throws BundleException

The location identifier of the bundle to install.

Installs a bundle from the specified location identifier.

This method performs the same function as calling installBundle(String,InputStream) with the specified location identifier and a null InputStream.

The Bundle object of the installed bundle.

BundleException– If the installation failed. BundleException types thrown by this method include: BundleException.READ_ERROR , BundleException.DUPLICATE_BUNDLE_ERROR, BundleException.MANIFEST_ERROR, and BundleException.REJECTED_BY_HOOK.

SecurityException– If the caller does not have the appropriate AdminPermission[installed bundle,LIFECYCLE], and the Java Runtime Environment supports permissions.

IllegalStateException– If this BundleContext is no longer valid.

installBundle(String, InputStream)

10.1.7.21 public ServiceRegistration<?> registerService(String[] clazzes, Object service, Dictionary<String, ?> properties)

The class names under which the service can be located. The class names in this array will be stored in the service's properties under the key Constants.OBJECTCLASS.

The service object or an object implementing ServiceFactory.

The properties for this service. The keys in the properties object must all be String objects. See Constants for a list of standard service property keys. Changes should not be made to this object after calling this method. To update the service's properties the ServiceRegistration.setProperties(Dictionary) method must be called. The set of properties may be null if the service has no properties.

Registers the specified service object with the specified properties under the specified class names into the Framework. A ServiceRegistration object is returned. The ServiceRegistration object is for the private use of the bundle registering the service and should not be shared with other bundles. The registering bundle is defined to be the context bundle. Other bundles can locate the service by using one of the getServiceReferences(Class, String), getServiceReferences(String, String), getServiceReference(Class) or getServiceReference(String) methods.

A bundle can register a service object that implements the ServiceFactory interface to have more flexibility in providing service objects to other bundles.

The following steps are required to register a service:

  1. If service does not implement ServiceFactory, an IllegalArgumentException is thrown if service is not an instanceof all the specified class names.

  2. The Framework adds the following service properties to the service properties from the specified Dictionary (which may be null):

    Properties with these names in the specified Dictionary will be ignored.

  3. The service is added to the Framework service registry and may now be used by other bundles.

  4. A service event of type ServiceEvent.REGISTERED is fired.

  5. A ServiceRegistration object for this registration is returned.

A ServiceRegistration object for use by the bundle registering the service to update the service's properties or to unregister the service.

IllegalArgumentException– If one of the following is true:

  • service is null.

  • service does not implement ServiceFactory and is not an instance of all the specified classes.

  • properties contains case variants of the same key name.

SecurityException– If the caller does not have the ServicePermission to register the service for all the named classes and the Java Runtime Environment supports permissions.

IllegalStateException– If this BundleContext is no longer valid.

ServiceRegistration, PrototypeServiceFactory, ServiceFactory

10.1.7.22 public ServiceRegistration<?> registerService(String clazz, Object service, Dictionary<String, ?> properties)

The class name under which the service can be located.

The service object or an object implementing ServiceFactory.

The properties for this service.

Registers the specified service object with the specified properties under the specified class name with the Framework.

This method is otherwise identical to registerService(String[], Object, Dictionary) and is provided as a convenience when service will only be registered under a single class name. Note that even in this case the value of the service's Constants.OBJECTCLASS property will be an array of string, rather than just a single string.

A ServiceRegistration object for use by the bundle registering the service to update the service's properties or to unregister the service.

IllegalStateException– If this BundleContext is no longer valid.

registerService(String[], Object, Dictionary)

10.1.7.23 public ServiceRegistration<S> registerService(Class<S> clazz, S service, Dictionary<String, ?> properties)

<S>

Type of Service.

The class under whose name the service can be located.

The service object or an object implementing ServiceFactory.

The properties for this service.

Registers the specified service object with the specified properties under the name of the specified class with the Framework.

This method is otherwise identical to registerService(String, Object, Dictionary) and is provided to return a type safe ServiceRegistration.

A ServiceRegistration object for use by the bundle registering the service to update the service's properties or to unregister the service.

IllegalStateException– If this BundleContext is no longer valid.

registerService(String, Object, Dictionary)

1.6

10.1.7.24 public ServiceRegistration<S> registerService(Class<S> clazz, ServiceFactory<S> factory, Dictionary<String, ?> properties)

<S>

Type of Service.

The class under whose name the service can be located.

The ServiceFactory object.

The properties for this service.

Registers the specified service factory object with the specified properties under the name of the specified class with the Framework.

This method is otherwise identical to registerService(Class, Object, Dictionary) and is provided to return a type safe ServiceRegistration when registering a ServiceFactory.

A ServiceRegistration object for use by the bundle registering the service to update the service's properties or to unregister the service.

IllegalStateException– If this BundleContext is no longer valid.

registerService(Class, Object, Dictionary)

1.8

10.1.7.25 public void removeBundleListener(BundleListener listener)

The BundleListener object to be removed.

Removes the specified BundleListener object from the context bundle's list of listeners.

If listener is not contained in the context bundle's list of listeners or this BundleContext is no longer valid, this method does nothing.

SecurityException– If listener is a SynchronousBundleListener and the caller does not have the appropriate AdminPermission[context bundle,LISTENER], and the Java Runtime Environment supports permissions.

10.1.7.26 public void removeFrameworkListener(FrameworkListener listener)

The FrameworkListener object to be removed.

Removes the specified FrameworkListener object from the context bundle's list of listeners.

If listener is not contained in the context bundle's list of listeners or this BundleContext is no longer valid, this method does nothing.

10.1.7.27 public void removeServiceListener(ServiceListener listener)

The ServiceListener to be removed.

Removes the specified ServiceListener object from the context bundle's list of listeners.

If listener is not contained in this context bundle's list of listeners or this BundleContext is no longer valid, this method does nothing.

10.1.7.28 public boolean ungetService(ServiceReference<?> reference)

A reference to the service to be released.

Releases the service object for the service referenced by the specified ServiceReference object. If the context bundle's use count for the service is zero, this method returns false. Otherwise, the context bundle's use count for the service is decremented by one.

The service object must no longer be used and all references to it should be destroyed when a bundle's use count for the service drops to zero.

The following steps are required to release the service object:

  1. If this BundleContext is no longer valid, false is returned.

  2. If the context bundle's use count for the service is zero or the service has been unregistered, false is returned.

  3. The context bundle's use count for the service is decremented by one.

  4. If the context bundle's use count for the service is now zero and the service has bundle or prototype scope, the ServiceFactory.ungetService(Bundle, ServiceRegistration, Object) method is called to release the service object for the context bundle.

  5. true is returned.

false if the context bundle's use count for the service is zero or if the service has been unregistered; true otherwise.

IllegalArgumentException– If the specified ServiceReference was not created by the same framework instance as this BundleContext.

getService(ServiceReference), ServiceFactory

10.1.8 public class BundleEvent
extends EventObject

An event from the Framework describing a bundle lifecycle change.

BundleEvent objects are delivered to SynchronousBundleListeners and BundleListeners when a change occurs in a bundle's lifecycle. A type code is used to identify the event type for future extendability.

OSGi Working Group reserves the right to extend the set of types.

BundleListener, SynchronousBundleListener

Immutable

10.1.8.1 public static final int INSTALLED = 1

The bundle has been installed.

BundleContext.installBundle(String)

10.1.8.2 public static final int LAZY_ACTIVATION = 512

The bundle will be lazily activated.

The bundle has a lazy activation policy and is waiting to be activated. It is now in the STARTING state and has a valid BundleContext. This event is only delivered to SynchronousBundleListeners. It is not delivered to BundleListeners.

1.4

10.1.8.3 public static final int RESOLVED = 32

The bundle has been resolved.

Bundle.RESOLVED

1.3

10.1.8.4 public static final int STARTED = 2

The bundle has been started.

The bundle's BundleActivator start method has been executed if the bundle has a bundle activator class.

Bundle.start()

10.1.8.5 public static final int STARTING = 128

The bundle is about to be activated.

The bundle's BundleActivator start method is about to be called if the bundle has a bundle activator class. This event is only delivered to SynchronousBundleListener s. It is not delivered to BundleListeners.

Bundle.start()

1.3

10.1.8.6 public static final int STOPPED = 4

The bundle has been stopped.

The bundle's BundleActivator stop method has been executed if the bundle has a bundle activator class.

Bundle.stop()

10.1.8.7 public static final int STOPPING = 256

The bundle is about to deactivated.

The bundle's BundleActivator stop method is about to be called if the bundle has a bundle activator class. This event is only delivered to SynchronousBundleListener s. It is not delivered to BundleListeners.

Bundle.stop()

1.3

10.1.8.8 public static final int UNINSTALLED = 16

The bundle has been uninstalled.

Bundle.uninstall()

10.1.8.9 public static final int UNRESOLVED = 64

The bundle has been unresolved.

Bundle.INSTALLED

1.3

10.1.8.10 public static final int UPDATED = 8

The bundle has been updated.

Bundle.update()

10.1.8.11 public BundleEvent(int type, Bundle bundle, Bundle origin)

The event type.

The bundle which had a lifecycle change.

The bundle which is the origin of the event. For the event type INSTALLED, this is the bundle whose context was used to install the bundle. Otherwise it is the bundle itself.

Creates a bundle event of the specified type.

1.6

10.1.8.12 public BundleEvent(int type, Bundle bundle)

The event type.

The bundle which had a lifecycle change. This bundle is used as the origin of the event.

Creates a bundle event of the specified type.

10.1.8.13 public Bundle getBundle()

Returns the bundle which had a lifecycle change. This bundle is the source of the event.

The bundle that had a change occur in its lifecycle.

10.1.8.14 public Bundle getOrigin()

Returns the bundle that was the origin of the event.

For the event type INSTALLED, this is the bundle whose context was used to install the bundle. Otherwise it is the bundle itself.

The bundle that was the origin of the event.

1.6

10.1.8.15 public int getType()

Returns the type of lifecyle event. The type values are:

The type of lifecycle event.

10.1.9 public class BundleException
extends Exception

A Framework exception used to indicate that a bundle lifecycle problem occurred.

A BundleException object is created by the Framework to denote an exception condition in the lifecycle of a bundle. BundleExceptions should not be created by bundle developers. A type code is used to identify the exception type for future extendability.

OSGi Working Group reserves the right to extend the set of types.

This exception conforms to the general purpose exception chaining mechanism.

10.1.9.1 public static final int ACTIVATOR_ERROR = 5

The bundle activator was in error.

1.5

10.1.9.2 public static final int DUPLICATE_BUNDLE_ERROR = 9

The install or update operation failed because another already installed bundle has the same symbolic name and version. This exception type will only occur if the framework is configured to only allow a single bundle to be installed for a given symbolic name and version.

Constants.FRAMEWORK_BSNVERSION

1.5

10.1.9.3 public static final int INVALID_OPERATION = 2

The operation was invalid.

1.5

10.1.9.4 public static final int MANIFEST_ERROR = 3

The bundle manifest was in error.

1.5

10.1.9.5 public static final int NATIVECODE_ERROR = 8

The bundle could not be resolved due to an error with the Bundle-NativeCode header.

1.5

10.1.9.6 public static final int READ_ERROR = 11

The framework received an error while reading the input stream for a bundle.

1.6

10.1.9.7 public static final int REJECTED_BY_HOOK = 12

A framework hook rejected the operation.

1.6

10.1.9.8 public static final int RESOLVE_ERROR = 4

The bundle was not resolved.

1.5

10.1.9.9 public static final int SECURITY_ERROR = 6

The operation failed due to insufficient permissions.

1.5

10.1.9.10 public static final int START_TRANSIENT_ERROR = 10

The start transient operation failed because the start level of the bundle is greater than the current framework start level

1.5

10.1.9.11 public static final int STATECHANGE_ERROR = 7

The operation failed to complete the requested lifecycle state change.

1.5

10.1.9.12 public static final int UNSPECIFIED = 0

No exception type is specified.

1.5

10.1.9.13 public static final int UNSUPPORTED_OPERATION = 1

The operation was unsupported. This type can be used anywhere a BundleException can be thrown.

1.5

10.1.9.14 public BundleException(String msg, Throwable cause)

The associated message.

The cause of this exception.

Creates a BundleException with the specified message and exception cause.

10.1.9.15 public BundleException(String msg)

The message.

Creates a BundleException with the specified message.

10.1.9.16 public BundleException(String msg, int type, Throwable cause)

The associated message.

The type for this exception.

The cause of this exception.

Creates a BundleException with the specified message, type and exception cause.

1.5

10.1.9.17 public BundleException(String msg, int type)

The message.

The type for this exception.

Creates a BundleException with the specified message and type.

1.5

10.1.9.18 public Throwable getCause()

Returns the cause of this exception or null if no cause was set.

The cause of this exception or null if no cause was set.

1.3

10.1.9.19 public Throwable getNestedException()

Returns the cause of this exception or null if no cause was specified when this exception was created.

This method predates the general purpose exception chaining mechanism. The getCause() method is now the preferred means of obtaining this information.

The result of calling getCause().

10.1.9.20 public int getType()

Returns the type for this exception or UNSPECIFIED if the type was unspecified or unknown.

The type of this exception.

1.5

10.1.9.21 public Throwable initCause(Throwable cause)

The cause of this exception.

Initializes the cause of this exception to the specified value.

This exception.

IllegalArgumentException– If the specified cause is this exception.

IllegalStateException– If the cause of this exception has already been set.

1.3

10.1.10 public interface BundleListener
extends EventListener

A BundleEvent listener. BundleListener is a listener interface that may be implemented by a bundle developer. When a BundleEvent is fired, it is asynchronously delivered to a BundleListener. The Framework delivers BundleEvent objects to a BundleListener in order and must not concurrently call a BundleListener.

A BundleListener object is registered with the Framework using the BundleContext.addBundleListener(BundleListener) method. BundleListeners are called with a BundleEvent object when a bundle has been installed, resolved, started, stopped, updated, unresolved, or uninstalled.

BundleEvent

Not Thread-safe

10.1.10.1 public void bundleChanged(BundleEvent event)

The BundleEvent.

Receives notification that a bundle has had a lifecycle change.

10.1.11 public final class BundlePermission
extends BasicPermission

A bundle's authority to require or provide a bundle or to receive or attach fragments.

A bundle symbolic name defines a unique fully qualified name. Wildcards may be used.

 name ::= <symbolic name> | <symbolic name ending in ".*"> | *

Examples:

 org.osgi.example.bundle
 org.osgi.example.*
 *

BundlePermission has four actions: provide, require, host, and fragment. The provide action implies the require action.

1.3

Thread-safe

10.1.11.1 public static final String FRAGMENT = "fragment"

The action string fragment.

10.1.11.2 public static final String HOST = "host"

The action string host.

10.1.11.3 public static final String PROVIDE = "provide"

The action string provide. The provide action implies the require action.

10.1.11.4 public static final String REQUIRE = "require"

The action string require. The require action is implied by the provide action.

10.1.11.5 public BundlePermission(String symbolicName, String actions)

The bundle symbolic name.

provide,require, host, fragment (canonical order).

Defines the authority to provide and/or require and or specify a host fragment symbolic name within the OSGi environment.

Bundle Permissions are granted over all possible versions of a bundle. A bundle that needs to provide a bundle must have the appropriate BundlePermission for the symbolic name; a bundle that requires a bundle must have the appropriate BundlePermssion for that symbolic name; a bundle that specifies a fragment host must have the appropriate BundlePermission for that symbolic name.

10.1.11.6 public boolean equals(Object obj)

The object to test for equality with this BundlePermission object.

Determines the equality of two BundlePermission objects. This method checks that specified bundle has the same bundle symbolic name and BundlePermission actions as this BundlePermission object.

true if obj is a BundlePermission, and has the same bundle symbolic name and actions as this BundlePermission object; false otherwise.

10.1.11.7 public String getActions()

Returns the canonical string representation of the BundlePermission actions.

Always returns present BundlePermission actions in the following order: provide, require, host, fragment.

Canonical string representation of the BundlePermission actions.

10.1.11.8 public int hashCode()

Returns the hash code value for this object.

A hash code value for this object.

10.1.11.9 public boolean implies(Permission p)

The requested permission.

Determines if the specified permission is implied by this object.

This method checks that the symbolic name of the target is implied by the symbolic name of this object. The list of BundlePermission actions must either match or allow for the list of the target object to imply the target BundlePermission action.

The permission to provide a bundle implies the permission to require the named symbolic name.

       x.y.*,"provide" -> x.y.z,"provide" is true
       *,"require" -> x.y, "require"      is true
       *,"provide" -> x.y, "require"      is true
       x.y,"provide" -> x.y.z, "provide"  is false

true if the specified BundlePermission action is implied by this object; false otherwise.

10.1.11.10 public PermissionCollection newPermissionCollection()

Returns a new PermissionCollection object suitable for storing BundlePermission objects.

A new PermissionCollection object.

10.1.12 public interface BundleReference

A reference to a Bundle.

1.5

Thread-safe

Consumers of this API must not implement this type

10.1.12.1 public Bundle getBundle()

Returns the Bundle object associated with this BundleReference.

The Bundle object associated with this BundleReference.

10.1.13 public final class CapabilityPermission
extends BasicPermission

A bundle's authority to provide or require a capability.

  • The provide action allows a bundle to provide a capability matching the specified filter.

  • The require action allows a bundle to require a capability matching the specified filter.

1.6

Thread-safe

10.1.13.1 public static final String PROVIDE = "provide"

The action string provide.

10.1.13.2 public static final String REQUIRE = "require"

The action string require.

10.1.13.3 public CapabilityPermission(String name, String actions)

The capability namespace or a filter over the attributes.

require,provide (canonical order)

Create a new CapabilityPermission.

The name is specified as a dot-separated string. Wildcards may be used.

 name ::= <namespace> | <namespace ending in ".*"> | *

Examples:

 com.acme.capability.*
 org.foo.capability
 *

For the require action, the name can also be a filter expression. The filter gives access to the capability attributes as well as the following attributes:

  • signer - A Distinguished Name chain used to sign the bundle providing the capability. Wildcards in a DN are not matched according to the filter string rules, but according to the rules defined for a DN chain.

  • location - The location of the bundle providing the capability.

  • id - The bundle ID of the bundle providing the capability.

  • name - The symbolic name of the bundle providing the capability.

  • capability.namespace - The namespace of the required capability.

Since the above attribute names may conflict with attribute names of a capability, you can prefix an attribute name with '@' in the filter expression to match against the capability attributes and not one of the above attributes. Filter attribute names are processed in a case sensitive manner.

There are two possible actions: require and provide. The require permission allows the owner of this permission to require a capability matching the attributes. The provide permission allows the bundle to provide a capability in the specified capability namespace.

IllegalArgumentException– If the specified name is a filter expression and either the specified action is not require or the filter has an invalid syntax.

10.1.13.4 public CapabilityPermission(String namespace, Map<String, ?> attributes, Bundle providingBundle, String actions)

The requested capability namespace.

The requested capability attributes.

The bundle providing the requested capability.

The action require.

Creates a new requested CapabilityPermission object to be used by code that must perform checkPermission for the require action. CapabilityPermission objects created with this constructor cannot be added to a CapabilityPermission permission collection.

IllegalArgumentException– If the specified action is not require or attributes or providingBundle are null .

10.1.13.5 public boolean equals(Object obj)

The object to test for equality.

Determines the equality of two CapabilityPermission objects. Checks that specified object has the same name and action as this CapabilityPermission.

true if obj is a CapabilityPermission, and has the same name and actions as this CapabilityPermission object; false otherwise.

10.1.13.6 public String getActions()

Returns the canonical string representation of the actions. Always returns present actions in the following order: require, provide.

The canonical string representation of the actions.

10.1.13.7 public int hashCode()

Returns the hash code value for this object.

Hash code value for this object.

10.1.13.8 public boolean implies(Permission p)

The target permission to check.

Determines if a CapabilityPermission object "implies" the specified permission.

true if the specified permission is implied by this object; false otherwise.

10.1.13.9 public PermissionCollection newPermissionCollection()

Returns a new PermissionCollection object for storing CapabilityPermission objects.

A new PermissionCollection object suitable for storing CapabilityPermission objects.

10.1.14 public interface Configurable

Supports a configuration object.

Configurable is an interface that should be used by a bundle developer in support of a configurable service. Bundles that need to configure a service may test to determine if the service object is an instanceof Configurable.

As of 1.2. Please use Configuration Admin service.

10.1.14.1 public Object getConfigurationObject()

Returns this service's configuration object.

Services implementing Configurable should take care when returning a service configuration object since this object is probably sensitive.

If the Java Runtime Environment supports permissions, it is recommended that the caller is checked for some appropriate permission before returning the configuration object.

The configuration object for this service.

SecurityException– If the caller does not have an appropriate permission and the Java Runtime Environment supports permissions.

As of 1.2. Please use Configuration Admin service.

10.1.15 public interface Constants

Defines standard names for the OSGi environment system properties, service properties, and Manifest header attribute keys.

The values associated with these keys are of type String, unless otherwise indicated.

1.1

Consumers of this API must not implement this type

10.1.15.1 public static final String ACTIVATION_LAZY = "lazy"

Bundle activation policy declaring the bundle must be activated when the first class load is made from the bundle.

A bundle with the lazy activation policy that is started with the START_ACTIVATION_POLICY option will wait in the STARTING state until the first class load from the bundle occurs. The bundle will then be activated before the class is returned to the requester.

The activation policy value is specified as in the Bundle-ActivationPolicy manifest header like:

       Bundle-ActivationPolicy: lazy

BUNDLE_ACTIVATIONPOLICY, Bundle.start(int), Bundle.START_ACTIVATION_POLICY

1.4

10.1.15.2 public static final String BUNDLE_ACTIVATIONPOLICY = "Bundle-ActivationPolicy"

Manifest header identifying the bundle's activation policy.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

ACTIVATION_LAZY, INCLUDE_DIRECTIVE, EXCLUDE_DIRECTIVE

1.4

10.1.15.3 public static final String BUNDLE_ACTIVATOR = "Bundle-Activator"

Manifest header identifying the bundle's activator class.

If present, this header specifies the name of the bundle resource class that implements the BundleActivator interface and whose start and stop methods are called by the Framework when the bundle is started and stopped, respectively.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.4 public static final String BUNDLE_CATEGORY = "Bundle-Category"

Manifest header identifying the bundle's category.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.5 public static final String BUNDLE_CLASSPATH = "Bundle-ClassPath"

Manifest header identifying a list of directories and embedded JAR files, which are bundle resources used to extend the bundle's classpath.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.6 public static final String BUNDLE_CONTACTADDRESS = "Bundle-ContactAddress"

Manifest header identifying the contact address where problems with the bundle may be reported; for example, an email address.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.7 public static final String BUNDLE_COPYRIGHT = "Bundle-Copyright"

Manifest header identifying the bundle's copyright information.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.8 public static final String BUNDLE_DESCRIPTION = "Bundle-Description"

Manifest header containing a brief description of the bundle's functionality.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.9 public static final String BUNDLE_DEVELOPERS = "Bundle-Developers"

Manifest header identifying the bundle's developers.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.9

10.1.15.10 public static final String BUNDLE_DOCURL = "Bundle-DocURL"

Manifest header identifying the bundle's documentation URL, from which further information about the bundle may be obtained.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.11 public static final String BUNDLE_ICON = "Bundle-Icon"

Manifest header identifying the bundle's icon URLs.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.8

10.1.15.12 public static final String BUNDLE_LICENSE = "Bundle-License"

Manifest header identifying the bundle's license information.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.8

10.1.15.13 public static final String BUNDLE_LOCALIZATION = "Bundle-Localization"

Manifest header identifying the base name of the bundle's localization entries.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

BUNDLE_LOCALIZATION_DEFAULT_BASENAME

1.3

10.1.15.14 public static final String BUNDLE_LOCALIZATION_DEFAULT_BASENAME = "OSGI-INF/l10n/bundle"

Default value for the Bundle-Localization manifest header.

BUNDLE_LOCALIZATION

1.3

10.1.15.15 public static final String BUNDLE_MANIFESTVERSION = "Bundle-ManifestVersion"

Manifest header identifying the bundle manifest version. A bundle manifest may express the version of the syntax in which it is written by specifying a bundle manifest version. Bundles exploiting OSGi Release 4, or later, syntax must specify a bundle manifest version.

The bundle manifest version defined by OSGi Release 4 or, more specifically, by version 1.3 of the OSGi Core Specification is "2".

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.3

10.1.15.16 public static final String BUNDLE_NAME = "Bundle-Name"

Manifest header identifying the bundle's name.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.17 public static final String BUNDLE_NATIVECODE = "Bundle-NativeCode"

Manifest header identifying a number of hardware environments and the native language code libraries that the bundle is carrying for each of these environments.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.18 public static final String BUNDLE_NATIVECODE_LANGUAGE = "language"

Manifest header attribute identifying the language in which the native bundle code is written specified in the Bundle-NativeCode manifest header. See ISO 639 for possible values.

The attribute value is encoded in the Bundle-NativeCode manifest header like:

     Bundle-NativeCode: http.so ; language=nl_be ...

BUNDLE_NATIVECODE

10.1.15.19 public static final String BUNDLE_NATIVECODE_OSNAME = "osname"

Manifest header attribute identifying the operating system required to run native bundle code specified in the Bundle-NativeCode manifest header).

The attribute value is encoded in the Bundle-NativeCode manifest header like:

     Bundle-NativeCode: http.so ; osname=Linux ...

BUNDLE_NATIVECODE

10.1.15.20 public static final String BUNDLE_NATIVECODE_OSVERSION = "osversion"

Manifest header attribute identifying the operating system version required to run native bundle code specified in the Bundle-NativeCode manifest header).

The attribute value is encoded in the Bundle-NativeCode manifest header like:

     Bundle-NativeCode: http.so ; osversion="2.34" ...

BUNDLE_NATIVECODE

10.1.15.21 public static final String BUNDLE_NATIVECODE_PROCESSOR = "processor"

Manifest header attribute identifying the processor required to run native bundle code specified in the Bundle-NativeCode manifest header).

The attribute value is encoded in the Bundle-NativeCode manifest header like:

     Bundle-NativeCode: http.so ; processor=x86 ...

BUNDLE_NATIVECODE

10.1.15.22 public static final String BUNDLE_REQUIREDEXECUTIONENVIRONMENT = "Bundle-RequiredExecutionEnvironment"

Manifest header identifying the required execution environment for the bundle. The service platform may run this bundle if any of the execution environments named in this header matches one of the execution environments it implements.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.2

As of 1.6. Replaced by the osgi.ee capability.

10.1.15.23 public static final String BUNDLE_SCM = "Bundle-SCM"

Manifest header identifying the bundle's software configuration management system.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.9

10.1.15.24 public static final String BUNDLE_SYMBOLICNAME = "Bundle-SymbolicName"

Manifest header identifying the bundle's symbolic name.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.3

10.1.15.25 public static final String BUNDLE_SYMBOLICNAME_ATTRIBUTE = "bundle-symbolic-name"

Manifest header attribute identifying the symbolic name of a bundle that exports a package specified in the Import-Package manifest header.

The attribute value is encoded in the Import-Package manifest header like:

     Import-Package: org.osgi.framework;
       bundle-symbolic-name="com.acme.module.test"

IMPORT_PACKAGE

1.3

10.1.15.26 public static final String BUNDLE_UPDATELOCATION = "Bundle-UpdateLocation"

Manifest header identifying the location from which a new bundle version is obtained during a bundle update operation.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.27 public static final String BUNDLE_VENDOR = "Bundle-Vendor"

Manifest header identifying the bundle's vendor.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.28 public static final String BUNDLE_VERSION = "Bundle-Version"

Manifest header identifying the bundle's version.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.29 public static final String BUNDLE_VERSION_ATTRIBUTE = "bundle-version"

Manifest header attribute identifying a range of versions for a bundle specified in the Require-Bundle or Fragment-Host manifest headers. The default value is 0.0.0.

The attribute value is encoded in the Require-Bundle manifest header like:

     Require-Bundle: com.acme.module.test; bundle-version="1.1"
     Require-Bundle: com.acme.module.test; bundle-version="[1.0,2.0)"

The bundle-version attribute value uses a mathematical interval notation to specify a range of bundle versions. A bundle-version attribute value specified as a single version means a version range that includes any bundle version greater than or equal to the specified version.

REQUIRE_BUNDLE

1.3

10.1.15.30 public static final String DYNAMICIMPORT_PACKAGE = "DynamicImport-Package"

Manifest header identifying the packages that the bundle may dynamically import during execution.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.2

10.1.15.31 public static final String EFFECTIVE_ACTIVE = "active"

Manifest header directive value identifying a capability that is effective at active time. Capabilities with an effective time of active are ignored by the resolver.

The directive value is encoded in the Provide-Capability manifest header like:

     Provide-Capability: com.acme.capability; effective:="active"

EFFECTIVE_DIRECTIVE

1.6

10.1.15.32 public static final String EFFECTIVE_DIRECTIVE = "effective"

Manifest header directive identifying the effective time of the provided capability. The default value is resolve.

The directive value is encoded in the Provide-Capability manifest header like:

     Provide-Capability: com.acme.capability; effective:="resolve"

PROVIDE_CAPABILITY, EFFECTIVE_RESOLVE, EFFECTIVE_ACTIVE

1.6

10.1.15.33 public static final String EFFECTIVE_RESOLVE = "resolve"

Manifest header directive value identifying a capability that is effective at resolve time. Capabilities with an effective time of resolve are the only capabilities which are processed by the resolver.

The directive value is encoded in the Provide-Capability manifest header like:

     Provide-Capability: com.acme.capability; effective:="resolve"

EFFECTIVE_DIRECTIVE

1.6

10.1.15.34 public static final String EXCLUDE_DIRECTIVE = "exclude"

Manifest header directive identifying a list of classes to exclude in the exported package..

This directive is used by the Export-Package manifest header to identify a list of classes of the specified package which must not be allowed to be exported. The directive value is encoded in the Export-Package manifest header like:

     Export-Package: org.osgi.framework; exclude:="*Impl"

This directive is also used by the Bundle-ActivationPolicy manifest header to identify the packages from which class loads will not trigger lazy activation. The directive value is encoded in the Bundle-ActivationPolicy manifest header like:

     Bundle-ActivationPolicy: lazy; exclude:="org.osgi.framework"

EXPORT_PACKAGE, BUNDLE_ACTIVATIONPOLICY

1.3

10.1.15.35 public static final String EXPORT_PACKAGE = "Export-Package"

Manifest header identifying the packages that the bundle offers to the Framework for export.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.36 public static final String EXPORT_SERVICE = "Export-Service"

Manifest header identifying the fully qualified class names of the services that the bundle may register (used for informational purposes only).

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

As of 1.2.

10.1.15.37 public static final String EXTENSION_BOOTCLASSPATH = "bootclasspath"

Manifest header directive value identifying the type of extension fragment. An extension fragment type of bootclasspath indicates that the extension fragment is to be loaded by the boot class loader.

The directive value is encoded in the Fragment-Host manifest header like:

     Fragment-Host: system.bundle; extension:="bootclasspath"

EXTENSION_DIRECTIVE

1.3

As of 1.9.

10.1.15.38 public static final String EXTENSION_BUNDLE_ACTIVATOR = "ExtensionBundle-Activator"

Manifest header identifying the extension bundle's activator class.

If present, this header specifies the name of the extension bundle resource class that implements the BundleActivator interface and whose start and stop methods are called by the Framework when the Framework is initialized and shutdown, respectively.

1.8

10.1.15.39 public static final String EXTENSION_DIRECTIVE = "extension"

Manifest header directive identifying the type of the extension fragment.

The directive value is encoded in the Fragment-Host manifest header like:

     Fragment-Host: system.bundle; extension:="framework"

The default value is framework.

FRAGMENT_HOST, EXTENSION_FRAMEWORK

1.3

10.1.15.40 public static final String EXTENSION_FRAMEWORK = "framework"

Manifest header directive value identifying the type of extension fragment. An extension fragment type of framework indicates that the extension fragment is to be loaded by the framework's class loader.

The directive value is encoded in the Fragment-Host manifest header like:

     Fragment-Host: system.bundle; extension:="framework"

EXTENSION_DIRECTIVE

1.3

10.1.15.41 public static final String FILTER_DIRECTIVE = "filter"

Manifest header directive identifying the capability filter specified in the Require-Capability manifest header.

The directive value is encoded in the Require-Capability manifest header like:

     Require-Capability: com.acme.capability; filter:="(someattr=somevalue)"

REQUIRE_CAPABILITY

1.6

10.1.15.42 public static final String FRAGMENT_ATTACHMENT_ALWAYS = "always"

Manifest header directive value identifying a fragment attachment type of always. A fragment attachment type of always indicates that fragments are allowed to attach to the host bundle at any time (while the host is resolved or during the process of resolving the host bundle).

The directive value is encoded in the Bundle-SymbolicName manifest header like:

     Bundle-SymbolicName: com.acme.module.test; fragment-attachment:="always"

FRAGMENT_ATTACHMENT_DIRECTIVE

1.3

10.1.15.43 public static final String FRAGMENT_ATTACHMENT_DIRECTIVE = "fragment-attachment"

Manifest header directive identifying if and when a fragment may attach to a host bundle. The default value is always.

The directive value is encoded in the Bundle-SymbolicName manifest header like:

     Bundle-SymbolicName: com.acme.module.test; fragment-attachment:="never"

BUNDLE_SYMBOLICNAME, FRAGMENT_ATTACHMENT_ALWAYS, FRAGMENT_ATTACHMENT_RESOLVETIME, FRAGMENT_ATTACHMENT_NEVER

1.3

10.1.15.44 public static final String FRAGMENT_ATTACHMENT_NEVER = "never"

Manifest header directive value identifying a fragment attachment type of never. A fragment attachment type of never indicates that no fragments are allowed to attach to the host bundle at any time.

The directive value is encoded in the Bundle-SymbolicName manifest header like:

     Bundle-SymbolicName: com.acme.module.test; fragment-attachment:="never"

FRAGMENT_ATTACHMENT_DIRECTIVE

1.3

10.1.15.45 public static final String FRAGMENT_ATTACHMENT_RESOLVETIME = "resolve-time"

Manifest header directive value identifying a fragment attachment type of resolve-time. A fragment attachment type of resolve-time indicates that fragments are allowed to attach to the host bundle only during the process of resolving the host bundle.

The directive value is encoded in the Bundle-SymbolicName manifest header like:

     Bundle-SymbolicName: com.acme.module.test;
       fragment-attachment:="resolve-time"

FRAGMENT_ATTACHMENT_DIRECTIVE

1.3

10.1.15.46 public static final String FRAGMENT_HOST = "Fragment-Host"

Manifest header identifying the symbolic name of another bundle for which that the bundle is a fragment.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.3

10.1.15.47 public static final String FRAMEWORK_BEGINNING_STARTLEVEL = "org.osgi.framework.startlevel.beginning"

Framework launching property specifying the beginning start level of the framework.

Core Specification, Starting the Framework.

1.5

10.1.15.48 public static final String FRAMEWORK_BOOTDELEGATION = "org.osgi.framework.bootdelegation"

Framework launching property identifying packages for which the Framework must delegate class loading to the parent class loader of the bundle.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

FRAMEWORK_BUNDLE_PARENT

1.3

10.1.15.49 public static final String FRAMEWORK_BSNVERSION = "org.osgi.framework.bsnversion"

Framework launching property specifying whether multiple bundles having the same symbolic name and version may be installed.

Default value is managed in this release of the specification. This default may change in a future specification release. Therefore, code must not assume the default behavior is managed and should interrogate the value of this property to determine the behavior.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

FRAMEWORK_BSNVERSION_MULTIPLE, FRAMEWORK_BSNVERSION_SINGLE, FRAMEWORK_BSNVERSION_MANAGED

1.6

10.1.15.50 public static final String FRAMEWORK_BSNVERSION_MANAGED = "managed"

Specifies the framework must consult the bundle collision hook services to determine if it will be an error to install a bundle or update a bundle to have the same symbolic name and version as another installed bundle. If no bundle collision hook services are registered, then it will be an error to install a bundle or update a bundle to have the same symbolic name and version as another installed bundle.

FRAMEWORK_BSNVERSION, BundleException.DUPLICATE_BUNDLE_ERROR

1.7

10.1.15.51 public static final String FRAMEWORK_BSNVERSION_MULTIPLE = "multiple"

Specifies the framework will allow multiple bundles to be installed having the same symbolic name and version.

FRAMEWORK_BSNVERSION

1.6

10.1.15.52 public static final String FRAMEWORK_BSNVERSION_SINGLE = "single"

Specifies the framework will only allow a single bundle to be installed for a given symbolic name and version. It will be an error to install a bundle or update a bundle to have the same symbolic name and version as another installed bundle.

FRAMEWORK_BSNVERSION, BundleException.DUPLICATE_BUNDLE_ERROR

1.6

10.1.15.53 public static final String FRAMEWORK_BUNDLE_PARENT = "org.osgi.framework.bundle.parent"

Framework launching property specifying the parent class loader type for all bundle class loaders. Default value is boot.

FRAMEWORK_BUNDLE_PARENT_BOOT, FRAMEWORK_BUNDLE_PARENT_EXT, FRAMEWORK_BUNDLE_PARENT_APP, FRAMEWORK_BUNDLE_PARENT_FRAMEWORK

1.5

10.1.15.54 public static final String FRAMEWORK_BUNDLE_PARENT_APP = "app"

Specifies to use the application class loader as the parent class loader for all bundle class loaders. Depending on how the framework is launched, this may refer to the same class loader as FRAMEWORK_BUNDLE_PARENT_FRAMEWORK.

FRAMEWORK_BUNDLE_PARENT

1.5

10.1.15.55 public static final String FRAMEWORK_BUNDLE_PARENT_BOOT = "boot"

Specifies to use of the boot class loader as the parent class loader for all bundle class loaders.

FRAMEWORK_BUNDLE_PARENT

1.5

10.1.15.56 public static final String FRAMEWORK_BUNDLE_PARENT_EXT = "ext"

Specifies to use the extension class loader as the parent class loader for all bundle class loaders.

FRAMEWORK_BUNDLE_PARENT

1.5

10.1.15.57 public static final String FRAMEWORK_BUNDLE_PARENT_FRAMEWORK = "framework"

Specifies to use the framework class loader as the parent class loader for all bundle class loaders. The framework class loader is the class loader used to load the framework implementation. Depending on how the framework is launched, this may refer to the same class loader as FRAMEWORK_BUNDLE_PARENT_APP.

FRAMEWORK_BUNDLE_PARENT

1.5

10.1.15.58 public static final String FRAMEWORK_COMMAND_ABSPATH = "abspath"

Specified the substitution string for the absolute path of a file.

FRAMEWORK_EXECPERMISSION

1.6

10.1.15.59 public static final String FRAMEWORK_EXECPERMISSION = "org.osgi.framework.command.execpermission"

Framework launching property specifying an optional OS specific command to set file permissions on extracted native code. On some operating systems, it is required that native libraries be set to executable. This optional property allows you to specify the command. For example, on a UNIX style OS, this property could have the following value.

 chmod +rx ${abspath}

The ${abspath} is used by the framework to substitute the actual absolute file path.

1.5

10.1.15.60 public static final String FRAMEWORK_EXECUTIONENVIRONMENT = "org.osgi.framework.executionenvironment"

Framework launching property identifying execution environments provided by the Framework.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

1.2

As of 1.6. Replaced by the osgi.ee capability.

10.1.15.61 public static final String FRAMEWORK_LANGUAGE = "org.osgi.framework.language"

Framework launching property identifying the Framework implementation language (see ISO 639 for possible values).

The value of this property may be retrieved by calling the BundleContext.getProperty method.

10.1.15.62 public static final String FRAMEWORK_LIBRARY_EXTENSIONS = "org.osgi.framework.library.extensions"

Framework launching property specifying a comma separated list of additional library file extensions that must be used when a bundle's class loader is searching for native libraries. If this property is not set, then only the library name returned by System.mapLibraryName(String) will be used to search. This is needed for certain operating systems which allow more than one extension for a library. For example, AIX allows library extensions of .a and .so, but System.mapLibraryName(String) will only return names with the .a extension.

1.5

10.1.15.63 public static final String FRAMEWORK_OS_NAME = "org.osgi.framework.os.name"

Framework launching property identifying the Framework host-computer's operating system.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

10.1.15.64 public static final String FRAMEWORK_OS_VERSION = "org.osgi.framework.os.version"

Framework launching property identifying the Framework host-computer's operating system version number.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

10.1.15.65 public static final String FRAMEWORK_PROCESSOR = "org.osgi.framework.processor"

Framework launching property identifying the Framework host-computer's processor name.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

10.1.15.66 public static final String FRAMEWORK_SECURITY = "org.osgi.framework.security"

Framework launching property specifying the type of security manager the framework must use. If not specified then the framework will not set the VM security manager.

FRAMEWORK_SECURITY_OSGI

1.5

10.1.15.67 public static final String FRAMEWORK_SECURITY_OSGI = "osgi"

Specifies that a security manager that supports all security aspects of the OSGi core specification including postponed conditions must be installed.

If this value is specified and there is a security manager already installed, then a SecurityException must be thrown when the Framework is initialized.

FRAMEWORK_SECURITY

1.5

10.1.15.68 public static final String FRAMEWORK_STORAGE = "org.osgi.framework.storage"

Framework launching property specifying the persistent storage area used by the framework. The value of this property must be a valid file path in the file system to a directory. If the specified directory does not exist then the framework will create the directory. If the specified path exists but is not a directory or if the framework fails to create the storage directory, then framework initialization must fail. The framework is free to use this directory as it sees fit. This area can not be shared with anything else.

If this property is not set, the framework should use a reasonable platform default for the persistent storage area.

1.5

10.1.15.69 public static final String FRAMEWORK_STORAGE_CLEAN = "org.osgi.framework.storage.clean"

Framework launching property specifying if and when the persistent storage area for the framework should be cleaned. If this property is not set, then the framework storage area must not be cleaned.

FRAMEWORK_STORAGE_CLEAN_ONFIRSTINIT

1.5

10.1.15.70 public static final String FRAMEWORK_STORAGE_CLEAN_ONFIRSTINIT = "onFirstInit"

Specifies that the framework storage area must be cleaned before the framework is initialized for the first time. Subsequent inits, starts or updates of the framework will not result in cleaning the framework storage area.

1.5

10.1.15.71 public static final String FRAMEWORK_SYSTEMCAPABILITIES = "org.osgi.framework.system.capabilities"

Framework launching property identifying capabilities which the system bundle must provide.

If this property is not specified then the framework must calculate a reasonable default value for the current execution environment.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

1.6

10.1.15.72 public static final String FRAMEWORK_SYSTEMCAPABILITIES_EXTRA = "org.osgi.framework.system.capabilities.extra"

Framework launching property identifying extra capabilities which the system bundle must additionally provide.

This property is useful for configuring extra system capabilities in addition to the system capabilities calculated by the framework.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

FRAMEWORK_SYSTEMCAPABILITIES

1.6

10.1.15.73 public static final String FRAMEWORK_SYSTEMPACKAGES = "org.osgi.framework.system.packages"

Framework launching property identifying packages which the system bundle must export.

If this property is not specified then the framework must calculate a reasonable default value for the current execution environment.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

1.3

10.1.15.74 public static final String FRAMEWORK_SYSTEMPACKAGES_EXTRA = "org.osgi.framework.system.packages.extra"

Framework launching property identifying extra packages which the system bundle must export from the current execution environment.

This property is useful for configuring extra system packages in addition to the system packages calculated by the framework.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

FRAMEWORK_SYSTEMPACKAGES

1.5

10.1.15.75 public static final String FRAMEWORK_TRUST_REPOSITORIES = "org.osgi.framework.trust.repositories"

Framework launching property specifying the trust repositories used by the framework. The value is a java.io.File.pathSeparator separated list of valid file paths to files that contain key stores. Key stores of type JKS must be supported and other key store types may be supported. The framework will use the key stores as trust repositories to authenticate certificates of trusted signers. The key stores are only used as read-only trust repositories to access public keys. No passwords are required to access the key stores' public keys.

Note that framework implementations are allowed to use other trust repositories in addition to the trust repositories specified by this property. How these other trust repositories are configured and populated is implementation specific.

1.5

10.1.15.76 public static final String FRAMEWORK_UUID = "org.osgi.framework.uuid"

Framework environment property identifying the Framework's universally unique identifier (UUID). A UUID represents a 128-bit value. A new UUID is generated by the Framework.init() method each time a framework is initialized. The value of this property must conform to the UUID string representation specified in RFC 4122.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

1.6

10.1.15.77 public static final String FRAMEWORK_VENDOR = "org.osgi.framework.vendor"

Framework environment property identifying the Framework implementation vendor.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

10.1.15.78 public static final String FRAMEWORK_VERSION = "org.osgi.framework.version"

Framework environment property identifying the Framework version.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

10.1.15.79 public static final String FRAMEWORK_WINDOWSYSTEM = "org.osgi.framework.windowsystem"

Framework launching property specifying the current windowing system. The framework should provide a reasonable default if this is not set.

1.5

10.1.15.80 public static final String IMPORT_PACKAGE = "Import-Package"

Manifest header identifying the packages on which the bundle depends.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

10.1.15.81 public static final String IMPORT_SERVICE = "Import-Service"

Manifest header identifying the fully qualified class names of the services that the bundle requires (used for informational purposes only).

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

As of 1.2.

10.1.15.82 public static final String INCLUDE_DIRECTIVE = "include"

Manifest header directive identifying a list of classes to include in the exported package.

This directive is used by the Export-Package manifest header to identify a list of classes of the specified package which must be allowed to be exported. The directive value is encoded in the Export-Package manifest header like:

     Export-Package: org.osgi.framework; include:="MyClass*"

This directive is also used by the Bundle-ActivationPolicy manifest header to identify the packages from which class loads will trigger lazy activation. The directive value is encoded in the Bundle-ActivationPolicy manifest header like:

     Bundle-ActivationPolicy: lazy; include:="org.osgi.framework"

EXPORT_PACKAGE, BUNDLE_ACTIVATIONPOLICY

1.3

10.1.15.83 public static final String INTENT_ASYNC = "osgi.async"

Intent supported by Remote Service implementations that support Asynchronous Remote Services as defined for the osgi.async intent.

1.9

10.1.15.84 public static final String INTENT_BASIC = "osgi.basic"

Intent supported by Remote Services implementations that support Basic Remote Services as defined for the osgi.basic intent.

1.9

10.1.15.85 public static final String INTENT_CONFIDENTIAL = "osgi.confidential"

Intent supported by Remote Service implementation that provide confidential communications as defined for the osgi.confidential intent.

1.9

10.1.15.86 public static final String INTENT_PRIVATE = "osgi.private"

Intent supported by Remote Service implementations that provide private communications as defined for the osgi.private intent.

1.9

10.1.15.87 public static final String MANDATORY_DIRECTIVE = "mandatory"

Manifest header directive identifying names of matching attributes which must be specified by matching Import-Package statements in the Export-Package manifest header.

The directive value is encoded in the Export-Package manifest header like:

     Export-Package: org.osgi.framework; mandatory:="bundle-symbolic-name"

EXPORT_PACKAGE

1.3

10.1.15.88 public static final String OBJECTCLASS = "objectClass"

Service property identifying all of the class names under which a service was registered in the Framework. The value of this property must be of type String[].

This property is set by the Framework when a service is registered.

10.1.15.89 public static final String PACKAGE_SPECIFICATION_VERSION = "specification-version"

Manifest header attribute identifying the version of a package specified in the Export-Package or Import-Package manifest header.

As of 1.3. This has been replaced by VERSION_ATTRIBUTE.

10.1.15.90 public static final String PROVIDE_CAPABILITY = "Provide-Capability"

Manifest header identifying the capabilities that the bundle offers to provide to other bundles.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.6

10.1.15.91 public static final String REMOTE_CONFIGS_SUPPORTED = "remote.configs.supported"

Service property identifying the configuration types supported by a distribution provider. Registered by the distribution provider on one of its services to indicate the supported configuration types.

The value of this property must be of type String, String[], or Collection of String.

Remote Services Specification

1.6

10.1.15.92 public static final String REMOTE_INTENTS_SUPPORTED = "remote.intents.supported"

Service property identifying the intents supported by a distribution provider. Registered by the distribution provider on one of its services to indicate the vocabulary of implemented intents.

The value of this property must be of type String, String[], or Collection of String.

Remote Services Specification

1.6

10.1.15.93 public static final String REQUIRE_BUNDLE = "Require-Bundle"

Manifest header identifying the symbolic names of other bundles required by the bundle.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.3

10.1.15.94 public static final String REQUIRE_CAPABILITY = "Require-Capability"

Manifest header identifying the capabilities on which the bundle depends.

The header value may be retrieved from the Dictionary object returned by the Bundle.getHeaders method.

1.6

10.1.15.95 public static final String RESOLUTION_DIRECTIVE = "resolution"

Manifest header directive identifying the resolution type in the Import-Package, Require-Bundle or Require-Capability manifest header. The default value is mandatory.

The directive value is encoded in the Import-Package, Require-Bundle or Require-Capability manifest header like:

     Import-Package: org.osgi.framework; resolution:="optional"
     Require-Bundle: com.acme.module.test; resolution:="optional"
     Require-Capability: com.acme.capability; resolution:="optional"

IMPORT_PACKAGE, REQUIRE_BUNDLE, REQUIRE_CAPABILITY, RESOLUTION_MANDATORY, RESOLUTION_OPTIONAL

1.3

10.1.15.96 public static final String RESOLUTION_MANDATORY = "mandatory"

Manifest header directive value identifying a mandatory resolution type. A mandatory resolution type indicates that the import package, require bundle or require capability must be resolved when the bundle is resolved. If such an import, require bundle or require capability cannot be resolved, the module fails to resolve.

The directive value is encoded in the Import-Package, Require-Bundle or Require-Capability manifest header like:

     Import-Package: org.osgi.framework; resolution:="mandatory"
     Require-Bundle: com.acme.module.test; resolution:="mandatory"
     Require-Capability: com.acme.capability; resolution:="mandatory"

RESOLUTION_DIRECTIVE

1.3

10.1.15.97 public static final String RESOLUTION_OPTIONAL = "optional"

Manifest header directive value identifying an optional resolution type. An optional resolution type indicates that the import, require bundle or require capability is optional and the bundle may be resolved without the import, require bundle or require capability being resolved. If the import, require bundle or require capability is not resolved when the bundle is resolved, the import, require bundle or require capability may not be resolved until the bundle is refreshed.

The directive value is encoded in the Import-Package, Require-Bundle or Require-Capability manifest header like:

     Import-Package: org.osgi.framework; resolution:="optional"
     Require-Bundle: com.acme.module.test; resolution:="optional"
     Require-Capability: com.acme.capability; resolution:="optional"

RESOLUTION_DIRECTIVE

1.3

10.1.15.98 public static final String SCOPE_BUNDLE = "bundle"

Service scope is bundle. Each bundle using the service receives a customized service object.

SERVICE_SCOPE

1.8

10.1.15.99 public static final String SCOPE_PROTOTYPE = "prototype"

Service scope is prototype. Each bundle using the service receives either a customized service object or can request multiple customized service objects via ServiceObjects.

SERVICE_SCOPE

1.8

10.1.15.100 public static final String SCOPE_SINGLETON = "singleton"

Service scope is singleton. All bundles using the service receive the same service object.

SERVICE_SCOPE

1.8

10.1.15.101 public static final String SELECTION_FILTER_ATTRIBUTE = "selection-filter"

Manifest header attribute is used for selection by filtering based upon system properties.

The attribute value is encoded in manifest headers like:

     Bundle-NativeCode: libgtk.so; selection-filter="(ws=gtk)"; ...

BUNDLE_NATIVECODE

1.3

10.1.15.102 public static final String SERVICE_BUNDLEID = "service.bundleid"

Service property identifying the bundle id of the bundle registering the service.

This property is set by the Framework when a service is registered. The value of this property must be of type Long.

1.8

10.1.15.103 public static final String SERVICE_CHANGECOUNT = "service.changecount"

Service property identifying the monotonically increasing change count of a service.

A service may provide this property to indicate there has been a change in some data provided by the service. The change count must be incremented with a positive value every time the data provided by the service is changed. The service announces the modified change count by updating its service properties with the new value for this service property.

The value of this property must be of type Long.

1.9

10.1.15.104 public static final String SERVICE_DESCRIPTION = "service.description"

Service property identifying a service's description.

This property may be supplied in the properties Dictionary object passed to the BundleContext.registerService method.

10.1.15.105 public static final String SERVICE_EXPORTED_CONFIGS = "service.exported.configs"

Service property identifying the configuration types that should be used to export the service. Each configuration type represents the configuration parameters for an endpoint. A distribution provider should create an endpoint for each configuration type that it supports.

This property may be supplied in the properties Dictionary object passed to the BundleContext.registerService method. The value of this property must be of type String, String[], or Collection of String.

Remote Services Specification

1.6

10.1.15.106 public static final String SERVICE_EXPORTED_INTENTS = "service.exported.intents"

Service property identifying the intents that the distribution provider must implement to distribute the service. Intents listed in this property are reserved for intents that are critical for the code to function correctly, for example, ordering of messages. These intents should not be configurable.

This property may be supplied in the properties Dictionary object passed to the BundleContext.registerService method. The value of this property must be of type String, String[], or Collection of String.

Remote Services Specification

1.6

10.1.15.107 public static final String SERVICE_EXPORTED_INTENTS_EXTRA = "service.exported.intents.extra"

Service property identifying the extra intents that the distribution provider must implement to distribute the service. This property is merged with the service.exported.intents property before the distribution provider interprets the listed intents; it has therefore the same semantics but the property should be configurable so the administrator can choose the intents based on the topology. Bundles should therefore make this property configurable, for example through the Configuration Admin service.

This property may be supplied in the properties Dictionary object passed to the BundleContext.registerService method. The value of this property must be of type String, String[], or Collection of String.

Remote Services Specification

1.6

10.1.15.108 public static final String SERVICE_EXPORTED_INTERFACES = "service.exported.interfaces"

Service property marking the service for export. It defines the interfaces under which this service can be exported. This list must be a subset of the types under which the service was registered. The single value of an asterisk ('*' \u002A) indicates all the interface types under which the service was registered excluding the non-interface types. It is strongly recommended to only export interface types and not concrete classes due to the complexity of creating proxies for some type of concrete classes.

This property may be supplied in the properties Dictionary object passed to the BundleContext.registerService method. The value of this property must be of type String, String[], or Collection of String.

Remote Services Specification

1.6

10.1.15.109 public static final String SERVICE_ID = "service.id"

Service property identifying a service's registration number. The value of this property must be of type Long.

The value of this property is assigned by the Framework when a service is registered. The Framework assigns a unique, non-negative value that is larger than all previously assigned values since the Framework was started. These values are NOT persistent across restarts of the Framework.

10.1.15.110 public static final String SERVICE_IMPORTED = "service.imported"

Service property identifying the service as imported. This service property must be set by a distribution provider to any value when it registers the endpoint proxy as an imported service. A bundle can use this property to filter out imported services.

The value of this property may be of any type.

Remote Services Specification

1.6

10.1.15.111 public static final String SERVICE_IMPORTED_CONFIGS = "service.imported.configs"

Service property identifying the configuration types used to import the service. Any associated properties for this configuration types must be properly mapped to the importing system. For example, a URL in these properties must point to a valid resource when used in the importing framework. If multiple configuration types are listed in this property, then they must be synonyms for exactly the same remote endpoint that is used to export this service.

The value of this property must be of type String, String[], or Collection of String.

Remote Services Specification, SERVICE_EXPORTED_CONFIGS

1.6

10.1.15.112 public static final String SERVICE_INTENTS = "service.intents"

Service property identifying the intents that this service implements. This property has a dual purpose:

  • A bundle can use this service property to notify the distribution provider that these intents are already implemented by the exported service object.

  • A distribution provider must use this property to convey the combined intents of: the exporting service, the intents that the exporting distribution provider adds, and the intents that the importing distribution provider adds.

To export a service, a distribution provider must expand any qualified intents. Both the exporting and importing distribution providers must recognize all intents before a service can be distributed.

The value of this property must be of type String, String[], or Collection of String.

Remote Services Specification

1.6

10.1.15.113 public static final String SERVICE_PID = "service.pid"

Service property identifying a service's persistent identifier.

This property may be supplied in the properties Dictionary object passed to the BundleContext.registerService method. The value of this property must be of type String, String[], or Collection of String.

A service's persistent identifier uniquely identifies the service and persists across multiple Framework invocations.

By convention, every bundle has its own unique namespace, starting with the bundle's identifier (see Bundle.getBundleId()) and followed by a dot (.). A bundle may use this as the prefix of the persistent identifiers for the services it registers.

10.1.15.114 public static final String SERVICE_RANKING = "service.ranking"

Service property identifying a service's ranking number.

This property may be supplied in the properties Dictionary object passed to the BundleContext.registerService method. The value of this property must be of type Integer.

The service ranking is used by the Framework to determine the natural order of services, see ServiceReference.compareTo(Object), and the default service to be returned from a call to the BundleContext.getServiceReference(Class) or BundleContext.getServiceReference(String) method.

The default ranking is zero (0). A service with a ranking of Integer.MAX_VALUE is very likely to be returned as the default service, whereas a service with a ranking of Integer.MIN_VALUE is very unlikely to be returned.

If the supplied property value is not of type Integer, it is deemed to have a ranking value of zero.

10.1.15.115 public static final String SERVICE_SCOPE = "service.scope"

Service property identifying a service's scope.

This property is set by the Framework when a service is registered. If the registered object implements PrototypeServiceFactory, then the value of this service property will be SCOPE_PROTOTYPE. Otherwise, if the registered object implements ServiceFactory, then the value of this service property will be SCOPE_BUNDLE. Otherwise, the value of this service property will be SCOPE_SINGLETON.

SCOPE_SINGLETON, SCOPE_BUNDLE, SCOPE_PROTOTYPE

1.8

10.1.15.116 public static final String SERVICE_VENDOR = "service.vendor"

Service property identifying a service's vendor.

This property may be supplied in the properties Dictionary object passed to the BundleContext.registerService method.

10.1.15.117 public static final String SINGLETON_DIRECTIVE = "singleton"

Manifest header directive identifying whether a bundle is a singleton. The default value is false.

The directive value is encoded in the Bundle-SymbolicName manifest header like:

     Bundle-SymbolicName: com.acme.module.test; singleton:=true

BUNDLE_SYMBOLICNAME

1.3

10.1.15.118 public static final String SUPPORTS_BOOTCLASSPATH_EXTENSION = "org.osgi.supports.bootclasspath.extension"

Framework environment property identifying whether the Framework supports bootclasspath extension bundles.

If the value of this property is true, then the Framework supports bootclasspath extension bundles. The default value is false.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

1.3

As of 1.10.

10.1.15.119 public static final String SUPPORTS_FRAMEWORK_EXTENSION = "org.osgi.supports.framework.extension"

Framework environment property identifying whether the Framework supports framework extension bundles.

As of version 1.4, the value of this property must be true. The Framework must support framework extension bundles.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

1.3

10.1.15.120 public static final String SUPPORTS_FRAMEWORK_FRAGMENT = "org.osgi.supports.framework.fragment"

Framework environment property identifying whether the Framework supports fragment bundles.

As of version 1.4, the value of this property must be true. The Framework must support fragment bundles.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

1.3

10.1.15.121 public static final String SUPPORTS_FRAMEWORK_REQUIREBUNDLE = "org.osgi.supports.framework.requirebundle"

Framework environment property identifying whether the Framework supports the Require-Bundle manifest header.

As of version 1.4, the value of this property must be true. The Framework must support the Require-Bundle manifest header.

The value of this property may be retrieved by calling the BundleContext.getProperty method.

1.3

10.1.15.122 public static final long SYSTEM_BUNDLE_ID = 0L

Identifier of the OSGi system bundle , which is defined to be 0.

1.8

10.1.15.123 public static final String SYSTEM_BUNDLE_LOCATION = "System Bundle"

Location identifier of the OSGi system bundle , which is defined to be "System Bundle".

10.1.15.124 public static final String SYSTEM_BUNDLE_SYMBOLICNAME = "system.bundle"

Alias for the symbolic name of the OSGi system bundle . It is defined to be "system.bundle".

1.3

10.1.15.125 public static final String USES_DIRECTIVE = "uses"

Manifest header directive identifying a list of packages that an exported package or provided capability uses.

The directive value is encoded in the Export-Package or Provide-Capability manifest header like:

     Export-Package: org.osgi.util.tracker; uses:="org.osgi.framework"
     Provide-Capability: com.acme.capability; uses:="com.acme.service"

EXPORT_PACKAGE, PROVIDE_CAPABILITY

1.3

10.1.15.126 public static final String VERSION_ATTRIBUTE = "version"

Manifest header attribute identifying the version of a package specified in the Export-Package or Import-Package manifest header.

The attribute value is encoded in the Export-Package or Import-Package manifest header like:

     Export-Package: org.osgi.framework; version="1.1"

EXPORT_PACKAGE, IMPORT_PACKAGE

1.3

10.1.15.127 public static final String VISIBILITY_DIRECTIVE = "visibility"

Manifest header directive identifying the visibility of a required bundle in the Require-Bundle manifest header. The default value is private.

The directive value is encoded in the Require-Bundle manifest header like:

     Require-Bundle: com.acme.module.test; visibility:="reexport"

REQUIRE_BUNDLE, VISIBILITY_PRIVATE, VISIBILITY_REEXPORT

1.3

10.1.15.128 public static final String VISIBILITY_PRIVATE = "private"

Manifest header directive value identifying a private visibility type. A private visibility type indicates that any packages that are exported by the required bundle are not made visible on the export signature of the requiring bundle.

The directive value is encoded in the Require-Bundle manifest header like:

     Require-Bundle: com.acme.module.test; visibility:="private"

VISIBILITY_DIRECTIVE

1.3

10.1.15.129 public static final String VISIBILITY_REEXPORT = "reexport"

Manifest header directive value identifying a reexport visibility type. A reexport visibility type indicates any packages that are exported by the required bundle are re-exported by the requiring bundle. Any arbitrary matching attributes with which they were exported by the required bundle are deleted.

The directive value is encoded in the Require-Bundle manifest header like:

     Require-Bundle: com.acme.module.test; visibility:="reexport"

VISIBILITY_DIRECTIVE

1.3

10.1.16 public interface Filter

An RFC 1960-based Filter.

Filters can be created by calling BundleContext.createFilter(String) or FrameworkUtil.createFilter(String) with a filter string.

A Filter can be used numerous times to determine if the match argument matches the filter string that was used to create the Filter.

Some examples of LDAP filters are:

  "(cn=Babs Jensen)"
  "(!(cn=Tim Howes))"
  "(&(" + Constants.OBJECTCLASS + "=Person)(|(sn=Jensen)(cn=Babs J*)))"
  "(o=univ*of*mich*)"

Core Specification, Filters, for a description of the filter string syntax.

1.1

Thread-safe

Consumers of this API must not implement this type

10.1.16.1 public boolean equals(Object obj)

The object to compare against this Filter.

Compares this Filter to another Filter.

This implementation returns the result of calling this.toString().equals(obj.toString()).

If the other object is a Filter object, then returns the result of calling this.toString().equals(obj.toString()); false otherwise.

10.1.16.2 public int hashCode()

Returns the hashCode for this Filter.

This implementation returns the result of calling this.toString().hashCode().

The hashCode of this Filter.

10.1.16.3 public boolean match(ServiceReference<?> reference)

The reference to the service whose properties are used in the match.

Filter using a service's properties.

This Filter is executed using the keys and values of the referenced service's properties. The keys are looked up in a case insensitive manner.

true if the service's properties match this Filter; false otherwise.

10.1.16.4 public boolean match(Dictionary<String, ?> dictionary)

The Dictionary whose key/value pairs are used in the match.

Filter using a Dictionary with case insensitive key lookup. This Filter is executed using the specified Dictionary's keys and values. The keys are looked up in a case insensitive manner.

true if the Dictionary's values match this filter; false otherwise.

IllegalArgumentException– If dictionary contains case variants of the same key name.

10.1.16.5 public boolean matchCase(Dictionary<String, ?> dictionary)

The Dictionary whose key/value pairs are used in the match.

Filter using a Dictionary. This Filter is executed using the specified Dictionary's keys and values. The keys are looked up in a normal manner respecting case.

true if the Dictionary's values match this filter; false otherwise.

1.3

10.1.16.6 public boolean matches(Map<String, ?> map)

The Map whose key/value pairs are used in the match. Maps with null key or values are not supported. A null value is considered not present to the filter.

Filter using a Map. This Filter is executed using the specified Map's keys and values. The keys are looked up in a normal manner respecting case.

true if the Map's values match this filter; false otherwise.

1.6

10.1.16.7 public String toString()

Returns this Filter's filter string.

The filter string is normalized by removing whitespace which does not affect the meaning of the filter.

This Filter's filter string.

10.1.17 public class FrameworkEvent
extends EventObject

A general event from the Framework.

FrameworkEvent objects are delivered to FrameworkListeners when a general event occurs within the OSGi environment. A type code is used to identify the event type for future extendability.

OSGi Working Group reserves the right to extend the set of event types.

FrameworkListener

Immutable

10.1.17.1 public static final int ERROR = 2

An error has occurred.

There was an error associated with a bundle.

10.1.17.2 public static final int INFO = 32

An informational event has occurred.

There was an informational event associated with a bundle.

1.3

10.1.17.3 public static final int PACKAGES_REFRESHED = 4

A FrameworkWiring.refreshBundles operation has completed.

This event is fired when the Framework has completed the refresh bundles operation initiated by a call to the FrameworkWiring.refreshBundles method. The source of this event is the System Bundle.

FrameworkWiring.refreshBundles(java.util.Collection, FrameworkListener...)

1.2

10.1.17.4 public static final int STARTED = 1

The Framework has started.

This event is fired when the Framework has started after all installed bundles that are marked to be started have been started and the Framework has reached the initial start level. The source of this event is the System Bundle.

The Start Level Specification

10.1.17.5 public static final int STARTLEVEL_CHANGED = 8

A FrameworkStartLevel.setStartLevel operation has completed.

This event is fired when the Framework has completed changing the active start level initiated by a call to the StartLevel.setStartLevel method. The source of this event is the System Bundle.

FrameworkStartLevel.setStartLevel(int, FrameworkListener...)

1.2

10.1.17.6 public static final int STOPPED = 64

The Framework has stopped.

This event is fired when the Framework has been stopped because of a stop operation on the system bundle. The source of this event is the System Bundle.

1.5

10.1.17.7 public static final int STOPPED_BOOTCLASSPATH_MODIFIED = 256

The Framework has stopped and the boot class path has changed.

This event is fired when the Framework has been stopped because of a stop operation on the system bundle and a bootclasspath extension bundle has been installed or updated. The source of this event is the System Bundle.

1.5

As of 1.10.

10.1.17.8 public static final int STOPPED_SYSTEM_REFRESHED = 1024

The Framework has stopped and the framework requires a new class loader to restart.

This event is fired when the Framework has been stopped because of a refresh operation on the system bundle and the framework requires a new class loader to be used to restart. For example, if a framework extension bundle has been refreshed. The source of this event is the System Bundle.

1.9

10.1.17.9 public static final int STOPPED_UPDATE = 128

The Framework has stopped during update.

This event is fired when the Framework has been stopped because of an update operation on the system bundle. The Framework will be restarted after this event is fired. The source of this event is the System Bundle.

1.5

10.1.17.10 public static final int WAIT_TIMEDOUT = 512

The Framework did not stop before the wait timeout expired.

This event is fired when the Framework did not stop before the wait timeout expired. The source of this event is the System Bundle.

1.5

10.1.17.11 public static final int WARNING = 16

A warning has occurred.

There was a warning associated with a bundle.

1.3

10.1.17.12 public FrameworkEvent(int type, Object source)

The event type.

The event source object. This may not be null.

Creates a Framework event.

As of 1.2. This constructor is deprecated in favor of using the other constructor with the System Bundle as the event source.

10.1.17.13 public FrameworkEvent(int type, Bundle bundle, Throwable throwable)

The event type.

The event source.

The related exception. This argument may be null if there is no related exception.

Creates a Framework event regarding the specified bundle.

10.1.17.14 public Bundle getBundle()

Returns the bundle associated with the event. This bundle is also the source of the event.

The bundle associated with the event.

10.1.17.15 public Throwable getThrowable()

Returns the exception related to this event.

The related exception or null if none.

10.1.17.16 public int getType()

Returns the type of framework event.

The type values are:

The type of state change.

10.1.18 public interface FrameworkListener
extends EventListener

A FrameworkEvent listener. FrameworkListener is a listener interface that may be implemented by a bundle developer. When a FrameworkEvent is fired, it is asynchronously delivered to a FrameworkListener. The Framework delivers FrameworkEvent objects to a FrameworkListener in order and must not concurrently call a FrameworkListener.

A FrameworkListener object is registered with the Framework using the BundleContext.addFrameworkListener(FrameworkListener) method. FrameworkListener objects are called with a FrameworkEvent objects when the Framework starts and when asynchronous errors occur.

FrameworkEvent

Not Thread-safe

10.1.18.1 public void frameworkEvent(FrameworkEvent event)

The FrameworkEvent object.

Receives notification of a general FrameworkEvent object.

10.1.19 public class FrameworkUtil

Framework Utility class.

This class contains utility methods which access Framework functions that may be useful to bundles.

1.3

Thread-safe

10.1.19.1 public static Dictionary<K, V> asDictionary(Map<? extends K, ? extends V> map)

<K, V>

The type of the key.

The type of the value.

The map to wrap.

Return a Dictionary wrapper around a Map.

A Dictionary object which wraps the specified map. If the specified map can be cast to a Dictionary, then the specified map is returned.

1.10

10.1.19.2 public static Map<K, V> asMap(Dictionary<? extends K, ? extends V> dictionary)

<K, V>

The type of the key.

The type of the value.

The dictionary to wrap.

Return a Map wrapper around a Dictionary.

A Map object which wraps the specified dictionary. If the specified dictionary can be cast to a Map, then the specified dictionary is returned.

1.10

10.1.19.3 public static Filter createFilter(String filter)

The filter string.

Creates a Filter object. This Filter object may be used to match a ServiceReference object or a Dictionary object.

If the filter cannot be parsed, an InvalidSyntaxException will be thrown with a human readable message where the filter became unparsable.

This method returns a Filter implementation which may not perform as well as the framework implementation-specific Filter implementation returned by BundleContext.createFilter(String).

A Filter object encapsulating the filter string.

InvalidSyntaxException– If filter contains an invalid filter string that cannot be parsed.

NullPointerException– If filter is null.

Filter

10.1.19.4 public static Optional<Bundle> getBundle(ClassLoader bundleClassLoader)

A bundle class loader.

Return a Bundle for the specified bundle class loader.

An Optional containing Bundle for the specified bundle class loader or an empty Optional if the specified class loader is not associated with a specific bundle.

1.10

10.1.19.5 public static Bundle getBundle(Class<?> classFromBundle)

A class defined by a bundle.

Return a Bundle for the specified bundle class.

A Bundle for the specified bundle class or null if the specified class was not defined by a bundle.

1.5

10.1.19.6 public static boolean matchDistinguishedNameChain(String matchPattern, List<String> dnChain)

The pattern against which to match the DN chain.

The DN chain to match against the specified pattern. Each element of the chain must be of type String and use the format defined in RFC 2253.

Match a Distinguished Name (DN) chain against a pattern. DNs can be matched using wildcards. A wildcard ('*' \u002A) replaces all possible values. Due to the structure of the DN, the comparison is more complicated than string-based wildcard matching.

A wildcard can stand for zero or more DNs in a chain, a number of relative distinguished names (RDNs) within a DN, or the value of a single RDN. The DNs in the chain and the matching pattern are canonicalized before processing. This means, among other things, that spaces must be ignored, except in values.

The format of a wildcard match pattern is:

 matchPattern ::= dn-match ( ';' dn-match ) *
 dn-match     ::= ( '*' | rdn-match ) ( ',' rdn-match ) * | '-'
 rdn-match    ::= name '=' value-match
 value-match  ::= '*' | value-star
 value-star   ::= < value, requires escaped '*' and '-' >

The most simple case is a single wildcard; it must match any DN. A wildcard can also replace the first list of RDNs of a DN. The first RDNs are the least significant. Such lists of matched RDNs can be empty.

For example, a match pattern with a wildcard that matches all DNs that end with RDNs of o=ACME and c=US would look like this:

 *, o=ACME, c=US

This match pattern would match the following DNs:

 cn = Bugs Bunny, o = ACME, c = US
 ou = Carrots, cn=Daffy Duck, o=ACME, c=US
 street = 9C\, Avenue St. Drézéry, o=ACME, c=US
 dc=www, dc=acme, dc=com, o=ACME, c=US
 o=ACME, c=US

The following DNs would not match:

 street = 9C\, Avenue St. Drézéry, o=ACME, c=FR
 dc=www, dc=acme, dc=com, c=US

If a wildcard is used for a value of an RDN, the value must be exactly *. The wildcard must match any value, and no substring matching must be done. For example:

 cn=*,o=ACME,c=*

This match pattern with wildcard must match the following DNs:

 cn=Bugs Bunny,o=ACME,c=US
 cn = Daffy Duck , o = ACME , c = US
 cn=Road Runner, o=ACME, c=NL

But not:

 o=ACME, c=NL
 dc=acme.com, cn=Bugs Bunny, o=ACME, c=US

A match pattern may contain a chain of DN match patterns. The semicolon( ';' \u003B) must be used to separate DN match patterns in a chain. Wildcards can also be used to match against a complete DN within a chain.

The following example matches a certificate signed by Tweety Inc. in the US.

 * ; ou=S & V, o=Tweety Inc., c=US

The wildcard ('*') matches zero or one DN in the chain, however, sometimes it is necessary to match a longer chain. The minus sign ( '-' \u002D) represents zero or more DNs, whereas the asterisk only represents a single DN. For example, to match a DN where the Tweety Inc. is in the DN chain, use the following expression:

 - ; *, o=Tweety Inc., c=US

true If the pattern matches the DN chain; otherwise false is returned.

IllegalArgumentException– If the specified match pattern or DN chain is invalid.

1.5

10.1.20 public class InvalidSyntaxException
extends RuntimeException

A Framework exception used to indicate that a filter string has an invalid syntax.

An InvalidSyntaxException object indicates that a filter string parameter has an invalid syntax and cannot be parsed. See Filter for a description of the filter string syntax.

This exception conforms to the general purpose exception chaining mechanism.

10.1.20.1 public InvalidSyntaxException(String msg, String filter)

The message.

The invalid filter string.

Creates an exception of type InvalidSyntaxException.

This method creates an InvalidSyntaxException object with the specified message and the filter string which generated the exception.

10.1.20.2 public InvalidSyntaxException(String msg, String filter, Throwable cause)

The message.

The invalid filter string.

The cause of this exception.

Creates an exception of type InvalidSyntaxException.

This method creates an InvalidSyntaxException object with the specified message and the filter string which generated the exception.

1.3

10.1.20.3 public Throwable getCause()

Returns the cause of this exception or null if no cause was set.

The cause of this exception or null if no cause was set.

1.3

10.1.20.4 public String getFilter()

Returns the filter string that generated the InvalidSyntaxException object.

The invalid filter string.

BundleContext.getServiceReferences(Class, String), BundleContext.getServiceReferences(String, String), BundleContext.addServiceListener(ServiceListener,String)

10.1.20.5 public Throwable initCause(Throwable cause)

The cause of this exception.

Initializes the cause of this exception to the specified value.

This exception.

IllegalArgumentException– If the specified cause is this exception.

IllegalStateException– If the cause of this exception has already been set.

1.3

10.1.21 public final class PackagePermission
extends BasicPermission

A bundle's authority to import or export a package.

A package is a dot-separated string that defines a fully qualified Java package.

For example:

 org.osgi.service.servlet.runtime

PackagePermission has three actions: exportonly, import and export. The export action, which is deprecated, implies the import action.

Thread-safe

10.1.21.1 public static final String EXPORT = "export"

The action string export. The export action implies the import action.

As of 1.5. Use exportonly instead.

10.1.21.2 public static final String EXPORTONLY = "exportonly"

The action string exportonly. The exportonly action does not imply the import action.

1.5

10.1.21.3 public static final String IMPORT = "import"

The action string import.

10.1.21.4 public PackagePermission(String name, String actions)

Package name or filter expression. A filter expression can only be specified if the specified action is import.

exportonly,import (canonical order).

Creates a new PackagePermission object.

The name is specified as a normal Java package name: a dot-separated string. Wildcards may be used.

 name ::= <package name> | <package name ending in ".*"> | *

Examples:

 org.osgi.service.servlet.runtime
 jakarta.servlet.*
 *

For the import action, the name can also be a filter expression. The filter gives access to the following attributes:

  • signer - A Distinguished Name chain used to sign the exporting bundle. Wildcards in a DN are not matched according to the filter string rules, but according to the rules defined for a DN chain.

  • location - The location of the exporting bundle.

  • id - The bundle ID of the exporting bundle.

  • name - The symbolic name of the exporting bundle.

  • package.name - The name of the requested package.

Filter attribute names are processed in a case sensitive manner.

Package Permissions are granted over all possible versions of a package. A bundle that needs to export a package must have the appropriate PackagePermission for that package; similarly, a bundle that needs to import a package must have the appropriate PackagePermssion for that package.

Permission is granted for both classes and resources.

IllegalArgumentException– If the specified name is a filter expression and either the specified action is not import or the filter has an invalid syntax.

10.1.21.5 public PackagePermission(String name, Bundle exportingBundle, String actions)

The name of the requested package to import.

The bundle exporting the requested package.

The action import.

Creates a new requested PackagePermission object to be used by code that must perform checkPermission for the import action. PackagePermission objects created with this constructor cannot be added to a PackagePermission permission collection.

IllegalArgumentException– If the specified action is not import or the name is a filter expression.

1.5

10.1.21.6 public boolean equals(Object obj)

The object to test for equality with this PackagePermission object.

Determines the equality of two PackagePermission objects. This method checks that specified package has the same package name and PackagePermission actions as this PackagePermission object.

true if obj is a PackagePermission, and has the same package name and actions as this PackagePermission object; false otherwise.

10.1.21.7 public String getActions()

Returns the canonical string representation of the PackagePermission actions.

Always returns present PackagePermission actions in the following order: EXPORTONLY,IMPORT.

Canonical string representation of the PackagePermission actions.

10.1.21.8 public int hashCode()

Returns the hash code value for this object.

A hash code value for this object.

10.1.21.9 public boolean implies(Permission p)

The requested permission.

Determines if the specified permission is implied by this object.

This method checks that the package name of the target is implied by the package name of this object. The list of PackagePermission actions must either match or allow for the list of the target object to imply the target PackagePermission action.

The permission to export a package implies the permission to import the named package.

 x.y.*,"export" -> x.y.z,"export" is true
 *,"import" -> x.y, "import"      is true
 *,"export" -> x.y, "import"      is true
 x.y,"export" -> x.y.z, "export"  is false

true if the specified permission is implied by this object; false otherwise.

10.1.21.10 public PermissionCollection newPermissionCollection()

Returns a new PermissionCollection object suitable for storing PackagePermission objects.

A new PermissionCollection object.

10.1.22 public interface PrototypeServiceFactory<S>
extends ServiceFactory<S>

Type of Service

A factory for prototype scope services. The factory can provide multiple, customized service objects in the OSGi environment.

When registering a service, a PrototypeServiceFactory object can be used instead of a service object, so that the bundle developer can create a customized service object for each caller that is using the service.

When a caller uses a ServiceObjects to request a service object, the framework calls the getService method to return a service object customized for the requesting caller. The caller can release the returned service object and the framework will call the ungetService method with the service object.

When a bundle uses the BundleContext.getService(ServiceReference) method to obtain a service object, the framework must act as if the service has bundle scope. That is, the framework will call the getService method to obtain a bundle-scoped service object which will be cached and have a use count. See ServiceFactory.

A bundle can use both ServiceObjects and BundleContext.getService(ServiceReference) to obtain a service object for a service. ServiceObjects.getService() will always return a service object provided by a call to getService(Bundle, ServiceRegistration) and BundleContext.getService(ServiceReference) will always return the bundle-scoped service object.

PrototypeServiceFactory objects are only used by the Framework and are not made available to other bundles in the OSGi environment. The Framework may concurrently call a PrototypeServiceFactory.

BundleContext.getServiceObjects(ServiceReference), ServiceObjects

1.8

Thread-safe

10.1.22.1 public S getService(Bundle bundle, ServiceRegistration<S> registration)

The bundle requesting the service.

The ServiceRegistration object for the requested service.

Returns a service object for a caller.

The Framework invokes this method for each caller requesting a service object using ServiceObjects.getService(). The factory can then return a customized service object for the caller.

The Framework must check that the returned service object is valid. If the returned service object is null or is not an instanceof all the classes named when the service was registered, a framework event of type FrameworkEvent.ERROR is fired containing a service exception of type ServiceException.FACTORY_ERROR and null is returned to the caller. If this method throws an exception, a framework event of type FrameworkEvent.ERROR is fired containing a service exception of type ServiceException.FACTORY_EXCEPTION with the thrown exception as the cause and null is returned to the caller.

A service object that must be an instance of all the classes named when the service was registered.

ServiceObjects.getService()

10.1.22.2 public void ungetService(Bundle bundle, ServiceRegistration<S> registration, S service)

The bundle releasing the service.

The ServiceRegistration object for the service being released.

The service object returned by a previous call to the getService method.

Releases a service object customized for a caller.

The Framework invokes this method when a service has been released by a bundle such as by calling ServiceObjects.ungetService(Object). The service object may then be destroyed.

If this method throws an exception, a framework event of type FrameworkEvent.ERROR is fired containing a service exception of type ServiceException.FACTORY_EXCEPTION with the thrown exception as the cause.

ServiceObjects.ungetService(Object)

10.1.23 public class ServiceEvent
extends EventObject

An event from the Framework describing a service lifecycle change.

ServiceEvent objects are delivered to ServiceListeners, AllServiceListeners and UnfilteredServiceListeners when a change occurs in this service's lifecycle. A type code is used to identify the event type for future extendability.

OSGi Working Group reserves the right to extend the set of types.

ServiceListener, AllServiceListener, UnfilteredServiceListener

Immutable

10.1.23.1 public static final int MODIFIED = 2

The properties of a registered service have been modified.

This event is synchronously delivered after the service properties have been modified.

ServiceRegistration.setProperties(Dictionary)

10.1.23.2 public static final int MODIFIED_ENDMATCH = 8

The properties of a registered service have been modified and the new properties no longer match the listener's filter.

This event is synchronously delivered after the service properties have been modified. This event is only delivered to listeners which were added with a non-null filter where the filter matched the service properties prior to the modification but the filter does not match the modified service properties.

ServiceRegistration.setProperties(Dictionary)

1.5

10.1.23.3 public static final int REGISTERED = 1

This service has been registered.

This event is synchronously delivered after the service has been registered with the Framework.

BundleContext.registerService(String[],Object,Dictionary)

10.1.23.4 public static final int UNREGISTERING = 4

This service is in the process of being unregistered.

This event is synchronously delivered before the service has completed unregistering.

If a bundle is using a service that is UNREGISTERING, the bundle should release its use of the service when it receives this event. If the bundle does not release its use of the service when it receives this event, the Framework will automatically release the bundle's use of the service while completing the service unregistration operation.

ServiceRegistration.unregister(), BundleContext.ungetService(ServiceReference)

10.1.23.5 public ServiceEvent(int type, ServiceReference<?> reference)

The event type.

A ServiceReference object to the service that had a lifecycle change.

Creates a new service event object.

10.1.23.6 public ServiceReference<?> getServiceReference()

Returns a reference to the service that had a change occur in its lifecycle.

This reference is the source of the event.

Reference to the service that had a lifecycle change.

10.1.23.7 public int getType()

Returns the type of event. The event type values are:

Type of service lifecycle change.

10.1.24 public class ServiceException
extends RuntimeException

A service exception used to indicate that a service problem occurred.

A ServiceException object is created by the Framework or service implementation to denote an exception condition in the service. A type code is used to identify the exception type for future extendability. Service implementations may also create subclasses of ServiceException. When subclassing, the subclass should set the type to SUBCLASSED to indicate that ServiceException has been subclassed.

This exception conforms to the general purpose exception chaining mechanism.

1.5

10.1.24.1 public static final int ASYNC_ERROR = 7

An asynchronous operation was unable to obtain the service.

1.8

10.1.24.2 public static final int FACTORY_ERROR = 2

The service factory produced an invalid service object.

10.1.24.3 public static final int FACTORY_EXCEPTION = 3

The service factory threw an exception.

10.1.24.4 public static final int FACTORY_RECURSION = 6

The service factory resulted in a recursive call to itself for the requesting bundle.

1.6

10.1.24.5 public static final int REMOTE = 5

An error occurred invoking a remote service.

10.1.24.6 public static final int SUBCLASSED = 4

The exception is a subclass of ServiceException. The subclass should be examined for the type of the exception.

10.1.24.7 public static final int UNREGISTERED = 1

The service has been unregistered.

10.1.24.8 public static final int UNSPECIFIED = 0

No exception type is unspecified.

10.1.24.9 public ServiceException(String msg, Throwable cause)

The associated message.

The cause of this exception.

Creates a ServiceException with the specified message and exception cause.

10.1.24.10 public ServiceException(String msg)

The message.

Creates a ServiceException with the specified message.

10.1.24.11 public ServiceException(String msg, int type, Throwable cause)

The associated message.

The type for this exception.

The cause of this exception.

Creates a ServiceException with the specified message, type and exception cause.

10.1.24.12 public ServiceException(String msg, int type)

The message.

The type for this exception.

Creates a ServiceException with the specified message and type.

10.1.24.13 public int getType()

Returns the type for this exception or UNSPECIFIED if the type was unspecified or unknown.

The type of this exception.

10.1.25 public interface ServiceFactory<S>

Type of Service

A factory for bundle scope services. The factory can provide service objects customized for each bundle in the OSGi environment.

When registering a service, a ServiceFactory object can be used instead of a service object, so that the bundle developer can create a customized service object for each bundle that is using the service.

When a bundle requests the service object, the framework calls the getService method to return a service object customized for the requesting bundle. The returned service object is cached by the Framework for subsequent calls to BundleContext.getService(ServiceReference) until the bundle releases its use of the service.

When the bundle's use count for the service is decremented to zero (including the bundle stopping or the service being unregistered), the framework will call the ungetService method.

ServiceFactory objects are only used by the Framework and are not made available to other bundles in the OSGi environment. The Framework may concurrently call a ServiceFactory.

BundleContext.getService(ServiceReference)

Thread-safe

10.1.25.1 public S getService(Bundle bundle, ServiceRegistration<S> registration)

The bundle requesting the service.

The ServiceRegistration object for the requested service.

Returns a service object for a bundle.

The Framework invokes this method the first time the specified bundle requests a service object using the BundleContext.getService(ServiceReference) method. The factory can then return a customized service object for each bundle.

The Framework must check that the returned service object is valid. If the returned service object is null or is not an instanceof all the classes named when the service was registered, a framework event of type FrameworkEvent.ERROR is fired containing a service exception of type ServiceException.FACTORY_ERROR and null is returned to the bundle. If this method throws an exception, a framework event of type FrameworkEvent.ERROR is fired containing a service exception of type ServiceException.FACTORY_EXCEPTION with the thrown exception as the cause and null is returned to the bundle. If this method is recursively called for the specified bundle, a framework event of type FrameworkEvent.ERROR is fired containing a service exception of type ServiceException.FACTORY_RECURSION and null is returned to the bundle.

The Framework caches the valid service object and will return the same service object on any future call to BundleContext.getService(ServiceReference) for the specified bundle. This means the Framework must not allow this method to be concurrently called for the specified bundle.

A service object that must be an instance of all the classes named when the service was registered.

BundleContext.getService(ServiceReference)

10.1.25.2 public void ungetService(Bundle bundle, ServiceRegistration<S> registration, S service)

The bundle releasing the service.

The ServiceRegistration object for the service being released.

The service object returned by a previous call to the getService method.

Releases a service object customized for a bundle.

The Framework invokes this method when a service has been released by a bundle. The service object may then be destroyed.

If this method throws an exception, a framework event of type FrameworkEvent.ERROR is fired containing a service exception of type ServiceException.FACTORY_EXCEPTION with the thrown exception as the cause.

BundleContext.ungetService(ServiceReference)

10.1.26 public interface ServiceListener
extends EventListener

A ServiceEvent listener. ServiceListener is a listener interface that may be implemented by a bundle developer. When a ServiceEvent is fired, it is synchronously delivered to a ServiceListener. The Framework may deliver ServiceEvent objects to a ServiceListener out of order and may concurrently call and/or reenter a ServiceListener.

A ServiceListener object is registered with the Framework using the BundleContext.addServiceListener method. ServiceListener objects are called with a ServiceEvent object when a service is registered, modified, or is in the process of unregistering.

ServiceEvent object delivery to ServiceListener objects is filtered by the filter specified when the listener was registered. If the Java Runtime Environment supports permissions, then additional filtering is done. ServiceEvent objects are only delivered to the listener if the bundle which defines the listener object's class has the appropriate ServicePermission to get the service using at least one of the named classes under which the service was registered.

ServiceEvent object delivery to ServiceListener objects is further filtered according to package sources as defined in ServiceReference.isAssignableTo(Bundle, String).

ServiceEvent, ServicePermission

Thread-safe

10.1.26.1 public void serviceChanged(ServiceEvent event)

The ServiceEvent object.

Receives notification that a service has had a lifecycle change.

10.1.27 public interface ServiceObjects<S>

Type of Service

Allows multiple service objects for a service to be obtained.

For services with prototype scope, multiple service objects for the service can be obtained. Since implementations of PrototypeServiceFactory can return the same service object repeatedly, the framework must use count the returned service objects to release the service object only when its use count returns to zero.

For services with singleton or bundle scope, only one, use-counted service object is available to a requesting bundle.

Any unreleased service objects obtained from this ServiceObjects object are automatically released by the framework when the bundle associated with the BundleContext used to create this ServiceObjects object is stopped.

BundleContext.getServiceObjects(ServiceReference), PrototypeServiceFactory

1.8

Thread-safe

Consumers of this API must not implement this type

10.1.27.1 public S getService()

Returns a service object for the associated service.

This ServiceObjects object can be used to obtain multiple service objects for the associated service if the service has prototype scope.

If the associated service has singleton or bundle scope, this method behaves the same as calling the BundleContext.getService(ServiceReference) method for the associated service. That is, only one, use-counted service object is available from this ServiceObjects object.

This method will always return null when the associated service has been unregistered.

For a prototype scope service, the following steps are required to obtain a service object:

  1. If the associated service has been unregistered, null is returned.

  2. The PrototypeServiceFactory.getService(Bundle, ServiceRegistration) method is called to supply a customized service object for the caller.

  3. If the service object returned by the PrototypeServiceFactory object is null, not an instanceof all the classes named when the service was registered or the PrototypeServiceFactory object throws an exception, null is returned and a Framework event of type FrameworkEvent.ERROR containing a ServiceException describing the error is fired.

  4. The use count for the customized service object is incremented by one.

  5. The customized service object is returned.

A service object for the associated service or null if the service is not registered, the customized service object returned by a ServiceFactory does not implement the classes under which it was registered or the ServiceFactory threw an exception.

IllegalStateException– If the BundleContext used to create this ServiceObjects object is no longer valid.

ungetService(Object)

10.1.27.2 public ServiceReference<S> getServiceReference()

Returns the ServiceReference for the service associated with this ServiceObjects object.

The ServiceReference for the service associated with this ServiceObjects object.

10.1.27.3 public void ungetService(S service)

A service object previously provided by this ServiceObjects object.

Releases a service object for the associated service.

This ServiceObjects object can be used to obtain multiple service objects for the associated service if the service has prototype scope. If the associated service has singleton or bundle scope, this method behaves the same as calling the BundleContext.ungetService(ServiceReference) method for the associated service. That is, only one, use-counted service object is available from this ServiceObjects object.

For a prototype scope service, the following steps are required to release a service object:

  1. If the associated service has been unregistered, this method returns without doing anything.

  2. The use count for the specified service object is decremented by one.

  3. If the use count for the specified service object is now zero, the PrototypeServiceFactory.ungetService(Bundle, ServiceRegistration, Object) method is called to release the specified service object.

The specified service object must no longer be used and all references to it should be destroyed after calling this method when the use count has returned to zero.

IllegalArgumentException– If the specified service object is null or was not provided by a ServiceObjects object for the associated service.

getService()

10.1.28 public final class ServicePermission
extends BasicPermission

A bundle's authority to register or get a service.

  • The register action allows a bundle to register a service on the specified names.

  • The get action allows a bundle to detect a service and get it.

Permission to get a service is required in order to detect events regarding the service. Untrusted bundles should not be able to detect the presence of certain services unless they have the appropriate ServicePermission to get the specific service.

Thread-safe

10.1.28.1 public static final String GET = "get"

The action string get.

10.1.28.2 public static final String REGISTER = "register"

The action string register.

10.1.28.3 public ServicePermission(String name, String actions)

The service class name

get,register (canonical order)

Create a new ServicePermission.

The name of the service is specified as a fully qualified class name. Wildcards may be used.

 name ::= <class name> | <class name ending in ".*"> | *

Examples:

 org.osgi.service.servlet.runtime.HttpServiceRuntime
 org.osgi.service.servlet.runtime.*
 *

For the get action, the name can also be a filter expression. The filter gives access to the service properties as well as the following attributes:

  • signer - A Distinguished Name chain used to sign the bundle publishing the service. Wildcards in a DN are not matched according to the filter string rules, but according to the rules defined for a DN chain.

  • location - The location of the bundle publishing the service.

  • id - The bundle ID of the bundle publishing the service.

  • name - The symbolic name of the bundle publishing the service.

Since the above attribute names may conflict with service property names used by a service, you can prefix an attribute name with '@' in the filter expression to match against the service property and not one of the above attributes. Filter attribute names are processed in a case sensitive manner unless the attribute references a service property. Service properties names are case insensitive.

There are two possible actions: get and register. The get permission allows the owner of this permission to obtain a service with this name. The register permission allows the bundle to register a service under that name.

IllegalArgumentException– If the specified name is a filter expression and either the specified action is not get or the filter has an invalid syntax.

10.1.28.4 public ServicePermission(ServiceReference<?> reference, String actions)

The requested service.

The action get.

Creates a new requested ServicePermission object to be used by code that must perform checkPermission for the get action. ServicePermission objects created with this constructor cannot be added to a ServicePermission permission collection.

IllegalArgumentException– If the specified action is not get or reference is null.

1.5

10.1.28.5 public boolean equals(Object obj)

The object to test for equality.

Determines the equality of two ServicePermission objects. Checks that specified object has the same class name and action as this ServicePermission.

true if obj is a ServicePermission, and has the same class name and actions as this ServicePermission object; false otherwise.

10.1.28.6 public String getActions()

Returns the canonical string representation of the actions. Always returns present actions in the following order: get, register.

The canonical string representation of the actions.

10.1.28.7 public int hashCode()

Returns the hash code value for this object.

Hash code value for this object.

10.1.28.8 public boolean implies(Permission p)

The target permission to check.

Determines if a ServicePermission object "implies" the specified permission.

true if the specified permission is implied by this object; false otherwise.

10.1.28.9 public PermissionCollection newPermissionCollection()

Returns a new PermissionCollection object for storing ServicePermission objects.

A new PermissionCollection object suitable for storing ServicePermission objects.

10.1.29 public interface ServiceReference<S>
extends Comparable<Object>, BundleReference

Type of Service.

A reference to a service.

The Framework returns ServiceReference objects from the BundleContext.getServiceReference and BundleContext.getServiceReferences methods.

A ServiceReference object may be shared between bundles and can be used to examine the properties of the service and to get the service object.

Every service registered in the Framework has a unique ServiceRegistration object and may have multiple, distinct ServiceReference objects referring to it. ServiceReference objects associated with a ServiceRegistration object have the same hashCode and are considered equal (more specifically, their equals() method will return true when compared).

If the same service object is registered multiple times, ServiceReference objects associated with different ServiceRegistration objects are not equal.

BundleContext.getServiceReference(Class), BundleContext.getServiceReference(String), BundleContext.getServiceReferences(Class, String), BundleContext.getServiceReferences(String, String), BundleContext.getService(ServiceReference), BundleContext.getServiceObjects(ServiceReference)

Thread-safe

Consumers of this API must not implement this type

10.1.29.1 public A adapt(Class<A> type)

<A>

The type to which this ServiceReference object is to be adapted.

Class object for the type to which this ServiceReference object is to be adapted.

Adapt this ServiceReference object to the specified type.

Adapting this ServiceReference object to the specified type may require certain checks, including security checks, to succeed. If a check does not succeed, then this ServiceReference object cannot be adapted and null is returned.

The object, of the specified type, to which this ServiceReference object has been adapted or null if this ServiceReference object cannot be adapted to the specified type.

SecurityException– If the caller does not have the appropriate AdaptPermission[type,this,ADAPT], and the Java Runtime Environment supports permissions.

1.10

10.1.29.2 public int compareTo(Object reference)

The ServiceReference to be compared.

Compares this ServiceReference with the specified ServiceReference for order.

Natural Order

If this ServiceReference and the specified ServiceReference have the same service id they are equal. This ServiceReference is less than the specified ServiceReference if it has a lower service ranking and greater if it has a higher service ranking. Otherwise, if this ServiceReference and the specified ServiceReference have the same service ranking, this ServiceReference is less than the specified ServiceReference if it has a higher service id and greater if it has a lower service id.

Sorting a collection of ServiceReference objects with natural order will result in the first element having the lowest service ranking and the last element having the highest service ranking.

Ranking Order

Ranking order, as defined in the Core Specification, is the reverse of natural order.

Sorting a collection of ServiceReference objects with ranking order will result in the first element having the highest service ranking and the last element having the lowest service ranking.

Returns a negative integer, zero, or a positive integer if this ServiceReference is less than, equal to, or greater than the specified ServiceReference.

IllegalArgumentException– If the specified ServiceReference was not created by the same framework instance as this ServiceReference.

Core Specification, Service Ranking Order

1.4

10.1.29.3 public Bundle getBundle()

Returns the bundle that registered the service referenced by this ServiceReference object.

This method must return null when the service has been unregistered. This can be used to determine if the service has been unregistered.

The bundle that registered the service referenced by this ServiceReference object; null if that service has already been unregistered.

BundleContext.registerService(String[],Object,Dictionary)

10.1.29.4 public Dictionary<String, Object> getProperties()

Returns a copy of the properties of the service referenced by this ServiceReference object.

This method will continue to return the properties after the service has been unregistered. This is so references to unregistered services (for example, ServiceReference objects stored in the log) can still be interrogated.

The returned Dictionary object:

A copy of the properties of the service referenced by this ServiceReference object

1.9

10.1.29.5 public Object getProperty(String key)

The property key.

Returns the property value to which the specified property key is mapped in the properties Dictionary object of the service referenced by this ServiceReference object.

Property keys are case-insensitive.

This method must continue to return property values after the service has been unregistered. This is so references to unregistered services (for example, ServiceReference objects stored in the log) can still be interrogated.

The property value to which the key is mapped; null if there is no property named after the key.

10.1.29.6 public String[] getPropertyKeys()

Returns an array of the keys in the properties Dictionary object of the service referenced by this ServiceReference object.

This method will continue to return the keys after the service has been unregistered. This is so references to unregistered services (for example, ServiceReference objects stored in the log) can still be interrogated.

This method is case-preserving ; this means that every key in the returned array must have the same case as the corresponding key in the properties Dictionary that was passed to the BundleContext.registerService(String[],Object,Dictionary) or ServiceRegistration.setProperties(Dictionary) methods.

An array of property keys.

10.1.29.7 public Bundle[] getUsingBundles()

Returns the bundles that are using the service referenced by this ServiceReference object. Specifically, this method returns the bundles whose usage count for that service is greater than zero.

An array of bundles whose usage count for the service referenced by this ServiceReference object is greater than zero; null if no bundles are currently using that service.

1.1

10.1.29.8 public boolean isAssignableTo(Bundle bundle, String className)

The Bundle object to check.

The class name to check.

Tests if the bundle that registered the service referenced by this ServiceReference and the specified bundle use the same source for the package of the specified class name.

This method performs the following checks:

  1. If the specified bundle is equal to the bundle that registered the service referenced by this ServiceReference (registrant bundle) return true.

  2. Get the package name from the specified class name.

  3. For the specified bundle; find the source for the package. If no source is found then return true (use of reflection is assumed by the specified bundle).

  4. For the registrant bundle; find the source for the package. If the package source is found then return true if the package source equals the package source of the specified bundle; otherwise return false.

  5. If no package source is found for the registrant bundle then determine the package source based on the service object. If the service object is a ServiceFactory and the factory implementation is not from the registrant bundle return true; otherwise attempt to find the package source based on the service object class. If the package source is found and is equal to package source of the specified bundle return true; otherwise return false.

true if the bundle which registered the service referenced by this ServiceReference and the specified bundle use the same source for the package of the specified class name. Otherwise false is returned.

IllegalArgumentException– If the specified Bundle was not created by the same framework instance as this ServiceReference.

1.3

10.1.30 public interface ServiceRegistration<S>

Type of Service.

A registered service.

The Framework returns a ServiceRegistration object when a BundleContext.registerService method invocation is successful. The ServiceRegistration object is for the private use of the registering bundle and should not be shared with other bundles.

The ServiceRegistration object may be used to update the properties of the service or to unregister the service.

BundleContext.registerService(String[],Object,Dictionary)

Thread-safe

Consumers of this API must not implement this type

10.1.30.1 public ServiceReference<S> getReference()

Returns a ServiceReference object for a service being registered.

The ServiceReference object may be shared with other bundles.

ServiceReference object.

IllegalStateException– If this ServiceRegistration object has already been unregistered.

10.1.30.2 public void setProperties(Dictionary<String, ?> properties)

The properties for this service. See Constants for a list of standard service property keys. Changes should not be made to this object after calling this method. To update the service's properties this method should be called again.

Updates the properties associated with a service.

The Constants.OBJECTCLASS, Constants.SERVICE_BUNDLEID, Constants.SERVICE_ID and Constants.SERVICE_SCOPE keys cannot be modified by this method. These values are set by the Framework when the service is registered in the OSGi environment.

The following steps are required to modify service properties:

  1. The service's properties are replaced with the provided properties.

  2. A service event of type ServiceEvent.MODIFIED is fired.

IllegalStateException– If this ServiceRegistration object has already been unregistered.

IllegalArgumentException– If properties contains case variants of the same key name.

10.1.30.3 public void unregister()

Unregisters a service. Remove a ServiceRegistration object from the Framework service registry. All ServiceReference objects associated with this ServiceRegistration object can no longer be used to interact with the service once unregistration is complete.

The following steps are required to unregister a service:

  1. If this ServiceRegistration object has already been unregistered, then this method does nothing and returns.

  2. The service is removed from the Framework service registry so that it can no longer be obtained.

  3. A service event of type ServiceEvent.UNREGISTERING is fired so that bundles using this service can release their use of the service. Once delivery of the service event is complete, the ServiceReference objects for the service may no longer be used to get a service object for the service.

  4. For each bundle whose use count for this service is greater than zero:

    • The bundle's use count for this service is set to zero.

    • If the service was registered with a ServiceFactory object, the ServiceFactory.ungetService method is called to release the service object for the bundle.

BundleContext.ungetService(ServiceReference), ServiceFactory.ungetService(Bundle, ServiceRegistration, Object)

10.1.31 public interface SynchronousBundleListener
extends BundleListener

A synchronous BundleEvent listener. SynchronousBundleListener is a listener interface that may be implemented by a bundle developer. When a BundleEvent is fired, it is synchronously delivered to a SynchronousBundleListener. The Framework may deliver BundleEvent objects to a SynchronousBundleListener out of order and may concurrently call and/or reenter a SynchronousBundleListener.

For BundleEvent types STARTED and LAZY_ACTIVATION, the Framework must not hold the referenced bundle's "state change" lock when the BundleEvent is delivered to a SynchronousBundleListener. For the other BundleEvent types, the Framework must hold the referenced bundle's "state change" lock when the BundleEvent is delivered to a SynchronousBundleListener. A SynchronousBundleListener cannot directly call life cycle methods on the referenced bundle when the Framework is holding the referenced bundle's "state change" lock.

A SynchronousBundleListener object is registered with the Framework using the BundleContext.addBundleListener(BundleListener) method. SynchronousBundleListener objects are called with a BundleEvent object when a bundle has been installed, resolved, starting, started, stopping, stopped, updated, unresolved, or uninstalled.

Unlike normal BundleListener objects, SynchronousBundleListeners are synchronously called during bundle lifecycle processing. The bundle lifecycle processing will not proceed until all SynchronousBundleListeners have completed. SynchronousBundleListener objects will be called prior to BundleListener objects.

AdminPermission[bundle,LISTENER] is required to add or remove a SynchronousBundleListener object.

BundleEvent

1.1

Thread-safe

10.1.32 public interface UnfilteredServiceListener
extends ServiceListener

A ServiceEvent listener that does not filter based upon any filter string specified to BundleContext.addServiceListener(ServiceListener, String). Using an UnfilteredServiceListener and specifying a filter string to BundleContext.addServiceListener(ServiceListener, String) allows the listener to receive all ServiceEvent objects while still advising ListenerHook implementation of the service interests in the filter string. For example, an implementation of Declarative Services would add an UnfilteredServiceListener with a filter string listing all the services referenced by all the service components. The Declarative Services implementation would receive all ServiceEvent objects for internal processing and a Remote Services discovery service implementation can observe the service interests of the service components using a ListenerHook. When the set of service components being processed changes, the Declarative Services implementation would re-add the UnfilteredServiceListener with an updated filter string.

When a ServiceEvent is fired, it is synchronously delivered to an UnfilteredServiceListener. The Framework may deliver ServiceEvent objects to an UnfilteredServiceListener out of order and may concurrently call and/or reenter an UnfilteredServiceListener.

An UnfilteredServiceListener object is registered with the Framework using the BundleContext.addServiceListener method. UnfilteredServiceListener objects are called with a ServiceEvent object when a service is registered, modified, or is in the process of unregistering.

ServiceEvent object delivery to UnfilteredServiceListener objects are not filtered by the filter specified when the listener was registered. If the Java Runtime Environment supports permissions, then some filtering is done. ServiceEvent objects are only delivered to the listener if the bundle which defines the listener object's class has the appropriate ServicePermission to get the service using at least one of the named classes under which the service was registered.

ServiceEvent, ServicePermission

1.7

Thread-safe

10.1.33 public class Version
implements Comparable<Version>

Version identifier for capabilities such as bundles and packages.

Version identifiers have four components.

  1. Major version. A non-negative integer.

  2. Minor version. A non-negative integer.

  3. Micro version. A non-negative integer.

  4. Qualifier. A text string. See Version(String) for the format of the qualifier string.

Version objects are immutable.

1.3

Immutable

10.1.33.1 public static final Version emptyVersion

The empty version "0.0.0".

10.1.33.2 public Version(int major, int minor, int micro)

Major component of the version identifier.

Minor component of the version identifier.

Micro component of the version identifier.

Creates a version identifier from the specified numerical components.

The qualifier is set to the empty string.

IllegalArgumentException– If the numerical components are negative.

10.1.33.3 public Version(int major, int minor, int micro, String qualifier)

Major component of the version identifier.

Minor component of the version identifier.

Micro component of the version identifier.

Qualifier component of the version identifier. If null is specified, then the qualifier will be set to the empty string.

Creates a version identifier from the specified components.

IllegalArgumentException– If the numerical components are negative or the qualifier string is invalid.

10.1.33.4 public Version(String version)

String representation of the version identifier. There must be no whitespace in the argument.

Creates a version identifier from the specified string.

Version string grammar:

 version ::= major('.'minor('.'micro('.'qualifier)?)?)?
 major ::= digit+
 minor ::= digit+
 micro ::= digit+
 qualifier ::= (alpha|digit|'_'|'-')+
 digit ::= [0..9]
 alpha ::= [a..zA..Z]

IllegalArgumentException– If version is improperly formatted.

10.1.33.5 public int compareTo(Version other)

The Version object to be compared.

Compares this Version object to another Version.

A version is considered to be less than another version if its major component is less than the other version's major component, or the major components are equal and its minor component is less than the other version's minor component, or the major and minor components are equal and its micro component is less than the other version's micro component, or the major, minor and micro components are equal and it's qualifier component is less than the other version's qualifier component (using String.compareTo).

A version is considered to be equal to another version if the major, minor and micro components are equal and the qualifier component is equal (using String.compareTo).

A negative integer, zero, or a positive integer if this version is less than, equal to, or greater than the specified Version object.

ClassCastException– If the specified object is not a Version object.

10.1.33.6 public boolean equals(Object object)

The Version object to be compared.

Compares this Version object to another object.

A version is considered to be equal to another version if the major, minor and micro components are equal and the qualifier component is equal (using String.equals).

true if object is a Version and is equal to this object; false otherwise.

10.1.33.7 public int getMajor()

Returns the major component of this version identifier.

The major component.

10.1.33.8 public int getMicro()

Returns the micro component of this version identifier.

The micro component.

10.1.33.9 public int getMinor()

Returns the minor component of this version identifier.

The minor component.

10.1.33.10 public String getQualifier()

Returns the qualifier component of this version identifier.

The qualifier component.

10.1.33.11 public int hashCode()

Returns a hash code value for the object.

An integer which is a hash code value for this object.

10.1.33.12 public static Version parseVersion(String version)

String representation of the version identifier. Leading and trailing whitespace will be ignored.

Parses a version identifier from the specified string.

See Version(String) for the format of the version string.

A Version object representing the version identifier. If version is null or the empty string then emptyVersion will be returned.

IllegalArgumentException– If version is improperly formatted.

10.1.33.13 public String toString()

Returns the string representation of this version identifier.

The format of the version string will be major.minor.micro if qualifier is the empty string or major.minor.micro.qualifier otherwise.

The string representation of this version identifier.

10.1.33.14 public static Version valueOf(String version)

String representation of the version identifier. Leading and trailing whitespace will be ignored. Must not be null.

Returns a Version object holding the version identifier in the specified String.

See Version(String) for the format of the version string.

This method performs a similar function as parseVersion(String) but has the static factory valueOf(String) method signature.

A Version object representing the version identifier. If version is the empty string then emptyVersion will be returned.

IllegalArgumentException– If version is improperly formatted.

1.8

10.1.34 public class VersionRange

Version range. A version range is an interval describing a set of versions.

A range has a left (lower) endpoint and a right (upper) endpoint. Each endpoint can be open (excluded from the set) or closed (included in the set).

VersionRange objects are immutable.

1.7

Immutable

10.1.34.1 public static final char LEFT_CLOSED = 91

The left endpoint is closed and is included in the range.

The value of LEFT_CLOSED is '['.

10.1.34.2 public static final char LEFT_OPEN = 40

The left endpoint is open and is excluded from the range.

The value of LEFT_OPEN is '('.

10.1.34.3 public static final char RIGHT_CLOSED = 93

The right endpoint is closed and is included in the range.

The value of RIGHT_CLOSED is ']'.

10.1.34.4 public static final char RIGHT_OPEN = 41

The right endpoint is open and is excluded from the range.

The value of RIGHT_OPEN is ')'.

10.1.34.5 public VersionRange(char leftType, Version leftEndpoint, Version rightEndpoint, char rightType)

Must be either LEFT_CLOSED or LEFT_OPEN .

Left endpoint of range. Must not be null.

Right endpoint of range. May be null to indicate the right endpoint is Infinity.

Must be either RIGHT_CLOSED or RIGHT_OPEN.

Creates a version range from the specified versions.

IllegalArgumentException– If the arguments are invalid.

10.1.34.6 public VersionRange(String range)

String representation of the version range. The versions in the range must contain no whitespace. Other whitespace in the range string is ignored. Must not be null.

Creates a version range from the specified string.

Version range string grammar:

 range ::= interval | atleast
 interval ::= ( '[' | '(' ) left ',' right ( ']' | ')' )
 left ::= version
 right ::= version
 atleast ::= version

IllegalArgumentException– If range is improperly formatted.

10.1.34.7 public boolean equals(Object object)

The VersionRange object to be compared.

Compares this VersionRange object to another object.

A version range is considered to be equal to another version range if both the endpoints and their types are equal or if both version ranges are empty.

true if object is a VersionRange and is equal to this object; false otherwise.

10.1.34.8 public Version getLeft()

Returns the left endpoint of this version range.

The left endpoint.

10.1.34.9 public char getLeftType()

Returns the type of the left endpoint of this version range.

LEFT_CLOSED if the left endpoint is closed or LEFT_OPEN if the left endpoint is open.

10.1.34.10 public Version getRight()

Returns the right endpoint of this version range.

The right endpoint. May be null which indicates the right endpoint is Infinity.

10.1.34.11 public char getRightType()

Returns the type of the right endpoint of this version range.

RIGHT_CLOSED if the right endpoint is closed or RIGHT_OPEN if the right endpoint is open.

10.1.34.12 public int hashCode()

Returns a hash code value for the object.

An integer which is a hash code value for this object.

10.1.34.13 public boolean includes(Version version)

The version to test for inclusion in this version range.

Returns whether this version range includes the specified version.

true if the specified version is included in this version range; false otherwise.

10.1.34.14 public VersionRange intersection(VersionRange... ranges)

The version ranges to intersect with this version range.

Returns the intersection of this version range with the specified version ranges.

A version range representing the intersection of this version range and the specified version ranges. If no version ranges are specified, then this version range is returned.

10.1.34.15 public boolean isEmpty()

Returns whether this version range is empty. A version range is empty if the set of versions defined by the interval is empty.

true if this version range is empty; false otherwise.

10.1.34.16 public boolean isExact()

Returns whether this version range contains only a single version.

true if this version range contains only a single version; false otherwise.

10.1.34.17 public String toFilterString(String attributeName)

The attribute name to use in the returned filter string.

Returns the filter string for this version range using the specified attribute name.

A filter string for this version range using the specified attribute name.

IllegalArgumentException– If the specified attribute name is not a valid attribute name.

Core Specification, Filters, for a description of the filter string syntax.

10.1.34.18 public String toString()

Returns the string representation of this version range.

The format of the version range string will be a version string if the right end point is Infinity (null) or an interval string.

The string representation of this version range.

10.1.34.19 public static VersionRange valueOf(String range)

String representation of the version range. The versions in the range must contain no whitespace. Other whitespace in the range string is ignored. Must not be null.

Returns a VersionRange object holding the version range in the specified String.

See VersionRange(String) for the format of the version range string.

A VersionRange object representing the version range.

IllegalArgumentException– If range is improperly formatted.

1.8

10.2 org.osgi.framework.launch

Version 1.2

Framework Launch Package Version 1.2.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest.

Example import for consumers using the API in this package:

Import-Package: org.osgi.framework.launch; version="[1.2,2.0)"

10.2.1 Summary

10.2.2 public interface Framework
extends Bundle

A Framework instance. A Framework is also known as a System Bundle.

Framework instances are created using a FrameworkFactory. The methods of this interface can be used to manage and control the created framework instance.

Thread-safe

Consumers of this API must not implement this type

10.2.2.1 public A adapt(Class<A> type)

<A>

The type to which this Framework is to be adapted.

Class object for the type to which this Framework is to be adapted.

Adapt this Framework to the specified type.

Adapting this Framework to the specified type may require certain checks, including security checks, to succeed. If a check does not succeed, then this Framework cannot be adapted and null is returned. If this Framework is not initialized, then null is returned if the specified type is one of the OSGi defined types to which a system bundle can be adapted.

The object, of the specified type, to which this Framework has been adapted or null if this Framework cannot be adapted

10.2.2.2 public Enumeration<URL> findEntries(String path, String filePattern, boolean recurse)

Ignored.

Ignored.

Ignored.

Returns null as a framework implementation does not have a proper bundle from which to return entries.

null as a framework implementation does not have a proper bundle from which to return entries.

10.2.2.3 public long getBundleId()

Returns the Framework unique identifier. This Framework is assigned the unique identifier zero (0) since this Framework is also a System Bundle.

0.

Bundle.getBundleId()

10.2.2.4 public URL getEntry(String path)

Ignored.

Returns null as a framework implementation does not have a proper bundle from which to return an entry.

null as a framework implementation does not have a proper bundle from which to return an entry.

10.2.2.5 public Enumeration<String> getEntryPaths(String path)

Ignored.

Returns null as a framework implementation does not have a proper bundle from which to return entry paths.

null as a framework implementation does not have a proper bundle from which to return entry paths.

10.2.2.6 public long getLastModified()

Returns the time when the set of bundles in this framework was last modified. The set of bundles is considered to be modified when a bundle is installed, updated or uninstalled.

The time value is the number of milliseconds since January 1, 1970, 00:00:00 UTC.

The time when the set of bundles in this framework was last modified.

10.2.2.7 public String getLocation()

Returns the Framework location identifier. This Framework is assigned the unique location "System Bundle" since this Framework is also a System Bundle.

The string "System Bundle".

SecurityException– If the caller does not have the appropriate AdminPermission[this,METADATA], and the Java Runtime Environment supports permissions.

Bundle.getLocation(), Constants.SYSTEM_BUNDLE_LOCATION

10.2.2.8 public String getSymbolicName()

Returns the symbolic name of this Framework. The symbolic name is unique for the implementation of the framework. However, the symbolic name "system.bundle" must be recognized as an alias to the implementation-defined symbolic name since this Framework is also a System Bundle.

The symbolic name of this Framework.

Bundle.getSymbolicName(), Constants.SYSTEM_BUNDLE_SYMBOLICNAME

10.2.2.9 public void init() throws BundleException

Initialize this Framework.

This method performs the same function as calling init(FrameworkListener...) with no framework listeners.

BundleException– If this Framework could not be initialized.

SecurityException– If the Java Runtime Environment supports permissions and the caller does not have the appropriate AdminPermission[this,EXECUTE] or if there is a security manager already installed and the Constants.FRAMEWORK_SECURITY configuration property is set.

init(FrameworkListener...)

10.2.2.10 public void init(FrameworkListener... listeners) throws BundleException

Zero or more listeners to be notified when framework events occur while initializing the framework. The specified listeners do not need to be otherwise registered with the framework. If a specified listener is registered with the framework, it will be notified twice for each framework event.

Initialize this Framework. After calling this method, this Framework must:

  • Have generated a new framework UUID.

  • Be in the STARTING state.

  • Have a valid Bundle Context.

  • Be at start level 0.

  • Have event handling enabled.

  • Have reified Bundle objects for all installed bundles.

  • Have registered any framework services. For example, ConditionalPermissionAdmin.

  • Be adaptable to the OSGi defined types to which a system bundle can be adapted.

  • Have called the start method of the extension bundle activator for all resolved extension bundles.

This Framework will not actually be started until start is called.

This method does nothing if called when this Framework is in the STARTING, ACTIVE or STOPPING states.

All framework events fired by this method are also delivered to the specified FrameworkListeners in the order they are specified before returning from this method. After returning from this method the specified listeners are no longer notified of framework events.

BundleException– If this Framework could not be initialized.

SecurityException– If the Java Runtime Environment supports permissions and the caller does not have the appropriate AdminPermission[this,EXECUTE] or if there is a security manager already installed and the Constants.FRAMEWORK_SECURITY configuration property is set.

1.2

10.2.2.11 public void start() throws BundleException

Start this Framework.

The following steps are taken to start this Framework:

  1. If this Framework is not in the STARTING state, initialize this Framework.

  2. All installed bundles must be started in accordance with each bundle's persistent autostart setting. This means some bundles will not be started, some will be started with eager activation and some will be started with their declared activation policy. The start level of this Framework is moved to the start level specified by the beginning start level framework property, as described in the Start Level Specification. If this framework property is not specified, then the start level of this Framework is moved to start level one (1). Any exceptions that occur during bundle starting must be wrapped in a BundleException and then published as a framework event of type FrameworkEvent.ERROR

  3. This Framework's state is set to ACTIVE.

  4. A framework event of type FrameworkEvent.STARTED is fired

BundleException– If this Framework could not be started.

SecurityException– If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

Start Level Specification

10.2.2.12 public void start(int options) throws BundleException

Ignored. There are no start options for the Framework.

Start this Framework.

Calling this method is the same as calling start(). There are no start options for the Framework.

BundleException– If this Framework could not be started.

SecurityException– If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

start()

10.2.2.13 public void stop() throws BundleException

Stop this Framework.

The method returns immediately to the caller after initiating the following steps to be taken on another thread.

  1. This Framework's state is set to STOPPING.

  2. All installed bundles must be stopped without changing each bundle's persistent autostart setting. The start level of this Framework is moved to start level zero (0), as described in the Start Level Specification. Any exceptions that occur during bundle stopping must be wrapped in a BundleException and then published as a framework event of type FrameworkEvent.ERROR

  3. Unregister all services registered by this Framework.

  4. Event handling is disabled.

  5. This Framework's state is set to RESOLVED.

  6. All resources held by this Framework are released. This includes threads, bundle class loaders, open files, etc.

  7. Notify all threads that are waiting at waitForStop that the stop operation has completed.

After being stopped, this Framework may be discarded, initialized or started.

BundleException– If stopping this Framework could not be initiated.

SecurityException– If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

Start Level Specification

10.2.2.14 public void stop(int options) throws BundleException

Ignored. There are no stop options for the Framework.

Stop this Framework.

Calling this method is the same as calling stop(). There are no stop options for the Framework.

BundleException– If stopping this Framework could not be initiated.

SecurityException– If the caller does not have the appropriate AdminPermission[this,EXECUTE], and the Java Runtime Environment supports permissions.

stop()

10.2.2.15 public void uninstall() throws BundleException

The Framework cannot be uninstalled.

This method always throws a BundleException.

BundleException– This Framework cannot be uninstalled.

SecurityException– If the caller does not have the appropriate AdminPermission[this,LIFECYCLE], and the Java Runtime Environment supports permissions.

10.2.2.16 public void update() throws BundleException

Stop and restart this Framework.

The method returns immediately to the caller after initiating the following steps to be taken on another thread.

  1. Perform the steps in the stop() method to stop this Framework.

  2. Perform the steps in the start() method to start this Framework.

BundleException– If stopping and restarting this Framework could not be initiated.

SecurityException– If the caller does not have the appropriate AdminPermission[this,LIFECYCLE], and the Java Runtime Environment supports permissions.

10.2.2.17 public void update(InputStream in) throws BundleException

Any provided InputStream is immediately closed before returning from this method and otherwise ignored.

Stop and restart this Framework.

Calling this method is the same as calling update() except that any provided InputStream is immediately closed.

BundleException– If stopping and restarting this Framework could not be initiated.

SecurityException– If the caller does not have the appropriate AdminPermission[this,LIFECYCLE], and the Java Runtime Environment supports permissions.

10.2.2.18 public FrameworkEvent waitForStop(long timeout) throws InterruptedException

Maximum number of milliseconds to wait until this Framework has completely stopped. A value of zero will wait indefinitely.

Wait until this Framework has completely stopped. The stop and update methods on a Framework performs an asynchronous stop of the Framework. This method can be used to wait until the asynchronous stop of this Framework has completed. This method will only wait if called when this Framework is in the STARTING, ACTIVE, or STOPPING states. Otherwise it will return immediately.

A Framework Event is returned to indicate why this Framework has stopped.

A Framework Event indicating the reason this method returned. The following FrameworkEvent types may be returned by this method.

  • STOPPED - This Framework has been stopped.

  • STOPPED_UPDATE - This Framework has been updated which has shutdown and will now restart.

  • STOPPED_SYSTEM_REFRESHED - The Framework has been stopped because of a refresh operation on the system bundle. A new class loader must be used to restart the Framework.

  • ERROR - The Framework encountered an error while shutting down or an error has occurred which forced the framework to shutdown.

  • WAIT_TIMEDOUT - This method has timed out and returned before this Framework has stopped.

InterruptedException– If another thread interrupted the current thread before or while the current thread was waiting for this Framework to completely stop. The interrupted status of the current thread is cleared when this exception is thrown.

IllegalArgumentException– If the value of timeout is negative.

10.2.3 public interface FrameworkFactory

A factory for creating Framework instances.

A framework implementation jar must contain the following resource:

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

This UTF-8 encoded resource must contain the name of the framework implementation's FrameworkFactory implementation class. Space and tab characters, including blank lines, in the resource must be ignored. The number sign ('#' \u0023) and all characters following it on each line are a comment and must be ignored.

Launchers can find the name of the FrameworkFactory implementation class in the resource and then load and construct a FrameworkFactory object for the framework implementation. The FrameworkFactory implementation class must have a public, no-argument constructor. Java™ SE 6 introduced the ServiceLoader class which can create a FrameworkFactory instance from the resource.

Thread-safe

Consumers of this API must not implement this type

10.2.3.1 public Framework newFramework(Map<String, String> configuration)

The framework properties to configure the new framework instance. If framework properties are not provided by the configuration argument, the created framework instance must use some reasonable default configuration appropriate for the current VM. For example, the system packages for the current execution environment should be properly exported. The specified configuration argument may be null. The created framework instance must copy any information needed from the specified configuration argument since the configuration argument can be changed after the framework instance has been created.

Create a new Framework instance.

A new, configured Framework instance. The framework instance must be in the Bundle.INSTALLED state.

SecurityException– If the caller does not have AllPermission, and the Java Runtime Environment supports permissions.

10.3 org.osgi.resource

Version 1.1

Resource Package Version 1.1.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. For example:

 Import-Package: org.osgi.resource; version="[1.1,2.0)"

10.3.1 Summary

10.3.2 public interface Capability

A capability that has been declared from a Resource.

Instances of this type must be effectively immutable. That is, for a given instance of this interface, the methods defined by this interface must always return the same result.

Thread-safe

10.3.2.1 public boolean equals(Object obj)

The object to compare against this Capability.

Compares this Capability to another Capability.

This Capability is equal to another Capability if they have the same namespace, directives and attributes and are declared by the same resource.

true if this Capability is equal to the other object; false otherwise.

10.3.2.2 public Map<String, Object> getAttributes()

Returns the attributes of this capability.

An unmodifiable map of attribute names to attribute values for this capability, or an empty map if this capability has no attributes.

10.3.2.3 public Map<String, String> getDirectives()

Returns the directives of this capability.

An unmodifiable map of directive names to directive values for this capability, or an empty map if this capability has no directives.

10.3.2.4 public String getNamespace()

Returns the namespace of this capability.

The namespace of this capability.

10.3.2.5 public Resource getResource()

Returns the resource declaring this capability.

The resource declaring this capability.

10.3.2.6 public int hashCode()

Returns the hashCode of this Capability.

The hashCode of this Capability.

10.3.3 public abstract class Namespace

Capability and Requirement Namespaces base class.

This class is the common class shared by all OSGi defined namespaces. It defines the names for the common attributes and directives for the OSGi specified namespaces.

The OSGi Working Group reserves the right to extend the set of directives and attributes which have specified semantics for all of the specified namespaces.

The values associated with these keys are of type String, unless otherwise indicated.

Immutable

10.3.3.1 public static final String CAPABILITY_DEPRECATED_DIRECTIVE = "deprecated"

The capability directive used to specify that the capability has been deprecated. The value is the human-readable reason to developers for the deprecation. This reason should include the version in which the capability was deprecated and any removal plan.

Tooling can use the presence of this directive to provide deprecation warnings to developers when they use a capability that has been marked deprecated. Resolver hooks can use the deprecation information to report on the use of deprecated capabilities in a resolution.

1.1

10.3.3.2 public static final String CAPABILITY_EFFECTIVE_DIRECTIVE = "effective"

The capability directive used to specify the effective time for the capability. The default value is resolve.

resolve, active

10.3.3.3 public static final String CAPABILITY_USES_DIRECTIVE = "uses"

The capability directive used to specify the comma separated list of package names used by a capability.

10.3.3.4 public static final String CARDINALITY_MULTIPLE = "multiple"

The directive value identifying a multiple cardinality type.

REQUIREMENT_CARDINALITY_DIRECTIVE

10.3.3.5 public static final String CARDINALITY_SINGLE = "single"

The directive value identifying a cardinality type of single.

REQUIREMENT_CARDINALITY_DIRECTIVE

10.3.3.6 public static final String EFFECTIVE_ACTIVE = "active"

The directive value identifying a capability or requirement that is effective at active time. Capabilities and requirements with an effective time of active are ignored while resolving a resource.

REQUIREMENT_EFFECTIVE_DIRECTIVE, CAPABILITY_EFFECTIVE_DIRECTIVE

10.3.3.7 public static final String EFFECTIVE_RESOLVE = "resolve"

The directive value identifying a capability or requirement that is effective at resolve time. Capabilities and requirements with an effective time of resolve are the only capabilities which are processed while resolving a resource.

REQUIREMENT_EFFECTIVE_DIRECTIVE, CAPABILITY_EFFECTIVE_DIRECTIVE

10.3.3.8 public static final String REQUIREMENT_CARDINALITY_DIRECTIVE = "cardinality"

The requirement directive used to specify the cardinality for a requirement. The default value is single.

multiple, single

10.3.3.9 public static final String REQUIREMENT_EFFECTIVE_DIRECTIVE = "effective"

The requirement directive used to specify the effective time for the requirement. The default value is resolve.

resolve, active

10.3.3.10 public static final String REQUIREMENT_FILTER_DIRECTIVE = "filter"

The requirement directive used to specify a capability filter. This filter is used to match against a capability's attributes.

10.3.3.11 public static final String REQUIREMENT_RESOLUTION_DIRECTIVE = "resolution"

The requirement directive used to specify the resolution type for a requirement. The default value is mandatory .

mandatory, optional

10.3.3.12 public static final String RESOLUTION_MANDATORY = "mandatory"

The directive value identifying a mandatory requirement resolution type. A mandatory resolution type indicates that the requirement must be resolved when the resource is resolved. If such a requirement cannot be resolved, the resource fails to resolve.

REQUIREMENT_RESOLUTION_DIRECTIVE

10.3.3.13 public static final String RESOLUTION_OPTIONAL = "optional"

The directive value identifying an optional requirement resolution type. An optional resolution type indicates that the requirement is optional and the resource may be resolved without the requirement being resolved.

REQUIREMENT_RESOLUTION_DIRECTIVE

10.3.3.14 protected Namespace()

Protected constructor for Namespace sub-types.

10.3.4 public interface Requirement

A requirement that has been declared from a Resource .

Instances of this type must be effectively immutable. That is, for a given instance of this interface, the methods defined by this interface must always return the same result.

Thread-safe

10.3.4.1 public boolean equals(Object obj)

The object to compare against this Requirement.

Compares this Requirement to another Requirement.

This Requirement is equal to another Requirement if they have the same namespace, directives and attributes and are declared by the same resource.

true if this Requirement is equal to the other object; false otherwise.

10.3.4.2 public Map<String, Object> getAttributes()

Returns the attributes of this requirement.

Requirement attributes have no specified semantics and are considered extra user defined information.

An unmodifiable map of attribute names to attribute values for this requirement, or an empty map if this requirement has no attributes.

10.3.4.3 public Map<String, String> getDirectives()

Returns the directives of this requirement.

An unmodifiable map of directive names to directive values for this requirement, or an empty map if this requirement has no directives.

10.3.4.4 public String getNamespace()

Returns the namespace of this requirement.

The namespace of this requirement.

10.3.4.5 public Resource getResource()

Returns the resource declaring this requirement.

The resource declaring this requirement. This can be null if this requirement is synthesized.

10.3.4.6 public int hashCode()

Returns the hashCode of this Requirement.

The hashCode of this Requirement.

10.3.5 public interface Resource

A resource is the representation of a uniquely identified and typed data. A resource declares requirements that need to be satisfied by capabilities before it can provide its capabilities.

Instances of this type must be effectively immutable. That is, for a given instance of this interface, the methods defined by this interface must always return the same result.

Thread-safe

10.3.5.1 public boolean equals(Object obj)

The object to compare against this Resource.

Compares this Resource to another Resource.

This Resource is equal to another Resource if both have the same content and come from the same location. Location may be defined as the bundle location if the resource is an installed bundle or the repository location if the resource is in a repository.

true if this Resource is equal to the other object; false otherwise.

10.3.5.2 public List<Capability> getCapabilities(String namespace)

The namespace of the declared capabilities to return or null to return the declared capabilities from all namespaces.

Returns the capabilities declared by this resource.

An unmodifiable list containing the declared Capabilitys from the specified namespace. The returned list will be empty if this resource declares no capabilities in the specified namespace.

10.3.5.3 public List<Requirement> getRequirements(String namespace)

The namespace of the declared requirements to return or null to return the declared requirements from all namespaces.

Returns the requirements declared by this bundle resource.

An unmodifiable list containing the declared Requirement s from the specified namespace. The returned list will be empty if this resource declares no requirements in the specified namespace.

10.3.5.4 public int hashCode()

Returns the hashCode of this Resource.

The hashCode of this Resource.

10.3.6 public interface Wire

A wire connecting a Capability to a Requirement.

Instances of this type must be effectively immutable. That is, for a given instance of this interface, the methods defined by this interface must always return the same result.

Thread-safe

10.3.6.1 public boolean equals(Object obj)

The object to compare against this Wire.

Compares this Wire to another Wire.

This Wire is equal to another Wire if they have the same capability, requirement, provider and requirer.

true if this Wire is equal to the other object; false otherwise.

10.3.6.2 public Capability getCapability()

Returns the Capability for this wire.

The Capability for this wire.

10.3.6.3 public Resource getProvider()

Returns the resource providing the capability.

The returned resource may differ from the resource referenced by the capability.

The resource providing the capability.

10.3.6.4 public Requirement getRequirement()

Returns the Requirement for this wire.

The Requirement for this wire.

10.3.6.5 public Resource getRequirer()

Returns the resource who requires the capability.

The returned resource may differ from the resource referenced by the requirement.

The resource who requires the capability.

10.3.6.6 public int hashCode()

Returns the hashCode of this Wire.

The hashCode of this Wire.

10.3.7 public interface Wiring

A wiring for a resource. A wiring is associated with a resource and represents the dependencies with other wirings.

Instances of this type must be effectively immutable. That is, for a given instance of this interface, the methods defined by this interface must always return the same result.

Thread-safe

10.3.7.1 public List<Wire> getProvidedResourceWires(String namespace)

The namespace of the capabilities for which to return wires or null to return the wires for the capabilities in all namespaces.

Returns the Wires to the provided capabilities of this wiring.

A list containing a snapshot of the Wires for the capabilities of this wiring, or an empty list if this wiring has no capabilities in the specified namespace. For a given namespace, the list contains the wires in the order the capabilities were specified in the manifests of the resource and the attached fragment resources of this wiring. There is no ordering defined between capabilities in different namespaces.

10.3.7.2 public List<Wire> getRequiredResourceWires(String namespace)

The namespace of the requirements for which to return wires or null to return the wires for the requirements in all namespaces.

Returns the Wires to the requirements in use by this wiring.

A list containing a snapshot of the Wires for the requirements of this wiring, or an empty list if this wiring has no requirements in the specified namespace. For a given namespace, the list contains the wires in the order the requirements were specified in the manifests of the resource and the attached fragment resources of this wiring. There is no ordering defined between requirements in different namespaces.

10.3.7.3 public Resource getResource()

Returns the resource associated with this wiring.

The resource associated with this wiring.

10.3.7.4 public List<Capability> getResourceCapabilities(String namespace)

The namespace of the capabilities to return or null to return the capabilities from all namespaces.

Returns the capabilities provided by this wiring.

Only capabilities considered by the resolver are returned. For example, capabilities with effective directive not equal to resolve are not returned.

A capability may not be required by any wiring and thus there may be no wires for the capability.

A wiring for a non-fragment resource provides a subset of the declared capabilities from the resource and all attached fragment resources. Not all declared capabilities may be provided since some may be discarded. For example, if a package is declared to be both exported and imported, only one is selected and the other is discarded.

A wiring for a fragment resource with a symbolic name must provide exactly one osgi.identity capability.

† The osgi.identity capability provided by attached fragment resource must not be included in the capabilities of the host wiring.

A list containing a snapshot of the Capabilitys, or an empty list if this wiring provides no capabilities in the specified namespace. For a given namespace, the list contains the capabilities in the order the capabilities were specified in the manifests of the resource and the attached fragment resources of this wiring. There is no ordering defined between capabilities in different namespaces.

10.3.7.5 public List<Requirement> getResourceRequirements(String namespace)

The namespace of the requirements to return or null to return the requirements from all namespaces.

Returns the requirements of this wiring.

Only requirements considered by the resolver are returned. For example, requirements with effective directive not equal to resolve are not returned.

A wiring for a non-fragment resource has a subset of the declared requirements from the resource and all attached fragment resources. Not all declared requirements may be present since some may be discarded. For example, if a package is declared to be both exported and imported, only one is selected and the other is discarded.

A list containing a snapshot of the Requirements, or an empty list if this wiring uses no requirements in the specified namespace. For a given namespace, the list contains the requirements in the order the requirements were specified in the manifests of the resource and the attached fragment resources of this wiring. There is no ordering defined between requirements in different namespaces.

10.4 org.osgi.framework.wiring

Version 1.2

Framework Wiring Package Version 1.2.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. For example:

 Import-Package: org.osgi.framework.wiring; version="[1.2,2.0)"

10.4.1 Summary

10.4.2 public interface BundleCapability
extends Capability

A capability that has been declared from a bundle revision.

Thread-safe

Consumers of this API must not implement this type

10.4.2.1 public Map<String, Object> getAttributes()

Returns the attributes of this capability.

An unmodifiable map of attribute names to attribute values for this capability, or an empty map if this capability has no attributes.

10.4.2.2 public Map<String, String> getDirectives()

Returns the directives of this capability.

All capability directives not specified by the wiring namespaces have no specified semantics and are considered extra user defined information.

An unmodifiable map of directive names to directive values for this capability, or an empty map if this capability has no directives.

10.4.2.3 public String getNamespace()

Returns the namespace of this capability.

The namespace of this capability.

10.4.2.4 public BundleRevision getResource()

Returns the resource declaring this capability.

This method returns the same value as getRevision().

The resource declaring this capability.

1.1

10.4.2.5 public BundleRevision getRevision()

Returns the bundle revision declaring this capability.

The bundle revision declaring this capability.

10.4.3 public interface BundleRequirement
extends Requirement

A requirement that has been declared from a bundle revision.

Thread-safe

Consumers of this API must not implement this type

10.4.3.1 public Map<String, Object> getAttributes()

Returns the attributes of this requirement.

Requirement attributes have no specified semantics and are considered extra user defined information.

An unmodifiable map of attribute names to attribute values for this requirement, or an empty map if this requirement has no attributes.

10.4.3.2 public Map<String, String> getDirectives()

Returns the directives of this requirement.

All requirement directives not specified by the wiring namespaces have no specified semantics and are considered extra user defined information.

An unmodifiable map of directive names to directive values for this requirement, or an empty map if this requirement has no directives.

10.4.3.3 public String getNamespace()

Returns the namespace of this requirement.

The namespace of this requirement.

10.4.3.4 public BundleRevision getResource()

Returns the resource declaring this requirement.

This method returns the same value as getRevision().

The resource declaring this requirement. This can be null if this requirement is synthesized.

1.1

10.4.3.5 public BundleRevision getRevision()

Returns the bundle revision declaring this requirement.

The bundle revision declaring this requirement.

10.4.3.6 public boolean matches(BundleCapability capability)

The capability to match to this requirement.

Returns whether the specified capability matches this requirement.

true if the specified capability has the same namespace as this requirement and the filter for this requirement matches the attributes of the specified capability; false otherwise.

10.4.4 public interface BundleRevision
extends BundleReference, Resource

Bundle Revision. When a bundle is installed and each time a bundle is updated, a new bundle revision of the bundle is created. Since a bundle update can change the entries in a bundle, different bundle wirings for the same bundle can be associated with different bundle revisions.

For a bundle that has not been uninstalled, the most recent bundle revision is defined to be the current bundle revision. A bundle in the UNINSTALLED state does not have a current revision. The current bundle revision for a bundle can be obtained by calling bundle.adapt (BundleRevision.class). Since a bundle in the UNINSTALLED state does not have a current revision, adapting such a bundle returns null.

The framework defines namespaces for package, bundle and host capabilities and requirements. These namespaces are defined only to express wiring information by the framework. They must not be used in Provide-Capability and Require-Capability manifest headers.

Thread-safe

Consumers of this API must not implement this type

10.4.4.1 public static final String BUNDLE_NAMESPACE = "osgi.wiring.bundle"

Namespace for bundle capabilities and requirements.

The bundle symbolic name of the bundle is stored in the capability attribute of the same name as this namespace (osgi.wiring.bundle). The other directives and attributes of the bundle, from the Bundle-SymbolicName manifest header, can be found in the capability's directives and attributes. The bundle-version capability attribute must contain the Version of the bundle from the Bundle-Version manifest header if one is specified or Version.emptyVersion if not specified.

A non-fragment revision declares exactly one bundle capability (that is, the bundle can be required by another bundle). A fragment revision must not declare a bundle capability.

A bundle wiring for a non-fragment revision provides exactly one bundle capability (that is, the bundle can be required by another bundle) and requires zero or more bundle capabilities (that is, requires other bundles).

† A bundle with no bundle symbolic name (that is, a bundle with Bundle-ManifestVersion < 2) must not provide a bundle capability.

BundleNamespace

10.4.4.2 public static final String HOST_NAMESPACE = "osgi.wiring.host"

Namespace for host capabilities and requirements.

The bundle symbolic name of the bundle is stored in the capability attribute of the same name as this namespace (osgi.wiring.host). The other directives and attributes of the bundle, from the Bundle-SymbolicName manifest header, can be found in the capability's directives and attributes. The bundle-version capability attribute must contain the Version of the bundle from the Bundle-Version manifest header if one is specified or Version.emptyVersion if not specified.

A non-fragment revision declares zero or one host capability if the bundle allows fragments to be attached. A fragment revision must declare exactly one host requirement.

A bundle wiring for a non-fragment revision provides zero or one host capability if the bundle allows fragments to be attached. A bundle wiring for a fragment revision requires a host capability for each host to which it is attached.

† A bundle with no bundle symbolic name (that is, a bundle with Bundle-ManifestVersion < 2) must not provide a host capability.

HostNamespace

10.4.4.3 public static final String PACKAGE_NAMESPACE = "osgi.wiring.package"

Namespace for package capabilities and requirements.

The name of the package is stored in the capability attribute of the same name as this namespace (osgi.wiring.package). The other directives and attributes of the package, from the Export-Package manifest header, can be found in the capability's directives and attributes. The version capability attribute must contain the Version of the package if one is specified or Version.emptyVersion if not specified. The bundle-symbolic-name capability attribute must contain the symbolic name of the provider if one is specified. The bundle-version capability attribute must contain the version of the provider if one is specified or Version.emptyVersion if not specified.

The package capabilities provided by the system bundle, that is the bundle with id zero, must include the package specified by the Constants.FRAMEWORK_SYSTEMPACKAGES and Constants.FRAMEWORK_SYSTEMPACKAGES_EXTRA framework properties as well as any other package exported by the framework implementation.

A bundle revision declares zero or more package capabilities (this is, exported packages) and declares zero or more package requirements.

A bundle wiring provides zero or more resolved package capabilities (that is, exported packages) and requires zero or more resolved package requirements (that is, imported packages). The number of package wires required by a bundle wiring may change as the bundle wiring may dynamically import additional packages.

PackageNamespace

10.4.4.4 public static final int TYPE_FRAGMENT = 1

Bundle revision type indicating the bundle revision is a fragment.

getTypes()

10.4.4.5 public List<Capability> getCapabilities(String namespace)

The namespace of the declared capabilities to return or null to return the declared capabilities from all namespaces.

Returns the capabilities declared by this resource.

This method returns the same value as getDeclaredCapabilities(String).

An unmodifiable list containing the declared Capabilitys from the specified namespace. The returned list will be empty if this resource declares no capabilities in the specified namespace.

1.1

10.4.4.6 public List<BundleCapability> getDeclaredCapabilities(String namespace)

The namespace of the declared capabilities to return or null to return the declared capabilities from all namespaces.

Returns the capabilities declared by this bundle revision.

An unmodifiable list containing the declared BundleCapabilitys from the specified namespace. The returned list will be empty if this bundle revision declares no capabilities in the specified namespace. The list contains the declared capabilities in the order they are specified in the manifest.

10.4.4.7 public List<BundleRequirement> getDeclaredRequirements(String namespace)

The namespace of the declared requirements to return or null to return the declared requirements from all namespaces.

Returns the requirements declared by this bundle revision.

An unmodifiable list containing the declared BundleRequirements from the specified namespace. The returned list will be empty if this bundle revision declares no requirements in the specified namespace. The list contains the declared requirements in the order they are specified in the manifest.

10.4.4.8 public List<Requirement> getRequirements(String namespace)

The namespace of the declared requirements to return or null to return the declared requirements from all namespaces.

Returns the requirements declared by this bundle resource.

This method returns the same value as getDeclaredRequirements(String).

An unmodifiable list containing the declared Requirement s from the specified namespace. The returned list will be empty if this resource declares no requirements in the specified namespace.

1.1

10.4.4.9 public String getSymbolicName()

Returns the symbolic name for this bundle revision.

The symbolic name for this bundle revision.

Bundle.getSymbolicName()

10.4.4.10 public int getTypes()

Returns the special types of this bundle revision. The bundle revision type values are:

A bundle revision may be more than one type at a time. A type code is used to identify the bundle revision type for future extendability.

If this bundle revision is not one or more of the defined types then 0 is returned.

The special types of this bundle revision. The type values are ORed together.

10.4.4.11 public Version getVersion()

Returns the version for this bundle revision.

The version for this bundle revision, or Version.emptyVersion if this bundle revision has no version information.

Bundle.getVersion()

10.4.4.12 public BundleWiring getWiring()

Returns the bundle wiring which is using this bundle revision.

The bundle wiring which is using this bundle revision or null if no bundle wiring is using this bundle revision.

BundleWiring.getRevision()

10.4.5 public interface BundleRevisions
extends BundleReference

The bundle revisions of a bundle. When a bundle is installed and each time a bundle is updated, a new bundle revision of the bundle is created. For a bundle that has not been uninstalled, the most recent bundle revision is defined to be the current bundle revision. A bundle in the UNINSTALLED state does not have a current revision. An in use bundle revision is associated with an in use BundleWiring. The current bundle revision, if there is one, and all in use bundle revisions are returned.

The bundle revisions for a bundle can be obtained by calling bundle.adapt(BundleRevisions.class). getRevisions() on the bundle.

Thread-safe

Consumers of this API must not implement this type

10.4.5.1 public List<BundleRevision> getRevisions()

Return the bundle revisions for the referenced bundle.

The result is a list containing the current bundle revision, if there is one, and all in use bundle revisions. The list may also contain intermediate bundle revisions which are not in use.

The list is ordered in reverse chronological order such that the first item is the most recent bundle revision and last item is the oldest bundle revision.

Generally the list will have at least one bundle revision for the bundle: the current bundle revision. However, for an uninstalled bundle with no in use bundle revisions, the list may be empty.

A list containing a snapshot of the BundleRevisions for the referenced bundle.

10.4.6 public interface BundleWire
extends Wire

A wire connecting a BundleCapability to a BundleRequirement.

Thread-safe

Consumers of this API must not implement this type

10.4.6.1 public BundleCapability getCapability()

Returns the BundleCapability for this wire.

The BundleCapability for this wire.

10.4.6.2 public BundleRevision getProvider()

Returns the resource providing the capability.

The returned resource may differ from the resource referenced by the capability.

This method returns the same value as getProviderWiring(). getRevision().

The resource providing the capability.

1.1

10.4.6.3 public BundleWiring getProviderWiring()

Returns the bundle wiring providing the capability.

The bundle revision referenced by the returned bundle wiring may differ from the bundle revision referenced by the capability.

The bundle wiring providing the capability. If the bundle wiring providing the capability is not in use, null will be returned.

10.4.6.4 public BundleRequirement getRequirement()

Return the BundleRequirement for this wire.

The BundleRequirement for this wire.

10.4.6.5 public BundleRevision getRequirer()

Returns the resource who requires the capability.

The returned resource may differ from the resource referenced by the requirement.

This method returns the same value as getRequirerWiring(). getRevision().

The resource who requires the capability.

1.1

10.4.6.6 public BundleWiring getRequirerWiring()

Returns the bundle wiring who requires the capability.

The bundle revision referenced by the returned bundle wiring may differ from the bundle revision referenced by the requirement.

The bundle wiring whose requirement is wired to the capability. If the bundle wiring requiring the capability is not in use, null will be returned.

10.4.7 public interface BundleWiring
extends BundleReference, Wiring

A wiring for a bundle. Each time a bundle is resolved, a new bundle wiring for the bundle is created. A bundle wiring is associated with a bundle revision and represents the dependencies with other bundle wirings.

The bundle wiring for a bundle is the current bundle wiring if it is the most recent bundle wiring for the current bundle revision. A bundle wiring is in use if it is the current bundle wiring or if some other in use bundle wiring is dependent upon it. For example, another bundle wiring is wired to a capability provided by the bundle wiring. An in use bundle wiring for a non-fragment bundle has a class loader. All bundles with non-current, in use bundle wirings are considered removal pending. Once a bundle wiring is no longer in use, it is considered stale and is discarded by the framework.

The current bundle wiring for a bundle can be obtained by calling bundle.adapt(BundleWiring.class). A bundle in the INSTALLED or UNINSTALLED state does not have a current wiring, adapting such a bundle returns null.

Thread-safe

Consumers of this API must not implement this type

10.4.7.1 public static final int FINDENTRIES_RECURSE = 1

The find entries operation must recurse into subdirectories.

This bit may be set when calling findEntries(String, String, int) to specify the result must include the matching entries from the specified path and its subdirectories. If this bit is not set, then the result must only include matching entries from the specified path.

findEntries(String, String, int)

10.4.7.2 public static final int LISTRESOURCES_LOCAL = 2

The list resource names operation must limit the result to the names of matching resources contained in this bundle wiring's bundle revision and its attached fragment revisions. The result must not include resource names for resources in package names which are imported by this wiring.

This bit may be set when calling listResources(String, String, int) to specify the result must only include the names of matching resources contained in this bundle wiring's bundle revision and its attached fragment revisions. If this bit is not set, then the result must include the names of matching resources reachable from this bundle wiring's class loader which may include the names of matching resources contained in imported packages and required bundles.

listResources(String, String, int)

10.4.7.3 public static final int LISTRESOURCES_RECURSE = 1

The list resource names operation must recurse into subdirectories.

This bit may be set when calling listResources(String, String, int) to specify the result must include the names of matching resources from the specified path and its subdirectories. If this bit is not set, then the result must only include names of matching resources from the specified path.

listResources(String, String, int)

10.4.7.4 public List<URL> findEntries(String path, String filePattern, int options)

The path name in which to look. The path is always relative to the root of this bundle wiring and may begin with "/". A path value of "/" indicates the root of this bundle wiring.

The file name pattern for selecting entries in the specified path. The pattern is only matched against the last element of the entry path. If the entry is a directory then the trailing "/" is not used for pattern matching. Substring matching is supported, as specified in the Filter specification, using the wildcard character ("*"). If null is specified, this is equivalent to "*" and matches all files.

The options for listing resource names. See FINDENTRIES_RECURSE. The method must ignore unrecognized options.

Returns entries in this bundle wiring's bundle revision and its attached fragment revisions. This bundle wiring's class loader is not used to search for entries. Only the contents of this bundle wiring's bundle revision and its attached fragment revisions are searched for the specified entries.

This method takes into account that the "contents" of this bundle wiring can have attached fragments. This "bundle space" is not a namespace with unique members; the same entry name can be present multiple times. This method therefore returns a list of URL objects. These URLs can come from different JARs but have the same path name. This method can either return only entries in the specified path or recurse into subdirectories returning entries in the directory tree beginning at the specified path.

URLs for directory entries must have their path end with "/".

Note: Jar and zip files are not required to include directory entries. URLs to directory entries will not be returned if the bundle contents do not contain directory entries.

An unmodifiable list of URL objects for each matching entry, or an empty list if no matching entry could be found, if this bundle wiring is for a fragment revision or if the caller does not have the appropriate AdminPermission[bundle,RESOURCE] and the Java Runtime Environment supports permissions. The list is ordered such that entries from the bundle revision are returned first followed by the entries from attached fragment revisions in attachment order. If this bundle wiring is not in use, null must be returned.

Bundle.findEntries(String, String, boolean)

10.4.7.5 public List<BundleCapability> getCapabilities(String namespace)

The namespace of the capabilities to return or null to return the capabilities from all namespaces.

Returns the capabilities provided by this bundle wiring.

Only capabilities considered by the resolver are returned. For example, capabilities with effective directive not equal to resolve are not returned.

A capability may not be required by any bundle wiring and thus there may be no wires for the capability.

A bundle wiring for a non-fragment revision provides a subset of the declared capabilities from the bundle revision and all attached fragment revisions. Not all declared capabilities may be provided since some may be discarded. For example, if a package is declared to be both exported and imported, only one is selected and the other is discarded.

A bundle wiring for a fragment revision with a symbolic name must provide exactly one identity capability.

† The identity capability provided by attached fragment revisions must not be included in the capabilities of the host bundle wiring.

A list containing a snapshot of the BundleCapabilitys, or an empty list if this bundle wiring provides no capabilities in the specified namespace. If this bundle wiring is not in use, null will be returned. For a given namespace, the list contains the capabilities in the order the capabilities were specified in the manifests of the bundle revision and the attached fragments of this bundle wiring. There is no ordering defined between capabilities in different namespaces.

10.4.7.6 public ClassLoader getClassLoader()

Returns the class loader for this bundle wiring. Since a bundle refresh creates a new bundle wiring for a bundle, different bundle wirings for the same bundle will have different class loaders.

The class loader for this bundle wiring. If this bundle wiring is not in use or this bundle wiring is for a fragment revision, null will be returned.

SecurityException– If the caller does not have the appropriate RuntimePermission("getClassLoader"), and the Java Runtime Environment supports permissions.

10.4.7.7 public List<Wire> getProvidedResourceWires(String namespace)

The namespace of the capabilities for which to return wires or null to return the wires for the capabilities in all namespaces.

Returns the Wires to the provided capabilities of this wiring.

This method returns the same value as getProvidedWires(String).

A list containing a snapshot of the Wires for the capabilities of this wiring, or an empty list if this wiring has no capabilities in the specified namespace. For a given namespace, the list contains the wires in the order the capabilities were specified in the manifests of the resource and the attached fragment resources of this wiring. There is no ordering defined between capabilities in different namespaces.

1.1

10.4.7.8 public List<BundleWire> getProvidedWires(String namespace)

The namespace of the capabilities for which to return wires or null to return the wires for the capabilities in all namespaces.

Returns the BundleWires to the provided capabilities of this bundle wiring.

A list containing a snapshot of the BundleWires for the capabilities of this bundle wiring, or an empty list if this bundle wiring has no capabilities in the specified namespace. If this bundle wiring is not in use, null will be returned. For a given namespace, the list contains the wires in the order the capabilities were specified in the manifests of the bundle revision and the attached fragments of this bundle wiring. There is no ordering defined between capabilities in different namespaces.

10.4.7.9 public List<Wire> getRequiredResourceWires(String namespace)

The namespace of the requirements for which to return wires or null to return the wires for the requirements in all namespaces.

Returns the Wires to the requirements in use by this wiring.

This method returns the same value as getRequiredWires(String).

A list containing a snapshot of the Wires for the requirements of this wiring, or an empty list if this wiring has no requirements in the specified namespace. For a given namespace, the list contains the wires in the order the requirements were specified in the manifests of the resource and the attached fragment resources of this wiring. There is no ordering defined between requirements in different namespaces.

1.1

10.4.7.10 public List<BundleWire> getRequiredWires(String namespace)

The namespace of the requirements for which to return wires or null to return the wires for the requirements in all namespaces.

Returns the BundleWires to the requirements in use by this bundle wiring.

This method may return different results if this bundle wiring establishes additional wires to more requirements. For example, dynamically importing a package will establish a new wire to the dynamically imported package.

A list containing a snapshot of the BundleWires for the requirements of this bundle wiring, or an empty list if this bundle wiring has no requirements in the specified namespace. If this bundle wiring is not in use, null will be returned. For a given namespace, the list contains the wires in the order the requirements were specified in the manifests of the bundle revision and the attached fragments of this bundle wiring followed by dynamically established wires, if any, in the order they were established. There is no ordering defined between requirements in different namespaces.

10.4.7.11 public List<BundleRequirement> getRequirements(String namespace)

The namespace of the requirements to return or null to return the requirements from all namespaces.

Returns the requirements of this bundle wiring.

Only requirements considered by the resolver are returned. For example, requirements with effective directive not equal to resolve are not returned.

A bundle wiring for a non-fragment revision has a subset of the declared requirements from the bundle revision and all attached fragment revisions. Not all declared requirements may be present since some may be discarded. For example, if a package is declared to be both exported and imported, only one is selected and the other is discarded.

A list containing a snapshot of the BundleRequirements, or an empty list if this bundle wiring uses no requirements in the specified namespace. If this bundle wiring is not in use, null will be returned. For a given namespace, the list contains the requirements in the order the requirements were specified in the manifests of the bundle revision and the attached fragments of this bundle wiring. There is no ordering defined between requirements in different namespaces.

10.4.7.12 public BundleRevision getResource()

Returns the resource associated with this wiring.

This method returns the same value as getRevision().

The resource associated with this wiring.

1.1

10.4.7.13 public List<Capability> getResourceCapabilities(String namespace)

The namespace of the capabilities to return or null to return the capabilities from all namespaces.

Returns the capabilities provided by this wiring.

Only capabilities considered by the resolver are returned. For example, capabilities with effective directive not equal to resolve are not returned.

A capability may not be required by any wiring and thus there may be no wires for the capability.

A wiring for a non-fragment resource provides a subset of the declared capabilities from the resource and all attached fragment resources. Not all declared capabilities may be provided since some may be discarded. For example, if a package is declared to be both exported and imported, only one is selected and the other is discarded.

A wiring for a fragment resource with a symbolic name must provide exactly one osgi.identity capability.

† The osgi.identity capability provided by attached fragment resource must not be included in the capabilities of the host wiring.

This method returns the same value as getCapabilities(String).

A list containing a snapshot of the Capabilitys, or an empty list if this wiring provides no capabilities in the specified namespace. For a given namespace, the list contains the capabilities in the order the capabilities were specified in the manifests of the resource and the attached fragment resources of this wiring. There is no ordering defined between capabilities in different namespaces.

1.1

10.4.7.14 public List<Requirement> getResourceRequirements(String namespace)

The namespace of the requirements to return or null to return the requirements from all namespaces.

Returns the requirements of this wiring.

Only requirements considered by the resolver are returned. For example, requirements with effective directive not equal to resolve are not returned.

A wiring for a non-fragment resource has a subset of the declared requirements from the resource and all attached fragment resources. Not all declared requirements may be present since some may be discarded. For example, if a package is declared to be optionally imported and is not actually imported, the requirement must be discarded.

This method returns the same value as getRequirements(String).

A list containing a snapshot of the Requirements, or an empty list if this wiring uses no requirements in the specified namespace. For a given namespace, the list contains the requirements in the order the requirements were specified in the manifests of the resource and the attached fragment resources of this wiring. There is no ordering defined between requirements in different namespaces.

1.1

10.4.7.15 public BundleRevision getRevision()

Returns the bundle revision for the bundle in this bundle wiring. Since a bundle update can change the entries in a bundle, different bundle wirings for the same bundle can have different bundle revisions.

The bundle object referenced by the returned BundleRevision may return different information than the returned BundleRevision since the returned BundleRevision may refer to an older revision of the bundle.

The bundle revision for this bundle wiring.

BundleRevision.getWiring()

10.4.7.16 public boolean isCurrent()

Returns true if this bundle wiring is the current bundle wiring. The bundle wiring for a bundle is the current bundle wiring if it is the most recent bundle wiring for the current bundle revision. All bundles with non-current, in use bundle wirings are considered removal pending.

true if this bundle wiring is the current bundle wiring; false otherwise.

10.4.7.17 public boolean isInUse()

Returns true if this bundle wiring is in use. A bundle wiring is in use if it is the current wiring or if some other in use bundle wiring is dependent upon it. Once a bundle wiring is no longer in use, it is considered stale and is discarded by the framework.

true if this bundle wiring is in use; false otherwise.

10.4.7.18 public Collection<String> listResources(String path, String filePattern, int options)

The path name in which to look. The path is always relative to the root of this bundle wiring's class loader and may begin with "/". A path value of "/" indicates the root of this bundle wiring's class loader.

The file name pattern for selecting resource names in the specified path. The pattern is only matched against the last element of the resource path. If the resource is a directory then the trailing "/" is not used for pattern matching. Substring matching is supported, as specified in the Filter specification, using the wildcard character ("*"). If null is specified, this is equivalent to "*" and matches all files.

The options for listing resource names. See LISTRESOURCES_LOCAL and LISTRESOURCES_RECURSE. This method must ignore unrecognized options.

Returns the names of resources visible to this bundle wiring's class loader. The returned names can be used to access the resources via this bundle wiring's class loader.

  • Only the resource names for resources in bundle wirings will be returned. The names of resources visible to a bundle wiring's parent class loader, such as the bootstrap class loader, must not be included in the result.

  • Only established wires will be examined for resources. This method must not cause new wires for dynamic imports to be established.

An unmodifiable collection of resource names for each matching resource, or an empty collection if no matching resource could be found, if this bundle wiring is for a fragment revision or if the caller does not have the appropriate AdminPermission[bundle,RESOURCE] and the Java Runtime Environment supports permissions. The collection is unordered and must contain no duplicate resource names. If this bundle wiring is not in use, null must be returned.

10.4.8 public interface FrameworkWiring
extends BundleReference

Query and modify wiring information for the framework. The framework wiring object for the framework can be obtained by calling bundle.adapt(FrameworkWiring.class) on the system bundle. Only the system bundle can be adapted to a FrameworkWiring object.

The system bundle associated with this FrameworkWiring object can be obtained by calling BundleReference.getBundle().

Thread-safe

Consumers of this API must not implement this type

10.4.8.1 public Collection<BundleCapability> findProviders(Requirement requirement)

The requirement to find matching bundle capabilities. Must not be null.

Find bundle capabilities that match the given requirement.

The returned collection contains BundleCapability objects where the revision must be the declaring revision of the capability and the revision must either be the current bundle revision or an in use bundle revision.

Each returned capability must match the given requirement. This means that the filter in the requirement must match as well as any namespace specific directives. For example, the mandatory attributes for the osgi.wiring.package namespace.

The returned collection has not been filtered to remove capabilities that are non-effective, substituted or for which the providing bundle does not have permission to provide. No resolve hooks are called to filter matching capabilities.

A collection of BundleCapability objects that match the specified requirement.

1.2

10.4.8.2 public Collection<Bundle> getDependencyClosure(Collection<Bundle> bundles)

The initial bundles for which to generate the dependency closure.

Returns the dependency closure for the specified bundles.

A graph of bundles is computed starting with the specified bundles. The graph is expanded by adding any bundle that is either wired to a package that is currently exported by a bundle in the graph or requires a bundle in the graph. The graph is fully constructed when there is no bundle outside the graph that is wired to a bundle in the graph. The graph may contain UNINSTALLED bundles that are removal pending.

A collection containing a snapshot of the dependency closure of the specified bundles, or an empty collection if there were no specified bundles.

IllegalArgumentException– If the specified Bundles were not created by the same framework instance associated with this FrameworkWiring.

10.4.8.3 public Collection<Bundle> getRemovalPendingBundles()

Returns the bundles that have non-current, in use bundle wirings. This is typically the bundles which have been updated or uninstalled since the last call to refreshBundles(Collection, FrameworkListener...).

A collection containing a snapshot of the Bundles which have non-current, in use BundleWirings, or an empty collection if there are no such bundles.

10.4.8.4 public void refreshBundles(Collection<Bundle> bundles, FrameworkListener... listeners)

The bundles to be refreshed, or null to refresh the removal pending bundles.

Zero or more listeners to be notified when the bundle refresh has been completed. The specified listeners do not need to be otherwise registered with the framework. If a specified listener is already registered with the framework, it will be notified twice.

Refreshes the specified bundles. This forces the update (replacement) or removal of packages exported by the specified bundles.

The technique by which the framework refreshes bundles may vary among different framework implementations. A permissible implementation is to stop and restart the framework.

This method returns to the caller immediately and then performs the following steps on a separate thread:

  1. Compute the dependency closure of the specified bundles. If no bundles are specified, compute the dependency closure of the removal pending bundles.

  2. Each bundle in the dependency closure that is in the ACTIVE state will be stopped as described in the Bundle.stop method.

  3. Each bundle in the dependency closure that is in the RESOLVED state is unresolved and thus moved to the INSTALLED state. The effect of this step is that bundles in the dependency closure are no longer RESOLVED.

  4. Each bundle in the dependency closure that is in the UNINSTALLED state is removed from the dependency closure and is now completely removed from the Framework.

  5. Each bundle in the dependency closure that was in the ACTIVE state prior to Step 2 is started as described in the Bundle.start method, causing all bundles required for the restart to be resolved. It is possible that, as a result of the previous steps, packages that were previously exported no longer are. Therefore, some bundles may be unresolvable until bundles satisfying the dependencies have been installed in the Framework.

For any exceptions that are thrown during any of these steps, a framework event of type FrameworkEvent.ERROR is fired containing the exception. The source bundle for these events should be the specific bundle to which the exception is related. If no specific bundle can be associated with the exception then the System Bundle must be used as the source bundle for the event. All framework events fired by this method are also delivered to the specified FrameworkListeners in the order they are specified.

When this process completes after the bundles are refreshed, the Framework will fire a Framework event of type FrameworkEvent.PACKAGES_REFRESHED to announce it has completed the bundle refresh. The specified FrameworkListeners are notified in the order specified. Each specified FrameworkListener will be called with a Framework event of type FrameworkEvent.PACKAGES_REFRESHED.

IllegalArgumentException– If the specified Bundles were not created by the same framework instance associated with this FrameworkWiring.

SecurityException– If the caller does not have AdminPermission[System Bundle,RESOLVE] and the Java runtime environment supports permissions.

10.4.8.5 public boolean resolveBundles(Collection<Bundle> bundles)

The bundles to resolve or null to resolve all unresolved bundles installed in the Framework.

Resolves the specified bundles. The Framework must attempt to resolve the specified bundles that are unresolved. Additional bundles that are not included in the specified bundles may be resolved as a result of calling this method. A permissible implementation of this method is to attempt to resolve all unresolved bundles installed in the framework.

If no bundles are specified, then the Framework will attempt to resolve all unresolved bundles. This method must not cause any bundle to be refreshed, stopped, or started. This method will not return until the operation has completed.

true if all specified bundles are resolved; false otherwise.

IllegalArgumentException– If the specified Bundles were not created by the same framework instance associated with this FrameworkWiring.

SecurityException– If the caller does not have AdminPermission[System Bundle,RESOLVE] and the Java runtime environment supports permissions.

10.5 org.osgi.framework.startlevel

Version 1.0

Framework Start Level Package Version 1.0.

The Framework Start Level package allows management agents to manage a start level assigned to each bundle and the active start level of the Framework. This package is a replacement for the now deprecated org.osgi.service.startlevel package.

A start level is defined to be a state of execution in which the Framework exists. Start level values are defined as unsigned integers with 0 (zero) being the state where the Framework is not launched. Progressively higher integral values represent progressively higher start levels. For example, 2 is a higher start level than 1.

AdminPermission is required to modify start level information.

Start Level support in the Framework includes the ability to modify the active start level of the Framework and to assign a specific start level to a bundle. The beginning start level of a Framework is specified via the org.osgi.framework.Constants.FRAMEWORK_BEGINNING_STARTLEVEL framework property when configuring a framework.

When the Framework is first started it must be at start level zero. In this state, no bundles are running. This is the initial state of the Framework before it is launched. When the Framework is launched, the Framework will enter start level one and all bundles which are assigned to start level one and whose autostart setting indicates the bundle should be started are started as described in the org.osgi.framework.Bundle.start(int) method. The Framework will continue to increase the start level, starting bundles at each start level, until the Framework has reached a beginning start level. At this point the Framework has completed starting bundles and will then fire a Framework event of type org.osgi.framework.FrameworkEvent.STARTED to announce it has completed its launch.

Within a start level, bundles may be started in an order defined by the Framework implementation. This may be something like ascending org.osgi.framework.Bundle.getBundleId() order or an order based upon dependencies between bundles. A similar but reversed order may be used when stopping bundles within a start level.

The Framework Start Level package can be used by management bundles to alter the active start level of the framework.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest. For example:

 Import-Package: org.osgi.framework.startlevel; version="[1.0,2.0)"

10.5.1 Summary

10.5.2 public interface BundleStartLevel
extends BundleReference

Query and modify the start level information for a bundle. The start level object for a bundle can be obtained by calling bundle.adapt(BundleStartLevel.class) on the bundle.

The bundle associated with this BundleStartLevel object can be obtained by calling BundleReference.getBundle().

Thread-safe

Consumers of this API must not implement this type

10.5.2.1 public int getStartLevel()

Return the assigned start level value for the bundle.

The start level value of the bundle.

IllegalStateException– If the bundle has been uninstalled.

setStartLevel(int)

10.5.2.2 public boolean isActivationPolicyUsed()

Returns whether the bundle's autostart setting indicates that the activation policy declared in the bundle manifest must be used.

The autostart setting of a bundle indicates whether the bundle's declared activation policy is to be used when the bundle is started.

true if the bundle's autostart setting indicates the activation policy declared in the manifest must be used. false if the bundle must be eagerly activated.

IllegalStateException– If the bundle has been uninstalled.

Bundle.START_ACTIVATION_POLICY

10.5.2.3 public boolean isPersistentlyStarted()

Returns whether the bundle's autostart setting indicates it must be started.

The autostart setting of a bundle indicates whether the bundle is to be started when its start level is reached.

true if the autostart setting of the bundle indicates it is to be started. false otherwise.

IllegalStateException– If this bundle has been uninstalled.

Bundle.START_TRANSIENT

10.5.2.4 public void setStartLevel(int startlevel)

The new start level for the bundle.

Assign a start level value to the bundle.

The bundle will be assigned the specified start level. The start level value assigned to the bundle will be persistently recorded by the Framework.

If the new start level for the bundle is lower than or equal to the active start level of the Framework and the bundle's autostart setting indicates this bundle must be started, the Framework will start the bundle as described in the Bundle.start(int) method using the Bundle.START_TRANSIENT option. The Bundle.START_ACTIVATION_POLICY option must also be used if isActivationPolicyUsed() returns true. The actual starting of the bundle must occur asynchronously.

If the new start level for the bundle is higher than the active start level of the Framework, the Framework will stop the bundle as described in the Bundle.stop(int) method using the Bundle.STOP_TRANSIENT option. The actual stopping of the bundle must occur asynchronously.

IllegalArgumentException– If the specified start level is less than or equal to zero, or if the bundle is the system bundle.

IllegalStateException– If the bundle has been uninstalled.

SecurityException– If the caller does not have AdminPermission[bundle,EXECUTE] and the Java runtime environment supports permissions.

10.5.3 public interface FrameworkStartLevel
extends BundleReference

Query and modify the start level information for the framework. The start level object for the framework can be obtained by calling bundle.adapt(FrameworkStartLevel.class) on the system bundle. Only the system bundle can be adapted to a FrameworkStartLevel object.

The system bundle associated with this FrameworkStartLevel object can be obtained by calling BundleReference.getBundle().

Thread-safe

Consumers of this API must not implement this type

10.5.3.1 public int getInitialBundleStartLevel()

Return the initial start level value that is assigned to a Bundle when it is first installed.

The initial start level value for Bundles.

setInitialBundleStartLevel(int)

10.5.3.2 public int getStartLevel()

Return the active start level value of the Framework. If the Framework is in the process of changing the start level this method must return the active start level if this differs from the requested start level.

The active start level value of the Framework.

10.5.3.3 public void setInitialBundleStartLevel(int startlevel)

The initial start level for newly installed bundles.

Set the initial start level value that is assigned to a Bundle when it is first installed.

The initial bundle start level will be set to the specified start level. The initial bundle start level value will be persistently recorded by the Framework.

When a Bundle is installed via BundleContext.installBundle, it is assigned the initial bundle start level value.

The default initial bundle start level value is 1 unless this method has been called to assign a different initial bundle start level value.

This method does not change the start level values of installed bundles.

IllegalArgumentException– If the specified start level is less than or equal to zero.

SecurityException– If the caller does not have AdminPermission[System Bundle,STARTLEVEL] and the Java runtime environment supports permissions.

10.5.3.4 public void setStartLevel(int startlevel, FrameworkListener... listeners)

The requested start level for the Framework.

Zero or more listeners to be notified when the start level change has been completed. The specified listeners do not need to be otherwise registered with the framework. If a specified listener is already registered with the framework, it will be notified twice.

Modify the active start level of the Framework and notify when complete.

The Framework will move to the requested start level. This method will return immediately to the caller and the start level change will occur asynchronously on another thread. The specified FrameworkListener s are notified, in the order specified, when the start level change is complete. When the start level change completes normally, each specified FrameworkListener will be called with a Framework event of type FrameworkEvent.STARTLEVEL_CHANGED. If the start level change does not complete normally, each specified FrameworkListener will be called with a Framework event of type FrameworkEvent.ERROR.

If the specified start level is higher than the active start level, the Framework will continue to increase the start level until the Framework has reached the specified start level. At each intermediate start level value on the way to and including the target start level, the Framework must:

  1. Change the active start level to the intermediate start level value.

  2. Start bundles at the intermediate start level whose autostart setting indicate they must be started. They are started as described in the Bundle.start(int) method using the Bundle.START_TRANSIENT option. The Bundle.START_ACTIVATION_POLICY option must also be used if BundleStartLevel.isActivationPolicyUsed() returns true for the bundle.

When this process completes after the specified start level is reached, the Framework will fire a Framework event of type FrameworkEvent.STARTLEVEL_CHANGED to announce it has moved to the specified start level.

If the specified start level is lower than the active start level, the Framework will continue to decrease the start level until the Framework has reached the specified start level. At each intermediate start level value on the way to and including the specified start level, the framework must:

  1. Stop bundles at the intermediate start level as described in the Bundle.stop(int) method using the Bundle.STOP_TRANSIENT option.

  2. Change the active start level to the intermediate start level value.

When this process completes after the specified start level is reached, the Framework will fire a Framework event of type FrameworkEvent.STARTLEVEL_CHANGED to announce it has moved to the specified start level.

If the specified start level is equal to the active start level, then no bundles are started or stopped, however, the Framework must fire a Framework event of type FrameworkEvent.STARTLEVEL_CHANGED to announce it has finished moving to the specified start level. This event may arrive before this method returns.

IllegalArgumentException– If the specified start level is less than or equal to zero.

SecurityException– If the caller does not have AdminPermission[System Bundle,STARTLEVEL] and the Java runtime environment supports permissions.

10.6 org.osgi.framework.namespace

Version 1.2

Namespace Package Version 1.2.

Bundles should not need to import this package at runtime since all the types in this package just contain constants for capability and requirement namespaces specified by the OSGi Working Group.

10.6.1 Summary

10.6.2 public abstract class AbstractWiringNamespace
extends Namespace

Wiring Capability and Requirement Namespaces base class.

This class is the common class shared by all OSGi defined wiring namespaces. It defines the names for the common attributes and directives for the OSGi specified wiring namespaces.

The values associated with these keys are of type String, unless otherwise indicated.

Immutable

Consumers of this API must not implement this type

10.6.2.1 public static final String CAPABILITY_BUNDLE_VERSION_ATTRIBUTE = "bundle-version"

The capability attribute contains the Version of the resource providing the capability if one is specified or 0.0.0 if not specified. The value of this attribute must be of type Version.

10.6.2.2 public static final String CAPABILITY_MANDATORY_DIRECTIVE = "mandatory"

The capability directive used to specify the comma separated list of mandatory attributes which must be specified in the filter of a requirement in order for the capability to match the requirement.

10.6.3 public final class BundleNamespace
extends AbstractWiringNamespace

Bundle Capability and Requirement Namespace.

This class defines the names for the attributes and directives for this namespace. All unspecified capability attributes are of type String and are used as arbitrary matching attributes for the capability. The values associated with the specified directive and attribute keys are of type String, unless otherwise indicated.

Unless otherwise noted, all directives specified on the Bundle-SymbolicName header are visible in the capability and all directives specified on the Require-Bundle header are visible in the requirement.

  • The uses directive must be ignored. A uses directive specified on the Bundle-SymbolicName header must be ignored. A uses directive must not be present in the capability.

  • The effective directives must be ignored. This namespace is only effective at resolve time. An effective directive specified on the Bundle-SymbolicName or Require-Bundle headers must be ignored. An effective directive must not be present in a capability or requirement.

  • The cardinality directive must be ignored. A cardinality directive specified on the Require-Bundle header must be ignored. A cardinality directive must not be present in a requirement.

A non-fragment resource with the osgi.bundle type identity provides exactly one bundle capability (that is, the bundle can be required by another bundle). A fragment resource with the osgi.fragment type identity must not declare a bundle capability. A resource requires zero or more bundle requirements (that is, required bundles).

† A resource with no symbolic name must not provide a bundle capability.

Immutable

10.6.3.1 public static final String BUNDLE_NAMESPACE = "osgi.wiring.bundle"

Namespace name for bundle capabilities and requirements.

Also, the capability attribute used to specify the symbolic name of the bundle.

10.6.3.2 public static final String CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE = "fragment-attachment"

The capability directive identifying if and when a fragment may attach to a host bundle.

This directive should be examined using the host namespace.

HostNamespace.CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE

10.6.3.3 public static final String CAPABILITY_SINGLETON_DIRECTIVE = "singleton"

The capability directive identifying if the resource is a singleton. A String value of "true" indicates the resource is a singleton; any other value or null indicates the resource is not a singleton.

This directive should be examined using the identity namespace.

IdentityNamespace.CAPABILITY_SINGLETON_DIRECTIVE

10.6.3.4 public static final String REQUIREMENT_EXTENSION_DIRECTIVE = "extension"

The requirement directive used to specify the type of the extension fragment.

This directive should be examined using the host namespace.

HostNamespace.REQUIREMENT_EXTENSION_DIRECTIVE

10.6.3.5 public static final String REQUIREMENT_VISIBILITY_DIRECTIVE = "visibility"

The requirement directive used to specify the visibility type for a requirement. The default value is private.

private, reexport

10.6.3.6 public static final String VISIBILITY_PRIVATE = "private"

The directive value identifying a private visibility type. A private visibility type indicates that any packages that are exported by the required bundle are not made visible on the export signature of the requiring bundle. .

REQUIREMENT_VISIBILITY_DIRECTIVE

10.6.3.7 public static final String VISIBILITY_REEXPORT = "reexport"

The directive value identifying a reexport visibility type. A reexport visibility type indicates any packages that are exported by the required bundle are re-exported by the requiring bundle.

REQUIREMENT_VISIBILITY_DIRECTIVE

10.6.4 public final class ExecutionEnvironmentNamespace
extends Namespace

Execution Environment Capability and Requirement Namespace.

This class defines the names for the attributes and directives for this namespace. All unspecified capability attributes are of type String and are used as arbitrary matching attributes for the capability. The values associated with the specified directive and attribute keys are of type String, unless otherwise indicated.

Immutable

10.6.4.1 public static final String CAPABILITY_VERSION_ATTRIBUTE = "version"

The capability attribute contains the versions of the execution environment. The value of this attribute must be of type List<Version>.

10.6.4.2 public static final String EXECUTION_ENVIRONMENT_NAMESPACE = "osgi.ee"

Namespace name for execution environment capabilities and requirements.

Also, the capability attribute used to specify the name of the execution environment.

10.6.5 public final class HostNamespace
extends AbstractWiringNamespace

Host Capability and Requirement Namespace.

This class defines the names for the attributes and directives for this namespace. All unspecified capability attributes are of type String and are used as arbitrary matching attributes for the capability. The values associated with the specified directive and attribute keys are of type String, unless otherwise indicated.

Unless otherwise noted, all directives specified on the Bundle-SymbolicName header are visible in the capability and all directives specified on the Fragment-Host header are visible in the requirement.

  • The uses directive must be ignored. A uses directive specified on the Bundle-SymbolicName header must be ignored. A uses directive must not be present in the capability.

  • The effective directives must be ignored. This namespace is only effective at resolve time. An effective directive specified on the Bundle-SymbolicName or Fragment-Host headers must be ignored. An effective directive must not be present in a capability or requirement.

  • The cardinality directive has limited applicability to this namespace. A cardinality directive specified on the Fragment-Host header must be ignored. All requirements must have the cardinality directive set to multiple.

A non-fragment resource with the osgi.bundle type identity provides zero or one host capabilities. A fragment resource with the osgi.fragment type identity must not declare a host capability and must declare exactly one host requirement.

† A resource with no bundle symbolic name must not provide a host capability.

Immutable

10.6.5.1 public static final String CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE = "fragment-attachment"

The capability directive identifying if and when a fragment may attach to a host bundle. The default value is always.

FRAGMENT_ATTACHMENT_ALWAYS, FRAGMENT_ATTACHMENT_RESOLVETIME, FRAGMENT_ATTACHMENT_NEVER

10.6.5.2 public static final String CAPABILITY_SINGLETON_DIRECTIVE = "singleton"

The capability directive identifying if the resource is a singleton. A String value of "true" indicates the resource is a singleton; any other value or null indicates the resource is not a singleton.

This directive should be examined using the identity namespace.

IdentityNamespace.CAPABILITY_SINGLETON_DIRECTIVE

10.6.5.3 public static final String EXTENSION_BOOTCLASSPATH = "bootclasspath"

The directive value indicating that the extension fragment is to be loaded by the boot class loader.

REQUIREMENT_EXTENSION_DIRECTIVE

As of 1.2.

10.6.5.4 public static final String EXTENSION_FRAMEWORK = "framework"

The directive value indicating that the extension fragment is to be loaded by the framework's class loader.

REQUIREMENT_EXTENSION_DIRECTIVE

10.6.5.5 public static final String FRAGMENT_ATTACHMENT_ALWAYS = "always"

The directive value indicating that fragments are allowed to attach to the host bundle at any time (while the host is resolved or during the process of resolving the host bundle).

CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE

10.6.5.6 public static final String FRAGMENT_ATTACHMENT_NEVER = "never"

The directive value indicating that no fragments are allowed to attach to the host bundle at any time.

CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE

10.6.5.7 public static final String FRAGMENT_ATTACHMENT_RESOLVETIME = "resolve-time"

The directive value indicating that fragments are allowed to attach to the host bundle only during the process of resolving the host bundle.

CAPABILITY_FRAGMENT_ATTACHMENT_DIRECTIVE

10.6.5.8 public static final String HOST_NAMESPACE = "osgi.wiring.host"

Namespace name for host capabilities and requirements.

Also, the capability attribute used to specify the symbolic name of the host.

10.6.5.9 public static final String REQUIREMENT_EXTENSION_DIRECTIVE = "extension"

The requirement directive used to specify the type of the extension fragment. The default value is framework.

EXTENSION_FRAMEWORK

10.6.5.10 public static final String REQUIREMENT_VISIBILITY_DIRECTIVE = "visibility"

The requirement directive used to specify the visibility type for a requirement.

This directive should be examined using the bundle namespace.

BundleNamespace.REQUIREMENT_VISIBILITY_DIRECTIVE

10.6.6 public final class IdentityNamespace
extends Namespace

Identity Capability and Requirement Namespace.

This class defines the names for the attributes and directives for this namespace. All unspecified capability attributes are of type String and are used as arbitrary matching attributes for the capability. The values associated with the specified directive and attribute keys are of type String, unless otherwise indicated.

Each resource provides exactly one identity capability that can be used to identify the resource.

The bundle wiring for the bundle revision provides exactly one identity capability.

† A resource with no symbolic name must not provide an identity capability.

Immutable

10.6.6.1 public static final String CAPABILITY_COPYRIGHT_ATTRIBUTE = "copyright"

The capability attribute that contains a human readable copyright notice for the resource. See the Bundle-Copyright manifest header.

10.6.6.2 public static final String CAPABILITY_DESCRIPTION_ATTRIBUTE = "description"

The capability attribute that contains a human readable description for the resource. See the Bundle-Description manifest header.

10.6.6.3 public static final String CAPABILITY_DOCUMENTATION_ATTRIBUTE = "documentation"

The capability attribute that contains the URL to documentation for the resource. See the Bundle-DocURL manifest header.

10.6.6.4 public static final String CAPABILITY_LICENSE_ATTRIBUTE = "license"

The capability attribute that contains the URL to the license for the resource. See the name portion of the Bundle-License manifest header.

10.6.6.5 public static final String CAPABILITY_SINGLETON_DIRECTIVE = "singleton"

The capability directive identifying if the resource is a singleton. A String value of "true" indicates the resource is a singleton; any other value or null indicates the resource is not a singleton.

10.6.6.6 public static final String CAPABILITY_TAGS_ATTRIBUTE = "tags"

The attribute value that contains tags for the resource. A tag is used to identify an aspect of the resource that is not otherwise expressed by the capabilities of the resource. The value of this attribute must be of type List<String>.

1.2

10.6.6.7 public static final String CAPABILITY_TYPE_ATTRIBUTE = "type"

The capability attribute identifying the resource type. If the resource has no type then the value unknown must be used for the attribute.

TYPE_BUNDLE, TYPE_FRAGMENT, TYPE_UNKNOWN

10.6.6.8 public static final String CAPABILITY_VERSION_ATTRIBUTE = "version"

The capability attribute identifying the Version of the resource if one is specified or 0.0.0 if not specified. The value of this attribute must be of type Version.

10.6.6.9 public static final String CLASSIFIER_JAVADOC = "javadoc"

The attribute value identifying the resource classifier as an archive containing the javadoc in the same directory layout as the resource.

REQUIREMENT_CLASSIFIER_DIRECTIVE

10.6.6.10 public static final String CLASSIFIER_SOURCES = "sources"

The attribute value identifying the resource classifier as an archive containing the source code in the same directory layout as the resource.

REQUIREMENT_CLASSIFIER_DIRECTIVE

10.6.6.11 public static final String IDENTITY_NAMESPACE = "osgi.identity"

Namespace name for identity capabilities and requirements.

Also, the capability attribute used to specify the symbolic name of the resource.

10.6.6.12 public static final String REQUIREMENT_CLASSIFIER_DIRECTIVE = "classifier"

The requirement directive that classifies the relationship with another resource.

CLASSIFIER_SOURCES, CLASSIFIER_JAVADOC

10.6.6.13 public static final String TYPE_BUNDLE = "osgi.bundle"

The attribute value identifying the resource type as an OSGi bundle.

CAPABILITY_TYPE_ATTRIBUTE

10.6.6.14 public static final String TYPE_FRAGMENT = "osgi.fragment"

The attribute value identifying the resource type as an OSGi fragment.

CAPABILITY_TYPE_ATTRIBUTE

10.6.6.15 public static final String TYPE_UNKNOWN = "unknown"

The attribute value identifying the resource type as unknown.

CAPABILITY_TYPE_ATTRIBUTE

10.6.7 public final class NativeNamespace
extends Namespace

Native Capability and Requirement Namespace.

This class defines the names for the attributes and directives for this namespace. All unspecified capability attributes are of type String and are used as arbitrary matching attributes for the capability. The values associated with the specified directive and attribute keys are of type String, unless otherwise indicated.

1.1

Immutable

10.6.7.1 public static final String CAPABILITY_LANGUAGE_ATTRIBUTE = "osgi.native.language"

The capability attribute contains the org.osgi.framework.language launching property value. The value of this attribute must be of type String.

10.6.7.2 public static final String CAPABILITY_OSNAME_ATTRIBUTE = "osgi.native.osname"

The capability attribute contains alias values of the org.osgi.framework.os.name launching property value according to the OSGi Specification References. The value of this attribute must be of type List<String>.

10.6.7.3 public static final String CAPABILITY_OSVERSION_ATTRIBUTE = "osgi.native.osversion"

The capability attribute contains a Version parsed from the org.osgi.framework.os.version launching property value. The value of this attribute must be of type Version.

10.6.7.4 public static final String CAPABILITY_PROCESSOR_ATTRIBUTE = "osgi.native.processor"

The capability attribute contains alias values of the org.osgi.framework.processor launching property value according to the OSGi Specification References. The value of this attribute must be of type List<String>.

10.6.7.5 public static final String NATIVE_NAMESPACE = "osgi.native"

Namespace name for native capabilities and requirements.

10.6.8 public final class PackageNamespace
extends AbstractWiringNamespace

Package Capability and Requirement Namespace.

A resource provides zero or more package capabilities (this is, exported packages) and requires zero or more package requirements (that is, imported packages).

This class defines the names for the attributes and directives for this namespace. All unspecified capability attributes are of type String and are used as arbitrary matching attributes for the capability. The values associated with the specified directive and attribute keys are of type String, unless otherwise indicated.

Unless otherwise noted, all directives specified on the Export-Package header are visible in the capability and all directives specified on the Import-Package and DynamicImport-Package headers are visible in the requirement.

  • The effective directives must be ignored. This namespace is only effective at resolve time. An effective directive specified on the Export-Package, Import-Package or DynamicImport-Package headers must be ignored. An effective directive must not be present in a capability or requirement.

  • The cardinality directive has limited applicability to this namespace. A cardinality directive specified on the Import-Package or DynamicImport-Package headers must be ignored. Only requirements with resolution set to dynamic and the package name contains a wildcard must have the cardinality directive set to multiple. Otherwise, a cardinality directive must not be present in a requirement.

Immutable

10.6.8.1 public static final String CAPABILITY_BUNDLE_SYMBOLICNAME_ATTRIBUTE = "bundle-symbolic-name"

The capability attribute contains the symbolic name of the resource providing the package.

10.6.8.2 public static final String CAPABILITY_EXCLUDE_DIRECTIVE = "exclude"

The capability directive used to specify the comma separated list of classes which must not be allowed to be exported.

10.6.8.3 public static final String CAPABILITY_INCLUDE_DIRECTIVE = "include"

The capability directive used to specify the comma separated list of classes which must be allowed to be exported.

10.6.8.4 public static final String CAPABILITY_VERSION_ATTRIBUTE = "version"

The capability attribute contains the Version of the package if one is specified or 0.0.0 if not specified. The value of this attribute must be of type Version.

10.6.8.5 public static final String PACKAGE_NAMESPACE = "osgi.wiring.package"

Namespace name for package capabilities and requirements.

Also, the capability attribute used to specify the name of the package.

10.6.8.6 public static final String RESOLUTION_DYNAMIC = "dynamic"

The directive value identifying a dynamic requirement resolution type. A dynamic resolution type indicates that the requirement is resolved dynamically at runtime (such as a dynamically imported package) and the resource will be resolved without the requirement being resolved.

Namespace.REQUIREMENT_RESOLUTION_DIRECTIVE

10.7 org.osgi.annotation.versioning

Version 1.1

OSGi Versioning Annotations Package Version 1.1.

This package is not used at runtime.

Semantic Versioning

10.7.1 Summary

  • ConsumerType - A type implemented by, or extended by, the Consumer Role.

  • ProviderType - A type implemented by, or extended by, the Provider Role.

  • Version - Specify the version of a package.

10.7.2 @ConsumerType

A type implemented by, or extended by, the Consumer Role.

A non-binary-compatible change to a consumer type or a binary-compatible change to a consumer type affecting an abstract method normally requires incrementing the major version of the type's package. This change will require all providers and all consumers to be updated to handle the change since consumers that implement or extend the consumer type and all providers must understand the change in the consumer type.

A binary-compatible change to a consumer type not affecting an abstract method normally requires incrementing the minor version of the type's package. This change will require all providers to be updated to handle the change, but consumers will not require changes since no abstract methods requiring implementation by the consumer are affected.

A type can be marked ConsumerType or ProviderType but not both. A type is assumed to be ConsumerType if it is not marked either ConsumerType or ProviderType.

A package can be marked ProviderType. In this case, all types in the package are considered to be a provider type regardless of whether they are marked ConsumerType or ProviderType.

This annotation is not retained at runtime. It is for use by tools to understand the semantic version of a package. When a bundle implements a consumer type from an imported package, then the bundle's import range for that package must require the exact major version and a minor version greater than or equal to the package's version.

Semantic Versioning

CLASS

TYPE

10.7.3 @ProviderType

A type implemented by, or extended by, the Provider Role.

A non-binary-compatible change to a provider type normally requires incrementing the major version of the type's package. This change will require all providers and all consumers to be updated to handle the change. However, a non-binary-compatible change affecting a protected access member only requires incrementing the minor version of the type's package. This change will require all providers to be updated to handle the change, but consumers will not require changes since they only use, and do not extend, the provider type and thus could not access protected access members of the provider type.

A binary-compatible change to a provider type normally requires incrementing the minor version of the type's package. This change will require all providers to be updated to handle the change, but consumers will not require changes since they only use, and do not implement or extend, the provider type.

A type can be marked ConsumerType or ProviderType but not both. A type is assumed to be ConsumerType if it is not marked either ConsumerType or ProviderType.

A package can be marked ProviderType. In this case, all types in the package are considered to be a provider type regardless of whether they are marked ConsumerType or ProviderType.

This annotation is not retained at runtime. It is for use by tools to understand the semantic version of a package. When a bundle implements a provider type from an imported package, then the bundle's import range for that package must require the package's exact major and minor version.

Semantic Versioning

CLASS

TYPE, PACKAGE

10.7.4 @Version

Specify the version of a package.

This annotation is not retained at runtime. It is for use by tools to generate bundle manifests or otherwise process the version of a package.

Semantic Versioning

CLASS

PACKAGE

10.7.4.1 String value

The version of the annotated package.

The version must be a valid OSGi version string.

10.8 org.osgi.annotation.bundle

Version 2.0

OSGi Bundle Annotations Package Version 2.0.

This package is not used at runtime.

10.8.1 Summary

10.8.2 @Attribute

Mark an annotation element as an attribute.

This is used when applying Capability or Requirement as a meta annotation to an annotation declaration. The value of the annotation element annotated with Attribute is used as the value of an attribute in the generated capability or requirement clause. For example:

 @Capability(namespace = "my.namespace")
 public @interface MyCapability {
   @Attribute("attr")
   String value() default "";
 }
 
 @MyCapability("foo")
 public MyClass {}

The use of the MyCapability annotation, which is meta annotated with the Capability and Attribute annotations, will result in a capability in the namespace my.namespace with the attribute attr=foo.

If the element annotated with Attribute is unspecified when applied, then the attribute must not be generated in the generated capability or requirement clause. For example:

 @MyCapability
 public MyClass {}

will not have the attr attribute in the generated capability.

This annotation is not retained at runtime. It is for use by tools to generate bundle manifests.

CLASS

METHOD

10.8.2.1 String value default ""

The name of the attribute.

If not specified, the name of the annotated element is used as the name of the attribute.

10.8.3 @Capabilities

Container annotation for repeated Capability annotations.

CLASS

TYPE, PACKAGE

10.8.3.1 Capability[] value

Repeated Capability annotations.

10.8.4 @Capability

Define a capability for a bundle.

For example:

 @Capability(namespace=ExtenderNamespace.EXTENDER_NAMESPACE,
             name="osgi.component", version="1.3.0")

This annotation is not retained at runtime. It is for use by tools to generate bundle manifests or otherwise process the type or package.

This annotation can be used to annotate an annotation

CLASS

TYPE, PACKAGE

10.8.4.1 String namespace

The namespace of this capability.

10.8.4.2 String name default ""

The name of this capability within the namespace.

If specified, adds an attribute with the name of the namespace and the value of the specified name to the capability clause.

10.8.4.3 String version default ""

The version of this capability.

If specified, adds an attribute with the name and type of version:Version and the value of the specified version to the capability clause.

The specified version must be a valid OSGi version string.

10.8.4.4 Class<?>[] uses default {}

A list of classes whose packages are inspected to calculate the uses directive for this capability.

If not specified, the uses directive is omitted from the capability clause.

10.8.4.5 String effective default "resolve"

The effective time of this capability.

Specifies the time the capability is available. The OSGi framework resolver only considers capabilities without an effective directive or effective:=resolve. Capabilities with other values for the effective directive can be considered by an external agent.

If not specified, the effective directive is omitted from the capability clause.

10.8.4.6 String[] attribute default {}

A list of attribute or directive names and values.

Each string should be specified in the form:

  • "name=value" for attributes.

  • "name:type=value" for typed attributes.

  • "name:=value" for directives.

These are added, separated by semicolons, to the capability clause.

10.8.5 @Directive

Mark an annotation element as a directive.

This is used when applying Capability or Requirement as a meta annotation to an annotation declaration. The value of the annotation element annotated with Directive is used as the value of a directive in the generated capability or requirement clause. For example:

 @Capability(namespace = "my.namespace")
 public @interface MyCapability {
   @Directive("resource")
   String value() default "";
 }
 
 @MyCapability("foo")
 public MyClass {}

The use of the MyCapability annotation, which is meta annotated with the Capability and Directive annotations, will result in a capability in the namespace my.namespace with the directive resource:=foo.

If the element annotated with Directive is unspecified when applied, then the directive must not be generated in the generated capability or requirement clause. For example:

 @MyCapability
 public MyClass {}

will not have the resource directive in the generated capability.

This annotation is not retained at runtime. It is for use by tools to generate bundle manifests.

CLASS

METHOD

10.8.5.1 String value default ""

The name of the directive.

If not specified, the name of the annotated element is used as the name of the directive.

10.8.6 @Export

Mark a package to be exported from its bundle.

The package must also be annotation with the Version annotation to specify the export version of the package.

This annotation is not retained at runtime. It is for use by tools to generate bundle manifests or otherwise process the package.

CLASS

PACKAGE

10.8.6.1 String[] uses default {}

A list of package names that are used by this package.

If the uses directive must be omitted from the export package clause for this package, the empty value {} must be specified.

If not specified, the uses directive for the export package clause is calculated by inspection of the classes in this package.

10.8.6.2 String[] attribute default {}

A list of attribute or directive names and values.

Each string should be specified in the form:

  • "name=value" for attributes.

  • "name:type=value" for typed attributes.

  • "name:=value" for directives.

These are added, separated by semicolons, to the export package clause.

10.8.6.3 String substitution default "CALCULATED"

Specify the policy for substitutably importing this package.

Bundles that collaborate require the same class loader for types used in the collaboration. If multiple bundles export packages with collaboration types then they will have to be placed in disjoint class spaces, making collaboration impossible. Collaboration is significantly improved when bundles are willing to import exported packages; these imports will allow a framework to substitute exports for imports.

If not specified, the Substitution.CALCULATED substitution policy is used for this package.

10.8.7 public static final class Export.Substitution

Substitution policy for this package.

10.8.7.1 public static final String CALCULATED = "CALCULATED"

The policy value is calculated by inspection of the classes in the package.

10.8.7.2 public static final String CONSUMER = "CONSUMER"

Use a consumer type version range for the import package clause when substitutably importing a package.

ConsumerType

10.8.7.3 public static final String NOIMPORT = "NOIMPORT"

The package must not be substitutably imported.

10.8.7.4 public static final String PROVIDER = "PROVIDER"

Use a provider type version range for the import package clause when substitutably importing a package.

ProviderType

10.8.8 @Header

Define a manifest header for a bundle.

For example:

 @Header(name=Constants.BUNDLE_CATEGORY, value="osgi")

This annotation is not retained at runtime. It is for use by tools to generate bundle manifests.

CLASS

TYPE, PACKAGE

10.8.8.1 String name

The name of this header.

10.8.8.2 String value

The value of this header.

10.8.9 @Headers

Container annotation for repeated Header annotations.

CLASS

TYPE, PACKAGE

10.8.9.1 Header[] value

Repeated Header annotations.

10.8.10 @Referenced

Mark types as referenced.

A reference can cause the package of a specified type to be imported if the bundle does not contain the package.

This annotation is not retained at runtime. It is for use by tools to generate bundle manifests.

CLASS

TYPE, PACKAGE

10.8.10.1 Class<?>[] value

A list of referenced classes.

Specifying a class in this annotation must be treated by tools as if the annotated type has a code reference to the class which may result in an import of the package of the class if the bundle does not contain that package.

10.8.11 @Requirement

Define a requirement for a bundle.

For example:

 @Requirement(namespace=ExtenderNamespace.EXTENDER_NAMESPACE,
              name="osgi.component", version="1.3.0")

This annotation is not retained at runtime. It is for use by tools to generate bundle manifests or otherwise process the a package.

This annotation can be used to annotate an annotation.

CLASS

TYPE, PACKAGE

10.8.11.1 String namespace

The namespace of this requirement.

10.8.11.2 String name default ""

The name of this requirement within the namespace.

If specified, adds an expression, using the & operator with any specified filter(), to the requirement's filter directive to test that an attribute with the name of the namespace is equal to the value of the specified name.

10.8.11.3 String version default ""

The floor version of the version range for this requirement.

If specified, adds a version range expression, using the & operator with any specified filter(), to the requirement's filter directive. The ceiling version of the version range is the next major version from the floor version. For example, if the specified version is 1.3, then the version range expression is (&(version>=1.3)(!(version>=2.0))).

The specified version must be a valid OSGi version string.

10.8.11.4 String filter default ""

The filter expression of this requirement, if any.

10.8.11.5 String effective default "resolve"

The effective time of this requirement.

Specifies the time the requirement is available. The OSGi framework resolver only considers requirement without an effective directive or effective:=resolve. Requirements with other values for the effective directive can be considered by an external agent.

If not specified, the effective directive is omitted from the requirement clause.

10.8.11.6 String[] attribute default {}

A list of attribute or directive names and values.

Each string should be specified in the form:

  • "name=value" for attributes.

  • "name:type=value" for typed attributes.

  • "name:=value" for directives.

These are added, separated by semicolons, to the requirement clause.

10.8.11.7 String cardinality default "SINGLE"

The cardinality of this requirement.

Indicates if this requirement can be wired a single time or multiple times.

If not specified, the cardinality directive is omitted from the requirement clause.

10.8.11.8 String resolution default "MANDATORY"

The resolution policy of this requirement.

A mandatory requirement forbids the bundle to resolve when this requirement is not satisfied; an optional requirement allows a bundle to resolve even if this requirement is not satisfied.

If not specified, the resolution directive is omitted from the requirement clause.

10.8.12 public static final class Requirement.Cardinality

Cardinality for this requirement.

10.8.12.1 public static final String MULTIPLE = "MULTIPLE"

Indicates if the requirement can be wired multiple times.

10.8.12.2 public static final String SINGLE = "SINGLE"

Indicates if the requirement can only be wired a single time.

10.8.13 public static final class Requirement.Resolution

Resolution for this requirement.

10.8.13.1 public static final String MANDATORY = "MANDATORY"

A mandatory requirement forbids the bundle to resolve when the requirement is not satisfied.

10.8.13.2 public static final String OPTIONAL = "OPTIONAL"

An optional requirement allows a bundle to resolve even if the requirement is not satisfied.

10.8.14 @Requirements

Container annotation for repeated Requirement annotations.

CLASS

TYPE, PACKAGE

10.8.14.1 Requirement[] value

Repeated Requirement annotations.