ServiceTracker¶

template <class S, class T = S>

class cppmicroservices::ServiceTracker¶

#include <cppmicroservices/ServiceTracker.h>

The 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 can use a ServiceTrackerCustomizer to customize the service objects to be tracked. The ServiceTracker can then be opened to begin tracking all services in the framework’s service registry that match the specified search criteria. The ServiceTracker correctly handles all of the details of listening to ServiceEvents 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.

Customization of the services to be tracked requires the tracked type to be default constructible and convertible to bool. To customize a tracked service using a custom type with value-semantics like

struct MyTrackedClass
{
  explicit operator bool() const { return true; }
  /* ... */
};

a custom ServiceTrackerCustomizer is required. It provides code to associate the tracked service with the custom tracked type:

struct MyTrackingCustomizer
  : public ServiceTrackerCustomizer<IFooService, MyTrackedClass>
{
  virtual std::shared_ptr<MyTrackedClass> AddingService(
    const ServiceReference<IFooService>&)
  {
    return std::shared_ptr<MyTrackedClass>();
  }

  virtual void ModifiedService(const ServiceReference<IFooService>&,
                               const std::shared_ptr<MyTrackedClass>&)
  {}

  virtual void RemovedService(const ServiceReference<IFooService>&,
                              const std::shared_ptr<MyTrackedClass>&)
  {}
};

Instantiation of a ServiceTracker with the custom customizer looks like this:

    MyTrackingCustomizer myCustomizer;
    ServiceTracker<IFooService, MyTrackedClass> tracker(GetBundleContext(),
                                                        &myCustomizer);

Note

The ServiceTracker class is thread-safe. It does not call a ServiceTrackerCustomizer while holding any locks. ServiceTrackerCustomizer implementations must also be thread-safe.

Remark

This class is thread safe.

Template Parameters

S: The type of the service being tracked. The type S* must be an assignable datatype.
T: The tracked object.

Inherits from cppmicroservices::ServiceTrackerCustomizer< S, T >

Public Types

template<> using TrackedParamType = typename ServiceTrackerCustomizer::TrackedParamType¶: The type of the tracked object.

template<> using TrackingMap = std::unordered_map<ServiceReference<S>, std::shared_ptr<TrackedParamType>>¶

Public Functions

~ServiceTracker()¶: Automatically closes the ServiceTracker

ServiceTracker(const BundleContext &context, const ServiceReference<S> &reference, ServiceTrackerCustomizer<S, T> *customizer = nullptr)¶

Create a ServiceTracker on the specified ServiceReference.

The service referenced by the specified ServiceReference will be tracked by this ServiceTracker.

Parameters

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

ServiceTracker(const BundleContext &context, const std::string &clazz, ServiceTrackerCustomizer<S, T> *customizer = nullptr)¶

Create a ServiceTracker on the specified class name.

Services registered under the specified class name will be tracked by this ServiceTracker.

Parameters

context: The BundleContext 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 ServiceTracker. If customizer is null, then this ServiceTracker will be used as the ServiceTrackerCustomizer and this ServiceTracker will call the ServiceTrackerCustomizer methods on itself.

ServiceTracker(const BundleContext &context, const LDAPFilter &filter, ServiceTrackerCustomizer<S, T> *customizer = nullptr)¶

Create a ServiceTracker on the specified LDAPFilter object.

Services which match the specified LDAPFilter object will be tracked by this ServiceTracker.

Parameters

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

ServiceTracker(const BundleContext &context, ServiceTrackerCustomizer<S, T> *customizer = nullptr)¶

Create a ServiceTracker on the class template argument S.

Services registered under the interface name of the class template argument S will be tracked by this ServiceTracker.

Parameters

context: The BundleContext against which the tracking is done.
customizer: The customizer object to call when services are added, modified, or removed in this ServiceTracker. If customizer is null, then this ServiceTracker will be used as the ServiceTrackerCustomizer and this ServiceTracker will call the ServiceTrackerCustomizer methods on itself.

Exceptions

ServiceException: If the service interface name is empty.

virtual void Open()¶

Open this ServiceTracker and begin tracking services.

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

Exceptions

std::runtime_error: If the BundleContext with which this ServiceTracker was created is no longer valid.
std::runtime_error: If the LDAP filter used to construct the ServiceTracker contains an invalid filter expression that cannot be parsed.

virtual void Close()¶

