Fixed documentation of ctkServiceTracker.

Libs/PluginFramework/ctkServiceTracker.h

@@ -34,6 +34,31 @@
 class ctkPluginContext;
 class ctkServiceTrackerPrivate;
 
+/**
+ * The <code>ctkServiceTracker</code> class simplifies using services from the
+ * Framework's service registry.
+ * <p>
+ * A <code>ctkServiceTracker</code> object is constructed with search criteria and
+ * a <code>ctkServiceTrackerCustomizer</code> object. A <code>ctkServiceTracker</code>
+ * can use a <code>ctkServiceTrackerCustomizer</code> to customize the service
+ * objects to be tracked. The <code>ctkServiceTracker</code> can then be opened to
+ * begin tracking all services in the Framework's service registry that match
+ * the specified search criteria. The <code>ctkServiceTracker</code> correctly
+ * handles all of the details of listening to <code>ctkServiceEvent</code>s and
+ * getting and ungetting services.
+ * <p>
+ * The <code>getServiceReferences</code> method can be called to get references
+ * to the services being tracked. The <code>getService</code> and
+ * <code>getServices</code> methods can be called to get the service objects for
+ * the tracked service.
+ * <p>
+ * The <code>ctkServiceTracker</code> class is thread-safe. It does not call a
+ * <code>ctkServiceTrackerCustomizer</code> while holding any locks.
+ * <code>ctkServiceTrackerCustomizer</code> implementations must also be
+ * thread-safe.
+ *
+ * @ThreadSafe
+ */
 class CTK_PLUGINFW_EXPORT ctkServiceTracker : protected ctkServiceTrackerCustomizer
 {
 public:
@@ -41,137 +66,131 @@ public:
   ~ctkServiceTracker();
 
   /**
-   * Create a <code>ServiceTracker</code> on the specified
-   * <code>ServiceReference</code>.
+   * Create a <code>ctkServiceTracker</code> on the specified
+   * <code>ctkServiceReference</code>.
    *
    * <p>
-   * The service referenced by the specified <code>ServiceReference</code>
-   * will be tracked by this <code>ServiceTracker</code>.
+   * The service referenced by the specified <code>ctkServiceReference</code>
+   * will be tracked by this <code>ctkServiceTracker</code>.
    *
-   * @param context The <code>BundleContext</code> against which the tracking
+   * @param context The <code>ctkPluginContext</code> against which the tracking
    *        is done.
-   * @param reference The <code>ServiceReference</code> for the service to be
+   * @param reference The <code>ctkServiceReference</code> for the service to be
    *        tracked.
    * @param customizer The customizer object to call when services are added,
-   *        modified, or removed in this <code>ServiceTracker</code>. If
+   *        modified, or removed in this <code>ctkServiceTracker</code>. If
    *        customizer is <code>null</code>, then this
-   *        <code>ServiceTracker</code> will be used as the
-   *        <code>ServiceTrackerCustomizer</code> and this
-   *        <code>ServiceTracker</code> will call the
-   *        <code>ServiceTrackerCustomizer</code> methods on itself.
+   *        <code>ctkServiceTracker</code> will be used as the
+   *        <code>ctkServiceTrackerCustomizer</code> and this
+   *        <code>ctkServiceTracker</code> will call the
+   *        <code>ctkServiceTrackerCustomizer</code> methods on itself.
    */
   ctkServiceTracker(ctkPluginContext* context,
                     const ctkServiceReference& reference,
                     ctkServiceTrackerCustomizer* customizer = 0);
 
   /**
-   * Create a <code>ServiceTracker</code> on the specified class name.
+   * Create a <code>ctkServiceTracker</code> on the specified class name.
    *
    * <p>
    * Services registered under the specified class name will be tracked by
-   * this <code>ServiceTracker</code>.
+   * this <code>ctkServiceTracker</code>.
    *
-   * @param context The <code>BundleContext</code> against which the tracking
+   * @param context The <code>ctkPluginContext</code> against which the tracking
    *        is done.
    * @param clazz The class name of the services to be tracked.
    * @param customizer The customizer object to call when services are added,
-   *        modified, or removed in this <code>ServiceTracker</code>. If
+   *        modified, or removed in this <code>ctkServiceTracker</code>. If
    *        customizer is <code>null</code>, then this
-   *        <code>ServiceTracker</code> will be used as the
-   *        <code>ServiceTrackerCustomizer</code> and this
-   *        <code>ServiceTracker</code> will call the
-   *        <code>ServiceTrackerCustomizer</code> methods on itself.
+   *        <code>ctkServiceTracker</code> will be used as the
+   *        <code>ctkServiceTrackerCustomizer</code> and this
+   *        <code>ctkServiceTracker</code> will call the
+   *        <code>ctkServiceTrackerCustomizer</code> methods on itself.
    */
   ctkServiceTracker(ctkPluginContext* context, const QString& clazz,
                         ctkServiceTrackerCustomizer* customizer = 0);
 
   /**
-   * Create a <code>ServiceTracker</code> on the specified <code>Filter</code>
-   * object.
+   * Create a <code>ctkServiceTracker</code> on the specified
+   * <code>ctkLDAPSearchFilter</code> object.
    *
    * <p>
-   * Services which match the specified <code>Filter</code> object will be
-   * tracked by this <code>ServiceTracker</code>.
+   * Services which match the specified <code>ctkLDAPSearchFilter</code> object will be
+   * tracked by this <code>ctkServiceTracker</code>.
    *
-   * @param context The <code>BundleContext</code> against which the tracking
+   * @param context The <code>ctkPluginContext</code> against which the tracking
    *        is done.
-   * @param filter The <code>Filter</code> to select the services to be
+   * @param filter The <code>ctkLDAPSearchFilter</code> to select the services to be
    *        tracked.
    * @param customizer The customizer object to call when services are added,
-   *        modified, or removed in this <code>ServiceTracker</code>. If
-   *        customizer is null, then this <code>ServiceTracker</code> will be
-   *        used as the <code>ServiceTrackerCustomizer</code> and this
-   *        <code>ServiceTracker</code> will call the
-   *        <code>ServiceTrackerCustomizer</code> methods on itself.
-   * @since 1.1
+   *        modified, or removed in this <code>ctkServiceTracker</code>. If
+   *        customizer is null, then this <code>ctkServiceTracker</code> will be
+   *        used as the <code>ctkServiceTrackerCustomizer</code> and this
+   *        <code>ctkServiceTracker</code> will call the
+   *        <code>ctkServiceTrackerCustomizer</code> methods on itself.
    */
   ctkServiceTracker(ctkPluginContext* context, const ctkLDAPSearchFilter& filter,
                         ctkServiceTrackerCustomizer* customizer = 0);
 
   /**
-   * Open this <code>ServiceTracker</code> and begin tracking services.
+   * Open this <code>ctkServiceTracker</code> and begin tracking services.
    *
    * <p>
    * Services which match the search criteria specified when this
-   * <code>ServiceTracker</code> was created are now tracked by this
-   * <code>ServiceTracker</code>.
+   * <code>ctkServiceTracker</code> was created are now tracked by this
+   * <code>ctkServiceTracker</code>.
    *
-   * @throws java.lang.IllegalStateException If the <code>BundleContext</code>
-   *         with which this <code>ServiceTracker</code> was created is no
+   * @throws std::logic_error If the <code>ctkPluginContext</code>
+   *         with which this <code>ctkServiceTracker</code> was created is no
    *         longer valid.
-   * @since 1.3
    */
   void open();
 
   /**
-   * Close this <code>ServiceTracker</code>.
+   * Close this <code>ctkServiceTracker</code>.
    *
    * <p>
-   * This method should be called when this <code>ServiceTracker</code> should
+   * This method should be called when this <code>ctkServiceTracker</code> should
    * end the tracking of services.
    *
    * <p>
-   * This implementation calls {@link #getServiceReferences()} to get the list
+   * This implementation calls getServiceReferences() to get the list
    * of tracked services to remove.
    */
   void close();
 
   /**
    * Wait for at least one service to be tracked by this
-   * <code>ServiceTracker</code>. This method will also return when this
-   * <code>ServiceTracker</code> is closed.
+   * <code>ctkServiceTracker</code>. This method will also return when this
+   * <code>ctkServiceTracker</code> is closed.
    *
    * <p>
    * It is strongly recommended that <code>waitForService</code> is not used
-   * during the calling of the <code>BundleActivator</code> methods.
-   * <code>BundleActivator</code> methods are expected to complete in a short
+   * during the calling of the <code>ctkPluginActivator</code> methods.
+   * <code>ctkPluginActivator</code> methods are expected to complete in a short
    * period of time.
    *
    * <p>
-   * This implementation calls {@link #getService()} to determine if a service
+   * This implementation calls getService() to determine if a service
    * is being tracked.
    *
    * @param timeout The time interval in milliseconds to wait. If zero, the
    *        method will wait indefinitely.
-   * @return Returns the result of {@link #getService()}.
-   * @throws InterruptedException If another thread has interrupted the
-   *         current thread.
-   * @throws IllegalArgumentException If the value of timeout is negative.
+   * @return Returns the result of getService().
    */
   QObject* waitForService(unsigned long timeout);
 
   /**
-   * Return an array of <code>ServiceReference</code>s for all services being
-   * tracked by this <code>ServiceTracker</code>.
+   * Return a list of <code>ctkServiceReference</code>s for all services being
+   * tracked by this <code>ctkServiceTracker</code>.
    *
-   * @return Array of <code>ServiceReference</code>s or <code>null</code> if
-   *         no services are being tracked.
+   * @return List of <code>ctkServiceReference</code>s.
    */
   QList<ctkServiceReference> getServiceReferences() const;
 
   /**
-   * Returns a <code>ServiceReference</code> for one of the services being
-   * tracked by this <code>ServiceTracker</code>.
+   * Returns a <code>ctkServiceReference</code> for one of the services being
+   * tracked by this <code>ctkServiceTracker</code>.
    *
    * <p>
    * If multiple services are being tracked, the service with the highest
@@ -179,48 +198,47 @@ public:
    * returned. If there is a tie in ranking, the service with the lowest
    * service ID (as specified in its <code>service.id</code> property); that
    * is, the service that was registered first is returned. This is the same
-   * algorithm used by <code>BundleContext.getServiceReference</code>.
+   * algorithm used by <code>ctkPluginContext::getServiceReference()</code>.
    *
    * <p>
-   * This implementation calls {@link #getServiceReferences()} to get the list
+   * This implementation calls getServiceReferences() to get the list
    * of references for the tracked services.
    *
-   * @return A <code>ServiceReference</code> or <code>null</code> if no
-   *         services are being tracked.
-   * @since 1.1
+   * @return A <code>ctkServiceReference</code> for a tracked service.
+   * @throws ctkServiceException if no services are being tracked.
    */
   ctkServiceReference getServiceReference() const;
 
   /**
    * Returns the service object for the specified
-   * <code>ServiceReference</code> if the specified referenced service is
-   * being tracked by this <code>ServiceTracker</code>.
+   * <code>ctkServiceReference</code> if the specified referenced service is
+   * being tracked by this <code>ctkServiceTracker</code>.
    *
    * @param reference The reference to the desired service.
    * @return A service object or <code>null</code> if the service referenced
-   *         by the specified <code>ServiceReference</code> is not being
+   *         by the specified <code>ctkServiceReference</code> is not being
    *         tracked.
    */
   QObject* getService(const ctkServiceReference& reference) const;
 
   /**
-   * Return an array of service objects for all services being tracked by this
-   * <code>ServiceTracker</code>.
+   * Return a list of service objects for all services being tracked by this
+   * <code>ctkServiceTracker</code>.
    *
    * <p>
-   * This implementation calls {@link #getServiceReferences()} to get the list
+   * This implementation calls getServiceReferences() to get the list
    * of references for the tracked services and then calls
-   * {@link #getService(ServiceReference)} for each reference to get the
+   * getService(const ctkServiceReference&) for each reference to get the
    * tracked service object.
    *
-   * @return An array of service objects or <code>null</code> if no services
+   * @return A list of service objects or an empty list if no services
    *         are being tracked.
    */
   QList<QObject*> getServices() const;
 
   /**
    * Returns a service object for one of the services being tracked by this
-   * <code>ServiceTracker</code>.
+   * <code>ctkServiceTracker</code>.
    *
    * <p>
    * If any services are being tracked, this implementation returns the result
@@ -232,11 +250,11 @@ public:
   QObject* getService() const;
 
   /**
-   * Remove a service from this <code>ServiceTracker</code>.
+   * Remove a service from this <code>ctkServiceTracker</code>.
    *
    * The specified service will be removed from this
-   * <code>ServiceTracker</code>. If the specified service was being tracked
-   * then the <code>ServiceTrackerCustomizer.removedService</code> method will
+   * <code>ctkServiceTracker</code>. If the specified service was being tracked
+   * then the <code>ctkServiceTrackerCustomizer::removedService</code> method will
    * be called for that service.
    *
    * @param reference The reference to the service to be removed.
@@ -245,31 +263,30 @@ public:
 
   /**
    * Return the number of services being tracked by this
-   * <code>ServiceTracker</code>.
+   * <code>ctkServiceTracker</code>.
    *
    * @return The number of services being tracked.
    */
   int size() const;
 
   /**
-   * Returns the tracking count for this <code>ServiceTracker</code>.
+   * Returns the tracking count for this <code>ctkServiceTracker</code>.
    *
    * The tracking count is initialized to 0 when this
-   * <code>ServiceTracker</code> is opened. Every time a service is added,
-   * modified or removed from this <code>ServiceTracker</code>, the tracking
+   * <code>ctkServiceTracker</code> is opened. Every time a service is added,
+   * modified or removed from this <code>ctkServiceTracker</code>, the tracking
    * count is incremented.
    *
    * <p>
    * The tracking count can be used to determine if this
-   * <code>ServiceTracker</code> has added, modified or removed a service by
+   * <code>ctkServiceTracker</code> 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 <code>ServiceTracker</code>
+   * been added, modified or removed from this <code>ctkServiceTracker</code>
    * since the previous tracking count was collected.
    *
-   * @since 1.2
-   * @return The tracking count for this <code>ServiceTracker</code> or -1 if
-   *         this <code>ServiceTracker</code> is not open.
+   * @return The tracking count for this <code>ctkServiceTracker</code> or -1 if
+   *         this <code>ctkServiceTracker</code> is not open.
    */
   int getTrackingCount() const;
 
@@ -277,69 +294,69 @@ protected:
 
   /**
    * Default implementation of the
-   * <code>ServiceTrackerCustomizer.addingService</code> method.
+   * <code>ctkServiceTrackerCustomizer::addingService</code> method.
    *
    * <p>
-   * This method is only called when this <code>ServiceTracker</code> has been
-   * constructed with a <code>null ServiceTrackerCustomizer</code> argument.
+   * This method is only called when this <code>ctkServiceTracker</code> has been
+   * constructed with a <code>null</code> ctkServiceTrackerCustomizer argument.
    *
    * <p>
    * This implementation returns the result of calling <code>getService</code>
-   * on the <code>BundleContext</code> with which this
-   * <code>ServiceTracker</code> was created passing the specified
-   * <code>ServiceReference</code>.
+   * on the <code>ctkPluginContext</code> with which this
+   * <code>ctkServiceTracker</code> was created passing the specified
+   * <code>ctkServiceReference</code>.
    * <p>
    * 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
-   * {@link #removedService(ServiceReference, Object) removedService} to unget
-   * the service.
+   * \link removedService(const ctkServiceReference&, QObject*) removedService\endlink
+   * to unget the service.
    *
    * @param reference The reference to the service being added to this
-   *        <code>ServiceTracker</code>.
+   *        <code>ctkServiceTracker</code>.
    * @return The service object to be tracked for the service added to this
-   *         <code>ServiceTracker</code>.
-   * @see ServiceTrackerCustomizer#addingService(ServiceReference)
+   *         <code>ctlServiceTracker</code>.
+   * @see ctkServiceTrackerCustomizer::addingService(const ctkServiceReference&)
    */
   QObject* addingService(const ctkServiceReference& reference);
 
   /**
    * Default implementation of the
-   * <code>ServiceTrackerCustomizer.modifiedService</code> method.
+   * <code>ctkServiceTrackerCustomizer::modifiedService</code> method.
    *
    * <p>
-   * This method is only called when this <code>ServiceTracker</code> has been
-   * constructed with a <code>null ServiceTrackerCustomizer</code> argument.
+   * This method is only called when this <code>ctkServiceTracker</code> has been
+   * constructed with a <code>null</code> ctkServiceTrackerCustomizer argument.
    *
    * <p>
    * This implementation does nothing.
    *
    * @param reference The reference to modified service.
    * @param service The service object for the modified service.
-   * @see ServiceTrackerCustomizer#modifiedService(ServiceReference, Object)
+   * @see ctkServiceTrackerCustomizer::modifiedService(const ctkServiceReference&, QObject*)
    */
   void modifiedService(const ctkServiceReference& reference, QObject* service);
 
   /**
    * Default implementation of the
-   * <code>ServiceTrackerCustomizer.removedService</code> method.
+   * <code>ctkServiceTrackerCustomizer::removedService</code> method.
    *
    * <p>
-   * This method is only called when this <code>ServiceTracker</code> has been
-   * constructed with a <code>null ServiceTrackerCustomizer</code> argument.
+   * This method is only called when this <code>ctkServiceTracker</code> has been
+   * constructed with a <code>null</code> ctkServiceTrackerCustomizer argument.
    *
    * <p>
    * This implementation calls <code>ungetService</code>, on the
-   * <code>BundleContext</code> with which this <code>ServiceTracker</code>
-   * was created, passing the specified <code>ServiceReference</code>.
+   * <code>ctkPluginContext</code> with which this <code>ctkServiceTracker</code>
+   * was created, passing the specified <code>ctkServiceReference</code>.
    * <p>
    * This method can be overridden in a subclass. If the default
-   * implementation of {@link #addingService(ServiceReference) addingService}
+   * implementation of \link addingService(const ctkServiceReference&) addingService\endlink
    * method was used, this method must unget the service.
    *
    * @param reference The reference to removed service.
    * @param service The service object for the removed service.
-   * @see ServiceTrackerCustomizer#removedService(ServiceReference, Object)
+   * @see ctkServiceTrackerCustomizer::removedService(const ServiceReference&, QObject*)
    */
   void removedService(const ctkServiceReference& reference, QObject* service);