WELD-679, Improve Javadoc

weld/src/main/java/org/jboss/weld/context/ApplicationContext.java

@@ -1,12 +1,26 @@
 package org.jboss.weld.context;
 
+import javax.enterprise.context.ApplicationScoped;
 import javax.enterprise.context.spi.Context;
 
 /**
- * The built in application context, which is always active (not managed) and is
- * backed by an application scoped singleton. The context is bound to 
+ * <p>
+ * The built in application context, associated with {@link ApplicationScoped}.
+ * It is always active (not managed) and is backed by an application scoped
+ * singleton.
+ * </p>
+ * 
+ * <p>
+ * Weld comes with one Application context which can be injected using:
+ * </p>
+ * 
+ * <pre>
+ * &#064Inject ApplicationContext applicationContext;
+ * </pre>
  * 
  * @author Pete Muir
+ * @see SingletonContext
+ * @see ApplicationScoped
  * 
  */
 public interface ApplicationContext extends Context

weld/src/main/java/org/jboss/weld/context/ConversationContext.java

@@ -3,22 +3,44 @@
 import java.util.Collection;
 
 import javax.enterprise.context.Conversation;
+import javax.enterprise.context.ConversationScoped;
+import javax.servlet.http.HttpSession;
 
 import org.jboss.weld.context.bound.BoundConversationContext;
