1Net::STOMP::Client::FraUmsee(r3)Contributed Perl DocumenNteatt:i:oSnTOMP::Client::Frame(3)
2
6 Net::STOMP::Client::Frame - Frame support for Net::STOMP::Client
7
9 use Net::STOMP::Client::Frame qw();
10 # create a connection frame
12 $frame = Net::STOMP::Client::Frame->new(
13 command => "CONNECT",
14 headers => {
15 login => "guest",
16 passcode => "guest",
17 },
18 );
19 # get the command
21 $cmd = $frame->command();
22 # set the body
24 $frame->body("...some data...");
25 # directly get a header field
27 $msgid = $frame->header("message-id");
28
30 This module provides an object oriented interface to manipulate STOMP
31 frames.
32 A frame object has the following attributes: "command", "headers" and
34 "body_reference". The "headers" attribute must be a reference to a hash
35 of header key/value pairs. The body is usually manipulated by reference
36 to avoid string copies.
37
39 This module provides the following methods:
40 new([OPTIONS])
42 return a new Net::STOMP::Client::Frame object (class method); the
43 options that can be given ("command", "headers", "body_reference"
44 and "body") match the accessors described below
45 command([STRING])
47 get/set the "command" attribute
48 headers([HASHREF])
50 get/set the "headers" attribute
51 body_reference([STRINGREF])
53 get/set the "body_reference" attribute
54 header(NAME[, VALUE])
56 get/set the value associated with the given name in the header; if
57 the given value is undefined, remove the named header (this is a
58 convenient wrapper around the headers() method)
59 body([STRING])
61 get/set the body as a string (this is a convenient wrapper around
62 the body_reference() method)
63 encode([OPTIONS])
65 encode the given frame and return a reference to a binary string
66 suitable to be written to a TCP stream (for instance); supported
67 options: "debug" (debugging flags as a string), "strict" (the
68 desired strictness, overriding $StrictEncode), "version" (the STOMP
69 protocol version to use)
70 check([OPTIONS])
72 this method is obsolete and should not be used anymore; it is left
73 here only to provide backward compatibility with Net::STOMP::Client
74 1.x
75
77 This module provides the following functions (which are not exported):
78 decode(STRINGREF, [OPTIONS])
80 decode the given string reference and return a complete frame
81 object, if possible or false in case there is not enough data for a
82 complete frame; supported options: the same as encode() plus
83 parse()
84 parse(STRINGREF, [OPTIONS])
86 parse the given string reference and return true if a complete
87 frame is found or false otherwise; supported options: "state" (a
88 hash reference that holds the parsing state); see the "FRAME
89 PARSING" section for more information
90
92 This module uses the following global variables (which are not
93 exported):
94 $Net::STOMP::Client::Frame::DebugBodyLength
96 the maximum number of bytes to dump when debugging message bodies
97 (default: 256)
98 $Net::STOMP::Client::Frame::StrictEncode
100 whether or not to perform strict character encoding/decoding
101 (default: false)
102
104 The parse() function can be used to parse a frame without decoding it.
105 It takes as input a binary string reference (to avoid string copies)
107 and an optional state (a hash reference). It parses the string to find
108 out where the different parts of the frames are and it updates its
109 state (if given).
110 It returns false if the string does not hold a complete frame or a hash
112 reference if a complete frame is present. This hash is in fact the same
113 thing as the state and it contains the following keys:
114 before_len
116 the length of what is found before the frame (only frame EOL can
117 appear here)
118 command_idx, command_len, command_eol
120 the start position, length and length of the EOL of the command
121 header_idx, header_len, header_eol
123 the start position, length and length of the EOL of the header
124 body_idx, body_len
126 the start position and length of the body
127 after_idx, after_len
129 the length of what is found after the frame (only frame EOL can
130 appear here)
131 content_length
133 the value of the "content-length" header (if present)
134 total_len
136 the total length of the frame, including before and after parts
137 Here is how this could be used:
139 $data = "... read from socket or file ...";
141 $info = Net::STOMP::Client::Frame::parse(\$data);
142 if ($info) {
143 # extract interesting frame parts
144 $command = substr($data, $info->{command_idx}, $info->{command_len});
145 # remove the frame from the buffer
146 substr($data, 0, $info->{total_len}) = "";
147 }
148
150 The "content-length" header is special because it is sometimes used to
151 indicate the length of the body but also the JMS type of the message in
152 ActiveMQ as per <http://activemq.apache.org/stomp.html>.
153 If you do not supply a "content-length" header, following the protocol
155 recommendations, a "content-length" header will be added if the frame
156 has a body.
157 If you do supply a numerical "content-length" header, it will be used
159 as is. Warning: this may give unexpected results if the supplied value
160 does not match the body length. Use only with caution!
161 Finally, if you supply an empty string as the "content-length" header,
163 it will not be sent, even if the frame has a body. This can be used to
164 mark a message as being a TextMessage for ActiveMQ. Here is an example
165 of this:
166 $stomp->send(
168 "destination" => "/queue/test",
169 "body" => "hello world!",
170 "content-length" => "",
171 );
172
174 The STOMP 1.0 specification does not define which encoding should be
175 used to serialize frames. So, by default, this module assumes that what
176 has been given by the user or by the server is a ready-to-use sequence
177 of bytes and it does not perform any further encoding or decoding.
178 If $Net::STOMP::Client::Frame::StrictEncode is true, all encoding and
180 decoding operations will be stricter and will report a fatal error when
181 given malformed input. This is done by using the Encode::FB_CROAK flag
182 instead of the default Encode::FB_DEFAULT.
183 N.B.: Perl's standard Encode module is used for all encoding/decoding
185 operations.
186
188 If the Messaging::Message module is available, the following method and
189 function are available too:
190 messagify()
192 transform the frame into a Messaging::Message object (method)
193 demessagify(MESSAGE)
195 transform the given Messaging::Message object into a
196 Net::STOMP::Client::Frame object (function)
197 Here is how they could be used:
199 # frame to message
201 $frame = $stomp->wait_for_frames(timeout => 1);
202 if ($frame) {
203 $message = $frame->messagify();
204 ...
205 }
206 # message to frame
208 $frame = Net::STOMP::Client::Frame::demessagify($message);
209 $stomp->send_frame($frame);
210 Note: in both cases, string copies are avoided so both objects will
212 share the same header hash and body string. Therefore modifying one may
213 also modify the other. Clone (copy) the objects if you do not want this
214 behavior.
215
217 STOMP 1.0 has several ambiguities and this module does its best to work
218 "as expected" in these gray areas.
219 STOMP 1.1 and STOMP 1.2 are much better specified and this module
221 should be fully compliant with these STOMP specifications with only one
222 exception: by default, this module is permissive and allows malformed
223 encoded data (this is the same default as the Encode module itself); to
224 be more strict, set $Net::STOMP::Client::Frame::StrictEncode to true
225 (as explained above).
226
228 Encode, Messaging::Message, Net::STOMP::Client.
229
231 Lionel Cons <http://cern.ch/lionel.cons>
232 Copyright (C) CERN 2010-2021
234perl v5.36.0 2023-01-20 Net::STOMP::Client::Frame(3)