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

actions 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:

Filter attribute names are processed in a case sensitive manner.

Throws IllegalArgumentException– If the filter has an invalid syntax.

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

adaptableBundleThe bundle associated with the object being adapted.

actions 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.

objThe 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.

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

□ Returns the canonical string representation of the AdaptPermission actions.

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

ReturnsCanonical string representation of the AdaptPermission actions.

□ Returns the hash code value for this object.

ReturnsA hash code value for this object.

pThe 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.

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

□ Returns a new PermissionCollection object suitable for storing AdaptPermission objects.

ReturnsA new PermissionCollection object.

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

filterA 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.

actions 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 "*".

Throws IllegalArgumentException– If the filter has an invalid syntax.

bundleA bundle.

actions 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.

Since1.3

objThe object being compared for equality with this object.

□ Determines the equality of two AdminPermission objects.

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

□ 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.

ReturnsCanonical string representation of the AdminPermission actions.

□ Returns the hash code value for this object.

ReturnsHash code value for this object.

pThe 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

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

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

□ Returns a new PermissionCollection object suitable for storing AdminPermissions.

ReturnsA new PermissionCollection object.

Type Parameters <A>

<A>The type to which this bundle is to be adapted.

typeClass 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.

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

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

Since1.6

pathThe 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.

filePatternThe 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.

recurseIf 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.

ReturnsAn 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.

Throws IllegalStateException– If this bundle has been uninstalled.

Since1.3

□ 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.

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

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

Since1.4

□ 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:

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

ReturnsThe unique identifier of this bundle.

filenameA 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.

ReturnsA 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.

Throws IllegalStateException– If this bundle has been uninstalled.

Since1.6

pathThe 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.

ReturnsA 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.

Throws IllegalStateException– If this bundle has been uninstalled.

Since1.3

pathThe 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.

ReturnsAn 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.

Throws IllegalStateException– If this bundle has been uninstalled.

Since1.3

□ 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.

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

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

See Also Constants.BUNDLE_LOCALIZATION

localeThe 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.

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

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

See Also getHeaders(), Constants.BUNDLE_LOCALIZATION

Since1.3

□ 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.

ReturnsThe time when this bundle was last modified.

Since1.3

□ 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.

ReturnsThe string representation of this bundle's location identifier.

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

□ 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.

ReturnsAn array of ServiceReference objects or null.

Throws IllegalStateException– If this bundle has been uninstalled.

See Also ServiceRegistration, ServiceReference, ServicePermission

nameThe 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.

ReturnsA 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.

Throws IllegalStateException– If this bundle has been uninstalled.

See Also getEntry(String), findEntries(String, String, boolean)

Since1.1

nameThe 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.

ReturnsAn 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.

Throws IllegalStateException– If this bundle has been uninstalled.

IOException– If there is an I/O error.

Since1.3

□ 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.

ReturnsAn array of ServiceReference objects or null.

Throws IllegalStateException– If this bundle has been uninstalled.

See Also ServiceReference, ServicePermission

signersTypeIf 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.

ReturnsThe 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.

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

Since1.5

□ Returns this bundle's current state.

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

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

□ 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.

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

Since1.3

□ 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.

ReturnsThe version of this bundle.

Since1.5

permissionThe 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.

Returns 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.

Throws IllegalStateException– If this bundle has been uninstalled.

nameThe 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.

ReturnsThe Class object for the requested class.

Throws 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.

Since1.3

optionsThe 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:

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:

Preconditions

Postconditions, no exceptions thrown

Postconditions, when an exception is thrown

Throws 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.

Since1.4

□ Starts this bundle with no options.

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

Throws 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.

See Also start(int)

optionsThe 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:

Preconditions

Postconditions, no exceptions thrown

Postconditions, when an exception is thrown

Throws 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.

Since1.4

□ Stops this bundle with no options.

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

Throws 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.

See Also start(int)

□ 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:

Preconditions

Postconditions, no exceptions thrown

Postconditions, when an exception is thrown

Throws 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.

See Also stop()

inputThe 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:

Preconditions

Postconditions, no exceptions thrown

Postconditions, when an exception is thrown

Throws 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.

See Also stop(), start()

□ Updates this bundle.

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

Throws 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.

See Also update(InputStream)

contextThe 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.

Throws 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.

contextThe 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.

Throws 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.

listenerThe 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.

Throws 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.

See Also BundleEvent, BundleListener

listenerThe 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.

Throws IllegalStateException– If this BundleContext is no longer valid.

See Also FrameworkEvent, FrameworkListener

listenerThe ServiceListener object to be added.

filterThe 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.

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

IllegalStateException– If this BundleContext is no longer valid.

See Also ServiceEvent, ServiceListener, ServicePermission

listenerThe 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.

Throws IllegalStateException– If this BundleContext is no longer valid.

See Also addServiceListener(ServiceListener, String)

filterThe 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.

ReturnsA Filter object encapsulating the filter string.

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

NullPointerException– If filter is null.

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

Since1.1

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

filterThe 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:

ReturnsAn 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.

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

