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::INET->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::INET 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" and "connected" operations use this value.
206

STOMP METHODS

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

OTHER METHODS

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

CALLBACKS

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

TRANSACTIONS

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

LOW-LEVEL API

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

COMPATIBILITY

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

SEE ALSO

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

AUTHOR

440       Lionel Cons <http://cern.ch/lionel.cons>
441
442       Copyright (C) CERN 2010-2017
443
444
445
446perl v5.28.1                      2017-01-31             Net::STOMP::Client(3)
Impressum