Instance
Date: 2015-09-11

javax.enterprise.inject

## Interface Instance<T>

- Type Parameters:
    `T` - the required bean type
  All Superinterfaces:
    java.lang.Iterable<T>, javax.inject.Provider<T>

      public interface Instance<T>
      extends java.lang.Iterable<T>, javax.inject.Provider<T>

  Allows the application to dynamically obtain instances of beans with a specified combination of required type and qualifiers.

  In certain situations, injection is not the most convenient way to obtain a contextual reference. For example, it may not be used when:

  - the bean type or qualifiers vary dynamically at runtime, or
  - depending upon the deployment, there may be no bean which satisfies the type and qualifiers, or
  - we would like to iterate over all beans of a certain type.

  In these situations, an instance of the `Instance` may be injected:

       @Inject Instance<PaymentProcessor> paymentProcessor;

  Any combination of qualifiers may be specified at the injection point:

       @Inject @PayBy(CHEQUE) Instance<PaymentProcessor> chequePaymentProcessor;

  Or, the `@Any` qualifier may be used, allowing the application to specify qualifiers dynamically:

       @Inject @Any Instance<PaymentProcessor> anyPaymentProcessor;

  Finally, the `@New` qualifier may be used, allowing the application to obtain a `@New` qualified bean:

       @Inject @New(ChequePaymentProcessor.class)
       Instance<PaymentProcessor> chequePaymentProcessor;

  For an injected `Instance`:

  - the required type is the type parameter specified at the injection point, and
  - the required qualifiers are the qualifiers specified at the injection point.

  The inherited `Provider.get()` method returns a contextual references for the unique bean that matches the required type and required qualifiers and is eligible for injection into the class into which the parent `Instance` was injected, or throws an `UnsatisfiedResolutionException` or `AmbiguousResolutionException`.

      PaymentProcessor pp = chequePaymentProcessor.get();

  The inherited `Iterable.iterator()` method returns an iterator over contextual references for beans that match the required type and required qualifiers and are eligible for injection into the class into which the parent `Instance` was injected.

      for (PaymentProcessor pp: anyPaymentProcessor) pp.test();

  See Also:
    `Provider.get()`, `Iterable.iterator()`, `AnnotationLiteral`, `TypeLiteral`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isAmbiguous()` Determines if there is more than one bean that matches the required type and qualifiers and is eligible for injection into the class into which the parent `Instance` was injected.
    `boolean` | `isUnsatisfied()` Determines if there is no bean that matches the required type and qualifiers and is eligible for injection into the class into which the parent `Instance` was injected.
    `Instance<T>` | `select(java.lang.annotation.Annotation... qualifiers)` Obtains a child `Instance` for the given additional required qualifiers.
    `<U extends T> Instance<U>` | `select(java.lang.Class<U> subtype, java.lang.annotation.Annotation... qualifiers)` Obtains a child `Instance` for the given required type and additional required qualifiers.
    `<U extends T> Instance<U>` | `select(TypeLiteral<U> subtype, java.lang.annotation.Annotation... qualifiers)` Obtains a child `Instance` for the given required type and additional required qualifiers.

    - ### Methods inherited from interface java.lang.Iterable

      `iterator`

    - ### Methods inherited from interface javax.inject.Provider

      `get`

- - ### Method Detail

    - #### select

          Instance<T> select(java.lang.annotation.Annotation... qualifiers)

      Obtains a child `Instance` for the given additional required qualifiers.

      Parameters:
        `qualifiers` - the additional required qualifiers
      Returns:
        the child `Instance`
      Throws:
        `java.lang.IllegalArgumentException` - if passed two instances of the same qualifier type, or an instance of an annotation that is not a qualifier type

    - #### select

          <U extends T> Instance<U> select(java.lang.Class<U> subtype,
                                         java.lang.annotation.Annotation... qualifiers)

      Obtains a child `Instance` for the given required type and additional required qualifiers.

      Type Parameters:
        `U` - the required type
      Parameters:
        `subtype` - a `Class` representing the required type
        `qualifiers` - the additional required qualifiers
      Returns:
        the child `Instance`
      Throws:
        `java.lang.IllegalArgumentException` - if passed two instances of the same qualifier type, or an instance of an annotation that is not a qualifier type

    - #### select

          <U extends T> Instance<U> select(TypeLiteral<U> subtype,
                                         java.lang.annotation.Annotation... qualifiers)

      Obtains a child `Instance` for the given required type and additional required qualifiers.

      Type Parameters:
        `U` - the required type
      Parameters:
        `subtype` - a `TypeLiteral` representing the required type
        `qualifiers` - the additional required qualifiers
      Returns:
        the child `Instance`
      Throws:
        `java.lang.IllegalArgumentException` - if passed two instances of the same qualifier type, or an instance of an annotation that is not a qualifier type

    - #### isUnsatisfied

          boolean isUnsatisfied()

      Determines if there is no bean that matches the required type and qualifiers and is eligible for injection into the class into which the parent `Instance` was injected.

      Returns:
        `true` if there is no bean that matches the required type and qualifiers and is eligible for injection into the class into which the parent `Instance` was injected, or `false` otherwise.

    - #### isAmbiguous

          boolean isAmbiguous()

      Determines if there is more than one bean that matches the required type and qualifiers and is eligible for injection into the class into which the parent `Instance` was injected.

      Returns:
        `true` if there is more than one bean that matches the required type and qualifiers and is eligible for injection into the class into which the parent `Instance` was injected, or `false` otherwise.