<document>
<header>
  <product>resin</product>
  <title>JMS Messaging in Quercus - Receiving messages</title>
  <type>tutorial</type>
  <tutorial-startpage>display-ad.php</tutorial-startpage>
</header>

<body>
<summary localtoc="3" />

<section title="Files in this tutorial">
<deftable>
<tr><td><viewfile-link file="WEB-INF/resin-web.xml"/></td>
    <td>resin-web.xml configuration</td>
</tr>
<tr><td><viewfile-link file="display-ad.php"/></td>
    <td>PHP script displaying the advertisement.</td>
</tr>
<tr><td><viewfile-link file="WEB-INF/classes/example/AdProducer.java"/></td>
    <td>Java listener that fills the advertisement queue.</td>
</tr>
<tr><td><viewfile-link file="WEB-INF/adproducer.ejb"/></td>
    <td>EJB Message bean configuration.</td>
</tr>
</deftable>
</section>

<section title="Using JMS in Quercus">

<p>
Quercus offers a simplified messaging interface built upon JMS.  This 
functionality makes it possible to send and receive messages using either
the Resin JMS implementation or any other messaging service with a JMS
implementation.  Many features of JMS are designed for message-driven
services which make sense in the Java world, but are not appropriate for
PHP.  This tutorial focuses receiving messages in a non-blocking way.
</p>

</section>

<section title="Receiving JMS messages from a PHP script">
<p>
This example uses two queues: an "ad queue" and a "control queue".
The PHP script removes advertisements from the ad queue using the
<code>receive()</code> method.  This method is <em>non-blocking</em> -
if there are no advertisements, the method will return <code>FALSE</code>
instead of waiting for a new advertisement.  Whenever the PHP script
removes an advertisement from the ad queue, it signals a Java message
driven bean (MDB) to add another ad by sending an empty message to the
control queue.
</p>

<example language="php">
$ad_queue = new JMSQueue("jms/AdQueue");
$control_queue = new JMSQueue("jms/ControlQueue");

if (! $ad_queue) {
  echo "Unable to get ad queue!\n";
} elseif (! $control_queue) {
  echo "Unable to get control queue!\n";
} else {
  $ad = $ad_queue->receive();

  if ($ad == null) {
    echo "No ads available on the queue\n";
  } else {
    echo "$ad";
  }

  if (! $control_queue->send(0)) {
    echo "Unable to send control message\n";
  }
}
</example>

<p>
The programming model of the Quercus JMS interface is first to create
a connection to a queue by instantiating a <code>JMSQueue</code> object.
To create a <code>JMSQueue</code> object, pass in the JNDI name of the
JMS queue to be used.  <code>JMSQueue</code> objects have two methods:
<code>send()</code> and <code>receive()</code>.  The example above shows
how to use both methods.
</p>

<p>
</p>
</section>

<section title="Configuring JMS for PHP and Java">

<p>
JMS requires that two resources be set up: A
<code>ConnectionFactory</code> and a <code>Queue</code>.  Both are
configured in <viewfile-link file="WEB-INF/resin-web.xml"/>.
The <code>ConnectionFactory</code> is used to connect to all the
<code>Queue</code>s and only one of them needs to be set up.  The default
JNDI name is <code>jms/ConnectionFactory</code> - Quercus automatically
uses this connection factory.  Another connection factory may be used by
setting the PHP ini variable <code>jms.connection_factory</code>.
</p>

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

<p>
This example uses two queues, <code>jms/AdQueue</code> and 
<code>jms/ControlQueue</code>.
</p>

<example>
  &lt;resource jndi-name="jms/AdQueue"
    type='com.caucho.jms.memory.MemoryQueue' />

  &lt;resource jndi-name="jms/ControlQueue"
    type='com.caucho.jms.memory.MemoryQueue' />
</example>

<p>
The complete configuration is in <viewfile-link file="WEB-INF/resin-web.xml"/>.
</p>

</section>

</body>
</document>