Close this ServiceTracker.

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

This implementation calls GetServiceReferences() to get the list of tracked services to remove.

Exceptions

std::runtime_error: If the BundleContext with which this ServiceTracker was created is no longer valid.

std::shared_ptr<TrackedParamType> WaitForService()¶

Wait for at least one service to be tracked by this ServiceTracker.

This method will also return when this ServiceTracker is closed.

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.

This implementation calls GetService() to determine if a service is being tracked.

Return: The result of GetService().

template <class Rep, class Period>

std::shared_ptr<TrackedParamType> WaitForService(const std::chrono::duration<Rep, Period> &rel_time)¶

Wait for at least one service to be tracked by this ServiceTracker.

This method will also return when this ServiceTracker is closed.

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.

This implementation calls GetService() to determine if a service is being tracked.

Return

The result of GetService().

Parameters

rel_time: The relative time duration to wait for a service. If zero, the method will wait indefinitely.

Exceptions

std::invalid_argument: exception if rel_time is negative.

virtual std::vector<ServiceReference<S>> GetServiceReferences() const¶

Return a list of ServiceReferences for all services being tracked by this ServiceTracker.

Return: A list of ServiceReference objects.

virtual ServiceReference<S> GetServiceReference() const¶

Returns a ServiceReference for one of the services being tracked by this ServiceTracker.

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().

This implementation calls GetServiceReferences() to get the list of references for the tracked services.

Return

A ServiceReference for a tracked service.

Exceptions

ServiceException: if no services are being tracked.

virtual std::shared_ptr<TrackedParamType> GetService(const ServiceReference<S> &reference) const¶

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

Return

A service object or nullptr if the service referenced by the specified ServiceReference is not being tracked.

Parameters

reference: The reference to the desired service.

virtual std::vector<std::shared_ptr<TrackedParamType>> GetServices() const¶

Return a list of service objects for all services being tracked by this ServiceTracker.

This implementation calls GetServiceReferences() to get the list of references for the tracked services and then calls GetService(const ServiceReference&) for each reference to get the tracked service object.

Return: A list of service objects or an empty list if no services are being tracked.

virtual std::shared_ptr<TrackedParamType> GetService() const¶

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

If any services are being tracked, this implementation returns the result of calling GetService(GetServiceReference()).

Return: A service object or null if no services are being tracked.

virtual void Remove(const ServiceReference<S> &reference)¶

Remove a service from this ServiceTracker.

The specified service will be removed from this ServiceTracker. If the specified service was being tracked then the ServiceTrackerCustomizer::RemovedService method will be called for that service.

Parameters

reference: The reference to the service to be removed.

virtual int Size() const¶

Return the number of services being tracked by this ServiceTracker.

Return: The number of services being tracked.

virtual int GetTrackingCount() const¶

Returns the tracking count for this ServiceTracker.

The tracking count is initialized to 0 when this ServiceTracker is opened. Every time a service is added, modified or removed from this ServiceTracker, the tracking count is incremented.

The tracking count can be used to determine if this ServiceTracker has added, modified 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, modified or removed from this ServiceTracker since the previous tracking count was collected.

Return: The tracking count for this ServiceTracker or -1 if this ServiceTracker is not open.

virtual void GetTracked(TrackingMap &tracked) const¶

Return a sorted map of the ServiceReferences and service objects for all services being tracked by this ServiceTracker.

The map is sorted in natural order of ServiceReference. That is, the last entry is the service with the highest ranking and the lowest service id.

Parameters

tracked: A TrackingMap with the ServiceReferences and service objects for all services being tracked by this ServiceTracker. If no services are being tracked, then the returned map is empty.

virtual bool IsEmpty() const¶

Return if this ServiceTracker is empty.

Return: true if this ServiceTracker is not tracking any services.

Protected Functions

std::shared_ptr<TrackedParamType> AddingService(const ServiceReference<S> &reference)¶

Default implementation of the ServiceTrackerCustomizer::AddingService method.

This method is only called when this ServiceTracker has been constructed with a nullptr ServiceTrackerCustomizer argument.

This implementation returns the result of calling GetService on the BundleContext with which this ServiceTracker was created passing the specified ServiceReference.

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 to unget the service.

Return

The service object to be tracked for the service added to this ServiceTracker.

See

ServiceTrackerCustomizer::AddingService(const ServiceReference&)