IllegalStateException– If this BundleContext is no longer valid.

Since1.3

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

ReturnsThe Bundle object associated with this BundleContext.

idThe identifier of the bundle to retrieve.

□ Returns the bundle with the specified identifier.

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

Throws IllegalStateException– If this BundleContext is no longer valid.

locationThe location of the bundle to retrieve.

□ Returns the bundle with the specified location.

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

Throws IllegalStateException– If this BundleContext is no longer valid.

Since1.6

□ 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.

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

Throws IllegalStateException– If this BundleContext is no longer valid.

filenameA 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.

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

Throws IllegalStateException– If this BundleContext is no longer valid.

keyThe 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.".

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

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

Type Parameters <S>

<S>Type of Service.

referenceA 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:

ReturnsA 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.

Throws 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.

See Also ungetService(ServiceReference), ServiceFactory

Type Parameters <S>

<S>Type of Service.

referenceA 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.

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

Throws 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.

See Also PrototypeServiceFactory

Since1.8

clazzThe 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.

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

Throws IllegalStateException– If this BundleContext is no longer valid.

See Also getServiceReferences(String, String)

Type Parameters <S>

<S>Type of Service.

clazzThe 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.

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

Throws IllegalStateException– If this BundleContext is no longer valid.

See Also getServiceReferences(Class, String)

Since1.6

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

filterThe 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:

ReturnsAn 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.

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

IllegalStateException– If this BundleContext is no longer valid.

Type Parameters <S>

<S>Type of Service

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

filterThe 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:

ReturnsA 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.

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

IllegalStateException– If this BundleContext is no longer valid.

Since1.6

locationThe location identifier of the bundle to install.

inputThe 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:

Postconditions, no exceptions thrown

Postconditions, when an exception is thrown

ReturnsThe Bundle object of the installed bundle.

Throws 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.

locationThe 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.

ReturnsThe Bundle object of the installed bundle.

Throws 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.

See Also installBundle(String, InputStream)

clazzesThe 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.

serviceThe service object or an object implementing ServiceFactory.

propertiesThe 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:

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

Throws IllegalArgumentException– If one of the following is true:

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.

See Also ServiceRegistration, PrototypeServiceFactory, ServiceFactory

clazzThe class name under which the service can be located.

serviceThe service object or an object implementing ServiceFactory.

propertiesThe 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.

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

Throws IllegalStateException– If this BundleContext is no longer valid.

See Also registerService(String[], Object, Dictionary)

Type Parameters <S>

<S>Type of Service.

clazzThe class under whose name the service can be located.

serviceThe service object or an object implementing ServiceFactory.

propertiesThe 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.

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

Throws IllegalStateException– If this BundleContext is no longer valid.

See Also registerService(String, Object, Dictionary)

Since1.6

Type Parameters <S>

<S>Type of Service.

clazzThe class under whose name the service can be located.

factoryThe ServiceFactory object.

propertiesThe 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.

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

Throws IllegalStateException– If this BundleContext is no longer valid.

See Also registerService(Class, Object, Dictionary)

Since1.8

listenerThe 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.

Throws 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.

listenerThe 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.

listenerThe 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.

referenceA 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:

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

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

See Also getService(ServiceReference), ServiceFactory

typeThe event type.

bundleThe bundle which had a lifecycle change.

originThe 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.

Since1.6

typeThe event type.

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

□ Creates a bundle event of the specified type.

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

ReturnsThe bundle that had a change occur in its lifecycle.

□ 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.

ReturnsThe bundle that was the origin of the event.

Since1.6

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

ReturnsThe type of lifecycle event.

msgThe associated message.

causeThe cause of this exception.

□ Creates a BundleException with the specified message and exception cause.

msgThe message.

□ Creates a BundleException with the specified message.

msgThe associated message.

typeThe type for this exception.

causeThe cause of this exception.

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

Since1.5

msgThe message.

typeThe type for this exception.

□ Creates a BundleException with the specified message and type.

Since1.5

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

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

Since1.3

□ 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.

ReturnsThe result of calling getCause().

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

ReturnsThe type of this exception.

Since1.5

causeThe cause of this exception.

□ Initializes the cause of this exception to the specified value.

ReturnsThis exception.

Throws IllegalArgumentException– If the specified cause is this exception.

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

Since1.3

eventThe BundleEvent.

□ Receives notification that a bundle has had a lifecycle change.

symbolicNameThe bundle symbolic name.

actions 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.

objThe 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.

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

□ Returns the canonical string representation of the BundlePermission actions.

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

ReturnsCanonical string representation of the BundlePermission actions.

□ Returns the hash code value for this object.

ReturnsA hash code value for this object.

pThe 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

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

□ Returns a new PermissionCollection object suitable for storing BundlePermission objects.

ReturnsA new PermissionCollection object.

□ Returns the Bundle object associated with this BundleReference.

ReturnsThe Bundle object associated with this BundleReference.

nameThe capability namespace or a filter over the attributes.

actions 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:

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.

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

namespaceThe requested capability namespace.

attributesThe requested capability attributes.

providingBundleThe bundle providing the requested capability.

