Medical Imaging Interaction Toolkit  2024.06.00
Medical Imaging Interaction Toolkit
us::ServiceTracker< S, TTT > Class Template Reference

#include <usServiceTracker.h>

Inheritance diagram for us::ServiceTracker< S, TTT >:
Collaboration diagram for us::ServiceTracker< S, TTT >:

Public Types

typedef S ServiceType
 The type of the service being tracked. More...
 
typedef TTT::TrackedType T
 The type of the tracked object. More...
 
typedef ServiceReference< S > ServiceReferenceType
 
typedef std::map< ServiceReference< S >, TTrackingMap
 

Public Member Functions

 ~ServiceTracker () override
 
 ServiceTracker (ModuleContext *context, const ServiceReferenceType &reference, ServiceTrackerCustomizer< S, T > *customizer=nullptr)
 
 ServiceTracker (ModuleContext *context, const std::string &clazz, ServiceTrackerCustomizer< S, T > *customizer=0)
 
 ServiceTracker (ModuleContext *context, const LDAPFilter &filter, ServiceTrackerCustomizer< S, T > *customizer=nullptr)
 
 ServiceTracker (ModuleContext *context, ServiceTrackerCustomizer< S, T > *customizer=nullptr)
 
virtual void Open ()
 
virtual void Close ()
 
virtual T WaitForService (unsigned long timeoutMillis=0)
 
virtual std::vector< ServiceReferenceTypeGetServiceReferences () const
 
virtual ServiceReferenceType GetServiceReference () const
 
virtual T GetService (const ServiceReferenceType &reference) const
 
virtual std::vector< TGetServices () const
 
virtual T GetService () const
 
virtual void Remove (const ServiceReferenceType &reference)
 
virtual int Size () const
 
virtual int GetTrackingCount () const
 
virtual void GetTracked (TrackingMap &tracked) const
 
virtual bool IsEmpty () const
 

Protected Member Functions

T AddingService (const ServiceReferenceType &reference) override
 
void ModifiedService (const ServiceReferenceType &reference, T service) override
 
void RemovedService (const ServiceReferenceType &reference, T service) override
 
- Protected Member Functions inherited from us::ServiceTrackerCustomizer< S, TrackedTypeTraits< S, S * > ::TrackedType >
virtual ~ServiceTrackerCustomizer ()
 
virtual TrackedType AddingService (const ServiceReferenceType &reference)=0
 
virtual void ModifiedService (const ServiceReferenceType &reference, TrackedType service)=0
 
virtual void RemovedService (const ServiceReferenceType &reference, TrackedType service)=0
 

Additional Inherited Members

- Protected Types inherited from us::ServiceTrackerCustomizer< S, TrackedTypeTraits< S, S * > ::TrackedType >
typedef S ServiceType
 
typedef TrackedTypeTraits< S, S * > ::TrackedType TrackedType
 
typedef ServiceReference< ServiceTypeServiceReferenceType
 

Detailed Description

template<class S, class TTT = TrackedTypeTraits<S,S*>>
class us::ServiceTracker< S, TTT >

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.

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

Customization of the services to be tracked requires a custom tracked type traits class if the custom tracked type is not a pointer type. To customize a tracked service using a custom type with value-semantics like

struct MyTrackedClass { /* ... */ };

the custom tracked type traits class should look like this:

struct MyTrackedClassTraits : public TrackedTypeTraitsBase<MyTrackedClass, MyTrackedClassTraits>
{
static bool IsValid(const TrackedType&)
{
// Dummy implementation
return true;
}
static void Dispose(TrackedType&)
{}
static TrackedType DefaultValue()
{
return TrackedType();
}
};

For a custom tracked type, a ServiceTrackerCustomizer is required, which knows how to associate the tracked service with the custom tracked type:

struct MyTrackingCustomizer : public ServiceTrackerCustomizer<IFooService, MyTrackedClass>
{
MyTrackedClass AddingService(const ServiceReferenceType&) override
{
return MyTrackedClass();
}
void ModifiedService(const ServiceReferenceType&, MyTrackedClass) override
{
}
void RemovedService(const ServiceReferenceType&, MyTrackedClass) override
{
}
};

