Added interfaces for the MetaType specifications.

Libs/PluginFramework/CMakeLists.txt

@@ -101,6 +101,12 @@ SET(KIT_SRCS
   service/log/ctkLogReaderService.h
   service/log/ctkLogService.cpp
   service/log/ctkLogStream.cpp
+
+  service/metatype/ctkAttributeDefinition.cpp
+  service/metatype/ctkMetaTypeInformation.h
+  service/metatype/ctkMetaTypeProvider.cpp
+  service/metatype/ctkMetaTypeService.cpp
+  service/metatype/ctkObjectClassDefinition.h
   )
 
 # Headers that should run through moc

Libs/PluginFramework/service/metatype/ctkAttributeDefinition.cpp

@@ -0,0 +1,25 @@
+/*=============================================================================
+
+  Library: CTK
+
+  Copyright (c) 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.
+
+=============================================================================*/
+
+#include "ctkAttributeDefinition.h"
+
+const int ctkAttributeDefinition::PASSWORD = qRegisterMetaType<ctkAttributeDefinition::Password>("PASSWORD");
+

Libs/PluginFramework/service/metatype/ctkAttributeDefinition.h

@@ -0,0 +1,213 @@
+/*=============================================================================
+
+  Library: CTK
+
+  Copyright (c) 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 CTKATTRIBUTEDEFINITION_H
+#define CTKATTRIBUTEDEFINITION_H
+
+#include <QSharedPointer>
+#include <QMetaType>
+#include <QString>
+#include <QVariant>
+
+#include <ctkPluginFrameworkExport.h>
+
+/**
+ * An interface to describe an attribute.
+ *
+ * <p>
+ * An {@code ctkAttributeDefinition} object defines a description of the data type
+ * of a property/attribute.
+ */
+struct CTK_PLUGINFW_EXPORT ctkAttributeDefinition
+{
+  typedef QVariant::Type Type;
+
+  static const int PASSWORD;
+
+  /**
+   * The {@code Password} type.
+   *
+   * Attributes of this type must be stored as {@code QString}
+   * or {@code QStringList} objects depending on
+   * getCardinality(). A {@code Password} must be treated as a string but the type
+   * can be used to disguise the information when displayed to a user to
+   * prevent others from seeing it.
+   */
+  struct Password : public QString {
+    Password() : QString() {}
+    Password(const QString& pwd) : QString(pwd) {}
+    Password(const char* pwd) : QString(pwd) {}
+  };
+
+  virtual ~ctkAttributeDefinition() {}
+
+  /**
+   * Get the name of the attribute. This name may be localized.
+   *
+   * @return The localized name of the definition.
+   */
+  virtual QString getName() const = 0;
+
+  /**
+   * Unique identity for this attribute.
+   *
+   * Attributes share a global namespace in the registry. E.g. an attribute
+   * {@code cn} or {@code commonName} must always be a {@code QString} and the
+   * semantics are always a name of some object. They share this aspect with
+   * LDAP/X.500 attributes. In these standards the OSI Object Identifier (OID)
+   * is used to uniquely identify an attribute. If such an OID exists, (which
+   * can be requested at several standard organisations and many companies
+   * already have a node in the tree) it can be returned here. Otherwise, a
+   * unique id should be returned which can be a class name combined witha a reverse
+   * domain name or generated with a GUID algorithm. Note that all LDAP
+   * defined attributes already have an OID. It is strongly advised to define
+   * the attributes from existing LDAP schemes which will give the OID. Many
+   * such schemes exist ranging from postal addresses to DHCP parameters.
+   *
+   * @return The id or oid
+   */
+  virtual QString getID() const = 0;
+
+  /**
+   * Return a description of this attribute.
+   *
+   * The description may be localized and must describe the semantics of this
+   * type and any constraints.
+   *
+   * @return The localized description of the definition.
+   */
+  virtual QString getDescription() const = 0;
+
+  /**
+   * Return the cardinality of this attribute.
+   *
+   * The CTK Plugin environment handles multi valued attributes in QList
+   * objects. The return value is defined as follows:
+   *
+   * <pre>
+   *
+   *    x = -1     no limit, store in QList
+   *    x &gt; 0   x = max occurrences, store in QList
+   *    x = 0      1 occurrence required
+   *
+   * </pre>
+   *
+   * @return The cardinality of this attribute.
+   */
+  virtual int getCardinality() const = 0;
+
+  /**
+   * Return the type for this attribute.
+   *
+   * <p>
+   * The following types from QVariant::Type are supported:
+   * QVariant::String, QVariant::LongLong, QVariant::Int, QVariant::Char,
+   * QVariant::Double, QVariant::Bool, QVariant::UserType.
+   *
+   * <p>
+   * QVariant::UserType maps to ctkAttributeDefinition::Password only.
+   *
+   * @return The type for this attribute.
+   */
+  virtual int getType() const = 0;
+
+  /**
+   * Return a list of option values that this attribute can take.
+   *
+   * <p>
+   * If the function returns an empty QList, there are no option values
+   * available.
+   *
+   * <p>
+   * Each value must be acceptable to validate() (return "") and must be a
+   * {@code QString} object that can be converted to the data type defined by
+   * getType() for this attribute.
+   *
+   * <p>
+   * This list must be in the same sequence as {@code getOptionLabels()}. I.e.
+   * for each index i in {@code getOptionValues}, i in {@code
+   * getOptionLabels()} should be the label.
+   *
+   * @return A list values
+   */
+  virtual QStringList getOptionValues() const = 0;
+
+  /**
+   * Return a list of labels of option values.
+   *
+   * <p>
+   * The purpose of this method is to allow menus with localized labels. It is
+   * associated with {@code getOptionValues}. The labels returned here are
+   * ordered in the same way as the values in that method.
+   *
+   * <p>
+   * If the function returns an empty list, there are no option labels
+   * available.
+   * <p>
+   * This list must be in the same sequence as the {@code getOptionValues()}
+   * method. I.e. for each index i in {@code getOptionLabels}, i in {@code
+   * getOptionValues()} should be the associated value.
+   *
+   * @return A list values
+   */
+  virtual QStringList getOptionLabels() const = 0;
+
+  /**
+   * Validate an attribute in {@code QString} form.
+   *
+   * An attribute might be further constrained in value. This method will
+   * attempt to validate the attribute according to these constraints. It can
+   * return three different values:
+   *
+   * <pre>
+   *  a null QString     No validation present
+   *  an empty QString   No problems detected
+   *  "..."              A localized description of why the value is wrong
+   * </pre>
+   *
+   * @param value The value before turning it into the basic data type
+   * @return a null QString, an empty QString, or another QString
+   */
+  virtual QString validate(const QString& value) const = 0;
+
+  /**
+   * Return a default for this attribute.
+   *
+   * The object must be of the appropriate type as defined by the cardinality
+   * and {@code getType()}. The return type is a QStringList
+   * object whose entries can be converted to the appropriate type. The cardinality of
+   * the return list must follow the absolute cardinality of this type. E.g.
+   * if the cardinality = 0, the list must contain 1 element. If the
+   * cardinality is 1, it must contain 0 or 1 elements. Note that the special case of a 0
+   * cardinality, meaning a single value, does not allow lists of
+   * 0 elements, except for signalling that no default exists.
+   *
+   * @return Return a default value or an empty list if no default exists.
+   */
+  virtual QStringList getDefaultValue() const = 0;
+};
+
+typedef QSharedPointer<ctkAttributeDefinition> ctkAttributeDefinitionPtr;
+
+Q_DECLARE_METATYPE(ctkAttributeDefinition::Password)
+
+#endif // CTKATTRIBUTEDEFINITION_H

