[weld-commits] Weld SVN: r4270 - api/trunk/cdi/src/main/java/javax/enterprise/inject.
weld-commits at lists.jboss.org
weld-commits at lists.jboss.org
Sat Oct 24 18:56:44 EDT 2009
Author: gavin.king at jboss.com
Date: 2009-10-24 18:56:44 -0400 (Sat, 24 Oct 2009)
New Revision: 4270
Modified:
api/trunk/cdi/src/main/java/javax/enterprise/inject/Instance.java
Log:
javadoc for Instance
Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/Instance.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/Instance.java 2009-10-24 16:44:14 UTC (rev 4269)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/Instance.java 2009-10-24 22:56:44 UTC (rev 4270)
@@ -23,41 +23,135 @@
/**
- * An interface for looking up beans of a particular type.
+ * <p>Allows the application to dynamically obtain instances of
+ * beans with a specified combination of required type and
+ * qualifiers.</p>
*
+ * <p>In certain situations, injection is not the most convenient
+ * way to obtain a contextual reference. For example, it may not
+ * be used when:</p>
+ *
+ * <ul>
+ * <li>the bean type or qualifiers vary dynamically at runtime, or</li>
+ * <li>depending upon the deployment, there may be no bean which
+ * satisfies the type and qualifiers, or</li>
+ * <li>we would like to iterate over all beans of a certain type.</li>
+ * </ul>
+ *
+ * <p>In these situations, an instance of the <tt>Instance</tt> may
+ * be injected:</p>
+ *
+ * <pre>
+ * @Inject Instance<PaymentProcessor> paymentProcessor;
+ * </pre>
+ *
+ * <p>Any combination of qualifiers may be specified at the injection
+ * point:</p>
+ *
+ * <pre>
+ * @Inject @PayBy(CHEQUE) Instance<PaymentProcessor> chequePaymentProcessor;
+ * </pre>
+ *
+ * <p>Or, the {@link javax.enterprise.inject.Any @Any} qualifier may
+ * be used, allowing the application to specify qualifiers dynamically:</p>
+ *
+ * <pre>
+ * @Inject @Any Instance<PaymentProcessor> anyPaymentProcessor;
+ * </pre>
+ *
+ * <p>Finally, the {@link javax.enterprise.inject.New @New} qualifier
+ * may be used, allowing the application to obtain a
+ * {@link javax.enterprise.inject.New @New} qualified bean:</p>
+ *
+ * <pre>
+ * @Inject @New(ChequePaymentProcessor.class)
+ * Instance<PaymentProcessor> chequePaymentProcessor;
+ * </pre>
+ *
+ * <p>For an injected <tt>Instance</tt>:</p>
+ *
+ * <ul>
+ * <li>the <em>required type</em> is the type parameter specified at the
+ * injection point, and</li>
+ * <li>the <em>required qualifiers</em> are the qualifiers specified at
+ * the injection point.</li>
+ * </ul>
+ *
+ * <p>The inherited {@link javax.inject.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 <tt>Instance</tt> was injected, or throws an
+ * {@link javax.enterprise.inject.UnsatisfiedResolutionException} or
+ * {@link javax.enterprise.inject.AmbiguousResolutionException}.</p>
+ *
+ * <pre>PaymentProcessor pp = chequePaymentProcessor.get();</pre>
+ *
+ * <p>The inherited {@link java.lang.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 <tt>Instance</tt> was injected.</p>
+ *
+ * <pre>for (PaymentProcessor pp: anyPaymentProcessor) pp.test();</pre>
+ *
+ * @see {@link javax.inject.Provider#get()}
+ * @see {@link java.lang.Iterable#iterator()}
+ * @see javax.enterprise.inject.AnnotationLiteral
+ * @see javax.enterprise.inject.TypeLiteral
+ *
* @author Gavin King
*
- * @param <T>
- * the type of the event object
+ * @param <T> the required bean type
*/
public interface Instance<T> extends Iterable<T>, Provider<T>
{
+
/**
- * Get an instance of a bean of the specified type.
+ * <p>Obtains a child <tt>Instance</tt> for a given required type and additional
+ * required qualifiers. If no required type is given, the required type is the
+ * same as the parent.
*
- * Additional binding annotations may be specified at the injection point.
+ * @param qualifiers the additional required qualifiers
+ * @return the child <tt>Instance</tt>
+ */
+ public Instance<T> select(Annotation... qualifiers);
+
+ /**
+ * <p>Obtains a child <tt>Instance</tt> for a given required type and additional
+ * required qualifiers. If no required type is given, the required type is the
+ * same as the parent.
*
- * @param bindings
- * Additional binding types
- * @return an instance of a bean of the specified type
- * @throws IllegalArgumentException
- * if two instances of the same binding type are passed
- * @throws IllegalArgumentException
- * if an instance of an annotation that is not a binding type is
- * passed
+ * @param <U> the required type
+ * @param subtype a {@link java.lang.Class} representing the required type
+ * @param qualifiers the additional required qualifiers
+ * @return the child <tt>Instance</tt>
+ */
+ public <U extends T> Instance<U> select(Class<U> subtype, Annotation... qualifiers);
+
+ /**
+ * <p>Obtains a child <tt>Instance</tt> for a given required type and additional
+ * required qualifiers. If no required type is given, the required type is the
+ * same as the parent.
*
+ * @param <U> the required type
+ * @param subtype a {@link javax.enterprise.inject.TypeLiteral} representing the required type
+ * @param qualifiers the additional required qualifiers
+ * @return the child <tt>Instance</tt>
*/
- public T get(Annotation... bindings);
+ public <U extends T> Instance<U> select(TypeLiteral<U> subtype, Annotation... qualifiers);
- public Instance<T> select(Annotation... bindings);
-
- public <U extends T> Instance<U> select(Class<U> subtype, Annotation... bindings);
-
- public <U extends T> Instance<U> select(TypeLiteral<U> subtype, Annotation... bindings);
-
+ /**
+ * @return <tt>true</tt> if there is no bean that matches the required type and
+ * qualifiers and is eligible for injection into the class into which the parent
+ * <tt>Instance</tt> was injected, or <tt>false</tt> otherwise.
+ */
public boolean isUnsatisfied();
+ /**
+ * @return <tt>true</tt> 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 <tt>Instance</tt> was injected, or <tt>false</tt> otherwise.
+ */
public boolean isAmbiguous();
}
More information about the weld-commits
mailing list