[weld-commits] Weld SVN: r4395 - api/trunk/cdi/src/main/java/javax/enterprise/context/spi.
weld-commits at lists.jboss.org
weld-commits at lists.jboss.org
Thu Oct 29 02:42:08 EDT 2009
Author: gavin.king at jboss.com
Date: 2009-10-29 02:42:07 -0400 (Thu, 29 Oct 2009)
New Revision: 4395
Modified:
api/trunk/cdi/src/main/java/javax/enterprise/context/spi/Context.java
api/trunk/cdi/src/main/java/javax/enterprise/context/spi/Contextual.java
api/trunk/cdi/src/main/java/javax/enterprise/context/spi/CreationalContext.java
Log:
javadoc for context.spi package
Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/spi/Context.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/context/spi/Context.java 2009-10-29 06:08:14 UTC (rev 4394)
+++ api/trunk/cdi/src/main/java/javax/enterprise/context/spi/Context.java 2009-10-29 06:42:07 UTC (rev 4395)
@@ -22,9 +22,19 @@
import javax.enterprise.context.ContextNotActiveException;
/**
- * The contract between the manager and a contextual object.
- * This interface should not be called directly by the application.
+ * <p>Provides an operation for obtaining contextual instances with a particular scope
+ * of any contextual type. Any instance of {@code Context} is called a context object.</p>
*
+ * <p>The context object is responsible for creating and destroying contextual instances
+ * by calling operations of {@link javax.enterprise.context.spi.Contextual}. In particular,
+ * the context object is responsible for destroying any contextual instance it creates by
+ * passing the instance to
+ * {@link javax.enterprise.context.spi.Contextual#destroy(Object, CreationalContext)}. A
+ * destroyed instance must not subsequently be returned by {@code get()}.
+ * The context object must pass the same instance of
+ * {@link javax.enterprise.context.spi.CreationalContext} to {@code Contextual.destroy()}
+ * that it passed to {@code Contextual.create()} when it created the instance.</p>
+ *
* @author Gavin King
* @author Pete Muir
*/
@@ -33,42 +43,42 @@
{
/**
- * The scope which this context implements
+ * Get the scope type of the context object.
*
* @return the scope
*/
public Class<? extends Annotation> getScope();
/**
- * Return an existing instance of a contextual type or create a new instance
- * of a contextual type
+ * Return an existing instance of certain contextual type or create a new
+ * instance by calling
+ * {@link javax.enterprise.context.spi.Contextual#create(CreationalContext)}
+ * and return the new instance.
*
* @param <T> the type of contextual type
* @param contextual the contextual type
- * @param creationalContext the creational context in which incompletely
- * initialized instances may be placed
- * @return the contextual instance, or null if no creational context is given
- * and an instance does not exist in the context
+ * @param creationalContext the context in which the new instance will be created
+ * @return the contextual instance
+ *
* @throws ContextNotActiveException if the context is not active
*/
public <T> T get(Contextual<T> contextual, CreationalContext<T> creationalContext);
/**
- * Return an existing instance of a contextual type or create a new instance
- * of a contextual type
+ * Return an existing instance of a certain contextual type or a null value.
*
* @param <T> the type of the contextual type
* @param contextual the contextual type
- * @return the contextual instance, or null if an instance does not exist in
- * the context
+ * @return the contextual instance, or a null value
+ *
* @throws ContextNotActiveException if the context is not active
*/
public <T> T get(Contextual<T> contextual);
/**
- * The context is only active at certain points in the application lifecycle
+ * Determines if the context object is active.
*
- * @return true if the context is active
+ * @return <tt>true</tt> if the context is active, or <tt>false</tt> otherwise.
*/
boolean isActive();
Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/spi/Contextual.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/context/spi/Contextual.java 2009-10-29 06:08:14 UTC (rev 4394)
+++ api/trunk/cdi/src/main/java/javax/enterprise/context/spi/Contextual.java 2009-10-29 06:42:07 UTC (rev 4395)
@@ -20,33 +20,46 @@
import javax.enterprise.inject.CreationException;
/**
- * The contract between a context and a contextual type This interface should
- * not be implemented directly by the application.
+ * <p>Defines operations to create and destroy contextual instances of a
+ * certain type. Any implementation of {@code Contextual} is called a
+ * contextual type. In particular, all beans are contextual types.</p>
*
+ * @see javax.enterprise.inject.spi.Bean
+ *
+ * @author Gavin King
* @author Nicklas Karlsson
* @author Pete Muir
*/
public interface Contextual<T>
{
/**
- * Create a new instance of the contextual type
+ * Create a new instance of the contextual type. Instances should
+ * use the given {@link javax.enterprise.context.spi.CreationalContext}
+ * when obtaining contextual references to inject, in order to ensure
+ * that any dependent objects are associated with the contextual instance
+ * that is being created. An implementation may call
+ * {@link javax.enterprise.context.spi.CreationalContext#push(Object)}
+ * between instantiation and injection to help the container minimize the
+ * use of client proxy objects.
*
- * @param creationalContext
- * the creational context in which incompletely initialized
- * contexts may be placed
+ * @param creationalContext
+ * the context in which this instance is being created
* @return the contextual instance
* @throws CreationException
- * if a checked exception occurs whilst creating the instance
+ * if a checked exception occurs while creating the instance
*/
public T create(CreationalContext<T> creationalContext);
/**
- * Destroys an instance of the contexual type
+ * Destroy an instance of the contextual type. Implementations should
+ * call {@link javax.enterprise.context.spi.CreationalContext#release()}
+ * to allow the container to destroy dependent objects of the contextual
+ * instance.
*
* @param instance
- * the insance to destroy
+ * the contextual instance to destroy
* @param creationalContext
- * the creational context used to create the instance
+ * the context in which this instance was created
*/
public void destroy(T instance, CreationalContext<T> creationalContext);
}
Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/spi/CreationalContext.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/context/spi/CreationalContext.java 2009-10-29 06:08:14 UTC (rev 4394)
+++ api/trunk/cdi/src/main/java/javax/enterprise/context/spi/CreationalContext.java 2009-10-29 06:42:07 UTC (rev 4395)
@@ -17,10 +17,11 @@
package javax.enterprise.context.spi;
/**
- * Allows registration of an incompletely initialized contextual instance with
- * the container. The contextual instance is considered incompletely initialized
- * until the create() method returns the instance.
+ * <p>Provides operations that are used by the
+ * {@link javax.enterprise.context.spi.Contextual} implementation during
+ * instance creation and destruction.</p>
*
+ * @author Gavin King
* @author Pete Muir
*
*/
@@ -28,12 +29,20 @@
{
/**
- * Push an incomplete instance to the container
+ * Registers an incompletely initialized contextual instance the with the
+ * container. A contextual instance is considered incompletely initialized
+ * until it is returned by
+ * {@link javax.enterprise.context.spi.Contextual#create(CreationalContext)}.
*
- * @param incompleteInstance
+ * @param incompleteInstance the incompletely initialized instance
*/
public void push(T incompleteInstance);
+ /**
+ * Destroys all dependent objects of the instance which is being destroyed,
+ * by passing each dependent object to
+ * {@link javax.enterprise.context.spi.Contextual#destroy(Object, CreationalContext)}.
+ */
public void release();
}
More information about the weld-commits
mailing list