1Net::STOMP::Client(3) User Contributed Perl DocumentationNet::STOMP::Client(3)
2
3
4

NAME

6       Net::STOMP::Client - STOMP object oriented client module
7

SYNOPSIS

9         #
10         # simple producer
11         #
12
13         use Net::STOMP::Client;
14
15         $stomp = Net::STOMP::Client->new(host => "127.0.0.1", port => 61613);
16         $stomp->connect(login => "guest", passcode => "guest");
17         $stomp->send(destination => "/queue/test", body => "hello world!");
18         $stomp->disconnect();
19
20         #
21         # consumer with client side acknowledgment
22         #
23
24         use Net::STOMP::Client;
25
26         $stomp = Net::STOMP::Client->new(host => "127.0.0.1", port => 61613);
27         $stomp->connect(login => "guest", passcode => "guest");
28         # declare a callback to be called for each received message frame
29         $stomp->message_callback(sub {
30             my($self, $frame) = @_;
31             $self->ack(frame => $frame);
32             printf("received: %s\n", $frame->body());
33             return($self);
34         });
35         # subscribe to the given queue
36         $stomp->subscribe(
37             destination => "/queue/test",
38             id          => "testsub",          # required in STOMP 1.1
39             ack         => "client",           # client side acknowledgment
40         );
41         # wait for a specified message frame
42         $stomp->wait_for_frames(callback => sub {
43             my($self, $frame) = @_;
44             if ($frame->command() eq "MESSAGE") {
45                 # stop waiting for new frames if body is "quit"
46                 return(1) if $frame->body() eq "quit";
47             }
48             # continue to wait for more frames
49             return(0);
50         });
51         $stomp->unsubscribe(id => "testsub");
52         $stomp->disconnect();
53

DESCRIPTION

55       This module provides an object oriented client interface to interact
56       with servers supporting STOMP (Streaming Text Orientated Messaging
57       Protocol). It supports the major features of modern messaging brokers:
58       SSL, asynchronous I/O, receipts and transactions.
59

CONSTRUCTOR

61       The new() method can be used to create a Net::STOMP::Client object that
62       will later be used to interact with a server. The following attributes
63       are supported:
64
65       "accept_version"
66           the STOMP version to use (string) or versions to use (reference to
67           a list of strings); this defaults to the list of all supported
68           versions; see Net::STOMP::Client::Version for more information
69
70       "version"
71           this attribute is obsolete and should not be used anymore, use
72           "accept_version" instead; it is left here only to provide backward
73           compatibility with Net::STOMP::Client 1.x
74
75       "uri"
76           the Uniform Resource Identifier (URI) specifying where the STOMP
77           service is and how to connect to it, this can be for instance
78           "tcp://msg01:6163" or something more complex, see
79           Net::STOMP::Client::Connection for more information
80
81       "host"
82           the server name or IP address
83
84       "port"
85           the port number of the STOMP service
86
87       "auth"
88           the authentication credential(s) to use, see
89           Net::STOMP::Client::Auth for more information
90
91       "sockopts"
92           arbitrary socket options (as a hash reference) that will be passed
93           to IO::Socket::IP->new() or IO::Socket::SSL->new()
94
95       "client_heart_beat"
96           the desired client-side heart-beat setting, see
97           Net::STOMP::Client::HeartBeat for more information
98
99       "server_heart_beat"
100           the desired server-side heart-beat setting, see
101           Net::STOMP::Client::HeartBeat for more information
102
103       "debug"
104           the debugging flags for this object, see the "DEBUGGING" section
105           for more information
106
107       "timeout"
108           the maximum time (in seconds) for various operations, see the
109           "TIMEOUTS" section for more information
110
111       Upon object creation, a TCP connection is made to the server but no
112       data (i.e. STOMP frame) is exchanged.
113
114   DEBUGGING
115       Net::STOMP::Client uses No::Worries::Log's log_debug() to log debugging
116       information. In addition, to avoid useless data massaging, it also uses
117       a debug string to specify what will be logged using log_debug().
118
119       The debug string should contain a list of words describing what to log.
120       For instance, "io" logs I/O information while "io connection" logs both
121       I/O and connection information.
122
123       Here are the supported debug words that can be used:
124
125       "all"
126           everything
127
128       "api"
129           high-level API calls
130
131       "body"
132           frame bodies
133
134       "command"
135           frame commands
136
137       "connection"
138           connection establishment
139
140       "header"
141           frame headers
142
143       "io"
144           I/O as bytes sent/received
145
146       To enable debugging, you must first configure No::Worries::Log so that
147       it indeed reports debugging messages. This can be done with something
148       like:
149
150         log_filter("debug");
151
152       or, to enable logging only from Net::STOMP::Client modules:
153
154         log_filter("debug caller=~^Net::STOMP::Client");
155
156       See the No::Worries::Log documentation for more information.
157
158       Then, you have to tell Net::STOMP::Client to indeed log what you want
159       to see. This can be done globally for all connections by setting the
160       global variable $Net::STOMP::Client::Debug:
161
162         $Net::STOMP::Client::Debug = "connection api";
163
164       or per connection via the new() method:
165
166         $stomp = Net::STOMP::Client->new(
167             uri   => "stomp://mybroker:6163",
168             debug => "connection api",
169         );
170
171   TIMEOUTS
172       By default, when sending STOMP frames, the module waits until the frame
173       indeed has been sent (from the socket point of view). In case the
174       server is stuck or unusable, the module can therefore hang.
175
176       When creating the Net::STOMP::Client object, you can pass a "timeout"
177       attribute to better control how certain operations handle timeouts.
178
179       This attribute should contain a reference to hash with the following
180       keys:
181
182       connect
183           TCP-level timeout that will be given to the underlying
184           IO::Socket::IP or IO::Socket::SSL object (default: none)
185
186       connected
187           timeout used while waiting for the initial "CONNECTED" frame from
188           the broker (default: 10)
189
190       disconnect
191           timeout specifying how long the disconnect() method should wait for
192           a "RECEIPT" frame back in case the "DISCONNECT" frame contained a
193           receipt (default: 10)
194
195       receive
196           timeout used while trying to receive any frame (default: none)
197
198       send
199           timeout used while trying to send any frame (default: none)
200
201       All values are in seconds. No timeout means wait until the operation
202       succeeds.
203
204       As a shortcut, the "timeout" attribute can also be a scalar. In this
205       case, only the "connect", "connected" and "disconnect" operations use
206       this value.
207

