GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  NET::STOMP::CLIENT::FRAME (3)

.ds Aq ’

NAME

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

CONTENTS

SYNOPSIS



  use Net::STOMP::Client::Frame qw();

  # 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 <B>notB> 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 <B>notB> 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 (C) CERN 2010-2013

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 NET::STOMP::CLIENT::FRAME (3) 2013-11-28

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.