/* * $Header: /cvshome/build/org.osgi.framework/src/org/osgi/framework/BundleContext.java,v 1.22 2007/02/21 16:49:05 hargrave Exp $ * * Copyright (c) OSGi Alliance (2000, 2007). 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: *

* *

* 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: 1.22 $ */ 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. * *

* The Framework defines the following standard property keys: *

* *

* All bundles must have permission to read these properties. * *

* Note: The last four standard properties are used by the * {@link Constants#BUNDLE_NATIVECODE} Manifest header's * matching algorithm for selecting native language code. * * @param key The name of the requested property. * @return The value of the requested property, or null if * the property is undefined. * @throws java.lang.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 java.lang.IllegalStateException If this BundleContext is no * longer valid. */ public Bundle getBundle(); /** * Installs a bundle from the specified location string. A bundle is * obtained from location as interpreted by the Framework in * an implementation dependent manner. *

* Every installed bundle is uniquely identified by its location string, * typically in the form of a URL. * *

* The following steps are required to install a bundle: *

    *
  1. If a bundle containing the same location string is already * installed, the Bundle object for that bundle is returned. * *
  2. The bundle's content is read from the location string. If this * fails, a {@link BundleException} is thrown. * *
  3. The bundle's Bundle-NativeCode dependencies are * resolved. If this fails, a BundleException is thrown. * *
  4. 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. * *
  5. If the bundle has declared an Bundle-RequiredExecutionEnvironment * header, then the listed execution environments must be verified against * the installed execution environments. If none of the listed execution * environments match an installed execution environment, a * BundleException must be thrown. * *
  6. The bundle's state is set to INSTALLED. * *
  7. A bundle event of type {@link BundleEvent#INSTALLED} is fired. * *
  8. The Bundle object for the newly or previously * installed bundle is returned. *
* * Postconditions, no exceptions thrown * * Postconditions, when an exception is thrown * * * @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 java.lang.SecurityException If the caller does not have the * appropriate AdminPermission[installed bundle,LIFECYCLE], and the * Java Runtime Environment supports permissions. * @throws java.lang.IllegalStateException If this BundleContext is no * longer valid. */ public Bundle installBundle(String location) throws BundleException; /** * Installs a bundle from the specified InputStream object. * *

* This method performs all of the steps listed in * BundleContext.installBundle(String location), except that * the bundle's content will be read from the InputStream * object. The location identifier string specified will be used as the * identity of the bundle. * *

* This method must always close the InputStream object, even * if an exception is thrown. * * @param location The location identifier of the bundle to install. * @param input The InputStream object from which this bundle * will be read. * @return The Bundle object of the installed bundle. * @throws BundleException If the provided stream cannot be read or the * installation failed. * @throws java.lang.SecurityException If the caller does not have the * appropriate AdminPermission[installed bundle,LIFECYCLE], and the * Java Runtime Environment supports permissions. * @throws java.lang.IllegalStateException If this BundleContext is no * longer valid. * @see #installBundle(java.lang.String) */ public Bundle installBundle(String location, InputStream input) 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 java.lang.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 java.lang.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 java.lang.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 java.lang.IllegalStateException If this BundleContext is no * longer valid. * @throws java.lang.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 java.lang.IllegalStateException If this BundleContext is no * longer valid. * @throws java.lang.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 java.lang.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 java.lang.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: *

    *
  1. If service is not a ServiceFactory, * an IllegalArgumentException is thrown if * service is not an instanceof all the * classes named. *
  2. The Framework adds these service properties to the specified * Dictionary (which may be null): a property * named {@link Constants#SERVICE_ID} identifying the registration number of * the service and a property named {@link Constants#OBJECTCLASS} containing * all the specified classes. If any of these properties have already been * specified by the registering bundle, their values will be overwritten by * the Framework. *
  3. The service is added to the Framework service registry and may now * be used by other bundles. *
  4. A service event of type {@link ServiceEvent#REGISTERED} is * fired. *
  5. 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 java.lang.IllegalArgumentException If one of the following is * true: * * * @throws java.lang.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 java.lang.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(java.lang.String[], java.lang.Object, * java.util.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 strings, * 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 java.lang.IllegalStateException If this BundleContext is no * longer valid. * @see #registerService(java.lang.String[], java.lang.Object, * java.util.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 * criteria, 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 anytime. * *

* filter is used to select the registered service whose * properties objects contain keys and values which satisfy the filter. See * {@link Filter} for a description of the filter string syntax. * *

* If filter is null, all registered services * are considered to match the filter. If filter cannot be * parsed, an {@link InvalidSyntaxException} will be thrown with a human * readable message where the filter became unparsable. * *

* The following steps are required to select a set of * ServiceReference objects: *

    *
  1. If the filter string is not null, the filter string * is parsed and the set ServiceReference objects of * registered services that satisfy the filter is produced. If the filter * string is null, then all registered services are * considered to satisfy the filter. *
  2. If the Java Runtime Environment supports permissions, the set of * ServiceReference objects produced by the previous step is * reduced by checking that the caller has the * ServicePermission to get at least one of the class names * under which the service was registered. If the caller does not have the * correct permission for a particular ServiceReference * object, then it is removed from the set. *
  3. If clazz is not null, the set is * further reduced to those services that are an instanceof * and were registered under the specified class. The complete list of * classes of which a service is an instance and which were specified when * the service was registered is available from the service's * {@link Constants#OBJECTCLASS} property. *
  4. The set is reduced one final time by cycling through each * ServiceReference object and calling * {@link ServiceReference#isAssignableTo(Bundle, String)} with the context * bundle and each class name under which the ServiceReference * object was registered. For any given ServiceReference * object, if any call to * {@link ServiceReference#isAssignableTo(Bundle, String)} returns * false, then it is removed from the set of * ServiceReference objects. *
  5. An array of the remaining ServiceReference objects is * returned. *
* * @param clazz The class name with which the service was registered or * null for all services. * @param filter The filter criteria. * @return An array of ServiceReference objects or * null if no services are registered which satisfy * the search. * @throws InvalidSyntaxException If filter contains an * invalid filter string that cannot be parsed. * @throws java.lang.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 * criteria. * *

* 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 anytime. * *

* filter is used to select the registered service whose * properties objects contain keys and values which satisfy the filter. See * {@link Filter} for a description of the filter string syntax. * *

* If filter is null, all registered services * are considered to match the filter. If filter cannot be * parsed, an {@link InvalidSyntaxException} will be thrown with a human * readable message where the filter became unparsable. * *

* The following steps are required to select a set of * ServiceReference objects: *

    *
  1. If the filter string is not null, the filter string * is parsed and the set ServiceReference objects of * registered services that satisfy the filter is produced. If the filter * string is null, then all registered services are * considered to satisfy the filter. *
  2. If the Java Runtime Environment supports permissions, the set of * ServiceReference objects produced by the previous step is * reduced by checking that the caller has the * ServicePermission to get at least one of the class names * under which the service was registered. If the caller does not have the * correct permission for a particular ServiceReference * object, then it is removed from the set. *
  3. If clazz is not null, the set is * further reduced to those services that are an instanceof * and were registered under the specified class. The complete list of * classes of which a service is an instance and which were specified when * the service was registered is available from the service's * {@link Constants#OBJECTCLASS} property. *
  4. An array of the remaining ServiceReference objects is * returned. *
* * @param clazz The class name with which the service was registered or * null for all services. * @param filter The filter criteria. * @return An array of ServiceReference objects or * null if no services are registered which satisfy * the search. * @throws InvalidSyntaxException If filter contains an * invalid filter string that cannot be parsed. * @throws java.lang.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. * *

* This 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 anytime. * *

* This method is the same as calling * {@link BundleContext#getServiceReferences(String, String)} with a * null filter string. 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 java.lang.IllegalStateException If this BundleContext is no * longer valid. * @see #getServiceReferences(String, String) */ public ServiceReference getServiceReference(String clazz); /** * Returns the specified service object for a service. *

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

    *
  1. If the service has been unregistered, null is * returned. *
  2. The context bundle's use count for this service is incremented by * one. *
  3. 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} is fired. *
  4. 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 or does not implement the classes under which it * was registered in the case of a ServiceFactory. * @throws java.lang.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 java.lang.IllegalStateException If this BundleContext is no * longer valid. * @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: *

    *
  1. If the context bundle's use count for the service is zero or the * service has been unregistered, false is returned. *
  2. The context bundle's use count for this service is decremented by * one. *
  3. 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. *
  4. 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 java.lang.IllegalStateException If this BundleContext is no * longer valid. * @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 java.lang.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 java.lang.IllegalStateException If this BundleContext is no * longer valid. * * @since 1.1 * @see "Framework specification for a description of the filter string syntax." * @see FrameworkUtil#createFilter(String) */ public Filter createFilter(String filter) throws InvalidSyntaxException; }