Class BundleContextImpl
- java.lang.Object
-
- org.apache.felix.framework.BundleContextImpl
-
- All Implemented Interfaces:
FelixBundleContext
,BundleContext
,BundleReference
class BundleContextImpl extends java.lang.Object implements FelixBundleContext
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) class
BundleContextImpl.ServiceObjectsImpl<S>
-
Constructor Summary
Constructors Modifier Constructor Description protected
BundleContextImpl(Logger logger, Felix felix, BundleImpl bundle)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addBundleListener(BundleListener l)
Adds the specifiedBundleListener
object to the context bundle's list of listeners if not already present.void
addCapability()
void
addFrameworkListener(FrameworkListener l)
Adds the specifiedFrameworkListener
object to the context bundle's list of listeners if not already present.void
addRequirement(java.lang.String s)
void
addServiceListener(ServiceListener l)
Adds the specifiedServiceListener
object to the context bundle's list of listeners.void
addServiceListener(ServiceListener l, java.lang.String s)
Adds the specifiedServiceListener
object with the specifiedfilter
to the context bundle's list of listeners.private void
checkValidity()
Filter
createFilter(java.lang.String expr)
Creates aFilter
object.ServiceReference<?>[]
getAllServiceReferences(java.lang.String clazz, java.lang.String filter)
Returns an array ofServiceReference
objects.private ServiceReference
getBestServiceReference(ServiceReference[] refs)
Bundle
getBundle()
Returns theBundle
object associated with thisBundleContext
.Bundle
getBundle(long id)
Returns the bundle with the specified identifier.Bundle
getBundle(java.lang.String location)
Returns the bundle with the specified location.Bundle[]
getBundles()
Returns a list of all installed bundles.java.io.File
getDataFile(java.lang.String s)
Creates aFile
object for a file in the persistent storage area provided for the bundle by the Framework.java.lang.String
getProperty(java.lang.String name)
Returns the value of the specified property.<S> S
getService(ServiceReference<S> ref)
Returns the service object for the service referenced by the specifiedServiceReference
object.<S> ServiceObjects<S>
getServiceObjects(ServiceReference<S> ref)
Returns theServiceObjects
object for the service referenced by the specifiedServiceReference
object.<S> ServiceReference<S>
getServiceReference(java.lang.Class<S> clazz)
Returns aServiceReference
object for a service that implements and was registered under the name of the specified class.ServiceReference<?>
getServiceReference(java.lang.String clazz)
Returns aServiceReference
object for a service that implements and was registered under the specified class.<S> java.util.Collection<ServiceReference<S>>
getServiceReferences(java.lang.Class<S> clazz, java.lang.String filter)
Returns a collection ofServiceReference
objects.ServiceReference<?>[]
getServiceReferences(java.lang.String clazz, java.lang.String filter)
Returns an array ofServiceReference
objects.Bundle
installBundle(java.lang.String location)
Installs a bundle from the specifiedlocation
identifier.Bundle
installBundle(java.lang.String location, java.io.InputStream is)
Installs a bundle from the specifiedInputStream
object.protected void
invalidate()
<S> ServiceRegistration<S>
registerService(java.lang.Class<S> clazz, ServiceFactory<S> factory, java.util.Dictionary<java.lang.String,?> properties)
Registers the specified service factory object with the specified properties under the name of the specified class with the Framework.<S> ServiceRegistration<S>
registerService(java.lang.Class<S> clazz, S svcObj, java.util.Dictionary<java.lang.String,?> dict)
Registers the specified service object with the specified properties under the name of the specified class with the Framework.ServiceRegistration<?>
registerService(java.lang.String[] clazzes, java.lang.Object svcObj, java.util.Dictionary<java.lang.String,?> dict)
Registers the specified service object with the specified properties under the specified class names into the Framework.ServiceRegistration<?>
registerService(java.lang.String clazz, java.lang.Object svcObj, java.util.Dictionary<java.lang.String,?> dict)
Registers the specified service object with the specified properties under the specified class name with the Framework.void
removeBundleListener(BundleListener l)
Removes the specifiedBundleListener
object from the context bundle's list of listeners.void
removeCapability()
void
removeFrameworkListener(FrameworkListener l)
Removes the specifiedFrameworkListener
object from the context bundle's list of listeners.void
removeRequirement()
void
removeServiceListener(ServiceListener l)
Removes the specifiedServiceListener
object from the context bundle's list of listeners.boolean
ungetService(ServiceReference<?> ref)
Releases the service object for the service referenced by the specifiedServiceReference
object.
-
-
-
Field Detail
-
m_logger
private Logger m_logger
-
m_felix
private Felix m_felix
-
m_bundle
private BundleImpl m_bundle
-
m_valid
private boolean m_valid
-
-
Constructor Detail
-
BundleContextImpl
protected BundleContextImpl(Logger logger, Felix felix, BundleImpl bundle)
-
-
Method Detail
-
invalidate
protected void invalidate()
-
addRequirement
public void addRequirement(java.lang.String s) throws BundleException
- Specified by:
addRequirement
in interfaceFelixBundleContext
- Throws:
BundleException
-
removeRequirement
public void removeRequirement() throws BundleException
- Specified by:
removeRequirement
in interfaceFelixBundleContext
- Throws:
BundleException
-
addCapability
public void addCapability() throws BundleException
- Specified by:
addCapability
in interfaceFelixBundleContext
- Throws:
BundleException
-
removeCapability
public void removeCapability() throws BundleException
- Specified by:
removeCapability
in interfaceFelixBundleContext
- Throws:
BundleException
-
getProperty
public java.lang.String getProperty(java.lang.String name)
Description copied from 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 returnsnull
if the property is not found.All bundles must have permission to read properties whose names start with "org.osgi.".
- Specified by:
getProperty
in interfaceBundleContext
- Parameters:
name
- The name of the requested property.- Returns:
- The value of the requested property, or
null
if the property is undefined.
-
getBundle
public Bundle getBundle()
Description copied from interface:BundleContext
Returns theBundle
object associated with thisBundleContext
. This bundle is called the context bundle.- Specified by:
getBundle
in interfaceBundleContext
- Specified by:
getBundle
in interfaceBundleReference
- Returns:
- The
Bundle
object associated with thisBundleContext
.
-
createFilter
public Filter createFilter(java.lang.String expr) throws InvalidSyntaxException
Description copied from interface:BundleContext
Creates aFilter
object. ThisFilter
object may be used to match aServiceReference
object or aDictionary
object.If the filter cannot be parsed, an
InvalidSyntaxException
will be thrown with a human readable message where the filter became unparsable.- Specified by:
createFilter
in interfaceBundleContext
- Parameters:
expr
- The filter string.- Returns:
- A
Filter
object encapsulating the filter string. - Throws:
InvalidSyntaxException
- Iffilter
contains an invalid filter string that cannot be parsed.- See Also:
- "Framework specification for a description of the filter string syntax.",
FrameworkUtil.createFilter(String)
-
installBundle
public Bundle installBundle(java.lang.String location) throws BundleException
Description copied from interface:BundleContext
Installs a bundle from the specifiedlocation
identifier.This method performs the same function as calling
BundleContext.installBundle(String,InputStream)
with the specifiedlocation
identifier and anull
InputStream.- Specified by:
installBundle
in interfaceBundleContext
- Parameters:
location
- The location identifier of the bundle to install.- Returns:
- The
Bundle
object of the installed bundle. - Throws:
BundleException
- If the installation failed. BundleException types thrown by this method include:BundleException.READ_ERROR
,BundleException.DUPLICATE_BUNDLE_ERROR
,BundleException.MANIFEST_ERROR
, andBundleException.REJECTED_BY_HOOK
.- See Also:
BundleContext.installBundle(String, InputStream)
-
installBundle
public Bundle installBundle(java.lang.String location, java.io.InputStream is) throws BundleException
Description copied from interface:BundleContext
Installs a bundle from the specifiedInputStream
object.If the specified
InputStream
isnull
, the Framework must create theInputStream
from which to read the bundle by interpreting, in an implementation dependent manner, the specifiedlocation
.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.
getState()
in {INSTALLED
,RESOLVED
}.- Bundle has a unique ID.
- 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.
- Specified by:
installBundle
in interfaceBundleContext
- Parameters:
location
- The location identifier of the bundle to install.is
- TheInputStream
object from which this bundle will be read ornull
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.- Returns:
- The
Bundle
object of the installed bundle. - Throws:
BundleException
- If the installation failed. BundleException types thrown by this method include:BundleException.READ_ERROR
,BundleException.DUPLICATE_BUNDLE_ERROR
,BundleException.MANIFEST_ERROR
, andBundleException.REJECTED_BY_HOOK
.
- If a bundle containing the same location identifier is already
installed, the
-
getBundle
public Bundle getBundle(long id)
Description copied from interface:BundleContext
Returns the bundle with the specified identifier.- Specified by:
getBundle
in interfaceBundleContext
- Parameters:
id
- The identifier of the bundle to retrieve.- Returns:
- A
Bundle
object ornull
if the identifier does not match any installed bundle.
-
getBundle
public Bundle getBundle(java.lang.String location)
Description copied from interface:BundleContext
Returns the bundle with the specified location.- Specified by:
getBundle
in interfaceBundleContext
- Parameters:
location
- The location of the bundle to retrieve.- Returns:
- A
Bundle
object ornull
if the location does not match any installed bundle.
-
getBundles
public Bundle[] getBundles()
Description copied from interface:BundleContext
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.
- Specified by:
getBundles
in interfaceBundleContext
- Returns:
- An array of
Bundle
objects, one object per installed bundle.
-
addBundleListener
public void addBundleListener(BundleListener l)
Description copied from interface:BundleContext
Adds the specifiedBundleListener
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.- Specified by:
addBundleListener
in interfaceBundleContext
- Parameters:
l
- TheBundleListener
to be added.- See Also:
BundleEvent
,BundleListener
-
removeBundleListener
public void removeBundleListener(BundleListener l)
Description copied from interface:BundleContext
Removes the specifiedBundleListener
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.- Specified by:
removeBundleListener
in interfaceBundleContext
- Parameters:
l
- TheBundleListener
object to be removed.
-
addServiceListener
public void addServiceListener(ServiceListener l)
Description copied from interface:BundleContext
Adds the specifiedServiceListener
object to the context bundle's list of listeners.This method is the same as calling
BundleContext.addServiceListener(ServiceListener listener, String filter)
withfilter
set tonull
.- Specified by:
addServiceListener
in interfaceBundleContext
- Parameters:
l
- TheServiceListener
object to be added.- See Also:
BundleContext.addServiceListener(ServiceListener, String)
-
addServiceListener
public void addServiceListener(ServiceListener l, java.lang.String s) throws InvalidSyntaxException
Description copied from interface:BundleContext
Adds the specifiedServiceListener
object with the specifiedfilter
to the context bundle's list of listeners. SeeFilter
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 benull
) with the specified one (which may benull
).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. Iffilter
isnull
, all services are considered to match the filter.When using a
filter
, it is possible that theServiceEvent
s for the complete lifecycle of a service will not be delivered to the listener. For example, if thefilter
only matches when the propertyx
has the value1
, the listener will not be called if the service is registered with the propertyx
not set to the value1
. Subsequently, when the service is modified setting propertyx
to the value1
, the filter will match and the listener will be called with aServiceEvent
of typeMODIFIED
. Thus, the listener will not be called with aServiceEvent
of typeREGISTERED
.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 theServicePermission
to get the service using at least one of the named classes the service was registered under.- Specified by:
addServiceListener
in interfaceBundleContext
- Parameters:
l
- TheServiceListener
object to be added.s
- The filter criteria.- Throws:
InvalidSyntaxException
- Iffilter
contains an invalid filter string that cannot be parsed.- See Also:
ServiceEvent
,ServiceListener
,ServicePermission
-
removeServiceListener
public void removeServiceListener(ServiceListener l)
Description copied from interface:BundleContext
Removes the specifiedServiceListener
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.- Specified by:
removeServiceListener
in interfaceBundleContext
- Parameters:
l
- TheServiceListener
to be removed.
-
addFrameworkListener
public void addFrameworkListener(FrameworkListener l)
Description copied from interface:BundleContext
Adds the specifiedFrameworkListener
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.- Specified by:
addFrameworkListener
in interfaceBundleContext
- Parameters:
l
- TheFrameworkListener
object to be added.- See Also:
FrameworkEvent
,FrameworkListener
-
removeFrameworkListener
public void removeFrameworkListener(FrameworkListener l)
Description copied from interface:BundleContext
Removes the specifiedFrameworkListener
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.- Specified by:
removeFrameworkListener
in interfaceBundleContext
- Parameters:
l
- TheFrameworkListener
object to be removed.
-
registerService
public ServiceRegistration<?> registerService(java.lang.String clazz, java.lang.Object svcObj, java.util.Dictionary<java.lang.String,?> dict)
Description copied from interface:BundleContext
Registers the specified service object with the specified properties under the specified class name with the Framework.This method is otherwise identical to
BundleContext.registerService(String[], Object, Dictionary)
and is provided as a convenience whenservice
will only be registered under a single class name. Note that even in this case the value of the service'sConstants.OBJECTCLASS
property will be an array of string, rather than just a single string.- Specified by:
registerService
in interfaceBundleContext
- Parameters:
clazz
- The class name under which the service can be located.svcObj
- The service object or an object implementingServiceFactory
.dict
- The properties for this service.- Returns:
- A
ServiceRegistration
object for use by the bundle registering the service to update the service's properties or to unregister the service. - See Also:
BundleContext.registerService(String[], Object, Dictionary)
-
registerService
public ServiceRegistration<?> registerService(java.lang.String[] clazzes, java.lang.Object svcObj, java.util.Dictionary<java.lang.String,?> dict)
Description copied from interface:BundleContext
Registers the specified service object with the specified properties under the specified class names into the Framework. AServiceRegistration
object is returned. TheServiceRegistration
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 theBundleContext.getServiceReferences(Class, String)
,BundleContext.getServiceReferences(String, String)
,BundleContext.getServiceReference(Class)
orBundleContext.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 the context bundle.
Dictionary
will be ignored. - A property named
- 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.
- Specified by:
registerService
in interfaceBundleContext
- Parameters:
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 keyConstants.OBJECTCLASS
.svcObj
- The service object or an object implementingServiceFactory
.dict
- The properties for this service. The keys in the properties object must all beString
objects. SeeConstants
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 theServiceRegistration.setProperties(Dictionary)
method must be called. The set of properties may benull
if the service has no properties.- Returns:
- A
ServiceRegistration
object for use by the bundle registering the service to update the service's properties or to unregister the service. - See Also:
ServiceRegistration
,PrototypeServiceFactory
,ServiceFactory
- If
-
registerService
public <S> ServiceRegistration<S> registerService(java.lang.Class<S> clazz, S svcObj, java.util.Dictionary<java.lang.String,?> dict)
Description copied from interface:BundleContext
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
BundleContext.registerService(String, Object, Dictionary)
and is provided to return a type safeServiceRegistration
.- Specified by:
registerService
in interfaceBundleContext
- Type Parameters:
S
- Type of Service.- Parameters:
clazz
- The class under whose name the service can be located.svcObj
- The service object or an object implementingServiceFactory
.dict
- The properties for this service.- Returns:
- A
ServiceRegistration
object for use by the bundle registering the service to update the service's properties or to unregister the service. - See Also:
BundleContext.registerService(String, Object, Dictionary)
-
getServiceReference
public ServiceReference<?> getServiceReference(java.lang.String clazz)
Description copied from interface:BundleContext
Returns aServiceReference
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
BundleContext.getServiceReferences(String, String)
with anull
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 with the highest priority is selected. This priority is defined as the service reference 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.- Specified by:
getServiceReference
in interfaceBundleContext
- Parameters:
clazz
- The class name with which the service was registered.- Returns:
- A
ServiceReference
object, ornull
if no services are registered which implement the named class. - See Also:
BundleContext.getServiceReferences(String, String)
-
getServiceReference
public <S> ServiceReference<S> getServiceReference(java.lang.Class<S> clazz)
Description copied from interface:BundleContext
Returns aServiceReference
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
BundleContext.getServiceReferences(Class, String)
with anull
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
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.- Specified by:
getServiceReference
in interfaceBundleContext
- Type Parameters:
S
- Type of Service.- Parameters:
clazz
- The class under whose name the service was registered. Must not benull
.- Returns:
- A
ServiceReference
object, ornull
if no services are registered which implement the specified class. - See Also:
BundleContext.getServiceReferences(Class, String)
-
getBestServiceReference
private ServiceReference getBestServiceReference(ServiceReference[] refs)
-
getAllServiceReferences
public ServiceReference<?>[] getAllServiceReferences(java.lang.String clazz, java.lang.String filter) throws InvalidSyntaxException
Description copied from interface:BundleContext
Returns an array ofServiceReference
objects. The returned array ofServiceReference
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. SeeFilter
for a description of the filter syntax. If the specifiedfilter
isnull
, all registered services are considered to match the filter. If the specifiedfilter
expression cannot be parsed, anInvalidSyntaxException
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'sobjectClass
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.
- Specified by:
getAllServiceReferences
in interfaceBundleContext
- Parameters:
clazz
- The class name with which the service was registered ornull
for all services.filter
- The filter expression ornull
for all services.- Returns:
- An array of
ServiceReference
objects ornull
if no services are registered which satisfy the search. - Throws:
InvalidSyntaxException
- If the specifiedfilter
contains an invalid filter expression that cannot be parsed.
- If the specified class name,
-
getServiceReferences
public ServiceReference<?>[] getServiceReferences(java.lang.String clazz, java.lang.String filter) throws InvalidSyntaxException
Description copied from interface:BundleContext
Returns an array ofServiceReference
objects. The returned array ofServiceReference
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 inServiceReference.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. SeeFilter
for a description of the filter syntax. If the specifiedfilter
isnull
, all registered services are considered to match the filter. If the specifiedfilter
expression cannot be parsed, anInvalidSyntaxException
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'sobjectClass
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'sServiceReference
object must returntrue
- Specified by:
getServiceReferences
in interfaceBundleContext
- Parameters:
clazz
- The class name with which the service was registered ornull
for all services.filter
- The filter expression ornull
for all services.- Returns:
- An array of
ServiceReference
objects ornull
if no services are registered which satisfy the search. - Throws:
InvalidSyntaxException
- If the specifiedfilter
contains an invalid filter expression that cannot be parsed.
- If the specified class name,
-
getServiceReferences
public <S> java.util.Collection<ServiceReference<S>> getServiceReferences(java.lang.Class<S> clazz, java.lang.String filter) throws InvalidSyntaxException
Description copied from interface:BundleContext
Returns a collection ofServiceReference
objects. The returned collection ofServiceReference
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 inServiceReference.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. SeeFilter
for a description of the filter syntax. If the specifiedfilter
isnull
, all registered services are considered to match the filter. If the specifiedfilter
expression cannot be parsed, anInvalidSyntaxException
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'sServiceReference
object must returntrue
- Specified by:
getServiceReferences
in interfaceBundleContext
- Type Parameters:
S
- Type of Service- Parameters:
clazz
- The class under whose name the service was registered. Must not benull
.filter
- The filter expression ornull
for all services.- Returns:
- A collection of
ServiceReference
objects. May be empty if no services are registered which satisfy the search. - Throws:
InvalidSyntaxException
- If the specifiedfilter
contains an invalid filter expression that cannot be parsed.
- 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
-
getService
public <S> S getService(ServiceReference<S> ref)
Description copied from interface:BundleContext
Returns the service object for the service referenced by the specifiedServiceReference
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
BundleContext.getService(ServiceReference)
the context bundle's use count for the service is incremented by one. Each time the service object is released byBundleContext.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 specifiedreference
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
orprototype
scope, theServiceFactory.getService(Bundle, ServiceRegistration)
method is called to supply the service object for the context bundle. If the service object returned by theServiceFactory
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 typeFrameworkEvent.ERROR
containing aServiceException
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.
- Specified by:
getService
in interfaceBundleContext
- Type Parameters:
S
- Type of Service.- Parameters:
ref
- A reference to the service.- Returns:
- A service object for the service associated with
reference
ornull
if the service is not registered, the service object returned by aServiceFactory
does not implement the classes under which it was registered or theServiceFactory
threw an exception. - See Also:
BundleContext.ungetService(ServiceReference)
,ServiceFactory
- If the service has been unregistered,
-
ungetService
public boolean ungetService(ServiceReference<?> ref)
Description copied from interface:BundleContext
Releases the service object for the service referenced by the specifiedServiceReference
object. If the context bundle's use count for the service is zero, this method returnsfalse
. 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 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
orprototype
scope, theServiceFactory.ungetService(Bundle, ServiceRegistration, Object)
method is called to release the service object for the context bundle. true
is returned.
- Specified by:
ungetService
in interfaceBundleContext
- Parameters:
ref
- A reference to the service to be released.- Returns:
false
if the context bundle's use count for the service is zero or if the service has been unregistered;true
otherwise.- See Also:
BundleContext.getService(ServiceReference)
,ServiceFactory
- If the context bundle's use count for the service is zero or the
service has been unregistered,
-
getDataFile
public java.io.File getDataFile(java.lang.String s)
Description copied from interface:BundleContext
Creates aFile
object for a file in the persistent storage area provided for the bundle by the Framework. This method will returnnull
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 asfilename
.If the Java Runtime Environment supports permissions, the Framework will ensure that the bundle has the
java.io.FilePermission
with actionsread
,write
,delete
for all files (recursively) in the persistent storage area provided for the context bundle.- Specified by:
getDataFile
in interfaceBundleContext
- Parameters:
s
- A relative name to the file to be accessed.- Returns:
- A
File
object that represents the requested file ornull
if the platform does not have file system support.
-
checkValidity
private void checkValidity()
-
registerService
public <S> ServiceRegistration<S> registerService(java.lang.Class<S> clazz, ServiceFactory<S> factory, java.util.Dictionary<java.lang.String,?> properties)
Description copied from interface:BundleContext
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
BundleContext.registerService(Class, Object, Dictionary)
and is provided to return a type safeServiceRegistration
when registering aServiceFactory
.- Specified by:
registerService
in interfaceBundleContext
- Type Parameters:
S
- Type of Service.- Parameters:
clazz
- The class under whose name the service can be located.factory
- TheServiceFactory
object.properties
- The properties for this service.- Returns:
- A
ServiceRegistration
object for use by the bundle registering the service to update the service's properties or to unregister the service. - See Also:
BundleContext.registerService(java.lang.Class, org.osgi.framework.ServiceFactory, java.util.Dictionary)
-
getServiceObjects
public <S> ServiceObjects<S> getServiceObjects(ServiceReference<S> ref)
Description copied from interface:BundleContext
Returns theServiceObjects
object for the service referenced by the specifiedServiceReference
object.The
ServiceObjects
object can be used to obtain multiple service objects for services withprototype
scope.For services with
singleton
orbundle
scope, theServiceObjects.getService()
method behaves the same as theBundleContext.getService(ServiceReference)
method and theServiceObjects.ungetService(Object)
method behaves the same as theBundleContext.ungetService(ServiceReference)
method. That is, only one, use-counted service object is available from theServiceObjects
object.This method will always return
null
when the service associated with the specifiedreference
has been unregistered.- Specified by:
getServiceObjects
in interfaceBundleContext
- Type Parameters:
S
- Type of Service.- Parameters:
ref
- A reference to the service.- Returns:
- A
ServiceObjects
object for the service associated with the specifiedreference
ornull
if the service is not registered. - See Also:
BundleContext.getServiceObjects(org.osgi.framework.ServiceReference)
-
-