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;
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". The "headers" must be a reference to a hash of header key/value
35 pairs.
36
38 This module provides the following methods:
39 check()
41 check that the frame is well-formed, see below for more information
42 header(NAME)
44 return the value associated with the given name in the header
45 debug([TAG])
47 if debugging is enabled, dump a frame object on STDERR; for the
48 body, at most $Net::STOMP::Client::Frame::DebugBodyLength bytes
49 will be printed
50
52 The "content-length" header is special because it is used to indicate
53 the length of the body but also the JMS type of the message in ActiveMQ
54 as per <http://activemq.apache.org/stomp.html>.
55 If you do not supply a "content-length" header, following the protocol
57 recommendations, a "content-length" header will be added if the frame
58 has a body.
59 If you do supply a numerical "content-length" header, it will be used
61 as is. Warning: this may give unexpected results if the supplied value
62 does not match the body length. Use only with caution!
63 Finally, if you supply an empty string as the "content-length" header,
65 it will not be sent, even if the frame has a body. This can be used to
66 mark a message as being a TextMessage for ActiveMQ. Here is an example
67 of this:
68 $stomp->send(
70 "destination" => "/queue/test",
71 "body" => "hello world!",
72 "content-length" => "",
73 );
74
76 The STOMP 1.0 specification does not define which encoding should be
77 used to serialize frames. So, by default, this module assumes that what
78 has been given by the user or by the server is a ready-to-use sequence
79 of bytes and it does not perform any further encoding or decoding.
80 However, for convenience, three global variables can be used to control
82 encoding/decoding.
83 If $Net::STOMP::Client::Frame::UTF8Header is set to true, the module
85 will use UTF-8 to encode/decode the header part of the frame.
86 The STOMP 1.1 specification states that UTF-8 encoding should always be
88 used for the header. So, for STOMP 1.1 connections,
89 $Net::STOMP::Client::Frame::UTF8Header defaults to true.
90 If $Net::STOMP::Client::Frame::BodyEncode is set to true, the module
92 will use the "content-type" header to decide when and how to
93 encode/decode the body part of the frame.
94 The STOMP 1.1 specification states that the "content-type" header
96 defines when and how the body is encoded/decoded. So, for STOMP 1.1
97 connections, $Net::STOMP::Client::Frame::BodyEncode defaults to true.
98 As a consequence, if you use STOMP 1.1 and supply an already encoded
99 body, you should set $Net::STOMP::Client::Frame::BodyEncode to false to
100 prevent double encoding.
101 If $Net::STOMP::Client::Frame::StrictEncode is true, all
103 encoding/decoding operations will be stricter and will report a fatal
104 error when given malformed input. This is done by using the
105 Encode::FB_CROAK flag instead of the default Encode::FB_DEFAULT.
106 N.B.: Perl's standard Encode module is used for all encoding/decoding
108 operations.
109
111 STOMP 1.0 has several ambiguities and this module does its best to work
112 "as expected" in these gray areas.
113 STOMP 1.1 is much better specified and this module should be fully
115 compliant with the STOMP 1.1 specification with two exceptions:
116 invalid encoding
118 by default, this module is permissive and allows malformed encoded
119 data (this is the same default as the Encode module itself); to be
120 strict, set $Net::STOMP::Client::Frame::StrictEncode to true (as
121 explained above)
122 header keys
124 by default, this module allows only "reasonable" header keys, made
125 of alphanumerical characters (along with "_", "-" and "."); to be
126 able to use any header key (like the specification allows), set
127 $Net::STOMP::Client::Frame::HeaderNameRE to "q/[\d\D]+/".
128 So, to sum up, here is what you can add to your code to get strict
130 STOMP 1.1 compliance:
131 $Net::STOMP::Client::Frame::StrictEncode = 1;
133 $Net::STOMP::Client::Frame::HeaderNameRE = q/[\d\D]+/;
134
136 Net::STOMP::Client calls the check() method for every frame about to be
137 sent and for every received frame.
138 The check() method verifies that the frame is well-formed. For
140 instance, it must contain a "command" made of uppercase letters.
141 The global variable $Net::STOMP::Client::Frame::CheckLevel controls the
143 amount of checking that is performed. The default value is 2.
144 0 nothing is checked
146 1
148 · the frame must have a good looking command
149 · the header keys must be good looking and their value must be
151 defined
152 2
154 · the level 1 checks are performed
155 · the frame must have a known command
157 · the presence/absence of the body is checked; for instance, body
159 is not expected for a "CONNECT" frame
160 · the presence of mandatory keys (e.g. "message-id" for a
162 "MESSAGE" frame) is checked
163 · for known header keys, their value must be good looking (e.g.
165 the "timestamp" value must be an integer)
166 3
168 · the level 2 checks are performed
169 · all header keys must be known/expected
171 A violation of any of these checks trigger an error in the check()
173 method.
174
176 Net::STOMP::Client::Debug, Encode.
177
179 Lionel Cons <http://cern.ch/lionel.cons>
180 Copyright CERN 2010-2011
182perl v5.12.3 2011-05-10 Net::STOMP::Client::Frame(3)