Net::STOMP::Client::FrUser3Contributed Perl DocumeNet::STOMP::Client::Frame(3)NAMENet::STOMP::Client::Frame - Frame support for Net::STOMP::Client
SYNOPSIS
use Net::STOMP::Client::Frameqw();
# create a connection frame
$frame = Net::STOMP::Client::Frame->new(
command => "CONNECT",
headers => {
login => "guest",
passcode => "guest",
},
);
# get the command
$cmd = $frame->command();
# set the body
$frame->body("...some data...");
# directly get a header field
$msgid = $frame->header("message-id");
DESCRIPTION
This module provides an object oriented interface to manipulate STOMP
frames.
A frame object has the following attributes: "command", "headers" and
"body_reference". The "headers" attribute must be a reference to a hash
of header key/value pairs. The body is usually manipulated by reference
to avoid string copies.
METHODS
This module provides the following methods:
new([OPTIONS])
return a new Net::STOMP::Client::Frame object (class method); the
options that can be given ("command", "headers", "body_reference"
and "body") match the accessors described below
command([STRING])
get/set the "command" attribute
headers([HASHREF])
get/set the "headers" attribute
body_reference([STRINGREF])
get/set the "body_reference" attribute
header(NAME[, VALUE])
get/set the value associated with the given name in the header; if
the given value is undefined, remove the named header (this is a
convenient wrapper around the headers() method)
body([STRING])
get/set the body as a string (this is a convenient wrapper around
the body_reference() method)
encode([OPTIONS])
encode the given frame and return a reference to a binary string
suitable to be written to a TCP stream (for instance); supported
options: "debug" (debugging flags as a string), "strict" (the
desired strictness, overriding $StrictEncode), "version" (the STOMP
protocol version to use)
check([OPTIONS])
this method is obsolete and should not be used anymore; it is left
here only to provide backward compatibility with Net::STOMP::Client
1.x
FUNCTIONS
This module provides the following functions (which are not exported):
decode(STRINGREF, [OPTIONS])
decode the given string reference and return a complete frame
object, if possible or false in case there is not enough data for a
complete frame; supported options: the same as encode() plus
parse()
parse(STRINGREF, [OPTIONS])
parse the given string reference and return true if a complete
frame is found or false otherwise; supported options: "state" (a
hash reference that holds the parsing state); see the "FRAME
PARSING" section for more information
VARIABLES
This module uses the following global variables (which are not
exported):
$Net::STOMP::Client::Frame::DebugBodyLength
the maximum number of bytes to dump when debugging message bodies
(default: 256)
$Net::STOMP::Client::Frame::StrictEncode
whether or not to perform strict character encoding/decoding
(default: false)
FRAME PARSING
The parse() function can be used to parse a frame without decoding it.
It takes as input a binary string reference (to avoid string copies)
and an optional state (a hash reference). It parses the string to find
out where the different parts of the frames are and it updates its
state (if given).
It returns false if the string does not hold a complete frame or a hash
reference if a complete frame is present. This hash is in fact the same
thing as the state and it contains the following keys:
before_len
the length of what is found before the frame (only frame EOL can
appear here)
command_idx, command_len, command_eol
the start position, length and length of the EOL of the command
header_idx, header_len, header_eol
the start position, length and length of the EOL of the header
body_idx, body_len
the start position and length of the body
after_idx, after_len
the length of what is found after the frame (only frame EOL can
appear here)
content_length
the value of the "content-length" header (if present)
total_len
the total length of the frame, including before and after parts
Here is how this could be used:
$data = "... read from socket or file ...";
$info = Net::STOMP::Client::Frame::parse(\$data);
if ($info) {
# extract interesting frame parts
$command = substr($data, $info->{command_idx}, $info->{command_len});
# remove the frame from the buffer
substr($data, 0, $info->{total_len}) = "";
}
CONTENT LENGTH
The "content-length" header is special because it is sometimes used to
indicate the length of the body but also the JMS type of the message in
ActiveMQ as per <http://activemq.apache.org/stomp.html>.
If you do not supply a "content-length" header, following the protocol
recommendations, a "content-length" header will be added if the frame
has a body.
If you do supply a numerical "content-length" header, it will be used
as is. Warning: this may give unexpected results if the supplied value
does not match the body length. Use only with caution!
Finally, if you supply an empty string as the "content-length" header,
it will not be sent, even if the frame has a body. This can be used to
mark a message as being a TextMessage for ActiveMQ. Here is an example
of this:
$stomp->send(
"destination" => "/queue/test",
"body" => "hello world!",
"content-length" => "",
);
ENCODING
The STOMP 1.0 specification does not define which encoding should be
used to serialize frames. So, by default, this module assumes that what
has been given by the user or by the server is a ready-to-use sequence
of bytes and it does not perform any further encoding or decoding.
If $Net::STOMP::Client::Frame::StrictEncode is true, all encoding and
decoding operations will be stricter and will report a fatal error when
given malformed input. This is done by using the Encode::FB_CROAK flag
instead of the default Encode::FB_DEFAULT.
N.B.: Perl's standard Encode module is used for all encoding/decoding
operations.
MESSAGING ABSTRACTION
If the Messaging::Message module is available, the following method and
function are available too:
messagify()
transform the frame into a Messaging::Message object (method)
demessagify(MESSAGE)
transform the given Messaging::Message object into a
Net::STOMP::Client::Frame object (function)
Here is how they could be used:
# frame to message
$frame = $stomp->wait_for_frames(timeout => 1);
if ($frame) {
$message = $frame->messagify();
...
}
# message to frame
$frame = Net::STOMP::Client::Frame::demessagify($message);
$stomp->send_frame($frame);
Note: in both cases, string copies are avoided so both objects will
share the same header hash and body string. Therefore modifying one may
also modify the other. Clone (copy) the objects if you do not want this
behavior.
COMPLIANCE
STOMP 1.0 has several ambiguities and this module does its best to work
"as expected" in these gray areas.
STOMP 1.1 and STOMP 1.2 are much better specified and this module
should be fully compliant with these STOMP specifications with only one
exception: by default, this module is permissive and allows malformed
encoded data (this is the same default as the Encode module itself); to
be more strict, set $Net::STOMP::Client::Frame::StrictEncode to true
(as explained above).
SEE ALSO
Encode, Messaging::Message, Net::STOMP::Client.
AUTHOR
Lionel Cons <http://cern.ch/lionel.cons>
Copyright CERN 2010-2012
perl v5.14.3 2012-12-14 Net::STOMP::Client::Frame(3)
