Caucho Technology

bam queue

Using BAM to implement a queuing service.


Files in this tutorial

WEB-INF/resin-web.xmlConfigures the BamService.
WEB-INF/classes/example/ExampleService.javaThe Java message listener.
WEB-INF/php/bam_queue.phpThe PHP message listener.
WEB-INF/classes/example/ExampleMessage.javaThe custom message model.
demo.jspThe JSP demo
demo.phpThe PHP demo


Messaging lets a servlet delegate processing to a batch process either on the same machine or on a separate machine. The servlet creates a message and sends it to a queue. The servlet immediately completes and when the batch process is ready, it processes the message.

Messaging is therefore comprised of three main components:

  • A Producer creates messages and sends them to a Consumer, continuing processing. The Producer could be a Servlet or PHP page that sends a request to a backend consumer and continues the web response without waiting for the task to complete.
  • A Consumer processes messages as they become available. In BAM, the Consumer extends SimpleBamService to receive the messages.
  • The Queue buffers messages from the Produces and provides them to a Consumer when the Consumer is ready. The Queue is part of the BAM messaging system.


In this example, the Producer is a Servlet which sends a simple message. The Producer creates aLocalActorClientto send the message.

Example: MessageServlet using LocalActorClient
import com.caucho.bam.LocalActorClient;

public void send()
  LocalActorClient client = new LocalActorClient();

  ExampleMessage message = new ExampleMessage("sample message");

  client.message("consumer@", message);

Example: PHP using bam_send_message

$msg = java("example.ExampleMessage", "sample message");

bam_send_message("consumer@", $msg);



The Queue delivers message to the Consumer one by one. When the Consumer finishes processing a message the Queue will deliver the next available message. The Consumer implementscom.caucho.bam.BamService.

In this example, the Consumer just logs the message.

Example: ExampleService
package example;

import com.caucho.bam.SimpleActor;
import com.caucho.bam.Message;

public class ExampleService extends SimpleActor;
  public void onMessage(String to, String from, ExampleMessage message)
    System.out.println("Message: " + message + " from=" + from);

The PHP version of the service implements abam_messagemethod to handle the message and callsbam_dispatch()to dispatch the message. The PHP service will call the bam_queue.php when it receives a message.

Example: bam_queue.php

function bam_message($to, $from, $value)




Example: resin-web.xml
<web-app xmlns="">

     <resin:BamService name="java-consumer"/>

  <bam-service name="php-consumer"
    <init script="WEB-INF/php/bam_queue.php"/>



Copyright © 1998-2011 Caucho Technology, Inc. All rights reserved.
Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.