Author: dallen6 Date: 2009-10-25 19:07:53 -0400 (Sun, 25 Oct 2009) New Revision: 4313 Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeforeBeanDiscovery.java api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessAnnotatedType.java api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessBean.java api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessManagedBean.java api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducerField.java api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducerMethod.java api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessSessionBean.java Log: Additional JavaDoc for lifecycle events. Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeforeBeanDiscovery.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeforeBeanDiscovery.java 2009-10-25 18:19:30 UTC (rev 4312) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/BeforeBeanDiscovery.java 2009-10-25 23:07:53 UTC (rev 4313) @@ -46,7 +46,9 @@ * @param scopeType The annotation type to treat as a * {@linkplain javax.enterprise.context scope type} * @param normal Indicates if the scope is normal - * @param passivating Indicates if the scope is passivation capable + * @param passivating Indicates if the scope is + * {@linkplain javax.enterprise.inject.spi.PassivationCapable + * passivation capable} */ public void addScope(Class<? extends Annotation> scopeType, boolean normal, boolean passivating); Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessAnnotatedType.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessAnnotatedType.java 2009-10-25 18:19:30 UTC (rev 4312) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessAnnotatedType.java 2009-10-25 23:07:53 UTC (rev 4313) @@ -16,11 +16,58 @@ */ package javax.enterprise.inject.spi; +/** + * <p> + * The container fires this event for each Java class or interface it discovers, + * before it reads the declared annotations. + * </p> + * <p> + * Any observer of this event is permitted to wrap and/or replace the + * {@link javax.enterprise.inject.spi.AnnotatedType}. The container must use the + * final value of this property, after all observers have been called, to + * discover the types and read the annotations of the program elements. + * </p> + * <p> + * For example, the following observer decorates the + * {@link javax.enterprise.inject.spi.AnnotatedType} for every class that is + * discovered by the container. + * </p> + * + * <pre> + * public &lt;T&gt; void decorateAnnotatedType(@Observes ProcessAnnotatedType&lt;T&gt; pat) + * { + * pat.setAnnotatedType(decorate(pat.getAnnotatedType())); + * } + * </pre> + * <p> + * If any observer method of a {@code ProcessAnnotatedType} event throws an + * exception, the exception is treated as a definition error by the container. + * </p> + * + * @author David Allen + * @see javax.enterprise.inject.spi.AnnotatedType + * @param <X> The class being annotated + */ public interface ProcessAnnotatedType<X> { + /** + * Returns the {@link javax.enterprise.inject.spi.AnnotatedType} object that + * will be used by the container to read the declared annotations. + * + * @return the {@code AnnotatedType} object + */ public AnnotatedType<X> getAnnotatedType(); + /** + * Replaces the {@link javax.enterprise.inject.spi.AnnotatedType}. + * + * @param type the new {@link javax.enterprise.inject.spi.AnnotatedType} + * object to use + */ public void setAnnotatedType(AnnotatedType<X> type); + /** + * Forces the container to ignore this type. + */ public void veto(); } \ No newline at end of file Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessBean.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessBean.java 2009-10-25 18:19:30 UTC (rev 4312) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessBean.java 2009-10-25 23:07:53 UTC (rev 4313) @@ -16,11 +16,68 @@ */ package javax.enterprise.inject.spi; +/** + * <p> + * The container fires an event of this type for each bean it discovers, before + * registering the {@link javax.enterprise.inject.spi.Bean} object. + * </p> + * <p> + * The event object type in the package javax.enterprise.inject.spi depends upon + * what kind of bean was discovered: + * </p> + * <ul> + * <li>For a managed bean with bean class X, the container must raise an event + * of type {@link javax.enterprise.inject.spi.ProcessManagedBean}<X>.</li> + * <li>For a session bean with bean class X, the container must raise an event + * of type {@link javax.enterprise.inject.spi.ProcessSessionBean}<X>.</li> + * <li>For a producer method with method return type X of a bean with bean class + * T, the container must raise an event of type + * {@link javax.enterprise.inject.spi.ProcessProducerMethod}<T, X>.</li> + * <li>For a producer field with field type X of a bean with bean class T, the + * container must raise an event of type + * {@link javax.enterprise.inject.spi.ProcessProducerField}<T, X>.</li> + * </ul> + * <p> + * Resources are considered to be producer fields. + * </p> + * <p> + * If any observer method of a {@code ProcessBean} event throws an exception, + * the exception is treated as a definition error by the container. + * </p> + * + * @author David Allen + * @param <X> The class of the bean + */ public interface ProcessBean<X> { + /** + * Returns the {@link javax.enterprise.inject.spi.AnnotatedType} representing + * the bean class, the {@link javax.enterprise.inject.spi.AnnotatedMethod} + * representing the producer method, or the + * {@link javax.enterprise.inject.spi.AnnotatedField} representing the + * producer field. + * + * @return the {@link javax.enterprise.inject.spi.AnnotatedType} for the bean + * being registered + */ public Annotated getAnnotated(); + /** + * Returns the {@link javax.enterprise.inject.spi.Bean} object that is about + * to be registered. The {@link javax.enterprise.inject.spi.Bean} may + * implement {@link javax.enterprise.inject.spi.Interceptor} or + * {@link javax.decorator.Decorator}. + * + * @return the {@link javax.enterprise.inject.spi.Bean} object about to be + * registered + */ public Bean<X> getBean(); + /** + * Registers a definition error with the container, causing the container to + * abort deployment after bean discovery is complete. + * + * @param t The definition error to register as a {@link java.lang.Throwable} + */ public void addDefinitionError(Throwable t); } Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessManagedBean.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessManagedBean.java 2009-10-25 18:19:30 UTC (rev 4312) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessManagedBean.java 2009-10-25 23:07:53 UTC (rev 4313) @@ -16,7 +16,27 @@ */ package javax.enterprise.inject.spi; +/** + * <p> + * The container fires an event of this type for each managed bean it discovers, + * before registering the {@link javax.enterprise.inject.spi.Bean} object. + * </p> + * <p> + * If any observer method of a {@code ProcessManagedBean} event throws an + * exception, the exception is treated as a definition error by the container. + * </p> + * + * @author David Allen + * @param <X> The class of the bean + */ public interface ProcessManagedBean<X> extends ProcessBean<X> { + /** + * Returns the {@link javax.enterprise.inject.spi.AnnotatedType} representing + * the bean class. + * + * @return the {@link javax.enterprise.inject.spi.AnnotatedType} for the bean + * being registered + */ public AnnotatedType<X> getAnnotatedBeanClass(); } Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducerField.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducerField.java 2009-10-25 18:19:30 UTC (rev 4312) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducerField.java 2009-10-25 23:07:53 UTC (rev 4313) @@ -16,7 +16,29 @@ */ package javax.enterprise.inject.spi; +/** + * <p> + * The container fires an event of this type for each producer field it + * discovers, before registering the corresponding + * {@link javax.enterprise.inject.spi.Bean} object. + * </p> + * <p> + * If any observer method of a {@code ProcessProducerField} event throws an + * exception, the exception is treated as a definition error by the container. + * </p> + * + * @author David Allen + * @param <T> The class of the producer field + * @param <X> The class of the bean representing the producer field + */ public interface ProcessProducerField<T, X> extends ProcessBean<X> { + /** + * Returns the {@link javax.enterprise.inject.spi.AnnotatedField} + * representing the producer field. + * + * @return the {@link javax.enterprise.inject.spi.AnnotatedField} for the + * producer field being registered + */ public AnnotatedField<T> getAnnotatedProducerField(); } \ No newline at end of file Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducerMethod.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducerMethod.java 2009-10-25 18:19:30 UTC (rev 4312) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducerMethod.java 2009-10-25 23:07:53 UTC (rev 4313) @@ -16,9 +16,38 @@ */ package javax.enterprise.inject.spi; +/** + * <p> + * The container fires an event of this type for each producer method it + * discovers, before registering the corresponding + * {@link javax.enterprise.inject.spi.Bean} object. + * </p> + * <p> + * If any observer method of a {@code ProcessProducerMethod} event throws an + * exception, the exception is treated as a definition error by the container. + * </p> + * + * @author David Allen + * @param <T> The class of the return type of the producer method + * @param <X> The class of the bean representing the producer method + */ public interface ProcessProducerMethod<T, X> extends ProcessBean<X> { + /** + * Returns the {@link javax.enterprise.inject.spi.AnnotatedMethod} + * representing the producer method. + * + * @return the {@link javax.enterprise.inject.spi.AnnotatedMethod} for the + * producer method being registered + */ public AnnotatedMethod<T> getAnnotatedProducerMethod(); + /** + * Returns the {@link javax.enterprise.inject.spi.AnnotatedParameter} for + * any matching injection point of the same type as the producer method + * return type found on a disposal method. + * + * @return the disposal method's {@link javax.enterprise.inject.spi.AnnotatedParameter} + */ public AnnotatedParameter<T> getAnnotatedDisposedParameter(); } Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessSessionBean.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessSessionBean.java 2009-10-25 18:19:30 UTC (rev 4312) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessSessionBean.java 2009-10-25 23:07:53 UTC (rev 4313) @@ -17,11 +17,42 @@ package javax.enterprise.inject.spi; +/** + * <p> + * The container fires an event of this type for each session bean it discovers, + * before registering the {@link javax.enterprise.inject.spi.Bean} object. + * </p> + * <p> + * If any observer method of a {@code ProcessSessionBean} event throws an + * exception, the exception is treated as a definition error by the container. + * </p> + * + * @author David Allen + * @param <X> + */ public interface ProcessSessionBean<X> extends ProcessManagedBean<Object> { + /** + * Returns the {@link javax.enterprise.inject.spi.AnnotatedType} representing + * the bean class. + * + * @return the {@link javax.enterprise.inject.spi.AnnotatedType} for the bean + * being registered + */ public AnnotatedType<X> getAnnotatedSessionBeanClass(); + /** + * Returns the EJB name of the session bean. + * + * @return the name of the EJB + */ public String getEjbName(); + /** + * Returns a {@link javax.enterprise.inject.spi.SessionBeanType} representing the + * kind of session bean. + * + * @return the {@link javax.enterprise.inject.spi.SessionBeanType} + */ public SessionBeanType getSessionBeanType(); } \ No newline at end of file