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

[weld-commits at lists.jboss.org]

Author: gavin.king at jboss.com
Date: 2009-12-01 19:27:01 -0500 (Tue, 01 Dec 2009)
New Revision: 5187

Modified:
   doc/trunk/reference/en-US/resources.xml
Log:
more explanation

Modified: doc/trunk/reference/en-US/resources.xml
===================================================================
--- doc/trunk/reference/en-US/resources.xml	2009-12-02 00:02:39 UTC (rev 5186)
+++ doc/trunk/reference/en-US/resources.xml	2009-12-02 00:27:01 UTC (rev 5187)
@@ -30,6 +30,26 @@
          <section>
             <title>Defining a resource</title>
             
+            <para>The CDI specification uses the term <emphasis>resource</emphasis> to refer, generically, to any of
+            the following kinds of object which might be available in the Java EE component environment:</para>
+            
+            <itemizedlist>
+               <listitem>
+                  <para>JDBC <literal>Datasource</literal>s, JMS <literal>Queue</literal>s, <literal>Topic</literal>s
+                  and <literal>ConnectionFactory</literal>s, JavaMail <literal>Session</literal>s and other transactional 
+                  resources including JCA connectors,</para>
+               </listitem>
+               <listitem>
+                  <para>JPA <literal>EntityManager</literal>s and <literal>EntityManagerFactory</literal>s,</para>
+               </listitem>
+               <listitem>
+                  <para>remote EJBs, and</para>
+               </listitem>
+               <listitem>
+                  <para>web services</para>
+               </listitem>
+            </itemizedlist>
+            
             <para>We declare a resource by annotating a producer field with a component environment injection
             annotation: <literal>@Resource</literal>, <literal>@EJB</literal>, <literal>@PersistenceContext</literal>,
             <literal>@PersistenceUnit</literal> or <literal>@WebServiceRef</literal>.</para>
@@ -51,9 +71,23 @@
 
             <para>The field may be static (but not final).</para>
             
-            <para>It might feel strange to be declaring resources in Java code. Isn't this stuff that might be
-            deployment-specific? Certainly, and that's why it makes sense to declare your resources in a class
-            annotated <literal>@Alternative</literal>.</para>
+            <para>A resource declaration really contains two pieces of information:</para>
+            
+            <itemizedlist>
+               <listitem>
+                  <para>the JNDI name, EJB link, persistence unit name, or other metadata needed to obtain a 
+                  reference to the resource from the component environment, and</para>
+               </listitem>
+               <listitem>
+                  <para>the type and qualifiers that we will use to inject the reference into our beans.</para>
+               </listitem>
+            </itemizedlist>
+            
+            <tip>
+               <para>It might feel strange to be declaring resources in Java code. Isn't this stuff that might be
+               deployment-specific? Certainly, and that's why it makes sense to declare your resources in a class
+               annotated <literal>@Alternative</literal>.</para>
+            </tip>
 
          </section>