Libs/PluginFramework/service/metatype/ctkMetaTypeInformation.h

@@ -0,0 +1,64 @@
+/*=============================================================================
+
+  Library: CTK
+
+  Copyright (c) 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 CTKMETATYPEINFORMATION_H
+#define CTKMETATYPEINFORMATION_H
+
+#include "ctkMetaTypeProvider.h"
+
+#include <QSharedPointer>
+
+class ctkPlugin;
+
+/**
+ * A MetaType Information object is created by the ctkMetaTypeService to return
+ * meta type information for a specific plugin.
+ */
+struct ctkMetaTypeInformation : public ctkMetaTypeProvider
+{
+  /**
+   * Return the PIDs (for ManagedServices) for which ctkObjectClassDefinition
+   * information is available.
+   *
+   * @return List of PIDs.
+   */
+  virtual QStringList getPids() const = 0;
+
+  /**
+   * Return the Factory PIDs (for ManagedServiceFactories) for which
+   * ctkObjectClassDefinition information is available.
+   *
+   * @return List of Factory PIDs.
+   */
+  virtual QStringList getFactoryPids() const = 0;
+
+  /**
+   * Return the plugin for which this object provides meta type information.
+   *
+   * @return Plugin for which this object provides meta type information.
+   */
+  virtual QSharedPointer<ctkPlugin> getPlugin() const = 0;
+};
+
+typedef QSharedPointer<ctkMetaTypeInformation> ctkMetaTypeInformationPtr;
+
+#endif // CTKMETATYPEINFORMATION_H

