octopi/library/octopus/infoton.h

   1 #ifndef INFOTON_CLASS
   2 #define INFOTON_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : infoton                                                           *
   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 <basis/contracts.h>
  19 #include <structures/string_array.h>
  20
  21 namespace octopi {
  22
  23 //! An infoton is an individual request parcel with accompanying information.
  24 /*!
  25   This is the unit of data exchange in the octopus scheme.
  26 */
  27
  28 class infoton
  29 : public virtual basis::packable,
  30   public virtual basis::clonable,
  31   public virtual basis::text_formable
  32 {
  33 public:
  34   infoton(const structures::string_array &classifier);
  35     //!< creates an infoton with the "classifier".
  36     /*!< keep in mind that although anything can be passed in here, the
  37     consistency of one's collection of octopi depends on a regular
  38     classification scheme.  it is recommended that the "classifier" be
  39     effectively constant.  also, classifiers that begin with the octothorpe
  40     (aka the pound sign '#') are reserved for octopus internal usage. */
  41
  42   // takes care of the most common cases of 1, 2 & 3 level classifiers.
  43   infoton(const basis::astring &class_1);
  44   infoton(const basis::astring &class_1, const basis::astring &class_2);
  45   infoton(const basis::astring &class_1, const basis::astring &class_2, const basis::astring &cl_3);
  46
  47   infoton(const infoton &to_copy);
  48     //!< copies only the base class portion of the infoton.
  49     /*!< clone() is the proper method for copying an instantiated infoton--
  50     this constructor only supports copying the base's information. */
  51
  52   virtual ~infoton();
  53
  54   DEFINE_CLASS_NAME("infoton");
  55
  56   infoton &operator =(const infoton &to_copy);
  57     //!< assigns only the base class portion.
  58     /*!< clone() is the proper method for copying an instantiated infoton. */
  59
  60   const structures::string_array &classifier() const;
  61     //!< this array of strings is the "name" for this infoton.
  62     /*!< the naming scheme for an infoton hierarchically and uniquely
  63     identifies the exact type of this object.  the last string (at the end()
  64     index) is the most specific name for this object, while the preceding
  65     names describe the object's membership in groups.  the outermost group
  66     name is at the zeroth index in the array.  a classifier can have one or
  67     more elements. */
  68
  69   void set_classifier(const structures::string_array &new_classifier);
  70     //!< sets the infoton's classifier to the "new_classifier".
  71     /*!< do not do this unless you know what you're doing; changing the
  72     classifier may keep an infoton from being recognized properly. */
  73
  74   // these are also dangerous if you're not careful; they mimic the
  75   // string constructors.
  76   void set_classifier(const basis::astring &class_1);
  77   void set_classifier(const basis::astring &class_1, const basis::astring &class_2);
  78   void set_classifier(const basis::astring &class_1, const basis::astring &class_2,
  79           const basis::astring &cl_3);
  80
  81   bool check_classifier(const basis::astring &class_name, const basis::astring &caller);
  82     //!< checks that the classifier seems valid.
  83     /*!< the "class_name" and "caller" should be set to the location where
  84     the check is being done. */
  85
  86   virtual void pack(basis::byte_array &packed_form) const = 0;
  87     //!< stuffs the data in the infoton into the "packed_form".
  88     /*!< the derived method must know how to pack this particular type
  89     of infoton. */
  90   virtual bool unpack(basis::byte_array &packed_form) = 0;
  91     //!< restores an infoton from a packed form.
  92     /*!< the unpack() method will be utilized by tentacles that support
  93     this type of object. */
  94
  95   virtual void text_form(basis::base_string &state_fill) const = 0;
  96     //!< requires derived infotons to be able to show their state as a string.
  97
  98   virtual clonable *clone() const = 0;
  99     //!< must be provided to allow creation of a copy of this object.
 100
 101   virtual int packed_size() const = 0;
 102     //!< reports how large the infoton will be when packed.
 103     /*!< must be overridden by derived classes to provide a guess at how
 104     large the packed size of this will be.  this is important to estimate
 105     accurately. */
 106
 107   //! local version just makes text_form() more functional.
 108   virtual basis::astring text_form() const { basis::astring fill; text_form(fill); return fill; }
 109
 110   //////////////
 111
 112   // This defines the wire format for a flattened infoton.  It is in essence
 113   // a packet header format which all infotons must adhere to to ensure that
 114   // they can be successfully unflattened when appropriate item managers are
 115   // available.
 116   static void fast_pack(basis::byte_array &packed_form, const infoton &to_pack);
 117     //!< flattens an infoton "to_pack" into the byte array "packed_form".
 118
 119   static bool fast_unpack(basis::byte_array &packed_form, structures::string_array &classifier,
 120           basis::byte_array &info);
 121     //!< undoes a previous fast_pack to restore the previous information.
 122     /*!< extracts the data from a packed infoton in "packed_form" into the
 123     "classifier" and "info" that are contained therein. */
 124
 125   static bool test_fast_unpack(const basis::byte_array &packed_form,
 126           int &packed_length);
 127     //!< checks that the "packed_form" could hold a valid packed infoton.
 128     /*!< tests that the smallest prefix of the "packed_form" looks like an
 129     appropriate packed classifier and packet length.  the "packed_length"
 130     is set to the length found in the packet.  note that the byte array
 131     does not need to contain the complete packed infoton yet; just the first
 132     portion where the header info is located must be present.  this method
 133     does not disturb the data in the packed array. */
 134
 135   static int fast_pack_overhead(const structures::string_array &classifier);
 136     //!< reports how much space is needed to pack the "classifier".
 137     /*!< returns the overhead in bytes that will be added to an infoton's
 138     packed size when it is packed with fast_pack().  the "classifier" is the
 139     name of the infoton in question and must be accurate or the overhead will
 140     not be calculated properly. */
 141
 142 private:
 143   structures::string_array *_classifier;  //!< our classifier held.
 144 };
 145
 146 //////////////
 147
 148 //! a templated method for cloning any infoton with a valid copy constructor.
 149
 150 template <class contents>
 151 basis::clonable *cloner(const contents &this_obj) { return new contents(this_obj); }
 152
 153 } //namespace.
 154
 155 #endif
 156