1Net::STOMP::Client(3) User Contributed Perl DocumentationNet::STOMP::Client(3)
2
3
4
6 Net::STOMP::Client - STOMP object oriented client module
7
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
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
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
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
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
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
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
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
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
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
440 Lionel Cons <http://cern.ch/lionel.cons>
441
442 Copyright (C) CERN 2010-2017
443
444
445
446perl v5.30.1 2020-01-30 Net::STOMP::Client(3)