[weld-commits] Weld SVN: r4319 - api/trunk/cdi/src/main/java/javax/enterprise/inject/spi.
weld-commits at lists.jboss.org
weld-commits at lists.jboss.org
Sun Oct 25 21:09:29 EDT 2009
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 <T extends Servlet> void decorateServlet(@Observes ProcessInjectionTarget<T> 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<?, EntityManager> 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>
{
More information about the weld-commits
mailing list