The custom tracking type traits class and customizer can now be used to instantiate a ServiceTracker:

MyTrackingCustomizer myCustomizer;
ServiceTracker<IFooService, MyTrackedClassTraits> tracker(GetModuleContext(), &myCustomizer);

If the custom tracked type is a pointer type, a suitable tracked type traits template is provided by the framework and only a ServiceTrackerCustomizer needs to be provided:

MyTrackingPointerCustomizer myCustomizer;
ServiceTracker<IFooService, TrackedTypeTraits<IFooService,MyTrackedClass*> > tracker(GetModuleContext(), &myCustomizer);
Template Parameters
SThe type of the service being tracked. The type S* must be an assignable datatype.
TTTType traits of the tracked object. The type traits class provides information about the customized service object, see TrackedTypeTraitsBase.
Remarks
This class is thread safe.

Definition at line 231 of file usServiceTracker.h.

Member Typedef Documentation

◆ ServiceReferenceType

template<class S , class TTT = TrackedTypeTraits<S,S*>>
typedef ServiceReference<S> us::ServiceTracker< S, TTT >::ServiceReferenceType

Definition at line 240 of file usServiceTracker.h.

◆ ServiceType

template<class S , class TTT = TrackedTypeTraits<S,S*>>
typedef S us::ServiceTracker< S, TTT >::ServiceType

The type of the service being tracked.

Definition at line 236 of file usServiceTracker.h.

◆ T

template<class S , class TTT = TrackedTypeTraits<S,S*>>
typedef TTT::TrackedType us::ServiceTracker< S, TTT >::T

The type of the tracked object.

Definition at line 238 of file usServiceTracker.h.

◆ TrackingMap

template<class S , class TTT = TrackedTypeTraits<S,S*>>
typedef std::map<ServiceReference<S>,T> us::ServiceTracker< S, TTT >::TrackingMap

Definition at line 242 of file usServiceTracker.h.

Constructor & Destructor Documentation

◆ ~ServiceTracker()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
us::ServiceTracker< S, TTT >::~ServiceTracker ( )
override

◆ ServiceTracker() [1/4]

