1Net::STOMP::Client::FraUmsee(r3)Contributed Perl DocumenNteatt:i:oSnTOMP::Client::Frame(3)
2
3
4

NAME

6       Net::STOMP::Client::Frame - Frame support for Net::STOMP::Client
7

SYNOPSIS

9         use Net::STOMP::Client::Frame qw();
10
11         # 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
20         # get the command
21         $cmd = $frame->command();
22
23         # set the body
24         $frame->body("...some data...");
25
26         # directly get a header field
27         $msgid = $frame->header("message-id");
28

DESCRIPTION

30       This module provides an object oriented interface to manipulate STOMP
31       frames.
32
33       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

METHODS

39       This module provides the following methods:
40
41       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
46       command([STRING])
47           get/set the "command" attribute
48
49       headers([HASHREF])
50           get/set the "headers" attribute
51
52       body_reference([STRINGREF])
53           get/set the "body_reference" attribute
54
55       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
60       body([STRING])
61           get/set the body as a string (this is a convenient wrapper around
62           the body_reference() method)
63
64       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
71       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

FUNCTIONS

77       This module provides the following functions (which are not exported):
78
79       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
85       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

VARIABLES

92       This module uses the following global variables (which are not
93       exported):
94
95       $Net::STOMP::Client::Frame::DebugBodyLength
96           the maximum number of bytes to dump when debugging message bodies
97           (default: 256)
98
99       $Net::STOMP::Client::Frame::StrictEncode
100           whether or not to perform strict character encoding/decoding
101           (default: false)
102

FRAME PARSING

104       The parse() function can be used to parse a frame without decoding it.
105
106       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
111       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
115       before_len
116           the length of what is found before the frame (only frame EOL can
117           appear here)
118
119       command_idx, command_len, command_eol
120           the start position, length and length of the EOL of the command
121
122       header_idx, header_len, header_eol
123           the start position, length and length of the EOL of the header
124
125       body_idx, body_len
126           the start position and length of the body
127
128       after_idx, after_len
129           the length of what is found after the frame (only frame EOL can
130           appear here)
131
132       content_length
133           the value of the "content-length" header (if present)
134
135       total_len
136           the total length of the frame, including before and after parts
137
138       Here is how this could be used:
139
140         $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

CONTENT LENGTH

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
154       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
158       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
162       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
167         $stomp->send(
168             "destination"    => "/queue/test",
169             "body"           => "hello world!",
170             "content-length" => "",
171         );
172

ENCODING

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
179       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
184       N.B.: Perl's standard Encode module is used for all encoding/decoding
185       operations.
186

MESSAGING ABSTRACTION

188       If the Messaging::Message module is available, the following method and
189       function are available too:
190
191       messagify()
192           transform the frame into a Messaging::Message object (method)
193
194       demessagify(MESSAGE)
195           transform the given Messaging::Message object into a
196           Net::STOMP::Client::Frame object (function)
197
198       Here is how they could be used:
199
200         # frame to message
201         $frame = $stomp->wait_for_frames(timeout => 1);
202         if ($frame) {
203             $message = $frame->messagify();
204             ...
205         }
206
207         # message to frame
208         $frame = Net::STOMP::Client::Frame::demessagify($message);
209         $stomp->send_frame($frame);
210
211       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

COMPLIANCE

217       STOMP 1.0 has several ambiguities and this module does its best to work
218       "as expected" in these gray areas.
219
220       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

SEE ALSO

228       Encode, Messaging::Message, Net::STOMP::Client.
229

AUTHOR

231       Lionel Cons <http://cern.ch/lionel.cons>
232
233       Copyright (C) CERN 2010-2021
234
235
236
237perl v5.38.0                      2023-07-21      Net::STOMP::Client::Frame(3)
Impressum