ServiceTracker
class simplifies using services from the Framework's service registry.
A ServiceTracker
object is constructed with search criteria and a ServiceTrackerCustomizer
object. A ServiceTracker
object can use the ServiceTrackerCustomizer
object to customize the service objects to be tracked. The ServiceTracker
object can then be opened to begin tracking all services in the Framework's service registry that match the specified search criteria. The ServiceTracker
object correctly handles all of the details of listening to ServiceEvent
objects and getting and ungetting services.
The getServiceReferences
method can be called to get references to the services being tracked. The getService
and getServices
methods can be called to get the service objects for the tracked service.
Definition at line 46 of file ServiceTracker.java.
Public Member Functions | |
ServiceTracker (BundleContext context, ServiceReference reference, ServiceTrackerCustomizer customizer) | |
Create a ServiceTracker object on the specified ServiceReference object. | |
ServiceTracker (BundleContext context, String clazz, ServiceTrackerCustomizer customizer) | |
Create a ServiceTracker object on the specified class name. | |
ServiceTracker (BundleContext context, Filter filter, ServiceTrackerCustomizer customizer) | |
Create a ServiceTracker object on the specified Filter object. | |
void | open () |
Open this ServiceTracker object and begin tracking services. | |
synchronized void | open (boolean trackAllServices) |
Open this ServiceTracker object and begin tracking services. | |
synchronized void | close () |
Close this ServiceTracker object. | |
Object | addingService (ServiceReference reference) |
Default implementation of the ServiceTrackerCustomizer.addingService method. | |
void | modifiedService (ServiceReference reference, Object service) |
Default implementation of the ServiceTrackerCustomizer.modifiedService method. | |
void | removedService (ServiceReference reference, Object service) |
Default implementation of the ServiceTrackerCustomizer.removedService method. | |
Object | waitForService (long timeout) throws InterruptedException |
Wait for at least one service to be tracked by this ServiceTracker object. | |
ServiceReference[] | getServiceReferences () |
Return an array of ServiceReference objects for all services being tracked by this ServiceTracker object. | |
ServiceReference | getServiceReference () |
Returns a ServiceReference object for one of the services being tracked by this ServiceTracker object. | |
Object | getService (ServiceReference reference) |
Returns the service object for the specified ServiceReference object if the referenced service is being tracked by this ServiceTracker object. | |
Object[] | getServices () |
Return an array of service objects for all services being tracked by this ServiceTracker object. | |
Object | getService () |
Returns a service object for one of the services being tracked by this ServiceTracker object. | |
void | remove (ServiceReference reference) |
Remove a service from this ServiceTracker object. | |
int | size () |
Return the number of services being tracked by this ServiceTracker object. | |
int | getTrackingCount () |
Returns the tracking count for this ServiceTracker object. | |
Protected Member Functions | |
void | finalize () throws Throwable |
Finalize. | |
Protected Attributes | |
final BundleContext | context |
Bundle context this ServiceTracker object is tracking against. | |
final Filter | filter |
Filter specifying search criteria for the services to track. | |
Package Functions | |
void | modified () |
Called by the Tracked object whenever the set of tracked services is modified. | |
Package Attributes | |
final ServiceTrackerCustomizer | customizer |
ServiceTrackerCustomizer object for this tracker. | |
final String | listenerFilter |
Filter string for use when adding the ServiceListener. | |
Classes | |
class | AllTracked |
Subclass of Tracked which implements the AllServiceListener interface. More... | |
class | Tracked |
Inner class to track services. More... |
org.osgi.util.tracker.ServiceTracker.ServiceTracker | ( | BundleContext | context, | |
ServiceReference | reference, | |||
ServiceTrackerCustomizer | customizer | |||
) |
Create a ServiceTracker
object on the specified ServiceReference
object.
The service referenced by the specified ServiceReference
object will be tracked by this ServiceTracker
object.
context | BundleContext object against which the tracking is done. | |
reference | ServiceReference object for the service to be tracked. | |
customizer | The customizer object to call when services are added, modified, or removed in this ServiceTracker object. If customizer is null , then this ServiceTracker object will be used as the ServiceTrackerCustomizer object and the ServiceTracker object will call the ServiceTrackerCustomizer methods on itself. |
Definition at line 125 of file ServiceTracker.java.
References org.osgi.framework.BundleContext.createFilter(), org.osgi.framework.ServiceReference.getProperty(), and org.osgi.util.tracker.ServiceTracker.listenerFilter.
org.osgi.util.tracker.ServiceTracker.ServiceTracker | ( | BundleContext | context, | |
String | clazz, | |||
ServiceTrackerCustomizer | customizer | |||
) |
Create a ServiceTracker
object on the specified class name.
Services registered under the specified class name will be tracked by this ServiceTracker
object.
context | BundleContext object against which the tracking is done. | |
clazz | Class name of the services to be tracked. | |
customizer | The customizer object to call when services are added, modified, or removed in this ServiceTracker object. If customizer is null , then this ServiceTracker object will be used as the ServiceTrackerCustomizer object and the ServiceTracker object will call the ServiceTrackerCustomizer methods on itself. |
Definition at line 162 of file ServiceTracker.java.
References org.osgi.framework.BundleContext.createFilter(), and org.osgi.util.tracker.ServiceTracker.listenerFilter.
org.osgi.util.tracker.ServiceTracker.ServiceTracker | ( | BundleContext | context, | |
Filter | filter, | |||
ServiceTrackerCustomizer | customizer | |||
) |
Create a ServiceTracker
object on the specified Filter
object.
Services which match the specified Filter
object will be tracked by this ServiceTracker
object.
context | BundleContext object against which the tracking is done. | |
filter | Filter object to select the services to be tracked. | |
customizer | The customizer object to call when services are added, modified, or removed in this ServiceTracker object. If customizer is null, then this ServiceTracker object will be used as the ServiceTrackerCustomizer object and the ServiceTracker object will call the ServiceTrackerCustomizer methods on itself. |
Definition at line 200 of file ServiceTracker.java.
void org.osgi.util.tracker.ServiceTracker.open | ( | ) |
Open this ServiceTracker
object and begin tracking services.
This method calls open(false)
.
java.lang.IllegalStateException | if the BundleContext object with which this ServiceTracker object was created is no longer valid. |
Definition at line 228 of file ServiceTracker.java.
Referenced by org.openmobileis.bundle.osgi.synchro.BaseBundleLoaderActivator.start().
synchronized void org.osgi.util.tracker.ServiceTracker.open | ( | boolean | trackAllServices | ) |
Open this ServiceTracker
object and begin tracking services.
Services which match the search criteria specified when this ServiceTracker
object was created are now tracked by this ServiceTracker
object.
trackAllServices | If true , then this ServiceTracker will track all matching services regardless of class loader accessibility. If false , then this ServiceTracker will only track matching services which are class loader accessibile to the bundle whose BundleContext is used by this ServiceTracker . |
java.lang.IllegalStateException | if the BundleContext object with which this ServiceTracker object was created is no longer valid. |
Definition at line 253 of file ServiceTracker.java.
References org.osgi.framework.BundleContext.addServiceListener(), org.osgi.util.tracker.ServiceTracker.context, org.osgi.util.tracker.ServiceTracker.filter, org.osgi.util.tracker.ServiceTracker.listenerFilter, org.osgi.util.tracker.ServiceTracker.Tracked.setInitialServices(), org.osgi.framework.Filter.toString(), and org.osgi.util.tracker.ServiceTracker.Tracked.trackInitialServices().
synchronized void org.osgi.util.tracker.ServiceTracker.close | ( | ) |
Close this ServiceTracker
object.
This method should be called when this ServiceTracker
object should end the tracking of services.
Definition at line 322 of file ServiceTracker.java.
References org.osgi.util.tracker.ServiceTracker.Tracked.close(), org.osgi.util.tracker.ServiceTracker.context, org.osgi.util.tracker.ServiceTracker.filter, org.osgi.util.tracker.ServiceTracker.getServiceReferences(), org.osgi.framework.BundleContext.removeServiceListener(), and org.osgi.util.tracker.ServiceTracker.Tracked.untrack().
Object org.osgi.util.tracker.ServiceTracker.addingService | ( | ServiceReference | reference | ) |
Default implementation of the ServiceTrackerCustomizer.addingService
method.
This method is only called when this ServiceTracker
object has been constructed with a null ServiceTrackerCustomizer
argument.
The default implementation returns the result of calling getService
, on the BundleContext
object with which this ServiceTracker
object was created, passing the specified ServiceReference
object.
This method can be overridden in a subclass to customize the service object to be tracked for the service being added. In that case, take care not to rely on the default implementation of removedService that will unget the service.
reference | Reference to service being added to this ServiceTracker object. |
ServiceTracker
object. Implements org.osgi.util.tracker.ServiceTrackerCustomizer.
Definition at line 378 of file ServiceTracker.java.
References org.osgi.util.tracker.ServiceTracker.context, and org.osgi.framework.BundleContext.getService().
void org.osgi.util.tracker.ServiceTracker.modifiedService | ( | ServiceReference | reference, | |
Object | service | |||
) |
Default implementation of the ServiceTrackerCustomizer.modifiedService
method.
This method is only called when this ServiceTracker
object has been constructed with a null ServiceTrackerCustomizer
argument.
The default implementation does nothing.
reference | Reference to modified service. | |
service | The service object for the modified service. |
Implements org.osgi.util.tracker.ServiceTrackerCustomizer.
Definition at line 397 of file ServiceTracker.java.
void org.osgi.util.tracker.ServiceTracker.removedService | ( | ServiceReference | reference, | |
Object | service | |||
) |
Default implementation of the ServiceTrackerCustomizer.removedService
method.
This method is only called when this ServiceTracker
object has been constructed with a null ServiceTrackerCustomizer
argument.
The default implementation calls ungetService
, on the BundleContext
object with which this ServiceTracker
object was created, passing the specified ServiceReference
object.
This method can be overridden in a subclass. If the default implementation of addingService
method was used, this method must unget the service.
reference | Reference to removed service. | |
service | The service object for the removed service. |
Implements org.osgi.util.tracker.ServiceTrackerCustomizer.
Definition at line 422 of file ServiceTracker.java.
References org.osgi.util.tracker.ServiceTracker.context, and org.osgi.framework.BundleContext.ungetService().
Object org.osgi.util.tracker.ServiceTracker.waitForService | ( | long | timeout | ) | throws InterruptedException |
Wait for at least one service to be tracked by this ServiceTracker
object.
It is strongly recommended that waitForService
is not used during the calling of the BundleActivator
methods. BundleActivator
methods are expected to complete in a short period of time.
timeout | time interval in milliseconds to wait. If zero, the method will wait indefinately. |
getService()
. InterruptedException | If another thread has interrupted the current thread. | |
IllegalArgumentException | If the value of timeout is negative. |
Definition at line 442 of file ServiceTracker.java.
References org.osgi.util.tracker.ServiceTracker.getService().
ServiceReference [] org.osgi.util.tracker.ServiceTracker.getServiceReferences | ( | ) |
Return an array of ServiceReference
objects for all services being tracked by this ServiceTracker
object.
ServiceReference
objects or null
if no service are being tracked. Definition at line 475 of file ServiceTracker.java.
Referenced by org.osgi.util.tracker.ServiceTracker.close(), org.osgi.util.tracker.ServiceTracker.getServiceReference(), and org.osgi.util.tracker.ServiceTracker.getServices().
ServiceReference org.osgi.util.tracker.ServiceTracker.getServiceReference | ( | ) |
Returns a ServiceReference
object for one of the services being tracked by this ServiceTracker
object.
If multiple services are being tracked, the service with the highest ranking (as specified in its service.ranking
property) is returned.
If there is a tie in ranking, the service with the lowest service ID (as specified in its service.id
property); that is, the service that was registered first is returned.
This is the same algorithm used by BundleContext.getServiceReference
.
ServiceReference
object or null
if no service is being tracked. Definition at line 518 of file ServiceTracker.java.
References org.osgi.util.tracker.ServiceTracker.filter, org.osgi.framework.ServiceReference.getProperty(), and org.osgi.util.tracker.ServiceTracker.getServiceReferences().
Referenced by org.osgi.util.tracker.ServiceTracker.getService().
Object org.osgi.util.tracker.ServiceTracker.getService | ( | ServiceReference | reference | ) |
Returns the service object for the specified ServiceReference
object if the referenced service is being tracked by this ServiceTracker
object.
reference | Reference to the desired service. |
null
if the service referenced by the specified ServiceReference
object is not being tracked. Definition at line 589 of file ServiceTracker.java.
Object [] org.osgi.util.tracker.ServiceTracker.getServices | ( | ) |
Return an array of service objects for all services being tracked by this ServiceTracker
object.
null
if no service are being tracked. Definition at line 609 of file ServiceTracker.java.
References org.osgi.util.tracker.ServiceTracker.getService(), and org.osgi.util.tracker.ServiceTracker.getServiceReferences().
Object org.osgi.util.tracker.ServiceTracker.getService | ( | ) |
Returns a service object for one of the services being tracked by this ServiceTracker
object.
If any services are being tracked, this method returns the result of calling getService(getServiceReference())
.
null
if no service is being tracked. Definition at line 642 of file ServiceTracker.java.
References org.osgi.util.tracker.ServiceTracker.filter, and org.osgi.util.tracker.ServiceTracker.getServiceReference().
Referenced by org.osgi.util.tracker.ServiceTracker.getServices(), and org.osgi.util.tracker.ServiceTracker.waitForService().
void org.osgi.util.tracker.ServiceTracker.remove | ( | ServiceReference | reference | ) |
Remove a service from this ServiceTracker
object.
The specified service will be removed from this ServiceTracker
object. If the specified service was being tracked then the ServiceTrackerCustomizer.removedService
method will be called for that service.
reference | Reference to the service to be removed. |
Definition at line 671 of file ServiceTracker.java.
References org.osgi.util.tracker.ServiceTracker.Tracked.untrack().
int org.osgi.util.tracker.ServiceTracker.size | ( | ) |
Return the number of services being tracked by this ServiceTracker
object.
Definition at line 688 of file ServiceTracker.java.
Referenced by org.osgi.util.tracker.ServiceTracker.Tracked.setInitialServices().
int org.osgi.util.tracker.ServiceTracker.getTrackingCount | ( | ) |
Returns the tracking count for this ServiceTracker
object.
The tracking count is initialized to 0 when this ServiceTracker
object is opened. Every time a service is added or removed from this ServiceTracker
object the tracking count is incremented.
The tracking count can be used to determine if this ServiceTracker
object has added or removed a service by comparing a tracking count value previously collected with the current tracking count value. If the value has not changed, then no service has been added or removed from this ServiceTracker
object since the previous tracking count was collected.
ServiceTracker
object or -1 if this ServiceTracker
object is not open. Definition at line 719 of file ServiceTracker.java.
void org.osgi.util.tracker.ServiceTracker.modified | ( | ) | [package] |
Called by the Tracked object whenever the set of tracked services is modified.
Increments the tracking count and clears the cache.
Definition at line 732 of file ServiceTracker.java.
References org.osgi.util.tracker.ServiceTracker.filter.
Referenced by org.osgi.util.tracker.ServiceTracker.Tracked.track(), and org.osgi.util.tracker.ServiceTracker.Tracked.untrack().
void org.osgi.util.tracker.ServiceTracker.finalize | ( | ) | throws Throwable [protected] |
Finalize.
This method no longer performs any function but it kept to maintain binary compatibility with prior versions of this class.
Definition at line 745 of file ServiceTracker.java.
final Filter org.osgi.util.tracker.ServiceTracker.filter [protected] |
Filter specifying search criteria for the services to track.
Definition at line 59 of file ServiceTracker.java.
Referenced by org.osgi.util.tracker.ServiceTracker.close(), org.osgi.util.tracker.ServiceTracker.getService(), org.osgi.util.tracker.ServiceTracker.getServiceReference(), org.osgi.util.tracker.ServiceTracker.modified(), org.osgi.util.tracker.ServiceTracker.open(), and org.osgi.util.tracker.ServiceTracker.Tracked.serviceChanged().
final String org.osgi.util.tracker.ServiceTracker.listenerFilter [package] |
Filter string for use when adding the ServiceListener.
If this field is set, then certain optimizations can be taken since we don't have a user supplied filter.
Definition at line 69 of file ServiceTracker.java.
Referenced by org.osgi.util.tracker.ServiceTracker.open(), org.osgi.util.tracker.ServiceTracker.Tracked.serviceChanged(), and org.osgi.util.tracker.ServiceTracker.ServiceTracker().