The ServiceTracker class simplifies using services from the framework's service registry. More...

Inheritance diagram for ServiceTracker< S, T >:

Collaboration diagram for ServiceTracker< S, T >:

Public Types
typedef std::map < ServiceReference, T >	TrackingMap

Public Member Functions
	~ServiceTracker ()

	ServiceTracker (ModuleContext context, const ServiceReference &reference, ServiceTrackerCustomizer< T > customizer=0)
	Create a `ServiceTracker` on the specified `ServiceReference`. More...

	ServiceTracker (ModuleContext context, const std::string &clazz, ServiceTrackerCustomizer< T > customizer=0)
	Create a `ServiceTracker` on the specified class name. More...

	ServiceTracker (ModuleContext context, const LDAPFilter &filter, ServiceTrackerCustomizer< T > customizer=0)
	Create a `ServiceTracker` on the specified `LDAPFilter` object. More...

	ServiceTracker (ModuleContext context, ServiceTrackerCustomizer< T > customizer=0)
	Create a `ServiceTracker` on the class template argument S. More...

virtual void	Open ()
	Open this `ServiceTracker` and begin tracking services. More...

virtual void	Close ()
	Close this `ServiceTracker`. More...

virtual T	WaitForService (unsigned long timeoutMillis=0)
	Wait for at least one service to be tracked by this `ServiceTracker`. More...

virtual void	GetServiceReferences (std::list< ServiceReference > &refs) const
	Return a list of `ServiceReference`s for all services being tracked by this `ServiceTracker`. More...

virtual ServiceReference	GetServiceReference () const
	Returns a `ServiceReference` for one of the services being tracked by this `ServiceTracker`. More...

virtual T	GetService (const ServiceReference &reference) const
	Returns the service object for the specified `ServiceReference` if the specified referenced service is being tracked by this `ServiceTracker`. More...

virtual void	GetServices (std::list< T > &services) const
	Return a list of service objects for all services being tracked by this `ServiceTracker`. More...

virtual T	GetService () const
	Returns a service object for one of the services being tracked by this `ServiceTracker`. More...

virtual void	Remove (const ServiceReference &reference)
	Remove a service from this `ServiceTracker`. More...

virtual int	Size () const
	Return the number of services being tracked by this `ServiceTracker`. More...

virtual int	GetTrackingCount () const
	Returns the tracking count for this `ServiceTracker`. More...

virtual void	GetTracked (TrackingMap &tracked) const
	Return a sorted map of the `ServiceReference`s and service objects for all services being tracked by this `ServiceTracker`. More...

virtual bool	IsEmpty () const
	Return if this `ServiceTracker` is empty. More...

Protected Member Functions
T	AddingService (const ServiceReference &reference)
	Default implementation of the `ServiceTrackerCustomizer::AddingService` method. More...

void	ModifiedService (const ServiceReference &reference, T service)
	Default implementation of the `ServiceTrackerCustomizer::ModifiedService` method. More...

void	RemovedService (const ServiceReference &reference, T service)
	Default implementation of the `ServiceTrackerCustomizer::RemovedService` method. More...

Protected Member Functions inherited from ServiceTrackerCustomizer< T >
virtual	~ServiceTrackerCustomizer ()

Detailed Description

template<class S = us::Base*, class T = S>
class ServiceTracker< S, T >

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.

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

Template Parameters

S	The type of the service being tracked. The type must be an assignable datatype. Further, if the `ServiceTracker(ModuleContext, ServiceTrackerCustomizer<T>)` constructor is used, the type must have an associated interface id via US_DECLARE_SERVICE_INTERFACE.
T	The type of the tracked object. The type must be an assignable datatype, provide a boolean conversion function, and provide a constructor and an assignment operator which can handle 0 as an argument.

Remarks: This class is thread safe.

Member Typedef Documentation

template<class S = us::Base*, class T = S>

typedef std::map<ServiceReference,T> ServiceTracker< S, T >::TrackingMap

Constructor & Destructor Documentation

template<class S = us::Base*, class T = S>

ServiceTracker< S, T >::~ServiceTracker ( )

template<class S = us::Base*, class T = S>