STOMP METHODS

209       With a Net::STOMP::Client object, the following methods can be used to
210       interact with the server. They match one-to-one the different commands
211       that a client frame can hold:
212
213       connect()
214           connect to server
215
216       disconnect()
217           disconnect from server
218
219       subscribe()
220           subscribe to something
221
222       unsubscribe()
223           unsubscribe from something
224
225       send()
226           send a message somewhere
227
228       ack()
229           acknowledge the reception of a message
230
231       nack()
232           acknowledge the rejection of a message (STOMP >=1.1 only)
233
234       begin()
235           begin/start a transaction
236
237       commit()
238           commit a transaction
239
240       abort()
241           abort/rollback a transaction
242
243       All these methods can receive options that will be passed directly as
244       frame headers. For instance:
245
246         $stomp->subscribe(
247             destination => "/queue/test",
248             id          => "testsub",
249             ack         => "client",
250         );
251
252       Some methods also support additional options:
253
254       send()
255           "body" or "body_reference": holds the body or body reference of the
256           message to be sent
257
258       ack()
259           "frame": holds the "MESSAGE" frame object to ack
260
261       nack()
262           "frame": holds the "MESSAGE" frame object to nack
263
264       Finally, all methods support "debug" and "timeout" options that will be
265       given to the send_frame() method called internally to send the crafted
266       frame.
267

OTHER METHODS

269       In addition to the STOMP methods, the following ones are also
270       available:
271
272       new(OPTIONS)
273           return a new Net::STOMP::Client object (constructor)
274
275       peer()
276           return a Net::STOMP::Client::Peer object containing information
277           about the connected STOMP server
278
279       socket()
280           return the file handle of the socket connecting the client and the
281           server
282
283       server()
284           return the server header seen on the "CONNECTED" frame (if any)
285
286       session()
287           return the session identifier if connected or false otherwise
288
289       uuid()
290           return a universal pseudo-unique identifier to be used for instance
291           in receipts and transactions
292
293       wait_for_frames()
294           wait for frames coming from the server, see the next section for
295           more information
296
297       noop([timeout => TIMEOUT])
298           send an empty/noop frame i.e. a single newline byte, using
299           send_frame() underneath
300

CALLBACKS

