1Net::Stomp(3) User Contributed Perl Documentation Net::Stomp(3)
2
6 Net::Stomp - A Streaming Text Orientated Messaging Protocol Client
7
9 # send a message to the queue 'foo'
10 use Net::Stomp;
11 my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );
12 $stomp->connect( { login => 'hello', passcode => 'there' } );
13 $stomp->send(
14 { destination => '/queue/foo', body => 'test message' } );
15 $stomp->disconnect;
16 # subscribe to messages from the queue 'foo'
18 use Net::Stomp;
19 my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );
20 $stomp->connect( { login => 'hello', passcode => 'there' } );
21 $stomp->subscribe(
22 { destination => '/queue/foo',
23 'ack' => 'client',
24 'activemq.prefetchSize' => 1
25 }
26 );
27 while (1) {
28 my $frame = $stomp->receive_frame;
29 warn $frame->body; # do something here
30 $stomp->ack( { frame => $frame } );
31 }
32 $stomp->disconnect;
33 # write your own frame
35 my $frame = Net::Stomp::Frame->new(
36 { command => $command, headers => $conf, body => $body } );
37 $self->send_frame($frame);
38 # connect with failover supporting similar URI to ActiveMQ
40 $stomp = Net::Stomp->new({ failover => "failover://tcp://primary:61616" })
41 # "?randomize=..." and other parameters are ignored currently
42 $stomp = Net::Stomp->new({ failover => "failover:(tcp://primary:61616,tcp://secondary:61616)?randomize=false" })
43 # Or in a more natural perl way
45 $stomp = Net::Stomp->new({ hosts => [
46 { hostname => 'primary', port => 61616 },
47 { hostname => 'secondary', port => 61616 },
48 ] });
49
51 This module allows you to write a Stomp client. Stomp is the Streaming
52 Text Orientated Messaging Protocol (or the Protocol Briefly Known as
53 TTMP and Represented by the symbol :ttmp). It's a simple and easy to
54 implement protocol for working with Message Orientated Middleware from
55 any language. Net::Stomp is useful for talking to Apache ActiveMQ, an
56 open source (Apache 2.0 licensed) Java Message Service 1.1 (JMS)
57 message broker packed with many enterprise features.
58 A Stomp frame consists of a command, a series of headers and a body -
60 see Net::Stomp::Frame for more details.
61 For details on the protocol see <http://stomp.codehaus.org/Protocol>.
63 To enable the ActiveMQ Broker for Stomp add the following to the
65 activemq.xml configuration inside the <transportConnectors> section:
66 <transportConnector name="stomp" uri="stomp://localhost:61613"/>
68 To enable the ActiveMQ Broker for Stomp and SSL add the following
70 inside the <transportConnectors> section:
71 <transportConnector name="stomp+ssl" uri="stomp+ssl://localhost:61612"/>
73 For details on Stomp in ActiveMQ See
75 <http://activemq.apache.org/stomp.html>.
76
78 new
79 The constructor creates a new object. You must pass in a hostname and a
80 port or set a failover configuration:
81 my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );
83 If you want to use SSL, make sure you have IO::Socket::SSL and pass in
85 the SSL flag:
86 my $stomp = Net::Stomp->new( {
88 hostname => 'localhost',
89 port => '61612',
90 ssl => 1,
91 } );
92 If you want to pass in IO::Socket::SSL options:
94 my $stomp = Net::Stomp->new( {
96 hostname => 'localhost',
97 port => '61612',
98 ssl => 1,
99 ssl_options => { SSL_cipher_list => 'ALL:!EXPORT' },
100 } );
101 Failover
103 There is experiemental failover support in Net::Stomp. You can specify
105 failover in a similar maner to ActiveMQ
106 (http://activemq.apache.org/failover-transport-reference.html
107 <http://activemq.apache.org/failover-transport-reference.html>) for
108 similarity with Java configs or using a more natural method to perl of
109 passing in an array-of-hashrefs in the "hosts" parameter.
110 Currently when ever Net::Stomp connects or reconnects it will simply
112 try the next host in the list.
113 connect
115 This connects to the Stomp server. You may pass in a "login" and
116 "passcode" options.
117 You may also pass in 'client-id', which specifies the JMS Client ID
119 which is used in combination to the activemqq.subscriptionName to
120 denote a durable subscriber.
121 $stomp->connect( { login => 'hello', passcode => 'there' } );
123 send
125 This sends a message to a queue or topic. You must pass in a
126 destination and a body.
127 $stomp->send(
129 { destination => '/queue/foo', body => 'test message' } );
130 To send a BytesMessage, you should set the field 'bytes_message' to 1.
132 send_transactional
134 This sends a message in transactional mode and fails if the receipt of
135 the message is not acknowledged by the server:
136 $stomp->send_transactional(
138 { destination => '/queue/foo', body => 'test message' }
139 ) or die "Couldn't send the message!";
140 If using ActiveMQ, you might also want to make the message persistent:
142 $stomp->send_transactional(
144 { destination => '/queue/foo', body => 'test message', persistent => 'true' }
145 ) or die "Couldn't send the message!";
146 disconnect
148 This disconnects from the Stomp server:
149 $stomp->disconnect;
151 subscribe
153 This subscribes you to a queue or topic. You must pass in a
154 destination.
155 The acknowledge mode defaults to 'auto', which means that frames will
157 be considered delivered after they have been sent to a client. The
158 other option is 'client', which means that messages will only be
159 considered delivered after the client specifically acknowledges them
160 with an ACK frame.
161 Other options:
163 'selector': which specifies a JMS Selector using SQL 92 syntax as
165 specified in the JMS 1.1 specificiation. This allows a filter to be
166 applied to each message as part of the subscription.
167 'activemq.dispatchAsync': should messages be dispatched synchronously
169 or asynchronously from the producer thread for non-durable topics in
170 the broker. For fast consumers set this to false. For slow consumers
171 set it to true so that dispatching will not block fast consumers.
172 'activemq.exclusive': Would I like to be an Exclusive Consumer on a
174 queue.
175 'activemq.maximumPendingMessageLimit': For Slow Consumer Handlingon
177 non-durable topics by dropping old messages - we can set a maximum
178 pending limit which once a slow consumer backs up to this high water
179 mark we begin to discard old messages.
180 'activemq.noLocal': Specifies whether or not locally sent messages
182 should be ignored for subscriptions. Set to true to filter out locally
183 sent messages.
184 'activemq.prefetchSize': Specifies the maximum number of pending
186 messages that will be dispatched to the client. Once this maximum is
187 reached no more messages are dispatched until the client acknowledges a
188 message. Set to 1 for very fair distribution of messages across
189 consumers where processing messages can be slow.
190 'activemq.priority': Sets the priority of the consumer so that
192 dispatching can be weighted in priority order.
193 'activemq.retroactive': For non-durable topics do you wish this
195 subscription to the retroactive.
196 'activemq.subscriptionName': For durable topic subscriptions you must
198 specify the same clientId on the connection and subscriberName on the
199 subscribe.
200 $stomp->subscribe(
202 { destination => '/queue/foo',
203 'ack' => 'client',
204 'activemq.prefetchSize' => 1
205 }
206 );
207 unsubscribe
209 This unsubscribes you to a queue or topic. You must pass in a
210 destination:
211 $stomp->unsubcribe({ destination => '/queue/foo' });
213 receive_frame
215 This blocks and returns you the next Stomp frame.
216 my $frame = $stomp->receive_frame;
218 warn $frame->body; # do something here
219 The header bytes_message is 1 if the message was a BytesMessage.
221 By default this method will block until a frame can be returned. If you
223 wish to wait for a specified time pass a "timeout" argument:
224 # Wait half a second for a frame, else return undef
226 $stomp->receive_frame({ timeout => 0.5 })
227 can_read
229 This returns whether a frame is waiting to be read. Optionally takes a
230 timeout in seconds:
231 my $can_read = $stomp->can_read;
233 my $can_read = $stomp->can_read({ timeout => '0.1' });
234 ack
236 This acknowledges that you have received and processed a frame (if you
237 are using client acknowledgements):
238 $stomp->ack( { frame => $frame } );
240 send_frame
242 If this module does not provide enough help for sending frames, you may
243 construct your own frame and send it:
244 # write your own frame
246 my $frame = Net::Stomp::Frame->new(
247 { command => $command, headers => $conf, body => $body } );
248 $self->send_frame($frame);
249
251 Net::Stomp::Frame.
252
254 Leon Brocard <acme@astray.com>. Thom May <thom.may@betfair.com>. Ash
255 Berlin <ash_github@firemirror.com>.
256
258 Copyright (C) 2006-9, Leon Brocard Copyright (C) 2009, Thom May,
259 Betfair.com Copyright (C) 2010, Ash Berlin, Net-a-Porter.com
260 This module is free software; you can redistribute it or modify it
262 under the same terms as Perl itself.
263perl v5.12.1 2010-06-27 Net::Stomp(3)