| /* |
| * 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; |
| |
| /** |
| * When defining component service properties, one way to achieve this is to apply the {@link Property} annotation on your component class name. |
| * Now, you can also define your own component property type interfaces and apply them directly on your components (instead of the |
| * {@link Property} annotation). The PropertyType annotation is closely similar to standard OSGi r7 declarative service @ComponentPropertyType |
| * (which is also supported by dependency manager annotations). |
| * |
| * <h3>Usage Examples</h3> |
| * |
| * Let’s assume your write an OSGi r7 jax rs servlet context which needs the two following service properties: |
| * |
| * <p><ul> |
| * <li> osgi.http.whiteboard.context.name |
| * <li> osgi.http.whiteboard.context.path |
| * </ul> |
| * |
| * <p> Then you can first define your own annotation (but you could also reuse the default annotations provided by the jaxrs whiteboard r7 api): |
| * (notice that in the annotation, you can define default service property values): |
| * |
| * <blockquote> |
| * <pre> |
| * @PropertyType |
| * @interface ServletContext { |
| * String osgi_http_whiteboard_context_name() default AppServletContext.NAME; |
| * String osgi_http_whiteboard_context_path(); |
| * } |
| * </pre> |
| * </blockquote> |
| * |
| * In the above, the underscore is mapped to ".". |
| * Then you can apply the above annotation on top of your component like this: |
| * |
| * <blockquote> |
| * <pre> |
| * @Component |
| * @ServletContext(osgi_http_whiteboard_context_path="/game") |
| * public class AppServletContext extends ServletContextHelper { |
| * } |
| * </pre> |
| * </blockquote> |
| * |
| * You can also use configuration admin service in order to override the default service properties: |
| * |
| * <blockquote> |
| * <pre> |
| * @Component |
| * @ServletContext(osgi_http_whiteboard_context_path="/game") |
| * public class AppServletContext extends ServletContextHelper { |
| * @ConfigurationDependency(propagate=true, pid="my.pid") |
| * void updated(ServletContext cnf) { |
| * // if some properties are not present in the configuration, then the ones used in the annotation will be used. |
| * // The configuration admin properties, if defined, will override the default configurations defined in the annotations |
| * } |
| * } |
| * </pre> |
| * </blockquote> |
| * |
| * You can also define multiple property type annotations, and possibly single valued annotation. In this case, you can use |
| * the standard R7 PREFIX_ constants in order to specify the property prefix, and the property name will be derived from the |
| * single valued annotation (using camel case convention): |
| * |
| * <blockquote> |
| * <pre> |
| * @PropertyType |
| * @interface ContextName { // will map to "osgi.http.whiteboard.context.name" property name |
| * String PREFIX="osgi.http.whiteboard."; |
| * String value(); |
| * } |
| * |
| * @PropertyType |
| * @interface ContextPath { // will map to "osgi.http.whiteboard.context.path" property name |
| * String PREFIX="osgi.http.whiteboard."; |
| * String value(); |
| * } |
| * |
| * @Component |
| * @ContextName(AppServletContext.NAME) |
| * @ContextPath("/game") |
| * public class AppServletContext extends ServletContextHelper { |
| * } |
| * </pre> |
| * </blockquote> |
| * |
| * Same example as above, but also using configuration admin service in order to override default service properties: Here, as in OSGi r7 declarative service, |
| * you can define a callback method which accepts as arguments all (or some of) the defined property types: |
| * |
| * <blockquote> |
| * <pre> |
| * @Component |
| * @ContextName(AppServletContext.NAME) |
| * @ContextPath("/game") |
| * public class AppServletContext extends ServletContextHelper { |
| * @ConfigurationDependency(propagate=true, pid="my.pid") |
| * void updated(ContextName ctxName, ContextPath ctxPath) { |
| * // if some properties are not present in the configuration, then the ones used in the annotation will be used. |
| * // The configuration admin properties, if defined, will override the default configurations defined in the annotations |
| * } |
| * } |
| * </pre> |
| * </blockquote> |
| * |
| * The following is the same example as above, but this time the configuration callback can also define a Dictionary in the first argument |
| * (in case you want to also get the raw configuration dictionary: |
| * |
| * <blockquote> |
| * <pre> |
| * @Component |
| * @ContextName(AppServletContext.NAME) |
| * @ContextPath("/game") |
| * public class AppServletContext extends ServletContextHelper { |
| * @ConfigurationDependency(propagate=true, pid="my.pid") |
| * void updated(Dictionary<String, Object> rawConfig, ContextName ctxName) { |
| * // if some properties are not present in the configuration, then the ones used in the annotation will be used. |
| * // The configuration admin properties, if defined, will override the default configurations defined in the annotations |
| * } |
| * } |
| * </pre> |
| * </blockquote> |
| * |
| * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a> |
| */ |
| @Retention(RetentionPolicy.CLASS) |
| @Target(ElementType.ANNOTATION_TYPE) |
| public @interface PropertyType { |
| // meta-annotation |
| } |