octopi/library/octopus/tentacle_helper.h

   1 #ifndef TENTACLE_HELPER_CLASS
   2 #define TENTACLE_HELPER_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : tentacle_helper                                                   *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2002-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include "infoton.h"
  19 #include "tentacle.h"
  20
  21 #include <basis/byte_array.h>
  22 #include <basis/outcome.h>
  23 #include <structures/string_array.h>
  24
  25 /*! @file tentacle_helper.h
  26   @brief Automates some common tasks for tentacle implementations.
  27   This template provides some default implementations for the methods that
  28   derived tentacles must implement.  This works best when the infotons being
  29   exchanged are derived from a common base; the base class would be used as
  30   the instantiation type here.  For tentacles used in network communication,
  31   the client side could use tentacle_helper<infoton_type> without adding any
  32   functionality.  The server side must override the consume() and expunge()
  33   methods in order to implement processing for the infotons sent by
  34   its clients.
  35 */
  36
  37 namespace octopi {
  38
  39 //!< reconstituter should work for most infotons to restore flattened infotons.
  40 /*!< the infotons that can be used here just need valid default constructor
  41 and unpack methods.  the "junk" parameter is needed to allow the template to
  42 be disambiguated on some compilers--it is unused and should just be NULL_POINTER. */
  43 template <class contents>
  44 basis::outcome reconstituter(const structures::string_array &classifier,
  45     basis::byte_array &packed_form,
  46     infoton * &reformed, contents *formal(junk))
  47 {
  48   contents *inf = new contents;
  49   if (!inf->unpack(packed_form)) {
  50     WHACK(inf);
  51     return tentacle::GARBAGE;
  52   }
  53   reformed = inf;
  54   reformed->set_classifier(classifier);
  55   return tentacle::OKAY;
  56 }
  57
  58 //////////////
  59
  60 //! provides prefab implementations for parts of the tentacle object.
  61 /*! tentacle_helper provides the base functionality of reconstitution that
  62 should support most of the simple needs of a user of an octopus.  if the
  63 octopus will actually implement the request processing (instead of just
  64 unpacking returned responses), the consume method needs to be filled in
  65 appropriately so that it implements the derived tentacle's purpose. */
  66 template <class contents>
  67 class tentacle_helper : public tentacle
  68 {
  69 public:
  70   tentacle_helper(const structures::string_array &classifier, bool backgrounded,
  71       int motivational_rate = tentacle::DEFAULT_RATE)
  72       : tentacle(classifier, backgrounded, motivational_rate) {}
  73
  74   virtual ~tentacle_helper() {}
  75     //!< force a virtual destructor.
  76
  77   //! this is a simple enough action that it is totally automated.
  78   virtual basis::outcome reconstitute(const structures::string_array &classifier,
  79       basis::byte_array &packed_form, infoton * &reformed) {
  80     return reconstituter(classifier, packed_form, reformed,
  81         (contents *)NULL_POINTER);
  82   }
  83
  84   //! consume is not really provided here.  remember to implement for servers!
  85   /*! consume will generally need to be implemented by a "real" tentacle that
  86   is based on the tentacle_helper.  in the context of network communications,
  87   the server side will generally have a real tentacle that implements consume()
  88   while the client side will just have the tentacle_helper version of one,
  89   which does nothing. */
  90   virtual basis::outcome consume(infoton &formal(to_chow),
  91           const octopus_request_id &formal(item_id), basis::byte_array &transformed)
  92       { transformed.reset(); return NO_HANDLER; }
  93
  94   virtual void expunge(const octopus_entity &formal(to_remove)) {}
  95     //!< no general actions for expunge; they are all class-specific.
  96 };
  97
  98 } //namespace.
  99
 100 #endif
 101