<document>
  <header>
    <product>resin</product>
    <title>Resin JMS Configuration</title>
    <description>
      <p>Configuration for Resin's JMS provider implementation.  The JDBC Queues and Topics provide a persistent messaging store.  The Memory Queues and Topics provide a low-overhead memory-based store.</p>
    </description>
  </header>

  <body>
    <localtoc/>

<s1 title="ConnectionFactory">

<p>The <code>ConnectionFactory</code> resource defines the JMS factory
for creating JMS connections.</p>

<example title="ConnectionFactory resource">
&lt;resource jndi-name="jms/factory"
          type="com.caucho.jms.ConnectionFactoryImpl"/&gt;
</example>

<p>
If an application creates a named queue or topic using the the JMS Session,
Resin's default behaviour is to create a memory queue or topic.  The 
<a href="#jdbc-manager">jdbc-manager</a> configuration of the connection factory 
causes creation of a jdbc queue or topic instead.
</p>

<example title="ConnectionFactory resource">
&lt;resource jndi-name="jms/factory"
           type="com.caucho.jms.ConnectionFactoryImpl"/&gt;
  &lt;init&gt;
    &lt;jdbc-manager&gt;
      &lt;data-source&gt;jdbc/database&lt;/data-source&gt;
    &lt;/jdbc-manager&gt;
  &lt;/init&gt;
&lt;/resource&gt;
</example>

<deftable-childtags>
<tr><td>client-id</td>
    <td>clientID value for durable subscriptions</td>
    <td>pseudo-random generated value</td>
    </tr>
<tr><td>jdbc-manager</td>
    <td>Use jdbc queues and topics for queues and topics created using the JMS Session object,
        see <a href="#jdbc-manager">jdbc-manager</a></td>
    <td>use a memory queue for created queues and topics</td>
    </tr>
</deftable-childtags>

</s1>

<s1 title="JDBC Queue/Topic">

<p>
The JDBC Queue and Topic store the messages using a JDBC DataSource.  The data
source is defined in a &lt;database&gt; element.  Resin's internal file-based
database can be used for single-JVM messaging.  A central database is used for
clusters and situations where more than one is a producer or consumer.
</p>

<s2 title="JdbcQueue configuration">

<example title="Queue configuration with Resin's database">
&lt;database jndi-name="jdbc/resin"&gt;
  &lt;driver type="com.caucho.db.jdbc.ConnectionPoolDataSourceImpl"&gt;
     &lt;path&gt;WEB-INF/db&lt;/path&gt;
  &lt;/driver&gt;
&lt;/database&gt;

&lt;resource jndi-name="jms/my-queue"
          type="com.caucho.jms.jdbc.JdbcQueue"&gt;
  &lt;init&gt;
    &lt;queue-name&gt;my-queue&lt;/queue-name&gt;
    &lt;jdbc-manager&gt;
      &lt;data-source&gt;jdbc/resin&lt;/data-source&gt;
    &lt;/jdbc-manager&gt;
  &lt;/init&gt;
&lt;/resource&gt;
</example>

<deftable-childtags>
<tr><td>queue-name</td>
    <td>Name of the queue</td>
    <td>required</td>
    </tr>
<tr><td>jdbc-manager</td>
    <td>Configuration of database usage, see <a href="#jdbc-manager">jdbc-manager</a></td>
    <td>required</td>
    </tr>
</deftable-childtags>
</s2>

<s2 title="JdbcTopic configuration">
<example title="Topic configuration with MySQL database">
&lt;database&gt;
  &lt;jndi-name&gt;jdbc/jms&lt;/jndi-name&gt;
  &lt;driver&gt;
    &lt;type&gt;com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource&lt;/type&gt;
    &lt;url&gt;jdbc:mysql://localhost:3306/<var>jms</var>&lt;/url&gt;
    &lt;user&gt;<var>username</var>&lt;/user&gt;
    &lt;password&gt;<var>password</var>&lt;/password&gt;
  &lt;/driver&gt;
  ...
&lt;/database&gt;

&lt;resource jndi-name="jms/my-topic"
          type="com.caucho.jms.jdbc.JdbcTopic"&gt;
  &lt;init&gt;
    &lt;topic-name&gt;my-topic&lt;/topic-name&gt;
    &lt;jdbc-manager&gt;
      &lt;data-source&gt;jdbc/jms&lt;/data-source&gt;
    &lt;/jdbc-manager&gt;
  &lt;/init&gt;
&lt;/resource&gt;
</example>

<deftable-childtags>
<tr><td>topic-name</td>
    <td>Name of the topic</td>
    <td>required</td>
    </tr>
<tr><td>jdbc-manager</td>
    <td>Configuration of database usage, see <a href="#jdbc-manager">jdbc-manager</a></td>
    <td>required</td>
    </tr>
</deftable-childtags>
</s2>

<s2 title="jdbc-manager">

<deftable-childtags>
<tr><td>consumer-table</td>
    <td>Name of the table to use for storing consumers</td>
    <td>resin_jms_consumer</td>
    </tr>
<tr><td>data-source</td>
    <td>JDBC DataSource</td>
    <td>required</td>
    </tr>
<tr><td>destination-table</td>
    <td>Name of the table to use for storing destinations</td>
    <td>resin_jms_destination</td>
    </tr>
<tr><td>message-table</td>
    <td>Name of the table to use for storing messages</td>
    <td>resin_jms_message</td>
    </tr>
<tr><td>purge-interval</td>
    <td>Frequency for purging of expired messages</td>
    <td>60s</td>
    </tr>
<tr><td>poll-interval</td>
    <td>Polling interval when there is a message listener</td>
    <td>no polling</td>
    </tr>
<tr><td>tablespace</td>
    <td>Tablespace for Oracle blobs only</td>
    <td>none</td>
    </tr>
</deftable-childtags>

</s2>

</s1>

<s1 title="Memory Queue/Topic">

<p>The Memory Queue and Topic are non-persistent.  If the server restarts
or even if the Queue's environment restarts, the messaging data will be
lost.  Applications needing persistent messaging should use the JDBC
Queues.</p>

<example title="Memory Queue configuration">
&lt;resource jndi-name="jms/factory"
           type="com.caucho.jms.ConnectionFactoryImpl"/&gt;

&lt;resource jndi-name="jms/my-queue"
           type="com.caucho.jms.memory.MemoryQueue"&gt;
  &lt;init&gt;
    &lt;queue-name&gt;my-queue&lt;/queue-name&gt;
  &lt;/init&gt;
&lt;/resource&gt;
</example>

<example title="Memory Topic configuration">
&lt;resource jndi-name="jms/factory"
           type="com.caucho.jms.ConnectionFactoryImpl"/&gt;

&lt;resource jndi-name="jms/my-topic"
           type="com.caucho.jms.memory.MemoryTopic"&gt;
  &lt;init&gt;
    &lt;topic-name&gt;my-topic&lt;/topic-name&gt;
  &lt;/init&gt;
&lt;/resource&gt;
</example>

</s1>
</body>
</document>
