Weld SVN: r5079 - doc/trunk/reference/en-US.
by weld-commits＠lists.jboss.org
Author: gavin.king(a)jboss.com
Date: 2009-11-16 18:47:30 -0500 (Mon, 16 Nov 2009)
New Revision: 5079
Modified:
doc/trunk/reference/en-US/extend.xml
Log:
fix bug
Modified: doc/trunk/reference/en-US/extend.xml
===================================================================
--- doc/trunk/reference/en-US/extend.xml 2009-11-16 23:41:00 UTC (rev 5078)
+++ doc/trunk/reference/en-US/extend.xml 2009-11-16 23:47:30 UTC (rev 5079)
@@ -286,82 +286,81 @@
void afterBeanDiscovery(@Observes AfterBeanDiscovery abd, BeanManager bm) {
- //use this to read annotations of the class
- AnnotatedType<SecurityManager> at = bm.createAnnotatedType(SecurityManager.class);
+ //use this to read annotations of the class
+ AnnotatedType<SecurityManager> at = bm.createAnnotatedType(SecurityManager.class);
- //use this to instantiate the class and inject dependencies
- final InjectionTarget<SecurityManager> it = bm.createInjectionTarget(at);
+ //use this to instantiate the class and inject dependencies
+ final InjectionTarget<SecurityManager> it = bm.createInjectionTarget(at);
- abd.addBean( new Bean<SecurityManager>() {
-
- @Override
- public Class<?> getBeanClass() {
- return SecurityManager.class;
- }
-
- @Override
- public Set<InjectionPoint> getInjectionPoints() {
- return it.getInjectionPoints();
- }
-
- @Override
- public String getName() {
- return "securityManager";
- }
-
- @Override
- public Set<Annotation> getQualifiers() {
- Set<Annotation> qualifiers = new HashSet<Annotation>();
- qualifiers.add( new AnnotationLiteral<Default>() {} );
- qualifiers.add( new AnnotationLiteral<Any>() {} );
- return qualifiers;
- }
-
- @Override
- public Class<? extends Annotation> getScope() {
- return SessionScoped.class;
- }
-
- @Override
- public Set<Class<? extends Annotation>> getStereotypes() {
- return Collections.emptySet();
- }
-
- @Override
- public Set<Type> getTypes() {
- Set<Type> types = new HashSet<Type>();
- types.add(SecurityManager.class);
- types.add(Object.class);
- return types;
- }
-
- @Override
- public boolean isAlternative() {
- return false;
- }
-
- @Override
- public boolean isNullable() {
- return false;
- }
-
- @Override
- public Object create(CreationalContext<SecurityManager> ctx) {
- SecurityManager instance = it.produce(ctx);
- it.inject(instance, ctx);
- it.postConstruct(instance);
- return instance;
- }
-
- @Override
- public void destroy(SecurityManager instance, CreationalContext<SecurityManager> ctx) {
- it.preDestroy(instance);
- it.dispose(instance);
- ctx.release();
- }
-
- } );
- }
+ abd.addBean( new Bean<SecurityManager>() {
+
+ @Override
+ public Class<?> getBeanClass() {
+ return SecurityManager.class;
+ }
+
+ @Override
+ public Set<InjectionPoint> getInjectionPoints() {
+ return it.getInjectionPoints();
+ }
+
+ @Override
+ public String getName() {
+ return "securityManager";
+ }
+
+ @Override
+ public Set<Annotation> getQualifiers() {
+ Set<Annotation> qualifiers = new HashSet<Annotation>();
+ qualifiers.add( new AnnotationLiteral<Default>() {} );
+ qualifiers.add( new AnnotationLiteral<Any>() {} );
+ return qualifiers;
+ }
+
+ @Override
+ public Class<? extends Annotation> getScope() {
+ return SessionScoped.class;
+ }
+
+ @Override
+ public Set<Class<? extends Annotation>> getStereotypes() {
+ return Collections.emptySet();
+ }
+
+ @Override
+ public Set<Type> getTypes() {
+ Set<Type> types = new HashSet<Type>();
+ types.add(SecurityManager.class);
+ types.add(Object.class);
+ return types;
+ }
+
+ @Override
+ public boolean isAlternative() {
+ return false;
+ }
+
+ @Override
+ public boolean isNullable() {
+ return false;
+ }
+
+ @Override
+ public SecurityManager create(CreationalContext<SecurityManager> ctx) {
+ SecurityManager instance = it.produce(ctx);
+ it.inject(instance, ctx);
+ it.postConstruct(instance);
+ return instance;
+ }
+
+ @Override
+ public void destroy(SecurityManager instance, CreationalContext<SecurityManager> ctx) {
+ it.preDestroy(instance);
+ it.dispose(instance);
+ ctx.release();
+ }
+
+ } );
}
}]]></programlisting>
14 years, 7 months
Weld SVN: r5078 - doc/trunk/reference/en-US.
by weld-commits＠lists.jboss.org
Author: gavin.king(a)jboss.com
Date: 2009-11-16 18:41:00 -0500 (Mon, 16 Nov 2009)
New Revision: 5078
Modified:
doc/trunk/reference/en-US/extend.xml
Log:
much better portable extensions chapter
Modified: doc/trunk/reference/en-US/extend.xml
===================================================================
--- doc/trunk/reference/en-US/extend.xml 2009-11-16 04:46:28 UTC (rev 5077)
+++ doc/trunk/reference/en-US/extend.xml 2009-11-16 23:41:00 UTC (rev 5078)
@@ -79,6 +79,11 @@
into other beans once the initialization process is complete.
</para>
+ <programlisting>@Inject
+MyBean(MyExtension myExtension) {
+ myExtension.doSomething();
+}</programlisting>
+
<para>
And, like beans, extensions can have observer methods. Usually, the observer methods
observe <emphasis>container lifecycle events</emphasis>.
@@ -164,11 +169,7 @@
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>
+ <programlisting role="JAVA"><![CDATA[<T> void processAnnotatedType(ProcessAnnotatedType<T> pat, BeanManager beanManager) { ... }]]></programlisting>
</section>
@@ -213,7 +214,7 @@
<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>
+ <programlisting role="JAVA">@Inject BeanManager beanManager;</programlisting>
<para>
Java EE components may obtain an instance of <literal>BeanManager</literal> from JNDI by looking up the name
@@ -231,9 +232,21 @@
<para>
Instances of the interface <literal>Bean</literal> represent beans. There is an instance of
<literal>Bean</literal> registered with the <literal>BeanManager</literal> object for every bean in the
- application.
+ application. There are even <literal>Bean</literal> objects representing interceptors, decorators and
+ producer methods.
</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>
+
<programlisting role="JAVA"><![CDATA[public interface Bean<T> extends Contextual<T> {
public Set<Type> getTypes();
public Set<Annotation> getQualifiers();
@@ -247,41 +260,118 @@
}]]></programlisting>
<para>
- 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.
+ 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
+ to be injected into beans.
</para>
-
- <para>
- There are two subinterfaces of <literal>Bean</literal> defined by the CDI specification:
- <literal>Interceptor</literal> and <literal>Decorator</literal>.
- </para>
-
+
</section>
<section>
- <title>The <literal>Context</literal> interface</title>
-
+ <title>Registering a <literal>Bean</literal></title>
+
<para>
- The <literal>Context</literal> interface supports addition of new scopes to CDI, or extension of the built-in
- scopes to new environments.
+ The most common kind of CDI portable extension registers a bean (or beans) with the container.
</para>
+
+ <para>
+ In this example, we make a framework class, <literal>SecurityManager</literal> available
+ for injection. To make things a bit more interesting, we're going to delegate back to
+ the container's <literal>InjectionTarget</literal> to perform instantiation and injection
+ upon the <literal>SecurityManager</literal> instance.
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[public class SecurityManagerExtension implements Extension {
-<programlisting role="JAVA"><![CDATA[public interface Context {
- public Class<? extends Annotation> getScope();
- public <T> T get(Contextual<T> contextual, CreationalContext<T> creationalContext);
- public <T> T get(Contextual<T> contextual);
- boolean isActive();
+ void afterBeanDiscovery(@Observes AfterBeanDiscovery abd, BeanManager bm) {
+
+ //use this to read annotations of the class
+ AnnotatedType<SecurityManager> at = bm.createAnnotatedType(SecurityManager.class);
+
+ //use this to instantiate the class and inject dependencies
+ final InjectionTarget<SecurityManager> it = bm.createInjectionTarget(at);
+
+ abd.addBean( new Bean<SecurityManager>() {
+
+ @Override
+ public Class<?> getBeanClass() {
+ return SecurityManager.class;
+ }
+
+ @Override
+ public Set<InjectionPoint> getInjectionPoints() {
+ return it.getInjectionPoints();
+ }
+
+ @Override
+ public String getName() {
+ return "securityManager";
+ }
+
+ @Override
+ public Set<Annotation> getQualifiers() {
+ Set<Annotation> qualifiers = new HashSet<Annotation>();
+ qualifiers.add( new AnnotationLiteral<Default>() {} );
+ qualifiers.add( new AnnotationLiteral<Any>() {} );
+ return qualifiers;
+ }
+
+ @Override
+ public Class<? extends Annotation> getScope() {
+ return SessionScoped.class;
+ }
+
+ @Override
+ public Set<Class<? extends Annotation>> getStereotypes() {
+ return Collections.emptySet();
+ }
+
+ @Override
+ public Set<Type> getTypes() {
+ Set<Type> types = new HashSet<Type>();
+ types.add(SecurityManager.class);
+ types.add(Object.class);
+ return types;
+ }
+
+ @Override
+ public boolean isAlternative() {
+ return false;
+ }
+
+ @Override
+ public boolean isNullable() {
+ return false;
+ }
+
+ @Override
+ public Object create(CreationalContext<SecurityManager> ctx) {
+ SecurityManager instance = it.produce(ctx);
+ it.inject(instance, ctx);
+ it.postConstruct(instance);
+ return instance;
+ }
+
+ @Override
+ public void destroy(SecurityManager instance, CreationalContext<SecurityManager> ctx) {
+ it.preDestroy(instance);
+ it.dispose(instance);
+ ctx.release();
+ }
+
+ } );
+ }
+ }
+
}]]></programlisting>
<para>
- For example, we might implement <literal>Context</literal> to add a business process scope to CDI, or to add
- support for the conversation scope to an application that uses Wicket.
+ But a portable extension can also mess with beans that are discovered automatically by the container.
</para>
-
+
</section>
-
+
<section>
<title>Wrapping an <literal>AnnotatedType</literal></title>
@@ -290,25 +380,134 @@
<emphasis>before</emphasis> the container builds its metamodel.
</para>
- <programlisting role="JAVA"><![CDATA[class MyExtension implements Extension {
+ <para>
+ Let's start with an example of an extension that provides support for the use of <literal>@Named</literal> at
+ the package level. The package-level name is used to qualify the EL names of all beans defined in that package.
+ The portable extension uses the <literal>ProcessAnnotatedType</literal> event to wrap the
+ <literal>AnnotatedType</literal> object and override the <literal>value()</literal> of the <literal>@Named</literal>
+ annotation.
+ </para>
+ <programlisting role="JAVA"><![CDATA[public class QualifiedNameExtension implements Extension {
+
+ <X> void processAnnotatedType(@Observes ProcessAnnotatedType<X> pat) {
+
+ //wrap this to override the annotations of the class
+ final AnnotatedType<X> at = pat.getAnnotatedType();
+
+ AnnotatedType<X> wrapped = new AnnotatedType<X>() {
+
+ @Override
+ public Set<AnnotatedConstructor<X>> getConstructors() {
+ return at.getConstructors();
+ }
+
+ @Override
+ public Set<AnnotatedField<? super X>> getFields() {
+ return at.getFields();
+ }
+
+ @Override
+ public Class<X> getJavaClass() {
+ return at.getJavaClass();
+ }
+
+ @Override
+ public Set<AnnotatedMethod<? super X>> getMethods() {
+ return at.getMethods();
+ }
+
+ @Override
+ public <T extends Annotation> T getAnnotation(final Class<T> annType) {
+ if ( Named.class.equals(annType) ) {
+ class NamedLiteral
+ extends AnnotationLiteral<Named>
+ implements Named {
+ @Override
+ public String value() {
+ Package pkg = at.getClass().getPackage();
+ String unqualifiedName = at.getAnnotation(Named.class).value();
+ final String qualifiedName;
+ if ( pkg.isAnnotationPresent(Named.class) ) {
+ qualifiedName = pkg.getAnnotation(Named.class).value()
+ + '.' + unqualifiedName;
+ }
+ else {
+ qualifiedName = unqualifiedName;
+ }
+ return qualifiedName;
+ }
+ }
+ return (T) new NamedLiteral();
+ }
+ else {
+ return at.getAnnotation(annType);
+ }
+ }
+
+ @Override
+ public Set<Annotation> getAnnotations() {
+ return at.getAnnotations();
+ }
+
+ @Override
+ public Type getBaseType() {
+ return at.getBaseType();
+ }
+
+ @Override
+ public Set<Type> getTypeClosure() {
+ return at.getTypeClosure();
+ }
+
+ @Override
+ public boolean isAnnotationPresent(Class<? extends Annotation> annType) {
+ return at.isAnnotationPresent(annType);
+ }
+
+ };
+
+ pat.setAnnotatedType(wrapped);
+ }
+
+}]]></programlisting>
+
+ <para>
+ Here's a second example, which adds the <literal>@Alternative</literal> annotation to any
+ class which implements a certain <literal>Service</literal> interface.
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[class ServiceAlternativeExtension implements Extension {
+
<T> void processAnnotatedType(ProcessAnnotatedType<T> pat) {
+
final AnnotatedType<T> type = pat.getAnnotatedType();
+
if ( Service.class.isAssignableFrom( type.getJavaClass() ) ) {
+
//if the class implements Service, make it an @Alternative
AnnotatedType<T> wrapped = new AnnotatedType<T>() {
+
+ @Override
public boolean isAnnotationPresent(Class<? extends Annotation> annotationType) {
return annotationType.equals(Alternative.class) ?
true : type.isAnnotationPresent(annotationType);
}
+
+ //remaining methods of AnnotatedType
...
}
+
pat.setAnnotatedType(wrapped);
}
}
}]]></programlisting>
+ <para>
+
+ </para>
+
<para>The <literal>AnnotatedType</literal> is not the only thing that can be wrapped by an extension.</para>
</section>
@@ -323,32 +522,65 @@
to intercept any of these operations when they are invoked by the container.
</para>
- <programlisting role="JAVA"><![CDATA[class MyExtension implements Extension {
+ <programlisting role="JAVA"><![CDATA[class LogServletCreationExtension implements Extension {
<T extends Servlet> void processServlet(ProcessInjectionTarget<T> pit) {
+
+ //wrap this to intercept the component lifecycle
final InjectionTarget<T> it = pit.getInjectionTarget();
+
InjectionTarget<T> wrapped = new InjectionTarget<T>() {
+
+ @Override
public T produce(CreationalContext<T> ctx) {
Logger.global.debug("instantiating a servlet");
return it.produce(ctx);
}
+
+ @Override
public void inject(T instance, CreationalContext<T> ctx) {
Logger.global.debug("injecting servlet dependencies");
it.inject(instance, ctx);
}
+
+ //remaining methods of InjectionTarget
...
}
+
pit.setInjectionTarget(wrapped);
}
}]]></programlisting>
+ <para>
+ There's a lot more to the portable extension SPI than what we've discussed here. Check out the CDI spec or
+ Javadoc for more information. For now, we'll just mention one more extension point.
+ </para>
+
</section>
+
+ <section>
+ <title>The <literal>Context</literal> interface</title>
+
+ <para>
+ The <literal>Context</literal> interface supports addition of new scopes to CDI, or extension of the built-in
+ scopes to new environments.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public interface Context {
+ public Class<? extends Annotation> getScope();
+ public <T> T get(Contextual<T> contextual, CreationalContext<T> creationalContext);
+ public <T> T get(Contextual<T> contextual);
+ boolean isActive();
+}]]></programlisting>
- <!--
- TODO finish me!
- -->
-
+ <para>
+ For example, we might implement <literal>Context</literal> to add a business process scope to CDI, or to add
+ support for the conversation scope to an application that uses Wicket.
+ </para>
+
+ </section>
+
<!--
vim:et:ts=3:sw=3:tw=120
-->
14 years, 7 months
Weld SVN: r5077 - doc/trunk/reference/en-US.
by weld-commits＠lists.jboss.org
Author: gavin.king(a)jboss.com
Date: 2009-11-15 23:46:28 -0500 (Sun, 15 Nov 2009)
New Revision: 5077
Modified:
doc/trunk/reference/en-US/extend.xml
Log:
minor
Modified: doc/trunk/reference/en-US/extend.xml
===================================================================
--- doc/trunk/reference/en-US/extend.xml 2009-11-16 04:44:04 UTC (rev 5076)
+++ doc/trunk/reference/en-US/extend.xml 2009-11-16 04:46:28 UTC (rev 5077)
@@ -338,7 +338,7 @@
}
...
}
- pat.setInjectionTarget(wrapped);
+ pit.setInjectionTarget(wrapped);
}
}]]></programlisting>
14 years, 7 months
Weld SVN: r5076 - doc/trunk/reference/en-US.
by weld-commits＠lists.jboss.org
Author: gavin.king(a)jboss.com
Date: 2009-11-15 23:44:04 -0500 (Sun, 15 Nov 2009)
New Revision: 5076
Modified:
doc/trunk/reference/en-US/extend.xml
Log:
wrapping InjectionTarget
Modified: doc/trunk/reference/en-US/extend.xml
===================================================================
--- doc/trunk/reference/en-US/extend.xml 2009-11-16 04:18:06 UTC (rev 5075)
+++ doc/trunk/reference/en-US/extend.xml 2009-11-16 04:44:04 UTC (rev 5076)
@@ -309,13 +309,40 @@
}]]></programlisting>
+ <para>The <literal>AnnotatedType</literal> is not the only thing that can be wrapped by an extension.</para>
+
</section>
<section>
<title>Wrapping an <literal>InjectionTarget</literal></title>
- <para>TODO</para>
+ <para>
+ The <literal>InjectionTarget</literal> interface exposes operations for producing and disposing an instance
+ of a component, injecting its dependencies and invoking its lifecycle callbacks. A portable extension may
+ wrap the <literal>InjectionTarget</literal> for any Java EE component that supports injection, allowing it
+ to intercept any of these operations when they are invoked by the container.
+ </para>
+ <programlisting role="JAVA"><![CDATA[class MyExtension implements Extension {
+
+ <T extends Servlet> void processServlet(ProcessInjectionTarget<T> pit) {
+ final InjectionTarget<T> it = pit.getInjectionTarget();
+ InjectionTarget<T> wrapped = new InjectionTarget<T>() {
+ public T produce(CreationalContext<T> ctx) {
+ Logger.global.debug("instantiating a servlet");
+ return it.produce(ctx);
+ }
+ public void inject(T instance, CreationalContext<T> ctx) {
+ Logger.global.debug("injecting servlet dependencies");
+ it.inject(instance, ctx);
+ }
+ ...
+ }
+ pat.setInjectionTarget(wrapped);
+ }
+
+}]]></programlisting>
+
</section>
<!--
14 years, 7 months
Weld SVN: r5075 - doc/trunk/reference/en-US.
by weld-commits＠lists.jboss.org
Author: gavin.king(a)jboss.com
Date: 2009-11-15 23:18:06 -0500 (Sun, 15 Nov 2009)
New Revision: 5075
Modified:
doc/trunk/reference/en-US/extend.xml
Log:
wrapping AnnotatedType
Modified: doc/trunk/reference/en-US/extend.xml
===================================================================
--- doc/trunk/reference/en-US/extend.xml 2009-11-16 03:52:02 UTC (rev 5074)
+++ doc/trunk/reference/en-US/extend.xml 2009-11-16 04:18:06 UTC (rev 5075)
@@ -285,8 +285,30 @@
<section>
<title>Wrapping an <literal>AnnotatedType</literal></title>
- <para>TODO</para>
+ <para>
+ One of the most interesting things that an extension class can do is process the annotations of a bean class
+ <emphasis>before</emphasis> the container builds its metamodel.
+ </para>
+ <programlisting role="JAVA"><![CDATA[class MyExtension implements Extension {
+
+ <T> void processAnnotatedType(ProcessAnnotatedType<T> pat) {
+ final AnnotatedType<T> type = pat.getAnnotatedType();
+ if ( Service.class.isAssignableFrom( type.getJavaClass() ) ) {
+ //if the class implements Service, make it an @Alternative
+ AnnotatedType<T> wrapped = new AnnotatedType<T>() {
+ public boolean isAnnotationPresent(Class<? extends Annotation> annotationType) {
+ return annotationType.equals(Alternative.class) ?
+ true : type.isAnnotationPresent(annotationType);
+ }
+ ...
+ }
+ pat.setAnnotatedType(wrapped);
+ }
+ }
+
+}]]></programlisting>
+
</section>
<section>
14 years, 7 months
Weld SVN: r5074 - doc/trunk/reference/en-US.
by weld-commits＠lists.jboss.org
Author: gavin.king(a)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!
-->
14 years, 7 months
Weld SVN: r5073 - doc/trunk/reference/en-US.
by weld-commits＠lists.jboss.org
Author: gavin.king(a)jboss.com
Date: 2009-11-15 21:07:52 -0500 (Sun, 15 Nov 2009)
New Revision: 5073
Modified:
doc/trunk/reference/en-US/injection.xml
Log:
explain
Modified: doc/trunk/reference/en-US/injection.xml
===================================================================
--- doc/trunk/reference/en-US/injection.xml 2009-11-16 02:04:01 UTC (rev 5072)
+++ doc/trunk/reference/en-US/injection.xml 2009-11-16 02:07:52 UTC (rev 5073)
@@ -268,7 +268,9 @@
<para>Whenever a bean or injection point does not explicitly declare a qualifier, the container assumes the
qualifier <literal>@Default</literal>. From time to time, you'll need to decare an injection point without
- specifying a qualifier. There's a qualifier for that too. All beans have the qualifier <literal>@Any</literal>.</para>
+ specifying a qualifier. There's a qualifier for that too. All beans have the qualifier <literal>@Any</literal>.
+ Therefore, by explicitly specifying <literal>@Any</literal> at an injection point, you suppress the default
+ qualifier, without otherwise restricting the beans that are eligible for injection.</para>
<tip>
<para>This is especially useful if you want to iterate over all beans with a certain bean type. For example:</para>
14 years, 7 months
Weld SVN: r5072 - doc/trunk/reference/en-US.
by weld-commits＠lists.jboss.org
Author: gavin.king(a)jboss.com
Date: 2009-11-15 21:04:01 -0500 (Sun, 15 Nov 2009)
New Revision: 5072
Modified:
doc/trunk/reference/en-US/beans.xml
doc/trunk/reference/en-US/injection.xml
doc/trunk/reference/en-US/scopescontexts.xml
Log:
new tip
Modified: doc/trunk/reference/en-US/beans.xml
===================================================================
--- doc/trunk/reference/en-US/beans.xml 2009-11-16 01:49:47 UTC (rev 5071)
+++ doc/trunk/reference/en-US/beans.xml 2009-11-16 02:04:01 UTC (rev 5072)
@@ -250,11 +250,11 @@
<!--
<tip>
<para>
- If you're expectng more than one bean to satisfy the contract, you can inject an <literal>Instance</literal>,
+ If you're expecting more than one bean to satisfy the contract, you can inject an <literal>Instance</literal>,
object which let's you iterate over all the beans which satisfy the contract. For example, we can iterate
over all our implementations of <literal>PaymentProcessor</literal> using:
</para>
- <programlisting>@Inject void init(@Any Instance<PaymentProcessor> paymentProcessorInstance) {
+ <programlisting role="JAVA">@Inject void init(@Any Instance<PaymentProcessor> paymentProcessorInstance) {
for (PaymentProcessor pp: paymentProcessorInstance) { ... }
}</programlisting>
</tip>
Modified: doc/trunk/reference/en-US/injection.xml
===================================================================
--- doc/trunk/reference/en-US/injection.xml 2009-11-16 01:49:47 UTC (rev 5071)
+++ doc/trunk/reference/en-US/injection.xml 2009-11-16 02:04:01 UTC (rev 5072)
@@ -262,6 +262,25 @@
</para>
</section>
+
+ <section>
+ <title>The built-in qualifiers <literal>@Default</literal> and <literal>@Any</literal></title>
+
+ <para>Whenever a bean or injection point does not explicitly declare a qualifier, the container assumes the
+ qualifier <literal>@Default</literal>. From time to time, you'll need to decare an injection point without
+ specifying a qualifier. There's a qualifier for that too. All beans have the qualifier <literal>@Any</literal>.</para>
+
+ <tip>
+ <para>This is especially useful if you want to iterate over all beans with a certain bean type. For example:</para>
+ <programlisting role="JAVA"><![CDATA[@Inject
+void initServices(@Any Instance<Service> services) {
+ for (Service service: services) {
+ service.init();
+ }
+}]]></programlisting>
+ </tip>
+
+ </section>
<section>
<title>Qualifiers with members</title>
Modified: doc/trunk/reference/en-US/scopescontexts.xml
===================================================================
--- doc/trunk/reference/en-US/scopescontexts.xml 2009-11-16 01:49:47 UTC (rev 5071)
+++ doc/trunk/reference/en-US/scopescontexts.xml 2009-11-16 02:04:01 UTC (rev 5072)
@@ -37,7 +37,7 @@
which just doesn't map naturally to the model used in CDI. Therefore, we recommend against treating entities
as CDI beans. You're certainly going to run into problems if you try to give an entity a scope other than
the default scope <literal>@Dependent</literal>. The client proxy will get in the way if you try to pass
- an injected instance to the JPA |EntityManager|.
+ an injected instance to the JPA <literal>EntityManager</literal>.
</para>
</tip>
14 years, 7 months
Weld SVN: r5071 - doc/trunk/reference/en-US.
by weld-commits＠lists.jboss.org
Author: gavin.king(a)jboss.com
Date: 2009-11-15 20:49:47 -0500 (Sun, 15 Nov 2009)
New Revision: 5071
Modified:
doc/trunk/reference/en-US/ee.xml
Log:
tip
Modified: doc/trunk/reference/en-US/ee.xml
===================================================================
--- doc/trunk/reference/en-US/ee.xml 2009-11-16 01:42:52 UTC (rev 5070)
+++ doc/trunk/reference/en-US/ee.xml 2009-11-16 01:49:47 UTC (rev 5071)
@@ -53,6 +53,18 @@
</para>
</note>
+ <tip>
+ <para>
+ Oh, you <emphasis>really</emphasis> want to inject the <literal>FacesContext</literal>? Alright then, try
+ this producer method:
+ </para>
+ <programlisting role="JAVA"><![CDATA[class FacesContextProducer {
+ @Produces @RequestScoped FacesContext getFacesContext() {
+ return FacesContext.getCurrentInstance();
+ }
+}]]></programlisting>
+ </tip>
+
</section>
<section>
14 years, 7 months
Weld SVN: r5070 - doc/trunk/reference/en-US.
by weld-commits＠lists.jboss.org
Author: gavin.king(a)jboss.com
Date: 2009-11-15 20:42:52 -0500 (Sun, 15 Nov 2009)
New Revision: 5070
Modified:
doc/trunk/reference/en-US/beans.xml
doc/trunk/reference/en-US/scopescontexts.xml
Log:
remove duplication
Modified: doc/trunk/reference/en-US/beans.xml
===================================================================
--- doc/trunk/reference/en-US/beans.xml 2009-11-16 01:38:56 UTC (rev 5069)
+++ doc/trunk/reference/en-US/beans.xml 2009-11-16 01:42:52 UTC (rev 5070)
@@ -286,8 +286,9 @@
<note>
<para>
Keep in mind that once a bean is bound to a context, it remains in that context until the context is
- destroyed. There is no way to explicitly remove a bean from a context. If you don't the bean to live in
- the session indefinitely, consider using another scope such as the request or conversation scope instead.
+ destroyed. There is no way to manually remove a bean from a context. If you don't want the bean to sit
+ in the session indefinitely, consider using another scope with a shorted lifespan, such as the request
+ or conversation scope.
</para>
</note>
Modified: doc/trunk/reference/en-US/scopescontexts.xml
===================================================================
--- doc/trunk/reference/en-US/scopescontexts.xml 2009-11-16 01:38:56 UTC (rev 5069)
+++ doc/trunk/reference/en-US/scopescontexts.xml 2009-11-16 01:42:52 UTC (rev 5070)
@@ -40,12 +40,6 @@
an injected instance to the JPA |EntityManager|.
</para>
</tip>
-
- <note>
- <para>
- There's actually no way to remove a bean from a context until the entire context is destroyed.
- </para>
- </note>
<section>
<title>Scope types</title>
14 years, 7 months