.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::Stomp 3pm"
.TH Net::Stomp 3pm "2016-07-02" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Stomp \- A Streaming Text Orientated Messaging Protocol Client
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\& # send a message to the queue \*(Aqfoo\*(Aq
\& use Net::Stomp;
\& my $stomp = Net::Stomp\->new( { hostname => \*(Aqlocalhost\*(Aq, port => \*(Aq61613\*(Aq } );
\& $stomp\->connect( { login => \*(Aqhello\*(Aq, passcode => \*(Aqthere\*(Aq } );
\& $stomp\->send(
\& { destination => \*(Aq/queue/foo\*(Aq, body => \*(Aqtest message\*(Aq } );
\& $stomp\->disconnect;
\&
\& # subscribe to messages from the queue \*(Aqfoo\*(Aq
\& use Net::Stomp;
\& my $stomp = Net::Stomp\->new( { hostname => \*(Aqlocalhost\*(Aq, port => \*(Aq61613\*(Aq } );
\& $stomp\->connect( { login => \*(Aqhello\*(Aq, passcode => \*(Aqthere\*(Aq } );
\& $stomp\->subscribe(
\& { destination => \*(Aq/queue/foo\*(Aq,
\& \*(Aqack\*(Aq => \*(Aqclient\*(Aq,
\& \*(Aqactivemq.prefetchSize\*(Aq => 1
\& }
\& );
\& while (1) {
\& my $frame = $stomp\->receive_frame;
\& if (!defined $frame) {
\& # maybe log connection problems
\& next; # will reconnect automatically
\& }
\& 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 => \*(Aqprimary\*(Aq, port => 61616 },
\& { hostname => \*(Aqsecondary\*(Aq, port => 61616 },
\& ] });
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module allows you to write a Stomp client. Stomp is the Streaming
Text Orientated Messaging Protocol (or the Protocol Briefly Known as
\&\s-1TTMP\s0 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 (\s-1JMS\s0)
message broker packed with many enterprise features.
.PP
A Stomp frame consists of a command, a series of headers and a body \-
see Net::Stomp::Frame for more details.
.PP
For details on the protocol see .
.PP
In long-lived processes, you can use a new \f(CW\*(C`Net::Stomp\*(C'\fR object to
send each message, but it's more polite to the broker to keep a single
object around and re-use it for multiple messages; this reduce the
number of \s-1TCP\s0 connections that have to be established. \f(CW\*(C`Net::Stomp\*(C'\fR
tries very hard to re-connect whenever something goes wrong.
.SS "ActiveMQ-specific suggestions"
.IX Subsection "ActiveMQ-specific suggestions"
To enable the ActiveMQ Broker for Stomp add the following to the
activemq.xml configuration inside the section:
.PP
.Vb 1
\&
.Ve
.PP
To enable the ActiveMQ Broker for Stomp and \s-1SSL\s0 add the following
inside the section:
.PP
.Vb 1
\&
.Ve
.PP
For details on Stomp in ActiveMQ See .
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .SS """new"""
.el .SS "\f(CWnew\fP"
.IX Subsection "new"
The constructor creates a new object. You must pass in a hostname and
a port or set a failover configuration:
.PP
.Vb 1
\& my $stomp = Net::Stomp\->new( { hostname => \*(Aqlocalhost\*(Aq, port => \*(Aq61613\*(Aq } );
.Ve
.PP
If you want to use \s-1SSL,\s0 make sure you have IO::Socket::SSL and
pass in the \s-1SSL\s0 flag:
.PP
.Vb 5
\& my $stomp = Net::Stomp\->new( {
\& hostname => \*(Aqlocalhost\*(Aq,
\& port => \*(Aq61612\*(Aq,
\& ssl => 1,
\& } );
.Ve
.PP
If you want to pass in IO::Socket::SSL options:
.PP
.Vb 6
\& my $stomp = Net::Stomp\->new( {
\& hostname => \*(Aqlocalhost\*(Aq,
\& port => \*(Aq61612\*(Aq,
\& ssl => 1,
\& ssl_options => { SSL_cipher_list => \*(AqALL:!EXPORT\*(Aq },
\& } );
.Ve
.PP
You can pass a logger object, for example a Log::Log4perl logger:
.PP
.Vb 5
\& my $stomp = Net::Stomp\->new({
\& hostname => \*(Aqlocalhost\*(Aq,
\& port => \*(Aq61613\*(Aq,
\& logger => Log::Log4perl\->get_logger(\*(Aqstomp\*(Aq),
\& });
.Ve
.PP
Warnings and errors will be logged instead of written to \f(CW\*(C`STDERR\*(C'\fR.
.PP
\fIFailover\fR
.IX Subsection "Failover"
.PP
There is some failover support in \f(CW\*(C`Net::Stomp\*(C'\fR. You can specify
"\f(CW\*(C`failover\*(C'\fR" in a similar manner to ActiveMQ
() for
similarity with Java configs or using a more natural method to Perl of
passing in an array-of-hashrefs in the \f(CW\*(C`hosts\*(C'\fR parameter.
.PP
When \f(CW\*(C`Net::Stomp\*(C'\fR connects the first time, upon construction, it will
simply try each host in the list, stopping at the first one that
accepts the connection, dying if no connection attempt is
successful. You can set "\f(CW\*(C`initial_reconnect_attempts\*(C'\fR" to 0 to
mean \*(L"keep looping forever\*(R", or to an integer value to mean \*(L"only go
through the list of hosts this many times\*(R" (the default value is
therefore 1).
.PP
When \f(CW\*(C`Net::Stomp\*(C'\fR notices that the connection has been lost (inside
"\f(CW\*(C`send_frame\*(C'\fR" or "\f(CW\*(C`receive_frame\*(C'\fR"), it will try to
re-connect. In this case, the number of connection attempts will be
limited by "\f(CW\*(C`reconnect_attempts\*(C'\fR", which defaults to 0, meaning
\&\*(L"keep trying forever\*(R".
.PP
\fIReconnect on \f(CI\*(C`fork\*(C'\fI\fR
.IX Subsection "Reconnect on fork"
.PP
By default Net::Stomp will reconnect, using a different socket, if the
process \f(CW\*(C`fork\*(C'\fRs. This avoids problems when parent & child write to
the socket at the same time. If, for whatever reason, you don't want
this to happen, set "\f(CW\*(C`reconnect_on_fork\*(C'\fR" to \f(CW0\fR (either as a
constructor parameter, or by calling the method).
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
These can be passed as constructor parameters, or used as read/write
accessors.
.ie n .SS """hostname"""
.el .SS "\f(CWhostname\fP"
.IX Subsection "hostname"
If you want to connect to a single broker, you can specify its
hostname here. If you modify this value during the lifetime of the
object, the new value will be used for the subsequent reconnect
attempts.
.ie n .SS """port"""
.el .SS "\f(CWport\fP"
.IX Subsection "port"
If you want to connect to a single broker, you can specify its
port here. If you modify this value during the lifetime of the
object, the new value will be used for the subsequent reconnect
attempts.
.ie n .SS """socket_options"""
.el .SS "\f(CWsocket_options\fP"
.IX Subsection "socket_options"
Optional hashref, it will be passed to the IO::Socket::IP,
IO::Socket::SSL, or IO::Socket::INET constructor every time we
need to get a socket.
.PP
In addition to the various options supported by those classes, you can
set \f(CW\*(C`keep_alive\*(C'\fR to a true value, which will enable TCP-level
keep-alive on the socket (see the \s-1TCP\s0 Keepalive
\&\s-1HOWTO\s0 for
some information on that feature).
.ie n .SS """ssl"""
.el .SS "\f(CWssl\fP"
.IX Subsection "ssl"
Boolean, defaults to false, whether we should use \s-1SSL\s0 to talk to the
single broker. If you modify this value during the lifetime of the
object, the new value will be used for the subsequent reconnect
attempts.
.ie n .SS """ssl_options"""
.el .SS "\f(CWssl_options\fP"
.IX Subsection "ssl_options"
Options to pass to IO::Socket::SSL when connecting via \s-1SSL\s0 to the
single broker. If you modify this value during the lifetime of the
object, the new value will be used for the subsequent reconnect
attempts.
.ie n .SS """failover"""
.el .SS "\f(CWfailover\fP"
.IX Subsection "failover"
Modifying this attribute after the object has been constructed has no
effect. Pass this as a constructor parameter only. Its value must be a
\&\s-1URL \s0(as a string) in the form:
.PP
.Vb 1
\& failover://(tcp://$hostname1:$port1,tcp://$hostname2:$port,...)
.Ve
.PP
This is equivalent to setting "\f(CW\*(C`hosts\*(C'\fR" to:
.PP
.Vb 2
\& [ { hostname => $hostname1, port => $port1 },
\& { hostname => $hostname2, port => $port2 } ]
.Ve
.ie n .SS """hosts"""
.el .SS "\f(CWhosts\fP"
.IX Subsection "hosts"
Arrayref of hashrefs, each having a \f(CW\*(C`hostname\*(C'\fR key and a \f(CW\*(C`port\*(C'\fR key,
and optionall \f(CW\*(C`ssl\*(C'\fR and \f(CW\*(C`ssl_options\*(C'\fR. Connections will be attempted
in order, looping around if necessary, depending on the values of "\f(CW\*(C`initial_reconnect_attempts\*(C'\fR" and "\f(CW\*(C`reconnect_attempts\*(C'\fR".
.ie n .SS """current_host"""
.el .SS "\f(CWcurrent_host\fP"
.IX Subsection "current_host"
If using multiple hosts, this is the index (inside the "\f(CW\*(C`hosts\*(C'\fR" array) of the one we're currently connected to.
.ie n .SS """logger"""
.el .SS "\f(CWlogger\fP"
.IX Subsection "logger"
Optional logger object, the default one just logs to \f(CW\*(C`STDERR\*(C'\fR (see
Net::Stomp::StupidLogger). You can pass in any object that
implements (at least) the \f(CW\*(C`warn\*(C'\fR and \f(CW\*(C`fatal\*(C'\fR methods. They will be
passed a string to log.
.ie n .SS """reconnect_on_fork"""
.el .SS "\f(CWreconnect_on_fork\fP"
.IX Subsection "reconnect_on_fork"
Boolean, defaults to true. Reconnect if a method is being invoked from
a different process than the one that created the object. Don't change
this unless you really know what you're doing.
.ie n .SS """initial_reconnect_attempts"""
.el .SS "\f(CWinitial_reconnect_attempts\fP"
.IX Subsection "initial_reconnect_attempts"
Integer, how many times to loop through the "\f(CW\*(C`hosts\*(C'\fR" trying to
connect, before giving up and throwing an exception, during the
construction of the object. Defaults to 1. 0 means \*(L"keep trying
forever\*(R". Between each connection attempt there will be a sleep of "\f(CW\*(C`connect_delay\*(C'\fR" seconds.
.ie n .SS """reconnect_attempts"""
.el .SS "\f(CWreconnect_attempts\fP"
.IX Subsection "reconnect_attempts"
Integer, how many times to loop through the "\f(CW\*(C`hosts\*(C'\fR" trying to
connect, before giving up and throwing an exception, during "\f(CW\*(C`send_frame\*(C'\fR" or "\f(CW\*(C`receive_frame\*(C'\fR". Defaults to 0, meaning
\&\*(L"keep trying forever\*(R". Between each connection attempt there will be a
sleep of "\f(CW\*(C`connect_delay\*(C'\fR" seconds.
.ie n .SS """connect_delay"""
.el .SS "\f(CWconnect_delay\fP"
.IX Subsection "connect_delay"
Integer, defaults to 5. How many seconds to sleep between connection
attempts to brokers.
.ie n .SS """timeout"""
.el .SS "\f(CWtimeout\fP"
.IX Subsection "timeout"
Integer, in seconds, defaults to \f(CW\*(C`undef\*(C'\fR. The default timeout for
read operations. \f(CW\*(C`undef\*(C'\fR means \*(L"wait forever\*(R".
.ie n .SS """receipt_timeout"""
.el .SS "\f(CWreceipt_timeout\fP"
.IX Subsection "receipt_timeout"
Integer, in seconds, defaults to \f(CW\*(C`undef\*(C'\fR. The default timeout while
waiting for a receipt (in "\f(CW\*(C`send_with_receipt\*(C'\fR" and "\f(CW\*(C`send_transactional\*(C'\fR"). If \f(CW\*(C`undef\*(C'\fR, the global "\f(CW\*(C`timeout\*(C'\fR"
is used.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS """connect"""
.el .SS "\f(CWconnect\fP"
.IX Subsection "connect"
This starts the Stomp session with the Stomp server. You may pass in a
\&\f(CW\*(C`login\*(C'\fR and \f(CW\*(C`passcode\*(C'\fR options, plus whatever other headers you may
need (e.g. \f(CW\*(C`client\-id\*(C'\fR, \f(CW\*(C`host\*(C'\fR).
.PP
.Vb 1
\& $stomp\->connect( { login => \*(Aqhello\*(Aq, passcode => \*(Aqthere\*(Aq } );
.Ve
.PP
Returns the frame that the server responded with (or \f(CW\*(C`undef\*(C'\fR if the
connection was lost). If that frame's command is not \f(CW\*(C`CONNECTED\*(C'\fR,
something went wrong.
.ie n .SS """send"""
.el .SS "\f(CWsend\fP"
.IX Subsection "send"
This sends a message to a queue or topic. You must pass in a
destination and a body (which must be a string of bytes). You can also
pass whatever other headers you may need (e.g. \f(CW\*(C`transaction\*(C'\fR).
.PP
.Vb 1
\& $stomp\->send( { destination => \*(Aq/queue/foo\*(Aq, body => \*(Aqtest message\*(Aq } );
.Ve
.PP
It's probably a good idea to pass a \f(CW\*(C`content\-length\*(C'\fR corresponding to
the byte length of the \f(CW\*(C`body\*(C'\fR; this is necessary if the \f(CW\*(C`body\*(C'\fR
contains a byte 0.
.PP
Always returns a true value. It automatically reconnects if writing to
the socket fails.
.ie n .SS """send_with_receipt"""
.el .SS "\f(CWsend_with_receipt\fP"
.IX Subsection "send_with_receipt"
This sends a message asking for a receipt, and returns false if the
receipt of the message is not acknowledged by the server:
.PP
.Vb 3
\& $stomp\->send_with_receipt(
\& { destination => \*(Aq/queue/foo\*(Aq, body => \*(Aqtest message\*(Aq }
\& ) or die "Couldn\*(Aqt send the message!";
.Ve
.PP
If using ActiveMQ, you might also want to make the message persistent:
.PP
.Vb 3
\& $stomp\->send_transactional(
\& { destination => \*(Aq/queue/foo\*(Aq, body => \*(Aqtest message\*(Aq, persistent => \*(Aqtrue\*(Aq }
\& ) or die "Couldn\*(Aqt send the message!";
.Ve
.PP
The actual frame sequence for a successful sending is:
.PP
.Vb 2
\& \-> SEND
\& <\- RECEIPT
.Ve
.PP
The actual frame sequence for a failed sending is:
.PP
.Vb 2
\& \-> SEND
\& <\- anything but RECEIPT
.Ve
.PP
If you are using this connection only to send (i.e. you've never
called "\f(CW\*(C`subscribe\*(C'\fR"), the only thing that could be received
instead of a \f(CW\*(C`RECEIPT\*(C'\fR is an \f(CW\*(C`ERROR\*(C'\fR frame, but if you subscribed,
the broker may well send a \f(CW\*(C`MESSAGE\*(C'\fR before sending the
\&\f(CW\*(C`RECEIPT\*(C'\fR. \fB\s-1DO NOT\s0\fR use this method on a connection used for
receiving.
.PP
If you want to see the \f(CW\*(C`RECEIPT\*(C'\fR or \f(CW\*(C`ERROR\*(C'\fR frame, pass a scalar as
a second parameter to the method, and it will be set to the received
frame:
.PP
.Vb 5
\& my $success = $stomp\->send_transactional(
\& { destination => \*(Aq/queue/foo\*(Aq, body => \*(Aqtest message\*(Aq },
\& $received_frame,
\& );
\& if (not $success) { warn $received_frame\->as_string }
.Ve
.PP
You can specify a \f(CW\*(C`timeout\*(C'\fR in the parametrs, just like for "\f(CW\*(C`received_frame\*(C'\fR". This function will wait for that timeout, or
for "\f(CW\*(C`receipt_timeout\*(C'\fR", or for "\f(CW\*(C`timeout\*(C'\fR", whichever
is defined, or forever, if none is defined.
.ie n .SS """send_transactional"""
.el .SS "\f(CWsend_transactional\fP"
.IX Subsection "send_transactional"
This sends a message in transactional mode and returns false if the
receipt of the message is not acknowledged by the server:
.PP
.Vb 3
\& $stomp\->send_transactional(
\& { destination => \*(Aq/queue/foo\*(Aq, body => \*(Aqtest message\*(Aq }
\& ) or die "Couldn\*(Aqt send the message!";
.Ve
.PP
If using ActiveMQ, you might also want to make the message persistent:
.PP
.Vb 3
\& $stomp\->send_transactional(
\& { destination => \*(Aq/queue/foo\*(Aq, body => \*(Aqtest message\*(Aq, persistent => \*(Aqtrue\*(Aq }
\& ) or die "Couldn\*(Aqt send the message!";
.Ve
.PP
\&\f(CW\*(C`send_transactional\*(C'\fR just wraps \f(CW\*(C`send_with_receipt\*(C'\fR in a \s-1STOMP\s0
transaction.
.PP
The actual frame sequence for a successful sending is:
.PP
.Vb 4
\& \-> BEGIN
\& \-> SEND
\& <\- RECEIPT
\& \-> COMMIT
.Ve
.PP
The actual frame sequence for a failed sending is:
.PP
.Vb 4
\& \-> BEGIN
\& \-> SEND
\& <\- anything but RECEIPT
\& \-> ABORT
.Ve
.PP
If you are using this connection only to send (i.e. you've never
called "\f(CW\*(C`subscribe\*(C'\fR"), the only thing that could be received
instead of a \f(CW\*(C`RECEIPT\*(C'\fR is an \f(CW\*(C`ERROR\*(C'\fR frame, but if you subscribed,
the broker may well send a \f(CW\*(C`MESSAGE\*(C'\fR before sending the
\&\f(CW\*(C`RECEIPT\*(C'\fR. \fB\s-1DO NOT\s0\fR use this method on a connection used for
receiving.
.PP
If you want to see the \f(CW\*(C`RECEIPT\*(C'\fR or \f(CW\*(C`ERROR\*(C'\fR frame, pass a scalar as
a second parameter to the method, and it will be set to the received
frame:
.PP
.Vb 5
\& my $success = $stomp\->send_transactional(
\& { destination => \*(Aq/queue/foo\*(Aq, body => \*(Aqtest message\*(Aq },
\& $received_frame,
\& );
\& if (not $success) { warn $received_frame\->as_string }
.Ve
.PP
You can specify a \f(CW\*(C`timeout\*(C'\fR in the parametrs, just like for "\f(CW\*(C`received_frame\*(C'\fR". This function will wait for that timeout, or
for "\f(CW\*(C`receipt_timeout\*(C'\fR", or for "\f(CW\*(C`timeout\*(C'\fR", whichever
is defined, or forever, if none is defined.
.ie n .SS """disconnect"""
.el .SS "\f(CWdisconnect\fP"
.IX Subsection "disconnect"
This disconnects from the Stomp server:
.PP
.Vb 1
\& $stomp\->disconnect;
.Ve
.PP
If you call any other method after this, a new connection will be
established automatically (to the next failover host, if there's more
than one).
.PP
Always returns a true value.
.ie n .SS """subscribe"""
.el .SS "\f(CWsubscribe\fP"
.IX Subsection "subscribe"
This subscribes you to a queue or topic. You must pass in a
\&\f(CW\*(C`destination\*(C'\fR.
.PP
Always returns a true value.
.PP
The acknowledge mode (header \f(CW\*(C`ack\*(C'\fR) defaults to \f(CW\*(C`auto\*(C'\fR, which means
that frames will be considered delivered after they have been sent to
a client. The other option is \f(CW\*(C`client\*(C'\fR, which means that messages
will only be considered delivered after the client specifically
acknowledges them with an \s-1ACK\s0 frame (see "\f(CW\*(C`ack\*(C'\fR").
.PP
When \f(CW\*(C`Net::Stomp\*(C'\fR reconnects after a failure, all subscriptions will
be re-instated, each with its own options.
.PP
Other options:
.ie n .IP """selector""" 4
.el .IP "\f(CWselector\fR" 4
.IX Item "selector"
Specifies a \s-1JMS\s0 Selector using \s-1SQL 92\s0 syntax as specified in the \s-1JMS
1.1\s0 specification. This allows a filter to be applied to each message
as part of the subscription.
.ie n .IP """id""" 4
.el .IP "\f(CWid\fR" 4
.IX Item "id"
A unique identifier for this subscription. Very useful if you
subscribe to the same destination more than once (e.g. with different
selectors), so that messages arriving will have a \f(CW\*(C`subscription\*(C'\fR
header with this value if they arrived because of this subscription.
.ie n .IP """activemq.dispatchAsync""" 4
.el .IP "\f(CWactivemq.dispatchAsync\fR" 4
.IX Item "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.
.ie n .IP """activemq.exclusive""" 4
.el .IP "\f(CWactivemq.exclusive\fR" 4
.IX Item "activemq.exclusive"
Would I like to be an Exclusive Consumer on a queue.
.ie n .IP """activemq.maximumPendingMessageLimit""" 4
.el .IP "\f(CWactivemq.maximumPendingMessageLimit\fR" 4
.IX Item "activemq.maximumPendingMessageLimit"
For Slow Consumer Handling on 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.
.ie n .IP """activemq.noLocal""" 4
.el .IP "\f(CWactivemq.noLocal\fR" 4
.IX Item "activemq.noLocal"
Specifies whether or not locally sent messages should be ignored for
subscriptions. Set to true to filter out locally sent messages.
.ie n .IP """activemq.prefetchSize""" 4
.el .IP "\f(CWactivemq.prefetchSize\fR" 4
.IX Item "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.
.ie n .IP """activemq.priority""" 4
.el .IP "\f(CWactivemq.priority\fR" 4
.IX Item "activemq.priority"
Sets the priority of the consumer so that dispatching can be weighted
in priority order.
.ie n .IP """activemq.retroactive""" 4
.el .IP "\f(CWactivemq.retroactive\fR" 4
.IX Item "activemq.retroactive"
For non-durable topics do you wish this subscription to the
retroactive.
.ie n .IP """activemq.subscriptionName""" 4
.el .IP "\f(CWactivemq.subscriptionName\fR" 4
.IX Item "activemq.subscriptionName"
For durable topic subscriptions you must specify the same "\f(CW\*(C`client\-id\*(C'\fR" on the connection and "\f(CW\*(C`subscriptionName\*(C'\fR" on
the subscribe.
.PP
.Vb 6
\& $stomp\->subscribe(
\& { destination => \*(Aq/queue/foo\*(Aq,
\& \*(Aqack\*(Aq => \*(Aqclient\*(Aq,
\& \*(Aqactivemq.prefetchSize\*(Aq => 1
\& }
\& );
.Ve
.ie n .SS """unsubscribe"""
.el .SS "\f(CWunsubscribe\fP"
.IX Subsection "unsubscribe"
This unsubscribes you to a queue or topic. You must pass in a
\&\f(CW\*(C`destination\*(C'\fR or an \f(CW\*(C`id\*(C'\fR:
.PP
.Vb 1
\& $stomp\->unsubcribe({ destination => \*(Aq/queue/foo\*(Aq });
.Ve
.PP
Always returns a true value.
.ie n .SS """receive_frame"""
.el .SS "\f(CWreceive_frame\fP"
.IX Subsection "receive_frame"
This blocks and returns you the next Stomp frame, or \f(CW\*(C`undef\*(C'\fR if there
was a connection problem.
.PP
.Vb 2
\& my $frame = $stomp\->receive_frame;
\& warn $frame\->body; # do something here
.Ve
.PP
By default this method will block until a frame can be returned, or
for however long the \*(L"timeout\*(R" attribue says. If you wish to wait
for a specified time pass a \f(CW\*(C`timeout\*(C'\fR argument:
.PP
.Vb 2
\& # Wait half a second for a frame, else return undef
\& $stomp\->receive_frame({ timeout => 0.5 })
.Ve
.ie n .SS """can_read"""
.el .SS "\f(CWcan_read\fP"
.IX Subsection "can_read"
This returns whether there is new data waiting to be read from the
\&\s-1STOMP\s0 server. Optionally takes a timeout in seconds:
.PP
.Vb 2
\& my $can_read = $stomp\->can_read;
\& my $can_read = $stomp\->can_read({ timeout => \*(Aq0.1\*(Aq });
.Ve
.PP
\&\f(CW\*(C`undef\*(C'\fR says block until something can be read, \f(CW0\fR says to poll and
return immediately. This method ignores the value of the \*(L"timeout\*(R"
attribute.
.ie n .SS """ack"""
.el .SS "\f(CWack\fP"
.IX Subsection "ack"
This acknowledges that you have received and processed a frame \fIand
all frames before it\fR (if you are using client acknowledgements):
.PP
.Vb 1
\& $stomp\->ack( { frame => $frame } );
.Ve
.PP
Always returns a true value.
.ie n .SS """nack"""
.el .SS "\f(CWnack\fP"
.IX Subsection "nack"
This informs the remote end that you have been unable to process a
received frame (if you are using client acknowledgements)
(See individual stomp server documentation for information about
additional fields that can be passed to alter \s-1NACK\s0 behavior):
.PP
.Vb 1
\& $stomp\->nack( { frame => $frame } );
.Ve
.PP
Always returns a true value.
.ie n .SS """send_frame"""
.el .SS "\f(CWsend_frame\fP"
.IX Subsection "send_frame"
If this module does not provide enough help for sending frames, you
may construct your own frame and send it:
.PP
.Vb 4
\& # write your own frame
\& my $frame = Net::Stomp::Frame\->new(
\& { command => $command, headers => $conf, body => $body } );
\& $self\->send_frame($frame);
.Ve
.PP
This is the method used by all the other methods that send frames. It
will keep trying to send the frame as hard as it can, reconnecting if
the connection breaks (limited by "\f(CW\*(C`reconnect_attempts\*(C'\fR"). If
no connection can be established, and "\f(CW\*(C`reconnect_attempts\*(C'\fR" is
not 0, this method will \f(CW\*(C`die\*(C'\fR.
.PP
Always returns an empty list.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::Stomp::Frame.
.SH "SOURCE REPOSITORY"
.IX Header "SOURCE REPOSITORY"
https://github.com/dakkar/Net\-Stomp
.SH "AUTHORS"
.IX Header "AUTHORS"
Leon Brocard ,
Thom May ,
Michael S. Fischer ,
Ash Berlin
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Paul Driver ,
Andreas Faafeng ,
Vigith Maurice ,
Stephen Fralich ,
Squeeks ,
Chisel Wright ,
Gianni Ceccarelli
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2006\-9, Leon Brocard
Copyright (C) 2009, Thom May, Betfair.com
Copyright (C) 2010, Ash Berlin, Net\-a\-Porter.com
Copyright (C) 2010, Michael S. Fischer
.PP
This module is free software; you can redistribute it or modify it
under the same terms as Perl itself.