| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you 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. |
| */ |
| package org.apache.felix.dm.annotation.api; |
| |
| import java.lang.annotation.ElementType; |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.lang.annotation.Target; |
| |
| /** |
| * Annotates an OSGi Component class with its dependencies. Components are the main building |
| * blocks for OSGi applications. They can publish themselves as a service, and/or they can have |
| * dependencies. These dependencies will influence their life cycle as component will only be |
| * activated when all required dependencies are available. |
| * By default, all directly implemented interfaces are registered into the OSGi registry, |
| * and the component is instantiated automatically, when the component bundle is started and |
| * when the component dependencies are available. If you need to take control of when and how |
| * much component instances must be created, then you can use the <code>factoryName</code> |
| * annotation attribute.<p> |
| * If a <code>factoryPid</code> attribute is set, the component is not started automatically |
| * during bundle startup, and the component can then be instantiated multiple times using |
| * Configuration Admin "Factory Configurations". |
| * |
| * <h3>Usage Examples</h3> |
| * |
| * Here is a sample showing a Hello component, which depends on a configuration dependency: |
| * <blockquote> |
| * |
| * <pre> |
| * /** |
| * * This component will be activated once the bundle is started and when all required dependencies |
| * * are available. |
| * */ |
| * @Component |
| * class Hello implements HelloService { |
| * @ConfigurationDependency(pid="my.pid") |
| * void configure(Dictionary conf) { |
| * // Configure or reconfigure our component. |
| * } |
| * |
| * @Start |
| * void start() { |
| * // Our component is starting and is about to be registered in the OSGi registry as a HelloService service. |
| * } |
| * } |
| * </pre> |
| * </blockquote> |
| * |
| * Here is a sample showing how a HelloFactory component may dynamically instantiate several Hello component instances, |
| * using Configuration Admin "Factory Configurations": |
| * <blockquote> |
| * |
| * <pre> |
| * /** |
| * * All component instances will be created/updated/removed by the "HelloFactory" component |
| * */ |
| * @Component(factoryPid="my.factory.pid") |
| * class Hello implements HelloService { |
| * void updated(Dictionary conf) { |
| * // Configure or reconfigure our component. The conf is provided by the factory, |
| * } |
| * |
| * @Start |
| * void start() { |
| * // Our component is starting and is about to be registered in the OSGi registry as a Hello service. |
| * } |
| * } |
| * |
| * /** |
| * * This class will instantiate some Hello component instances |
| * */ |
| * @Component |
| * class HelloFactory { |
| * @ServiceDependency |
| * void bind(ConfigurationAdmin cm) { |
| * // instantiate a first instance of Hello component |
| * Configuration c1 = cm.createFactoryConfiguration("my.factory.pid", "?"); |
| * Hashtable props = new Hashtable(); |
| * newprops.put("key", "value1"); |
| * c1.update(props); |
| * |
| * // instantiate another instance of Hello component |
| * Configuration c2 = cm.createFactoryConfiguration("my.factory.pid", "?"); |
| * props = new Hashtable(); |
| * newprops.put("key", "value2"); |
| * c2.update(props); |
| * |
| * // destroy the two instances of X component |
| * c1.delete(); |
| * c2.delete(); |
| * } |
| * } |
| * </pre> |
| * </blockquote> |
| * |
| * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a> |
| */ |
| @Retention(RetentionPolicy.CLASS) |
| @Target(ElementType.TYPE) |
| public @interface Component |
| { |
| /** |
| * Sets list of provided interfaces. By default, the directly implemented interfaces are provided. |
| * @return the provided interfaces |
| */ |
| Class<?>[] provides() default {}; |
| |
| /** |
| * Sets the static method used to create the components implementation instance. |
| * @return the factory method used to instantiate the component |
| */ |
| String factoryMethod() default ""; |
| |
| /** |
| * Returns the factory pid whose configurations will instantiate the annotated service class. Leaving this attribute |
| * unset means your component is a singleton. If you specify a factory pid, then this component will be instantiated |
| * each time a corresponding factory configuration is created. |
| * |
| * @return the factory pid |
| */ |
| String factoryPid() default ""; |
| |
| /** |
| * The Update method to invoke (defaulting to "updated"), when a factory configuration is created or updated. |
| * Only used if the factoryPid attribute is set. |
| * The updated callback supported signatures are the following:<p> |
| * <ul><li>callback(Dictionary) |
| * <li>callback(Component, Dictionary) |
| * <li>callback(Component, Configuration ... configTypes) // type safe configuration interface(s) |
| * <li>callback(Configuration ... configTypes) // type safe configuration interface(s) |
| * <li>callback(Dictionary, Configuration ... configTypes) // type safe configuration interfaces(s) |
| * <li>callback(Component, Dictionary, Configuration ... configTypes) // type safe configuration interfaces(s) |
| * </ul> |
| * @return the updated callback |
| */ |
| String updated() default "updated"; |
| |
| /** |
| * Returns true if the factory configuration properties must be published to the service properties. |
| * Only used if the factoryPid attribute is set. |
| * @return true if configuration must be published along with the service, false if not. |
| */ |
| boolean propagate() default false; |
| |
| /** |
| * The service scope for the service of this Component. |
| * |
| * <p> |
| * If not specified, the {@link ServiceScope#SINGLETON singleton} service |
| * scope is used. |
| */ |
| ServiceScope scope() default ServiceScope.SINGLETON; |
| |
| /** |
| * Sets list of provided service properties. Since R7 version, Property annotation is repeatable and you can directly |
| * apply it on top of the component class multiple times, instead of using the Component properties attribute. |
| * @return the component properties. |
| * @deprecated you can apply {@link Property} annotation directly on the component class. |
| */ |
| Property[] properties() default {}; |
| } |