Libs/PluginFramework/service/metatype/ctkMetaTypeProvider.cpp

@@ -0,0 +1,26 @@
+/*=============================================================================
+
+  Library: CTK
+
+  Copyright (c) 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.
+
+=============================================================================*/
+
+#include "ctkMetaTypeProvider.h"
+
+const QString ctkMetaTypeProvider::METATYPE_PID = "metatype.pid";
+const QString ctkMetaTypeProvider::METATYPE_FACTORY_PID = "metatype.factory.pid";
+

Libs/PluginFramework/service/metatype/ctkMetaTypeProvider.h

@@ -0,0 +1,82 @@
+/*=============================================================================
+
+  Library: CTK
+
+  Copyright (c) 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 CTKMETATYPEPROVIDER_H
+#define CTKMETATYPEPROVIDER_H
+
+#include "ctkObjectClassDefinition.h"
+#include <ctkPluginFrameworkExport.h>
+
+#include <QLocale>
+
+/**
+ * Provides access to metatypes. This interface can be implemented on a Managed
+ * Service or Managed Service Factory as well as registered as a service. When
+ * registered as a service, it must be registered with a
+ * {@link #METATYPE_FACTORY_PID} or {@link #METATYPE_PID} service property (or
+ * both). Any PID mentioned in either of these factories must be a valid argument
+ * to the {@link #getObjectClassDefinition(const QString, const QString)} method.
+ */
+struct CTK_PLUGINFW_EXPORT ctkMetaTypeProvider
+{
+
+  /**
+   * Service property to signal that this service has
+   * {@link ctkObjectClassDefinition} objects for the given PIDs. The type of
+   * this service property is {@code QString}.
+   */
+  static const QString METATYPE_PID; // = "metatype.pid"
+
+  /**
+   * Service property to signal that this service has
+   * {@link ctkObjectClassDefinition} objects for the given factory PIDs. The
+   * type of this service property is {@code QString}.
+   */
+  static const QString METATYPE_FACTORY_PID; // = "metatype.factory.pid"
+
+  virtual ~ctkMetaTypeProvider() {}
+
+  /**
+   * Returns an object class definition for the specified id localized to the
+   * specified locale. If no locale is specified, the default locale is used,
+   * according to the default constructor of QLocale.
+   *
+   * @param id The ID of the requested object class. This can be a pid or
+   *        factory pid returned by getPids or getFactoryPids.
+   * @param locale The locale of the definition
+   * @return A {@code ctkObjectClassDefinition} object.
+   */
+  virtual ctkObjectClassDefinitionPtr getObjectClassDefinition(
+    const QString& id, const QLocale& locale = QLocale()) = 0;
+
+  /**
+   * Return a list of available locales.
+   *
+   * @return A list of QLocale objects.
+   */
+  virtual QList<QLocale> getLocales() const = 0;
+
+};
+
+Q_DECLARE_INTERFACE(ctkMetaTypeProvider, "org.commontk.service.metatype.MetaTypeProvider")
+
+#endif // CTKMETATYPEPROVIDER_H

Libs/PluginFramework/service/metatype/ctkMetaTypeService.cpp

@@ -0,0 +1,25 @@
+/*=============================================================================
+
+  Library: CTK
+
+  Copyright (c) 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.
+
+=============================================================================*/
+
+#include "ctkMetaTypeService.h"
+
+const QString ctkMetaTypeService::METATYPE_DOCUMENTS_LOCATION = "CTK-INF/metatype";
+

Libs/PluginFramework/service/metatype/ctkMetaTypeService.h

@@ -0,0 +1,61 @@
+/*=============================================================================
+
+  Library: CTK
+
+  Copyright (c) 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 CTKMETATYPESERVICE_H
+#define CTKMETATYPESERVICE_H
+
+#include "ctkMetaTypeInformation.h"
+
+/**
+ * The MetaType Service can be used to obtain meta type information for a
+ * plugin. The MetaType Service will examine the specified plugin for meta type
+ * documents to create the returned {@code ctkMetaTypeInformation} object.
+ *
+ * <p>
+ * If the specified plugin does not contain any meta type documents, then a
+ * {@code ctkMetaTypeInformation} object will be returned that wraps any
+ * {@code ctkManagedService} or {@code ctkManagedServiceFactory}
+ * services registered by the specified plugin that implement
+ * {@code ctkMetaTypeProvider}. Thus the MetaType Service can be used to
+ * retrieve meta type information for plugins which contain meta type
+ * documents or which provide their own {@code ctkMetaTypeProvider} objects.
+ */
+struct CTK_PLUGINFW_EXPORT ctkMetaTypeService
+{
+ /**
+  * Return the MetaType information for the specified plugin.
+  *
+  * @param plugin The plugin for which meta type information is requested.
+  * @return A ctkMetaTypeInformation object for the specified plugin.
+  */
+ virtual ctkMetaTypeInformationPtr getMetaTypeInformation(const QSharedPointer<ctkPlugin>& plugin) = 0;
+
+ /**
+  * Location of meta type documents. The MetaType Service will process each
+  * entry in the meta type documents directory.
+  */
+ static const QString METATYPE_DOCUMENTS_LOCATION; // = "CTK-INF/metatype"
+};
+
+Q_DECLARE_INTERFACE(ctkMetaTypeService, "org.commontk.service.metatype.MetaTypeServce")
+
+#endif // CTKMETATYPESERVICE_H

