Carsten Ziegeler | fc1e692 | 2015-02-05 09:41:52 +0000 | [diff] [blame] | 1 | /* |
| 2 | * Licensed to the Apache Software Foundation (ASF) under one |
| 3 | * or more contributor license agreements. See the NOTICE file |
| 4 | * distributed with this work for additional information |
| 5 | * regarding copyright ownership. The ASF licenses this file |
| 6 | * to you under the Apache License, Version 2.0 (the |
| 7 | * "License"); you may not use this file except in compliance |
| 8 | * with the License. You may obtain a copy of the License at |
| 9 | * |
| 10 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 11 | * |
| 12 | * Unless required by applicable law or agreed to in writing, |
| 13 | * software distributed under the License is distributed on an |
| 14 | * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 15 | * KIND, either express or implied. See the License for the |
| 16 | * specific language governing permissions and limitations |
| 17 | * under the License. |
| 18 | */ |
| 19 | package org.apache.felix.scr; |
| 20 | |
| 21 | |
| 22 | import java.util.Dictionary; |
| 23 | |
| 24 | import org.osgi.framework.Bundle; |
| 25 | import org.osgi.service.component.ComponentInstance; |
| 26 | |
| 27 | |
| 28 | /** |
| 29 | * The <code>Component</code> interface represents a single component managed |
| 30 | * by the Service Component Runtime. Management agents may access the Component |
| 31 | * instances through the {@link ScrService}. |
| 32 | * |
| 33 | * @deprecated Use the ServiceComponentRuntime service. |
| 34 | */ |
| 35 | @Deprecated |
| 36 | public interface Component |
| 37 | { |
| 38 | |
| 39 | /** |
| 40 | * The Component has just been created and is still disabled or it has |
| 41 | * been disabled by calling the {@link #disable()} method (value is 1). |
| 42 | */ |
| 43 | static final int STATE_DISABLED = 1; |
| 44 | |
| 45 | /** |
| 46 | * The Component is being enabled (value is 512). After the component has |
| 47 | * been enabled it enters the {@link #STATE_UNSATISFIED} state. |
| 48 | * @since 1.2 |
| 49 | * @deprecated since 1.8.0 |
| 50 | */ |
| 51 | @Deprecated |
| 52 | static final int STATE_ENABLING = 512; |
| 53 | |
| 54 | /** |
| 55 | * The Component has been enabled and is now going to be activated (value |
| 56 | * is 2). |
| 57 | * @deprecated as of version 1.2 the enabled state is collapsed into the |
| 58 | * {@link #STATE_UNSATISFIED} state. This status code is never returned |
| 59 | * from the {@link #getState()} method. |
| 60 | */ |
| 61 | @Deprecated |
| 62 | static final int STATE_ENABLED = 2; |
| 63 | |
| 64 | /** |
| 65 | * The Component activation failed because any dependency is not satisfied |
| 66 | * (value is 4). |
| 67 | */ |
| 68 | static final int STATE_UNSATISFIED = 4; |
| 69 | |
| 70 | /** |
| 71 | * The Component is currently being activated either because it has been |
| 72 | * enabled or because any dependency which was previously unsatisfied has |
| 73 | * become satisfied (value is 8). |
| 74 | * @deprecated since 1.8.0 transient states are no longer used |
| 75 | */ |
| 76 | @Deprecated |
| 77 | static final int STATE_ACTIVATING = 8; |
| 78 | |
| 79 | /** |
| 80 | * The Component has successfully been activated and is fully functional |
| 81 | * (value is 16). This is the state of immediate components after |
| 82 | * successful activation. Delayed and Service Factory Components enter |
| 83 | * this state when the service instance has actually been instantiated because |
| 84 | * the service has been acquired. |
| 85 | */ |
| 86 | static final int STATE_ACTIVE = 16; |
| 87 | |
| 88 | /** |
| 89 | * The Component has successfully been activated but is a Delayed or Service |
| 90 | * Factory Component pending instantiation on first use (value is 32). |
| 91 | */ |
| 92 | static final int STATE_REGISTERED = 32; |
| 93 | |
| 94 | /** |
| 95 | * The Component is a Component Factory ready to create Component instances |
| 96 | * with the <code>ComponentFactory.newInstance(Dictionary)</code> method |
| 97 | * or (if enabled with the <code>ds.factory.enabled</code> configuration) to |
| 98 | * manage Component instances from configuration data received from the |
| 99 | * Configuration Admin Service (value is 64). |
| 100 | */ |
| 101 | static final int STATE_FACTORY = 64; |
| 102 | |
| 103 | /** |
| 104 | * The Component is being deactivated either because it is being disabled |
| 105 | * or because a dependency is not satisfied any more (value is 128). After |
| 106 | * deactivation the Component enters the {@link #STATE_UNSATISFIED} state. |
| 107 | * @deprecated since 1.8.0 transient states are no longer used |
| 108 | */ |
| 109 | @Deprecated |
| 110 | static final int STATE_DEACTIVATING = 128; |
| 111 | |
| 112 | /** |
| 113 | * The Component is being disabled (value is 1024). After the component has |
| 114 | * been disabled it enters the {@link #STATE_DISABLED} state. |
| 115 | * @since 1.2 |
| 116 | * @deprecated since 1.8.0 transient states are no longer used |
| 117 | */ |
| 118 | @Deprecated |
| 119 | static final int STATE_DISABLING = 1024; |
| 120 | |
| 121 | /** |
| 122 | * The Component is being disposed off (value is 2048). After the component |
| 123 | * has been disposed off it enters the {@link #STATE_DESTROYED} state. |
| 124 | * @since 1.2 |
| 125 | * @deprecated since 1.8.0 transient states are no longer used |
| 126 | */ |
| 127 | @Deprecated |
| 128 | static final int STATE_DISPOSING = 2048; |
| 129 | |
| 130 | /** |
| 131 | * The Component has been destroyed and cannot be used any more (value is |
| 132 | * 256). This state is only used when the bundle declaring the component |
| 133 | * is being stopped and all components have to be removed. |
| 134 | * @deprecated as of version 1.2 this constant has been renamed to |
| 135 | * {@link #STATE_DISPOSED}. |
| 136 | */ |
| 137 | @Deprecated |
| 138 | static final int STATE_DESTROYED = 256; |
| 139 | |
| 140 | /** |
| 141 | * The Component has been disposed off and cannot be used any more (value is |
| 142 | * 256). This state is used when the bundle declaring the component |
| 143 | * is being stopped and all components have to be removed. This status is |
| 144 | * also the final status of a component after the |
| 145 | * <code>ComponentInstance.dispose()</code> method has been called. |
| 146 | * @since 1.2 |
| 147 | */ |
| 148 | static final int STATE_DISPOSED = 256; |
| 149 | |
| 150 | |
| 151 | /** |
| 152 | * Returns the component ID of this component. This ID is managed by the |
| 153 | * SCR. If the component is not currently enabled the ID might not be |
| 154 | * assigned to the component (yet) and this method will return -1 in this |
| 155 | * case. |
| 156 | */ |
| 157 | long getId(); |
| 158 | |
| 159 | |
| 160 | /** |
| 161 | * Returns the name of the component, which is also used as the service PID. |
| 162 | * This method provides access to the <code>name</code> attribute of the |
| 163 | * <code>component</code> element. |
| 164 | */ |
| 165 | String getName(); |
| 166 | |
| 167 | |
| 168 | /** |
| 169 | * Returns the current state of the Component, which is one of the |
| 170 | * <code>STATE_*</code> constants defined in this interface. |
| 171 | */ |
| 172 | int getState(); |
| 173 | |
| 174 | |
| 175 | /** |
| 176 | * Returns the <code>Bundle</code> declaring this component. |
| 177 | */ |
| 178 | Bundle getBundle(); |
| 179 | |
| 180 | |
| 181 | /** |
| 182 | * Returns the component factory name or <code>null</code> if this component |
| 183 | * is not defined as a component factory. This method provides access to |
| 184 | * the <code>factory</code> attribute of the <code>component</code> |
| 185 | * element. |
| 186 | */ |
| 187 | String getFactory(); |
| 188 | |
| 189 | |
| 190 | /** |
| 191 | * Returns <code>true</code> if this component is a service factory. This |
| 192 | * method returns the value of the <code>serviceFactory</code> attribute of |
| 193 | * the <code>service</code> element. If the component has no service |
| 194 | * element, this method returns <code>false</code>. |
| 195 | */ |
| 196 | boolean isServiceFactory(); |
| 197 | |
| 198 | |
| 199 | /** |
| 200 | * Returns the class name of the Component implementation. This method |
| 201 | * provides access to the <code>class</code> attribute of the |
| 202 | * <code>implementation</code> element. |
| 203 | */ |
| 204 | String getClassName(); |
| 205 | |
| 206 | |
| 207 | /** |
| 208 | * Returns whether the Component is declared to be enabled initially. This |
| 209 | * method provides access to the <code>enabled</code> attribute of the |
| 210 | * <code>component</code> element. |
| 211 | */ |
| 212 | boolean isDefaultEnabled(); |
| 213 | |
| 214 | |
| 215 | /** |
| 216 | * Returns whether the Component is an Immediate or a Delayed Component. |
| 217 | * This method provides access to the <code>immediate</code> attribute of |
| 218 | * the <code>component</code> element. |
| 219 | */ |
| 220 | boolean isImmediate(); |
| 221 | |
| 222 | |
| 223 | /** |
| 224 | * Returns an array of service names provided by this Component or |
| 225 | * <code>null</code> if the Component is not registered as a service. This |
| 226 | * method provides access to the <code>interface</code> attributes of the |
| 227 | * <code>provide</code> elements. |
| 228 | */ |
| 229 | String[] getServices(); |
| 230 | |
| 231 | |
| 232 | /** |
| 233 | * Returns the properties of the Component. The Dictionary returned is a |
| 234 | * private copy of the actual properties and contains the same entries as |
| 235 | * are used to register the Component as a service and are returned by |
| 236 | * the <code>ComponentContext.getProperties()</code> method. |
| 237 | */ |
| 238 | Dictionary getProperties(); |
| 239 | |
| 240 | |
| 241 | /** |
| 242 | * Returns an array of {@link Reference} instances representing the service |
| 243 | * references (or dependencies) of this Component. If the Component has no |
| 244 | * references, <code>null</code> is returned. |
| 245 | */ |
| 246 | Reference[] getReferences(); |
| 247 | |
| 248 | |
| 249 | /** |
| 250 | * Returns the <code>org.osgi.service.component.ComponentInstance</code> |
| 251 | * representing this component or <code>null</code> if this component |
| 252 | * is not been activated yet. |
| 253 | * |
| 254 | * @since 1.2 |
| 255 | */ |
| 256 | ComponentInstance getComponentInstance(); |
| 257 | |
| 258 | |
| 259 | /** |
| 260 | * Returns the name of the method to be called when the component is being |
| 261 | * activated. |
| 262 | * <p> |
| 263 | * This method never returns <code>null</code>, that is, if this method is |
| 264 | * not declared in the component descriptor this method returns the |
| 265 | * default value <i>activate</i>. |
| 266 | * |
| 267 | * @since 1.2 |
| 268 | */ |
| 269 | String getActivate(); |
| 270 | |
| 271 | |
| 272 | /** |
| 273 | * Returns <code>true</code> if the name of the method to be called on |
| 274 | * component activation (see {@link #getActivate()} is declared in the |
| 275 | * component descriptor or not. |
| 276 | * <p> |
| 277 | * For a component declared in a Declarative Services 1.0 descriptor, this |
| 278 | * method always returns <code>false</code>. |
| 279 | * |
| 280 | * @since 1.2 |
| 281 | */ |
| 282 | boolean isActivateDeclared(); |
| 283 | |
| 284 | |
| 285 | /** |
| 286 | * Returns the name of the method to be called when the component is being |
| 287 | * deactivated. |
| 288 | * <p> |
| 289 | * This method never returns <code>null</code>, that is, if this method is |
| 290 | * not declared in the component descriptor this method returns the |
| 291 | * default value <i>deactivate</i>. |
| 292 | * |
| 293 | * @since 1.2 |
| 294 | */ |
| 295 | String getDeactivate(); |
| 296 | |
| 297 | |
| 298 | /** |
| 299 | * Returns <code>true</code> if the name of the method to be called on |
| 300 | * component deactivation (see {@link #getDeactivate()} is declared in the |
| 301 | * component descriptor or not. |
| 302 | * <p> |
| 303 | * For a component declared in a Declarative Services 1.0 descriptor, this |
| 304 | * method always returns <code>false</code>. |
| 305 | * |
| 306 | * @since 1.2 |
| 307 | */ |
| 308 | boolean isDeactivateDeclared(); |
| 309 | |
| 310 | |
| 311 | /** |
| 312 | * Returns the name of the method to be called when the component |
| 313 | * configuration has been updated or <code>null</code> if such a method is |
| 314 | * not declared in the component descriptor. |
| 315 | * <p> |
| 316 | * For a component declared in a Declarative Services 1.0 descriptor, this |
| 317 | * method always returns <code>null</code>. |
| 318 | * |
| 319 | * @since 1.2 |
| 320 | */ |
| 321 | String getModified(); |
| 322 | |
| 323 | |
| 324 | /** |
| 325 | * Returns the configuration policy declared in the component descriptor. |
| 326 | * If the component descriptor is a Declarative Services 1.0 descriptor or |
| 327 | * no configuration policy has been declared, the default value |
| 328 | * <i>optional</i> is returned. |
| 329 | * <p> |
| 330 | * The returned string is one of the three policies defined in the |
| 331 | * Declarative Services specification 1.1: |
| 332 | * <dl> |
| 333 | * <dt>optional</dt> |
| 334 | * <dd>Configuration from the Configuration Admin service is supplied to |
| 335 | * the component if available. Otherwise the component is activated without |
| 336 | * Configuration Admin configuration. This is the default value reflecting |
| 337 | * the behaviour of Declarative Services 1.0</dd> |
| 338 | * <dt>require</dt> |
| 339 | * <dd>Configuration is required. The component remains unsatisfied until |
| 340 | * configuration is available from the Configuration Admin service.</dd> |
| 341 | * <dt>ignore</dt> |
| 342 | * <dd>Configuration is ignored. No Configuration Admin service |
| 343 | * configuration is supplied to the component.</dd> |
| 344 | * </dl> |
| 345 | * |
| 346 | * @since 1.2 |
| 347 | */ |
| 348 | String getConfigurationPolicy(); |
| 349 | |
| 350 | /** |
| 351 | * Returns the configuration pid declared in the component descriptor. |
| 352 | * The value is used to retrieve the component configuration from the |
| 353 | * OSGi configuration admin service. The value returned by this method |
| 354 | * depends on the Declarative Service namespace used by the component: |
| 355 | * <p> |
| 356 | * <dl> |
| 357 | * <dt>DS 1.0</dt> |
| 358 | * <dd>The component name is returned.</dd> |
| 359 | * <dt>DS 1.1</dt> |
| 360 | * <dd>The component name is returned, if it has been specified. If not specified, |
| 361 | * then the default component name is returned (that is the fully qualified component |
| 362 | * class name). |
| 363 | * <dt>DS 1.2</dt> |
| 364 | * <dd>The value of the configuration-pid attribute is returned if it has been specified. |
| 365 | * If not specified, then the same DS 1.1 rules are applied.</dd> |
| 366 | * </dl> |
| 367 | * |
| 368 | * @since 1.2 |
| 369 | */ |
| 370 | String getConfigurationPid(); |
| 371 | |
| 372 | /** |
| 373 | * Returns whether the configuration-pid has been declared in the descriptor |
| 374 | * or not. |
| 375 | * |
| 376 | * @return whether the configuration-pid has method has been declared in the descriptor |
| 377 | * or not. |
| 378 | * @since DS 1.2 |
| 379 | */ |
| 380 | boolean isConfigurationPidDeclared(); |
| 381 | |
| 382 | /** |
| 383 | * Enables this Component if it is disabled. If the Component is not |
| 384 | * currently {@link #STATE_DISABLED disabled} this method has no effect. If |
| 385 | * the Component is {@link #STATE_DESTROYED destroyed}, this method throws |
| 386 | * an <code>IllegalStateException</code>. |
| 387 | * |
| 388 | * @throws IllegalStateException If the Component is destroyed. |
| 389 | */ |
| 390 | void enable(); |
| 391 | |
| 392 | |
| 393 | /** |
| 394 | * Disables this Component if it is enabled. If the Component is already |
| 395 | * {@link #STATE_DISABLED disabled} this method has no effect. If the |
| 396 | * Component is {@link #STATE_DESTROYED destroyed}, this method throws an |
| 397 | * <code>IllegalStateException</code>. |
| 398 | * |
| 399 | * @throws IllegalStateException If the Component is destroyed. |
| 400 | */ |
| 401 | void disable(); |
| 402 | |
| 403 | } |