From seam-commits at lists.jboss.org Thu May 20 21:50:39 2010
Content-Type: multipart/mixed; boundary="===============3720297908666783720=="
MIME-Version: 1.0
From: seam-commits at lists.jboss.org
To: seam-commits at lists.jboss.org
Subject: [seam-commits] Seam SVN: r12769 -
modules/jms/trunk/docs/reference/src/main/docbook/en-US.
Date: Thu, 20 May 2010 21:50:39 -0400
Message-ID: <201005210150.o4L1odap020969@svn01.web.mwc.hst.phx2.redhat.com>
--===============3720297908666783720==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
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 AP=
I.
Modified: modules/jms/trunk/docs/reference/src/main/docbook/en-US/routing.x=
ml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- modules/jms/trunk/docs/reference/src/main/docbook/en-US/routing.xml 201=
0-05-21 00:35:18 UTC (rev 12768)
+++ modules/jms/trunk/docs/reference/src/main/docbook/en-US/routing.xml 201=
0-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.
-
-
- Routing CDI Events to JMS
-
+ =
+
+ Event Routing
+ =
- 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 r=
equired 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 pla=
yers: 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.
+ =
+
+ Routes
+ =
+
+ Routing CDI events to and from JMS can be configured by defini=
ng a Route. 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 ty=
pes sent to which destinations generate CDI =
+ events.
=
-
- Configuration
+ public interface Route
+ {
+ public <D extends Destination> Route connectTo(Class<D> =
d, D destination);
+ public Route addQualifiers(Annotation... qualifiers);
+ }
+
+
- Introducing the JmsForwarding interface:
- @Named
-(a)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 destinati=
ons they should interact with and are created
+ from an EventBridge. Here's a simple route =
that forwards CDI events on to a queue:
+ =
+ @Inject EventBridge bridge;
+(a)EventRouting public Route registerMyRoute()
{
- public Set<? extends Destination> getDestinations();
- public Type getEventType();
- public Set<Annotation> getQualifiers();
+ return bridge.createRoute(RouteType.EGRESS, MyEvent.class).connectTo(Qu=
eue.class, myQueue);
}
+
+ =
+
+ @EventRouting
=
- The JmsForwarding interface allows for simp=
le mapping of event types, complete with =
- qualifiers, to a set of destinations. Every bean found implem=
enting JmsForwarding 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 ann=
otated with @EventRouting:
+ =
+ @Inject EventBridge bridge;
+(a)EventRouting public Route myConfig()
+{
+ return bridge.createRoute(RouteType.INGRESS, MyEvent.class).connectTo(Q=
ueue.class, myTopic);
+}
+
+
=
-
-
- JmsForwarding.getQualifiers() should onl=
y return annotations that are in fact =
- qualifiers. If not, Seam JMS will detect the problem and t=
reat it as a deployment problem. =
-
-
+
+ Routing CDI Events to JMS
=
-
-
- Since your JmsForwarding objects are CDI=
Beans you can use dependency injection to =
- obtain the destinations you wish to forward to.
-
-
-
+
+ Forwarding CDI events to JMS is configured by creating an egress =
route. Let's say you wanted to forward all
+ MyEvent events with @Bridged qualifier to the queue =
+ jms/EventQueue. Simple, register a route:
+ =
+ @Inject EventBridge bridge;
+(a)Inject @JmsDestination(jndiName=3D"jms/EventQueue") Queue eventQueue;
+AnnotationLiteral<Bridged> BRIDGED =3D new AnnotationLiteral<Brid=
ged>() {};
+(a)EventRouting public Route registerMyEventRoute()
+{
+ return bridge.createRoute(RouteType.EGRESS, MyEvent.class).addQualifier=
s(BRIDGED).connectTo(Queue.class, eventQueue);
+}
+
=
=
Usage
- With your configuration bean defined you can simply fire event=
s that match a configuration's event type and
+ With your routing defined you can simply fire events that matc=
h the route's payload type and
qualifiers and these events will be forwarded over JMS as obje=
ct messages.
=
- @Inject @Bridged Event<MyObje=
ct> event;
+ @Inject @Bridged Event<MyEven=
t> event;
...
-event.fire(myObject);
+event.fire(myEvent);
-
-
- Egress Routing Sample
-
-
- Here's a sample configuration that will match any MyO=
bject event fired with the =
- qualifier @Bridged:
-
- @Named
-(a)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 AnnotationLitera=
l<Bridged>(){});
- }
-}
-
-
-
- And here's an event that will be sent to JMS due to the config=
uration above:
- @Inject @Bridged Event<MyObje=
ct> event;
-...
-event.fire(myObject);
-
- =
-
- TODO Reference to example showing this off
-
-
=
CDI Events from JMS Messages
=
- =
-
- =
-
TODO Add documentation when implemented
--===============3720297908666783720==--