source: src/CodePatterns/PrototypeFactory.hpp@ 084729c

/*
 * PrototypeFactory.hpp
 *
 *  Created on: Jan 3, 2011
 *      Author: heber
 */

#ifndef PROTOTYPEFACTORY_HPP_
#define PROTOTYPEFACTORY_HPP_

// include config.h
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include <map>
#include <typeinfo>

#include "CodePatterns/Assert.hpp"

#include "CodePatterns/Clone.hpp"

class PrototypeFactoryTest;

/** \section <PrototypeFactory> (Prototype Factory Howto)
 *
 * This template produces the generic prototype factory pattern.
 *
 * <h2> Introduction </h2>
 *
 * The prototype factory is very similar to the factory pattern with one
 * important difference: An prototype factory contains prototypes that are
 * cloned, whereas a factory contains creation wrappers that just create
 * a new object (i.e. without copying any additional information).
 *
 * A prototype factory is a class that instantiates other types. In order to be
 * able to do so the following prerequisites must be met:
 * -# there is a list of types the factory should be able to produce
 * -# these types have to implement the Clone pattern, i.e. derive from it and
 *    implement a function clone(), see @ref <Clone> ''(Clone)''.
 * -# they all must be derived from a common class (e.g. an interface) which is
 *    the type of the reference the factory returned the newly created objects
 *    as.
 *
 * The reason for the last one is that it is not possible -- except by an ugly
 * static_cast -- to retrieve the particular type and if nonetheless needed,
 * factory is probably the wrong pattern. After all what a factory does is
 * hiding the specifics of a certain subtype, e.g. to control a motor it is not
 * necessary to know how fast it goes and what it precisely does, you just need
 * need the throttle as a control and some kind of rpm feedback. This control
 * and feedback would be the stuff abstracted into the interface class.
 *
 * <h2>How to make a class Prototype Factory</h2>
 *
 * If you want to make a class a Prototype Factory you can use the following
 * sequence of steps.
 *
 * Before we begin, we assume the following #defines to represent ...
 * - Abstract_Interface_Class: the aforementioned common interface of all
 *    particular types the factory should produce.
 * - Abstract_Encapsulation_Class: we need to connect the interface class (which
 *    must not be a template) with the types to put into the factory. Hence, we
 *    need this (templated) class that encapsulates each possible type as its
 *    template argument while deriving from (and implementing) the abstract
 *    interface as well.
 * - MyPrototypeFactory: Your specific factory that spills out references to
 *    Abstract_Interface_Class that are embodied by
 *    Abstract_Encapsulation_Class instances.
 *
 * For present code, have a look at RandomNumberDistributionFactory.def,
 * RandomNumberDistribution_Encapsulation.hpp and
 * RandomNumberDistributionFactory.hpp.
 *
 * @attention{
 * One last \b warning before we begin: Your types should reside in a distinct
 * (and not the global) namespace, otherwise you may get strange errors such
 * as
 * \verbatim
 * /usr/include/boost/preprocessor/iteration/detail/local.hpp:34: error: type/value mismatch at argument 1 in template parameter list for ‘template<class T> class stub’
 * /usr/include/boost/preprocessor/iteration/detail/local.hpp:34: error:   expected a type, got ‘(FactoryTypeList::ListOfKnownTypes)0u’
 * \endverbatim
 * i.e. the compiler cannot discern between the enumerated types and the true
 * types due.
 * @remarks But having your particular types in their own name space is always
 *          a good idea.
 * }
 *
 * Now beginning, first remember that all we need is a list of already present
 * types, i.e. implemented classes. The rest is the stuff below which is all
 * you need (and although it looks like quite a lot, it is actually not).
 *
 * Then, do the following steps:
 * - create a file "RandomNumberDistributionFactory.def" containing only
 *   preprocessor defines as follows:
 *   @code
 *   #ifndef RANDOMNUMBERDISTRIBUTIONPROTOTYPEFACTORY_DEF_
 *   #define RANDOMNUMBERDISTRIBUTIONPROTOTYPEFACTORY_DEF_
 *
 *   #define type_seq (uniform_smallint)(uniform_int)
 *   #define Abstract_Interface_Class RandomNumberDistribution
 *   #define Abstract_Encapsulation_Class RandomNumberDistribution_Encapsulation
 *   #define type_name_space boost::
 *   #undef type_suffix
 *
 *   #endif //RANDOMNUMBERDISTRIBUTIONPROTOTYPEFACTORY_DEF_
 *   @endcode
 *   where \a type_seq is the list of types, each element in round brackets,
 *   \a Abstract_Interface_Class is the class name of the abstract base class
 *   which a reference to the factory spills out, and
 *   \a Abstract_Encapsulation_Class is the class name of the (templated)
 *   encapsulation class of each type. Optionally, these types may reside in
 *   some other name_space, define this one via type_name_space (with suffixes
 *   double colons!). If you need to add something to the types such as "<>",
 *   do so in type_suffix.
 *   Note that the first two and the last line are just to avoid double
 *   inclusion, also the define made therein is used for the following step ...
 * - create the undefine file "RandomNumberDistributionFactory.undef" which
 *   undefines all the previously made definitions to allow for more factories
 *   created without the danger of the various defines getting in the way of
 *   each other:
 *   @code
 *   #ifdef RANDOMNUMBERDISTRIBUTIONPROTOTYPEFACTORY_DEF_
 *
 *   #undef type_seq
 *   #undef type_seq_size
 *   #undef Abstract_Interface_Class
 *   #undef Abstract_Encapsulation_Class
 *   #undef type_name_space
 *   #undef type_suffix
 *
 *   #undef RANDOMNUMBERDISTRIBUTIONPROTOTYPEFACTORY_DEF_
 *   #endif
 *   @endcode
 * - Create the encapsulation of the desired types, listed in the above define
 *   type_seq via a templated class:
 *   @code
 *    #include "Clone.hpp"  // the creator wrapper
 *    #include "RandomNumberDistribution.hpp" // the abstract interface class
 *    template <class type>
 *    class RandomNumberDistribution_Encapsulation :
 *      public RandomNumberDistribution,  // inherit from abstract interface
 *      public Clone<RandomNumberDistribution> // the specialized clone pattern
 *    {
 *      // Our Prototype Factory is friend because it needs to access protected cstor
 *      // to instantiate prototypes.
 *      friend class RandomNumberDistributionFactory;
 *
 *    protected: // no one except factory and ourselves should be allowed to call them
 *      RandomNumberDistribution_Encapsulation() {} // constructor
 *      virtual ~RandomNumberDistribution_Encapsulation() {} // virtual destructor
 *    public:
 *      // ... some interface functions here with template implementation ...
 *      // i.e. those defined as virtual functions in the abstract interface
 *      RandomNumberDistribution* clone() {
 *        // .. instantiate a clone of this instance ..
 *        return MyClone;
 *      };
 *    private:
 *      type encapsulated_type; // the instance of the type to encapsulate
 *    };
 *   @endcode
 * - in the header of your factory put these before any declaration:
 *   @code
 *   // has to be appear BEFORE PrototypeFactory.hpp is included!
 *   #include "RandomNumberDistributionFactory.def"
 *   #include "CodePatterns/FactoryTypeList.hpp"
 *   #include "RandomNumberDistributionFactory.undef"
 *   #include "CodePatterns/PrototypeFactory.hpp"
 *   @endcode
 *   Then declare your factory by inheriting from Factory<Abstract_Interface_Class>
 *   @code
 *   class RandomNumberDistributionFactory :
 *     public Factory<RandomNumberDistribution>
 *   {
 *    // place here all other classes as friends that are allowed to access
 *    // Factory<RandomNumberDistribution>::getPrototypeManipulator()
 *   public:
 *     void FillPrototypeTable(); // these are defined automatically
 *     void EmptyPrototypeTable(); // you don't have to implement them
 *
 *     RandomNumberDistributionFactory();
 *     virtual ~RandomNumberDistributionFactory();
 *
 *   };
 *   #include "RandomNumberDistributionFactory.undef"
 *   @endcode
 *   where the last includes undefines the defines made in the first step and
 *   assures that another factory can be created without any old defines
 *   getting in the way.
 *   @note FactoryTypeList.hpp is necessary as we can't have a forward
 *         declaration of an enum which we need in the header of
 *         PrototypeFactory<T>. Hence, there is an extra class the wraps the
 *         enum which we inherit.
 * - finally implement the prototype factory by:
 *   @code
 *   #include "RandomNumberDistribution_Encapsulation.hpp"
 *   #include "RandomNumberDistributionFactory.hpp"
 *   // has to be included BEFORE PrototypeFactory_impl.hpp!
 *   #include "RandomNumberDistributionFactory.def"
 *   #include "CodePatterns/PrototypeFactory_impl.hpp"
 *
 *   RandomNumberDistributionFactory::RandomNumberDistributionFactory() {
 *    FillPrototypeTable();
 *   }
 *   RandomNumberDistributionFactory::~RandomNumberDistributionFactory() {
 *    EmptyPrototypeTable();
 *   }
 *
 *   CONSTRUCT_SINGLETON(RandomNumberDistributionFactory)
 *   CONSTRUCT_PROTOTYPEFACTORY(RandomNumberDistribution)
 *
 *   #include "RandomNumberDistributionFactory.undef"
 *   @endcode
 *   @note the two functions within the constructor that fill and empty the
 *   prototype table are constructed automatically but you have to call them
 *   because only you (that is RandomNumberDistributionFactory in our case)
 *   is a true friend of RandomNumberDistribution_Encapsulation and can access
 *   its cstor and dstor.
 *
 * That's all.
 */
