Added interface classes for the Log Service.

Libs/PluginFramework/CMakeLists.txt

@@ -94,6 +94,9 @@ SET(KIT_SRCS
   service/cm/ctkManagedService.h
   service/cm/ctkManagedServiceFactory.h
 
+  service/log/ctkLogEntry.h
+  service/log/ctkLogListener.h
+  service/log/ctkLogReaderService.h
   service/log/ctkLogService.cpp
   service/log/ctkLogStream.cpp
   )

Libs/PluginFramework/service/log/ctkLogEntry.h

@@ -0,0 +1,148 @@
+/*=============================================================================
+
+  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 CTKLOGENTRY_H
+#define CTKLOGENTRY_H
+
+#include <QSharedPointer>
+#include <QDateTime>
+
+#include <ctkServiceReference.h>
+#include <ctkRuntimeException.h>
+
+
+/**
+ * Provides methods to access the information contained in an individual Log
+ * Service log entry.
+ *
+ * <p>
+ * A <code>ctkLogEntry</code> object may be acquired from the
+ * <code>ctkLogReaderService#getLog()</code> method or by registering a
+ * <code>ctkLogListener</code> object.
+ *
+ * @ThreadSafe
+ * @see ctkLogReaderService#getLog()
+ * @see ctkLogListener
+ */
+struct ctkLogEntry
+{
+  /**
+   * Returns the plugin that created this <code>ctkLogEntry</code> object.
+   *
+   * @return The plugin that created this <code>ctkLogEntry</code> object;
+   *         null if no plugins is associated with this
+   *         <code>ctkLogEntry</code> object.
+   */
+  virtual QSharedPointer<ctkPlugin> getPlugin() const = 0;
+
+  /**
+   * Returns the <code>ctkServiceReference</code> object for the service associated
+   * with this <code>ctkLogEntry</code> object.
+   *
+   * @return <code>ctkServiceReference</code> object for the service associated
+   *         with this <code>ctkLogEntry</code> object; A default constructed object if no
+   *         <code>ctkServiceReference</code> object was provided.
+   */
+  virtual ctkServiceReference getServiceReference() const = 0;
+
+  /**
+   * Returns the severity level of this <code>ctkLogEntry</code> object.
+   *
+   * <p>
+   * This is one of the severity levels defined by the <code>ctkLogService</code>
+   * interface.
+   *
+   * @return Severity level of this <code>ctkLogEntry</code> object.
+   *
+   * @see ctkLogService#LOG_ERROR
+   * @see ctkLogService#LOG_WARNING
+   * @see ctkLogService#LOG_INFO
+   * @see ctkLogService#LOG_DEBUG
+   */
+  virtual int getLevel() const = 0;
+
+  /**
+   * Returns the human readable message associated with this <code>ctkLogEntry</code>
+   * object.
+   *
+   * @return <code>QString</code> containing the message associated with this
+   *         <code>ctkLogEntry</code> object.
+   */
+  virtual QString getMessage() const = 0;
+
+  /**
+   * Returns the absolute file name of the source file with which this
+   * <code>ctkLogEntry</code> is associated.
+   *
+   * @return The source file name or an empty string if no information
+   *         about the file name is available.
+   */
+  virtual QString getFileName() const = 0;
+
+  /**
+   * Returns the function name of the calling function with which this
+   * <code>ctkLogEntry</code> is associated.
+   *
+   * @return The function name or an empty string if no information
+   *         about the function is available.
+   */
+  virtual QString getFunctionName() const = 0;
+
+  /**
+   * Returns the line number in the source file with which this
+   * <code>ctkLogEntry</code> is associated.
+   *
+   * @return The line number (a positive integer) or 0 if no information
+   *         about the line number is available.
+   */
+  virtual int getLineNumber() const = 0;
+
+  /**
+   * Returns the exception object associated with this <code>ctkLogEntry</code>
+   * object.
+   *
+   * <p>
+   * In some implementations, the returned exception may not be the original
+   * exception. For example, STL exceptions associated with log entries may be wrapped
+   * in a derived ctkRuntimeException. The returned object will attempt to provide as much
+   * information as possible from the original exception object.
+   *
+   * @return <code>ctkRuntimeException</code> object of the exception associated with this
+   *         <code>ctkLogEntry</code>; <code>null</code> if no exception is
+   *         associated with this <code>ctkLogEntry</code> object.
+   */
+  virtual ctkRuntimeException* getException() const = 0;
+
+  /**
+   * Returns the value of <code>QDateTime::currentDateTime()</code> at the time this
+   * <code>ctkLogEntry</code> object was created.
+   *
+   * @return The system time when this <code>ctkLogEntry</code>
+   *         object was created.
+   * @see "QDateTime::currentDateTime()"
+   */
+  virtual QDateTime getTime() const = 0;
+};
+
+typedef QSharedPointer<ctkLogEntry> ctkLogEntryPtr;
+
+#endif // CTKLOGENTRY_H

Libs/PluginFramework/service/log/ctkLogListener.h

