/ 
Net-MessageBus-0.04
River stage zero No dependents
/ Net::MessageBus

NAME

Net::MessageBus - Pure Perl simple message bus

VERSION

Version 0.04

SYNOPSIS

This module implements the client side of the Message Bus.

use Net::MessageBus;
my $MessageBus = Net::MessageBus->new(
                    server => '127.0.0.1',
                    group => 'backend',
                    sender => 'machine1',
                    username => 'user',
                    password => 'password',
                    logger  => $logger_object,
                );

On initialization the client authenticates with the Net::MessageBus::Server after which it can start pushing messages to the bus.

In order to receive any messages from the bus the client must subscribe to :

  • one or more groups

  • one or more senders

  • all messages

#each can be called multiple times
$MessageBus->subscribe(group => 'test');
$MessageBus->subscribe(sender => 'test_process_1');

or

$MessageBus->subscribe_to_all();

The client can unsubscribe at any time by calling the unsubscribe method

$MessageBus->unsubscribe();

To retrive the messages received from the bus, the client can call one of this methods :

my @messages = $MessageBus->pending_messages();

or

my $message = $MessageBus->next_message();

EXAMPLE

use Net::MessageBus;

my $MessageBus = Net::MessageBus->new(server => '127.0.0.1',
                      group => 'backend',
                      sender => 'machine1');

$MessageBus->subscribe_to_all();
or
$MessageBus->subscribe(group => 'test');
$MessageBus->subscribe(sender => 'test_process_1');
...

my @messages = $MessageBus->pending_messages();
or
while (my $message = $MessageBus->next_message()) {
    print $message->type();
}

SUBROUTINES/METHODS

new

Creates a new New::MessageBus object

Arguments

  • server = The ip address of the server

  • port = The port on which the server is listening for connections

  • group = The group to which this client belogs to

  • sender = A name for the current client

  • username = User name that will be sent to the server for authentication

  • password = The password that will be sent to the server for authentication

  • logger = A object on which we can call the fallowing methods debug,info,warn,error

Example

my $MessageBus = Net::MessageBus->new(
                    server => '127.0.0.1',
                    group => 'backend',
                    sender => 'machine1',
                    username => 'user',
                    password => 'password',
                    logger  => $logger_object,
                );

subscribe

Subscribes the current Net::MessageBus client to the messages from the specified category. It can be called multiple times

Example :

$MessageBus->subscribe(group => 'test');
or 
$MessageBus->subscribe(sender => 'test_process_1');

send

Send a new messge to the message queue. It has two forms in which it can be called :

1. With a Net::MessageBus::Message object as argument
2. With a hash ref containing the fallowing two keys :

  • type = The message type

  • payload = The actual information we want to send with the message. It can be a scalar, array ref or hash ref and it cannot contain any objects

Example :

$MessageBus->send( $message ); #message must be a Net::MessageBus::Message object
or
$MessageBus->send( type => 'alert', payload => { a => 1, b => 2 }  );

next_message

Returns the next message from the queue of messages we received from the server. The message is a Net::MessageBus::Message object.

pending_messages

Returns all the messages received until now from the server. Each message is a Net::MessageBus::Message object.

Private methods

This methods are for internal use and should not be called manually

connect_to_server

Creates a connection to the Net::MessageBus server and authenticates the user

send_to_server

Handles the actual comunication with the server

authenticate

Sends a authenication request to the server and waits for the response

get_response

Returns the response received from the server for the last request

read_server_messages

Reads all the messages received from the server and adds the to the internal message queue

AUTHOR

Horea Gligan, <gliganh at gmail.com>

BUGS

Please report any bugs or feature requests to bug-net-MessageBus at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-MessageBus. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::MessageBus

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2012 Horea Gligan.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.