README
1NAME
2 Net::Stomp - A Streaming Text Orientated Messaging Protocol Client
3
4SYNOPSIS
5 # send a message to the queue 'foo'
6 use Net::Stomp;
7 my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );
8 $stomp->connect( { login => 'hello', passcode => 'there' } );
9 $stomp->send(
10 { destination => '/queue/foo', body => 'test message' } );
11 $stomp->disconnect;
12
13 # subscribe to messages from the queue 'foo'
14 use Net::Stomp;
15 my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );
16 $stomp->connect( { login => 'hello', passcode => 'there' } );
17 $stomp->subscribe(
18 { destination => '/queue/foo',
19 'ack' => 'client',
20 'activemq.prefetchSize' => 1
21 }
22 );
23 while (1) {
24 my $frame = $stomp->receive_frame;
25 warn $frame->body; # do something here
26 $stomp->ack( { frame => $frame } );
27 }
28 $stomp->disconnect;
29
30 # write your own frame
31 my $frame = Net::Stomp::Frame->new(
32 { command => $command, headers => $conf, body => $body } );
33 $self->send_frame($frame);
34
35DESCRIPTION
36 This module allows you to write a Stomp client. Stomp is the Streaming
37 Text Orientated Messaging Protocol (or the Protocol Briefly Known as
38 TTMP and Represented by the symbol :ttmp). It's a simple and easy to
39 implement protocol for working with Message Orientated Middleware from
40 any language. Net::Stomp is useful for talking to Apache ActiveMQ, an
41 open source (Apache 2.0 licensed) Java Message Service 1.1 (JMS) message
42 broker packed with many enterprise features.
43
44 A Stomp frame consists of a command, a series of headers and a body -
45 see Net::Stomp::Frame for more details.
46
47 For details on the protocol see <http://stomp.codehaus.org/Protocol>.
48
49 To enable the ActiveMQ Broker for Stomp add the following to the
50 activemq.xml configuration inside the <transportConnectors> section:
51
52 <transportConnector name="stomp" uri="stomp://localhost:61613"/>
53
54 To enable the ActiveMQ Broker for Stomp and SSL add the following inside
55 the <transportConnectors> section:
56
57 <transportConnector name="stomp+ssl" uri="stomp+ssl://localhost:61612"/>
58
59 For details on Stomp in ActiveMQ See
60 <http://activemq.apache.org/stomp.html>.
61
62METHODS
63 new
64 The constructor creates a new object. You must pass in a hostname and a
65 port:
66
67 my $stomp = Net::Stomp->new( { hostname => 'localhost', port => '61613' } );
68
69 If you want to use SSL, make sure you have IO::Socket::SSL and pass in
70 the SSL flag:
71
72 my $stomp = Net::Stomp->new( {
73 hostname => 'localhost',
74 port => '61612',
75 ssl => 1,
76 } );
77
78 If you want to pass in IO::Socket::SSL options:
79
80 my $stomp = Net::Stomp->new( {
81 hostname => 'localhost',
82 port => '61612',
83 ssl => 1,
84 ssl_options => { SSL_cipher_list => 'ALL:!EXPORT' },
85 } );
86
87 connect
88 This connects to the Stomp server. You must pass in a login and
89 passcode.
90
91 You may pass in 'client-id', which specifies the JMS Client ID which is
92 used in combination to the activemqq.subscriptionName to denote a
93 durable subscriber.
94
95 $stomp->connect( { login => 'hello', passcode => 'there' } );
96
97 send
98 This sends a message to a queue or topic. You must pass in a destination
99 and a body.
100
101 $stomp->send(
102 { destination => '/queue/foo', body => 'test message' } );
103
104 To send a BytesMessage, you should set the field 'bytes_message' to 1.
105
106 send_transactional
107 This sends a message in transactional mode and fails if the receipt of
108 the message is not acknowledged by the server:
109
110 $stomp->send_transactional(
111 { destination => '/queue/foo', body => 'test message' }
112 ) or die "Couldn't send the message!";
113
114 If using ActiveMQ, you might also want to make the message persistent:
115
116 $stomp->send_transactional(
117 { destination => '/queue/foo', body => 'test message', persistent => 'true' }
118 ) or die "Couldn't send the message!";
119
120 disconnect
121 This disconnects from the Stomp server:
122
123 $stomp->disconnect;
124
125 subscribe
126 This subscribes you to a queue or topic. You must pass in a destination.
127
128 The acknowledge mode defaults to 'auto', which means that frames will be
129 considered delivered after they have been sent to a client. The other
130 option is 'client', which means that messages will only be considered
131 delivered after the client specifically acknowledges them with an ACK
132 frame.
133
134 Other options:
135
136 'selector': which specifies a JMS Selector using SQL 92 syntax as
137 specified in the JMS 1.1 specificiation. This allows a filter to be
138 applied to each message as part of the subscription.
139
140 'activemq.dispatchAsync': should messages be dispatched synchronously or
141 asynchronously from the producer thread for non-durable topics in the
142 broker. For fast consumers set this to false. For slow consumers set it
143 to true so that dispatching will not block fast consumers.
144
145 'activemq.exclusive': Would I like to be an Exclusive Consumer on a
146 queue.
147
148 'activemq.maximumPendingMessageLimit': For Slow Consumer Handlingon
149 non-durable topics by dropping old messages - we can set a maximum
150 pending limit which once a slow consumer backs up to this high water
151 mark we begin to discard old messages.
152
153 'activemq.noLocal': Specifies whether or not locally sent messages
154 should be ignored for subscriptions. Set to true to filter out locally
155 sent messages.
156
157 'activemq.prefetchSize': Specifies the maximum number of pending
158 messages that will be dispatched to the client. Once this maximum is
159 reached no more messages are dispatched until the client acknowledges a
160 message. Set to 1 for very fair distribution of messages across
161 consumers where processing messages can be slow.
162
163 'activemq.priority': Sets the priority of the consumer so that
164 dispatching can be weighted in priority order.
165
166 'activemq.retroactive': For non-durable topics do you wish this
167 subscription to the retroactive.
168
169 'activemq.subscriptionName': For durable topic subscriptions you must
170 specify the same clientId on the connection and subscriberName on the
171 subscribe.
172
173 $stomp->subscribe(
174 { destination => '/queue/foo',
175 'ack' => 'client',
176 'activemq.prefetchSize' => 1
177 }
178 );
179
180 unsubscribe
181 This unsubscribes you to a queue or topic. You must pass in a
182 destination:
183
184 $stomp->unsubcribe({ destination => '/queue/foo' });
185
186 receive_frame
187 This blocks and returns you the next Stomp frame.
188
189 my $frame = $stomp->receive_frame;
190 warn $frame->body; # do something here
191
192 The header bytes_message is 1 if the message was a BytesMessage.
193
194 can_read
195 This returns whether a frame is waiting to be read. Optionally takes a
196 timeout in seconds:
197
198 my $can_read = $stomp->can_read;
199 my $can_read = $stomp->can_read({ timeout => '0.1' });
200
201 ack
202 This acknowledges that you have received and processed a frame (if you
203 are using client acknowledgements):
204
205 $stomp->ack( { frame => $frame } );
206
207 nack
208 This informs the remote end that you have been unable to process a
209 received frame (if you are using client acknowledgements)
210 (See individual stomp server documentation for information about
211 additional fields that can be passed to alter NACK behavior):
212
213 $stomp->nack( { frame => $frame } );
214
215 send_frame
216 If this module does not provide enough help for sending frames, you may
217 construct your own frame and send it:
218
219 # write your own frame
220 my $frame = Net::Stomp::Frame->new(
221 { command => $command, headers => $conf, body => $body } );
222 $self->send_frame($frame);
223
224SEE ALSO
225 Net::Stomp::Frame.
226
227AUTHOR
228 Leon Brocard <acme@astray.com>.
229
230COPYRIGHT
231 Copyright (C) 2006-9, Leon Brocard
232
233 This module is free software; you can redistribute it or modify it under
234 the same terms as Perl itself.
235
236