[weld-commits] Weld SVN: r4327 - api/trunk/cdi/src/main/java/javax/enterprise/context.

[weld-commits at lists.jboss.org]

Author: gavin.king at jboss.com
Date: 2009-10-26 11:39:04 -0400 (Mon, 26 Oct 2009)
New Revision: 4327

Modified:
   api/trunk/cdi/src/main/java/javax/enterprise/context/package-info.java
Log:
simplify

Modified: api/trunk/cdi/src/main/java/javax/enterprise/context/package-info.java
===================================================================
--- api/trunk/cdi/src/main/java/javax/enterprise/context/package-info.java	2009-10-26 14:15:55 UTC (rev 4326)
+++ api/trunk/cdi/src/main/java/javax/enterprise/context/package-info.java	2009-10-26 15:39:04 UTC (rev 4327)
@@ -45,42 +45,31 @@
  * example, a third-party web application framework might provide a 
  * conversation context object for the built-in conversation scope.</p>
  * 
- * <p>For each of the built-in normal scopes, contexts propagate across 
- * any Java method call, including invocation of EJB local business methods. 
- * The built-in contexts do not propagate across remote method invocations 
- * or to asynchronous processes such as JMS message listeners or EJB timer 
- * service timeouts.</p>
+ * <p>The context associated with a built-in scope propagates across 
+ * local, synchronous Java method calls, including invocation of EJB 
+ * local business methods. The context does not propagate across remote 
+ * method invocations or to asynchronous processes such as JMS message 
+ * listeners or EJB timer service timeouts.</p>
  * 
  * <h3>Normal scopes and pseudo-scopes</h3>
  * 
- * <p>Most scopes are <em>normal scopes</em>. The 
- * {@linkplain javax.enterprise.context.spi.Context context object} for 
- * a normal scope type is a mapping from each contextual type with that 
- * scope to an instance of that contextual type. There may be no more than 
- * one mapped instance per contextual type per thread. The set of all 
- * mapped instances of contextual types with a certain scope for a 
- * certain thread is called the <em>context</em> for that scope associated 
- * with that thread.</p>
- * 
- * <p>A context may be associated with one or more threads. A context 
- * with a certain scope is said to <em>propagate</em> from one point in the 
- * execution of the program to another when the set of mapped instances 
- * of contextual types with that scope is preserved.</p>
- * 
- * <p>The context associated with the current thread is called the 
- * <em>current context</em> for the scope. The mapped instance of a 
- * contextual type associated with a current context is called the 
- * <em>current instance</em> of the contextual type.<p>
- * 
- * <p>Any scope that is not a normal scope is called a <em>pseudo-scope</em>. 
+ * <p>Most scopes are <em>normal scopes</em>. Normal scopes are declared 
+ * using {@link javax.enterprise.context.NormalScope &#064;NormalScope}. 
+ * If a bean has a normal scope, every client executing in a certain 
+ * thread sees the same contextual instance of the bean. This instance is 
+ * called the <em>current instance</em> of the bean. The operation 
+ * {@link javax.enterprise.context.spi.Context#get(Contextual)} of the 
+ * context object for a normal scope type always returns the current 
+ * instance of the given bean.</p> 
+ *
+ * <p>Any scope that is not a normal scope is called a <em>pseudo-scope</em>.
+ * Pseudo-scopes are declared using {@link javax.inject.Scope &#064;Scope}. 
  * The concept of a current instance is not well-defined in the case of 
- * a pseudo-scope.</p>
+ * a pseudo-scope. Different clients executing in the same thread may
+ * see different instances of the bean. In the extreme case of the
+ * {@link javax.enterprise.context.Dependent &#064;Dependent} pseudo-scope,
+ * every client has its own private instance of the bean.</p> 
  * 
- * <p>All normal scopes must be explicitly declared 
- * {@link javax.enterprise.context.NormalScope &#064;NormalScope}. All 
- * pseudo-scopes must be explicitly declared 
- * {@link javax.inject.Scope &#064;Scope}.</p> 
- * 
  * <p>All built-in scopes are normal scopes, except for the 
  * {@link javax.enterprise.context.Dependent &#064;Dependent} and
  * {@link javax.inject.Singleton &#064;Singleton} pseudo-scopes.</p>