/ 
Spread-Messaging-0.03
River stage zero No dependents
/ Spread::Messaging::Content

NAME

Spread::Messaging::Content - A Perl extension for the Spread Group Communications toolkit

SYNOPSIS

This module attempts to provide a simple and easy to use interface to the Spread Group Commuications toolkit. It builds upon the framework defined within Spread::Messaging::Transport.

DESCRIPTION

Your application could be as simple as this.

use Spread::Messaging::Content;

$spread = Spread::Messaging::Content->new();
$spread->join_group("test1");

for (;;) {

    if ($spread->poll()) {

        $spread->recv();
        do_something();

    }

    sleep(1);

}

sub do_something {

    if ($spread->is_regular_mess) {

        printf("Service Type: %s\n", $spread->message_type);
        printf("Sender      : %s\n", $spread->sender);
        printf("Groups      : %s\n", join(',', @{$spread->group}));
        printf("Message Type: %s\n", $spread->type);
        printf("Endian      : %s\n", $spread->endian);
        printf("Message     : %s\n", $spread->message);

    } elsif ($spread->is_membership_mess) {

        printf("Service Type: %s\n", $spread->message_type);
        printf("Sender      : %s\n", $spread->sender);
        printf("Groups      : %s\n", join(',', @{$spread->group}));
        printf("Message Type: %s\n", $spread->type);
        printf("Endian      : %s\n", $spread->endian);
        printf("Message     : %s\n", join(',', @{$spread->message});

    }

}

But of course, this is never the case. This module will allow you to build your application as you see fit. It builds upon the framework of Spread::Messaging::Transport by objectifing the returned messages. This allows you to not to worry about the actual data structure of the message.

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::Content->new(
    -port => "8000",
    -timeout => "10",
    -host => "spread.example.com",
    -private_name => "mymailbox"
);
is_unreliabe_mess

This returns true or false depending on the message type.

is_reliable_mess

This returns true or false depending on the message type.

is_fifo_mess

This returns true or false depending on the message type.

is_causal_mess

This returns true or false depending on the message type.

is_agreed_mess

This returns true or false depending on the message type.

is_regular_mess

This returns true or false depending on the message type.

is_private_mess

This returns true or false depending on the message type.

is_self_discard_mess

This returns true or false depending on the message type.

is_reg_memb_mess

This returns true of false depending on the message type.

is_transition_mess

This returns true or false depending on the message type.

is_safe_mess

This returns true or false depending on the message type.

is_caused_by_join

This returns true or false depending on the message type.

is_caused_by_leave

This returns true or false depending on the message type.

is_caused_by_leave

This returns true or false depending on the message type.

is_caused_by_disconnect

This returns true or false depending on the message type.

is_caused_by_network

This returns true or false depending on the message type.

is_membership_mess

This returns truw or false depending on the message type.

is_self_leave_mess

This returns true or false depending on the message type.

Example usage for the above
$spread->recv();

if ($spread->is_regular_mess) {

    if ($spread->is_private_mess) {

        printf("Private message from %s\n", @{$spread->group}[0]);

    } else {

        printf("Group message from %s\n", join(',', @{$spread->group}));

    }

} elsif ($spread->is_membership_mess) {

    if ($spread->is_transitional_mess) {

        if ($spread->is_caused_by_leave) {

            printf("%s has left the group\n", $spread->group);

        } elsif ($spread->is_caused_by_join) {

            printf("%s has joined the group\n", $spread->group);

        } else {

           printf("Something unexpected has happend: %s\n", 
                  $spread->message_type);

        }

    }

}
group

This method returns or sets the group.

Example:
$groups = $spread->group;
$spread->group("test1,test2");
type

This method returns or sets the application specific message type.

Example
$type = $spread->type;
$spread->type("2");
message

This method returns or sets the message. No form or structure is imposed upon the message before it is sent.

Example
$message = $spread->message;
$spread->message("this is neato");
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.

Examples:
$spread->group("test1");
$spread->type("0");
$spread->message("cooking with fire");
$spread->send();

or

$msg->{command} => "jump";
$msg->{command}->{parameter} => "how high";
$data = objToJson($msg);
$spread->group("test1");
$spread->message($data);
$spread->send();
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.

Example:
for (;;) {

    $spread->recv();

    if ($spread->is_regular_mess) {

        printf("Service Type: %s\n", $spread->message_type);
        printf("Sender      : %s\n", $spread->sender);
        printf("Groups      : %s\n", join(',', @{$spread->group}));
        printf("Message Type: %s\n", $spread->type);
        printf("Endian      : %s\n", $spread->endian);
        printf("Message     : %s\n", $spread->message);

    } elsif ($spread->is_membership_mess) {

        printf("Service Type: %s\n", $spread->message_type);
        printf("Sender      : %s\n", $spread->sender);
        printf("Groups      : %s\n", join(',', @{$spread->group}));
        printf("Message Type: %s\n", $spread->type);
        printf("Endian      : %s\n", $spread->endian);
        printf("Message     : %s\n", join(',', @{$spread->message});

    }

    sleep(1);

}

This example is not recommened, there are better ways to wait for messages from the network. One is to use Event and construct an event loop. For example:

use Event;
use Spread::Messaging::Content:

sub put_output {

   $spread->recv();

   printf("Service Type: %s\n", $spread->message_type);
   printf("Sender      : %s\n", $spread->sender);
   printf("Groups      : %s\n", join(',', @{$spread->group}));
   printf("Message Type: %s\n", $spread->type);
   printf("Endian      : %s\n", $spread->endian);
   printf("Message     : %s\n", ref($spread->message) eq "ARRAY" ? 
                                    join(',', @{$spread->message}) :
                                    $spread->message);

}

$spread = Spread::Messaging::Content->new();
$spread->join_group("test1");

Event->io(fd => $spread->fd, cb => \&put_output);
Event::loop();

ACCESSORS

endian

This accessor will return the endianness of the message.

sender

This accessor will return the sender of the message. Sender has differant meanings depending on the messages service type.

EXPORTS

This module exports the following constants from Spread.pm.

UNRELIABLE_MESS
RELIABLE_MESS
FIFO_MESS
CAUSAL_MESS
AGREED_MESS
SAFE_MESS

SEE ALSO

Spread::Messaging
Spread::Transport

There are several other modules located on CPAN that already handle the Spread Group Communications 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@kesteb.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.