+import org.jboss.weld.context.bound.BoundRequest;
 import org.jboss.weld.context.http.HttpConversationContext;
 
 /**
  * <p>
- * The conversation context, providing various options for controlling (default)
- * conversation configuration.
+ * The built in conversation context is associated with
+ * {@link ConversationScoped}. It can be activated, invalidated and deactivated.
+ * and provides various options for configuring conversation defaults.
  * </p>
  * 
  * <p>
- * Currently Weld comes with two implementation of the conversation context,
- * {@link HttpConversationContext} in which conversations are isolated to the
- * Http Session and {@link BoundConversationContext} in which conversations are
- * backed by a pair of maps.
+ * Weld comes with two implementation of the conversation context. The
+ * {@link HttpConversationContext}, in which conversations are bound to the
+ * {@link HttpSession}, can be injected:
  * </p>
+ * 
+ * <pre>
+ * &#064Inject &#064Http ConversationContext conversationContext;
+ * </pre>
+ * 
+ * <p>
+ * Alternatively the {@link BoundConversationContext} in which conversations are
+ * bound a {@link BoundRequest} can be injected:
+ * </p>
+ * 
+ * <pre>
+ * &#064Inject &#064Bound ConversationContext conversationContext;
+ * </pre>
+ * 
+ * @author Pete Muir
+ * @see BoundConversationContext
+ * @see HttpConversationContext
+ * @see ConversationScoped
+ * 
  */
 public interface ConversationContext extends ManagedContext
 {
@@ -27,6 +49,8 @@ public interface ConversationContext extends ManagedContext
     * Cause any expired conversations to be ended, and therefore marked for
     * destruction when deactivate is called.
     * 
+    * @throws IllegalStateException if the context is unable to access the
+    *            underlying data store
     */
    public void invalidate();
 
@@ -36,12 +60,16 @@ public interface ConversationContext extends ManagedContext
     * 
     * @param cid if the cid is null, a transient conversation will be created,
     *           otherwise the conversation will be restored
+    * @throws IllegalStateException if the context is unable to access the
+    *            underlying data store
     */
    public void activate(String cid);
 
    /**
     * Activate the conversation context, starting a new transient conversation
     * 
+    * @throws IllegalStateException if the context is unable to access the
+    *            underlying data store
     */
    public void activate();
 
@@ -91,10 +119,13 @@ public interface ConversationContext extends ManagedContext
 
    /**
     * Get conversations currently known to the context. This will include any
-    * long running conversations accessible, as well as any transient
-    * conversations which have yet to be destroyed.
+    * non transient conversations, as well as any conversations which were
+    * previously long running and have been made transient during this request.
+    * 
+    * @return a collection containing the conversations
     * 
-    * @return a collection containing the conversations known
+    * @throws IllegalStateException if the context is unable to access the
+    *            underlying data store
     */
    public Collection<ManagedConversation> getConversations();
 
@@ -103,20 +134,28 @@ public interface ConversationContext extends ManagedContext
     * 
     * @param id the id of the conversation to get
     * @return the conversation, or null if no conversation is known
+    * 
+    * @throws IllegalStateException if the context is unable to access the
+    *            underlying data store
     */
    public ManagedConversation getConversation(String id);
 
    /**
     * Generate a new, unique, conversation id
     * 
-    * @return
+    * @return a new, unique conversation id
+    * 
+    * @throws IllegalStateException if the context is unable to access the
+    *            underlying data store
     */
    public String generateConversationId();
 
    /**
     * Get a handle the current conversation (transient or otherwise).
     * 
-    * @return
+    * @return the current conversation
+    * @throws IllegalStateException if the context is unable to access the
+    *            underlying data store
     */
    public ManagedConversation getCurrentConversation();
 

weld/src/main/java/org/jboss/weld/context/DependentContext.java

@@ -1,7 +1,25 @@
 package org.jboss.weld.context;
 
+import javax.enterprise.context.Dependent;
 import javax.enterprise.context.spi.Context;
 
+/**
+ * <p>
+ * The built in dependent context, associated with {@link Dependent}. It is
+ * always active.
+ * </p>
+ * 
+ * <p>
+ * Weld comes with one Dependent context which can be injected using:
+ * </p>
+ * 
+ * <pre>
+ * &#064Inject DependentContext dependentContext;
+ * </pre>
+ * 
+ * @author Pete Muir
+ * 
+ */
 public interface DependentContext extends Context
 {
 

weld/src/main/java/org/jboss/weld/context/ManagedContext.java

@@ -13,7 +13,7 @@
  * <p>
  * Weld provides a number of managed contexts: {@link SessionContext},
  * {@link ConversationContext}, {@link RequestContext}. All these managed
- * contexts are scoped to the thread, and propagtion of the backing store
+ * contexts are scoped to the thread, and propagation of the backing store
  * between threads is the responsibility of the managed context user.
  * </p>
  * 
@@ -25,18 +25,17 @@ public interface ManagedContext extends Context
 {
 
    /**
-    * Activate the Context
+    * Activate the Context.
     */
    public void activate();
 
    /**
-    * Deactivate the Context
+    * Deactivate the Context, destroying any instances if the context is invalid.
     */
    public void deactivate();
 
    /**
     * Mark the context as due for destruction when deactivate is called.
-    * 
     */
    public void invalidate();
 

weld/src/main/java/org/jboss/weld/context/ManagedConversation.java

@@ -3,6 +3,16 @@
 import javax.enterprise.context.ContextNotActiveException;
 import javax.enterprise.context.Conversation;
 
+/**
+ * <p>
+ * Provides management operations for conversations, including locking, and
+ * expiration management.
+ * </p>
+ * 
+ * @author Pete Muir
+ * @see ConversationContext
+ * 
+ */
 public interface ManagedConversation extends Conversation
 {
 

weld/src/main/java/org/jboss/weld/context/RequestContext.java

@@ -1,6 +1,69 @@
 package org.jboss.weld.context;
 
+import java.util.Map;
 
+import javax.enterprise.context.ConversationScoped;
+import javax.enterprise.context.RequestScoped;
+import javax.interceptor.InvocationContext;
+import javax.servlet.ServletRequest;
+
+import org.jboss.weld.context.bound.BoundConversationContext;
+import org.jboss.weld.context.bound.BoundRequestContext;
+import org.jboss.weld.context.ejb.EjbRequestContext;
+import org.jboss.weld.context.http.HttpConversationContext;
+import org.jboss.weld.context.http.HttpRequestContext;
+
+/**
+ * <p>
+ * The built in request context is associated with {@link RequestScoped} and is
+ * a managed context which can be activated, invalidated and deactivated.
+ * </p>
+ * 
+ * <p>
+ * Weld comes with four implementation of the request context. The
+ * {@link HttpRequestContext}, in which conversations are bound to the
+ * {@link ServletRequest}, can be injected:
+ * </p>
+ * 
+ * <pre>
+ * &#064Inject &#064Http RequestContext requestContext;
+ * </pre>
+ * 
+ * <p>
+ * Alternatively the {@link BoundRequestContext} in which requests are bound a
+ * {@link Map} can be injected:
+ * </p>
+ * 
+ * <pre>
+ * &#064Inject &#064Bound RequestContext requestContext;
+ * </pre>
+ * 
+ * <p>
+ * Additionally, Weld provides an unbound request context (which is automatially
+ * bound to the thread) which can be injected:
+ * </p>
+ * 
+ * <pre>
+ * &#064Inject &#064Unbound RequestContext requestContext;
+ * </pre>
+ * 
+ * <p>
+ * Finally, Weld provides a request context which is bound to an
+ * {@link InvocationContext} and can be injected:
+ * </p>
+ * 
+ * 
+ * <pre>
+ * &#064Inject &#064Ejb RequestContext requestContext;
+ * </pre>
+ * 
+ * @author Pete Muir
+ * @see BoundRequestContext
+ * @see HttpRequestContext
+ * @see EjbRequestContext
+ * @see RequestScoped
+ * 
+ */
 public interface RequestContext extends ManagedContext
 {
 

weld/src/main/java/org/jboss/weld/context/SessionContext.java

@@ -1,6 +1,44 @@
 package org.jboss.weld.context;
 
+import java.util.Map;
 
+import javax.enterprise.context.SessionScoped;
+import javax.servlet.http.HttpSession;
+
+import org.jboss.weld.context.bound.BoundSessionContext;
+import org.jboss.weld.context.http.HttpSessionContext;
+
+/**
+ * <p>
+ * The built in session context is associated with {@link SessionScoped}. It can
+ * be activated, invalidated and deactivated.
+ * </p>
+ * 
+ * <p>
+ * Weld comes with two implementation of the session context. The
+ * {@link HttpSessionContext}, in which conversations are bound to the
+ * {@link HttpSession}, can be injected:
+ * </p>
+ * 
+ * <pre>
+ * &#064Inject &#064Http SessionContext sessionContext;
+ * </pre>
+ * 
+ * <p>
+ * Alternatively the {@link BoundSessionContext} in which conversations are
+ * bound a {@link Map} can be injected:
+ * </p>
+ * 
+ * <pre>
+ * &#064Inject &#064Bound SessionContext sessionContext;
+ * </pre>
+ * 
+ * @author Pete Muir
+ * @see BoundSessionContext
+ * @see HttpSessionContext
+ * @sees {@link SessionScoped}
+ * 
+ */
 public interface SessionContext extends ManagedContext
 {
 

weld/src/main/java/org/jboss/weld/context/SingletonContext.java

@@ -1,7 +1,28 @@
 package org.jboss.weld.context;
 
+import javax.enterprise.context.ApplicationScoped;
 import javax.enterprise.context.spi.Context;
 
+/**
+ * <p>
+ * The built in singleton context, associated with {@link Singleton}.
+ * It is always active (not managed) and is backed by an application scoped
+ * singleton.
+ * </p>
+ * 
+ * <p>
+ * Weld comes with one Singleton context which can be injected using:
+ * </p>
+ * 
+ * <pre>
+ * &#064Inject SingletonContext singletonContext;
+ * </pre>
+ * 
+ * @author Pete Muir
+ * @see SingletonContext
+ * @see ApplicationScoped
+ * 
+ */
 public interface SingletonContext extends Context
 {
 

weld/src/main/java/org/jboss/weld/context/bound/Bound.java

@@ -12,6 +12,13 @@
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Qualifier used with all for all of the bound (map backed) contexts Weld
+ * offers.
+ * 
+ * @author Pete Muir
+ * 
+ */
 @Qualifier
 @Target({ TYPE, METHOD, PARAMETER, FIELD })
 @Retention(RUNTIME)

weld/src/main/java/org/jboss/weld/context/bound/BoundRequest.java

@@ -10,7 +10,7 @@
  * {@link BoundRequest}.
  * </p>
  * 
- * @author pmuir
+ * @author Pete Muir
  * 
  */
 public interface BoundRequest