README
1Net-STOMP-Client
2
3This module provides an object oriented client interface to interact
4with servers supporting STOMP (Streaming Text Orientated Messaging
5Protocol). It supports the major features of messaging brokers: SSL,
6asynchronous I/O, receipts and transactions.
7
8Note: This module has been initially released on CPAN as Net::STOMP
9but has later been renamed to Net::STOMP::Client to avoid a naming
10conflict.
11
12INSTALLATION
13
14To install this module, run the following commands:
15
16 perl Makefile.PL
17 make
18 make test
19 make install
20
21To test this module with a STOMP broker, see t/2broker.t.
22
23In addition to the mandatory modules listed in Makefile.PL, the
24following optional modules do bring extra functionality:
25
26 Authen::Credential - allows easy authentication support
27 IO::Socket::SSL - allows using STOMP over SSL
28 Messaging::Message - allows frame <-> message conversions
29
30SUPPORT AND DOCUMENTATION
31
32After installing, you can find documentation for this module with the
33perldoc command.
34
35 perldoc Net::STOMP::Client
36 perldoc Net::STOMP::Client::Auth
37 perldoc Net::STOMP::Client::Connection
38 perldoc Net::STOMP::Client::Frame
39 perldoc Net::STOMP::Client::HeartBeat
40 perldoc Net::STOMP::Client::IO
41 perldoc Net::STOMP::Client::Peer
42 perldoc Net::STOMP::Client::Receipt
43 perldoc Net::STOMP::Client::Version
44
45You can find some examples in the eg directory and a detailed tutorial:
46
47 perldoc Net::STOMP::Client::Tutorial
48
49LICENSE AND COPYRIGHT
50
51Copyright (C) CERN 2010-2017
52
53This program is free software; you can redistribute it and/or modify it
54under the terms of either: the GNU General Public License as published
55by the Free Software Foundation; or the Artistic License.
56
57See http://dev.perl.org/licenses/ for more information.
58
README.2.x
1 Here are some notes on how to upgrade from Net::STOMP::Client 1.x to 2.x.
2
3 Net::STOMP::Client 2.0 is mostly backward compatible with versions 1.x
4 but some changes might be needed for code using some specific features.
5 These are documented below.
6
7
8 Compatible Changes
9 ==================
10
11 The following things have been changed in Net::STOMP::Client but version 2.0
12 provides backward compatibility for them. However, since this compatibility
13 will disappear at some point in future 2.x versions, it is recommended to
14 change your code after you have upgraded to Net::STOMP::Client 2.0.
15
16 Frame Checking
17 --------------
18
19 The frame checking code in Net::STOMP::Client::Frame has been removed. The
20 check() method is currently still present but it does nothing. You should
21 stop using it.
22
23 If needed, this functionality may come back as a separate optional module.
24
25 demessagify()
26 -------------
27
28 The demessagify() class method is now a function. You should replace calls
29 like:
30
31 $frame = Net::STOMP::Client::Frame->demessagify($message);
32
33 by:
34
35 $frame = Net::STOMP::Client::Frame::demessagify($message);
36
37 Timeout parameter
38 -----------------
39
40 All the methods from the low-level API that had a timeout parameter:
41
42 $stomp->send_frame(FRAME, TIMEOUT)
43 $stomp->send_data(TIMEOUT)
44 $stomp->receive_frame(TIMEOUT)
45 $stomp->receive_data(TIMEOUT)
46
47 now instead have keyed options:
48
49 $stomp->send_frame(FRAME, [OPTIONS])
50 $stomp->send_data([OPTIONS])
51 $stomp->receive_frame([OPTIONS])
52 $stomp->receive_data([OPTIONS])
53
54 If you did not supply the timeout parameter (i.e. relying on it being undef),
55 you do not need to change anything. Otherwise, you should replace calls like:
56
57 $stomp->send_frame($frame, $timeout);
58
59 by:
60
61 $stomp->send_frame($frame, timeout => $timeout);
62
63
64 Incompatible Changes
65 ====================
66
67 The following things have been changed and, if you use these features, you
68 must change your code before upgrading to Net::STOMP::Client 2.0.
69
70 Error Handling
71 --------------
72
73 Net::STOMP::Client 1.x used its own module to handle errors. Now, the more
74 standard No::Worries::Die module is used.
75
76 If you never modified $Net::STOMP::Client::Error::Die then nothing changes:
77 a fatal error will be reported by Perl's die().
78
79 Otherwise, you will have to use eval() and replace code like:
80
81 local $Net::STOMP::Client::Error::Die = 0;
82 $success = ... some Net::STOMP::Client code ...
83 unless ($success) {
84 ... error handling here ...
85 }
86
87 by:
88
89 eval { ... some Net::STOMP::Client code ... };
90 if ($@) {
91 ... error handling here ...
92 }
93
94 Debugging
95 ---------
96
97 Net::STOMP::Client 1.x used its own module to handle debugging. Now, the
98 more standard No::Worries::Log module is used.
99
100 If you never modified $Net::STOMP::Client::Debug::Flags then nothing
101 changes: debugging is still disabled by default.
102
103 Otherwise, you will have to enable debugging with something like:
104
105 log_filter("debug");
106
107 or, to enable logging only from Net::STOMP::Client modules:
108
109 log_filter("debug caller=~^Net::STOMP::Client");
110
111 See the No::Worries::Log documentation for more information.
112
113 Net::STOMP::Client 1.x used a bit-field to select what to debug. Version
114 2.0 uses a string, here is the mapping:
115
116 Flags String
117 ----- ------
118 API=1 api
119 FRAME=2 command
120 HEADER=4 header
121 BODY=8 body
122 IO=16 io
123 -1 all
124
125 See the DEBUGGING section of the Net::STOMP::Client documentation for
126 more information.
127