Parameters

reference: The reference to the service being added to this ServiceTracker.

Exceptions

std::runtime_error: If this BundleContext is no longer valid.
std::invalid_argument: If the specified ServiceReference is invalid (default constructed).

void ModifiedService(const ServiceReference<S> &reference, const std::shared_ptr<TrackedParamType> &service)¶

Default implementation of the ServiceTrackerCustomizer::ModifiedService method.

This method is only called when this ServiceTracker has been constructed with a nullptr ServiceTrackerCustomizer argument.

This implementation does nothing.

See

ServiceTrackerCustomizer::ModifiedService(const ServiceReference&, TrackedArgType)

Parameters

reference: The reference to modified service.
service: The service object for the modified service.

void RemovedService(const ServiceReference<S> &reference, const std::shared_ptr<TrackedParamType> &service)¶

Default implementation of the ServiceTrackerCustomizer::RemovedService method.

This method is only called when this ServiceTracker has been constructed with a nullptr ServiceTrackerCustomizer argument.

This method can be overridden in a subclass. If the default implementation of the AddingService method was used, this method must unget the service.

See

ServiceTrackerCustomizer::RemovedService(const ServiceReferenceType&, TrackedArgType)

Parameters

reference: The reference to removed service.
service: The service object for the removed service.

template <class S, class T = S>

struct cppmicroservices::ServiceTrackerCustomizer¶

#include <cppmicroservices/ServiceTrackerCustomizer.h>

The ServiceTrackerCustomizer interface allows a ServiceTracker to customize the service objects that are tracked.

A ServiceTrackerCustomizer is called when a service is being added to a ServiceTracker. The ServiceTrackerCustomizer can then return an object for the tracked service. A ServiceTrackerCustomizer is also called when a tracked service is modified or has been removed from a ServiceTracker.

The methods in this interface may be called as the result of a ServiceEvent being received by a ServiceTracker. Since ServiceEvents are synchronously delivered, it is highly recommended that implementations of these methods do not register (BundleContext::RegisterService), modify ( ServiceRegistration::SetProperties) or unregister ( ServiceRegistration::Unregister) a service while being synchronized on any object.

Note

The ServiceTracker class implementation of ServiceTrackerCustomizer is thread-safe. It does not call a ServiceTrackerCustomizer while holding any locks. ServiceTrackerCustomizer implementations must also be thread-safe.

Remark

ServiceTrackerCustomizer implementations must also be thread-safe.

Template Parameters

S: The type of the service being tracked
T: The type of the tracked object. The default is S.

Subclassed by cppmicroservices::ServiceTracker< S, T >

Public Types

template<> using TrackedParamType = typename TypeTraits::TrackedParamType ¶

Public Functions

virtual ~ServiceTrackerCustomizer()¶

virtual std::shared_ptr<TrackedParamType> AddingService(const ServiceReference<S> &reference) = 0¶

A service is being added to the ServiceTracker.

This method is called before a service which matched the search parameters of the ServiceTracker is added to the ServiceTracker. This method should return the service object to be tracked for the specified ServiceReference. The returned service object is stored in the ServiceTracker and is available from the GetService and GetServices methods.

Return

The service object to be tracked for the specified referenced service or 0 if the specified referenced service should not be tracked.

Parameters

reference: The reference to the service being added to the ServiceTracker.

virtual void ModifiedService(const ServiceReference<S> &reference, const std::shared_ptr<TrackedParamType> &service) = 0¶

A service tracked by the ServiceTracker has been modified.

This method is called when a service being tracked by the ServiceTracker has had it properties modified.

Parameters

reference: The reference to the service that has been modified.
service: The service object for the specified referenced service.

virtual void RemovedService(const ServiceReference<S> &reference, const std::shared_ptr<TrackedParamType> &service) = 0¶

A service tracked by the ServiceTracker has been removed.

This method is called after a service is no longer being tracked by the ServiceTracker.

Parameters

reference: The reference to the service that has been removed.
service: The service object for the specified referenced service.

struct TypeTraits¶

#include <cppmicroservices/ServiceTrackerCustomizer.h>

Public Types

template<> using ServiceType = S¶

template<> using TrackedType = T¶

template<> using TrackedParamType = T¶

Public Static Functions

template<> static std::shared_ptr<TrackedType> ConvertToTrackedType(const std::shared_ptr<S>&)¶