Completed interface classes for EventAdmin specs.

Libs/PluginFramework/CMakeLists.txt

@@ -90,7 +90,7 @@ SET(KIT_SRCS
   service/cm/ctkManagedServiceFactory.h
 
   service/event/ctkEvent.cpp
-  service/event/ctkEventBus.h
+  service/event/ctkEventAdmin.h
   service/event/ctkEventConstants.cpp
 
   service/log/ctkLogEntry.h

Libs/PluginFramework/ctkPluginConstants.cpp

@@ -49,7 +49,12 @@ const QString ctkPluginConstants::RESOLUTION_OPTIONAL = "optional";
 
 
 const QString ctkPluginConstants::OBJECTCLASS = "objectclass";
+
+// ATTENTION!!! If the value is changed, change also ctkEventConstants::SERVICE_ID
 const QString ctkPluginConstants::SERVICE_ID = "service.id";
+
+// ATTENTION!!! If the value is changed, change also ctkEventConstants::SERVICE_PID
 const QString ctkPluginConstants::SERVICE_PID = "service.pid";
+
 const QString ctkPluginConstants::SERVICE_RANKING = "service.ranking";
 

Libs/PluginFramework/ctkPluginConstants.h

@@ -305,7 +305,8 @@ struct CTK_PLUGINFW_EXPORT ctkPluginConstants {
    * previously assigned values since the Framework was started. These values
    * are NOT persistent across restarts of the Framework.
    */
-  static const QString SERVICE_ID; //	= "service.id"
+  // ATTENTION!!! If the value is changed, change also ctkEventConstants::SERVICE_ID
+  static const QString SERVICE_ID; // = "service.id"
 
   /**
    * Service property identifying a service's persistent identifier.
@@ -326,6 +327,7 @@ struct CTK_PLUGINFW_EXPORT ctkPluginConstants {
    * a dot (.). A plugin may use this as the prefix of the persistent
    * identifiers for the services it registers.
    */
+  // ATTENTION!!! If the value is changed, change also ctkEventConstants::SERVICE_PID
   static const QString SERVICE_PID; // = "service.pid"
 
   /**

Libs/PluginFramework/service/event/ctkEvent.cpp

@@ -33,7 +33,7 @@ public:
     : ref(1), topic(topic), properties(properties)
   {
     validateTopicName(topic);
-    this->properties.insert(EventConstants::EVENT_TOPIC, topic);
+    this->properties.insert(ctkEventConstants::EVENT_TOPIC, topic);
   }
 
   static void validateTopicName(const QString& topic)
@@ -105,12 +105,21 @@ bool ctkEvent::operator==(const ctkEvent& other) const
   return false;
 }
 
-QVariant ctkEvent::property(const QString& name) const
+QVariant ctkEvent::getProperty(const QString& name) const
 {
   return d->properties[name];
 }
 
-QStringList ctkEvent::propertyNames() const
+bool ctkEvent::containsProperty(const QString& name) const
+{
+  if (ctkEventConstants::EVENT_TOPIC == name)
+  {
+   return true;
+  }
+  return d->properties.contains(name);
+}
+
+QStringList ctkEvent::getPropertyNames() const
 {
   QStringList result;
   foreach (ctkCaseInsensitiveString key, d->properties.keys())
@@ -120,7 +129,7 @@ QStringList ctkEvent::propertyNames() const
   return result;
 }
 
-const QString& ctkEvent::topic() const
+const QString& ctkEvent::getTopic() const
 {
   return d->topic;
 }

Libs/PluginFramework/service/event/ctkEvent.h

@@ -36,8 +36,8 @@ class ctkEventPrivate;
 /**
  * A CTK event.
  *
- * <code>ctkEvent</code> objects are delivered to Qt slots
- * which subscribe to the topic of the event.
+ * <code>ctkEvent</code> objects are delivered to <code>ctkEventHandler</code>
+ * or Qt slots which subscribe to the topic of the event.
  */
 class CTK_PLUGINFW_EXPORT ctkEvent {
 
@@ -68,26 +68,39 @@ public:
   bool operator==(const ctkEvent& other) const;
 
   /**
-   * Retrieves a property.
+   * Retrieve the value of an event property. The event topic may be retrieved
+   * with the property name &quot;event.topics&quot;.
    *
    * @param name the name of the property to retrieve
    * @return The value of the property, or an invalid QVariant if not found.
    */
-  QVariant property(const QString& name) const;
+  QVariant getProperty(const QString& name) const;
 
   /**
-   * Returns a list of this event's property names.
+   * Indicate the presence of an event property. The event topic is present
+   * using the property name &quot;event.topics&quot;.
+   *
+   * @param name The name of the property.
+   * @return <code>true</code> if a property with the specified name is in the
+   *         event. This property may have an invalid QVariant value.
+   *         <code>false</code> otherwise.
+   */
+  bool containsProperty(const QString& name) const;
+
+  /**
+   * Returns a list of this event's property names. The list will include the
+   * event topic property name &quot;event.topics&quot;.
    *
    * @return A non-empty list with one element per property.
    */
-  QStringList propertyNames() const;
+  QStringList getPropertyNames() const;
 
   /**
    * Returns the topic of this event.
    *
    * @return The topic of this event.
    */
-  const QString& topic() const;
+  const QString& getTopic() const;
 
   /**
    * Tests this event's properties against the given filter using a case

Libs/PluginFramework/service/event/ctkEventBus.h

@@ -26,20 +26,19 @@
 
 
 /**
- * The Event Bus service. Plugins wishing to publish events can either
- * obtain the Event Bus service and call one of the event delivery methods
+ * The Event Admin service. Plugins wishing to publish events can either
+ * obtain the Event Admin service and call one of the event delivery methods
  * or publish a Qt signal for a specific event topic.
  *
  */
-class ctkEventBus {
-
-public:
-
+struct ctkEventBus
+{
   virtual ~ctkEventBus() {}
 
   /**
-   * Initiate asynchronous delivery of an event. This method returns to the
-   * caller before delivery of the event is completed.
+   * Initiate asynchronous, ordered delivery of an event. This method returns
+   * to the caller before delivery of the event is completed. Events are
+   * delivered in the order that they are received by this method.
    *
    * @param event The event to send to all listeners which subscribe to the
    *        topic of the event.
@@ -77,12 +76,12 @@ public:
    * which matches the topic string and LDAP search expression contained
    * in the properties.
    *
-   * Slots should be registered with a property EventConstants::EVENT_TOPIC.
+   * Slots should be registered with a property ctkEventConstants::EVENT_TOPIC.
    * The value being a QString or QStringList object that describes which
    * topics the slot is interested in. A wildcard (’*’ \u002A) may be used as
    * the last token of a topic name, for example com/action&#47*. This matches any
    * topic that shares the same first tokens. For example, com/action&#47* matches
-   * com/action/listen. Slot which have not been specified with the EVENT_TOPIC
+   * com/action/listen. Slots which have not been specified with the EVENT_TOPIC
    * property must not receive events.
    * The value of each entry in the EVENT_TOPIC property must conform to the
    * following grammar:
@@ -90,13 +89,13 @@ public:
    * topic-scope ::= ’*’ | ( topic ’&#47*’ ? )
    * \endverbatim
    *
-   * Slots can also be registered with a property named EventConstants::EVENT_FILTER.
+   * Slots can also be registered with a property named ctkEventConstants::EVENT_FILTER.
    * The value of this property must be a string containing a filter specification.
    * Any of the event's properties can be used in the filter expression.
    * Each slot is notified for any event which belongs to the topics the
    * slot has expressed an interest in. If the handler has defined a
    * EVENT_FILTER property then the event properties must also match the filter
-   * expression. If the filter is an error, then the Event Bus service
+   * expression. If the filter is an error, then the Event Admin service
    * should log a warning and further ignore the registered slot.
    *
    * @param subscriber The owner of the slot.
@@ -119,6 +118,6 @@ public:
 };
 
 
-Q_DECLARE_INTERFACE(ctkEventBus, "org.commontk.core.ctkEventBus")
+Q_DECLARE_INTERFACE(ctkEventBus, "org.commontk.service.event.EventAdmin")
 
 #endif // CTKEVENTBUS_H

Libs/PluginFramework/service/event/ctkEventConstants.cpp

@@ -22,11 +22,24 @@
 #include "ctkEventConstants.h"
 
 
-const QString EventConstants::EVENT_TOPIC = "event.topics";
-const QString EventConstants::EVENT_FILTER = "event.filter";
-
-const QString EventConstants::PLUGIN_SYMBOLICNAME = "plugin.symbolicName";
-const QString EventConstants::PLUGIN_ID = "plugin.id";
-const QString EventConstants::PLUGIN = "plugin";
-const QString EventConstants::PLUGIN_VERSION = "plugin.version";
-
+const QString ctkEventConstants::EVENT_TOPIC = "event.topics";
+const QString ctkEventConstants::EVENT_FILTER = "event.filter";
+
+const QString ctkEventConstants::EVENT_DELIVERY = "event.delivery";
+const QString ctkEventConstants::DELIVERY_ASYNC_ORDERED = "async.ordered";
+const QString ctkEventConstants::DELIVERY_ASYNC_UNORDERED = "async.unordered";
+
+const QString ctkEventConstants::PLUGIN_SYMBOLICNAME = "plugin.symbolicName";
+const QString ctkEventConstants::PLUGIN_ID = "plugin.id";
+const QString ctkEventConstants::PLUGIN = "plugin";
+const QString ctkEventConstants::PLUGIN_VERSION = "plugin.version";
+
+const QString ctkEventConstants::EXCEPTION = "exception";
+const QString ctkEventConstants::EXCEPTION_CLASS = "exception.class";
+const QString ctkEventConstants::EXCEPTION_MESSAGE = "exception.message";
+const QString ctkEventConstants::MESSAGE = "message";
+const QString ctkEventConstants::SERVICE = "service";
+const QString ctkEventConstants::SERVICE_ID = "service.id";
+const QString ctkEventConstants::SERVICE_OBJECTCLASS = "service.objectClass";
+const QString ctkEventConstants::SERVICE_PID = "service.pid";
+const QString ctkEventConstants::TIMESTAMP = "timestamp";

Libs/PluginFramework/service/event/ctkEventConstants.h

@@ -27,11 +27,12 @@
 #include "ctkPluginFrameworkExport.h"
 
 /**
- * Defines standard names for event properties
+ * Defines standard names for <code>ctkEventHandler</code> and Qt event slot properties.
  *
- * \see ctkEventBus::subscribeSlot()
+ * \see ctkEventHandler
+ * \see ctkEventAdmin::subscribeSlot()
  */
-struct CTK_PLUGINFW_EXPORT EventConstants {
+struct CTK_PLUGINFW_EXPORT ctkEventConstants {
 
   /**
    * Qt slot property (named <code>event.topics</code>)
@@ -76,28 +77,133 @@ struct CTK_PLUGINFW_EXPORT EventConstants {
   static const QString EVENT_FILTER; // = "event.filter"
 
   /**
+   * Service Registration property specifying the delivery qualities requested
+   * by an Event Handler service.
+   * <p>
+   * Event handlers MAY be registered with this property. Each value of this
+   * property is a string specifying a delivery quality for the Event handler.
+   *
+   * <p>
+   * The value of this property must be of type <code>QString</code> or
+   * <code>QStringList</code>.
+   *
+   * @see #DELIVERY_ASYNC_ORDERED
+   * @see #DELIVERY_ASYNC_UNORDERED
+   */
+  static const QString EVENT_DELIVERY; // = "event.delivery"
+
+  /**
+   * Event Handler delivery quality value specifying the Event Handler
+   * requires asynchronously delivered events be delivered in order. Ordered
+   * delivery is the default for asynchronously delivered events.
+   *
+   * <p>
+   * This delivery quality value is mutually exclusive with
+   * {@link #DELIVERY_ASYNC_UNORDERED}. However, if both this value and
+   * {@link #DELIVERY_ASYNC_UNORDERED} are specified for an event handler,
+   * this value takes precedence.
+   *
+   * @see #EVENT_DELIVERY
+   */
+  static const QString DELIVERY_ASYNC_ORDERED; // = "async.ordered"
+
+  /**
+   * Event Handler delivery quality value specifying the Event Handler does
+   * not require asynchronously delivered events be delivered in order. This
+   * may allow an Event Admin implementation to optimize asynchronous event
+   * delivery by relaxing ordering requirements.
+   *
+   * <p>
+   * This delivery quality value is mutually exclusive with
+   * {@link #DELIVERY_ASYNC_ORDERED}. However, if both this value and
+   * {@link #DELIVERY_ASYNC_ORDERED} are specified for an event handler,
+   * {@link #DELIVERY_ASYNC_ORDERED} takes precedence.
+   *
+   * @see #EVENT_DELIVERY
+   */
+  static const QString DELIVERY_ASYNC_UNORDERED; // = "async.unordered"
+
+  /**
    * The Plugin Symbolic Name of the plugin relevant to the event. The type of
    * the value for this event property is <code>QString</code>.
    */
-  static const QString PLUGIN_SYMBOLICNAME; // = "plugin.symbolicName";
+  static const QString PLUGIN_SYMBOLICNAME; // = "plugin.symbolicName"
 
   /**
    * The Plugin id of the plugin relevant to the event. The type of the value
    * for this event property is <code>long</code>.
    */
-  static const QString PLUGIN_ID; // = "plugin.id";
+  static const QString PLUGIN_ID; // = "plugin.id"
 
   /**
    * The ctkPlugin object of the plugin relevant to the event. The type of the
-   * value for this event property is {@link ctkPlugin}.
+   * value for this event property is <code>QSharedPointer<ctkPlugin></code>.
    */
-  static const QString PLUGIN; // = "plugin";
+  static const QString PLUGIN; // = "plugin"
 
   /**
    * The version of the plugin relevant to the event. The type of the value
    * for this event property is {@link ctkVersion}.
    */
-  static const QString PLUGIN_VERSION; // = "plugin.version";
+  static const QString PLUGIN_VERSION; // = "plugin.version"
+
+  /**
+   * An exception or error. The type of the value for this event property is
+   * <code>ctkRuntimeException</code>.
+   */
+  static const QString EXCEPTION; // = "exception"
+
+  /**
+   * The name of the exception type. Must be equal to the name of the class of
+   * the exception in the event property {@link #EXCEPTION}. The type of the
+   * value for this event property is <code>QString</code>.
+   */
+  static const QString EXCEPTION_CLASS; // = "exception.class"
+
+  /**
+   * The exception message. Must be equal to the result of calling
+   * <code>what()</code> on the exception in the event property
+   * {@link #EXCEPTION}. The type of the value for this event property is
+   * <code>QString</code>.
+   */
+  static const QString EXCEPTION_MESSAGE; // = "exception.message"
+
+  /**
+   * A human-readable message that is usually not localized. The type of the
+   * value for this event property is <code>QString</code>.
+   */
+  static const QString MESSAGE; // = "message"
+
+  /**
+   * A service reference. The type of the value for this event property is
+   * {@link ctkServiceReference}.
+   */
+  static const QString SERVICE; // = "service"
+
+  /**
+   * A service's id. The type of the value for this event property is
+   * <code>long</code>.
+   */
+  static const QString SERVICE_ID; // = ctkPluginConstants::SERVICE_ID
+
+  /**
+   * A service's objectClass. The type of the value for this event property is
+   * <code>QStringList</code>.
+   */
+  static const QString SERVICE_OBJECTCLASS; // = "service.objectClass"
+
+  /**
+   * A service's persistent identity. The type of the value for this event
+   * property is <code>QString</code>.
+   */
+  static const QString SERVICE_PID; // = ctkPluginConstants::SERVICE_PID
+
+  /**
+   * The time when the event occurred, as reported by
+   * <code>QDateTime::currentDateTime()</code>. The type of the value for this
+   * event property is <code>QDateTime</code>.
+   */
+  static const QString TIMESTAMP; // = "timestamp"
 
 };
 

Libs/PluginFramework/service/event/ctkEventHandler.h

@@ -0,0 +1,85 @@
+/*=============================================================================
+
+  Library: CTK
+
+  Copyright (c) 2010 German Cancer Research Center,
+    Division of Medical and Biological Informatics
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+=============================================================================*/
+
+
+#ifndef CTKEVENTHANDLER_H
+#define CTKEVENTHANDLER_H
+
+#include "ctkEvent.h"
+
+/**
+ * Listener for Events.
+ *
+ * <p>
+ * <code>ctkEventHandler</code> objects are registered with the Framework service
+ * registry and are notified with an <code>ctkEvent</code> object when an event
+ * is sent or posted.
+ * <p>
+ * <code>ctkEventHandler</code> objects can inspect the received
+ * <code>ctkEvent</code> object to determine its topic and properties.
+ *
+ * <p>
+ * <code>ctkEventHandler</code> objects must be registered with a service
+ * property {@link ctkEventConstants#EVENT_TOPIC} whose value is the list of topics
+ * in which the event handler is interested.
+ * <p>
+ * For example:
+ *
+ * \code
+ * QStringList topics("com/isv/*");
+ * ctkDictionary props;
+ * props.insert(ctkEventConstants::EVENT_TOPIC, topics);
+ * context->registerService<ctkEventHandler>(this, props);
+ * \endcode
+ *
+ * Event Handler services can also be registered with an
+ * {@link ctkEventConstants#EVENT_FILTER} service property to further filter the
+ * events. If the syntax of this filter is invalid, then the Event Handler must
+ * be ignored by the Event Admin service. The Event Admin service should log a
+ * warning.
+ * <p>
+ * Security Considerations. Plugins wishing to monitor <code>ctkEvent</code>
+ * objects will require <code>ctkServicePermission[ctkEventHandler,REGISTER]</code>
+ * to register a <code>ctkEventHandler</code> service. The plugin must also have
+ * <code>ctkTopicPermission[topic,SUBSCRIBE]</code> for the topic specified in
+ * the event in order to receive the event.
+ *
+ * @see ctkEvent
+ *
+ * @ThreadSafe
+ * @version $Id: 2b8202d10e77b774897c74714115059f46abc7e1 $
+ */
+struct ctkEventHandler
+{
+  virtual ~ctkEventHandler() {}
+
+  /**
+   * Called by the {@link ctkEventAdmin} service to notify the listener of an
+   * event.
+   *
+   * @param event The event that occurred.
+   */
+  virtual void handleEvent(const ctkEvent& event) = 0;
+};
+
+Q_DECLARE_INTERFACE(ctkEventHandler, "org.commontk.service.event.EventHandler")
+
+#endif // CTKEVENTHANDLER_H