#include <Libs/PluginFramework/ctkServiceTracker.h>

Inheritance diagram for ctkServiceTracker< S, T >:

Collaboration diagram for ctkServiceTracker< S, T >:

Public Member Functions
virtual void	close ()

	ctkServiceTracker (ctkPluginContext context, const ctkLDAPSearchFilter &filter, ctkServiceTrackerCustomizer< T > customizer=0)

	ctkServiceTracker (ctkPluginContext context, const ctkServiceReference &reference, ctkServiceTrackerCustomizer< T > customizer=0)

	ctkServiceTracker (ctkPluginContext context, const QString &clazz, ctkServiceTrackerCustomizer< T > customizer=0)

	ctkServiceTracker (ctkPluginContext context, ctkServiceTrackerCustomizer< T > customizer=0)

virtual T	getService () const

virtual T	getService (const ctkServiceReference &reference) const

virtual ctkServiceReference	getServiceReference () const

virtual QList< ctkServiceReference >	getServiceReferences () const

virtual QList< T >	getServices () const

virtual QMap< ctkServiceReference, T >	getTracked () const

virtual int	getTrackingCount () const

virtual bool	isEmpty () const

virtual void	open ()

virtual void	remove (const ctkServiceReference &reference)

virtual int	size () const

virtual T	waitForService (unsigned long timeout)

	~ctkServiceTracker ()

Protected Member Functions
T	addingService (const ctkServiceReference &reference)

void	modifiedService (const ctkServiceReference &reference, T service)

void	removedService (const ctkServiceReference &reference, T service)

Protected Member Functions inherited from ctkServiceTrackerCustomizer< QObject * >
virtual void	modifiedService (const ctkServiceReference &reference, QObject * service)=0

virtual void	removedService (const ctkServiceReference &reference, QObject * service)=0

virtual	~ctkServiceTrackerCustomizer ()

Friends
class	ctkServiceTrackerPrivate< S, T >

class	ctkTrackedService< S, T >

Detailed Description

template<class S = QObject*, class T = S>
class ctkServiceTracker< S, T >

The ctkServiceTracker class simplifies using services from the Framework's service registry.

A ctkServiceTracker object is constructed with search criteria and a ctkServiceTrackerCustomizer object. A ctkServiceTracker can use a ctkServiceTrackerCustomizer to customize the service objects to be tracked. The ctkServiceTracker can then be opened to begin tracking all services in the Framework's service registry that match the specified search criteria. The ctkServiceTracker correctly handles all of the details of listening to ctkServiceEvents 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 ctkServiceTracker class is thread-safe. It does not call a ctkServiceTrackerCustomizer while holding any locks. ctkServiceTrackerCustomizer 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 `ctkServiceTracker(ctkPluginContext, ctkServiceTrackerCustomizer<T>)` constructor is used, the type must have an associated interface id via Q_DECLARE_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.

Definition at line 74 of file ctkServiceTracker.h.

Constructor & Destructor Documentation

◆ ~ctkServiceTracker()

template<class S = QObject*, class T = S>

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

◆ ctkServiceTracker() [1/4]

template<class S = QObject*, class T = S>

ctkServiceTracker< S, T >::ctkServiceTracker	(	ctkPluginContext *	context,
		const ctkServiceReference &	reference,
		ctkServiceTrackerCustomizer< T > *	customizer = `0`
	)

Create a ctkServiceTracker on the specified ctkServiceReference.

The service referenced by the specified ctkServiceReference will be tracked by this ctkServiceTracker.

Parameters

context	The `ctkPluginContext` against which the tracking is done.
reference	The `ctkServiceReference` for the service to be tracked.
customizer	The customizer object to call when services are added, modified, or removed in this `ctkServiceTracker`. If customizer is `null`, then this `ctkServiceTracker` will be used as the `ctkServiceTrackerCustomizer` and this `ctkServiceTracker` will call the `ctkServiceTrackerCustomizer` methods on itself.

◆ ctkServiceTracker() [2/4]

template<class S = QObject*, class T = S>

ctkServiceTracker< S, T >::ctkServiceTracker	(	ctkPluginContext *	context,
		const QString &	clazz,
		ctkServiceTrackerCustomizer< T > *	customizer = `0`
	)

Create a ctkServiceTracker on the specified class name.

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

Parameters

context	The `ctkPluginContext` 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 `ctkServiceTracker`. If customizer is `null`, then this `ctkServiceTracker` will be used as the `ctkServiceTrackerCustomizer` and this `ctkServiceTracker` will call the `ctkServiceTrackerCustomizer` methods on itself.

