Net::Stomp(3) User Contributed Perl Documentation Net::Stomp(3)NAMENet::Stomp - A Streaming Text Orientated Messaging Protocol Client
SYNOPSIS
# send a message to the queue 'foo'
use Net::Stomp;
my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );
$stomp->connect( { login => 'hello', passcode => 'there' } );
$stomp->send(
{ destination => '/queue/foo', body => 'test message' } );
$stomp->disconnect;
# subscribe to messages from the queue 'foo'
use Net::Stomp;
my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );
$stomp->connect( { login => 'hello', passcode => 'there' } );
$stomp->subscribe(
{ destination => '/queue/foo',
'ack' => 'client',
'activemq.prefetchSize' => 1
}
);
while (1) {
my $frame = $stomp->receive_frame;
warn $frame->body; # do something here
$stomp->ack( { frame => $frame } );
}
$stomp->disconnect;
# write your own frame
my $frame = Net::Stomp::Frame->new(
{ command => $command, headers => $conf, body => $body } );
$self->send_frame($frame);
# connect with failover supporting similar URI to ActiveMQ
$stomp = Net::Stomp->new({ failover => "failover://tcp://primary:61616" })
# "?randomize=..." and other parameters are ignored currently
$stomp = Net::Stomp->new({ failover => "failover:(tcp://primary:61616,tcp://secondary:61616)?randomize=false" })
# Or in a more natural perl way
$stomp = Net::Stomp->new({ hosts => [
{ hostname => 'primary', port => 61616 },
{ hostname => 'secondary', port => 61616 },
] });
DESCRIPTION
This module allows you to write a Stomp client. Stomp is the Streaming
Text Orientated Messaging Protocol (or the Protocol Briefly Known as
TTMP and Represented by the symbol :ttmp). It's a simple and easy to
implement protocol for working with Message Orientated Middleware from
any language. Net::Stomp is useful for talking to Apache ActiveMQ, an
open source (Apache 2.0 licensed) Java Message Service 1.1 (JMS)
message broker packed with many enterprise features.
A Stomp frame consists of a command, a series of headers and a body -
see Net::Stomp::Frame for more details.
For details on the protocol see <http://stomp.codehaus.org/Protocol>.
To enable the ActiveMQ Broker for Stomp add the following to the
activemq.xml configuration inside the <transportConnectors> section:
<transportConnector name="stomp" uri="stomp://localhost:61613"/>
To enable the ActiveMQ Broker for Stomp and SSL add the following
inside the <transportConnectors> section:
<transportConnector name="stomp+ssl" uri="stomp+ssl://localhost:61612"/>
For details on Stomp in ActiveMQ See
<http://activemq.apache.org/stomp.html>.
METHODS
new
The constructor creates a new object. You must pass in a hostname and a
port or set a failover configuration:
my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );
If you want to use SSL, make sure you have IO::Socket::SSL and pass in
the SSL flag:
my $stomp = Net::Stomp->new( {
hostname => 'localhost',
port => '61612',
ssl => 1,
} );
If you want to pass in IO::Socket::SSL options:
my $stomp = Net::Stomp->new( {
hostname => 'localhost',
port => '61612',
ssl => 1,
ssl_options => { SSL_cipher_list => 'ALL:!EXPORT' },
} );
Failover
There is experiemental failover support in Net::Stomp. You can specify
failover in a similar maner to ActiveMQ
(http://activemq.apache.org/failover-transport-reference.html
<http://activemq.apache.org/failover-transport-reference.html>) for
similarity with Java configs or using a more natural method to perl of
passing in an array-of-hashrefs in the "hosts" parameter.
Currently when ever Net::Stomp connects or reconnects it will simply
try the next host in the list.
connect
This connects to the Stomp server. You may pass in a "login" and
"passcode" options.
You may also pass in 'client-id', which specifies the JMS Client ID
which is used in combination to the activemqq.subscriptionName to
denote a durable subscriber.
$stomp->connect( { login => 'hello', passcode => 'there' } );
send
This sends a message to a queue or topic. You must pass in a
destination and a body.
$stomp->send(
{ destination => '/queue/foo', body => 'test message' } );
To send a BytesMessage, you should set the field 'bytes_message' to 1.
send_transactional
This sends a message in transactional mode and fails if the receipt of
the message is not acknowledged by the server:
$stomp->send_transactional(
{ destination => '/queue/foo', body => 'test message' }
) or die "Couldn't send the message!";
If using ActiveMQ, you might also want to make the message persistent:
$stomp->send_transactional(
{ destination => '/queue/foo', body => 'test message', persistent => 'true' }
) or die "Couldn't send the message!";
disconnect
This disconnects from the Stomp server:
$stomp->disconnect;
subscribe
This subscribes you to a queue or topic. You must pass in a
destination.
The acknowledge mode defaults to 'auto', which means that frames will
be considered delivered after they have been sent to a client. The
other option is 'client', which means that messages will only be
considered delivered after the client specifically acknowledges them
with an ACK frame.
Other options:
'selector': which specifies a JMS Selector using SQL 92 syntax as
specified in the JMS 1.1 specificiation. This allows a filter to be
applied to each message as part of the subscription.
'activemq.dispatchAsync': should messages be dispatched synchronously
or asynchronously from the producer thread for non-durable topics in
the broker. For fast consumers set this to false. For slow consumers
set it to true so that dispatching will not block fast consumers.
'activemq.exclusive': Would I like to be an Exclusive Consumer on a
queue.
'activemq.maximumPendingMessageLimit': For Slow Consumer Handlingon
non-durable topics by dropping old messages - we can set a maximum
pending limit which once a slow consumer backs up to this high water
mark we begin to discard old messages.
'activemq.noLocal': Specifies whether or not locally sent messages
should be ignored for subscriptions. Set to true to filter out locally
sent messages.
'activemq.prefetchSize': Specifies the maximum number of pending
messages that will be dispatched to the client. Once this maximum is
reached no more messages are dispatched until the client acknowledges a
message. Set to 1 for very fair distribution of messages across
consumers where processing messages can be slow.
'activemq.priority': Sets the priority of the consumer so that
dispatching can be weighted in priority order.
'activemq.retroactive': For non-durable topics do you wish this
subscription to the retroactive.
'activemq.subscriptionName': For durable topic subscriptions you must
specify the same clientId on the connection and subscriberName on the
subscribe.
$stomp->subscribe(
{ destination => '/queue/foo',
'ack' => 'client',
'activemq.prefetchSize' => 1
}
);
unsubscribe
This unsubscribes you to a queue or topic. You must pass in a
destination:
$stomp->unsubcribe({ destination => '/queue/foo' });
receive_frame
This blocks and returns you the next Stomp frame.
my $frame = $stomp->receive_frame;
warn $frame->body; # do something here
The header bytes_message is 1 if the message was a BytesMessage.
By default this method will block until a frame can be returned. If you
wish to wait for a specified time pass a "timeout" argument:
# Wait half a second for a frame, else return undef
$stomp->receive_frame({ timeout => 0.5 })
can_read
This returns whether a frame is waiting to be read. Optionally takes a
timeout in seconds:
my $can_read = $stomp->can_read;
my $can_read = $stomp->can_read({ timeout => '0.1' });
ack
This acknowledges that you have received and processed a frame (if you
are using client acknowledgements):
$stomp->ack( { frame => $frame } );
send_frame
If this module does not provide enough help for sending frames, you may
construct your own frame and send it:
# write your own frame
my $frame = Net::Stomp::Frame->new(
{ command => $command, headers => $conf, body => $body } );
$self->send_frame($frame);
SEE ALSO
Net::Stomp::Frame.
AUTHOR
Leon Brocard <acme@astray.com>. Thom May <thom.may@betfair.com>. Ash
Berlin <ash_github@firemirror.com>.
COPYRIGHT
Copyright (C) 2006-9, Leon Brocard Copyright (C) 2009, Thom May,
Betfair.com Copyright (C) 2010, Ash Berlin, Net-a-Porter.com
This module is free software; you can redistribute it or modify it
under the same terms as Perl itself.
perl v5.14.1 2011-06-20 Net::Stomp(3)
