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)"
-
AdaptPermission
- A bundle's authority to adapt an object to a type. -
AdminPermission
- A bundle's authority to perform specific privileged administrative operations on or to get sensitive information about a bundle. -
AllServiceListener
- AServiceEvent
listener that does not filter based upon package wiring. -
Bundle
- An installed bundle in the Framework. -
BundleActivator
- Customizes the starting and stopping of a bundle. -
BundleContext
- A bundle's execution context within the Framework. -
BundleEvent
- An event from the Framework describing a bundle lifecycle change. -
BundleException
- A Framework exception used to indicate that a bundle lifecycle problem occurred. -
BundleListener
- ABundleEvent
listener. -
BundlePermission
- A bundle's authority to require or provide a bundle or to receive or attach fragments. -
BundleReference
- A reference to a Bundle. -
CapabilityPermission
- A bundle's authority to provide or require a capability. -
Configurable
- Supports a configuration object. -
Constants
- Defines standard names for the OSGi environment system properties, service properties, and Manifest header attribute keys. -
FrameworkEvent
- A general event from the Framework. -
FrameworkListener
- AFrameworkEvent
listener. -
FrameworkUtil
- Framework Utility class. -
InvalidSyntaxException
- A Framework exception used to indicate that a filter string has an invalid syntax. -
PackagePermission
- A bundle's authority to import or export a package. -
PrototypeServiceFactory
- A factory for prototype scope services. -
ServiceEvent
- An event from the Framework describing a service lifecycle change. -
ServiceException
- A service exception used to indicate that a service problem occurred. -
ServiceFactory
- A factory for bundle scope services. -
ServiceListener
- AServiceEvent
listener. -
ServiceObjects
- Allows multiple service objects for a service to be obtained. -
ServicePermission
- A bundle's authority to register or get a service. -
ServiceReference
- A reference to a service. -
ServiceRegistration
- A registered service. -
SynchronousBundleListener
- A synchronousBundleEvent
listener. -
UnfilteredServiceListener
- AServiceEvent
listener that does not filter based upon any filter string specified to BundleContext.addServiceListener(ServiceListener, String). -
Version
- Version identifier for capabilities such as bundles and packages. -
VersionRange
- Version range.
A bundle's authority to adapt an object to a type.
AdaptPermission
has one action: adapt
.
Thread-safe
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.
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.
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.
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.
Returns the hash code value for this object.
A hash code value for this object.
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.
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
The action string class
. The class
action implies the
resolve
action.
1.3
The action string execute
. The execute
action implies the
resolve
action.
1.3
The action string extensionLifecycle
.
1.3
The action string resolve
. The resolve
action is implied
by the class
, execute
and resource
actions.
1.3
The action string resource
. The resource
action implies
the resolve
action.
1.3
Creates a new AdminPermission
object that matches all bundles and
has all actions. Equivalent to AdminPermission("*","*");
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.
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
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.
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.
Returns the hash code value for this object.
Hash code value for this object.
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.
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
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 Bundle
s 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
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.
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.
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:
-
The bundle's class path from its Constants.BUNDLE_CLASSPATH Manifest header.
-
The bundle's package dependencies from its Constants.EXPORT_PACKAGE and Constants.IMPORT_PACKAGE Manifest headers.
-
The bundle's required bundle dependencies from its Constants.REQUIRE_BUNDLE Manifest header.
-
A fragment bundle's host dependency from its Constants.FRAGMENT_HOST Manifest header.
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.
Request that all certificates used to sign the bundle be returned.
1.5
Request that only certificates used to sign the bundle that are trusted by the framework be returned.
1.5
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
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.
1.4
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.
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.
1.4
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.
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.
<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
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
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
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.
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
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
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
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.
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
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
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.
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.
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
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
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.
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 X509Certificate
s for the signers of this bundle and
the X509Certificate
chains for those signers. The keys of
the Map
are the X509Certificate
s 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
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
.
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
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
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.
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
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:
-
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. -
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.
-
If this bundle's state is
ACTIVE
then this method returns immediately. -
If this bundle's state is not
RESOLVED
, an attempt is made to resolve this bundle. If the Framework cannot resolve this bundle, aBundleException
is thrown. -
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.
-
-
This bundle's state is set to
STARTING
. -
A bundle event of type BundleEvent.STARTING is fired.
-
The BundleActivator.start(BundleContext) method of this bundle's
BundleActivator
, if one is specified, is called. If theBundleActivator
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.
-
-
This bundle's state is set to
ACTIVE
. -
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
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.
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:
-
If this bundle's state is
UNINSTALLED
then anIllegalStateException
is thrown. -
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. -
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.
-
If this bundle's state is not
STARTING
orACTIVE
then this method returns immediately. -
This bundle's state is set to
STOPPING
. -
A bundle event of type BundleEvent.STOPPING is fired.
-
If this bundle's state was
ACTIVE
prior to setting the state toSTOPPING
, the BundleActivator.stop(BundleContext) method of this bundle'sBundleActivator
, if one is specified, is called. If that method throws an exception, this method must continue to stop this bundle and aBundleException
must be thrown after completion of the remaining steps. -
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.
-
If this bundle's state is
UNINSTALLED
, because this bundle was uninstalled while theBundleActivator.stop
method was running, aBundleException
must be thrown. -
This bundle's state is set to
RESOLVED
. -
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
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.
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:
-
If this bundle's state is
UNINSTALLED
, then this method does nothing and returns. -
If this bundle's state is
ACTIVE
,STARTING
orSTOPPING
, this bundle is stopped as described in theBundle.stop
method. IfBundle.stop
throws an exception, a Framework event of type FrameworkEvent.ERROR is fired containing the exception. -
This bundle's state is set to
UNINSTALLED
. -
A bundle event of type BundleEvent.UNINSTALLED is fired.
-
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.
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:
-
If this bundle's state is
UNINSTALLED
then anIllegalStateException
is thrown. -
If this bundle's state is
ACTIVE
,STARTING
orSTOPPING
, this bundle is stopped as described in theBundle.stop
method. IfBundle.stop
throws an exception, the exception is rethrown terminating the update. -
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. -
This bundle's state is set to
INSTALLED
. -
If the updated version of this bundle was successfully installed, a bundle event of type BundleEvent.UPDATED is fired.
-
If this bundle's state was originally
ACTIVE
, the updated bundle is started as described in theBundle.start
method. IfBundle.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.
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.
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
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.
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.
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
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.
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.
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.
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.
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
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 notnull
, 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 notnull
, the filter expression must match the service. -
If the Java Runtime Environment supports permissions, the caller must have
ServicePermission
with theGET
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
Returns the Bundle
object associated with this
BundleContext
. This bundle is called the context bundle.
The Bundle
object associated with this
BundleContext
.
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.
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
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.
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.
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.
<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:
-
If the service has been unregistered,
null
is returned. -
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 isnull
, not aninstanceof
all the classes named when the service was registered or theServiceFactory
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. -
The context bundle's use count for the service is incremented by one.
-
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
.
<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
.
1.8
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.
<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
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 notnull
, 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 notnull
, the filter expression must match the service. -
If the Java Runtime Environment supports permissions, the caller must have
ServicePermission
with theGET
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 returntrue
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.
<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 notnull
, the filter expression must match the service. -
If the Java Runtime Environment supports permissions, the caller must have
ServicePermission
with theGET
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 returntrue
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
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:
-
If a bundle containing the same location identifier is already installed, the
Bundle
object for that bundle is returned. -
The bundle's content is read from the input stream. If this fails, a BundleException is thrown.
-
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. -
The bundle's state is set to
INSTALLED
. -
A bundle event of type BundleEvent.INSTALLED is fired.
-
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.
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.
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:
-
If
service
does not implementServiceFactory
, anIllegalArgumentException
is thrown ifservice
is not aninstanceof
all the specified class names. -
The Framework adds the following service properties to the service properties from the specified
Dictionary
(which may benull
):-
A property named Constants.SERVICE_ID identifying the registration number of the service
-
A property named Constants.OBJECTCLASS containing all the specified classes.
-
A property named Constants.SERVICE_SCOPE identifying the scope of the service.
-
A property named Constants.SERVICE_BUNDLEID identifying the context bundle.
Properties with these names in the specified
Dictionary
will be ignored. -
-
The service is added to the Framework service registry and may now be used by other bundles.
-
A service event of type ServiceEvent.REGISTERED is fired.
-
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
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.
<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
<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
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.
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.
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.
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:
-
If this BundleContext is no longer valid,
false
is returned. -
If the context bundle's use count for the service is zero or the service has been unregistered,
false
is returned. -
The context bundle's use count for the service is decremented by one.
-
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.
-
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
.
An event from the Framework describing a bundle lifecycle change.
BundleEvent
objects are delivered to
SynchronousBundleListener
s and BundleListener
s 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
The bundle has been installed.
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
BundleListener
s.
1.4
The bundle has been started.
The bundle's BundleActivator start method has been executed if the bundle has a bundle activator class.
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 BundleListener
s.
1.3
The bundle has been stopped.
The bundle's BundleActivator stop method has been executed if the bundle has a bundle activator class.
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 BundleListener
s.
1.3
The bundle has been uninstalled.
The bundle has been unresolved.
1.3
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
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.
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.
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
Returns the type of lifecyle event. The type values are:
The type of lifecycle event.
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. BundleException
s
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.
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
The bundle could not be resolved due to an error with the Bundle-NativeCode header.
1.5
The framework received an error while reading the input stream for a bundle.
1.6
The operation failed due to insufficient permissions.
1.5
The start transient operation failed because the start level of the bundle is greater than the current framework start level
1.5
The operation failed to complete the requested lifecycle state change.
1.5
The operation was unsupported. This type can be used anywhere a BundleException can be thrown.
1.5
The associated message.
The cause of this exception.
Creates a BundleException
with the specified message and
exception cause.
The message.
Creates a BundleException
with the specified message.
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
The message.
The type for this exception.
Creates a BundleException
with the specified message and type.
1.5
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
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()
.
Returns the type for this exception or UNSPECIFIED
if the type
was unspecified or unknown.
The type of this exception.
1.5
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
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.
BundleListener
s are called with a BundleEvent
object when a
bundle has been installed, resolved, started, stopped, updated, unresolved,
or uninstalled.
Not Thread-safe
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
The action string provide
. The provide
action implies the
require
action.
The action string require
. The require
action is implied
by the provide
action.
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.
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.
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.
Returns the hash code value for this object.
A hash code value for this object.
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.
A reference to a Bundle.
1.5
Thread-safe
Consumers of this API must not implement this type
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
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.
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
.
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.
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.
Returns the hash code value for this object.
Hash code value for this object.
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.
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.
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.
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
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
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
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.
Manifest header identifying the bundle's category.
The header value may be retrieved from the Dictionary
object
returned by the Bundle.getHeaders
method.
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.
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.
Manifest header identifying the bundle's copyright information.
The header value may be retrieved from the Dictionary
object
returned by the Bundle.getHeaders
method.
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.
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
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.
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
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
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
Default value for the Bundle-Localization
manifest header.
1.3
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
Manifest header identifying the bundle's name.
The header value may be retrieved from the Dictionary
object
returned by the Bundle.getHeaders
method.
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.
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 ...
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 ...
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" ...
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 ...
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.
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
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
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"
1.3
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.
Manifest header identifying the bundle's vendor.
The header value may be retrieved from the Dictionary
object
returned by the Bundle.getHeaders
method.
Manifest header identifying the bundle's version.
The header value may be retrieved from the Dictionary
object
returned by the Bundle.getHeaders
method.
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.
1.3
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
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"
1.6
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
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"
1.6
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
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.
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.
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"
1.3
As of 1.9.
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
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
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"
1.3
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)"
1.6
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"
1.3
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
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"
1.3
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"
1.3
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
Framework launching property specifying the beginning start level of the framework.
Core Specification, Starting the Framework.
1.5
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.
1.3
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
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
Specifies the framework will allow multiple bundles to be installed having the same symbolic name and version.
1.6
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
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
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.
1.5
Specifies to use of the boot class loader as the parent class loader for all bundle class loaders.
1.5
Specifies to use the extension class loader as the parent class loader for all bundle class loaders.
1.5
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.
1.5
Specified the substitution string for the absolute path of a file.
1.6
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
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.
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.
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
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.
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.
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.
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.
1.5
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.
1.5
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
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
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
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
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.
1.6
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
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.
1.5
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
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
Framework environment property identifying the Framework implementation vendor.
The value of this property may be retrieved by calling the
BundleContext.getProperty
method.
Framework environment property identifying the Framework version.
The value of this property may be retrieved by calling the
BundleContext.getProperty
method.
Framework launching property specifying the current windowing system. The framework should provide a reasonable default if this is not set.
1.5
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.
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.
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
Intent supported by Remote Service implementations that support
Asynchronous Remote Services as defined for the osgi.async
intent.
1.9
Intent supported by Remote Services implementations that support Basic
Remote Services as defined for the osgi.basic
intent.
1.9
Intent supported by Remote Service implementation that provide
confidential communications as defined for the osgi.confidential
intent.
1.9
Intent supported by Remote Service implementations that provide private
communications as defined for the osgi.private
intent.
1.9
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"
1.3
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.
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.
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
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
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
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
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
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
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"
1.3
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"
1.3
Service scope is bundle. Each bundle using the service receives a customized service object.
1.8
Service scope is prototype. Each bundle using the service receives either a customized service object or can request multiple customized service objects via ServiceObjects.
1.8
Service scope is singleton. All bundles using the service receive the same service object.
1.8
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)"; ...
1.3
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
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
Service property identifying a service's description.
This property may be supplied in the properties Dictionary
object
passed to the BundleContext.registerService
method.
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
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
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
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
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.
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
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
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
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.
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.
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
Service property identifying a service's vendor.
This property may be supplied in the properties Dictionary
object
passed to the BundleContext.registerService
method.
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
1.3
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.
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
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
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
Identifier of the OSGi system bundle , which is defined to be
0
.
1.8
Location identifier of the OSGi system bundle , which is defined to be "System Bundle".
Alias for the symbolic name of the OSGi system bundle . It is defined to be "system.bundle".
1.3
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
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
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
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"
1.3
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"
1.3
An RFC 1960-based Filter.
Filter
s 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
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.
Returns the hashCode for this Filter
.
This implementation returns the result of calling
this.toString().hashCode()
.
The hashCode of this Filter
.
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.
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.
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
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
A general event from the Framework.
FrameworkEvent
objects are delivered to FrameworkListener
s
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.
Immutable
An error has occurred.
There was an error associated with a bundle.
An informational event has occurred.
There was an informational event associated with a bundle.
1.3
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
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
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
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
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.
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
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
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
A warning has occurred.
There was a warning associated with a bundle.
1.3
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.
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.
Returns the bundle associated with the event. This bundle is also the source of the event.
The bundle associated with the event.
Returns the exception related to this event.
The related exception or null
if none.
Returns the type of framework event.
The type values are:
The type of state change.
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.
Not Thread-safe
Framework Utility class.
This class contains utility methods which access Framework functions that may be useful to bundles.
1.3
Thread-safe
<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
<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
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.
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
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
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
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.
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.
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
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
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)
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
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
The action string export
. The export
action implies the
import
action.
As of 1.5. Use exportonly
instead.
The action string exportonly
. The exportonly
action does
not imply the import
action.
1.5
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.
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
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.
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.
Returns the hash code value for this object.
A hash code value for this object.
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.
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
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.
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.
An event from the Framework describing a service lifecycle change.
ServiceEvent
objects are delivered to ServiceListener
s,
AllServiceListener
s and UnfilteredServiceListener
s 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
The properties of a registered service have been modified.
This event is synchronously delivered after the service properties have been modified.
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
This service has been registered.
This event is synchronously delivered after the service has been registered with the Framework.
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)
The event type.
A ServiceReference
object to the service that
had a lifecycle change.
Creates a new service event object.
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.
Returns the type of event. The event type values are:
Type of service lifecycle change.
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
An asynchronous operation was unable to obtain the service.
1.8
The service factory produced an invalid service object.
The service factory resulted in a recursive call to itself for the requesting bundle.
1.6
The exception is a subclass of ServiceException. The subclass should be examined for the type of the exception.
The associated message.
The cause of this exception.
Creates a ServiceException
with the specified message and
exception cause.
The message.
Creates a ServiceException
with the specified message.
The associated message.
The type for this exception.
The cause of this exception.
Creates a ServiceException
with the specified message, type and
exception cause.
The message.
The type for this exception.
Creates a ServiceException
with the specified message and type.
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
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.
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.
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
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
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:
-
If the associated service has been unregistered,
null
is returned. -
The PrototypeServiceFactory.getService(Bundle, ServiceRegistration) method is called to supply a customized service object for the caller.
-
If the service object returned by the
PrototypeServiceFactory
object isnull
, not aninstanceof
all the classes named when the service was registered or thePrototypeServiceFactory
object throws an exception,null
is returned and a Framework event of type FrameworkEvent.ERROR containing a ServiceException describing the error is fired. -
The use count for the customized service object is incremented by one.
-
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.
Returns the ServiceReference for the service associated with this
ServiceObjects
object.
The ServiceReference for the service associated with this
ServiceObjects
object.
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:
-
If the associated service has been unregistered, this method returns without doing anything.
-
The use count for the specified service object is decremented by one.
-
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.
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
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.
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
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.
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.
Returns the hash code value for this object.
Hash code value for this object.
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.
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
<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
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
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.
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:
-
Must map property values by using property keys in a case-insensitive manner.
-
Must return property keys is a case-preserving manner. This means that the keys 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. -
Is the property of the caller and can be modified by the caller but any changes are not reflected in the properties of the service. ServiceRegistration.setProperties(Dictionary) must be called to modify the properties of the service.
A copy of the properties of the service referenced by this
ServiceReference
object
1.9
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.
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.
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
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:
-
If the specified bundle is equal to the bundle that registered the service referenced by this
ServiceReference
(registrant bundle) returntrue
. -
Get the package name from the specified class name.
-
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). -
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 returnfalse
. -
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 returntrue
; 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 returntrue
; otherwise returnfalse
.
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
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
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.
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:
-
The service's properties are replaced with the provided properties.
-
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.
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:
-
If this
ServiceRegistration
object has already been unregistered, then this method does nothing and returns. -
The service is removed from the Framework service registry so that it can no longer be obtained.
-
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. -
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)
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,
SynchronousBundleListener
s are synchronously called during bundle
lifecycle processing. The bundle lifecycle processing will not proceed until
all SynchronousBundleListener
s have completed.
SynchronousBundleListener
objects will be called prior to
BundleListener
objects.
AdminPermission[bundle,LISTENER]
is required to add or remove a
SynchronousBundleListener
object.
1.1
Thread-safe
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
Version identifier for capabilities such as bundles and packages.
Version identifiers have four components.
-
Major version. A non-negative integer.
-
Minor version. A non-negative integer.
-
Micro version. A non-negative integer.
-
Qualifier. A text string. See
Version(String)
for the format of the qualifier string.
Version
objects are immutable.
1.3
Immutable
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.
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.
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.
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.
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.
Returns the major component of this version identifier.
The major component.
Returns the micro component of this version identifier.
The micro component.
Returns the minor component of this version identifier.
The minor component.
Returns the qualifier component of this version identifier.
The qualifier component.
Returns a hash code value for the object.
An integer which is a hash code value for this object.
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.
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.
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
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
The left endpoint is closed and is included in the range.
The value of LEFT_CLOSED
is '['
.
The left endpoint is open and is excluded from the range.
The value of LEFT_OPEN
is '('
.
The right endpoint is closed and is included in the range.
The value of RIGHT_CLOSED
is ']'
.
The right endpoint is open and is excluded from the range.
The value of RIGHT_OPEN
is ')'
.
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.