Author: gavin.king(a)jboss.com
Date: 2009-11-10 02:35:33 -0500 (Tue, 10 Nov 2009)
New Revision: 4946
Added:
doc/trunk/reference/en-US/resources.xml
Modified:
doc/trunk/reference/en-US/ee.xml
doc/trunk/reference/en-US/interceptors.xml
doc/trunk/reference/en-US/intro.xml
doc/trunk/reference/en-US/master.xml
doc/trunk/reference/en-US/part3.xml
Log:
more reorg
Modified: doc/trunk/reference/en-US/ee.xml
===================================================================
--- doc/trunk/reference/en-US/ee.xml 2009-11-10 07:10:46 UTC (rev 4945)
+++ doc/trunk/reference/en-US/ee.xml 2009-11-10 07:35:33 UTC (rev 4946)
@@ -6,14 +6,48 @@
<para>
CDI is fully integrated into the Java EE environment. Beans have access to Java EE
resources and JPA persistence
contexts. They may be used in Unified EL expressions in JSF and JSP pages. They may
even be injected into other
- platform components, such as Servlets and Message-Driven Beans, which are not beans
themselves.
+ platform components, such as servlets and message-driven Beans, which are not beans
themselves.
</para>
+ <section>
+ <title>Built-in beans</title>
+
+ <para>
+ In the Java EE environment, the container provides the following built-in
beans, all with the qualifier
+ <literal>@Default</literal>:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ the current JTA <literal>UserTransaction</literal>,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a <literal>Principal</literal> representing the current
caller identity,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the default <ulink
src="http://jcp.org/en/jsr/detail?id=303">Bean Validation</ulink>
+ <literal>ValidationFactory</literal>, and
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a <literal>Validator</literal> for the default
<literal>ValidationFactory</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+
<section>
<title>Injecting Java EE resources into a bean</title>
<para>
- All managed beans may take advantage of Java EE dependency injection using
<literal>@Resource</literal>,
+ All managed beans may take advantage of Java EE component environment injection
using <literal>@Resource</literal>,
<literal>@EJB</literal>,
<literal>@PersistenceContext</literal>,
<literal>@PeristenceUnit</literal> and
<literal>@WebServiceRef</literal>. We've already seen a couple
of examples of this, though we didn't pay
much attention at the time:
@@ -38,6 +72,11 @@
for all managed beans. The <literal>@PostConstruct</literal> method
is called after <emphasis>all</emphasis>
injection has been performed.
</para>
+
+ <para>
+ Of course, we advise that component environment injection be used to define CDI
resources, and that typesafe
+ injection be used in application code.
+ </para>
</section>
Modified: doc/trunk/reference/en-US/interceptors.xml
===================================================================
--- doc/trunk/reference/en-US/interceptors.xml 2009-11-10 07:10:46 UTC (rev 4945)
+++ doc/trunk/reference/en-US/interceptors.xml 2009-11-10 07:35:33 UTC (rev 4946)
@@ -112,7 +112,7 @@
<programlisting role="JAVA"><![CDATA[@Transactional
@Interceptor
public class TransactionInterceptor {
- @Inject UserTransaction transaction;
+ @Resource UserTransaction transaction;
@AroundInvoke
public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
Modified: doc/trunk/reference/en-US/intro.xml
===================================================================
--- doc/trunk/reference/en-US/intro.xml 2009-11-10 07:10:46 UTC (rev 4945)
+++ doc/trunk/reference/en-US/intro.xml 2009-11-10 07:35:33 UTC (rev 4946)
@@ -947,122 +947,11 @@
<para>
A producer field is really just a shortcut that lets us avoid writing a
useless getter method. However,
in addition to convenience, producer fields serve a specific purpose as an
adaptor for Java EE component
- environment injection.
+ environment injection, but to learn more about that, you'll have to wait
until <xref linkend="resources"/>.
+ Because we can't wait to get to work on some examples.
</para>
</section>
-
- <section>
- <title>Java EE resources</title>
-
- <para>
- Java EE 5 already introduced some limited support for dependency injection,
in the form of component
- environment injection. A component environment resource is a Java EE
component, for example a JDBC
- datasource, JMS queue or topic, JPA persistence context, remote EJB or web
service.
- </para>
-
- <para>
- Naturally, there is now a slight mismatch with the new style of dependency
injection in CDI. Most notably,
- component environment injection relies on string-based names to qualify
ambiguous types, and there is no
- real consistency as to the nature of the names (sometimes a JNDI name,
sometimes a persistence unit name,
- sometimes an EJB link, sometimes a nonportable "mapped name").
Producer fields turned out to be an elegant
- adaptor to reduce all this complexity to a common model and get component
environment resources to
- participate in the CDI system just like any other kind of bean.
- </para>
-
- <para>
- Fields have a duality in that they can both be the target of Java EE
component environment injection and be
- declared as a CDI producer field. Therefore, they can define a mapping from a
string-based name in the
- component environment, to a combination of type and qualifiers used in the
world of typesafe injection. We
- call a producer field that represents a reference to an object in the Java EE
component environment a
- <emphasis>resource</emphasis>.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Produces
@WebServiceRef(lookup="java:app/service/Catalog")
-Catalog catalog;]]></programlisting>
-
- <programlisting role="JAVA"><![CDATA[@Produces
@Resource(lookup="java:global/env/jdbc/CustomerDatasource")
-@CustomerDatabase Datasource customerDatabase;]]></programlisting>
-
- <programlisting role="JAVA"><![CDATA[@Produces
@PersistenceContext(unitName="CustomerDatabase")
-@CustomerDatabase EntityManager
customerDatabasePersistenceContext;]]></programlisting>
-
- <programlisting role="JAVA"><![CDATA[@Produces
@PersistenceUnit(unitName="CustomerDatabase")
-@CustomerDatabase EntityManagerFactory
customerDatabasePersistenceUnit;]]></programlisting>
-
- <programlisting role="JAVA"><![CDATA[@Produces
@EJB(ejbLink="../their.jar#PaymentService")
-PaymentService paymentService;]]></programlisting>
-
- <para>
- These resources can then be injected in the usual way.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Inject Catalog
catalog;]]></programlisting>
- <programlisting role="JAVA"><![CDATA[@Inject
@CustomerDatabase Datasource customerDatabase;]]></programlisting>
- <programlisting role="JAVA"><![CDATA[@Inject
@CustomerDatabase EntityManager
customerDatabaseEntityManager;]]></programlisting>
- <programlisting role="JAVA"><![CDATA[@Inject
@CustomerDatabase EntityManagerFactory
customerDatabaseEntityManagerFactory;]]></programlisting>
- <programlisting role="JAVA"><![CDATA[@Inject PaymentService
paymentService;]]></programlisting>
-
- <para>
- The bean type and qualifiers of the resource are determined by the producer
field declaration.
- </para>
-
- <para>
- It might seem like a pain to have to write these extra producer field
declarations, just to gain an additional
- level of indirection. You could just as well use component environment
injection directly, right? But remember
- that you're going to be using resources like the
<literal>EntityManager</literal> in several different beans.
- Isn't it nicer and more typesafe to write
- </para>
-
- <programlisting>@Inject @CustomerDatabase
EntityManager</programlisting>
-
- <para>instead of</para>
-
-
<programlisting>@PersistenceContext(unitName="CustomerDatabase")
EntityManager</programlisting>
-
- <para>
- all over the place?
- </para>
-
- </section>
-
- <section>
- <title>Built-in beans</title>
-
- <para>
- In the Java EE environment, we get some additional goodies. The container
provides the following
- built-in beans, all with the qualifier
<literal>@Default</literal>:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- the current JTA <literal>UserTransaction</literal>,
- </para>
- </listitem>
- <listitem>
- <para>
- a <literal>Principal</literal> representing the current
caller identity,
- </para>
- </listitem>
- <listitem>
- <para>
- the default <ulink
src="http://jcp.org/en/jsr/detail?id=303">Bean Validation</ulink>
- <literal>ValidationFactory</literal>, and
- </para>
- </listitem>
- <listitem>
- <para>
- a <literal>Validator</literal> for the default
<literal>ValidationFactory</literal>.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Can't wait to get started? Great! In the next two chapters, we'll
start working on some examples.
- </para>
-
- </section>
</section>
Modified: doc/trunk/reference/en-US/master.xml
===================================================================
--- doc/trunk/reference/en-US/master.xml 2009-11-10 07:10:46 UTC (rev 4945)
+++ doc/trunk/reference/en-US/master.xml 2009-11-10 07:35:33 UTC (rev 4946)
@@ -74,6 +74,7 @@
<xi:include href="stereotypes.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="specialization.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="resources.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</part>
Modified: doc/trunk/reference/en-US/part3.xml
===================================================================
--- doc/trunk/reference/en-US/part3.xml 2009-11-10 07:10:46 UTC (rev 4945)
+++ doc/trunk/reference/en-US/part3.xml 2009-11-10 07:35:33 UTC (rev 4946)
@@ -3,7 +3,7 @@
<partintro>
<para>
- The second major theme of Weld is <emphasis>strong typing</emphasis>.
The information about the dependencies,
+ The second major theme of CDI is <emphasis>strong typing</emphasis>.
The information about the dependencies,
interceptors and decorators of a bean, and the information about event consumers
for an event producer, is
contained in typesafe Java constructs that may be validated by the compiler.
</para>
Added: doc/trunk/reference/en-US/resources.xml
===================================================================
--- doc/trunk/reference/en-US/resources.xml (rev 0)
+++ doc/trunk/reference/en-US/resources.xml 2009-11-10 07:35:33 UTC (rev 4946)
@@ -0,0 +1,96 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+<chapter id="resources">
+
+ <title>Java EE component environment resources</title>
+
+ <para>
+ Java EE 5 already introduced some limited support for dependency injection,
in the form of component
+ environment injection. A component environment resource is a Java EE
component, for example a JDBC
+ datasource, JMS queue or topic, JPA persistence context, remote EJB or web
service.
+ </para>
+
+ <para>
+ Naturally, there is now a slight mismatch with the new style of dependency
injection in CDI. Most notably,
+ component environment injection relies on string-based names to qualify
ambiguous types, and there is no
+ real consistency as to the nature of the names (sometimes a JNDI name,
sometimes a persistence unit name,
+ sometimes an EJB link, sometimes a nonportable "mapped name").
Producer fields turned out to be an elegant
+ adaptor to reduce all this complexity to a common model and get component
environment resources to
+ participate in the CDI system just like any other kind of bean.
+ </para>
+
+ <para>
+ Fields have a duality in that they can both be the target of Java EE
component environment injection and be
+ declared as a CDI producer field. Therefore, they can define a mapping from a
string-based name in the
+ component environment, to a combination of type and qualifiers used in the
world of typesafe injection. We
+ call a producer field that represents a reference to an object in the Java EE
component environment a
+ <emphasis>resource</emphasis>.
+ </para>
+
+ <section>
+ <title>Defining a resource</title>
+
+ <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>(a)WebServiceRef</literal>.</para>
+
+ <programlisting role="JAVA"><![CDATA[@Produces
@WebServiceRef(lookup="java:app/service/Catalog")
+Catalog catalog;]]></programlisting>
+
+ <programlisting role="JAVA"><![CDATA[@Produces
@Resource(lookup="java:global/env/jdbc/CustomerDatasource")
+@CustomerDatabase Datasource customerDatabase;]]></programlisting>
+
+ <programlisting role="JAVA"><![CDATA[@Produces
@PersistenceContext(unitName="CustomerDatabase")
+@CustomerDatabase EntityManager
customerDatabasePersistenceContext;]]></programlisting>
+
+ <programlisting role="JAVA"><![CDATA[@Produces
@PersistenceUnit(unitName="CustomerDatabase")
+@CustomerDatabase EntityManagerFactory
customerDatabasePersistenceUnit;]]></programlisting>
+
+ <programlisting role="JAVA"><![CDATA[@Produces
@EJB(ejbLink="../their.jar#PaymentService")
+PaymentService paymentService;]]></programlisting>
+
+ <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
+ annotation <literal>(a)Alternative</literal>.</para>
+
+ </section>
+
+ <section>
+ <title>Typesafe resource injection</title>
+
+ <para>
+ These resources can now be injected in the usual way.
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@Inject Catalog
catalog;]]></programlisting>
+ <programlisting role="JAVA"><![CDATA[@Inject
@CustomerDatabase Datasource customerDatabase;]]></programlisting>
+ <programlisting role="JAVA"><![CDATA[@Inject
@CustomerDatabase EntityManager
customerDatabaseEntityManager;]]></programlisting>
+ <programlisting role="JAVA"><![CDATA[@Inject
@CustomerDatabase EntityManagerFactory
customerDatabaseEntityManagerFactory;]]></programlisting>
+ <programlisting role="JAVA"><![CDATA[@Inject PaymentService
paymentService;]]></programlisting>
+
+ <para>
+ The bean type and qualifiers of the resource are determined by the producer
field declaration.
+ </para>
+
+ <para>
+ It might seem like a pain to have to write these extra producer field
declarations, just to gain an additional
+ level of indirection. You could just as well use component environment
injection directly, right? But remember
+ that you're going to be using resources like the
<literal>EntityManager</literal> in several different beans.
+ Isn't it nicer and more typesafe to write
+ </para>
+
+ <programlisting>@Inject @CustomerDatabase
EntityManager</programlisting>
+
+ <para>instead of</para>
+
+
<programlisting>@PersistenceContext(unitName="CustomerDatabase")
EntityManager</programlisting>
+
+ <para>
+ all over the place?
+ </para>
+
+ </section>
+
+</chapter>