9:56 p.m.
Author: gavin.king(a)jboss.com
Date: 2009-11-09 22:56:39 -0500 (Mon, 09 Nov 2009)
New Revision: 4934
Modified:
doc/trunk/reference/en-US/events.xml
doc/trunk/reference/en-US/stereotypes.xml
Log:
updates
Modified: doc/trunk/reference/en-US/events.xml
===================================================================
--- doc/trunk/reference/en-US/events.xml 2009-11-10 03:43:13 UTC (rev 4933)
+++ doc/trunk/reference/en-US/events.xml 2009-11-10 03:56:39 UTC (rev 4934)
@@ -5,80 +5,55 @@
<para>
Dependency injection enables loose-coupling by allowing the implementation of the
injected bean type to vary,
- either a deployment time or runtime. Events provide a whole other level of
decoupling in which there is no compile
- time dependency between the interacting beans at all. Event
<emphasis>producers</emphasis> raise (or fire) events
- that are delivered to event <emphasis>observers</emphasis>, an exchange
orchestrated by the container.
+ either a deployment time or runtime. Events go one step further, allowing beans to
interact with no compile
+ time dependency at all. Event <emphasis>producers</emphasis> raise
events that are delivered to event
+ <emphasis>observers</emphasis> by the container.
</para>
- <para>
- CDI provides an event notification facility like the one just described. It does so
using the same type safe
- approach that you've become accustomed to with CDI's dependency injection
service. In fact, it consists of all the
- same ingredients:
- </para>
-
+ <para>This basic schema might sound like the familiar observer/observable
pattern, but there are a couple of
+ twists:</para>
+
<itemizedlist>
- <listitem><para>bean types,</para></listitem>
- <listitem><para>qualifier annotations
and</para></listitem>
- <listitem><para>type-safe resolution.</para></listitem>
- </itemizedlist>
-
- <para>
- It also supports a couple of convenient features that extend beyond the basic
observer/observable pattern:
- </para>
-
- <itemizedlist>
<listitem>
- <para>events are qualified using annotations on the event producer
object,</para>
+ <para>not only are event producers decoupled from observers; observers are
completely decoupled from
+ producers,</para>
</listitem>
<listitem>
- <para>observers are completely decoupled from producers,</para>
- </listitem>
- <listitem>
<para>
- observers can specify a combination of "selectors" to narrow the
set of event notifications (described by
- qualifiers) they will receive, and
+ observers can specify a combination of "selectors" to narrow the
set of event notifications they will
+ receive, and
</para>
</listitem>
<listitem>
<para>
- observers can be notified immediately, or can specify that delivery of the
event should be delayed until the
- end of the current transaction (a very useful feature for enterprise web
applications).
+ observers can be notified immediately, or can specify that delivery of the
event should be delayed until
+ the end of the current transaction.
</para>
</listitem>
</itemizedlist>
-
- <para>
- Before getting into how events are produced, let's first consider what's
used as the event payload and how those
- events are observed. We'll then hook everything together by looking at how an
event is fired.
- </para>
-
+
+ <para>The CDI event notification facility uses more or less the same typesafe
approach that we've already
+ seen with the dependency injection service.</para>
+
<section>
<title>Event payload</title>
<para>
- The event payload carries state from producer to consumer. The event is nothing
more than a plain Java
- object--an instance of any Java type. (The only restriction is that an event
type may not contain type
- variables). No special interfaces or wrappers. In addition, that object can be
assigned qualifiers, which helps
- observers distinguish it from other events of the same type. In a way, the
qualifiers are like topic selectors,
- since they allow the observers to narrow the set of events it observes.
+ The event object carries state from producer to consumer. The event object is
nothing more than an instance of
+ a concrete Java class. (The only restriction is that an event type may not
contain type variables). An event
+ may be assigned qualifiers, which allows observers to distinguish it from other
events of the same type. The
+ qualifiers function like topic selectors, allowing an observer to narrow the set
of events it observes.
</para>
<para>
- So what's an event qualifier? An event qualifier is just a normal qualifier,
the same ones you assigned to
- beans and injection points. Here's an example.
+ An event qualifier is just a normal qualifier, defined using
<literal>@Qualifier</literal>. Here's an example:
</para>
<programlisting role="JAVA"><![CDATA[@Qualifier
@Target({FIELD, PARAMETER})
@Retention(RUNTIME)
-public @interface Updated {}]]></programlisting>
+public @interface Updated {}]]></programlisting>
- <para>
- These qualifiers may or may not come into play when selecting an observer. As
before, a qualifier type can have
- members. Those members are considered as well when selecting an observer.
However, only if the member is not
- annotated <literal>@NonBinding</literal>, which causes it to be
ignored by the selection process.
- </para>
-
</section>
<section>
@@ -93,26 +68,20 @@
<para>
The annotated parameter is called the <emphasis>event
parameter</emphasis>. The type of the event parameter is
- the observed <emphasis>event type</emphasis>, in this case
<literal>Document</literal>, a class in the
- application. Observer methods may also specify "selectors", which are
just qualifiers, as just described. When
- a qualifier is used as an event selector, it's called an
<emphasis>event qualifier type</emphasis>.
+ the observed <emphasis>event type</emphasis>, in this case
<literal>Document</literal>. The event parameter may
+ also specify qualifiers.
</para>
- <para>
- We specify the event qualifiers of the observer method by annotating the event
parameter:
- </para>
-
<programlisting role="JAVA"><![CDATA[public void
afterDocumentUpdate(@Observes @Updated Document document) { ...
}]]></programlisting>
<para>
- An observer method need not specify any event qualifiers — in this
case it is interested in
- <emphasis>all</emphasis> events of a particular type. If it does
specify event bindings, it's only interested
- in events which also have those qualifiers.
+ An observer method need not specify any event qualifiers—in this case
it is interested in
+ <emphasis>all</emphasis> events of a particular type. If it does
specify qualifiers, it's only interested
+ in events which have those qualifiers.
</para>
<para>
- The observer method may have <emphasis>additional</emphasis>
parameters, which are injected according to the
- usual bean method parameter injection semantics:
+ The observer method may have additional parameters, which are injection points:
</para>
<programlisting role="JAVA"><![CDATA[public void
afterDocumentUpdate(@Observes @Updated Document document, User user) { ...
}]]></programlisting>
@@ -120,18 +89,18 @@
</section>
<section>
- <title>Event producers (Firing events)</title>
+ <title>Event producers</title>
<para>
- Producers (i.e., beans) fire events using an instance of the parameterized
<literal>Event</literal> interface.
- Instances of this interface are obtained through injection:
+ Event producers fire events using an instance of the parameterized
<literal>Event</literal> interface.
+ An instance of this interface are obtained by injection:
</para>
<programlisting role="JAVA"><![CDATA[@Inject @Any
Event<Document> documentEvent;]]></programlisting>
<para>
A producer raises events by calling the <literal>fire()</literal>
method of the <literal>Event</literal>
- interface, passing an <emphasis>event object</emphasis>:
+ interface, passing the event object:
</para>
<programlisting
role="JAVA"><![CDATA[documentEvent.fire(document);]]></programlisting>
@@ -142,10 +111,11 @@
<itemizedlist>
<listitem>
- <para>has an event parameter to which the event object is assignable
(i.e., <literal>Document</literal>), and</para>
+ <para>has an event parameter to which the event object (the
<literal>Document</literal>) is assignable,
+ and</para>
</listitem>
<listitem>
- <para>specifies no qualifier bindings.</para>
+ <para>specifies no qualifiers.</para>
</listitem>
</itemizedlist>
@@ -185,8 +155,8 @@
</listitem>
<listitem>
<para>
- does not have any event qualifier <emphasis>except</emphasis>
for the event qualifiers that match those
- on the producer (in this case at the <literal>Event</literal>
inject point).
+ does not have any event qualifier <emphasis>except</emphasis>
for the event qualifiers that match
+ those specified at the <literal>Event</literal> injection
point.
</para>
</listitem>
</itemizedlist>
Modified: doc/trunk/reference/en-US/stereotypes.xml
===================================================================
--- doc/trunk/reference/en-US/stereotypes.xml 2009-11-10 03:43:13 UTC (rev 4933)
+++ doc/trunk/reference/en-US/stereotypes.xml 2009-11-10 03:56:39 UTC (rev 4934)
@@ -10,7 +10,7 @@
<para>
In many systems, use of architectural patterns produces a set of recurring bean
roles. A stereotype allows a
- framework de- veloper to identify such a role and declare some common metadata
for beans with that role in a
+ framework developer to identify such a role and declare some common metadata for
beans with that role in a
central place.
</para>
@@ -46,14 +46,14 @@
</blockquote>
<para>
- In layman's terms, a stereotype is a meta-annotation (an annotation used on
another annotation) annotated with
- <literal>@Stereotype</literal> that bundles other Java annotations to
give them a particular semantic. For
- instance, the following stereotype identifies action classes in some MVC
framework:
+ A stereotype is an annotation, annotated
<literal>@Stereotype</literal>, that packages several other annotations.
+ For instance, the following stereotype identifies action classes in some MVC
framework:
</para>
<programlisting role="JAVA"><![CDATA[@Stereotype
@Retention(RUNTIME)
@Target(TYPE)
+...
public @interface Action {}]]></programlisting>
<para>
@@ -64,16 +64,14 @@
public class LoginAction { ... }]]></programlisting>
<para>
- Of course, we need to associate our stereotype annotation with some other
annotations or else it isn't doing much
- for us. Let's see how to add them.
+ Of course, we need to apply some other annotations to our stereotype or else it
wouldn't be adding much value.
</para>
<section>
<title>Default scope for a stereotype</title>
<para>
- A stereotype may specify a default scope for beans annotated with the
stereotype. For example, if the we might
- specify the following defaults for action classes in a web application:
+ A stereotype may specify a default scope for beans annotated with the
stereotype. For example:
</para>
<programlisting role="JAVA"><![CDATA[@RequestScoped
@@ -83,7 +81,7 @@
public @interface Action {}]]></programlisting>
<para>
- Of course, a particular action may still override this default if necessary:
+ A particular action may still override this default if necessary:
</para>
<programlisting role="JAVA"><![CDATA[@Dependent @Action
@@ -122,8 +120,7 @@
<para>
We can specify that all beans with a certain stereotype have a defaulted EL name
when a name is not explicitly
- defined on that bean. Actions are often referenced in JSF views, so they're
a perfect use case for this
- feature. All we need to do is add an empty <literal>@Named</literal>
annotation:
+ defined for that bean. All we need to do is add an empty
<literal>@Named</literal> annotation:
</para>
<programlisting role="JAVA"><![CDATA[@RequestScoped
@@ -136,18 +133,16 @@
public @interface Action {}]]></programlisting>
<para>
- Now, <literal>LoginAction</literal> bean from above will have the
name <literal>loginAction</literal>.
+ Now, the <literal>LoginAction</literal> bean will have the defaulted
name <literal>loginAction</literal>.
</para>
</section>
<section>
- <title>Alternatives as stereotypes</title>
+ <title>Alternative stereotypes</title>
<para>
- A stereotype can indicate that all beans to which it is applied are
<literal>@Alternative</literal> beans. If
- you can remember back to the early days of the specification, this is the
closest match to a deployment type.
- Whole sets of beans can be enabled or left disabled by activating a single
stereotype.
+ A stereotype can indicate that all beans to which it is applied are
<literal>@Alternative</literal>s.
</para>
<programlisting role="JAVA"><![CDATA[@Alternative
@@ -157,12 +152,18 @@
public @interface Mock {}]]></programlisting>
<para>
- Now you apply this stereotype to beans that should be active in mock
environments.
+ We can apply an alternative stereotype to a whole set of beans, and activate
them all with one line
+ of code in <literal>beans.xml</literal>.
</para>
<programlisting role="JAVA"><![CDATA[@Mock
public class MockLoginAction extends LoginAction { ... }]]></programlisting>
+ <programlisting role="JAVA"><![CDATA[<beans>
+ <alternatives>
+ <stereotype>org.mycompany.testing.Mock</stereotype>
+ </alternatives>
+</beans>]]></programlisting>
</section>
<section>
@@ -209,7 +210,7 @@
public @interface Model {}]]></programlisting>
<para>
- Instead of using JSF managed beans, just annotate a Web Bean
<literal>@Model</literal>, and use it directly in
+ Instead of using JSF managed beans, just annotate a bean
<literal>@Model</literal>, and use it directly in
your JSF view!
</para>