Author: dallen6 Date: 2009-10-25 21:09:28 -0400 (Sun, 25 Oct 2009) New Revision: 4319 Removed: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProcessObserverMethod.java Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessInjectionTarget.java api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessObserverMethod.java api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducer.java api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Producer.java Log: Finished the JavaDoc for all lifecycle events. Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessInjectionTarget.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessInjectionTarget.java 2009-10-26 00:33:48 UTC (rev 4318) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessInjectionTarget.java 2009-10-26 01:09:28 UTC (rev 4319) @@ -16,13 +16,73 @@ */ package javax.enterprise.inject.spi; +/** + * <p> + * The container will fire an event of this type for each managed bean, session + * bean, Java EE component class supporting injection. + * </p> + * <p> + * Any observer of this event is permitted to wrap and/or replace the + * {@link javax.enterprise.inject.spi.InjectionTarget}. The container must use + * the final value of this property, after all observers have been called, + * whenever it performs injection upon the managed bean, session bean or other + * Java EE component class supporting injection. + * </p> + * <p> + * For example, this observer decorates the {@code InjectionTarget} for all + * servlets. + * </p> + * + * <pre> + * public &lt;T extends Servlet&gt; void decorateServlet(@Observes ProcessInjectionTarget&lt;T&gt; pit) + * { + * pit.setInjectionTarget(decorate(pit.getInjectionTarget())); + * } + * </pre> + * <p> + * If any observer method of a {@code ProcessInjectionTarget} event throws an exception, + * the exception is treated as a definition error by the container. + * </p> + * + * @author David Allen + * @param <X> The managed bean class, session bean class or Java EE component + * class supporting injection + */ public interface ProcessInjectionTarget<X> { + /** + * Returns the {@link javax.enterprise.inject.spi.AnnotatedType} representing + * the managed bean class, session bean class or other Java EE component + * class supporting injection. + * + * @return the {@link javax.enterprise.inject.spi.AnnotatedType} of the bean + * with an injection target + */ public AnnotatedType<X> getAnnotatedType(); + /** + * Returns the {@link javax.enterprise.inject.spi.InjectionTarget} object + * that will be used by the container to perform injection. + * + * @return the {@link javax.enterprise.inject.spi.InjectionTarget} object + * which performs the injection + */ public InjectionTarget<X> getInjectionTarget(); + /** + * Replaces the {@link javax.enterprise.inject.spi.InjectionTarget} which + * performs injection for this target. + * + * @param injectionTarget The new + * {@link javax.enterprise.inject.spi.InjectionTarget} to use + */ public void setInjectionTarget(InjectionTarget<X> injectionTarget); + /** + * Registers a definition error with the container, causing the container to + * abort deployment after bean discovery is complete. + * + * @param t A {@link java.lang.Throwable} representing the definition error + */ public void addDefinitionError(Throwable t); } Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessObserverMethod.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessObserverMethod.java 2009-10-26 00:33:48 UTC (rev 4318) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessObserverMethod.java 2009-10-26 01:09:28 UTC (rev 4319) @@ -18,27 +18,39 @@ package javax.enterprise.inject.spi; /** - * The container fires an event of this type for each observer method - * that is registered. + * <p> + * The container fires an event of this type for each + * {@linkplain javax.enterprise.inject.spi.ObserverMethod observer method} that + * is registered. + * </p> + * <p> + * If any observer method of a {@code ProcessObserverMethod} event throws an + * exception, the exception is treated as a definition error by the container. + * </p> * * @author Gavin King * @author David Allen - * * @param <X> The bean type containing the observer method * @param <T> The type of the event being observed */ public interface ProcessObserverMethod<X, T> { /** - * The AnnotatedMethod representing the observer method - * @return the AnnotatedMethod representing the observer method + * The {@link javax.enterprise.inject.spi.AnnotatedMethod} representing the + * observer method. + * + * @return the {@link javax.enterprise.inject.spi.AnnotatedMethod} + * representing the observer method */ public AnnotatedMethod<X> getAnnotatedMethod(); /** - * The ObserverMethod object that will be used by the container - * to invoke the observer when a matching event is fired. - * @return the ObserverMethod object that will be used by the container to call the observer method + * The {@link javax.enterprise.inject.spi.ObserverMethod} object that will be + * used by the container to invoke the observer when a matching event is + * fired. + * + * @return the {@link javax.enterprise.inject.spi.ObserverMethod} object that + * will be used by the container to call the observer method */ public ObserverMethod<X, T> getObserverMethod(); @@ -46,7 +58,7 @@ * Registers a definition error with the container, causing the container to * abort deployment after bean discovery is complete. * - * @param t A throwable representing the definition error + * @param t A {@link java.lang.Throwable} representing the definition error */ public void addDefinitionError(Throwable t); } Deleted: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProcessObserverMethod.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProcessObserverMethod.java 2009-10-26 00:33:48 UTC (rev 4318) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProcessObserverMethod.java 2009-10-26 01:09:28 UTC (rev 4319) @@ -1,26 +0,0 @@ -/* - * JBoss, Home of Professional Open Source - * Copyright 2008, Red Hat Middleware LLC, and individual contributors - * by the @authors tag. See the copyright.txt in the distribution for a - * full listing of individual contributors. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * http://www.apache.org/licenses/LICENSE-2.0 - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -package javax.enterprise.inject.spi; - -public interface ProcessProcessObserverMethod<X, T> -{ - public AnnotatedMethod<X> getAnnotatedMethod(); - - public ObserverMethod<X, T> getObserverMethod(); - - public void addDefinitionError(Throwable t); -} Modified: api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducer.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducer.java 2009-10-26 00:33:48 UTC (rev 4318) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/ProcessProducer.java 2009-10-26 01:09:28 UTC (rev 4319) @@ -17,13 +17,77 @@ package javax.enterprise.inject.spi; +/** + * <p> + * The container will fire an event of this type for each + * {@linkplain javax.enterprise.inject.Produces producer method or field}, + * including resources. + * </p> + * <p> + * Any observer of this event is permitted to wrap and/or replace the {@code + * Producer}. The container must use the final value of this property, after all + * observers have been called, whenever it calls the producer or disposer. + * </p> + * <p> + * For example, this observer decorates the {@code Producer} for the all producer + * methods and field of type {@code EntityManager}. + * </p> + * + * <pre> + * void decorateEntityManager(@Observes ProcessProducer&lt;?, EntityManager&gt; pp) + * { + * pit.setProducer(decorate(pp.getProducer())); + * } + * </pre> + * <p> + * If any observer method of a {@code ProcessProducer} event throws an exception, the + * exception is treated as a definition error by the container. + * </p> + * + * @author David Allen + * @param <T> The bean class of the bean that declares the producer method or + * field + * @param <X> The return type of the producer method or the type of the producer + * field + */ public interface ProcessProducer<T, X> { + /** + * Returns the {@link javax.enterprise.inject.spi.AnnotatedField} + * representing the producer field or the + * {@link javax.enterprise.inject.spi.AnnotatedMethod} representing the + * producer method. + * + * @return the {@link javax.enterprise.inject.spi.AnnotatedMember} + * representing the producer + */ public AnnotatedMember<T> getAnnotatedMember(); + /** + * Returns the {@link javax.enterprise.inject.spi.Producer} object that will + * be used by the container to call the producer method or read the producer + * field. + * + * @return the {@link javax.enterprise.inject.spi.Producer} invoker object + * used by the container + */ public Producer<X> getProducer(); + /** + * Replaces the {@link javax.enterprise.inject.spi.Producer} object that will + * be used by the container to call the producer method or read the producer + * field. + * + * @param producer the new {@link javax.enterprise.inject.spi.Producer} + * object to use + */ public void setProducer(Producer<X> producer); + /** + * 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/Producer.java =================================================================== --- api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Producer.java 2009-10-26 00:33:48 UTC (rev 4318) +++ api/trunk/cdi/src/main/java/javax/enterprise/inject/spi/Producer.java 2009-10-26 01:09:28 UTC (rev 4319) @@ -21,12 +21,12 @@ import javax.enterprise.context.spi.CreationalContext; /** - * The interface javax.enterprise.inject.spi.Producer provides a generic + * The interface {@link javax.enterprise.inject.spi.Producer} provides a generic * operation for producing an instance of a type. * * @author Pete Muir * - * @param <T> + * @param <T> The class of object produced by the producer */ public interface Producer<T> {