◆ ctkServiceTracker() [3/4]

template<class S = QObject*, class T = S>

ctkServiceTracker< S, T >::ctkServiceTracker	(	ctkPluginContext *	context,
		const ctkLDAPSearchFilter &	filter,
		ctkServiceTrackerCustomizer< T > *	customizer = `0`
	)

Create a ctkServiceTracker on the specified ctkLDAPSearchFilter object.

Services which match the specified ctkLDAPSearchFilter object will be tracked by this ctkServiceTracker.

Parameters

context	The `ctkPluginContext` against which the tracking is done.
filter	The `ctkLDAPSearchFilter` to select the services to be tracked.
customizer	The customizer object to call when services are added, modified, or removed in this `ctkServiceTracker`. If customizer is null, then this `ctkServiceTracker` will be used as the `ctkServiceTrackerCustomizer` and this `ctkServiceTracker` will call the `ctkServiceTrackerCustomizer` methods on itself.

◆ ctkServiceTracker() [4/4]

template<class S = QObject*, class T = S>

ctkServiceTracker< S, T >::ctkServiceTracker	(	ctkPluginContext *	context,
		ctkServiceTrackerCustomizer< T > *	customizer = `0`
	)

Create a ctkServiceTracker on the class template argument S.

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

Parameters

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

Member Function Documentation

◆ addingService()

template<class S = QObject*, class T = S>

T ctkServiceTracker< S, T >::addingService ( const ctkServiceReference & reference )

protectedvirtual

Default implementation of the ctkServiceTrackerCustomizer::addingService method.

This method is only called when this ctkServiceTracker has been constructed with a null ctkServiceTrackerCustomizer argument.

This implementation returns the result of calling getService on the ctkPluginContext with which this ctkServiceTracker was created passing the specified ctkServiceReference.

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

Returns: The service object to be tracked for the service added to this ctlServiceTracker.

See also: ctkServiceTrackerCustomizer::addingService(const ctkServiceReference&)

Implements ctkServiceTrackerCustomizer< QObject * >.

◆ close()

template<class S = QObject*, class T = S>

virtual void ctkServiceTracker< S, T >::close ( )

virtual

Close this ctkServiceTracker.

This method should be called when this ctkServiceTracker 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 = QObject*, class T = S>

virtual T ctkServiceTracker< S, T >::getService ( ) const

virtual

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

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 = QObject*, class T = S>

virtual T ctkServiceTracker< S, T >::getService ( const ctkServiceReference & reference ) const

virtual

Returns the service object for the specified ctkServiceReference if the specified referenced service is being tracked by this ctkServiceTracker.

Parameters

reference The reference to the desired service.

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

◆ getServiceReference()

template<class S = QObject*, class T = S>

virtual ctkServiceReference ctkServiceTracker< S, T >::getServiceReference ( ) const

virtual

Returns a ctkServiceReference for one of the services being tracked by this ctkServiceTracker.

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 ctkPluginContext::getServiceReference().

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

Returns: A ctkServiceReference for a tracked service.

Exceptions

ctkServiceException if no services are being tracked.

◆ getServiceReferences()

template<class S = QObject*, class T = S>

virtual QList<ctkServiceReference> ctkServiceTracker< S, T >::getServiceReferences ( ) const

virtual

Return a list of ctkServiceReferences for all services being tracked by this ctkServiceTracker.

Returns: List of ctkServiceReferences.

◆ getServices()

template<class S = QObject*, class T = S>

virtual QList<T> ctkServiceTracker< S, T >::getServices ( ) const

virtual

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

This implementation calls getServiceReferences() to get the list of references for the tracked services and then calls getService(const ctkServiceReference&) 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 = QObject*, class T = S>

virtual QMap<ctkServiceReference, T> ctkServiceTracker< S, T >::getTracked ( ) const

virtual

Return a sorted QMap of the ctkServiceReferences and service objects for all services being tracked by this ctkServiceTracker. The map is sorted in natural order of ctkServiceReference. That is, the last entry is the service with the highest ranking and the lowest service id.

Returns: A QMap with the ctkServiceReferences and service objects for all services being tracked by this ctkServiceTracker. If no services are being tracked, then the returned map is empty.

◆ getTrackingCount()

template<class S = QObject*, class T = S>

virtual int ctkServiceTracker< S, T >::getTrackingCount ( ) const

virtual

Returns the tracking count for this ctkServiceTracker.

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

