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 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 (read only) 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 end of a frame 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" => "",
);

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.

AUTHOR

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