/ 
XAS-0.15
River stage one • 6 direct dependents • 6 total dependents
/ XAS::Lib::Stomp::Utils

NAME

XAS::Lib::Stomp::Utils - STOMP protocol utilities for clients

SYNOPSIS

This module uses XAS::Lib::Stomp::Frame to create STOMP frames.

use XAS::Lib::Stomp::Utils;

my $stomp = XAS::Lib::Stomp::Utils->new();
my $frame = $stomp->connect(
    -login    => 'test', 
    -passcode => 'test'
);

put($frame->to_string);

DESCRIPTION

This module is an easy way to create STOMP frames without worrying about the various differences between the protocol versions.

METHODS

new

This method initializes the base object. It takes the following parameters:

connect

This method creates a "CONNECT" frame. This frame is used to initiate a session with a STOMP server. On STOMP v1.1 and later targets the following headers are automatically set:

host
heart-beat
accept-version

Unless otherwise specified, they will be the defaults. This method takes the following parameters:

-login

An optional login name to be used on the STOMP server.

-passcode

An optional password for the login name on the STOMP server.

-host

An optional virtual host name to connect to on STOMP v1.1 and later servers. Defaults to 'localhost'.

-heart_beat

An optional heart beat request for STOMP v1.1 and later servers. The default is to turn them off.

-acceptable

An optional list of protocol versions that are acceptable to this client for STOMP v1.1 and later clients. The default is '1.0,1.1,1.2'.

-prefetch

This sets the optional header 'prefetch-size' for RabbitMQ or other servers that support this extension.

stomp

This method creates a "STOMP" frame, this works the same as connect(), but only works for STOMP v1.1 and later targets. Please see the documentation for connect().

disconnect

This method creates a "DISCONNECT" frame. This frame is used to signal the server that you no longer wish to communicate with it. This method takes the following parameters:

-receipt

An optional receipt that will be returned by the server.

subscribe

This method create a "SUBSCRIBE" frame. This frame is used to notify the server which queues you want to listen too. The naming of queues is left up to the server implementation. This method takes the following parameters:

-destination

The name of the queue you wish to subscribe too. Naming convention is server dependent.

-subscription

A mandatory subscription id for usage on STOMP v1.1 and later targets. It has no meaning for STOMP v1.0 servers.

-ack

The type of acknowledgement you would like to receive when messages are sent to a queue. It defaults to 'auto'. It understands 'auto', 'client' and 'client-individual'. Please refer to the STOMP protocol reference for what this means.

-receipt

An optional receipt that will be returned by the server.

unsubscribe

This method creates an "UNSUBSCRIBE" frame. This frame is used to notify the server that you don't want to subscribe to a queue anymore. Subsequently any messages left on that queue will no longer be sent to your client.

-destination

The optional name of the queue that you subscribed too. STOMP v1.0 targets need a queue name and/or a subscription id to unsubscribe. This is optional on v1.1 and later targets.

-subscription

The id of the subscription, this should be the same as the one used with subscribe(). This is optional on STOMP v1.0 servers and mandatory on v1.1 and later targets.

-receipt

An optional receipt that will be returned by the server.

begin

This method creates a "BEGIN" frame. This frame signals the server that a transaction is beginning. A transaction is either ended by a "COMMIT" frame or an "ABORT" frame. Any other frame that is sent must have a transaction id associated with them. This method takes the following parameters:

-transaction

The mandatory id for the transaction.

-receipt

An optional receipt that will be returned by the server.

commit

This method creates a "COMMIT" frame. This frame signals the end of a transaction. This method takes the following parameters:

-transaction

The mandatory transaction id from begin().

-receipt

An optional receipt that will be returned by the server.

abort

This method creates an "ABORT" frame. This frame is used to signal the server that the current transaction is to be aborted.

This method takes the following parameters:

-transaction

The mandatory transaction id from begin().

-receipt

An optional receipt that will be returned by the server.

send

This method creates a "SEND" frame. This frame is the basis of communication over your queues to the server. This method takes the following parameters:

-destination

The name of the queue to send the message too.

-message

The message to be sent. No attempt is made to serializes the message.

-transaction

An optional transaction number. This should be the same as for begin().

-length

An optional length for the message. If one is not specified a 'content-length' header will be auto generated.

-type

An optional MIME type for the message. If one is not specified, 'text/plain' will be used. This only has meaning for STOMP v1.1 and later targets.

-persistent

An optional header for indicating that this frame should be 'persisted' by the server. What this means, is highly server specific.

-receipt

An optional receipt that will be returned by the server.

ack

This method creates an "ACK" frame. This frame is used to tell the server that the message was successfully received. This method takes the following parameters:

-message_id

The id of the message that is being acked.

-subscription

This should match the id from the subscribe() method. This has meaning for STOMP v1.1 and later targets.

-transaction

The transaction id if this ack is part of a transaction.

-receipt

An optional receipt that will be returned by the server.

nack

This method creates a "NACK" frame. It notifies the server that the message was rejected. It has meaning on STOMP v1.1 and later targets. This method takes the following parameters:

-message_id

The id of the message that is being nacked.

-subscription

This should match the id from the subscribe() method. This has meaning for STOMP v1.1 and later targets.

-transaction

The transaction id if this nack is part of a transaction.

-receipt

An optional receipt that will be returned by the server.

noop

This method creates a "NOOP" frame. It has meaning on STOMP v1.1 and later targets.

SEE ALSO

Net::Stomp
Net::Stomp::Frame
XAS

For more information on the STOMP protocol, please refer to: http://stomp.github.io/ .

AUTHOR

Kevin L. Esteb, <kevin@kesteb.us>

COPYRIGHT AND LICENSE

Copyright (C) 2014 Kevin L. Esteb

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0. For details, see the full text of the license at http://www.perlfoundation.org/artistic_license_2_0.