template<class S , class TTT = TrackedTypeTraits<S,S*>>
us::ServiceTracker< S, TTT >::ServiceTracker ( ModuleContext context,
const ServiceReferenceType 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
contextThe ModuleContext against which the tracking is done.
referenceThe ServiceReference for the service to be tracked.
customizerThe 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() [2/4]

template<class S , class TTT = TrackedTypeTraits<S,S*>>
us::ServiceTracker< S, TTT >::ServiceTracker ( ModuleContext context,
const std::string &  clazz,
ServiceTrackerCustomizer< S, T > *  customizer = 0 
)

Create a ServiceTracker on the specified class name.

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

Parameters
contextThe ModuleContext against which the tracking is done.
clazzThe class name of the services to be tracked.
customizerThe 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() [3/4]

template<class S , class TTT = TrackedTypeTraits<S,S*>>
us::ServiceTracker< S, TTT >::ServiceTracker ( ModuleContext 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
contextThe ModuleContext against which the tracking is done.
filterThe LDAPFilter to select the services to be tracked.
customizerThe 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() [4/4]

template<class S , class TTT = TrackedTypeTraits<S,S*>>
us::ServiceTracker< S, TTT >::ServiceTracker ( ModuleContext 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
contextThe ModuleContext against which the tracking is done.
customizerThe 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.

Member Function Documentation

◆ AddingService()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
T us::ServiceTracker< S, TTT >::AddingService ( const ServiceReferenceType reference)
overrideprotected

Default implementation of the ServiceTrackerCustomizer::AddingService method.

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

This implementation returns the result of calling GetService on the ModuleContext 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.

Parameters
referenceThe reference to the service being added to this ServiceTracker.
Returns
The service object to be tracked for the service added to this ServiceTracker.
See also
ServiceTrackerCustomizer::AddingService(const ServiceReference&)

◆ Close()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual void us::ServiceTracker< S, TTT >::Close ( )
virtual

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.

◆ GetService() [1/2]

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual T us::ServiceTracker< S, TTT >::GetService ( ) const
virtual

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

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

◆ GetService() [2/2]

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual T us::ServiceTracker< S, TTT >::GetService ( const ServiceReferenceType reference) const
virtual

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

Parameters
referenceThe reference to the desired service.
Returns
A service object or null if the service referenced by the specified ServiceReference is not being tracked.

◆ GetServiceReference()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual ServiceReferenceType us::ServiceTracker< S, TTT >::GetServiceReference ( ) const
virtual

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 ModuleContext::GetServiceReference().

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

Returns
A ServiceReference for a tracked service.
Exceptions
ServiceExceptionif no services are being tracked.

◆ GetServiceReferences()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual std::vector<ServiceReferenceType> us::ServiceTracker< S, TTT >::GetServiceReferences ( ) const
virtual

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

Returns
List of ServiceReferences.

◆ GetServices()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual std::vector<T> us::ServiceTracker< S, TTT >::GetServices ( ) const
virtual

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.

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

◆ GetTracked()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual void us::ServiceTracker< S, TTT >::GetTracked ( TrackingMap tracked) const
virtual

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

◆ GetTrackingCount()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual int us::ServiceTracker< S, TTT >::GetTrackingCount ( ) const
virtual

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.

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

◆ IsEmpty()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual bool us::ServiceTracker< S, TTT >::IsEmpty ( ) const
virtual

Return if this ServiceTracker is empty.

Returns
true if this ServiceTracker is not tracking any services.

◆ ModifiedService()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
void us::ServiceTracker< S, TTT >::ModifiedService ( const ServiceReferenceType reference,
T  service 
)
overrideprotected

Default implementation of the ServiceTrackerCustomizer::ModifiedService method.

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

This implementation does nothing.

Parameters
referenceThe reference to modified service.
serviceThe service object for the modified service.
See also
ServiceTrackerCustomizer::ModifiedService(const ServiceReference&, T)

◆ Open()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual void us::ServiceTracker< S, TTT >::Open ( )
virtual

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::logic_errorIf the ModuleContext with which this ServiceTracker was created is no longer valid.

◆ Remove()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual void us::ServiceTracker< S, TTT >::Remove ( const ServiceReferenceType reference)
virtual

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
referenceThe reference to the service to be removed.

◆ RemovedService()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
void us::ServiceTracker< S, TTT >::RemovedService ( const ServiceReferenceType reference,
T  service 
)
overrideprotected

Default implementation of the ServiceTrackerCustomizer::RemovedService method.

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

This implementation calls UngetService, on the ModuleContext with which this ServiceTracker was created, passing the specified ServiceReference.

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

Parameters
referenceThe reference to removed service.
serviceThe service object for the removed service.
See also
ServiceTrackerCustomizer::RemovedService(const ServiceReferenceType&, T)

◆ Size()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual int us::ServiceTracker< S, TTT >::Size ( ) const
virtual

Return the number of services being tracked by this ServiceTracker.

Returns
The number of services being tracked.

◆ WaitForService()

template<class S , class TTT = TrackedTypeTraits<S,S*>>
virtual T us::ServiceTracker< S, TTT >::WaitForService ( unsigned long  timeoutMillis = 0)
virtual

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 ModuleActivator methods. ModuleActivator methods are expected to complete in a short period of time.

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

Returns
Returns the result of GetService().

The documentation for this class was generated from the following file:
us::ServiceTracker::RemovedService
void RemovedService(const ServiceReferenceType &reference, T service) override
us::ServiceTracker::ModifiedService
void ModifiedService(const ServiceReferenceType &reference, T service) override
us::ServiceTracker::AddingService
T AddingService(const ServiceReferenceType &reference) override
us::GetModuleContext
static ModuleContext * GetModuleContext()
Returns the module context of the calling module.
Definition: usGetModuleContext.h:50
us::ServiceTrackerCustomizer< S, TrackedTypeTraits< S, S * > ::TrackedType >::TrackedType
TrackedTypeTraits< S, S * > ::TrackedType TrackedType
Definition: usServiceTrackerCustomizer.h:66
us::ServiceTracker::ServiceReferenceType
ServiceReference< S > ServiceReferenceType
Definition: usServiceTracker.h:240