[weld-commits] Weld SVN: r4358 - api/trunk/cdi/src/main/java/javax/enterprise/inject/spi.
weld-commits at lists.jboss.org
weld-commits at lists.jboss.org
Wed Oct 28 14:00:04 EDT 2009
Author: dallen6
Date: 2009-10-28 14:00:04 -0400 (Wed, 28 Oct 2009)
New Revision: 4358
Modified:
api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeanManager.java
Log:
Updated JavaDocs on BeanManager interface
Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeanManager.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeanManager.java 2009-10-28 17:56:15 UTC (rev 4357)
+++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeanManager.java 2009-10-28 18:00:04 UTC (rev 4358)
@@ -32,15 +32,40 @@
import javax.enterprise.inject.UnsatisfiedResolutionException;
/**
- * The contract between the application and the manager. Also the contract
- * between the manager and Bean, Context and Observer objects.
+ * <p>
+ * This interface provides operations for obtaining contextual references for
+ * beans, along with many other operations of use to portable extensions.
+ * Occasionally it is necessary to use this programmatic API to fully utilize
+ * portable extensions in the Contexts and Dependency Injection for the Java EE
+ * platform standard.
+ * </p>
+ * <p>
+ * The container provides a built-in bean with bean type BeanManager, scope
+ * {@literal @}{@link javax.enterprise.context.Dependent} and qualifier
+ * {@literal @}{@link javax.enterprise.inject.Default}. The built-in
+ * implementation is a {@linkplain PassivationCapable passivation capable}
+ * dependency. Thus, any bean may obtain an instance of BeanManager by injecting
+ * it:
+ * </p>
*
- * The application should not normally need to call this interface.
+ * <pre>
+ * @Inject
+ * BeanManager manager;
+ * </pre>
+ * <p>
+ * Java EE components may also obtain an instance of BeanManager from
+ * {@linkplain javax.naming JNDI} by looking up the name {@code
+ * java:comp/BeanManager}.
+ * </p>
+ * <p>
+ * Any operation of BeanManager may be called at any time during the execution
+ * of the application.
+ * </p>
*
* @author Gavin King
* @author Pete Muir
* @author Clint Popetz
- *
+ * @author David Allen
*/
public interface BeanManager
{
@@ -48,7 +73,7 @@
/**
* Obtains a contextual reference for a given bean and a given bean type.
*
- * @param bean the Bean object representing the bean
+ * @param bean the {@link Bean} object representing the bean
* @param beanType a bean type that must be implemented by any proxy that is
* returned
* @return a contextual reference representing the bean
@@ -58,10 +83,9 @@
public Object getReference(Bean<?> bean, Type beanType, CreationalContext<?> ctx);
/**
- * Obtains an instance of bean for a given injection point.
+ * Obtains an instance of bean for a given injection point. This method
+ * should not be called by an application.
*
- * This method should not be called by an application.
- *
* @param ij the injection point the instance is needed for
* @param ctx the context in which the injection is occurring
* @return an instance of the bean
@@ -81,12 +105,11 @@
public <T> CreationalContext<T> createCreationalContext(Contextual<T> contextual);
/**
- * Returns the set of beans which match the given required type and qualifiers
- * and are accessible to the class into which the BeanManager was injected,
- * according to the rules of typesafe resolution.
+ * Returns the set of beans which match the given required type and
+ * qualifiers and are accessible to the class into which the BeanManager was
+ * injected, according to the rules of typesafe resolution. Typesafe
+ * resolution usually occurs at container deployment time.
*
- * Typesafe resolution usually occurs at container deployment time.
- *
* @param beanType the type of the beans to be resolved
* @param qualifiers the qualifiers used to restrict the matched beans. If no
* qualifiers are passed to getBeans(), the default binding @Current
@@ -112,11 +135,13 @@
public Set<Bean<?>> getBeans(String name);
/**
- * Returns the Bean object representing the most specialized enabled bean
- * registered with the container that specializes the given bean,
+ * Returns the {@link Bean} object representing the
+ * most specialized enabled bean registered with the container that
+ * specializes the given bean,
*
- * @param <X> The type of the bean
- * @param bean The Bean representation of the bean.
+ * @param <X> the type of the bean
+ * @param bean the {@link Bean} representation of the
+ * bean.
* @return the most specialized enabled bean
*/
public <X> Bean<? extends X> getMostSpecializedBean(Bean<X> bean);
@@ -129,15 +154,15 @@
/**
* Apply the ambiguous dependency resolution rules
*
- * @param <X> The type of the bean
- * @param beans A set of beans of the given type
+ * @param <X> the type of the bean
+ * @param beans a set of beans of the given type
* @throws AmbiguousResolutionException if the ambiguous dependency
* resolution rules fail
*/
public <X> Bean<? extends X> resolve(Set<Bean<? extends X>> beans);
/**
- * Validates the dependency
+ * Validates the injection point dependency.
*
* @param injectionPoint the injection point to validate
* @throws an InjectionException if there is a deployment problem (for
@@ -147,10 +172,11 @@
public void validate(InjectionPoint injectionPoint);
/**
- * Fire an event
+ * Fires an event and notifies observers.
*
* @param event the event object
- * @param qualifiers the event qualifiers used to restrict the observers matched
+ * @param qualifiers the event qualifiers used to restrict the observers
+ * matched
* @throws IllegalArgumentException if the runtime type of the event object
* contains a type variable
* @throws IllegalArgumentException if two instances of the same binding type
@@ -178,7 +204,7 @@
/**
* Obtains an ordered list of enabled decorators for a set of bean types and
- * a set of qualifiers
+ * a set of qualifiers.
*
* @param types the set of bean types of the decorated bean
* @param qualifiers the qualifiers declared by the decorated bean
@@ -192,11 +218,12 @@
public List<Decorator<?>> resolveDecorators(Set<Type> types, Annotation... qualifiers);
/**
- * Obtains an ordered list of enabled interceptors for a set interceptor
- * bindings
+ * Obtains an ordered list of enabled interceptors for a set of interceptor
+ * bindings.
*
* @param type the type of the interception
- * @param interceptorBindings the bindings used to restrict the matched interceptors
+ * @param interceptorBindings the bindings used to restrict the matched
+ * interceptors
* @return the resolved interceptors
* @throws IllegalArgumentException if no interceptor binding type is passed
* @throws IllegalArgumentException if an annotation which is not a
@@ -207,100 +234,153 @@
public List<Interceptor<?>> resolveInterceptors(InterceptionType type, Annotation... interceptorBindings);
/**
- * Determine if the given annotationType is a scope type
+ * Tests the given annotationType to determine if it is a
+ * {@linkplain javax.enterprise.context scope type}.
+ *
+ * @param annotationType the annotation to test
+ * @return true if the annotation is a {@linkplain javax.enterprise.context
+ * scope type}
*/
public boolean isScope(Class<? extends Annotation> annotationType);
-
+
+ /**
+ * Tests the given annotationType to determine if it is a normal
+ * {@linkplain javax.enterprise.context scope type}.
+ *
+ * @param annotationType the annotation to test
+ * @return true if the annotation is a normal
+ * {@linkplain javax.enterprise.context scope type}
+ */
public boolean isNormalScope(Class<? extends Annotation> annotationType);
-
+
+ /**
+ * Tests the given annotationType to determine if it is a passivating
+ * {@linkplain javax.enterprise.context scope type}.
+ *
+ * @param annotationType the annotation to test
+ * @return true if the annotation is a passivating
+ * {@linkplain javax.enterprise.context scope type}
+ */
public boolean isPassivatingScope(Class<? extends Annotation> annotationType);
/**
- * Determine if the given annotationType is a binding type
+ * Tests the given annotationType to determine if it is a
+ * {@linkplain javax.inject.Qualifier qualifier type}.
+ *
+ * @param annotationType the annotation to test
+ * @return true if the annotation is a {@linkplain javax.inject.Qualifier
+ * qualifier type}
*/
public boolean isQualifier(Class<? extends Annotation> annotationType);
/**
- * Determine if the given annotationType is an interceptor binding type
+ * Tests the given annotationType to determine if it is an
+ * {@linkplain Interceptor interceptor} binding type.
+ *
+ * @param annotationType the annotation to test
+ * @return true if the annotationType is a {@linkplain Interceptor
+ * interceptor} binding type
*/
public boolean isInterceptorBindingType(Class<? extends Annotation> annotationType);
/**
- * Determine if the given annotationType is a stereotype
+ * Tests the given annotationType to determine if it is a
+ * {@linkplain javax.enterprise.inject.Stereotype stereotype}.
+ *
+ * @param annotationType the annotation to test
+ * @return true if the annotationType is a
+ * {@linkplain javax.enterprise.inject.Stereotype stereotype}
*/
public boolean isStereotype(Class<? extends Annotation> annotationType);
/**
- * Obtain the set of interceptor binding types meta-annotatinos for the given
- * binding type annotation
+ * Obtains the set of meta-annotations for an {@linkplain Interceptor
+ * interceptor} binding type.
+ *
+ * @param bindingType the annotation for which to obtain meta-annotations
+ * @return the set of meta-annotations for the given {@linkplain Interceptor
+ * interceptor} binding type
*/
public Set<Annotation> getInterceptorBindingTypeDefinition(Class<? extends Annotation> bindingType);
/**
- * Obtain the set of binding types meta-annotations for the given stereotype
- * annotation
+ * Obtains meta-annotations for a
+ * {@linkplain javax.enterprise.inject.Stereotype stereotype}.
+ *
+ * @param stereotype the {@linkplain javax.enterprise.inject.Stereotype
+ * stereotype} for which to obtain meta-annotations
+ * @return the set of meta-annotations for the given
+ * {@linkplain javax.enterprise.inject.Stereotype stereotype}
*/
public Set<Annotation> getStereotypeDefinition(Class<? extends Annotation> stereotype);
-
+
/**
- * Obtain an active context instance for the given scope type.
+ * Obtains an active {@linkplain javax.enterprise.context.spi.Context
+ * context} instance for the given {@linkplain javax.enterprise.context scope
+ * type}.
*
- * @param scopeType the scope to get the context instance for
- * @return the context instance
+ * @param scopeType the {@linkplain javax.enterprise.context scope} to get
+ * the context instance for
+ * @return the {@linkplain javax.enterprise.context.spi.Context context}
+ * instance
* @throws ContextNotActiveException if no active contexts exist for the
* given scope type
* @throws IllegalArgumentException if more than one active context exists
* for the given scope type
*/
public Context getContext(Class<? extends Annotation> scopeType);
-
+
/**
- * Returns the ELResolver for integration with the servlet engine and JSF
- * implementation This resolver will return a contextual instance of a bean
- * if the name for resolution resolves to exactly one bean
+ * Returns the {@link javax.el.ELResolver} for integration with the servlet
+ * engine and JSF implementation. This resolver will return a contextual
+ * instance of a bean if the name for resolution resolves to exactly one
+ * bean.
*/
public ELResolver getELResolver();
-
+
/**
- * Returns an ExpressionFactory
+ * Returns a wrapper {@link javax.el.ExpressionFactory} that delegates
+ * {@link javax.el.MethodExpression} and {@link javax.el.ValueExpression}
+ * creation to the given {@link javax.el.ExpressionFactory}. When a Unified
+ * EL expression is evaluated using a {@link javax.el.MethodExpression} or
+ * {@link javax.el.ValueExpression} returned by the wrapper
+ * {@link javax.el.ExpressionFactory}
*
- * @param expressionFactory
- * @return
+ * @param expressionFactory the expression factory to wrap
+ * @return the wrapped {@link javax.el.ExpressionFactory}
*/
public ExpressionFactory wrapExpressionFactory(ExpressionFactory expressionFactory);
-
+
/**
* Get an {@link AnnotatedType} for the given class
+ *
* @param <T> the type
* @param type the type
* @return the {@link AnnotatedType}
*/
public <T> AnnotatedType<T> createAnnotatedType(Class<T> type);
-
+
/**
* Returns an InjectionTarget to allow injection into custom beans or
- * non-contextual instances by portable extensions.
+ * non-contextual instances by portable extensions. The container ignores the
+ * annotations and types declared by the elements of the actual Java class
+ * and uses the metadata provided via the Annotated interface instead.
*
- * The container ignores the annotations and types declared by the elements
- * of the actual Java class and uses the metadata provided via the Annotated
- * interface instead.
- *
- * @param <T> The type of the AnnotatedType to inspect
- * @param type The AnnotatedType to inspect
+ * @param <T> the type of the AnnotatedType to inspect
+ * @param type the AnnotatedType to inspect
* @returns a container provided instance of InjectionTarget for the given
* type
* @throws IllegalArgumentException if there is a definition error associated
* with any injection point of the type.
*/
public <T> InjectionTarget<T> createInjectionTarget(AnnotatedType<T> type);
-
+
/**
* Allows a new bean to be registered. This fires a ProcessBean event and
* then registers a new bean with the container, thereby making it available
- * for injection into other beans.
+ * for injection into other beans. This method may be called at any time in
+ * the applications lifecycle.
*
- * This method may be called at any time in the applications lifecycle.
- *
* @param bean the bean to register
*/
@Deprecated
More information about the weld-commits
mailing list