302       Since STOMP is asynchronous (for instance, "MESSAGE" frames could be
303       sent by the server at any time), Net::STOMP::Client uses callbacks to
304       handle frames. There are in fact two levels of callbacks.
305
306       First, there are per-command callbacks that will be called each time a
307       frame is handled (via the internal dispatch_frame() method).
308       Net::STOMP::Client implements default callbacks that should be
309       sufficient for all frames except "MESSAGE" frames, which should really
310       be handled by the coder.  These callbacks should return undef on error,
311       something else on success.
312
313       Here is an example with a callback counting the messages received:
314
315         $stomp->message_callback(sub {
316             my($self, $frame) = @_;
317             $MessageCount++;
318             return($self);
319         });
320
321       Here are the methods that can be used to get or set these per-command
322       callbacks:
323
324       connected_callback([SUBREF])
325       error_callback([SUBREF])
326       message_callback([SUBREF])
327       receipt_callback([SUBREF])
328
329       These callbacks are somehow global and it is good practice not to
330       change them during a session. If you do not need a global message
331       callback, you can supply the dummy:
332
333         $stomp->message_callback(sub { return(1) });
334
335       Then, the wait_for_frames() method takes an optional callback argument
336       holding some code to be called for each received frame, after the per-
337       command callback has been called. This can be seen as a local callback,
338       only valid for the call to wait_for_frames(). This callback must return
339       undef on error, false if more frames are expected or true if
340       wait_for_frames() can now stop waiting for new frames and return.
341
342       Here are all the options that can be given to wait_for_frames():
343
344       callback
345           code to be called for each received frame (see above)
346
347       timeout
348           time to wait before giving up, undef means wait forever, this is
349           the default
350
351       once
352           wait only for one frame, within the given timeout
353
354       The return value of wait_for_frames() can be: false if no suitable
355       frame has been received, the received frame if there is no user
356       callback or the user callback return value otherwise.
357

TRANSACTIONS

359       Here is an example using transactions:
360
361         # create a unique transaction id
362         $tid = $stomp->uuid();
363         # begin the transaction
364         $stomp->begin(transaction => $tid);
365         # send two messages as part of this transaction
366         $stomp->send(
367             destination => "/queue/test1",
368             body        => "message 1",
369             transaction => $tid,
370         );
371         $stomp->send(
372             destination => "/queue/test2",
373             body        => "message 2",
374             transaction => $tid,
375         );
376         # commit the transaction
377         $stomp->commit(transaction => $tid);
378

LOW-LEVEL API

380       It should be enough to use the high-level API and use, for instance,
381       the send() method to create a "MESSAGE" frame and send it in one go.
382
383       If you need lower level interaction, you can manipulate frames with the
384       Net::STOMP::Client::Frame module.
385
386       You can also use:
387
388       $stomp->dispatch_frame(FRAME, [OPTIONS])
389           dispatch one received frame by calling the appropriate callback;
390           supported options: "debug"
391
392       $stomp->send_frame(FRAME, [OPTIONS])
393           try to send the given frame object; supported options: "timeout"
394           and "debug"
395
396       $stomp->send_message(MESSAGE, [OPTIONS])
397           identical to send_frame() but taking a Messaging::Message object
398
399       $stomp->queue_frame(FRAME, [OPTIONS])
400           add the given frame to the outgoing buffer queue; supported
401           options: "debug"
402
403       $stomp->queue_message(MESSAGE, [OPTIONS])
404           identical to queue_frame() but taking a Messaging::Message object
405
406       $stomp->send_data([OPTIONS])
407           send all the queued data; supported options: "timeout" and "debug"
408
409       $stomp->receive_frame([OPTIONS])
410           try to receive a frame; supported options: "timeout" and "debug"
411
412       $stomp->receive_data([OPTIONS])
413           try to receive data (this data will be appended to the incoming
414           buffer); supported options: "timeout" and "debug"
415
416       $stomp->outgoing_buffer_length()
417           return the length (in bytes) of the outgoing buffer
418
419       $stomp->incoming_buffer_reference()
420           return a reference to the incoming buffer
421
422       In these methods, the "timeout" option can either be "undef" (meaning
423       block until it's done) or 0 (meaning do not block at all) or a positive
424       number (meaning block at most this number of seconds).
425

COMPATIBILITY

427       This module has been successfully tested against ActiveMQ, Apollo,
428       HornetQ and RabbitMQ brokers.
429
430       See Net::STOMP::Client::Version for the list of supported STOMP
431       protocol versions.
432

SEE ALSO

434       Messaging::Message, Net::STOMP::Client::Auth,
435       Net::STOMP::Client::Connection, Net::STOMP::Client::Frame,
436       Net::STOMP::Client::HeartBeat, Net::STOMP::Client::Peer,
437       Net::STOMP::Client::Receipt, Net::STOMP::Client::Tutorial,
438       Net::STOMP::Client::Version, No::Worries::Log.
439

AUTHOR

441       Lionel Cons <http://cern.ch/lionel.cons>
442
443       Copyright (C) CERN 2010-2021
444
445
446
447perl v5.36.0                      2022-07-22             Net::STOMP::Client(3)
Impressum