ServiceTracker< S, T >::ServiceTracker	(	ModuleContext *	context,
		const ServiceReference &	reference,
		ServiceTrackerCustomizer< T > *	customizer = `0`
	)

Create a ServiceTracker on the specified ServiceReference.

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

Parameters

context	The `ModuleContext` 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.

template<class S = us::Base*, class T = S>

ServiceTracker< S, T >::ServiceTracker	(	ModuleContext *	context,
		const std::string &	clazz,
		ServiceTrackerCustomizer< 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

context	The `ModuleContext` 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.

template<class S = us::Base*, class T = S>

ServiceTracker< S, T >::ServiceTracker	(	ModuleContext *	context,
		const LDAPFilter &	filter,
		ServiceTrackerCustomizer< T > *	customizer = `0`
	)

Create a ServiceTracker on the specified LDAPFilter object.

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

Parameters

context	The `ModuleContext` 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.

template<class S = us::Base*, class T = S>

ServiceTracker< S, T >::ServiceTracker	(	ModuleContext *	context,
		ServiceTrackerCustomizer< T > *	customizer = `0`
	)

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 `ModuleContext` 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.

Member Function Documentation

template<class S = us::Base*, class T = S>

T ServiceTracker< S, T >::AddingService ( const ServiceReference & reference )

protectedvirtual

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

reference The 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&)

Implements ServiceTrackerCustomizer< T >.

template<class S = us::Base*, class T = S>

virtual void ServiceTracker< S, T >::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.

template<class S = us::Base*, class T = S>

virtual T ServiceTracker< S, T >::GetService ( const ServiceReference & reference ) const

virtual

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

Parameters

reference The reference to the desired service.

Returns: A service object or null if the service referenced by the specified ServiceReference is not being tracked.

template<class S = us::Base*, class T = S>

virtual T ServiceTracker< S, T >::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.

template<class S = us::Base*, class T = S>

virtual ServiceReference ServiceTracker< S, T >::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

ServiceException if no services are being tracked.

template<class S = us::Base*, class T = S>

virtual void ServiceTracker< S, T >::GetServiceReferences ( std::list< ServiceReference > & refs ) const

virtual

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

Parameters

refs	List of `ServiceReference`s.

template<class S = us::Base*, class T = S>

virtual void ServiceTracker< S, T >::GetServices ( std::list< T > & services ) 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.

Parameters

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

template<class S = us::Base*, class T = S>

virtual void ServiceTracker< S, T >::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

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.

template<class S = us::Base*, class T = S>

virtual int ServiceTracker< S, T >::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.

template<class S = us::Base*, class T = S>

virtual bool ServiceTracker< S, T >::IsEmpty ( ) const

virtual

Return if this ServiceTracker is empty.

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

template<class S = us::Base*, class T = S>

void ServiceTracker< S, T >::ModifiedService	(	const ServiceReference &	reference,
		T	service
	)

protectedvirtual

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

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

See Also: ServiceTrackerCustomizer::ModifiedService(const ServiceReference&, T)

Implements ServiceTrackerCustomizer< T >.

template<class S = us::Base*, class T = S>

virtual void ServiceTracker< S, T >::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_error If the ModuleContext with which this ServiceTracker was created is no longer valid.

template<class S = us::Base*, class T = S>

virtual void ServiceTracker< S, T >::Remove ( const ServiceReference & 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

reference The reference to the service to be removed.

template<class S = us::Base*, class T = S>

void ServiceTracker< S, T >::RemovedService	(	const ServiceReference &	reference,
		T	service
	)

protectedvirtual

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

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

See Also: ServiceTrackerCustomizer::RemovedService(const ServiceReference&, T)

Implements ServiceTrackerCustomizer< T >.

template<class S = us::Base*, class T = S>

virtual int ServiceTracker< S, T >::Size ( ) const

virtual

Return the number of services being tracked by this ServiceTracker.

Returns: The number of services being tracked.

template<class S = us::Base*, class T = S>

virtual T ServiceTracker< S, T >::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().

CppMicroServices

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

template<class S = us::Base*, class T = S> class ServiceTracker< S, T >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

template<class S = us::Base*, class T = S>
class ServiceTracker< S, T >