/ 
Catalyst-Engine-Stomp-0.15
River stage zero No dependents
/ Catalyst::Engine::Stomp

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' = {
     tries_per_server => 3,
    'servers' => [
     {
       'hostname' => 'localhost',
       'port' => '61613'
     },
     {
       'hostname' => 'stomp.yourmachine.com',
       '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.

FAILOVER

You can specify one or more servers in a list for the apps config. This enables fail over if an error occurs, like the broker or network connection disappears.

It will try to use a server a set number of times, as determined by tries_per_server in the config before failing on to the next server in the list. It cycle through each server in turn, going back to the start of the list if need be.

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.

Simplified configuration

Instead of using the complete config layout as shown in the synopsis, you can

  • not specify a tries_per_server (defaults to 1)

  • specify a single server:

    server => { hostname => $host, port => $port }

  • use the old-style (pre 0.14) config having hostname and port directly in the Engine::Stomp block, without a server key in between.

METHODS

_see_ya

Set to run when signal USR1 is received. Simply sets the stop flag.

run

App entry point. Starts a loop listening for messages.

If the stop flag is set (see _see_ya above) then no more requests are processed. Keep in mind this is a blocking server and it will wait for a STOMP message forever. Only after handling a request does it check the flag.

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/pmooney/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.