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