NAME

POE::Component::GCS::Server::Cmd - Generic command validation and dispatch

VERSION

This document describes version 0.12, released March, 2006.

SYNOPSIS

Create a subclass to extend the Command Set used to dispatch commands.

  package My::Network::Server;
  use vars qw( @ISA );
  @ISA = qw( POE::Component::GCS::Server::Cmd );

  use POE::Component::GCS::Server::Cmd;
  use POE::Event::Message;

  sub spawn
  {   my($class, $debug_flag, $command_set) = @_;

      $debug_flag ||= 0;

      $ANY_USER   = q{};      # Empty string
      $ANY_MODE   = q{};      # Empty string
      $DEBUG_MODE = q{D};     # Letter "D"
      $RESPOND    = 1;        # This class responds to the request
      $NO_RESPONSE= 0;        # Another service responds to request

      $command_set ||= {
	  # Generic commands that are dispatched by this class:
	  ping    => [ _ping   => $ANY_USER, $ANY_MODE,   $RESPOND     ],
	  sleep   => [ _sleep  => $ANY_USER, $ANY_MODE,   $NO_RESPONSE ],
	  echo    => [ _echo   => $ANY_USER, $ANY_MODE,   $NO_RESPONSE ],
	  banner  => [ _banner => $ANY_USER, $ANY_MODE,   $NO_RESPONSE ],

	  # Additional commands require methods defined in a subclass:
	  dump    => [ _dump   => $ANY_USER, $DEBUG_MODE, $RESPOND     ],
      };

      POE::Component::GCS::Server::Cmd->spawn( $debug_flag, $command_set );
  }

  sub _dump
  {   my($class, $message) = @_;

      my $response = POE::Event::Message->new( 
	  $message, 
	  "The 'dump' method is not yet implemented." 
      );

      return $response;
  }

Then, after 'spawning' the Command dispatch service, other services can make use of this service as shown here. This minimal example does not show the POE Session contect that is assumed to exist here.

  use POE::Component::GCS::Server::Cmd;
  use POE::Event::Message;

  $Cmd = "POE::Component::GCS::Server::Cmd";

  $message = POE::Event::Message->new( undef, "ping" );

  $method = "post";         # "post," to enqueue a POE event, or
                            # "call," for immediate response

  $service = "";            # "" for Current Session, or name of session

  $event   = "event_name";  # Name of event in the session that will
			    # accept the response.

  @state_args = ();         # State args, as with a POE 'postback'

  $message->addRouteBack( $method, $service, $event, @state_args );

  $Cmd->dispatch( $message );

To successfully 'catch' the response, a method handler for the named $event must exist in the current session (or, if a named $service was given, in the named session). Any @state_args are used in a similar manner to POE's postback mechanism.

DESCRIPTION

This class is used to validate and dispatch commands within a generic network server daemon. Method lookup and partial command validation are performed via a table driven command set. This is used to minimize performance penalties as the command set grows in a subclass.

To cleanly subclass, simply extend the command set, as described below, and define the additional dispatch handler methods in the derived class.

If the generic commands and methods remain included in the "command set", as shown in the Synopsis, above, this class will attempt to dispatch these as well. The success of this operation will depend on whether the services they requre exist in a network server derived from this set of 'PoCo-GCS' base classes.

Note that this module is not event driven. The assumptions are that

• a command will be dispatched from within some event handler

• for some commnds it may be appropriate to return immediate results

• command dispatch should be quick and efficient, and

• for some commands, an event may be generated by the dispatcher and there should not be a 'double dispatch' penalty for using this class

As such, this generic class is implemented to dispatch commands synchronously. This allows for immediate dispatch where appropriate, and avoids generating two events for a single command.

Constructor

spawn ( [ Debug ] [, CommandSet ] )

This creates a new generic server configuration object. Note that the object created is implemented as a 'singleton', meaning that any subsequent calls to this method will return the original object created by the first call to this method.

An optional Debug parameter can be added to enable additional commands that are only valid during debugging and testing. This parameter can be any non-zero value.

An optional CommandSet can, and should, be passed to extend the limited set of 'demo' commands provided with this base class. This parameter should be a data structure with similar format as the one provided with this class.

Methods

dispatch ( Message )

This method validates and dispatches command messages.

Message

The required Message argument is expected to be an object or subclass of the 'POE::Event::Message' class.

Replies to messages should be constructed as shown here. This syntax allows the '$response' to include the unique 'message ID' (from the original '$message' header) as an 'In Reply To' header in the '$response'. Useful for situations where an event needs to correlate various messages and responses.

$response = $message->new( $message, "body of response" );

$response->route();

DEPENDENCIES

None currently.

SEE ALSO

For discussion of the generic server, see POE::Component::GCS::Server. For discussion of the message protocol, see POE::Event::Message.

For notes on adding additional commands to the GCS server, see two 'HINT' sections in the source code for this class and one 'HINT' section in the source for the POE::Component::Server::Proc class.

AUTHOR

Chris Cobb, <no spam please at ccobb dot net>

COPYRIGHT

Copyright (c) 2005-2010 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.