[seam-commits] Seam SVN: r12704 - modules/jms/trunk/docs/reference/src/main/docbook/en-US.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Mon May 10 20:00:16 EDT 2010
Author: jganoff
Date: 2010-05-10 20:00:15 -0400 (Mon, 10 May 2010)
New Revision: 12704
Added:
modules/jms/trunk/docs/reference/src/main/docbook/en-US/resource-injection.xml
modules/jms/trunk/docs/reference/src/main/docbook/en-US/routing.xml
Removed:
modules/jms/trunk/docs/reference/src/main/docbook/en-US/gettingstarted.xml
Modified:
modules/jms/trunk/docs/reference/src/main/docbook/en-US/installation.xml
modules/jms/trunk/docs/reference/src/main/docbook/en-US/master.xml
Log:
Updated documentation
Deleted: modules/jms/trunk/docs/reference/src/main/docbook/en-US/gettingstarted.xml
===================================================================
--- modules/jms/trunk/docs/reference/src/main/docbook/en-US/gettingstarted.xml 2010-05-10 11:57:27 UTC (rev 12703)
+++ modules/jms/trunk/docs/reference/src/main/docbook/en-US/gettingstarted.xml 2010-05-11 00:00:15 UTC (rev 12704)
@@ -1,112 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- JBoss, Home of Professional Open Source
- Copyright 2010, Red Hat, Inc., and individual contributors
- by the @authors tag. See the copyright.txt in the distribution for a
- full listing of individual contributors.
-
- This is free software; you can redistribute it and/or modify it
- under the terms of the GNU Lesser General Public License as
- published by the Free Software Foundation; either version 2.1 of
- the License, or (at your option) any later version.
-
- This software is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public
- License along with this software; if not, write to the Free
- Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
- 02110-1301 USA, or see the FSF site: http://www.fsf.org.
--->
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" []>
-<chapter id="gettingstarted">
- <title>Getting Started</title>
-
- <para>
- In this chapter we'll look at how to inject JMS resources and route events over JMS.
- </para>
-
- <section id="injection">
- <title>JMS Resource Injection</title>
-
- <para>The following JMS resources are now available for injection:</para>
-
- <itemizedlist>
- <listitem>
- javax.jms.Connection
- </listitem>
- <listitem>
- javax.jms.Session
- </listitem>
- </itemizedlist>
-
- <para>Destination-based resources:</para>
- <itemizedlist>
- <listitem>
- javax.jms.Topic
- </listitem>
- <listitem>
- javax.jms.Queue
- </listitem>
- <listitem>
- javax.jms.TopicPublisher
- </listitem>
- <listitem>
- javax.jms.QueueSender
- </listitem>
- <listitem>
- javax.jms.TopicSubscriber
- </listitem>
- <listitem>
- javax.jms.QueueReceiver
- </listitem>
- </itemizedlist>
-
- <!-- TODO Clean up and move elsewhere
- <tip>
- You can use the <literal>@JmsSession</literal> qualifier when injecting <literal>javax.jms.Session</literal> to specify transacted and acknowledgement type:
- <programlisting role="Java">
- at Inject @JmsSession(transacted=true, acknowledgementType=Session.CLIENT_ACKNOWLEDGE) Session s;
-</programlisting>
- </tip>
- -->
-
- <section id="injection.destination-based">
- <title>Destination Based Injection</title>
-
- <para>
- The injection of resources that are themselves a <literal>javax.jms.Destination</literal> or require one needs
- a hint: What destination do you want to work with? This is provided by the
- <literal>@JmsDestination</literal> annotatation.
-
- <programlisting role="Java">
- at Inject @JmsDestination(jndiName="jms/MyTopic") Topic t;
- at Inject @JmsDestination(jndiName="jms/MyQueue") Queue q;</programlisting>
- </para>
-
- <para>
- You should create your own qualifier to provide type safe injection of predefined destinations:
- <programlisting role="Java">
- at Qualifier
- at JmsDestination(jndiName = "jms/MyTopic")
-public @interface MyTopic {}</programlisting>
- </para>
-
- <para>
- You can then use it in place of the <literal>@JmsDestination</literal> qualifier anywhere it's required:
-
- <programlisting role="Java">
- at Inject @MyTopic TopicPublisher myPub;</programlisting>
- </para>
- </section>
- </section>
-
- <section id="routing-egress">
- <title>Routing Events over JMS</title>
-
- <para>TODO</para>
- </section>
-</chapter>
Modified: modules/jms/trunk/docs/reference/src/main/docbook/en-US/installation.xml
===================================================================
--- modules/jms/trunk/docs/reference/src/main/docbook/en-US/installation.xml 2010-05-10 11:57:27 UTC (rev 12703)
+++ modules/jms/trunk/docs/reference/src/main/docbook/en-US/installation.xml 2010-05-11 00:00:15 UTC (rev 12704)
@@ -25,15 +25,20 @@
<chapter id="installation">
<title>Installation</title>
+
+ <para>
+ Seam JMS can be used by including a few libraries in your application's library folder:
+ </para>
+
+ <itemizedlist>
+ <listitem>seam-jms.jar</listitem>
+ <listitem>seam-jms-impl.jar</listitem>
+ <listitem>weld-extensions.jar</listitem>
+ </itemizedlist>
<para>
- Most features of Seam JMS are installed automatically by
- including the seam-jms.jar in your application's library folder.
- If you are using
- <ulink
- url="http://maven.apache.org/">Maven
- </ulink>
- as your build tool use the following dependency:
+ If you are using <ulink url="http://maven.apache.org/">Maven</ulink> as your build tool use the following
+ dependency:
</para>
<programlisting role="XML"><![CDATA[<dependency>
@@ -43,6 +48,8 @@
</dependency>]]></programlisting>
<tip>
- <para>Define or replace the property ${seam.jms.version} with a valid version of Seam JMS.</para>
+ <para>
+ Define or replace the property ${seam.jms.version} with a valid version of Seam JMS.
+ </para>
</tip>
</chapter>
Modified: modules/jms/trunk/docs/reference/src/main/docbook/en-US/master.xml
===================================================================
--- modules/jms/trunk/docs/reference/src/main/docbook/en-US/master.xml 2010-05-10 11:57:27 UTC (rev 12703)
+++ modules/jms/trunk/docs/reference/src/main/docbook/en-US/master.xml 2010-05-11 00:00:15 UTC (rev 12704)
@@ -27,5 +27,6 @@
<toc />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="intro.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="installation.xml" />
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="gettingstarted.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="resource-injection.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="routing.xml" />
</book>
Copied: modules/jms/trunk/docs/reference/src/main/docbook/en-US/resource-injection.xml (from rev 12703, modules/jms/trunk/docs/reference/src/main/docbook/en-US/gettingstarted.xml)
===================================================================
--- modules/jms/trunk/docs/reference/src/main/docbook/en-US/resource-injection.xml (rev 0)
+++ modules/jms/trunk/docs/reference/src/main/docbook/en-US/resource-injection.xml 2010-05-11 00:00:15 UTC (rev 12704)
@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ JBoss, Home of Professional Open Source
+ Copyright 2010, Red Hat, Inc., and individual contributors
+ by the @authors tag. See the copyright.txt in the distribution for a
+ full listing of individual contributors.
+
+ This is free software; you can redistribute it and/or modify it
+ under the terms of the GNU Lesser General Public License as
+ published by the Free Software Foundation; either version 2.1 of
+ the License, or (at your option) any later version.
+
+ This software is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this software; if not, write to the Free
+ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+-->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" []>
+<chapter id="resource-injection">
+ <title>Resource Injection</title>
+
+ <para>
+ In this chapter we'll look at how to inject some of the common JMS resource types.
+ </para>
+
+ <section id="injection">
+ <title>JMS Resource Injection</title>
+
+ <para>The following JMS resources are now available for injection:</para>
+
+ <itemizedlist>
+ <listitem>
+ javax.jms.Connection
+ </listitem>
+ <listitem>
+ javax.jms.Session
+ </listitem>
+ </itemizedlist>
+
+ <para>Destination-based resources:</para>
+ <itemizedlist>
+ <listitem>
+ javax.jms.Topic
+ </listitem>
+ <listitem>
+ javax.jms.Queue
+ </listitem>
+ <listitem>
+ javax.jms.TopicPublisher
+ </listitem>
+ <listitem>
+ javax.jms.QueueSender
+ </listitem>
+ <listitem>
+ javax.jms.TopicSubscriber
+ </listitem>
+ <listitem>
+ javax.jms.QueueReceiver
+ </listitem>
+ </itemizedlist>
+
+ <section id="injection.destination-based">
+ <title>Destination Based Injection</title>
+
+ <para>
+ The injection of resources that are themselves a <literal>javax.jms.Destination</literal> or require one needs
+ a hint: What destination do you want to work with? This is provided by the
+ <literal>@JmsDestination</literal> annotatation.
+
+ <programlisting role="Java">
+ at Inject @JmsDestination(jndiName="jms/MyTopic") Topic t;
+ at Inject @JmsDestination(jndiName="jms/MyQueue") Queue q;</programlisting>
+ </para>
+
+ <para>
+ You should create your own qualifier to provide type safe injection of predefined destinations:
+ <programlisting role="Java">
+ at Qualifier
+ at JmsDestination(jndiName = "jms/MyTopic")
+public @interface MyTopic {}</programlisting>
+ </para>
+
+ <para>
+ You can then use it in place of the <literal>@JmsDestination</literal> qualifier anywhere it's required:
+
+ <programlisting role="Java">
+ at Inject @MyTopic TopicPublisher myPub;
+...
+ at Inject @MyTopic Topic myTopic;</programlisting>
+ </para>
+ </section>
+
+ <section id="injection.configuration">
+ <title>Resource Configuration</title>
+
+ <para>
+ You can use the <literal>@JmsSession</literal> qualifier when injecting <literal>javax.jms.Session</literal> to specify transacted and acknowledgement type:
+ <programlisting role="Java">
+ at Inject @JmsSession(transacted=true, acknowledgementType=Session.CLIENT_ACKNOWLEDGE) Session s;
+</programlisting>
+ </para>
+
+ <para>
+ TODO Add other configuration options as they are implemented.
+ </para>
+ </section>
+ </section>
+</chapter>
Added: modules/jms/trunk/docs/reference/src/main/docbook/en-US/routing.xml
===================================================================
--- modules/jms/trunk/docs/reference/src/main/docbook/en-US/routing.xml (rev 0)
+++ modules/jms/trunk/docs/reference/src/main/docbook/en-US/routing.xml 2010-05-11 00:00:15 UTC (rev 12704)
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ JBoss, Home of Professional Open Source
+ Copyright 2010, Red Hat, Inc., and individual contributors
+ by the @authors tag. See the copyright.txt in the distribution for a
+ full listing of individual contributors.
+
+ This is free software; you can redistribute it and/or modify it
+ under the terms of the GNU Lesser General Public License as
+ published by the Free Software Foundation; either version 2.1 of
+ the License, or (at your option) any later version.
+
+ This software is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this software; if not, write to the Free
+ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+-->
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" []>
+<chapter id="routing">
+ <title>Bridging the Gap</title>
+
+ <para>
+ This chapter is designed to detail how to configure the CDI to JMS event bridge. Routing has two sides, sending
+ 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>
+
+ <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.
+ </para>
+
+ <section id="routing.egress.config">
+ <title>Configuration</title>
+ <para>
+ Introducing the <literal>JmsForwarding</literal> interface:
+ <programlisting role="Java">@Named
+ at ApplicationScoped
+public interface JmsForwarding
+{
+ public Set<? extends Destination> getDestinations();
+ public Type getEventType();
+ public Set<Annotation> getQualifiers();
+}</programlisting>
+ </para>
+
+ <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.
+ </para>
+
+ <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>
+
+ <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>
+
+ <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
+ qualifiers and these events will be forwarded over JMS as object messages.
+
+ <programlisting role="Java">@Inject @Bridged Event<MyObject> event;
+...
+event.fire(myObject);</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
+ at 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>
+</chapter>
+
\ No newline at end of file
More information about the seam-commits
mailing list