org.apache.felix.ipojo.util

## Class Tracker

- java.lang.Object
- - org.apache.felix.ipojo.util.Tracker

All Implemented Interfaces:
  TrackerCustomizer

    public class Tracker
    extends java.lang.Object
    implements TrackerCustomizer

Utility class close to the OSGi Service Tracker. This class is used when tracking dynamic services is required.

Author:
  Felix Project Team

### Field Summary

Fields
`protected org.osgi.framework.BundleContext` `m_context` The bundle context against which this Tracker object is tracking.
`protected TrackerCustomizer` `m_customizer` The TrackerCustomizer object for this tracker.
`protected org.osgi.framework.Filter` `m_filter` the filter specifying search criteria for the services to track.
`protected java.lang.String` `m_listenerFilter` The filter string for use when adding the ServiceListener.

### Constructor Summary

Constructors
Constructor and Description
`Tracker(org.osgi.framework.BundleContext context, org.osgi.framework.Filter filter, TrackerCustomizer customizer)` Creates a Tracker object on the specified Filter object.
`Tracker(org.osgi.framework.BundleContext context, org.osgi.framework.ServiceReference reference, TrackerCustomizer customizer)` Creates a Tracker object on the specified ServiceReference object.
`Tracker(org.osgi.framework.BundleContext context, java.lang.String clazz, TrackerCustomizer customizer)` Creates a Tracker object on the specified class name.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addedService(org.osgi.framework.ServiceReference reference)` Default implementation of the TrackerCustomizer.addedService method.
`boolean` `addingService(org.osgi.framework.ServiceReference reference)` Default implementation of the TrackerCustomizer.addingService method.
`void` `close()` Closes this Tracker object.
`java.lang.Object` `getService()` Returns a service object for one of the services being tracked by this Tracker object.
`java.lang.Object` `getService(org.osgi.framework.ServiceReference reference)` Returns the service object for the specified ServiceReference object if the referenced service is being tracked by this Tracker object.
`org.osgi.framework.ServiceReference` `getServiceReference()` Returns a ServiceReference object for one of the services being tracked by this Tracker object.
`org.osgi.framework.ServiceReference[]` `getServiceReferences()` Returns an array of ServiceReference objects for all services being tracked by this Tracker object.
`java.util.List<org.osgi.framework.ServiceReference>` `getServiceReferencesList()` Gets the list of stored service references.
`java.lang.Object[]` `getServices()` Returns an array of service objects for all services being tracked by this Tracker object.
`java.util.List<org.osgi.framework.ServiceReference>` `getUsedServiceReferences()` Returns the list of references used by the tracker.
`void` `modifiedService(org.osgi.framework.ServiceReference reference, java.lang.Object service)` Default implementation of the TrackerCustomizer.modifiedService method.
`void` `open()` Opens this Tracker object and begin tracking services.
`void` `remove(org.osgi.framework.ServiceReference reference)` Removes a service from this Tracker object.
`void` `removedService(org.osgi.framework.ServiceReference reference, java.lang.Object service)` Default implementation of the TrackerCustomizer.removedService method.
`int` `size()` Returns the number of services being tracked by this Tracker object.
`void` `ungetService(org.osgi.framework.ServiceReference reference)` Ungets the given service reference.
`java.lang.Object` `waitForService(long timeout)` Waits for at least one service to be tracked by this Tracker object.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### m_context

    protected org.osgi.framework.BundleContext m_context

The bundle context against which this Tracker object is tracking.

#### m_filter

    protected org.osgi.framework.Filter m_filter

the filter specifying search criteria for the services to track.

#### m_customizer

    protected TrackerCustomizer m_customizer

The TrackerCustomizer object for this tracker.

#### m_listenerFilter

    protected java.lang.String m_listenerFilter

The 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.

### Constructor Detail

#### Tracker

    public Tracker(org.osgi.framework.BundleContext context,
                   org.osgi.framework.ServiceReference reference,
                   TrackerCustomizer customizer)

Creates a Tracker object on the specified ServiceReference object. The service referenced by the specified ServiceReference object will be tracked by this Tracker.

Parameters:
  `context` - The BundleContext object against which the tracking is done.
  `reference` - The ServiceReference object for the service to be tracked.
  `customizer` - The customizer object to call when services are added, modified, or removed in this Tracker object. If customizer is null, then this Tracker object will be used as the TrackerCustomizer object and the Tracker object will call the TrackerCustomizer methods on itself.

#### Tracker

    public Tracker(org.osgi.framework.BundleContext context,
                   java.lang.String clazz,
                   TrackerCustomizer customizer)

Creates a Tracker object on the specified class name. Services registered under the specified class name will be tracked by this Tracker object.

Parameters:
  `context` - the BundleContext object against which the tracking is done.
  `clazz` - the Class name of the services to be tracked.
  `customizer` - the customizer object to call when services are added, modified, or removed in this Tracker object. If customizer is null, then this Tracker object will be used as the TrackerCustomizer object and the Tracker object will call the TrackerCustomizer methods on itself.

#### Tracker

    public Tracker(org.osgi.framework.BundleContext context,
                   org.osgi.framework.Filter filter,
                   TrackerCustomizer customizer)

Creates a Tracker object on the specified Filter object.

Services which match the specified Filter object will be tracked by this Tracker object.

Parameters:
  `context` - the BundleContext object against which the tracking is done.
  `filter` - the Filter object to select the services to be tracked.
  `customizer` - The customizer object to call when services are added, modified, or removed in this Tracker object. If customizer is null, then this Tracker object will be used as the TrackerCustomizer object and the Tracker object will call the TrackerCustomizer methods on itself.

### Method Detail

#### open

    public void open()

Opens this Tracker object and begin tracking services.

Services which match the search criteria specified when this Tracker object was created are now tracked by this Tracker object.

#### close

    public void close()

Closes this Tracker object.

This method should be called when this Tracker object should end the tracking of services.

#### addingService

    public boolean addingService(org.osgi.framework.ServiceReference reference)

Default implementation of the TrackerCustomizer.addingService method.

This method is only called when this Tracker object has been constructed with a null TrackerCustomizer argument. The default implementation returns the result of calling getService, on the BundleContext object with which this Tracker 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.

Specified by:
  `addingService` in interface `TrackerCustomizer`
Parameters:
  `reference` - the Reference to service being added to this Tracker object.
Returns:
  The service object to be tracked for the service added to this Tracker object.
See Also:
  `TrackerCustomizer`

#### addedService

    public void addedService(org.osgi.framework.ServiceReference reference)

Default implementation of the TrackerCustomizer.addedService method.

Specified by:
  `addedService` in interface `TrackerCustomizer`
Parameters:
  `reference` - the added reference.
See Also:
  `TrackerCustomizer.addedService(org.osgi.framework.ServiceReference)`

#### modifiedService

    public void modifiedService(org.osgi.framework.ServiceReference reference,
                                java.lang.Object service)

Default implementation of the TrackerCustomizer.modifiedService method.

This method is only called when this Tracker object has been constructed with a null TrackerCustomizer argument. The default implementation does nothing.

Specified by:
  `modifiedService` in interface `TrackerCustomizer`
Parameters:
  `reference` - the Reference to modified service.
  `service` - The service object for the modified service.
See Also:
  `TrackerCustomizer`

#### removedService

    public void removedService(org.osgi.framework.ServiceReference reference,
                               java.lang.Object service)

Default implementation of the TrackerCustomizer.removedService method.

This method is only called when this Tracker object has been constructed with a null TrackerCustomizer argument. The default implementation calls ungetService, on the BundleContext object with which this Tracker 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.

Specified by:
  `removedService` in interface `TrackerCustomizer`
Parameters:
  `reference` - the Reference to removed service.
  `service` - The service object for the removed service.
See Also:
  `TrackerCustomizer`

#### waitForService

    public java.lang.Object waitForService(long timeout)
                                    throws java.lang.InterruptedException

Waits for at least one service to be tracked by this Tracker 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.

Parameters:
  `timeout` - the time interval in milliseconds to wait. If zero, the method will wait indefinately.
Returns:
  Returns the result of getService().
Throws:
  `java.lang.InterruptedException` - If another thread has interrupted the current thread.

#### getServiceReferences

    public org.osgi.framework.ServiceReference[] getServiceReferences()

Returns an array of ServiceReference objects for all services being tracked by this Tracker object.

Returns:
  Array of ServiceReference objects or `null` if no service are being tracked.

#### getServiceReferencesList

    public java.util.List<org.osgi.framework.ServiceReference> getServiceReferencesList()

Gets the list of stored service references.

Returns:
  the list containing service references

#### getUsedServiceReferences

    public java.util.List<org.osgi.framework.ServiceReference> getUsedServiceReferences()

Returns the list of references used by the tracker. A reference becomes used when the dependency has already called getService on this reference.

Returns:
  the list of used references.

#### getServiceReference

    public org.osgi.framework.ServiceReference getServiceReference()

Returns a ServiceReference object for one of the services being tracked by this Tracker 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.

Returns:
  ServiceReference object or null if no service is being tracked.
Since:
  1.1

#### getService

    public java.lang.Object getService(org.osgi.framework.ServiceReference reference)

Returns the service object for the specified ServiceReference object if the referenced service is being tracked by this Tracker object.

Parameters:
  `reference` - the Reference to the desired service.
Returns:
  the Service object. Try to get the service if not yet tracked.

#### ungetService

    public void ungetService(org.osgi.framework.ServiceReference reference)

Ungets the given service reference.

Parameters:
  `reference` - the service reference to unget.

#### getServices

    public java.lang.Object[] getServices()

Returns an array of service objects for all services being tracked by this Tracker object.

Returns:
  Array of service objects or `null` if no service are being tracked.

#### getService

    public java.lang.Object getService()

Returns a service object for one of the services being tracked by this Tracker object.

If any services are being tracked, this method returns the result of calling getService(getServiceReference()).

Returns:
  Service object or `null` if no service is being tracked.

#### remove

    public void remove(org.osgi.framework.ServiceReference reference)

Removes a service from this Tracker object. The specified service will be removed from this Tracker object. If the specified service was being tracked then the TrackerCustomizer.removedService method will be called for that service.

Parameters:
  `reference` - the Reference to the service to be removed.

#### size

    public int size()

Returns the number of services being tracked by this Tracker object.

Returns:
  the Number of services being tracked.