Libs/PluginFramework/service/metatype/ctkObjectClassDefinition.h

@@ -0,0 +1,132 @@
+/*=============================================================================
+
+  Library: CTK
+
+  Copyright (c) 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 CTKOBJECTCLASSDEFINITION_H
+#define CTKOBJECTCLASSDEFINITION_H
+
+#include "ctkAttributeDefinition.h"
+
+/**
+ * Description for the data type information of an objectclass.
+ */
+struct ctkObjectClassDefinition
+{
+
+  enum Filter {
+    /**
+     * Argument for {@code getAttributeDefinitions()}.
+     * <p>
+     * {@code REQUIRED} indicates that only the required definitions are
+     * returned.
+     */
+    REQUIRED,
+    /**
+     * Argument for {@code getAttributeDefinitions()}.
+     * <p>
+     * {@code OPTIONAL} indicates that only the optional definitions are
+     * returned.
+     */
+    OPTIONAL,
+    /**
+     * Argument for {@code getAttributeDefinitions()}.
+     * <p>
+     * {@code ALL} indicates that all the definitions are returned.
+     */
+    ALL
+  };
+
+  virtual ~ctkObjectClassDefinition() {}
+
+ /**
+  * Return the name of this object class.
+  *
+  * The name may be localized.
+  *
+  * @return The name of this object class.
+  */
+  virtual QString getName() const = 0;
+
+ /**
+  * Return the id of this object class.
+  *
+  * <p>
+  * {@code ctkObjectClassDefintion} objects share a global namespace in the
+  * registry. They share this aspect with LDAP/X.500 attributes. In these
+  * standards the OSI Object Identifier (OID) is used to uniquely identify
+  * object classes. If such an OID exists, (which can be requested at several
+  * standard organisations and many companies already have a node in the
+  * tree) it can be returned here. Otherwise, a unique id should be returned
+  * which can be a class name combined with a reverse domain name, or generated with a
+  * GUID algorithm. Note that all LDAP defined object classes already have an
+  * OID associated. It is strongly advised to define the object classes from
+  * existing LDAP schemes which will give the OID for free. Many such schemes
+  * exist ranging from postal addresses to DHCP parameters.
+  *
+  * @return The id of this object class.
+  */
+  virtual QString getID() const = 0;
+
+ /**
+  * Return a description of this object class.
+  *
+  * The description may be localized.
+  *
+  * @return The description of this object class.
+  */
+  virtual QString getDescription() const = 0;
+
+ /**
+  * Return the attribute definitions for this object class.
+  *
+  * <p>
+  * Return a set of attributes. The filter parameter can distinguish between
+  * {@code ALL},{@code REQUIRED} or the {@code OPTIONAL}
+  * attributes.
+  *
+  * @param filter {@code ALL},{@code REQUIRED},{@code OPTIONAL}
+  * @return A list of attribute definitions, which is empty if no
+  *         attributes are selected
+  */
+  virtual QList<ctkAttributeDefinitionPtr> getAttributeDefinitions(Filter filter) = 0;
+
+ /**
+  * Return a QByteArray object that can be used to create an
+  * icon from.
+  *
+  * <p>
+  * Indicate the size and return a QByteAray object containing
+  * an icon. The returned icon maybe larger or smaller than the indicated
+  * size.
+  *
+  * <p>
+  * The icon may depend on the localization.
+  *
+  * @param size Requested size of an icon, e.g. a 16x16 pixels icon then size =
+  *        16
+  * @return A QByteArray holding an icon or an empty QByteArray.
+  */
+  virtual QByteArray getIcon(int size) const = 0;
+};
+
+typedef QSharedPointer<ctkObjectClassDefinition> ctkObjectClassDefinitionPtr;
+
+#endif // CTKOBJECTCLASSDEFINITION_H