[weld-commits] Weld SVN: r5074 - doc/trunk/reference/en-US.
weld-commits at lists.jboss.org
weld-commits at lists.jboss.org
Sun Nov 15 22:52:02 EST 2009
Author: gavin.king at jboss.com
Date: 2009-11-15 22:52:02 -0500 (Sun, 15 Nov 2009)
New Revision: 5074
Modified:
doc/trunk/reference/en-US/extend.xml
Log:
improve the portable extensions chapter
Modified: doc/trunk/reference/en-US/extend.xml
===================================================================
--- doc/trunk/reference/en-US/extend.xml 2009-11-16 02:07:52 UTC (rev 5073)
+++ doc/trunk/reference/en-US/extend.xml 2009-11-16 03:52:02 UTC (rev 5074)
@@ -53,16 +53,131 @@
</listitem>
</itemizedlist>
</blockquote>
+
+ <section>
+ <title>Creating an <literal>Extension</literal></title>
+
+ <para>
+ The first step in creating a portable extension is to write a class that implements
+ <literal>Extension</literal>. This marker interface does not define any methods, but
+ it's needed to satisfy the requirements of Java SE's service provider architecture.
+ </para>
+
+ <programlisting role="JAVA">class MyExtension implements Extension { ... }</programlisting>
+
+ <para>
+ Next, we need to register our extension as a service provider by creating a file named
+ <literal>META-INF/services/javax.enterprise.inject.spi.Extension</literal>, which contains
+ the name of our extension class:
+ </para>
+
+ <programlisting>org.mydomain.extension.MyExtension</programlisting>
+
+ <para>
+ An extension is not a bean, exactly, since it is instantiated by the container during the
+ initialization process, before any beans or contexts exist. However, it can be injected
+ into other beans once the initialization process is complete.
+ </para>
+
+ <para>
+ And, like beans, extensions can have observer methods. Usually, the observer methods
+ observe <emphasis>container lifecycle events</emphasis>.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Container lifecycle events</title>
+
+ <para>
+ During the initialization process, the container fires a series of events, including:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>BeforeBeanDiscovery</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ProcessAnnotatedType</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ProcessInjectionTarget</literal> and <literal>ProcessProducer</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ProcessBean</literal> and <literal>ProcessObserverMethod</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>AfterBeanDiscovery</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>AfterDeploymentValidation</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Extensions may observe these events:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[class MyExtension implements Extension {
+
+ void beforeBeanDiscovery(BeforeBeanDiscovery bbd) {
+ Logger.global.debug("beginning the scanning process");
+ }
+
+ <T> void processAnnotatedType(ProcessAnnotatedType<T> pat) {
+ Logger.global.debug("scanning type: " + pat.getAnnotatedType().getJavaClass().getName());
+ }
- <para>
- The nerve center for extending CDI is the <literal>BeanManager</literal> object.
- </para>
+ void afterBeanDiscovery(AfterBeanDiscovery abd) {
+ Logger.global.debug("finished the scanning process");
+ }
+
+}]]></programlisting>
+
+ <para>
+ In fact, the extension can do a lot more than just observe. The extension is permitted to
+ modify the container's metamodel and more. Here's a very simple example:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[class MyExtension implements Extension {
+
+ <T> void processAnnotatedType(ProcessAnnotatedType<T> pat) {
+ //tell the container to ignore the type if it is annotated @Ignore
+ if ( pat.getAnnotatedType().isAnnotionPresent(Ignore.class) ) pat.veto();
+ }
+
+}]]></programlisting>
+
+ <para>
+ The observer method may inject a <literal>BeanManager</literal>
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[class MyExtension implements Extension {
+
+ <T> void processAnnotatedType(ProcessAnnotatedType<T> pat, BeanManager beanManager) { ... }
+
+}]]></programlisting>
+
+ </section>
<section>
<title>The <literal>BeanManager</literal> object</title>
<para>
- The <literal>BeanManager</literal> interface lets us obtain beans, interceptors, decorators,
+ The nerve center for extending CDI is the <literal>BeanManager</literal> object. The
+ <literal>BeanManager</literal> interface lets us obtain beans, interceptors, decorators,
observers and contexts programmatically.
</para>
@@ -84,9 +199,9 @@
public boolean isNormalScope(Class<? extends Annotation> annotationType);
public boolean isPassivatingScope(Class<? extends Annotation> annotationType);
public boolean isQualifier(Class<? extends Annotation> annotationType);
- public boolean isInterceptorBindingType(Class<? extends Annotation> annotationType);
+ public boolean isInterceptorBinding(Class<? extends Annotation> annotationType);
public boolean isStereotype(Class<? extends Annotation> annotationType);
- public Set<Annotation> getInterceptorBindingTypeDefinition(Class<? extends Annotation> bindingType);
+ public Set<Annotation> getInterceptorBindingDefinition(Class<? extends Annotation> bindingType);
public Set<Annotation> getStereotypeDefinition(Class<? extends Annotation> stereotype);
public Context getContext(Class<? extends Annotation> scopeType);
public ELResolver getELResolver();
@@ -95,7 +210,8 @@
public <T> InjectionTarget<T> createInjectionTarget(AnnotatedType<T> type);
}]]></programlisting>
- <para>We can obtain an instance of <literal>BeanManager</literal> via injection:</para>
+ <para>Any bean or other Java EE component which supports injection can obtain an instance of <literal>BeanManager</literal>
+ via injection:</para>
<programlisting role="JAVA">@Inject BeanManager beanManager</programlisting>
@@ -131,11 +247,10 @@
}]]></programlisting>
<para>
- It's possible to implement the <literal>Bean</literal> interface and register instances by calling
- <literal>AfterBeanDiscovery.addBean()</literal> (<literal>AfterBeanDiscovery</literal> is a built-in event type
- that an extension can observe) 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 to be injected into beans.
+ It's possible to implement the <literal>Bean</literal> interface and register instances by observing the
+ <literal>AfterBeanDiscovery</literal> container lifecycle event and calling <literal>AfterBeanDiscovery.addBean()</literal>
+ 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 to be injected into beans.
</para>
<para>
@@ -166,7 +281,21 @@
</para>
</section>
+
+ <section>
+ <title>Wrapping an <literal>AnnotatedType</literal></title>
+
+ <para>TODO</para>
+
+ </section>
+ <section>
+ <title>Wrapping an <literal>InjectionTarget</literal></title>
+
+ <para>TODO</para>
+
+ </section>
+
<!--
TODO finish me!
-->
More information about the weld-commits
mailing list