NAME

Catalyst::Engine::Stomp - write message handling apps with Catalyst.

SYNOPSIS

  # In a server script:

  BEGIN {
    $ENV{CATALYST_ENGINE} = 'Stomp';
    require Catalyst::Engine::Stomp;
  }

  MyApp->config(
     'Engine::Stomp' = {
       hostname         => '127.0.0.1',
       port             => 61613,
       utf8             => 1,
       subscribe_header => {
         transformation       => 'jms-to-json',
       }
    },
  );
  MyApp->run();

  # In a controller, or controller base class:
  use base qw/ Catalyst::Controller::MessageDriven /;

  # then create actions, which map as message types
  sub testaction : Local {
      my ($self, $c) = @_;

      # Reply with a minimal response message
      my $response = { type => 'testaction_response' };
      $c->stash->{response} = $response;
  }

DESCRIPTION

Write a Catalyst app connected to a Stomp messagebroker, not HTTP. You need a controller that understands messaging, as well as this engine.

This is single-threaded and single process - you need to run multiple instances of this engine to get concurrency, and configure your broker to load-balance across multiple consumers of the same queue.

Controllers are mapped to Stomp queues, and a controller base class is provided, Catalyst::Controller::MessageDriven, which implements YAML-serialized messages, mapping a top-level YAML "type" key to the action.

UTF-8

By default STOMP messages are assumed to be in UTF-8. This module can automatically convert a Perl string into a UTF-8 set of octets to be sent over the wire instead. This is a Good Thing, especially if you use the function Load() from the package YAML::XS to un-serialize it in your client - it assumes it is in UTF-8.

If you do want this behaviour, set 'utf8' to '1' in your config.

METHODS

run

App entry point. Starts a loop listening for messages.

prepare_request

Overridden to add the source broker to the request, in place of the client IP address.

finalize_headers

Overridden to dump out any errors encountered, since you won't get a "debugging" message as for HTTP.

handle_stomp_frame

Dispatch according to Stomp frame type.

handle_stomp_message

Dispatch a Stomp message into the Catalyst app.

handle_stomp_error

Log any Stomp error frames we receive.

CONFIGURATION

subscribe_header

Add additional header key/value pairs to the subscribe message sent to the message broker.

DEVELOPMENT

The source to Catalyst::Engine::Stomp is in github:

  http://github.com/chrisa/catalyst-engine-stomp

AUTHOR

Chris Andrews <chris@nodnol.org>

CONTRIBUTORS

Tomas Doran (t0m) <bobtfish@bobtfish.net>

Jason Tang

Paul Mooney

LICENCE AND COPYRIGHT

Copyright (C) 2009 Venda Ltd

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm Catalyst::Engine::Stomp

perl -MCPAN -e shell
install Catalyst::Engine::Stomp