+ * The built in application context, associated with {@link ApplicationScoped}. + * It is always active (not managed) and is backed by an application scoped + * singleton. + *
+ * + *+ * Weld comes with one Application context which can be injected using: + *
+ * + *+ * @Inject ApplicationContext applicationContext; + ** * @author Pete Muir + * @see SingletonContext + * @see ApplicationScoped * */ public interface ApplicationContext extends Context diff --git a/weld/src/main/java/org/jboss/weld/context/ConversationContext.java b/weld/src/main/java/org/jboss/weld/context/ConversationContext.java index 762407fd..9049df12 100644 --- a/weld/src/main/java/org/jboss/weld/context/ConversationContext.java +++ b/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; /** *
- * 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. *
* *- * 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: *
+ * + *+ * @Inject @Http ConversationContext conversationContext; + *+ * + *
+ * Alternatively the {@link BoundConversationContext} in which conversations are + * bound a {@link BoundRequest} can be injected: + *
+ * + *+ * @Inject @Bound ConversationContext conversationContext; + *+ * + * @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
+ * The built in dependent context, associated with {@link Dependent}. It is + * always active. + *
+ * + *+ * Weld comes with one Dependent context which can be injected using: + *
+ * + *+ * @Inject DependentContext dependentContext; + *+ * + * @author Pete Muir + * + */ public interface DependentContext extends Context { diff --git a/weld/src/main/java/org/jboss/weld/context/ManagedContext.java b/weld/src/main/java/org/jboss/weld/context/ManagedContext.java index 40c9ff63..1a085c11 100644 --- a/weld/src/main/java/org/jboss/weld/context/ManagedContext.java +++ b/weld/src/main/java/org/jboss/weld/context/ManagedContext.java @@ -13,7 +13,7 @@ *
* 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. *
* @@ -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(); diff --git a/weld/src/main/java/org/jboss/weld/context/ManagedConversation.java b/weld/src/main/java/org/jboss/weld/context/ManagedConversation.java index 01ba6a1c..2c27b68d 100644 --- a/weld/src/main/java/org/jboss/weld/context/ManagedConversation.java +++ b/weld/src/main/java/org/jboss/weld/context/ManagedConversation.java @@ -3,6 +3,16 @@ import javax.enterprise.context.ContextNotActiveException; import javax.enterprise.context.Conversation; +/** + *+ * Provides management operations for conversations, including locking, and + * expiration management. + *
+ * + * @author Pete Muir + * @see ConversationContext + * + */ public interface ManagedConversation extends Conversation { diff --git a/weld/src/main/java/org/jboss/weld/context/RequestContext.java b/weld/src/main/java/org/jboss/weld/context/RequestContext.java index 93d76632..03d8b0ea 100644 --- a/weld/src/main/java/org/jboss/weld/context/RequestContext.java +++ b/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; + +/** + *+ * The built in request context is associated with {@link RequestScoped} and is + * a managed context which can be activated, invalidated and deactivated. + *
+ * + *+ * Weld comes with four implementation of the request context. The + * {@link HttpRequestContext}, in which conversations are bound to the + * {@link ServletRequest}, can be injected: + *
+ * + *+ * @Inject @Http RequestContext requestContext; + *+ * + *
+ * Alternatively the {@link BoundRequestContext} in which requests are bound a + * {@link Map} can be injected: + *
+ * + *+ * @Inject @Bound RequestContext requestContext; + *+ * + *
+ * Additionally, Weld provides an unbound request context (which is automatially + * bound to the thread) which can be injected: + *
+ * + *+ * @Inject @Unbound RequestContext requestContext; + *+ * + *
+ * Finally, Weld provides a request context which is bound to an + * {@link InvocationContext} and can be injected: + *
+ * + * + *+ * @Inject @Ejb RequestContext requestContext; + *+ * + * @author Pete Muir + * @see BoundRequestContext + * @see HttpRequestContext + * @see EjbRequestContext + * @see RequestScoped + * + */ public interface RequestContext extends ManagedContext { diff --git a/weld/src/main/java/org/jboss/weld/context/SessionContext.java b/weld/src/main/java/org/jboss/weld/context/SessionContext.java index 0ad7ef52..8dfe942e 100644 --- a/weld/src/main/java/org/jboss/weld/context/SessionContext.java +++ b/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; + +/** + *
+ * The built in session context is associated with {@link SessionScoped}. It can + * be activated, invalidated and deactivated. + *
+ * + *+ * Weld comes with two implementation of the session context. The + * {@link HttpSessionContext}, in which conversations are bound to the + * {@link HttpSession}, can be injected: + *
+ * + *+ * @Inject @Http SessionContext sessionContext; + *+ * + *
+ * Alternatively the {@link BoundSessionContext} in which conversations are + * bound a {@link Map} can be injected: + *
+ * + *+ * @Inject @Bound SessionContext sessionContext; + *+ * + * @author Pete Muir + * @see BoundSessionContext + * @see HttpSessionContext + * @sees {@link SessionScoped} + * + */ public interface SessionContext extends ManagedContext { diff --git a/weld/src/main/java/org/jboss/weld/context/SingletonContext.java b/weld/src/main/java/org/jboss/weld/context/SingletonContext.java index a5caa383..12d4e60f 100644 --- a/weld/src/main/java/org/jboss/weld/context/SingletonContext.java +++ b/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; +/** + *
+ * The built in singleton context, associated with {@link Singleton}. + * It is always active (not managed) and is backed by an application scoped + * singleton. + *
+ * + *+ * Weld comes with one Singleton context which can be injected using: + *
+ * + *+ * @Inject SingletonContext singletonContext; + *+ * + * @author Pete Muir + * @see SingletonContext + * @see ApplicationScoped + * + */ public interface SingletonContext extends Context { diff --git a/weld/src/main/java/org/jboss/weld/context/bound/Bound.java b/weld/src/main/java/org/jboss/weld/context/bound/Bound.java index d6a77ada..a4ca098e 100644 --- a/weld/src/main/java/org/jboss/weld/context/bound/Bound.java +++ b/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) diff --git a/weld/src/main/java/org/jboss/weld/context/bound/BoundRequest.java b/weld/src/main/java/org/jboss/weld/context/bound/BoundRequest.java index 1caa8a0c..1de4e72c 100644 --- a/weld/src/main/java/org/jboss/weld/context/bound/BoundRequest.java +++ b/weld/src/main/java/org/jboss/weld/context/bound/BoundRequest.java @@ -10,7 +10,7 @@ * {@link BoundRequest}. * * - * @author pmuir + * @author Pete Muir * */ public interface BoundRequest diff --git a/weld/src/main/java/org/jboss/weld/context/bound/MutableBoundRequest.java b/weld/src/main/java/org/jboss/weld/context/bound/MutableBoundRequest.java index cddcaf98..d4a20f6c 100644 --- a/weld/src/main/java/org/jboss/weld/context/bound/MutableBoundRequest.java +++ b/weld/src/main/java/org/jboss/weld/context/bound/MutableBoundRequest.java @@ -2,9 +2,15 @@ import java.util.Map; +/** + * An implementation of {@link BoundRequest} backed by a pair of maps. + * + * @author Pete Muir + * + */ public class MutableBoundRequest implements BoundRequest { - + private final Map
+ * A request context which can be bound to the {@link InvocationContext}. The + * context is automatically attached to the map on activation, and detached when + * {@link #invalidate()} is called. + *
+ * + *+ * This context is not thread safe, and provides no thread safety for the + * underlying map. + *
+ * + * + * @author Pete Muir + * + */ public interface EjbRequestContext extends RequestContext, BoundContext+ * A request context which can be bound to the {@link ServletRequest}. The + * context is automatically attached to the map on activation, and detached when + * {@link #invalidate()} is called. + *
+ * + *+ * This context is not thread safe, and provides no thread safety for the + * underlying map. + *
+ * + * @author Pete Muir + * + */ public interface HttpRequestContext extends BoundContext+ * A session context which can be bound to the {@link HttpServletRequest}. The + * context is automatically attached to the map on activation, and detached when + * {@link #invalidate()} is called. + *
+ * + *+ * This context is not thread safe, and provides no thread safety for the + * underlying map. + *
+ * + * + * @author Pete Muir + * + */ public interface HttpSessionContext extends BoundContext