1Net::STOMP::Client(3) User Contributed Perl DocumentationNet::STOMP::Client(3)
2
6 Net::STOMP::Client - STOMP object oriented client module
7
9 #
10 # simple producer
11 #
12 use Net::STOMP::Client;
14 $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 #
21 # consumer with client side acknowledgment
22 #
23 use Net::STOMP::Client;
25 $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);
33 printf("received: %s\n", $frame->body());
34 return($self);
35 });
36 # subscribe to the given queue
37 $stomp->subscribe(destination => "/queue/test", ack => "client");
38 # wait for a specified message frame
39 $stomp->wait_for_frames(callback => sub {
40 my($self, $frame) = @_;
41 if ($frame->command() eq "MESSAGE") {
43 # stop waiting for new frames if body is "quit"
44 return(1) if $frame->body() eq "quit";
45 }
46 # continue to wait for more frames
47 return(0);
48 });
49 $stomp->unsubscribe(destination => "/queue/test");
50 $stomp->disconnect();
51
53 This module provides an object oriented client interface to interact
54 with servers supporting STOMP (Streaming Text Orientated Messaging
55 Protocol). It supports the major features of modern messaging brokers:
56 SSL, asynchronous I/O, receipts and transactions.
57
59 The new() method can be used to create a Net::STOMP::Client object that
60 will later be used to interact with a server. The following attributes
61 are supported:
62 "version"
64 the STOMP version to use (string) or versions to use (reference to
65 a list of strings); this defaults to the list of all supported
66 versions
67 "uri"
69 the Uniform Resource Identifier (URI) specifying where the STOMP
70 service is and how to connect to it, this can be for instance
71 "tcp://msg01:6163" or something more complex such as
72 "failover:(ssl://msg01:6162,tcp://msg01:6163)"
73 "host"
75 the server name or IP address
76 "port"
78 the port number of the STOMP service
79 "timeout"
81 the maximum time (in seconds) for various operations, see the
82 "TIMEOUTS" section for more information
83 "sockopts"
85 arbitrary socket options (as a hash reference) that will be passed
86 to IO::Socket::INET->new() or IO::Socket::SSL->new()
87 "callbacks"
89 a hash of code references that will be called on each received
90 frame
91 "client_heart_beat"
93 the desired client-side heart-beat setting, see the "HEART-BEATING"
94 section for more information
95 "server_heart_beat"
97 the desired server-side heart-beat setting, see the "HEART-BEATING"
98 section for more information
99 Upon object creation, a TCP connection is made to the server but no
101 data (i.e. STOMP frame) is exchanged.
102
104 When creating an object with Net::STOMP::Client->new(), if you supply
105 some socket options (via "sockopts") with a name starting with "SSL_",
106 or if you supply a URI (via "uri") with a scheme containg "ssl",
107 IO::Socket::SSL will be used to create the socket instead of
108 IO::Socket::INET and the communication with the server will then go
109 through SSL.
110 Here are the most commonly used SSL socket options:
112 SSL_ca_path
114 path to a directory containing several trusted certificates as
115 separate files as well as an index of the certificates
116 SSL_key_file
118 path of your RSA private key
119 SSL_cert_file
121 path of your certificate
122 SSL_passwd_cb
124 subroutine that should return the password required to decrypt your
125 private key
126 For more information, see IO::Socket::SSL.
128
130 By default, when sending STOMP frames, the module waits until the frame
131 indeed has been sent (from the socket point of view). In case the
132 server is stuck or unusable, the module can therefore hang.
133 When creating the Net::STOMP::Client object, you can pass a "timeout"
135 attribute to better control how certain operations handle timeouts.
136 This attribute should contain a reference to hash with the following
138 keys:
139 connect
141 TCP-level timeout that will be given to the underlying
142 IO::Socket::INET or IO::Socket::SSL object (default: none)
143 connected
145 timeout used while waiting for the initial CONNECTED frame from the
146 broker (default: 10)
147 send
149 timeout used while trying to send any frame (default: none)
150 All values are in seconds. No timeout means wait until the operation
152 succeeds.
153 As a shortcut, the "timeout" attribute can also be a scalar. In this
155 case, only the "connect" and "connected" operations use this value.
156
158 With a Net::STOMP::Client object, the following methods can be used to
159 interact with the server. They match one-to-one the different commands
160 that a client frame can hold:
161 connect()
163 connect to server
164 disconnect()
166 disconnect from server
167 subscribe()
169 subscribe to something
170 unsubscribe()
172 unsubscribe from something
173 send()
175 send a message somewhere
176 ack()
178 acknowledge the reception of a message
179 nack()
181 acknowledge the rejection of a message (STOMP 1.1 only)
182 begin()
184 begin/start a transaction
185 commit()
187 commit a transaction
188 abort()
190 abort/rollback a transaction
191 All these methods can receive options that will be passed directly as
193 frame headers. For instance:
194 $stomp->subscribe(
196 destination => "/queue/test",
197 ack => "client",
198 );
199 Some methods also support other options:
201 send()
203 "body": holds the body of the message to be sent
204 ack()
206 "frame": holds the MESSAGE frame object to ACK
207 nack()
209 "frame": holds the MESSAGE frame object to NACK
210 Finally, all methods support a "timeout" option that will be given to
212 the send_frame() method called internally to send the crafted frame.
213
215 In addition to the STOMP methods, the following ones are also
216 available:
217 new(OPTIONS)
219 return a new Net::STOMP::Client object
220 peer()
222 return a Net::STOMP::Client::Peer object containing information
223 about the connected STOMP server
224 socket()
226 return the file handle of the socket connecting the client and the
227 server
228 session()
230 return the session identifier if connected or undef otherwise
231 version()
233 return the STOMP version that has been negotiated between the
234 client and the server or undef if the negotiation did not take
235 place yet
236 uuid()
238 return a universal pseudo-unique identifier to be used for instance
239 in receipts and transactions
240 receipts()
242 return the list of not-yet-received receipts, see the "RECEIPTS"
243 section for more information
244 wait_for_frames()
246 wait for frames coming from the server, see the next section for
247 more information
248 wait_for_receipts()
250 wait for all receipts to be received, using wait_for_frames()
251 underneath
252 noop([timeout => TIMEOUT])
254 send an empty/noop frame i.e. a single newline byte, using
255 send_frame() underneath
256
258 Since STOMP is asynchronous (for instance, "MESSAGE" frames could be
259 sent by the server at any time), Net::STOMP::Client uses callbacks to
260 handle frames. There are in fact two levels of callbacks.
261 First, there are per-command callbacks that will be called each time a
263 frame is handled (via the internal method dispatch_frame()).
264 Net::STOMP::Client implements default callbacks that should be
265 sufficient for all frames except "MESSAGE" frames, which should really
266 be handled by the coder. These callbacks should return undef on error,
267 something else on success.
268 Here is an example with a callback counting the messages received:
270 $stomp->message_callback(sub {
272 my($self, $frame) = @_;
273 $MessageCount++;
275 return($self);
276 });
277 Here are the methods that can be used to get or set these per-command
279 callbacks:
280 connected_callback([SUBREF])
282 error_callback([SUBREF])
283 message_callback([SUBREF])
284 receipt_callback([SUBREF])
285 These callbacks are somehow global and it is good practice not to
287 change them during a session. If you do not need a global message
288 callback, you can supply the dummy:
289 $stomp->message_callback(sub { return(1) });
291 Then, the wait_for_frames() method takes an optional callback argument
293 holding some code to be called for each received frame, after the per-
294 command callback has been called. This can be seen as a local callback,
295 only valid for the call to wait_for_frames(). This callback must return
296 undef on error, false if more frames are expected or true if
297 wait_for_frames() can now stop waiting for new frames and return.
298 Here are all the options that can be given to wait_for_frames():
300 callback
302 code to be called for each received frame (see above)
303 timeout
305 time to wait before giving up, undef means wait forever, this is
306 the default
307 once
309 wait only for one frame, within the given timeout
310 The return value of wait_for_frames() can be: undef in case of error,
312 false if no suitable frame has been received, the received frame if
313 there is no user callback or the user callback return value otherwise.
314
316 Net::STOMP::Client has built-in support for receipts.
317 Each time a frame is sent, its "receipt" header (if supplied) is
319 remembered.
320 Each time a "RECEIPT" frame is received from the server, the
322 corresponding receipt is ticked off.
323 The receipts() method can be used to get the list of outstanding
325 receipts.
326 The wait_for_receipts() method can be used to wait for all missing
328 receipts.
329 Here is sample code to send two messages with receipts and then wait
331 for both acknowledgments to come back from the server within ten
332 seconds:
333 $stomp->send(
335 destination => "/queue/test1",
336 body => "message 1",
337 receipt => $stomp->uuid(),
338 );
339 $stomp->send(
340 destination => "/queue/test2",
341 body => "message 2",
342 receipt => $stomp->uuid(),
343 );
344 $stomp->wait_for_receipts(timeout => 10);
345 die("Not all receipts received!\n") if $stomp->receipts();
346
348 Here is an example using transactions:
349 # create a unique transaction id
351 $tid = $stomp->uuid();
352 # begin the transaction
353 $stomp->begin(transaction => $tid);
354 # send two messages as part of this transaction
355 $stomp->send(
356 destination => "/queue/test1",
357 body => "message 1",
358 transaction => $tid,
359 );
360 $stomp->send(
361 destination => "/queue/test2",
362 body => "message 2",
363 transaction => $tid,
364 );
365 # commit the transaction
366 $stomp->commit(transaction => $tid);
367
369 STOMP 1.1 defines how each end of a STOMP connection can check if the
370 other end is alive. To support heart-beating, this module provides the
371 following methods:
372 last_received()
374 return the time at which data was last received, i.e. read from the
375 network socket
376 last_sent()
378 return the time at which data was last sent, i.e. written to the
379 network socket
380 client_heart_beat()
382 (after having received the CONNECTED frame) return the negotiated
383 client-side heart-beat setting
384 server_heart_beat()
386 (after having received the CONNECTED frame) return the negotiated
387 server-side heart-beat setting
388 beat([timeout => TIMEOUT])
390 send a noop frame (using the noop() method) unless the last sent
391 time is recent enough with regard to the client heart-beat setting
392 For consistency with other Perl modules (for instance Time::HiRes),
394 time is always expressed as a fractional number of seconds.
395 To use heart-beating, the client must specify the desired
397 "client_heart_beat" and/or "server_heart_beat" attributes when invoking
398 the new() method. Then, once the CONNECTED frame has been received, it
399 can get the negotiated values with the methods above.
400 To prove that it is alive, the client just needs to call the beat()
402 method.
403 To check if the server is alive, the client just needs to compare what
405 is returned by the last_received() and server_heart_beat() methods.
406
408 It should be enough to use the high-level API and use, for instance,
409 the send() method to create a MESSAGE frame and send it in one go.
410 If you need lower level interaction, you can manipulate frames with the
412 Net::STOMP::Client::Frame module.
413 You can also use:
415 $stomp->dispatch_frame(FRAME)
417 dispatch one received frame by calling the appropriate callback
418 $stomp->send_frame(FRAME, TIMEOUT)
420 try to send the given frame object within the given TIMEOUT, or
421 forever if the TIMEOUT is undef
422 $stomp->receive_frame(TIMEOUT)
424 try to receive a frame within the given TIMEOUT, or forever if the
425 TIMEOUT is undef
426
428 This module implements the versions 1.0 (see
429 http://stomp.github.com/stomp-specification-1.0.html
430 <http://stomp.github.com/stomp-specification-1.0.html>) and 1.1 (see
431 http://stomp.github.com/stomp-specification-1.1.html
432 <http://stomp.github.com/stomp-specification-1.1.html>) of the protocol
433 as well as well known extensions for JMS, AMQP, ActiveMQ and RabbitMQ.
434 It has been successfully tested against both ActiveMQ and RabbitMQ
436 brokers.
437
439 IO::Socket::INET, IO::Socket::SSL, Net::STOMP::Client::Error,
440 Net::STOMP::Client::Frame, Net::STOMP::Client::Peer, Time::HiRes.
441
443 Lionel Cons <http://cern.ch/lionel.cons>
444 Copyright CERN 2010-2011
446perl v5.12.3 2011-05-10 Net::STOMP::Client(3)