Skip to content
Browse files

more docs

  • Loading branch information...
1 parent 2c1af78 commit b1561f1044e7a8e1f806e6605fd6841635001bc7 @dakkar committed Mar 7, 2012
Showing with 111 additions and 13 deletions.
  1. +32 −13 lib/Plack/Handler/Stomp.pm
  2. +79 −0 lib/Plack/Handler/Stomp/NoNetwork.pm
View
45 lib/Plack/Handler/Stomp.pm
@@ -48,7 +48,8 @@ usable by any PSGI application.
=head2 Roles Consumed
We consume L<Net::Stomp::MooseHelpers::CanConnect> and
-L<Net::Stomp::MooseHelpers::CanSubscribe>.
+L<Net::Stomp::MooseHelpers::CanSubscribe>. Read those modules'
+documentation to see how to configure servers and subscriptions.
=attr C<logger>
@@ -103,21 +104,29 @@ Given a PSGI application, loops forever:
=item *
-connect to a STOMP server (see L</connect> and L</servers>)
+connect to a STOMP server (see
+L<connect|Net::Stomp::MooseHelpers::CanConnect/connect> and
+L<servers|Net::Stomp::MooseHelpers::CanConnect/servers> in
+L<Net::Stomp::MooseHelpers::CanConnect>)
=item *
-subscribe to whatever needed (see L</subscribe> and L</subscriptions>)
+subscribe to whatever needed (see
+L<subscribe|Net::Stomp::MooseHelpers::CanSubscribe/subscribe> and
+L<subscriptions|Net::Stomp::MooseHelpers::CanSubscribe/subscriptions>
+in L<Net::Stomp::MooseHelpers::CanSubscribe>)
=item *
-consume STOMP frames in an inner loop (see L</handle_stomp_frame>)
+consume STOMP frames in an inner loop (see L</frame_loop>)
=back
If the application throws an exception, the loop exits re-throwing the
exception. If the STOMP connection has problems, the outer loop is
-repeated with a different server (see L</next_server>).
+repeated with a different server (see
+L<next_server|Net::Stomp::MooseHelpers::CanConnect/next_server> in
+L<Net::Stomp::MooseHelpers::CanConnect>).
If L</one_shot> is set, this function exits after having consumed
exactly 1 frame.
@@ -159,6 +168,16 @@ sub run {
}
}
+=method C<frame_loop>
+
+Loop forever receiving frames from the STOMP connection. Call
+L</handle_stomp_frame> for each frame.
+
+If L</one_shot> is set, this function exits after having consumed
+exactly 1 frame.
+
+=cut
+
sub frame_loop {
my ($self,$app) = @_;
@@ -320,8 +339,8 @@ sub maybe_send_reply {
=method C<where_should_send_reply>
-Returns the header C<X-Reply-Address> or C<X-STOMP-Reply-Address>
-header from the response.
+Returns the header C<X-Reply-Address> or C<X-STOMP-Reply-Address> from
+the response.
=cut
@@ -336,11 +355,11 @@ sub where_should_send_reply {
=method C<send_reply>
-Converts the PSGI response into a STOMP frame, by removing every
-header not starting with C<x-stomp->, removing that prefix from the
-other headers, and stringifying the body.
+Converts the PSGI response into a STOMP frame, by removing the prefix
+C<x-stomp-> from the key of header fields that have it, removing
+entirely header fields that don't, and stringifying the body.
-Then sends the frame so built as the reply.
+Then sends the frame.
=cut
@@ -434,8 +453,8 @@ and writing to C<psgi.errors> will log via the L</logger> at level
C<error>.
Finally, every header in the STOMP message will be available in the
-"namespace" C<stomp.>, so for example the message type is in
-C<stomp.type>.
+"namespace" C<jms.>, so for example the message type is in
+C<jms.type>.
The C<$path_info> is obtained from the L</destination_path_map>
(i.e. from the C<path_info> subscription options) passed through
View
79 lib/Plack/Handler/Stomp/NoNetwork.pm
@@ -6,8 +6,65 @@ use File::ChangeNotify;
use Net::Stomp::MooseHelpers::ReadTrace;
extends 'Plack::Handler::Stomp';
+# ABSTRACT: like L<Plack::Handler::Stomp>, but without a network
+
+=head1 SYNOPSIS
+
+ my $runner = Plack::Handler::Stomp::NoNetwork->new({
+ trace_basedir => '/tmp/mq',
+ subscriptions => [
+ { destination => '/queue/plack-handler-stomp-test' },
+ { destination => '/topic/plack-handler-stomp-test',
+ headers => {
+ selector => q{custom_header = '1' or JMSType = 'test_foo'},
+ },
+ path_info => '/topic/ch1', },
+ { destination => '/topic/plack-handler-stomp-test',
+ headers => {
+ selector => q{custom_header = '2' or JMSType = 'test_bar'},
+ },
+ path_info => '/topic/ch2', },
+ ],
+ });
+ $runner->run(MyApp->get_app());
+
+=head1 DESCRIPTION
+
+Just like L<Plack::Handler::Stomp>, but instead of using a network
+connection, we get our frames from a directory.
+
+This class uses L<File::ChangeNotify> to monitor the
+L<trace_basedir|Net::Stomp::MooseHelpers::TraceOnly/trace_basedir>,
+and L<Net::Stomp::MooseHelpers::ReadTrace> to read the frames.
+
+It also consumes L<Net::Stomp::MooseHelpers::TraceOnly> to make sure
+that every reply we try to send is actually written to disk instead of
+a broker.
+
+=head2 WARNING!
+
+This class does not implement subscription selectors. If you have
+multiple subscriptions for the same destination, a random one will be
+used.
+
+=cut
+
with 'Net::Stomp::MooseHelpers::TraceOnly';
+sub _default_servers {
+ [ {
+ hostname => 'not.using.the.network',
+ port => 9999,
+ } ]
+}
+
+=attr C<file_watcher>
+
+Instance of L<File::ChangeNotify::Watcher>, set up to monitor
+C<trace_basedir> for sent messages.
+
+=cut
+
has file_watcher => (
is => 'ro',
isa => 'File::ChangeNotify::Watcher',
@@ -22,6 +79,13 @@ sub _build_file_watcher {
);
}
+=attr C<frame_reader>
+
+Instance of L<Net::Stomp::MooseHelpers::ReadTrace> used to parse
+frames from disk.
+
+=cut
+
has frame_reader => (
is => 'ro',
lazy_build => 1,
@@ -34,6 +98,19 @@ sub _build_frame_reader {
});
}
+=method C<frame_loop>
+
+This method ovverrides the corresponding one from
+L<Plack::Handler::Stomp>.
+
+Loop forever, collecting C<create> events from the
+L</file_watcher>. Each new file is parsed by the L</frame_reader>,
+then passed to
+L<handle_stomp_frame|Plack::Handler::Stomp/handle_stomp_frame> as
+usual.
+
+=cut
+
sub frame_loop {
my ($self,$app) = @_;
@@ -45,6 +122,8 @@ sub frame_loop {
my $frame = $self->frame_reader
->read_frame_from_filename($event->path);
+ # messages sent will be of type "SEND", but they would
+ # come back ask "MESSAGE" if they passed through a broker
$frame->command('MESSAGE') if $frame->command eq 'SEND';
$self->handle_stomp_frame($app, $frame);

0 comments on commit b1561f1

Please sign in to comment.
Something went wrong with that request. Please try again.