Author: jganoff
Date: 2010-05-20 21:50:38 -0400 (Thu, 20 May 2010)
New Revision: 12769
Modified:
modules/jms/trunk/docs/reference/src/main/docbook/en-US/routing.xml
Log:
Updated routing documentation to explain how to use the new EventRouting API.
Modified: modules/jms/trunk/docs/reference/src/main/docbook/en-US/routing.xml
===================================================================
--- modules/jms/trunk/docs/reference/src/main/docbook/en-US/routing.xml 2010-05-21
00:35:18 UTC (rev 12768)
+++ modules/jms/trunk/docs/reference/src/main/docbook/en-US/routing.xml 2010-05-21
01:50:38 UTC (rev 12769)
@@ -30,117 +30,96 @@
of events to JMS destinations and translating received messages from JMS
destinations back into CDI events. The
sections of this chapter will describe how to achieve both.
</para>
-
- <section id="routing.egress">
- <title>Routing CDI Events to JMS</title>
-
+
+ <section id="routing.bridge">
+ <title>Event Routing</title>
+
<para>
- The act of simply sending a message to a JMS destination involves a few players:
Connection, Session,
- Destination, and the message itself. Surely you can inject all required
resources and perform the forwarding
- yourself but that takes away from the whole reason you're using a tool in
the first place! Let's let a little
- configuration do the work for us.
+ Simply sending or receiving a message over JMS involves a few players:
Connection, Session, Destination, and
+ the message itself. Surely you can inject all required resources and perform
the routing yourself but that
+ takes away from the whole reason you're using a tool in the first place!
Let's let a little configuration do
+ the work for us.
</para>
+
+ <section id="routing.bridge.route">
+ <title>Routes</title>
+
+ <para>
+ Routing CDI events to and from JMS can be configured by defining a
<literal>Route</literal>. As you would
+ normally create an observer method for an event you can define a route to
control which events get
+ forwarded to what destination. Or conversely, what message types sent to
which destinations generate CDI
+ events.
- <section id="routing.egress.config">
- <title>Configuration</title>
+ <programlisting role="Java">public interface Route
+ {
+ public <D extends Destination> Route connectTo(Class<D>
d, D destination);
+ public Route addQualifiers(Annotation... qualifiers);
+ }</programlisting>
+ </para>
+
<para>
- Introducing the <literal>JmsForwarding</literal> interface:
- <programlisting role="Java">@Named
-@ApplicationScoped
-public interface JmsForwarding
+ Routes allows for simple mapping of event types, complete with qualifiers, to
a set of destinations. They
+ can be configured by adding qualifiers and providing destinations they should
interact with and are created
+ from an <literal>EventBridge</literal>. Here's a simple route
that forwards CDI events on to a queue:
+
+ <programlisting role="Java">@Inject EventBridge bridge;
+@EventRouting public Route registerMyRoute()
{
- public Set<? extends Destination> getDestinations();
- public Type getEventType();
- public Set<Annotation> getQualifiers();
+ return bridge.createRoute(RouteType.EGRESS, MyEvent.class).connectTo(Queue.class,
myQueue);
}</programlisting>
</para>
+ </section>
+
+ <section id="routing.bridge.eventrouting">
+ <title>@EventRouting</title>
<para>
- The <literal>JmsForwarding</literal> interface allows for simple
mapping of event types, complete with
- qualifiers, to a set of destinations. Every bean found implementing
<literal>JmsForwarding</literal> will be
- used to create a bridge from CDI to the JMS world, forwarding all events that
match the event type and
- qualifiers returned.
+ Routes are registered by returning them from a bean method annotated with
<literal>@EventRouting</literal>:
+
+ <programlisting role="Java">@Inject EventBridge bridge;
+@EventRouting public Route myConfig()
+{
+ return bridge.createRoute(RouteType.INGRESS, MyEvent.class).connectTo(Queue.class,
myTopic);
+}</programlisting>
</para>
+ </section>
+ </section>
- <caution>
- <para>
- <literal>JmsForwarding.getQualifiers()</literal> should only
return annotations that are in fact
- qualifiers. If not, Seam JMS will detect the problem and treat it as a
deployment problem.
- </para>
- </caution>
+ <section id="routing.egress">
+ <title>Routing CDI Events to JMS</title>
- <tip>
- <para>
- Since your <literal>JmsForwarding</literal> objects are CDI
Beans you can use dependency injection to
- obtain the destinations you wish to forward to.
- </para>
- </tip>
- </section>
+ <para>
+ Forwarding CDI events to JMS is configured by creating an egress route.
Let's say you wanted to forward all
+ <literal>MyEvent</literal> events with
<literal>@Bridged</literal> qualifier to the queue
+ <literal>jms/EventQueue</literal>. Simple, register a route:
+
+ <programlisting role="Java">@Inject EventBridge bridge;
+@Inject @JmsDestination(jndiName="jms/EventQueue") Queue eventQueue;
+AnnotationLiteral<Bridged> BRIDGED = new
AnnotationLiteral<Bridged>() {};
+@EventRouting public Route registerMyEventRoute()
+{
+ return bridge.createRoute(RouteType.EGRESS,
MyEvent.class).addQualifiers(BRIDGED).connectTo(Queue.class, eventQueue);
+}</programlisting>
+ </para>
<section id="routing.egress.usage">
<title>Usage</title>
<para>
- With your configuration bean defined you can simply fire events that match a
configuration's event type and
+ With your routing defined you can simply fire events that match the
route's payload type and
qualifiers and these events will be forwarded over JMS as object messages.
- <programlisting role="Java">@Inject @Bridged
Event<MyObject> event;
+ <programlisting role="Java">@Inject @Bridged
Event<MyEvent> event;
...
-event.fire(myObject);</programlisting>
+event.fire(myEvent);</programlisting>
</para>
</section>
-
- <section id="routing.egress.sample">
- <title>Egress Routing Sample</title>
-
- <para>
- Here's a sample configuration that will match any
<literal>MyObject</literal> event fired with the
- qualifier <literal>@Bridged</literal>:
-
- <programlisting role="Java">@Named
-@ApplicationScoped
-public class MyForwarding implements JmsForwarding
-{
- @Inject @MyTopic private Topic t;
-
- public Set<? extends Destination> getDestinations()
- {
- return Collections.singleton(t);
- }
-
- public Type getEventType()
- {
- return MyObject.class;
- }
-
- public Set<Annotation> getQualifiers()
- {
- return Collections.<Annotation> singleton(new
AnnotationLiteral<Bridged>(){});
- }
-}</programlisting>
- </para>
-
- <para>
- And here's an event that will be sent to JMS due to the configuration
above:
- <programlisting role="Java">@Inject @Bridged
Event<MyObject> event;
-...
-event.fire(myObject);</programlisting>
- </para>
-
- <para>
- TODO Reference to example showing this off
- </para>
- </section>
</section>
<section id="routing.ingress">
<title>CDI Events from JMS Messages</title>
<para>
-
- </para>
-
- <para>
TODO Add documentation when implemented
</para>
</section>
Show replies by date