org.osgi.framework.BundleContext Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2000, 2009). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.framework;
import java.io.File;
import java.io.InputStream;
import java.util.Dictionary;
/**
* 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 {@link 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 and provided to the
* bundle associated with this context when it is started using the
* {@link BundleActivator#start} method. The same BundleContext
* object will be passed to the bundle associated with this context when it is
* stopped using the {@link BundleActivator#stop} method. 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 Bundle object associated with a BundleContext
* object is called the context bundle.
*
*
* 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. If the BundleContext
* object is used subsequently, an IllegalStateException must be
* thrown. The BundleContext object must never be reused after
* its context bundle is stopped.
*
*
* The Framework is the only entity that can create BundleContext
* objects and they are only valid within the Framework that created them.
*
* @ThreadSafe
* @version $Revision: 6781 $
*/
public interface BundleContext {
/**
* 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.".
*
* @param key The name of the requested property.
* @return The value of the requested property, or null if the
* property is undefined.
* @throws SecurityException If the caller does not have the appropriate
* PropertyPermission to read the property, and the
* Java Runtime Environment supports permissions.
*/
public String getProperty(String key);
/**
* Returns the Bundle object associated with this
* BundleContext. This bundle is called the context bundle.
*
* @return The Bundle object associated with this
* BundleContext.
* @throws IllegalStateException If this BundleContext is no
* longer valid.
*/
public Bundle getBundle();
/**
* 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
* {@link 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 {@link 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 and no trace of the bundle exists.
*
*
* @param location The location identifier of the bundle to install.
* @param input 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.
* @return The Bundle object of the installed bundle.
* @throws BundleException If the input stream cannot be read or the
* installation failed.
* @throws SecurityException If the caller does not have the appropriate
* AdminPermission[installed bundle,LIFECYCLE], and the
* Java Runtime Environment supports permissions.
* @throws IllegalStateException If this BundleContext is no longer valid.
*/
public Bundle installBundle(String location, InputStream input)
throws BundleException;
/**
* Installs a bundle from the specified location identifier.
*
*
* This method performs the same function as calling
* {@link #installBundle(String,InputStream)} with the specified
* location identifier and a null InputStream.
*
* @param location The location identifier of the bundle to install.
* @return The Bundle object of the installed bundle.
* @throws BundleException If the installation failed.
* @throws SecurityException If the caller does not have the appropriate
* AdminPermission[installed bundle,LIFECYCLE], and the
* Java Runtime Environment supports permissions.
* @throws IllegalStateException If this BundleContext is no longer valid.
* @see #installBundle(String, InputStream)
*/
public Bundle installBundle(String location) throws BundleException;
/**
* Returns the bundle with the specified identifier.
*
* @param id The identifier of the bundle to retrieve.
* @return A Bundle object or null if the
* identifier does not match any installed bundle.
*/
public Bundle getBundle(long id);
/**
* 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.
*
* @return An array of Bundle objects, one object per
* installed bundle.
*/
public Bundle[] getBundles();
/**
* Adds the specified ServiceListener object with the
* specified filter to the context bundle's list of
* listeners. See {@link 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
* {@link Constants#OBJECTCLASS} property. If filter is
* null, all services are considered to match the filter.
*
*
* When using a filter, it is possible that the
* ServiceEvents 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.
*
* @param listener The ServiceListener object to be added.
* @param filter The filter criteria.
* @throws InvalidSyntaxException If filter contains an
* invalid filter string that cannot be parsed.
* @throws IllegalStateException If this BundleContext is no
* longer valid.
* @see ServiceEvent
* @see ServiceListener
* @see ServicePermission
*/
public void addServiceListener(ServiceListener listener, String filter)
throws InvalidSyntaxException;
/**
* 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.
*
* @param listener The ServiceListener object to be added.
* @throws IllegalStateException If this BundleContext is no
* longer valid.
* @see #addServiceListener(ServiceListener, String)
*/
public void addServiceListener(ServiceListener listener);
/**
* 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, this method does nothing.
*
* @param listener The ServiceListener to be removed.
* @throws IllegalStateException If this BundleContext is no
* longer valid.
*/
public void removeServiceListener(ServiceListener listener);
/**
* 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.
*
* @param listener The BundleListener to be added.
* @throws IllegalStateException If this BundleContext is no
* longer valid.
* @throws SecurityException If listener is a
* SynchronousBundleListener and the caller does not
* have the appropriate
* AdminPermission[context bundle,LISTENER], and the
* Java Runtime Environment supports permissions.
* @see BundleEvent
* @see BundleListener
*/
public void addBundleListener(BundleListener listener);
/**
* 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, this method does nothing.
*
* @param listener The BundleListener object to be removed.
* @throws IllegalStateException If this BundleContext is no
* longer valid.
* @throws SecurityException If listener is a
* SynchronousBundleListener and the caller does not
* have the appropriate
* AdminPermission[context bundle,LISTENER], and the
* Java Runtime Environment supports permissions.
*/
public void removeBundleListener(BundleListener listener);
/**
* 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.
*
* @param listener The FrameworkListener object to be added.
* @throws IllegalStateException If this BundleContext is no
* longer valid.
* @see FrameworkEvent
* @see FrameworkListener
*/
public void addFrameworkListener(FrameworkListener listener);
/**
* 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, this method does nothing.
*
* @param listener The FrameworkListener object to be
* removed.
* @throws IllegalStateException If this BundleContext is no
* longer valid.
*/
public void removeFrameworkListener(FrameworkListener listener);
/**
* 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 either the
* {@link #getServiceReferences} or {@link #getServiceReference} method.
*
*
* A bundle can register a service object that implements the
* {@link ServiceFactory} interface to have more flexibility in providing
* service objects to other bundles.
*
*
* The following steps are required to register a service:
*
* - If
service is not a ServiceFactory, an
* IllegalArgumentException is thrown if service
* is not an instanceof all the specified class names.
* - The Framework adds the following service properties to the service
* properties from the specified
Dictionary (which may be
* null):
* A property named {@link Constants#SERVICE_ID} identifying the
* registration number of the service
* A property named {@link Constants#OBJECTCLASS} containing all the
* specified classes.
* 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 {@link ServiceEvent#REGISTERED} is fired.
*
- A
ServiceRegistration object for this registration is
* returned.
*
*
* @param clazzes 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 {@link Constants#OBJECTCLASS}.
* @param service The service object or a ServiceFactory
* object.
* @param properties The properties for this service. The keys in the
* properties object must all be String objects. See
* {@link 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
* {@link ServiceRegistration#setProperties} method must be called.
* The set of properties may be null if the service has
* no properties.
* @return A ServiceRegistration object for use by the bundle
* registering the service to update the service's properties or to
* unregister the service.
* @throws IllegalArgumentException If one of the following is true:
*
* service is null. service
* is not a ServiceFactory object and is not an
* instance of all the named classes in clazzes. -
*
properties contains case variants of the same key
* name.
*
* @throws 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.
* @throws IllegalStateException If this BundleContext is no longer valid.
* @see ServiceRegistration
* @see ServiceFactory
*/
public ServiceRegistration registerService(String[] clazzes,
Object service, Dictionary properties);
/**
* Registers the specified service object with the specified properties
* under the specified class name with the Framework.
*
*
* This method is otherwise identical to
* {@link #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
* {@link Constants#OBJECTCLASS} property will be an array of string, rather
* than just a single string.
*
* @param clazz The class name under which the service can be located.
* @param service The service object or a ServiceFactory
* object.
* @param properties The properties for this service.
* @return A ServiceRegistration object for use by the bundle
* registering the service to update the service's properties or to
* unregister the service.
* @throws IllegalStateException If this BundleContext is no longer valid.
* @see #registerService(String[], Object, Dictionary)
*/
public ServiceRegistration registerService(String clazz, Object service,
Dictionary properties);
/**
* 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
* {@link 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 {@link 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 {@link InvalidSyntaxException} will be thrown with a human readable
* message where the filter became unparsable.
*
*
* The result is an array of ServiceReference objects for all
* services that meet all of the following conditions:
*
* - If the specified class name,
clazz, is not
* null, the service must have been registered with the
* specified class name. The complete list of class names with which a
* service was registered is available from the service's
* {@link Constants#OBJECTCLASS objectClass} property.
* - If the specified
filter is not null, the
* filter expression must match the service.
* - If the Java Runtime Environment supports permissions, the caller must
* have
ServicePermission with the GET action for
* at least one of the class names under which the service was registered.
* - For each class name with which the service was registered, calling
* {@link ServiceReference#isAssignableTo(Bundle, String)} with the context
* bundle and the class name on the service's
ServiceReference
* object must return true
*
*
* @param clazz The class name with which the service was registered or
* null for all services.
* @param filter The filter expression or null for all
* services.
* @return An array of ServiceReference objects or
* null if no services are registered which satisfy the
* search.
* @throws InvalidSyntaxException If the specified filter
* contains an invalid filter expression that cannot be parsed.
* @throws IllegalStateException If this BundleContext is no longer valid.
*/
public ServiceReference[] getServiceReferences(String clazz, String filter)
throws InvalidSyntaxException;
/**
* 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 {@link 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 {@link InvalidSyntaxException} will be thrown with a human readable
* message where the filter became unparsable.
*
*
* The result is an array of ServiceReference objects for all
* services that meet all of the following conditions:
*
* - If the specified class name,
clazz, is not
* null, the service must have been registered with the
* specified class name. The complete list of class names with which a
* service was registered is available from the service's
* {@link Constants#OBJECTCLASS objectClass} property.
* - If the specified
filter is not null, the
* filter expression must match the service.
* - If the Java Runtime Environment supports permissions, the caller must
* have
ServicePermission with the GET action for
* at least one of the class names under which the service was registered.
*
*
* @param clazz The class name with which the service was registered or
* null for all services.
* @param filter The filter expression or null for all
* services.
* @return An array of ServiceReference objects or
* null if no services are registered which satisfy the
* search.
* @throws InvalidSyntaxException If the specified filter
* contains an invalid filter expression that cannot be parsed.
* @throws IllegalStateException If this BundleContext is no longer valid.
* @since 1.3
*/
public ServiceReference[] getAllServiceReferences(String clazz,
String filter) throws InvalidSyntaxException;
/**
* 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
* {@link BundleContext#getServiceReferences(String, 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 with the highest ranking (as
* specified in its {@link Constants#SERVICE_RANKING} property) is returned.
*
* If there is a tie in ranking, the service with the lowest service ID (as
* specified in its {@link Constants#SERVICE_ID} property); that is, the
* service that was registered first is returned.
*
* @param clazz The class name with which the service was registered.
* @return A ServiceReference object, or null if
* no services are registered which implement the named class.
* @throws IllegalStateException If this BundleContext is no longer valid.
* @see #getServiceReferences(String, String)
*/
public ServiceReference getServiceReference(String clazz);
/**
* Returns the service object referenced by the specified
* ServiceReference object.
*
* A bundle's use of a service is tracked by the bundle's use count of that
* service. Each time a service's service object is returned by
* {@link #getService(ServiceReference)} the context bundle's use count for
* that service is incremented by one. Each time the service is released by
* {@link #ungetService(ServiceReference)} the context bundle's use count
* for that service is decremented by one.
*
* When a bundle's use count for a service drops to zero, the bundle should
* no longer use that service.
*
*
* This method will always return null when the service
* associated with this reference has been unregistered.
*
*
* The following steps are required to get the service object:
*
* - If the service has been unregistered,
null is returned.
* - The context bundle's use count for this service is incremented by
* one.
*
- If the context bundle's use count for the service is currently one
* and the service was registered with an object implementing the
*
ServiceFactory interface, the
* {@link ServiceFactory#getService(Bundle, ServiceRegistration)} method is
* called to create a service object for the context bundle. This 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
* services's service object for the context bundle will return the cached
* service object.
* If the service object returned by the ServiceFactory object
* is not an instanceof all the classes named when the service
* was registered or the ServiceFactory object throws an
* exception, null is returned and a Framework event of type
* {@link FrameworkEvent#ERROR} containing a {@link ServiceException}
* describing the error is fired.
* - The service object for the service is returned.
*
*
* @param reference A reference to the service.
* @return 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.
* @throws SecurityException If the caller does not have the
* ServicePermission to get the service using at least
* one of the named classes the service was registered under and the
* Java Runtime Environment supports permissions.
* @throws IllegalStateException If this BundleContext is no
* longer valid.
* @throws IllegalArgumentException If the specified
* ServiceReference was not created by the same
* framework instance as this BundleContext.
* @see #ungetService(ServiceReference)
* @see ServiceFactory
*/
public Object getService(ServiceReference reference);
/**
* Releases the service object 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's service object should 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 unget the service object:
*
* - 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 this service is decremented by
* one.
*
- If the context bundle's use count for the service is currently zero
* and the service was registered with a
ServiceFactory object,
* the
* {@link ServiceFactory#ungetService(Bundle, ServiceRegistration, Object)}
* method is called to release the service object for the context bundle.
* true is returned.
*
*
* @param reference A reference to the service to be released.
* @return false if the context bundle's use count for the
* service is zero or if the service has been unregistered;
* true otherwise.
* @throws IllegalStateException If this BundleContext is no
* longer valid.
* @throws IllegalArgumentException If the specified
* ServiceReference was not created by the same
* framework instance as this BundleContext.
* @see #getService
* @see ServiceFactory
*/
public boolean ungetService(ServiceReference reference);
/**
* 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.
*
* @param filename A relative name to the file to be accessed.
* @return A File object that represents the requested file
* or null if the platform does not have file system
* support.
* @throws IllegalStateException If this BundleContext is no
* longer valid.
*/
public File getDataFile(String filename);
/**
* 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 {@link InvalidSyntaxException} will be
* thrown with a human readable message where the filter became unparsable.
*
* @param filter The filter string.
* @return A Filter object encapsulating the filter string.
* @throws InvalidSyntaxException If filter contains an invalid
* filter string that cannot be parsed.
* @throws NullPointerException If filter is null.
* @throws IllegalStateException If this BundleContext is no longer valid.
* @see "Framework specification for a description of the filter string syntax."
* @see FrameworkUtil#createFilter(String)
* @since 1.1
*/
public Filter createFilter(String filter) throws InvalidSyntaxException;
}