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"> -@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"> -@Inject @JmsDestination(jndiName="jms/MyTopic") Topic t; -@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"> -@Qualifier -@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"> -@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"> +@Inject @JmsDestination(jndiName="jms/MyTopic") Topic t; +@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"> +@Qualifier +@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"> +@Inject @MyTopic TopicPublisher myPub; +... +@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"> +@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 +@ApplicationScoped +public interface JmsForwarding +{ + public Set&lt;? extends Destination&gt; getDestinations(); + public Type getEventType(); + public Set&lt;Annotation&gt; 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&lt;MyObject&gt; 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 +@ApplicationScoped +public class MyForwarding implements JmsForwarding +{ + @Inject @MyTopic private Topic t; + + public Set&lt;? extends Destination&gt; getDestinations() + { + return Collections.singleton(t); + } + + public Type getEventType() + { + return MyObject.class; + } + + public Set&lt;Annotation&gt; getQualifiers() + { + return Collections.&lt;Annotation&gt; singleton(new AnnotationLiteral&lt;Bridged&gt;(){}); + } +}</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&lt;MyObject&gt; 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