public  void addBundleListener(BundleListener 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.

 public  void addFrameworkListener(FrameworkListener 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.

 public  void addServiceListener(ServiceListener listener)
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.

 public  void addServiceListener(ServiceListener listener,
    String filter) throws InvalidSyntaxException
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
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.

 public Filter createFilter(String filter) throws InvalidSyntaxException
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.

 public ServiceReference[] getAllServiceReferences(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
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 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:

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.
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.
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
Constants#OBJECTCLASS  property.
An array of the remaining ServiceReference objects is
returned.

 public Bundle getBundle()
Returns the Bundle object associated with this
BundleContext. This bundle is called the context bundle.

 public Bundle getBundle(long id)
Returns the bundle with the specified identifier.

 public Bundle[] getBundles()
Returns a list of all installed bundles.

This method returns a list of all bundles installed in the OSGi
environment at the time of the call to this method. However, since the
Framework is a very dynamic environment, bundles can be installed or
uninstalled at anytime.

 public File getDataFile(String filename)
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.

 public String getProperty(String key)
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:


Constants#FRAMEWORK_VERSION  - The OSGi Framework version.

Constants#FRAMEWORK_VENDOR  - The Framework implementation
vendor.
Constants#FRAMEWORK_LANGUAGE  - The language being used. See
ISO 639 for possible values.
Constants#FRAMEWORK_OS_NAME  - The host computer operating
system.
Constants#FRAMEWORK_OS_VERSION  - The host computer
operating system version number.
Constants#FRAMEWORK_PROCESSOR  - The host computer processor
name.


All bundles must have permission to read these properties.


Note: The last four standard properties are used by the
Constants#BUNDLE_NATIVECODE  Manifest header's
matching algorithm for selecting native language code.

 public Object getService(ServiceReference reference)
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
#getService(ServiceReference)  the context bundle's use count for
that service is incremented by one. Each time the service is released by
#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
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 FrameworkEvent#ERROR  is fired.
The service object for the service is returned.

 public ServiceReference getServiceReference(String clazz)
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
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 Constants#SERVICE_RANKING  property) is returned.

If there is a tie in ranking, the service with the lowest service ID (as
specified in its Constants#SERVICE_ID  property); that is, the
service that was registered first is returned.

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

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.
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.
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
Constants#OBJECTCLASS  property.
The set is reduced one final time by cycling through each
ServiceReference object and calling
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
ServiceReference#isAssignableTo(Bundle, String)  returns
false, then it is removed from the set of
ServiceReference objects.
An array of the remaining ServiceReference objects is
returned.

 public Bundle installBundle(String location) throws BundleException
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:

If a bundle containing the same location string is already
installed, the Bundle object for that bundle is returned.

The bundle's content is read from the location string. If this
fails, a BundleException  is thrown.

The bundle's Bundle-NativeCode dependencies are
resolved. 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.

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.

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 and no trace of the bundle exists.

 public Bundle installBundle(String location,
    InputStream input) 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.

 public ServiceRegistration registerService(String[] clazzes,
    Object service,
    Dictionary 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 either the
#getServiceReferences  or #getServiceReference  method.


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 is not a ServiceFactory,
an IllegalArgumentException is thrown if
service is not an instanceof all the
classes named.
The Framework adds these service properties to the specified
Dictionary (which may be null): a property
named Constants#SERVICE_ID  identifying the registration number of
the service and a property named 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.
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.

 public ServiceRegistration registerService(String clazz,
    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
#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
Constants#OBJECTCLASS  property will be an array of strings,
rather than just a single string.

 public  void removeBundleListener(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.

 public  void removeFrameworkListener(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.

 public  void removeServiceListener(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.

 public boolean ungetService(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
ServiceFactory#ungetService(Bundle, ServiceRegistration, Object) 
method is called to release the service object for the context bundle.
true is returned.