站内搜索: 请输入搜索关键词
当前页面: 在线文档首页 > JBoss Seam 1.1.5 正式版英文参考手册

Chapter 17. Asynchronicity and messaging - JBoss Seam 1.1.5 正式版英文参考手册

Chapter 17. Asynchronicity and messaging

Seam makes it very easy to perform work asynchronously from a web request. When most people think of asynchronicity in Java EE, they think of using JMS. This is certainly one way to approach the problem in Seam, and is the right way when you have strict and well-defined quality of service requirements. Seam makes it easy to send and recieve JMS messages using Seam components.

But for many usecases, JMS is overkill. Seam layers a simple asynchronous method and event facility over the EJB 3.0 timer service.

17.1. Asynchronicity

Asynchronous events and method calls have the same quality of service expectations as the container's EJB timer service. If you're not familiar with the Timer service, don't worry, you don't need to interact with it directly if you want to use asynchronous methods in Seam.

To use asynchronous methods and events, you need to add the following line to components.xml:

<core:dispatcher/>

Note that this functionality is not available in environments which do not support EJB 3.0.

17.1.1. Asynchronous methods

In simplest form, an asynchronous call just lets a method call be processed asynchronously (in a different thread) from the caller. We usually use an asynchronous call when we want to return an immediate response to the client, and let some expensive work be processed in the background. This pattern works very well in applications which use AJAX, where the client can automatically poll the server for the result of the work.

For EJB components, we annotate the local interface to specify that a method is processed asynchronously.

@Local
public interface PaymentHandler
{
    @Asynchronous
    public void processPayment(Payment payment);
}

(For JavaBean components we can annotate the component implementation class if we like.)

The use of asynchronicity is transparent to the bean class:

@Stateless
@Name("paymentHandler")
public class PaymentHandlerBean implements PaymentHandler
{
    public void processPayment(Payment payment)
    {
        //do some work!
    }
}

And also transparent to the client:

@Stateful
@Name("paymentAction")
public class CreatePaymentAction
{
    @In(create=true) PaymentHandler paymentHandler;
    @In Bill bill;
    
    public String pay()
    {
        paymentHandler.processPayment( new Payment(bill) );
        return "success";
    }
}

The asynchronous method is processed in a completely new event context and does not have access to the session or conversation context state of the caller. However, the business process context is propagated.

Asynchronous method calls may be scheduled for later execution using the @Duration, @Expiration and @IntervalDuration annotations.

@Local
public interface PaymentHandler
{
    @Asynchronous
    public void processScheduledPayment(Payment payment, @Expiration Date date);

    @Asynchronous
    public void processRecurringPayment(Payment payment, @Expiration Date date, @IntervalDuration Date interval)'
}
@Stateful
@Name("paymentAction")
public class CreatePaymentAction
{
    @In(create=true) PaymentHandler paymentHandler;
    @In Bill bill;
    
    public String schedulePayment()
    {
        paymentHandler.processScheduledPayment( new Payment(bill), bill.getDueDate() );
        return "success";
    }

    public String scheduleRecurringPayment()
    {
        paymentHandler.processRecurringPayment( new Payment(bill), bill.getDueDate(), ONE_MONTH );
        return "success";
    }
}

Both client and server may access the Timer object associated with the invocation.

@Local
public interface PaymentHandler
{
    @Asynchronous
    public Timer processScheduledPayment(Payment payment, @Expiration Date date);
}
@Stateless
@Name("paymentHandler")
public class PaymentHandlerBean implements PaymentHandler
{
    @In Timer timer;
    
    public Timer processScheduledPayment(Payment payment, @Expiration Date date)
    {
        //do some work!
        
        return timer; //note that return value is completely ignored
    }

}
@Stateful
@Name("paymentAction")
public class CreatePaymentAction
{
    @In(create=true) PaymentHandler paymentHandler;
    @In Bill bill;
    
    public String schedulePayment()
    {
        Timer timer = paymentHandler.processScheduledPayment( new Payment(bill), bill.getDueDate() );
        return "success";
    }
}

Asynchronous methods cannot return any other value to the caller.

17.1.2. Asynchronous events

Component-driven events may also be asynchronous. To raise an event for asynchronous processing, simply call the raiseAsynchronousEvent() methods of the Events class. To schedule a timed event, call one of the raiseTimedEvent() methods. Components may observe asynchronous events in the usual way, but remember that only the business process context is propagated to the asynchronous thread.

17.2. Messaging in Seam

Seam makes it easy to send and receive JMS messages to and from Seam components.

17.2.1. Configuration

To configure Seam's infrastructure for sending JMS messages, you need to tell Seam about any topics and queues you want to send messages to, and also tell Seam where to find the QueueConnectionFactory and/or TopicConnectionFactory.

Seam defaults to using UIL2ConnectionFactory which is the usual connection factory for use with JBossMQ. If you are using some other JMS provider, you need to set one or both of queueConnection.queueConnectionFactoryJndiName and topicConnection.topicConnectionFactoryJndiName in seam.properties, web.xml or components.xml.

You also need to list topics and queues in components.xml to install Seam managed TopicPublishers and QueueSenders:

<jms:managed-topic-publisher name="stockTickerPublisher" auto-create="true" topic-jndi-name="topic/stockTickerTopic"/>

<jms:managed-queue-sender name="paymentQueueSender" auto-create="true" queue-jndi-name="queue/paymentQueue"/>

17.2.2. Sending messages

Now, you can inject a JMS TopicPublisher and TopicSession into any component:

@In 
private TopicPublisher stockTickerPublisher;   
@In 
private TopicSession topicSession;

public void publish(StockPrice price) {
      try
      {
         topicPublisher.publish( topicSession.createObjectMessage(price) );
      } 
      catch (Exception ex)
      {
         throw new RuntimeException(ex);
      } 
}

Or, for working with a queue:

@In
private QueueSender paymentQueueSender;   
@In
private QueueSession queueSession;

public void publish(Payment payment) {
      try
      {
         paymentQueueSender.publish( queueSession.createObjectMessage(payment) );
      } 
      catch (Exception ex)
      {
         throw new RuntimeException(ex);
      } 
}

17.2.3. Receiving messages using a message-driven bean

You can process messages using any EJB3 message driven bean. Message-driven beans may even be Seam components, in which case it is possible to inject other event and application scoped Seam components.

17.2.4. Receiving messages in the client

Seam Remoting lets you subscribe to a JMS topic from client-side JavaScript. This is described in the next chapter.