NAME

Spread::Messaging::Transport - A Perl extension to the Spread Group Communications toolkit

SYNOPSIS

This module attempts to provide a simple and easy to use interface to the Spread Group Communications toolkit. It is a thin, object oriented layer over the toolkits Spread.pm.

DESCRIPTION

Your application could be as simple as this, to receive messages from a Spread network.

use Spread::Messaging::Transport;

$spread = Spread::Messaging::Transport->new();
$spread->join_group("test");

for (;;) {

    if ($spread->poll()) {

       my ($service_type, $sender, $groups, 
           $msg_type, $endian, $message) = $spread->recv();

       do_something($service_type, $sender, $groups, 
                    $msg_type, $endian, $message);

    }

    sleep(1);

}

Or, your application could be as simple as this, to send messages over a Spread network.

use Spread::Messaging::Transport;

$spread = Spread::Messaging::Transport->new();
$spread->join_group("test");

for (;;) {

    $buffer = readline();
    $spread->send("test", $buffer, 0);

}

But of course, this is never the case. This module will allow you to build your application as you see fit. All errors are thrown as a Spread::Messaging::Exception object using Exception::Class as the base class. No structure is enforced upon the messages being sent. This module is designed for maximum flexibility.

METHODS

new

This method inializes the object. Reasonable defaults are provided during this initializaion. By default, your program will connect to a Spread server on port 4803, on host "localhost", with a timeout of 5 seconds, along with a self generated private name, using a message type of "SAFE_MESS". To override these defaults you can use the following named parameters.

-port

This allows you to indicate which port number to use.

-host

This allows you to choose which host the Spread server is located on.

-timeout

This allows you to select a timeout.

-service_type

This allows you to choose a differant service type. The following types are valid:

UNRELIABLE_MESS
RELIABLE_MESS
FIFO_MESS
CAUSAL_MESS
AGREED_MESS
SAFE_MESS

Please see the Spread documentation for the meaning of these service types.

-private_name

This allows you to choose a specifc private name for your private mailbox. This name can be used for unicast messages.

Example

$spread = Spread::Messaging::Transport->new(
     -port => "8000",
     -timeout => "10",
     -host => "spread.example.com",
     -private_name => "mymailbox"
);

connect

This method allows you to connect to a Spread server. It is useful if you have disconnected from your current server. You may also use this method to reconnect to another Spread server. It does not create a new object.

Examples:

$spread->connect();

or

$spread->disconnect();
$spread->host("spread.example.com");
$spread->connect();

disconnect

This method will disconnect from your current Spread server. It does not destroy the spread object.

Example

$spread->disconnect();

poll

This methed allows you to check for pending messages. The number of message bytes is returned, when messages are pending.

Example

$size = $spread->poll();
do_something() if $size;

join_group

This allows you to join one or more Spread groups. To receive any multicast messages you need to join a group. The group may be a comma delimted list of names.

Example

$spread->join_group("test1,test2");

leave_group

This allows you to leave a Spread group. Once you leave a group, you will stop receiving any multicast messages for that group. A comma delimted list may be used to leave more then one group.

Example

$spread->leave_group("test1");

send

This allows you to send messages to a group. You may only send a message to one group at a time. A group may be a either a public group or a private mailbox. The third parameter is an application specific message type. This allows the application to segregate message types.

Examples:

$spread->send("test1", "This is cool", 0);

or

$msg->{command} => "jump";
$msg->{command}->{parameter} => "how high";
$data = objToJson($msg);
$spread->send("test2", $data, 1);

recv

This method allows you to receive messages from the Spread server. The method will wait the default timeout period if no messages are pending. It returns five data items. Those items are as follows:

$service_type

This is the service type of the recieved message. This module tries to decode the message depending on the service type. This allows the application to do whatever with the message.

$sender

This is the sender of the message. The sender is ususally the mailbox the message originated from. But may contain other data depending on the service type.

$groups

This is the groups the message was sent too.

$message_type

This is the application specific message type. It is defined when the message was sent.

$endinan

This indicates if the endianness of the sending platform is differant from the receiving platform.

$message

This is the acutal data that was sent from the sender. Depending on the service type is may also contain one the following types of data.

If the service type was a MEMBERSHIP_MESS with a sub type of REG_MEMB_MESS the message will contain the following array:

If the sub type is CAUSED_BY_LEAVE, CAUSED_BY_JOIN or CAUSED_BY_DISCONNECT the first three array elements are the group id, the last element is the group name.

If the sub type is CAUSED_BY_NETWORK, the first three array elements is the group id, the next one is the number of elements for the groups effected, while the last element is those groups.

If the service type was a MEMBERSHIP_MESS with a sub type of TRANSITIONAL_MESS the message will contain an array with the elements containing the group id.

Example

my ($service_type, $sender, 
    $groups, $message_type, $endian, $message) = 
      $spread->recv();

if ($service_type & REGULAR_MESS) {

    handle_regular_message($service_type, $sender, 
                           $groups, $message_type, 
                           $endian, $message);

} else { 

    handle_membership_message($service_type, $sender, 
                              $groups, $message_type, 
                              $endian, $message);

}

See the documentation for the Spread C API to fully understand the service types and what data can be returned for each type.

ACCESSORS

fd

This returns the file descriptor for the Spread connection. This descriptor can be used with select() or one of the event handling modules to wait for messages from the server.

Example

$fd = $spread->fd;

private_group

This returns the name of your private group.

Example

$private_group = $spread->private_group;

port

This returns or sets the port number for the Spread server.

Example

$port = $spread->port;
$spread->port("8000");

host

This returns or sets the host name for the Spread server.

Example

$host = $spread->host;
$spread->host("spread.example.com");

timeout

This returns or sets the timeout value for your Spread connection.

Example

$timeout = $spread->timeout;
$spread->timeout("10");

private_name

This returns or sets the private name for your Spread connection.

Example

$name = $spread->private_name;
$spread->private_name("myname");

service_type

This returns or sets the service type of the Spread connection.

Example

$service_type = $spread->service_type;
$spread->service_type("SAFE_MESS");

EXPORTS

This module exports the constants that Spread.pm exposes. This is to allow your application access to those constants.

SEE ALSO

Spread::Messaging
Spread::Messaging::Content

There are several other modules located on CPAN that already handle the Spread Group Communication toolkit. They are:

Spread.pm

This module is provided by the Spread toolkit to enable basic connectivity to a Spread server. It works, the interface is smiliar to the C API and you need to do all of the heavy hitting on your own.

Spread::Message

Another wrapper module for Spread.pm. Please see this modules documentation for usage.

Spread::Session

Another wrapper modules for Spread.pm. This module is the base for these modules:

Spread::Queue
Spread::Queue::Fifo
Spread::Queue::Sender
Spread::Queue::Worker
Spread::Queue::Manager
Spread::Queue::ManagedWorker

Please read the documentation for these modules to see how they interact.

Messaging::Courier

Another wrapper module for Spread.pm. Please see this modules documentation for usage.

You also need to read the Spread documentation located at www.spread.org. This is the definative description on what the Spread system is all about. And should be considered mandatory reading for anybody attempting to use the toolkit.

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Kevin L. Esteb

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.