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