1 /*=============================================================================
2 
3   Library: CTK
4 
5   Copyright (c) German Cancer Research Center,
6     Division of Medical and Biological Informatics
7 
8   Licensed under the Apache License, Version 2.0 (the "License");
9   you may not use this file except in compliance with the License.
10   You may obtain a copy of the License at
11 
12     http://www.apache.org/licenses/LICENSE-2.0
13 
14   Unless required by applicable law or agreed to in writing, software
15   distributed under the License is distributed on an "AS IS" BASIS,
16   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   See the License for the specific language governing permissions and
18   limitations under the License.
19 
20 =============================================================================*/
21 
22 
23 #ifndef CTKMANAGEDSERVICEFACTORY_H
24 #define CTKMANAGEDSERVICEFACTORY_H
25 
26 #include <ctkDictionary.h>
27 
28 /**
29  * \ingroup ConfigAdmin
30  *
31  * Manage multiple service instances.
32  *
33  * Plugins registering this interface are giving the Configuration Admin service
34  * the ability to create and configure a number of instances of a service that
35  * the implementing plugin can provide. For example, a plugin implementing a
36  * DHCP server could be instantiated multiple times for different interfaces
37  * using a factory.
38  *
39  * <p>
40  * Each of these <i>service instances </i> is represented, in the persistent
41  * storage of the Configuration Admin service, by a factory
42  * <code>ctkConfiguration</code> object that has a PID. When such a
43  * <code>ctkConfiguration</code> is updated, the Configuration Admin service
44  * calls the <code>ctkManagedServiceFactory</code> updated method with the new
45  * properties. When <code>updated</code> is called with a new PID, the Managed
46  * Service Factory should create a new factory instance based on these
47  * configuration properties. When called with a PID that it has seen before, it
48  * should update that existing service instance with the new configuration
49  * information.
50  *
51  * <p>
52  * In general it is expected that the implementation of this interface will
53  * maintain a data structure that maps PIDs to the factory instances that it has
54  * created. The semantics of a factory instance are defined by the Managed
55  * Service Factory. However, if the factory instance is registered as a service
56  * object with the service registry, its PID should match the PID of the
57  * corresponding <code>ctkConfiguration</code> object (but it should <b>not</b>
58  * be registered as a Managed Service!).
59  *
60  * <p>
61  * An example that demonstrates the use of a factory. It will create serial
62  * ports under command of the Configuration Admin service.
63  *
64  * \code
65  *
66  *   class SerialPortFactory : public QObject, public ctkManagedServiceFactory
67  *   {
68  *
69  *     ctkServiceRegistration registration;
70  *     QHash<QString, SerialPort*> ports;
71  *
72  *     void start(ctkPluginContext* context)
73  *     {
74  *       ctkDictionary properties;
75  *       properties.insert(ctkPluginConstants::SERVICE_PID,
76  *         "com.acme.serialportfactory");
77  *       registration = context->registerService<ctkManagedServiceFactory>(
78  *         this, properties);
79  *     }
80  *
81  *   public:
82  *
83  *     void updated(const QString& pid, const ctkDictionary& properties)
84  *     {
85  *       QString portName = properties["port"].toString();
86  *       SerialPort* port = ports[pid];
87  *       if (port == 0)
88  *       {
89  *         port = new SerialPort();
90  *         ports.insert(pid, port);
91  *         port->open();
92  *       }
93  *       if (port->getPortName() == portName)
94  *         return;
95  *       port->setPortName(portName);
96  *     }
97  *
98  *     void deleted(const QString& pid)
99  *     {
100  *       SerialPort* port = ports[pid];
101  *       port->close();
102  *       ports.remove(pid);
103  *     }
104  *     ...
105  *   };
106  *
107  * \endcode
108  */
109 struct ctkManagedServiceFactory
110 {
~ctkManagedServiceFactoryctkManagedServiceFactory111   virtual ~ctkManagedServiceFactory() {}
112 
113   /**
114    * Return a descriptive name of this factory.
115    *
116    * @return the name for the factory, which might be localized
117    */
118   virtual QString getName() = 0;
119 
120   /**
121    * Create a new instance, or update the configuration of an existing
122    * instance.
123    *
124    * If the PID of the <code>ctkConfiguration</code> object is new for the
125    * Managed Service Factory, then create a new factory instance, using the
126    * configuration <code>properties</code> provided. Else, update the
127    * service instance with the provided <code>properties</code>.
128    *
129    * <p>
130    * If the factory instance is registered with the Framework, then the
131    * configuration <code>properties</code> should be copied to its registry
132    * properties. This is not mandatory and security sensitive properties
133    * should obviously not be copied.
134    *
135    * <p>
136    * If this method throws any <code>exception</code>, the Configuration
137    * Admin service must catch it and should log it.
138    *
139    * <p>
140    * When the implementation of updated detects any kind of error in the
141    * configuration properties, it should create a new
142    * {@link ctkConfigurationException} which describes the problem.
143    *
144    * <p>
145    * The Configuration Admin service must call this method asynchronously.
146    * This implies that implementors of the <code>ctkManagedServiceFactory</code>
147    * class can be assured that the callback will not take place during
148    * registration when they execute the registration in a synchronized method.
149    *
150    * @param pid The PID for this configuration.
151    * @param properties A copy of the configuration properties. This argument
152    *        must not contain the service.pluginLocation" property. The value
153    *        of this property may be obtained from the
154    *        <code>ctkConfiguration#getPluginLocation</code> method.
155    * @throws ctkConfigurationException when the configuration properties are
156    *         invalid.
157    */
158   virtual void updated(const QString& pid, const ctkDictionary& properties) = 0;
159 
160   /**
161    * Remove a factory instance.
162    *
163    * Remove the factory instance associated with the PID. If the instance was
164    * registered with the service registry, it should be unregistered.
165    * <p>
166    * If this method throws any <code>exception</code>, the Configuration
167    * Admin service must catch it and should log it.
168    * <p>
169    * The Configuration Admin service must call this method asynchronously.
170    *
171    * @param pid the PID of the service to be removed
172    */
173   virtual void deleted(const QString& pid) = 0;
174 };
175 
176 Q_DECLARE_INTERFACE(ctkManagedServiceFactory, "org.commontk.service.cm.ManagedServiceFactory")
177 
178 #endif // CTKMANAGEDSERVICEFACTORY_H
179