<document>
<header>
  <product>resin</product>
  <title>JMS services</title>
  <type>tutorial</type>
  <tutorial-startpage>services.php</tutorial-startpage>
</header>

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

<s1 title="Files in this tutorial">
<deftable>
<tr>
  <th>File</th>
  <th>Description</th>
</tr>
<tr><td><viewfile-link file="WEB-INF/resin-web.xml"/></td>
    <td>resin-web.xml configuration</td>
</tr>
<tr><td><viewfile-link file="services.php"/></td>
    <td>PHP script acting as the web client</td>
</tr>
<tr><td><viewfile-link file="WEB-INF/classes/example/LogService.java"/></td>
    <td>Log service implementation</td>
</tr>
</deftable>
</s1>

<s1 title="Using JMS for WebServices">

<p>
Using JMS for WebServices is as easy as sending the body of a SOAP message
as a JMS message. (TODO: Actually remove SOAP envelope.)  Below is a PHP
script using the Quercus JMS module that acts as the service client.
</p>

<example language="php">
&lt;?php

$service_queue = new JMSQueue("jms/ServiceQueue");

if (! $service_queue) {
  exit("Unable to get service queue!");
} 

$log_service = jndi_lookup("example/LogService");

echo "&lt;a href=\"\">Refresh&lt;/a>&lt;br/>\n";
echo "Logged messages:&lt;br/>\n";
echo "&lt;pre>\n";
echo $log_service->getLog();
echo "&lt;/pre>\n";

$request = 
  "&lt;env:Envelope xmlns:env=\"http://www.w3.org/2003/05/soap-enveloper\">" .
  "&lt;env:Body>" .
  "&lt;m:log xmlns:m=\"urn:log\">" .
  "  &lt;s>Hello, World&lt;/s>" .
  "&lt;/m:log>" .
  "&lt;/env:Body>" .
  "&lt;/env:Envelope>";

if (! $service_queue->send($request)) {
  echo "Unable to send request\n";
}

?>
</example>

</s1>

<s1 title="Configuring JMS for WebServices">

<p>
In the configuration below, we create a JMS queue for service requests.
The service provider is a JMS MessageListener (implemented by 
<code>com.caucho.jms.services.ServicesListener</code>) which services
all requests sent as JMS <code>TextMessage</code>s on the 
<var>serviceQueue</var>.  In this example, the actual service implementation
is a logging service, shown below.
</p>

<example language="xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">
  &lt;servlet servlet-name="resin-php"
           servlet-class="com.caucho.quercus.servlet.QuercusServlet" />

  &lt;servlet-mapping url-pattern="*.php" servlet-name="resin-php" />

  &lt;system-property javax.xml.stream.XMLInputFactory="com.caucho.xml.stream.XMLInputFactoryImpl"/>

  &lt;resource var="logService"
            jndi-name="example/LogService"
            type="example.LogService" />

  &lt;resource var="serviceQueue" 
            jndi-name="jms/ServiceQueue"
            type="com.caucho.jms.memory.MemoryQueue"/>
  
  &lt;resource var="jmsFactory" type="com.caucho.jms.ConnectionFactoryImpl"
            jndi-name="jms/ConnectionFactory"/>

  &lt;resource type="com.caucho.jms.services.ServicesListener">
    &lt;init>
      &lt;connection-factory>${jmsFactory}&lt;/connection-factory>
      &lt;destination>${serviceQueue}&lt;/destination>
      &lt;service>${logService}&lt;/service>
    &lt;/init>
  &lt;/resource>
&lt;/web-app>
</example>

</s1>

<s1 title="The LogService">

<p>
The actual service provided here is a logging service.  Note
the @WebService and @WebMethod annotations.
</p>

<example language="java">
package example;

import javax.jws.WebMethod;
import javax.jws.WebService;

@WebService
public class LogService {
  private int _sequenceNumber = 1;
  private StringBuilder _log = new StringBuilder();

  @WebMethod
  public int log(String message)
  {
    _log.append(_sequenceNumber + ": " + message + "\n");
    return _sequenceNumber++;
  }

  @WebMethod(exclude=true)
  public String getLog()
  {
    return _log.toString();
  }
}
</example>

</s1>

</body>
</document>