template <class T>
class PrototypeFactory : public FactoryTypeList<T>
{
public:
  /** Constructor of class PrototypeFactory.
   *
   */
  PrototypeFactory()
  {
    FillEnumTable();
//    FillPrototypeTable();
  }

  /** (virtual) Destructor of class PrototypeFactory.
   *
   */
  virtual ~PrototypeFactory()
  {
    // clear out factories map to allow boost::shared_ptr to do their work (i.e. to release mem)
    // this is necessary as factory is an object
    enums.clear();
    names.clear();
//    EmptyPrototypeTable();
//    PrototypeTable.clear();
  }


  /** Typedef of enumeration of all types known to this factory
   *
   * @note The true enumeration has to be stored in a wrapper class
   * FactoryTypeList because enumerations cannot be forward declared as is
   * necessary here.
   */
  typedef enum FactoryTypeList<T>::ListOfKnownTypes TypeList;

  /** Setter for currenttype to produce.
   *
   * @param instance_name name of type
   */
  void setCurrentType(const std::string instance_name)
  {
    ASSERT(enums.count(instance_name) != 0,
        "PrototypeFactory<"+toString(typeid(T).name())+">::setCurrentType() - type "+instance_name+" is not registered.");
    currenttype = enums[instance_name];
  }

  /** Setter for currenttype to produce.
   *
   * @param instance_type enumeration index of type
   */
  void setCurrentType(TypeList instance_type)
  {
    ASSERT(names.count(instance_type) != 0,
        "PrototypeFactory<"+toString(typeid(T).name())+">::setCurrentType() - enum type "+toString(instance_type)+" is not registered.");
    currenttype = instance_type;
  }

