Reference
Date: 2016-06-25

org.osgi.service.component.annotations

## Annotation Type Reference

-     @Retention(value=CLASS)
      @Target(value={METHOD,FIELD})
      public @interface Reference

  Identify the annotated member as a reference of a Service 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.

  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.

  In the generated Component Description for a component, the references must be ordered in ascending lexicographical order (using `String.compareTo` ) of the reference `name`s.

  See Also:
    "The reference element of a Component Description."

- - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `java.lang.String` | `bind` The name of the bind method for this reference.
    `ReferenceCardinality` | `cardinality` The cardinality of this reference.
    `java.lang.String` | `field` The name of the field for this reference.
    `FieldOption` | `fieldOption` The field option for this reference.
    `java.lang.String` | `name` The name of this reference.
    `ReferencePolicy` | `policy` The policy for this reference.
    `ReferencePolicyOption` | `policyOption` The policy option for this reference.
    `ReferenceScope` | `scope` The reference scope for this reference.
    `java.lang.Class<?>` | `service` The type of the service for this reference.
    `java.lang.String` | `target` The target property for this reference.
    `java.lang.String` | `unbind` The name of the unbind method for this reference.
    `java.lang.String` | `updated` The name of the updated method for this reference.

- - ### Element Detail

    - #### name

          public abstract java.lang.String name

      The name of this reference.

      The name of this reference must be specified when using this annotation in the `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:

      - Annotated method - If the method name begins with `bind`, `set` or `add`, that prefix is removed to create the name of the reference. Otherwise, the name of the reference is the method name.
      - Annotated field - The name of the reference is the field name.
      See Also:
        "The name attribute of the reference element of a Component Description."
      Default:
        ""

    - #### service

          public abstract java.lang.Class<?> service

      The type of the service for this reference.

      The type of the service for this reference must be specified when using this annotation in the `Component.reference()` element since there is no annotated member from which the type of the service can be determined.

      If not specified, the type of the service for this reference is based upon how this annotation is used:

      - Annotated method - The type of the service is the type of the first argument of the method.
      - 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 `0..n`, or `1..n`, the type of the field must be one of `java.util.Collection`, `java.util.List`, or a subtype of `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.
      See Also:
        "The interface attribute of the reference element of a Component Description."
      Default:
        java.lang.Object.class

    - #### cardinality

          public abstract ReferenceCardinality cardinality

      The cardinality of this reference.

      If not specified, the cardinality of this reference is based upon how this annotation is used:

      - Annotated method - The cardinality is `1..1`.
      - Annotated field - The cardinality is based on the type of the field. If the type is either `java.util.Collection`, `java.util.List`, or a subtype of `java.util.Collection`, the cardinality is `0..n`. Otherwise the cardinality is `1..1`.
      - `Component.reference()` element - The cardinality is `1..1`.
      See Also:
        "The cardinality attribute of the reference element of a Component Description."
      Default:
        org.osgi.service.component.annotations.ReferenceCardinality.MANDATORY

    - #### policy

          public abstract ReferencePolicy policy

      The policy for this reference.

      If not specified, the policy of this reference is based upon how this annotation is used:

      - Annotated method - The policy is `STATIC`.
      - Annotated field - The policy is based on the modifiers of the field. If the field is declared `volatile`, the policy is `ReferencePolicy.DYNAMIC`. Otherwise the policy is `STATIC`.
      - `Component.reference()` element - The policy is `STATIC`.
      See Also:
        "The policy attribute of the reference element of a Component Description."
      Default:
        org.osgi.service.component.annotations.ReferencePolicy.STATIC

    - #### target

          public abstract java.lang.String target

      The target property for this reference.

      If not specified, no target property is set.

      See Also:
        "The target attribute of the reference element of a Component Description."
      Default:
        ""

    - #### policyOption

          public abstract ReferencePolicyOption policyOption

      The policy option for this reference.

      If not specified, the `RELUCTANT` reference policy option is used.

      Since:
        1.2
      See Also:
        "The policy-option attribute of the reference element of a Component Description."
      Default:
        org.osgi.service.component.annotations.ReferencePolicyOption.RELUCTANT

    - #### scope

          public abstract ReferenceScope scope

      The reference scope for this reference.

      If not specified, the `bundle` reference scope is used.

      Since:
        1.3
      See Also:
        "The scope attribute of the reference element of a Component Description."
      Default:
        org.osgi.service.component.annotations.ReferenceScope.BUNDLE

    - #### bind

          public abstract java.lang.String bind

      The name of the bind method for this reference.

      If specified and this reference annotates a method, the specified name must match the name of the annotated method.

      If not specified, the name of the bind method is based upon how this annotation is used:

      - Annotated method - The name of the annotated method is the name of the bind method.
      - Annotated field - There is no bind method name.
      - `Component.reference()` element - There is no bind method name.

      If there is a bind method name, the component must contain a method with that name.

      Since:
        1.3
      See Also:
        "The bind attribute of the reference element of a Component Description."
      Default:
        ""

    - #### updated

          public abstract java.lang.String updated

      The name of the updated method for this reference.

      If not specified, the name of the updated method is based upon how this annotation is used:

      - 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 `bind`, `set` or `add`, that prefix is replaced with `updated` to create the name candidate for the updated method. Otherwise, `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 `"-"` must be used.
      - Annotated field - There is no updated method name.
      - `Component.reference()` element - There is no updated method name.

      If there is an updated method name, the component must contain a method with that name.

      Since:
        1.2
      See Also:
        "The updated attribute of the reference element of a Component Description."
      Default:
        ""

    - #### unbind

          public abstract java.lang.String unbind

      The name of the unbind method for this reference.

      If not specified, the name of the unbind method is based upon how this annotation is used:

      - 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 `bind`, `set` or `add`, that prefix is replaced with `unbind`, `unset` or `remove`, respectively, to create the name candidate for the unbind method. Otherwise, `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 `"-"` must be used.
      - Annotated field - There is no unbind method name.
      - `Component.reference()` element - There is no unbind method name.

      If there is an unbind method name, the component must contain a method with that name.

      See Also:
        "The unbind attribute of the reference element of a Component Description."
      Default:
        ""

    - #### field

          public abstract java.lang.String field

      The name of the field for this reference.

      If specified and this reference annotates a field, the specified name must match the name of the annotated field.

      If not specified, the name of the field is based upon how this annotation is used:

      - Annotated method - There is no field name.
      - Annotated field - The name of the annotated field is the name of the field.
      - `Component.reference()` element - There is no field name.

      If there is a field name, the component must contain a field with that name.

      Since:
        1.3
      See Also:
        "The field attribute of the reference element of a Component Description."
      Default:
        ""

    - #### fieldOption

          public abstract FieldOption fieldOption

      The field option for this reference.

      If not specified, the field option is based upon how this annotation is used:

      - Annotated method - There is no field option.
      - 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 `ReferencePolicy.DYNAMIC`, the cardinality is `0..n` or `1..n`, and the field is declared `final`, the field option is `FieldOption.UPDATE`. Otherwise, the field option is `FieldOption.REPLACE`
      - `Component.reference()` element - There is no field option.
      Since:
        1.3
      See Also:
        "The field-option attribute of the reference element of a Component Description."
      Default:
        org.osgi.service.component.annotations.FieldOption.REPLACE