Author: gavin.king(a)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(); }