NAME

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

SYNOPSIS

use Net::STOMP::Client::Frame;

# 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...");

DESCRIPTION

This module provides an object oriented interface to manipulate STOMP frames.

A frame object has the following attributes: command, headers and body. The headers must be a reference to a hash of header key/value pairs.

The check() method verifies that the frame is well-formed. For instance, it must contain a command made of uppercase letters. See below for more information.

The header() method can be used to directly access (in read-only mode) a given header key. For instance:

$msgid = $frame->header("message-id");

The debug() method can be used to dump a frame object on STDERR. So far, this excludes the frame body.

The decode() function and the encode() method are used internally by Net::STOMP::Client and are not expected to be used elsewhere.

CONTENT LENGTH

The "content-length" header is special because it is 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" => "",
);

STRING 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.

However, for convenience, three global variables can be used to automatically perform some encoding/decoding.

If $Net::STOMP::Client::Frame::UTF8Header is true, the module will use UTF-8 to encode/decode the header part of the frame.

If $Net::STOMP::Client::Frame::UTF8Body is true, the module will:

. encode user-supplied body if the UTF-8 Flag is true, as per Encode::is_utf8()

. decode server-supplied body if the received bytes string is a valid UTF-8 encoded string

Note: in case the body is encoded, the "content-length" header may not match the body string length.

If $Net::STOMP::Client::Frame::UTF8Strict is true, all encoding/decoding operations will be stricter and will report a fatal error when given malformed input.

Perl's standard Encode module is used for all encoding/decoding operations.

FRAME CHECKING

Net::STOMP::Client calls the check() method for every frame about to be sent and for every received frame.

The global variable $Net::STOMP::Client::Frame::CheckLevel controls the amount of checking that is performed.

0

nothing is checked

1

• the frame must have a good looking command

• the header keys must be good looking and their value must be defined

2 (default)

• the level 1 checks are performed

• the frame must have a known command

• for known header keys, their value must be good looking (e.g. the "timestamp" value must be an integer)

• the presence of mandatory keys (e.g. "session" for a "CONNECTED" frame) is checked

• the absence of the body (e.g. no body for a "CONNECT" frame) is checked

3

• the level 2 checks are performed

• all header keys must be known/expected

A violation of any of these checks trigger an error in the check() method.

SEE ALSO

Encode.

AUTHOR

Lionel Cons http://cern.ch/lionel.cons

cpanm Net::STOMP::Client

perl -MCPAN -e shell
install Net::STOMP::Client