  /** Getter for currenttype to produce.
   *
   * @return name of currenttype
   */
  const std::string & getCurrentTypeName() const
  {
    return names[currenttype];
  }

  /** Getter for currenttype to produce.
   *
   * @return enumeration index of currenttype
   */
  TypeList getCurrentTypeEnum() const
  {
    return currenttype;
  }

  /** Getter for desired type of product.
   *
   * @param enumeration index of product
   * @return reference to copy of product
   */
  T* getProduct(TypeList instance_type) const
  {
    ASSERT(names.count(instance_type) != 0,
        "PrototypeFactory<"+toString(typeid(T).name())+">::getProduct() - enum type "+toString(instance_type)+" is not registered.");
    return PrototypeTable[instance_type]->clone();
  }

  /** Getter for desired type of product.
   *
   * @param instance_name name of product
   * @return reference to copy of product
   */
  T* getProduct(const std::string instance_name) const
  {
    ASSERT(enums.count(instance_name) != 0,
        "PrototypeFactory<"+toString(typeid(T).name())+">::getProduct() - type name "+instance_name+" is not registered.");
    return PrototypeTable[ enums[instance_name] ]->clone();
  }

  /** Getter for desired type of product.
   *
   * @param instance_type_info object of the desired type
   * @return reference to copy of current type product or NULL if type mismatch
   */
  T* getProduct(const std::type_info &instance_type_info) const
  {
    ASSERT(types.count(instance_type_info.name()) != 0,
        "PrototypeFactory<"+toString(typeid(T).name())+">::getProduct() - type info name "+instance_type_info.name()+" is not registered.");
    return PrototypeTable[ types[instance_type_info.name()] ]->clone();
  }