actionsThe 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.

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

objThe 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.

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

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

ReturnsThe canonical string representation of the actions.

□ Returns the hash code value for this object.

ReturnsHash code value for this object.

pThe target permission to check.

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

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

□ Returns a new PermissionCollection object for storing CapabilityPermission objects.

ReturnsA new PermissionCollection object suitable for storing CapabilityPermission objects.

□ 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.

ReturnsThe configuration object for this service.

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

DeprecatedAs of 1.2. Please use Configuration Admin service.

objThe object to compare against this Filter.

□ Compares this Filter to another Filter.

This implementation returns the result of calling this.toString().equals(obj.toString()).

ReturnsIf the other object is a Filter object, then returns the result of calling this.toString().equals(obj.toString()); false otherwise.

□ Returns the hashCode for this Filter.

This implementation returns the result of calling this.toString().hashCode().

ReturnsThe hashCode of this Filter.

referenceThe 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.

Returns true if the service's properties match this Filter; false otherwise.

dictionaryThe 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.

Returns true if the Dictionary's values match this filter; false otherwise.

Throws IllegalArgumentException– If dictionary contains case variants of the same key name.

dictionaryThe 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.

Returns true if the Dictionary's values match this filter; false otherwise.

Since1.3

mapThe 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.

Returns true if the Map's values match this filter; false otherwise.

Since1.6

□ Returns this Filter's filter string.

The filter string is normalized by removing whitespace which does not affect the meaning of the filter.

ReturnsThis Filter's filter string.

typeThe event type.

sourceThe event source object. This may not be null.

□ Creates a Framework event.

DeprecatedAs of 1.2. This constructor is deprecated in favor of using the other constructor with the System Bundle as the event source.

typeThe event type.

bundleThe event source.

throwableThe related exception. This argument may be null if there is no related exception.

□ Creates a Framework event regarding the specified bundle.

□ Returns the bundle associated with the event. This bundle is also the source of the event.

ReturnsThe bundle associated with the event.

□ Returns the exception related to this event.

ReturnsThe related exception or null if none.

□ Returns the type of framework event.

The type values are:

ReturnsThe type of state change.

eventThe FrameworkEvent object.

□ Receives notification of a general FrameworkEvent object.

Type Parameters <K, V>

<K>The type of the key.

<V>The type of the value.

mapThe map to wrap.

□ Return a Dictionary wrapper around a Map.

ReturnsA Dictionary object which wraps the specified map. If the specified map can be cast to a Dictionary, then the specified map is returned.

Since1.10

Type Parameters <K, V>

<K>The type of the key.

<V>The type of the value.

dictionaryThe dictionary to wrap.

□ Return a Map wrapper around a Dictionary.

ReturnsA Map object which wraps the specified dictionary. If the specified dictionary can be cast to a Map, then the specified dictionary is returned.

Since1.10

filterThe 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).

ReturnsA Filter object encapsulating the filter string.

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

NullPointerException– If filter is null.

See Also Filter

bundleClassLoaderA bundle class loader.

□ Return a Bundle for the specified bundle class loader.

ReturnsAn 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.

Since1.10

classFromBundleA class defined by a bundle.

□ Return a Bundle for the specified bundle class.

ReturnsA Bundle for the specified bundle class or null if the specified class was not defined by a bundle.

Since1.5

matchPatternThe pattern against which to match the DN chain.

dnChainThe 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

Returns true If the pattern matches the DN chain; otherwise false is returned.

Throws IllegalArgumentException– If the specified match pattern or DN chain is invalid.

Since1.5

msgThe message.

filterThe 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.

msgThe message.

filterThe invalid filter string.

causeThe 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.

Since1.3

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

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

Since1.3

□ Returns the filter string that generated the InvalidSyntaxException object.

ReturnsThe invalid filter string.

See Also BundleContext.getServiceReferences(Class, String), BundleContext.getServiceReferences(String, String), BundleContext.addServiceListener(ServiceListener,String)

causeThe cause of this exception.

□ Initializes the cause of this exception to the specified value.

ReturnsThis exception.

Throws IllegalArgumentException– If the specified cause is this exception.

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

Since1.3

namePackage name or filter expression. A filter expression can only be specified if the specified action is import.

actions 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:

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.

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

nameThe name of the requested package to import.

exportingBundleThe bundle exporting the requested package.

actionsThe 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.

Throws IllegalArgumentException– If the specified action is not import or the name is a filter expression.

Since1.5

objThe 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.

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

□ Returns the canonical string representation of the PackagePermission actions.

Always returns present PackagePermission actions in the following order: EXPORTONLY,IMPORT.

ReturnsCanonical string representation of the PackagePermission actions.

□ Returns the hash code value for this object.

ReturnsA hash code value for this object.

pThe 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

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

□ Returns a new PermissionCollection object suitable for storing PackagePermission objects.

ReturnsA new PermissionCollection object.

bundleThe bundle requesting the service.

registrationThe 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.

ReturnsA service object that must be an instance of all the classes named when the service was registered.

See Also ServiceObjects.getService()