diff options
Diffstat (limited to 'bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Reference.java')
| -rw-r--r-- | bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Reference.java | 263 |
1 files changed, 213 insertions, 50 deletions
diff --git a/bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Reference.java b/bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Reference.java index 9887c51c7..b13bbef27 100644 --- a/bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Reference.java +++ b/bundles/org.eclipse.osgi.services/src/org/osgi/service/component/annotations/Reference.java @@ -1,5 +1,5 @@ /* - * Copyright (c) OSGi Alliance (2011, 2013). All Rights Reserved. + * Copyright (c) OSGi Alliance (2011, 2014). All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -22,16 +22,17 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Identify the annotated method as a {@code bind} method of a Service - * Component. + * Identify the annotated member as a reference of a Service Component. * * <p> - * The annotated method is a bind method of the Component. + * When the annotation is applied to a method, the method is the bind method of + * the reference. When the annotation is applied to a field, the field will + * contain the bound service(s) of the reference. * * <p> - * This annotation is not processed at runtime by a Service Component Runtime - * implementation. It must be processed by tools and used to add a Component - * Description to the bundle. + * This annotation is not processed at runtime by Service Component Runtime. It + * must be processed by tools and used to add a Component Description to the + * bundle. * * <p> * In the generated Component Description for a component, the references must @@ -42,111 +43,273 @@ import java.lang.annotation.Target; * @author $Id$ */ @Retention(RetentionPolicy.CLASS) -@Target(ElementType.METHOD) +@Target({ElementType.METHOD, ElementType.FIELD}) public @interface Reference { /** * The name of this reference. * * <p> - * If not specified, the name of this reference is based upon the name of - * the method being annotated. If the method name begins with {@code bind}, - * {@code set} or {@code add}, that is removed. + * The name of this reference must be specified when using this annotation + * in the {@link Component#reference()} element since there is no annotated + * member from which the name can be determined. + * + * If not specified, the name of this reference is based upon how this + * annotation is used: + * <ul> + * <li>Annotated method - If the method name begins with {@code bind}, + * {@code set} or {@code add}, that prefix is removed to create the name of + * the reference. Otherwise, the name of the reference is the method name.</li> + * <li>Annotated field - The name of the reference is the field name.</li> + * </ul> * * @see "The name attribute of the reference element of a Component Description." */ String name() default ""; /** - * The type of the service to bind to this reference. + * The type of the service for this reference. + * + * <p> + * The type of the service for this reference must be specified when using + * this annotation in the {@link Component#reference()} element since there + * is no annotated member from which the type of the service can be + * determined. * * <p> - * If not specified, the type of the service to bind is based upon the type - * of the first argument of the method being annotated. + * If not specified, the type of the service for this reference is based + * upon how this annotation is used: + * <ul> + * <li>Annotated method - The type of the service is the type of the first + * argument of the method.</li> + * <li>Annotated field - The type of the service is based upon the type of + * the field being annotated and the cardinality of the reference. If the + * cardinality is either {@link ReferenceCardinality#MULTIPLE 0..n}, or + * {@link ReferenceCardinality#AT_LEAST_ONE 1..n}, the type of the field + * must be one of {@code java.util.Collection}, {@code java.util.List}, or a + * subtype of {@code java.util.Collection} so the type of the service is the + * generic type of the collection. Otherwise, the type of the service is the + * type of the field.</li> + * </ul> * * @see "The interface attribute of the reference element of a Component Description." */ Class<?> service() default Object.class; /** - * The cardinality of the reference. + * The cardinality of this reference. * * <p> - * If not specified, the reference has a - * {@link ReferenceCardinality#MANDATORY 1..1} cardinality. + * If not specified, the cardinality of this reference is based upon how + * this annotation is used: + * <ul> + * <li>Annotated method - The cardinality is + * {@link ReferenceCardinality#MANDATORY 1..1}.</li> + * <li>Annotated field - The cardinality is based on the type of the field. + * If the type is either {@code java.util.Collection}, + * {@code java.util.List}, or a subtype of {@code java.util.Collection}, the + * cardinality is {@link ReferenceCardinality#MULTIPLE 0..n}. Otherwise the + * cardinality is {@link ReferenceCardinality#MANDATORY 1..1}.</li> + * <li>{@link Component#reference()} element - The cardinality is + * {@link ReferenceCardinality#MANDATORY 1..1}.</li> + * </ul> * * @see "The cardinality attribute of the reference element of a Component Description." */ ReferenceCardinality cardinality() default ReferenceCardinality.MANDATORY; /** - * The policy for the reference. + * The policy for this reference. * * <p> - * If not specified, the {@link ReferencePolicy#STATIC STATIC} reference - * policy is used. + * If not specified, the policy of this reference is based upon how this + * annotation is used: + * <ul> + * <li>Annotated method - The policy is {@link ReferencePolicy#STATIC + * STATIC}.</li> + * <li>Annotated field - The policy is based on the modifiers of the field. + * If the field is declared {@code volatile}, the policy is + * {@link ReferencePolicy#DYNAMIC}. Otherwise the policy is + * {@link ReferencePolicy#STATIC STATIC}.</li> + * <li>{@link Component#reference()} element - The policy is + * {@link ReferencePolicy#STATIC STATIC}.</li> + * </ul> * * @see "The policy attribute of the reference element of a Component Description." */ ReferencePolicy policy() default ReferencePolicy.STATIC; /** - * The target filter for the reference. + * The target property for this reference. + * + * <p> + * If not specified, no target property is set. * * @see "The target attribute of the reference element of a Component Description." */ String target() default ""; /** - * The name of the unbind method which is associated with the annotated bind - * method. + * The policy option for this reference. * * <p> - * To declare no unbind method, the value {@code "-"} must be used. + * If not specified, the {@link ReferencePolicyOption#RELUCTANT RELUCTANT} + * reference policy option is used. + * + * @see "The policy-option attribute of the reference element of a Component Description." + * @since 1.2 + */ + ReferencePolicyOption policyOption() default ReferencePolicyOption.RELUCTANT; + + /** + * The reference scope for this reference. * * <p> - * If not specified, the name of the unbind method is derived from the name - * of the annotated bind method. If the annotated method name begins with - * {@code bind}, {@code set} or {@code add}, that is replaced with - * {@code unbind}, {@code unset} or {@code remove}, respectively, to derive - * the unbind method name. Otherwise, {@code un} is prefixed to the - * annotated method name to derive the unbind method name. The unbind method - * is only set if the component type contains a method with the derived - * name. + * If not specified, the {@link ReferenceScope#BUNDLE bundle} reference + * scope is used. * - * @see "The unbind attribute of the reference element of a Component Description." + * @see "The scope attribute of the reference element of a Component Description." + * @since 1.3 */ - String unbind() default ""; + ReferenceScope scope() default ReferenceScope.BUNDLE; + + /* Method injection elements */ /** - * The policy option for the reference. + * The name of the bind method for this reference. * * <p> - * If not specified, the {@link ReferencePolicyOption#RELUCTANT RELUCTANT} - * reference policy option is used. + * If specified and this reference annotates a method, the specified name + * must match the name of the annotated method. * - * @see "The policy-option attribute of the reference element of a Component Description." - * @since 1.2 + * <p> + * If not specified, the name of the bind method is based upon how this + * annotation is used: + * <ul> + * <li>Annotated method - The name of the annotated method is the name of + * the bind method.</li> + * <li>Annotated field - There is no bind method name.</li> + * <li>{@link Component#reference()} element - There is no bind method name. + * </li> + * </ul> + * + * <p> + * If there is a bind method name, the component must contain a method with + * that name. + * + * @see "The bind attribute of the reference element of a Component Description." + * @since 1.3 */ - ReferencePolicyOption policyOption() default ReferencePolicyOption.RELUCTANT; + String bind() default ""; /** - * The name of the updated method which is associated with the annotated - * bind method. + * The name of the updated method for this reference. * * <p> - * To declare no updated method, the value {@code "-"} must be used. + * If not specified, the name of the updated method is based upon how this + * annotation is used: + * <ul> + * <li>Annotated method - The name of the updated method is created from the + * name of the annotated method. If the name of the annotated method begins + * with {@code bind}, {@code set} or {@code add}, that prefix is replaced + * with {@code updated} to create the name candidate for the updated method. + * Otherwise, {@code updated} is prefixed to the name of the annotated + * method to create the name candidate for the updated method. If the + * component type contains a method with the candidate name, the candidate + * name is used as the name of the updated method. To declare no updated + * method when the component type contains a method with the candidate name, + * the value {@code "-"} must be used.</li> + * <li>Annotated field - There is no updated method name.</li> + * <li>{@link Component#reference()} element - There is no updated method + * name.</li> + * </ul> * * <p> - * If not specified, the name of the updated method is derived from the name - * of the annotated bind method. If the annotated method name begins with - * {@code bind}, {@code set} or {@code add}, that is replaced with - * {@code updated} to derive the updated method name. Otherwise, - * {@code updated} is prefixed to the annotated method name to derive the - * updated method name. The updated method is only set if the component type - * contains a method with the derived name. + * If there is an updated method name, the component must contain a method + * with that name. * * @see "The updated attribute of the reference element of a Component Description." * @since 1.2 */ String updated() default ""; + + /** + * The name of the unbind method for this reference. + * + * <p> + * If not specified, the name of the unbind method is based upon how this + * annotation is used: + * <ul> + * <li>Annotated method - The name of the unbind method is created from the + * name of the annotated method. If the name of the annotated method begins + * with {@code bind}, {@code set} or {@code add}, that prefix is replaced + * with {@code unbind}, {@code unset} or {@code remove}, respectively, to + * create the name candidate for the unbind method. Otherwise, {@code un} is + * prefixed to the name of the annotated method to create the name candidate + * for the unbind method. If the component type contains a method with the + * candidate name, the candidate name is used as the name of the unbind + * method. To declare no unbind method when the component type contains a + * method with the candidate name, the value {@code "-"} must be used.</li> + * <li>Annotated field - There is no unbind method name.</li> + * <li>{@link Component#reference()} element - There is no unbind method + * name.</li> + * </ul> + * + * <p> + * If there is an unbind method name, the component must contain a method + * with that name. + * + * @see "The unbind attribute of the reference element of a Component Description." + */ + String unbind() default ""; + + /* Field injection elements */ + + /** + * The name of the field for this reference. + * + * <p> + * If specified and this reference annotates a field, the specified name + * must match the name of the annotated field. + * + * <p> + * If not specified, the name of the field is based upon how this annotation + * is used: + * <ul> + * <li>Annotated method - There is no field name.</li> + * <li>Annotated field - The name of the annotated field is the name of the + * field.</li> + * <li>{@link Component#reference()} element - There is no field name.</li> + * </ul> + * + * <p> + * If there is a field name, the component must contain a field with that + * name. + * + * @see "The field attribute of the reference element of a Component Description." + * @since 1.3 + */ + String field() default ""; + + /** + * The field option for this reference. + * + * <p> + * If not specified, the field option is based upon how this annotation is + * used: + * <ul> + * <li>Annotated method - There is no field option.</li> + * <li>Annotated field - The field option is based upon the policy and + * cardinality of the reference and the modifiers of the field. If the + * policy is {@link ReferencePolicy#DYNAMIC}, the cardinality is + * {@link ReferenceCardinality#MULTIPLE 0..n} or + * {@link ReferenceCardinality#AT_LEAST_ONE 1..n}, and the field is declared + * {@code final}, the field option is {@link FieldOption#UPDATE}. Otherwise, + * the field option is {@link FieldOption#REPLACE}</li> + * <li>{@link Component#reference()} element - There is no field option.</li> + * </ul> + * + * @see "The field-option attribute of the reference element of a Component Description." + * @since 1.3 + */ + FieldOption fieldOption() default FieldOption.REPLACE; } |