javax.enterprise.inject

## Interface Instance<T>

- Type Parameters:
    `T` - the required bean type
  All Superinterfaces:
    Iterable<T>, Provider<T>
  All Known Implementing Classes:
    CDI

      public interface Instance<T>
      extends Iterable<T>, 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();

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

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy(T instance)` When called, the container destroys the instance if the active context object for the scope type of the bean supports destroying bean instances.
    `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(Annotation... qualifiers)` Obtains a child `Instance` for the given additional required qualifiers.
    `<U extends T> Instance<U>` | `select(Class<U> subtype, Annotation... qualifiers)` Obtains a child `Instance` for the given required type and additional required qualifiers.
    `<U extends T> Instance<U>` | `select(TypeLiteral<U> subtype, 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(Annotation... qualifiers)

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

      Parameters:
        `qualifiers` - the additional required qualifiers
      Returns:
        the child `Instance`
      Throws:
        `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(Class<U> subtype,
                                         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:
        `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,
                                         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:
        `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.

    - #### destroy

          void destroy(T instance)

      When called, the container destroys the instance if the active context object for the scope type of the bean supports destroying bean instances. All normal scoped built-in contexts support destroying bean instances.

      The instance passed should either be a dependent scoped bean instance, or the client proxy for a normal scoped bean instance.

      Parameters:
        `instance` - the instance to destroy
      Throws:
        `UnsupportedOperationException` - if the active context object for the scope type of the bean does not support destroying bean instances
      Since:
        1.1

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.