[weld-commits] Weld SVN: r5219 - doc/trunk/reference/en-US.
weld-commits at lists.jboss.org
weld-commits at lists.jboss.org
Mon Dec 7 04:40:04 EST 2009
Author: peteroyle
Date: 2009-12-07 04:40:04 -0500 (Mon, 07 Dec 2009)
New Revision: 5219
Modified:
doc/trunk/reference/en-US/environments.xml
Log:
WELDX-51: documentation
Modified: doc/trunk/reference/en-US/environments.xml
===================================================================
--- doc/trunk/reference/en-US/environments.xml 2009-12-07 09:39:29 UTC (rev 5218)
+++ doc/trunk/reference/en-US/environments.xml 2009-12-07 09:40:04 UTC (rev 5219)
@@ -285,10 +285,7 @@
<para>
Weld provides an extension which will boot a CDI bean manager in Java SE, automatically registering all
- simple beans found on the classpath. Application developers need not write any bootstrapping code. The entry
- point for application code is a simple bean which observes the special
- <literal>ContainerInitialized</literal> event provided by this extension. The command line parameters can be
- injected using either of the following:
+ simple beans found on the classpath. The command line parameters can be injected using either of the following:
</para>
<programlisting role="JAVA"><![CDATA[@Inject @Parameters List<String> params;]]></programlisting>
@@ -298,7 +295,17 @@
<para>
The second form is useful for compatibility with existing classes.
</para>
-
+
+ <note>
+ <para>
+ The command line parameters do not become available for injection until the
+ <literal>ContainerInitialized</literal> event is fired. If you need access to the parameters during
+ initialization you can do so via the
+ <literal>public static String[] getParameters()</literal> method in
+ <literal>StartMain</literal>.
+ </para>
+ </note>
+
<para>
Here's an example of a simple CDI SE application:
</para>
@@ -311,35 +318,105 @@
}
}]]></programlisting>
- <para>
- CDI SE applications can be bootstrapped by running the <literal>StartMain</literal> class like so:
- </para>
+ </section>
- <programlisting role="JAVA"><![CDATA[java org.jboss.weld.environments.se.StartMain <args>]]></programlisting>
+ <section>
+
+ <title>Bootstrapping CDI SE</title>
- <para>
- If you need to do any custom initialization of the CDI bean manager, for example registering custom contexts
- or initializing resources for your beans you can do so in response to the
- <literal>AfterBeanDiscovery</literal> or <literal>AfterDeploymentValidation</literal> events. The following
- example registers a custom context:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public class PerformSetup {
- public void setup(@Observes AfterBeanDiscovery event) {
- event.addContext( ThreadContext.INSTANCE );
- }
+ <para>
+ CDI SE applications can be bootstrapped in the following ways.
+ </para>
+
+ <section>
+
+ <title>The ContainerInitialized Event</title>
+
+ <para>
+ Thanks to the power of CDI's typesafe event model, application developers
+ need not write any bootstrapping code. The Weld SE module comes
+ with a built-in main method which will bootstrap CDI for you and
+ then fire a <literal>ContainerInitialized</literal> event. The entry
+ point for your application code would therefore be a simple bean which observes
+ the <literal>ContainerInitialized</literal> event, as in the previous example.</para>
+
+ <para>In this case your application can be started by calling the provided
+ main method like so:</para>
+
+ <programlisting role="JAVA"><![CDATA[java org.jboss.weld.environments.se.StartMain <args>]]></programlisting>
+
+ </section>
+
+ <section>
+
+ <title>Programatic Bootstrap API</title>
+
+ <para>For added flexibility, CDI SE also comes with a bootstrap API
+ which can be called from within your application in order to initialize
+ CDI and obtain references to your application's beans and events. The
+ API consists of two classes: <literal>Weld</literal> and
+ <literal>WeldContainer</literal>.</para>
+
+ <programlisting role="JAVA"><![CDATA[public class Weld
+{
+
+ /** Boots Weld and creates and returns a WeldContainer instance, through which
+ * beans and events can be accesed. */
+ public WeldContainer initialize() {...}
+
+ /** Convenience method for shutting down the container. */
+ public void shutdown() {...}
+
}]]></programlisting>
- <note>
- <para>
- The command line parameters do not become available for injection until the
- <literal>ContainerInitialized</literal> event is fired. If you need access to the parameters during
- initialization you can do so via the <literal>public static String[] getParameters()</literal> method in
- <literal>StartMain</literal>.
+ <programlisting role="JAVA"><![CDATA[public class WeldContainer
+{
+
+ /** Provides access to all beans within the application. */
+ public Instance<Object> instance() {...}
+
+ /** Provides access to all events within the application. */
+ public Event<Object> event() {...}
+
+ /** Provides direct access to the BeanManager. */
+ public BeanManager getBeanManager() {...}
+
+}]]></programlisting>
+
+ <para>Here's an example application main method which uses this API
+ to initialize a bean of type <literal>MyApplicationBean</literal>.</para>
+
+ <programlisting role="JAVA"><![CDATA[public static void main(String[] args) {
+ WeldContainer weld = new Weld().initialize();
+ weld.instance().select(MyApplicationBean.class).get();
+ weld.shutdown();
+}]]></programlisting>
+
+ <para>Alternatively the application could be started by firing a custom
+ event which would then be observed by another simple bean. The following
+ example fires <literal>MyEvent</literal> on startup.</para>
+
+ <programlisting role="JAVA"><![CDATA[public static void main(String[] args) {
+ WeldContainer weld = new Weld().initialize();
+ weld.event().select(MyEvent.class).fire( new MyEvent() );
+ weld.shutdown();
+}]]></programlisting>
+
+ </section>
+
+ </section>
+
+ <section>
+
+ <title>Setting the Classpath</title>
+
+ <para>Weld SE comes packaged as a 'shaded' jar which includes the CDI API,
+ Weld Core and all dependant classes bundled into a single jar. Therefore the
+ only Weld jar you need on the classpath, in addition to your application's
+ classes and dependant jars, is the Weld SE jar.
</para>
- </note>
- </section>
+ </section>
</section>
More information about the weld-commits
mailing list