NAME

POE::Event::Message - A generic messaging protocol

VERSION

This document describes version 0.05, released December, 2005.

SYNOPSIS

use POE::Event::Message;

$MsgClass = "POE::Event::Message";

# Creating Messages

$mesg = $MsgClass->new();
$body = <whatever>;              # almost anything 

$mesg = $MsgClass->package( $body );

# Accessing Messages

$mesg->body( $body );            # add body
$body = $mesg->body();           # get body
$head = $mesg->header();         # get header

print $mesg->dump();             # useful when debugging
print $head->dump();             # useful when debugging

# Creating Responses to Messages

$resp = $MsgClass->new( $mesg->header()        );
$resp = $MsgClass->new( $mesg->header(), $body );

$resp = $MsgClass->new( $mesg        );
$resp = $MsgClass->new( $mesg, $body );

# Routing Messages and "Auto Replies" (Within POE environment)

$mesg->header->setMode( "call" );    # default mode: "post"


# FIX: replace this section

my(@routeback) = ( $mode => $session, $event, @routebackArgs );
$mesg->header->addRouteBack( @routeback );

$mesg->routeTo( $mode => $session, $event, @eventArgs );

$resp = $MsgClass->new( $mesg, "back atcha!" );
$resp->reply();                      # activate any "auto-reply"

$resp->reply( @additionalArgs );     # "$resp" included w/reply


# Note/FIX: "addRouteBack" does not default mode to "setMode" val

# Sending and Receiving Messages      (Outside POE environment)

$MsgClass->write( $fh, $message );   # write fh (sock, whatever)
$mesg->write( $fh );                 # write fh (sock, whatever)

$resp = $MsgClass->read( $fh );      # read fh (sock, whatever)
$resp = $mesg->read( $fh );          # read fh (sock, whatever)

DESCRIPTION

This class is a starting point for creating a generic application messaging protocol. The intent is for this to be used as a foundation when building network client/server applications, Web services, etc.

Features of POE::Event::Message include the following.

• Messages of this class have flexible routing capabilities that work both inside and outside POE-based applications.

• The messages are designed to be plug-compatible with POE's existing 'postback' mechanism. I refer to this as a 'routeback' mechanism instead.

• In addition, this class has the ability to introduce multiple 'forward' and/or 'reverse' routing to multiple event and/or remote host destinations. This allows for temporary interruption of normal message flow, without any of the original participants (events or whatever) knowing or caring.

• Messages are delivered based on the type of the destination. A 'local' routing will trigger a POE 'post' or 'call' event, while a 'remote' routing invokes a socket connection to a particular host and port.

• Messages can also be sent through a file handle, such as from a non-POE child to a POE-based parent process.

Constructor

new ( [ Header ] [, Body ] )

This method instantiates a new message object. Optionally it can be used to create a response to an existing message. A message body can also be specified during creation.

Header

The optional Header argument, when included, is expected to be an original message of this class. This mechanism is used to create a 'response' to the original message.

Body

The optional Body argument, when included, can be simple text. The Body can also be any arbitrary Perl data structure. This class provides a filtering mechanism that allows messages containing Perl data structures to be passed across file handles, including sockets and parent/child stdio file descriptors.

WARN: Use caution when using messages containing Perl 'CODE references.' While, as of version 2.05, the underlying 'Storable' module does now support passing CODE refs, this has not been tested here.

Methods

envelope ( Body )

package ( Body )

This method is included to simplify creating a new message object. The Body argument is included as the body of the message.

Body

The required Body argument can be either simple text or a Perl data structure as explained in the new method, above.

call ( Service, Event [, Args ] )

post ( Service, Event [, Args ] )

These methods provide direct message routing within a POE application and will invoke the corresponding method on the POE Kernel for immediate, synchronous event dispatch (call) or queued for asynchronous event dispatch (post).

Service

This argument is the name of an active POE 'Service'.

Event

This argument specifies the 'Event' that will be generated.

Args

The Args parameter is an optional list that can be included with either of the POE 'post' or 'call' event generators.

addRouteTo ( Mode, Service, Event [, Args ] )

addRouteBack ( Mode, Service, Event [, Args ] )

These methods add auto-routing capabilities to messages of this class. These add routing entries to the message header that can then be invoked via the route methods, explained next.

Mode

The Mode must be a string equal to one of 'post' or 'call'. Later, when one of the route methods is used, will then invoke either the corresponding method on the POE Kernel for immediate, synchronous event dispatch (call) or queued for asynchronous event dispatch (post).

Service

This argument is the name of an active POE 'Service'.

Event

This argument is the name of an active POE 'Service'.

Args

The Args parameter is an optional list that can be included with either of the POE 'post' or 'call' event generators.

route ( [ Args ] )

routeto ( [ Args ] )

routeback ( [ Args ] )

These methods add auto-routing capabilities to messages of this class. These extract routing entries from the message header that are then used to generate POE events using immediate dispatch (when the routing entry was created with a Mode of 'call') or queued for delayed dispatch (when the routing entry was created with a Mode of 'post').

The routeto method will extract only those entries created using the addRouteTo method, shown above, while the routeback method will extract only those entries created using the addRouteBack method, also shown above.

The route method will first extract routeTo entries and, when empty, will extract routeBack entries.

NOTE: These methods are designed to be plug-compatible with POE's 'postback' mechanism. These methods add the ability to introduce multiple forward and/or reverse event destinations and can be used to temporarially interrupt normal message routing (and none of the handlers that expect to process the message will even be aware of the interruption).

Args

The Args parameter is an optional list that can be added when any of the 'route' methods are invoked. These arguments are then received by whichever event handler happens to receive the routed message. Note that the message itself is already included as the first argument in the list.

send ( FH, Message )

write ( FH, Message )

These methods provide the ability to send the message object through an open file handle.

WARN: Use caution when using these methods with messages containing Perl 'CODE references.' While the underlying 'Storable' module does now support passing CODE refs, this has not been tested here.

TODO: The Message parameter should be optional and, when omitted, send the current object through the file handle.

FH

An open file handle.

Message

A message object of this class.

read ( FH )

recv ( FH )

These methods provide the ability to receive a message object through an open file handle.

WARN: Use caution when using these methods with messages containing Perl 'CODE references.' While the underlying 'Storable' module does now support passing CODE refs, this has not been tested here.

FH

An open file handle.

status

This method returns the current error status of a message object. When the status code is non-zero, the error message will contain text of the corresponding error.

dump

This method is included for convenience when developing or debugging applications that use this class. This does not produce a 'pretty' output, but is formatted to show the contents of the message object and the message header object, when one exists.

DEPENDENCIES

This class depends upon the following classes:

POE::Event::Message::Header
POE::Event::Message::UniqueID
POE::Driver::SysRW
POE::Filter::Reference

POE::Kernel (optional, but required for some methods)

INHERITANCE

None currently.

SEE ALSO

See POE::Event::Message::Header and POE::Event::Message::UniqueID.

AUTHOR

Chris Cobb, <nospamplease@ccobb.net>

COPYRIGHT

Copyright (c) 2005-2007 by Chris Cobb, All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.