  /** Getter for current type of product.
   *
   * @return reference to copy of current type product
   */
  T* getProduct() const
  {
    return PrototypeTable[currenttype]->create();
  }

  /** Getter for the name of the desired type of product.
   *
   * @return name of distribution
   */
  const std::string &getName(TypeList instance_type) const
  {
    ASSERT(names.count(instance_type) != 0,
        "PrototypeFactory<"+toString(typeid(T).name())+">::getName() - enum type "+toString(instance_type)+" is not registered.");
    return names[instance_type];
  }

  /** Getter for the enumeration index of the desired type of product.
   *
   * @return enum of distribution
   */
  TypeList getEnum(const std::string instance_name) const
  {
   ASSERT(enums.count(instance_name) != 0,
       "PrototypeFactory<"+toString(typeid(T).name())+">::getEnum() - type name "+instance_name+" is not registered.");
   return enums[instance_name];
  }


protected:
  /** Yields true prototype of the product and sets entry to NULL on
   *  PrototypeTable.
  *
  * @warning This method is \b intentionally protected such that only
  * specific friends are allowed to access it.
  * @warning This method performs a dynamic_cast from Clone<IPrototype>* to
  * IPrototype*. This prevents also that prototype is cloneable outside of
  * factory.
  *
  * @param instance_name name of product
  * @return const reference to prototype stored in this factory, i.e. read-only
  */
  const T& getPrototype(const std::string instance_name)
  {
    ASSERT(enums.count(instance_name) != 0,
        "PrototypeFactory<"+toString(typeid(T).name())+">::getPrototypeManipulator() - type name "+instance_name+" is not registered.");
    T* prototype = dynamic_cast<T *>(PrototypeTable[ enums[instance_name] ]);
    return *prototype;
  }

  /** Yields true prototype of the product and sets entry to NULL on
   *  PrototypeTable.
  *
  * @warning This method is \b intentionally protected such that only
  * specific friends are allowed to access it.
  *
  * @param enumeration index of product
  * @return const reference to prototype stored in this factory, i.e. read-only
  */
  const T& getPrototype(TypeList instance_type)
  {
    ASSERT(names.count(instance_type) != 0,
        "PrototypeFactory<"+toString(typeid(T).name())+">::getPrototypeManipulator() - enum type "+toString(instance_type)+" is not registered.");
    T* prototype = dynamic_cast<T *>(PrototypeTable[instance_type]);
    return *prototype;
  }

