8:23 p.m.
Author: gavin.king(a)jboss.com
Date: 2009-11-09 21:23:12 -0500 (Mon, 09 Nov 2009)
New Revision: 4927
Modified:
doc/trunk/reference/en-US/decorators.xml
doc/trunk/reference/en-US/interceptors.xml
Log:
revisions
Modified: doc/trunk/reference/en-US/decorators.xml
===================================================================
--- doc/trunk/reference/en-US/decorators.xml 2009-11-10 02:01:50 UTC (rev 4926)
+++ doc/trunk/reference/en-US/decorators.xml 2009-11-10 02:23:12 UTC (rev 4927)
@@ -17,8 +17,8 @@
interface, and is therefore aware of all the semantics attached to that interface.
Since decorators directly
implement operations with business semantics, it makes them the perfect tool for
modeling some kinds of business
concerns. It also means that a decorator doesn't have the generality of an
interceptor. Decorators aren't able to
- solve technical concerns that cut across many disparate types. The two complement
one another. Let's look at some
- cases where decorators fit the bill.
+ solve technical concerns that cut across many disparate types. Interceptors and
decorators, though similar in many
+ ways, are complementary. Let's look at some cases where decorators fit the
bill.
</para>
<para>Suppose we have an interface that represents accounts:</para>
Modified: doc/trunk/reference/en-US/interceptors.xml
===================================================================
--- doc/trunk/reference/en-US/interceptors.xml 2009-11-10 02:01:50 UTC (rev 4926)
+++ doc/trunk/reference/en-US/interceptors.xml 2009-11-10 02:23:12 UTC (rev 4927)
@@ -5,20 +5,13 @@
<title>Interceptors</title>
<para>
- Thanks to the managed bean specification, interceptors are now part of the core
functionality of a bean. That
- means that you no longer need to make your class an EJB just to use interceptors!
+ Interceptor functionality is defined in the Java Interceptors specification. CDI
enhances this functionality with
+ a more sophisticated, semantic, annotation-based approach to binding interceptors
to beans.
</para>
<para>
- But that doesn't mean there aren't other improvements that can be made. CDI
builds on the interceptor architecture
- of managed beans by introducing a more sophisticated, semantic, annotation-based
approach to binding interceptors
- to beans.
+ The Interceptors specification defines two kinds of interception points:
</para>
-
- <para>
- Interceptor functionality is defined in the interceptor specification, which the
managed bean, CDI, and EJB
- specifications all support. The interceptor specification defines two kinds of
interception points:
- </para>
<itemizedlist>
<listitem>
@@ -30,12 +23,17 @@
</itemizedlist>
<para>
+ In addition, the EJB specification defines timeout method interception.
+ </para>
+
+ <para>
A <emphasis>business method interceptor</emphasis> applies to
invocations of methods of the bean by clients of the
bean:
</para>
<programlisting role="JAVA"><![CDATA[public class
TransactionInterceptor {
- @AroundInvoke public Object manageTransaction(InvocationContext ctx) throws Exception
{ ... }
+ @AroundInvoke
+ public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
}]]></programlisting>
<para>
@@ -44,19 +42,30 @@
</para>
<programlisting role="JAVA"><![CDATA[public class
DependencyInjectionInterceptor {
- @PostConstruct public void injectDependencies(InvocationContext ctx) { ... }
+ @PostConstruct
+ public void injectDependencies(InvocationContext ctx) { ... }
}]]></programlisting>
<para>
An interceptor class may intercept both lifecycle callbacks and business methods.
</para>
+
+ <para>
+ A <emphasis>timeout method interceptor</emphasis> applies to
invocations of EJB timeout methods by the
+ container:
+ </para>
+ <programlisting role="JAVA"><![CDATA[public class
TimeoutInterceptor {
+ @AroundTimeout
+ public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
+}]]></programlisting>
+
<section>
<title>Interceptor bindings</title>
<para>
Suppose we want to declare that some of our beans are transactional. The first
thing we need is an
- <emphasis>interceptor binding annotation</emphasis> to specify
exactly which beans we're interested in:
+ <emphasis>interceptor binding type</emphasis> to specify exactly
which beans we're interested in:
</para>
<programlisting role="JAVA"><![CDATA[@InterceptorBinding
@@ -92,20 +101,21 @@
<programlisting role="JAVA"><![CDATA[@Transactional
@Interceptor
public class TransactionInterceptor {
- @AroundInvoke public Object manageTransaction(InvocationContext ctx) throws Exception
{ ... }
+ @AroundInvoke
+ public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
}]]></programlisting>
<para>
- All bean interceptors are beans, and can take advantage of dependency injection
and contextual lifecycle
- management.
+ Interceptors can take advantage of dependency injection:
</para>
- <programlisting role="JAVA"><![CDATA[@ApplicationScoped
@Transactional @Interceptor
+ <programlisting role="JAVA"><![CDATA[@Transactional
@Interceptor
public class TransactionInterceptor {
- @Resource Transaction transaction;
+ @Inject UserTransaction transaction;
- @AroundInvoke public Object manageTransaction(InvocationContext ctx) throws Exception
{ ... }
+ @AroundInvoke
+ public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
}]]></programlisting>
@@ -169,7 +179,8 @@
</interceptors>
</beans>]]></programlisting>
- <para>Or we could turn them both off in our test environment by simply taking
no action! Ah, so simple.</para>
+ <para>Or we could turn them both off in our test environment by simply not
mentioning them in
+ <literal>beans.xml</literal>! Ah, so simple.</para>
</section>
@@ -194,7 +205,8 @@
<programlisting role="JAVA"><![CDATA[@Transactional(requiresNew
= true) @Interceptor
public class RequiresNewTransactionInterceptor {
- @AroundInvoke public Object manageTransaction(InvocationContext ctx) throws Exception
{ ... }
+ @AroundInvoke
+ public Object manageTransaction(InvocationContext ctx) throws Exception { ... }
}]]></programlisting>
<para>