@@ -0,0 +1,65 @@
+/*=============================================================================
+
+  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 CTKLOGLISTENER_H
+#define CTKLOGLISTENER_H
+
+#include "ctkLogEntry.h"
+
+/**
+ * Subscribes to <code>ctkLogEntry</code> objects from the <code>ctkLogReaderService</code>.
+ *
+ * <p>
+ * <code>ctkLogListener</code> objects may be registered with the Framework service
+ * registry. After the listener is registered, the <code>logged(ctkLogEntryPtr)</code>
+ * method will be called for each <code>ctkLogEntry</code> object created.
+ *
+ * <p>
+ * Qt slots can also be used to be notified about new <code>ctkLogEntry</code>
+ * objects. See <code>ctkLogReaderService#connectLogListener()</code>.
+ *
+ * @ThreadSafe
+ * @see ctkLogReaderService
+ * @see ctkLogEntry
+ * @see ctkLogReaderService#connectLogListener()
+ * @see ctkLogReaderService#disconnectLogListener()
+ */
+struct ctkLogListener
+{
+  virtual ~ctkLogListener() {}
+
+  /**
+   * Listener method called for each ctkLogEntry object created.
+   *
+   * <p>
+   * As with all event listeners, this method should return to its caller as
+   * soon as possible.
+   *
+   * @param entry A <code>ctkLogEntry</code> object containing log information.
+   * @see ctkLogEntry
+   */
+  virtual void logged(ctkLogEntryPtr entry) = 0;
+};
+
+Q_DECLARE_INTERFACE(ctkLogListener, "org.commontk.service.log.LogListener")
+
+#endif // CTKLOGLISTENER_H

Libs/PluginFramework/service/log/ctkLogReaderService.h

@@ -0,0 +1,101 @@
+/*=============================================================================
+
+  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 CTKLOGREADERSERVICE_H
+#define CTKLOGREADERSERVICE_H
+
+#include <QList>
+
+#include "ctkLogEntry.h"
+
+/**
+ * Provides methods to retrieve <code>ctkLogEntry</code> objects from the log.
+ * <p>
+ * There are three ways to retrieve <code>ctkLogEntry</code> objects:
+ * <ul>
+ * <li>The primary way to retrieve <code>ctkLogEntry</code> objects is to register a
+ * <code>ctkLogListener</code> object with the service registry whose
+ * <code>ctkLogListener#logged()</code> method will
+ * be called for each entry added to the log. This way you do not need to retrieve
+ * any service object to express an interest in log entries.
+ * <li>A Qt slot can be connected to the <code>ctkLogReaderService</code> by using
+ * <code>connectLogListener()</code>.
+ * <li>To retrieve past <code>ctkLogEntry</code> objects, the <code>getLog()</code>
+ * method can be called which will return a QList of all
+ * <code>ctkLogEntry</code> objects in the log.
+ *
+ * @ThreadSafe
+ * @see ctkLogEntry
+ * @see ctkLogListener
+ * @see ctkLogListener#logged(ctkLogEntryPtr)
+ */
+struct ctkLogReaderService
+{
+  virtual ~ctkLogReaderService() {}
+
+  /**
+   * Subscribes to <code>ctkLogEntry</code> objects.
+   *
+   * <p>
+   * This method connects a Qt slot with the Log Reader
+   * Service. The slot must take a <code>ctkLogEntryPtr</code> as the
+   * only argument and will be
+   * called for each <code>ctkLogEntry</code> object placed into the log.
+   *
+   * <p>
+   * When a plugin which connects a Qt slot is stopped, the Log Reader
+   * Service must disconnect all of the plugin's connected slots.
+   *
+   * <p>
+   * If the same slot from the same object is already connected, this
+   * method does nothing.
+   *
+   * @param receiver The object to connect to.
+   * @param slot The name of the slot to be connected.
+   * @returns <code>true</code> if the connection was successfull;
+   *          <code>false</code> otherwise.
+   * @see ctkLogListener
+   * @see ctkLogEntry
+   * @see ctkLogListener#logged(ctkLogEntryPtr)
+   */
+  virtual bool connectLogListener(const QObject* receiver, const char* slot) = 0;
+
+  /**
+   * Returns a QList of all <code>ctkLogEntry</code> objects in
+   * the log.
+   *
+   * <p>
+   * Each element of the QList is a <code>ctkLogEntry</code> object, ordered
+   * with the most recent entry first. Whether the list is of all
+   * <code>ctkLogEntry</code> objects since the Log Service was started or some
+   * recent past is implementation-specific. Also implementation-specific is
+   * whether informational and debug <code>ctkLogEntry</code> objects are included
+   * in the list.
+   * @return A QList of all <code>ctkLogEntry</code> objects in
+   * the log.
+   */
+  virtual QList<ctkLogEntryPtr> getLog() = 0;
+};
+
+Q_DECLARE_INTERFACE(ctkLogReaderService, "org.commontk.service.log.LogReaderService")
+
+#endif // CTKLOGREADERSERVICE_H

Libs/PluginFramework/service/log/ctkLogService.h

@@ -48,11 +48,9 @@
  *
  * @ThreadSafe
  */
-class CTK_PLUGINFW_EXPORT ctkLogService
+struct CTK_PLUGINFW_EXPORT ctkLogService
 {
 
-public:
-
   virtual ~ctkLogService() {}