  /** Yields true prototype of the product and sets entry to NULL on
   *  PrototypeTable.
  *
  * @warning This method is \b intentionally protected such that only
  * specific friends are allowed to access it.
  *
  * @param instance_type_info object of the desired type
  * @return const reference to prototype stored in this factory, i.e. read-only
  */
  const T& getPrototype(const std::type_info &instance_type_info)
  {
    ASSERT(types.count(instance_type_info.name()) != 0,
        "PrototypeFactory<"+toString(typeid(T).name())+">::getPrototypeManipulator() - type info name "+instance_type_info.name()+" is not registered.");
    T* prototype = dynamic_cast<T *>(PrototypeTable[ types[instance_type_info.name()] ]);
    return *prototype;
  }

  /** Yields true prototype of the currenttype product and sets entry to NULL
   *  on PrototypeTable.
  *
  * @warning This method is \b intentionally protected such that only
  * specific friends are allowed to access it.
  *
  * @return const reference to prototype stored in this factory, i.e. read-only
  */
  const T& getPrototype()
  {
    T* prototype = dynamic_cast<T *>(PrototypeTable[ currenttype ]);
    return *prototype;
  }

  /** Creates instances of all possible distribution types
   *  and stores them in \a DistributionPrototypeTable.
   *
   *  @note This has to be handed down to the actual implementation of the
   *  desired prototype factory class as cstor and dstor of the abstract
   *  encapsulation class are protected (of a @ref <Clone> (Clone)) and hence
   *  cannot be accessed from this class (because we cannot befriend it from
   *  here).
   */
  virtual void FillPrototypeTable() = 0;

  /** Removes all prototypes from \a PrototypeTable and free's memory.
   *
   *  \sa FillPrototypeTable()
   */
  virtual void EmptyPrototypeTable() = 0;

  /** Create association for enums to strings and vice versa
   *  and stores them in \a distributions tables.
   */
  void FillEnumTable();

  typedef std::map<
      std::string,
      TypeList
      > TypeMap;
  typedef std::map<
      std::string,
      TypeList
      > EnumMap;
  typedef std::map<
      TypeList,
      Clone<T> *
      > InstanceTable;
  typedef std::map<
      TypeList,
      std::string
      > NameMap;

  static TypeList currenttype;
  static TypeMap types;
  static EnumMap enums;
  static InstanceTable PrototypeTable;
  static NameMap names;
};

template <class T> typename PrototypeFactory<T>::TypeList PrototypeFactory<T>::currenttype = (typename PrototypeFactory<T>::TypeList)0;
template <class T> typename PrototypeFactory<T>::TypeMap PrototypeFactory<T>::types;
template <class T> typename PrototypeFactory<T>::EnumMap PrototypeFactory<T>::enums;
template <class T> typename PrototypeFactory<T>::NameMap PrototypeFactory<T>::names;
template <class T> typename PrototypeFactory<T>::InstanceTable PrototypeFactory<T>::PrototypeTable;

/**
 * This define allows simple instantiation of the necessary factory functions
 * at a chosen place.
 */
#define CONSTRUCT_PROTOTYPEFACTORY(InstanceType) \
    template PrototypeFactory<InstanceType>::PrototypeFactory(); \
    template PrototypeFactory<InstanceType>::~PrototypeFactory(); \
    template void PrototypeFactory<InstanceType>::setCurrentType(const std::string instance_name); \
    template void PrototypeFactory<InstanceType>::setCurrentType(TypeList instance_type); \
    template const std::string & PrototypeFactory<InstanceType>::getCurrentTypeName() const; \
    template PrototypeFactory<InstanceType>::TypeList PrototypeFactory<InstanceType>::getCurrentTypeEnum() const; \
    template InstanceType* PrototypeFactory<InstanceType>::getProduct(TypeList instance_type) const; \
    template InstanceType* PrototypeFactory<InstanceType>::getProduct(const std::string instance_name) const; \
    template const std::string &PrototypeFactory<InstanceType>::getName(TypeList instance_type) const; \
    template PrototypeFactory<InstanceType>::TypeList PrototypeFactory<InstanceType>::getEnum(const std::string instance_name) const;


#endif /* PROTOTYPEFACTORY_HPP_ */