[weld-commits] Weld SVN: r5862 - doc/trunk/reference/en-US.

[weld-commits at lists.jboss.org]

Author: peteroyle
Date: 2010-02-17 08:27:52 -0500 (Wed, 17 Feb 2010)
New Revision: 5862

Modified:
   doc/trunk/reference/en-US/environments.xml
Log:
WELDX-19: Documented ThreadScoped

Modified: doc/trunk/reference/en-US/environments.xml
===================================================================
--- doc/trunk/reference/en-US/environments.xml	2010-02-17 11:56:08 UTC (rev 5861)
+++ doc/trunk/reference/en-US/environments.xml	2010-02-17 13:27:52 UTC (rev 5862)
@@ -408,6 +408,43 @@
 
          <section>
 
+            <title>Thread Context</title>
+
+            <para>In contrast to Java EE applications, Java SE applications place no restrictions
+               on developers regarding the creation and usage of threads.
+               Therefore Weld SE provides a custom scope annotation, <literal>@ThreadScoped</literal>,
+               and corresponding context implementation which can be used to bind bean instances
+               to the current thread. It is intended to be used in scenarios where you might otherwise
+               use <literal>ThreadLocal</literal>, and does in fact use
+               <literal>ThreadLocal</literal> under the hood.
+            </para>
+
+            <para>
+               To use the @ThreadScoped annotation you need to enable the <literal>RunnableDecorator</literal>
+               which 'listens' for all executions of <literal>Runnable.run()</literal> and
+               decorates them by setting up the thread context beforehand, bound to
+               the current thread, and destroying the context afterwards.
+            </para>
+
+ <programlisting role="XML"><![CDATA[<beans>
+  <decorators>
+     <decorator>org.jboss.weld.environment.se.threading.RunnableDecorator</decorator>
+  </decorator>
+</beans>]]></programlisting>
+
+            <note>
+               <para>It is not necessary to use @ThreadScoped in all
+                  multithreaded applications. The thread context is not intended 
+                  as a replacement for defining your own application-specific contexts.
+                  It is generally only useful in situtations where you would otherwise
+                  have used ThreadLocal directly, which are typically rare.
+               </para>
+            </note>
+
+        </section>
+
+         <section>
+
             <title>Setting the Classpath</title>
 
             <para>Weld SE comes packaged as a 'shaded' jar which includes the CDI API,