1:24 a.m.
Author: gavin.king(a)jboss.com
Date: 2009-11-16 19:24:06 -0500 (Mon, 16 Nov 2009)
New Revision: 5081
Modified:
doc/trunk/reference/en-US/extend.xml
Log:
useful!
Modified: doc/trunk/reference/en-US/extend.xml
===================================================================
--- doc/trunk/reference/en-US/extend.xml 2009-11-16 23:49:37 UTC (rev 5080)
+++ doc/trunk/reference/en-US/extend.xml 2009-11-17 00:24:06 UTC (rev 5081)
@@ -225,6 +225,52 @@
<para>Let's study some of the interfaces exposed by the
<literal>BeanManager</literal>.</para>
</section>
+
+ <section>
+ <title>The <literal>InjectionTarget</literal>
interface</title>
+
+ <para>
+ The first thing that a framework developer is going to look for in the portable
extension SPI is a way to
+ inject CDI beans into objects which are not under the control of CDI. The
<literal>InjectionTarget</literal>
+ interface makes this very easy.
+ </para>
+
+ <tip>
+ <para>
+ We recommend that frameworks let CDI take over the job of actually instantiating
the framework-controlled
+ objects. That way, the framework-controlled objects can take advantage of
constructor injection. However,
+ if the framework requires use of a constructor with a special signature, the
framework will need to
+ instatiate the object itself, and so only method and field injection will be
supported.
+ </para>
+ </tip>
+
+ <programlisting role="JAVA"><![CDATA[//get the BeanManager from
JNDI
+BeanManager beanManager = (BeanManager) new
InitialContext().lookup("java:comp/BeanManager");
+
+//CDI uses an AnnotatedType object to read the annotations of a class
+AnnotatedType<SomeFrameworkComponent> type =
beanManager.createAnnotatedType(SomeFrameworkComponent.class);
+
+//The extension uses an InjectionTarget to delegate instantiation, dependency injection
+//and lifecycle callbacks to the CDI container
+InjectionTarget<SomeFrameworkComponent> it =
beanManager.createInjectionTarget(type);
+
+//each instance needs its own CDI CreationalContext
+CreationalContext instanceContext = beanManager.createCreationalContext(null);
+
+//instantiate the framework component and inject its dependencies
+SomeFrameworkComponent instance = it.produce(instanceContext); //call the constructor
+it.inject(instance, ctx); //call initializer methods and perform field injection
+it.postConstruct(instance); //call the @PostConstruct method
+
+...
+
+//destroy the framework component instance and clean up dependent objects
+it.preDestroy(instance); //call the @PreDestroy method
+it.dispose(instance); //it is now safe to discard the instance
+ctx.release(); //clean up dependent objects
+]]></programlisting>
+
+ </section>
<section>
<title>The <literal>Bean</literal> interface</title>
@@ -237,12 +283,6 @@
</para>
<para>
- There's an easy way to find out what beans exist in the application:
- </para>
-
- <programlisting role="JAVA"><![CDATA[Set<Bean<?>>
allBeans = beanManager.getBeans(Obect.class, new AnnotationLiteral<Any>()
{});]]></programlisting>
-
- <para>
The <literal>Bean</literal> interface exposes all the interesting
things we dicussed in
<xref linkend="bean-anatomy"/>.
</para>
@@ -260,6 +300,12 @@
}]]></programlisting>
<para>
+ There's an easy way to find out what beans exist in the application:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[Set<Bean<?>>
allBeans = beanManager.getBeans(Obect.class, new AnnotationLiteral<Any>()
{});]]></programlisting>
+
+ <para>
The <literal>Bean</literal> interface makes it possible for a
portable extension to provide
support for new kinds of beans, beyond those defined by the CDI specification.
For example,
we could use the <literal>Bean</literal> interface to allow objects
managed by another framework