The tracking count can be used to determine if this ctkServiceTracker 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 ctkServiceTracker since the previous tracking count was collected.

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

◆ isEmpty()

template<class S = QObject*, class T = S>

virtual bool ctkServiceTracker< S, T >::isEmpty ( ) const

virtual

Return if this ctkServiceTracker is empty.

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

◆ modifiedService()

template<class S = QObject*, class T = S>

void ctkServiceTracker< S, T >::modifiedService	(	const ctkServiceReference &	reference,
		T	service
	)

protected

Default implementation of the ctkServiceTrackerCustomizer::modifiedService method.

This method is only called when this ctkServiceTracker has been constructed with a null ctkServiceTrackerCustomizer argument.

This implementation does nothing.

Parameters

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

See also: ctkServiceTrackerCustomizer::modifiedService(const ctkServiceReference&, QObject*)

◆ open()

template<class S = QObject*, class T = S>

virtual void ctkServiceTracker< S, T >::open ( )

virtual

Open this ctkServiceTracker and begin tracking services.

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

Exceptions

ctkIllegalStateException If the ctkPluginContext with which this ctkServiceTracker was created is no longer valid.

◆ remove()

template<class S = QObject*, class T = S>

virtual void ctkServiceTracker< S, T >::remove ( const ctkServiceReference & reference )

virtual

Remove a service from this ctkServiceTracker.

The specified service will be removed from this ctkServiceTracker. If the specified service was being tracked then the ctkServiceTrackerCustomizer::removedService method will be called for that service.

Parameters

reference The reference to the service to be removed.

◆ removedService()

template<class S = QObject*, class T = S>

void ctkServiceTracker< S, T >::removedService	(	const ctkServiceReference &	reference,
		T	service
	)

protected

Default implementation of the ctkServiceTrackerCustomizer::removedService method.

This method is only called when this ctkServiceTracker has been constructed with a null ctkServiceTrackerCustomizer argument.

This implementation calls ungetService, on the ctkPluginContext with which this ctkServiceTracker was created, passing the specified ctkServiceReference.

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: ctkServiceTrackerCustomizer::removedService(const ServiceReference&, QObject*)

◆ size()

template<class S = QObject*, class T = S>

virtual int ctkServiceTracker< S, T >::size ( ) const

virtual

Return the number of services being tracked by this ctkServiceTracker.

Returns: The number of services being tracked.

◆ waitForService()

template<class S = QObject*, class T = S>

virtual T ctkServiceTracker< S, T >::waitForService ( unsigned long timeout )

virtual

Wait for at least one service to be tracked by this ctkServiceTracker. This method will also return when this ctkServiceTracker is closed.

It is strongly recommended that waitForService is not used during the calling of the ctkPluginActivator methods. ctkPluginActivator methods are expected to complete in a short period of time.

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

Parameters

timeout The time interval in milliseconds to wait. If zero, the method will wait indefinitely.

Returns: Returns the result of getService().

Friends And Related Function Documentation

◆ ctkServiceTrackerPrivate< S, T >

template<class S = QObject*, class T = S>

friend class ctkServiceTrackerPrivate< S, T >

friend

Definition at line 421 of file ctkServiceTracker.h.

◆ ctkTrackedService< S, T >

template<class S = QObject*, class T = S>

friend class ctkTrackedService< S, T >

friend

Definition at line 421 of file ctkServiceTracker.h.

The documentation for this class was generated from the following file:

Libs/PluginFramework/ctkServiceTracker.h

Public Member Functions

Protected Member Functions

Friends

Detailed Description

template<class S = QObject*, class T = S> class ctkServiceTracker< S, T >

Constructor & Destructor Documentation

◆ ~ctkServiceTracker()

◆ ctkServiceTracker() [1/4]

◆ ctkServiceTracker() [2/4]

◆ ctkServiceTracker() [3/4]

◆ ctkServiceTracker() [4/4]

Member Function Documentation

◆ addingService()

◆ close()

◆ getService() [1/2]

◆ getService() [2/2]

◆ getServiceReference()

◆ getServiceReferences()

◆ getServices()

◆ getTracked()

◆ getTrackingCount()

◆ isEmpty()

◆ modifiedService()

◆ open()

◆ remove()

◆ removedService()

◆ size()

◆ waitForService()

Friends And Related Function Documentation

◆ ctkServiceTrackerPrivate< S, T >

◆ ctkTrackedService< S, T >

template<class S = QObject*, class T = S>
class ctkServiceTracker< S, T >