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