a Free Production Planning Library

Home

Download and install

Screenshots

Documentation

Tutorial

C++ API reference

External links

Get involved

Forum

Newsletter

Contact

search on this site:

Many thanks to

utils.h

Go to the documentation of this file.

/***************************************************************************
  file : $URL: https://frepple.svn.sourceforge.net/svnroot/frepple/trunk/include/frepple/utils.h $
  version : $LastChangedRevision: 861 $  $LastChangedBy: jdetaeye $
  date : $LastChangedDate: 2008-12-26 18:35:10 +0100 (Fri, 26 Dec 2008) $
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 * Copyright (C) 2007 by Johan De Taeye                                    *
 *                                                                         *
 * This library is free software; you can redistribute it and/or modify it *
 * under the terms of the GNU Lesser General Public License as Objecthed   *
 * by the Free Software Foundation; either version 2.1 of the License, or  *
 * (at your option) any later version.                                     *
 *                                                                         *
 * This library is distributed in the hope that it will be useful,         *
 * but WITHOUT ANY WARRANTY; without even the implied warranty of          *
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser *
 * General Public License for more details.                                *
 *                                                                         *
 * You should have received a copy of the GNU Lesser General Public        *
 * License along with this library; if not, write to the Free Software     *
 * Foundation Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA *
 *                                                                         *
 ***************************************************************************/

/** @file utils.h
  * @brief Header file for auxilary classes.
  *
  * @namespace frepple::utils
  * @brief Core namespace
  */

#ifndef FREPPLE_UTILS_H
#define FREPPLE_UTILS_H

/* Python.h has to be included first. 
   For a debugging build on windows we avoid using the debug version of Python
   since that also requires Python and all its modules to be compiled in debug
   mode.
*/
#if defined(_DEBUG) && defined(_MSC_VER)
#undef _DEBUG
#include "Python.h"
#define _DEBUG
#else
#include "Python.h"
#endif
#include "datetime.h"

// For compatibility with earlier Python releases
#if PY_VERSION_HEX < 0x02050000 && !defined(PY_SSIZE_T_MIN)
typedef int Py_ssize_t;
#define PY_SSIZE_T_MAX INT_MAX
#define PY_SSIZE_T_MIN INT_MIN
#endif

#include <iostream>
#include <fstream>
#include <sstream>
#include <stdexcept>
#include <ctime>
#include <assert.h>
#include <typeinfo>

// We want to use singly linked lists, but these are not part of the C++
// standard though. Sigh...
#ifndef DOXYGEN
#ifdef HAVE_EXT_SLIST
// Singly linked lists as extension: gcc 3.x
#include <ext/slist>
using namespace gnu_cxx;
#else
#ifdef HAVE_SLIST
// Singly linked lists available in std stl: gcc 2.95
#include <slist>
#else
// Not available: use a double linked list instead
#define slist list
#endif
#endif
#endif

// STL include files
#include <list>
#include <map>
#include <set>
#include <string>
#include <stack>
#include <vector>
#include <algorithm>
using namespace std;

// Configuration file created by autoconf
/** @def PACKAGE_VERSION
  * Defines the version of Frepple.
  */
#ifdef HAVE_CONFIG_H
#undef PACKAGE_BUGREPORT
#undef PACKAGE_NAME
#undef PACKAGE_STRING
#undef PACKAGE_TARNAME
#undef PACKAGE_VERSION
#include <config.h>
#else
// Define the version for (windows) compilers that don't use autoconf
#define PACKAGE_VERSION "0.6.0"
#endif

// Header for multithreading
#if defined(MT)
#if defined(HAVE_PTHREAD_H)
#include <pthread.h>
#elif defined(WIN32)
#define WIN32_LEAN_AND_MEAN
#include <windows.h>
#include <process.h>
#else
#error Multithreading not supported on your platform
#endif
#endif

// For the disabled and ansi-challenged people...
#ifndef DOXYGEN
#ifndef HAVE_STRNCASECMP
# ifdef _MSC_VER
#   define strncasecmp _strnicmp
# else
#   ifdef HAVE_STRNICMP
#     define strncasecmp(s1,s2,n) strnicmp(s1,s2,n)
#   else
      // Last resort. Force it through...
#     define strncasecmp(s1,s2,n) strnuppercmp(s1,s2,n)
#   endif
# endif
#endif
#endif

/** @def ROUNDING_ERROR
  * This constant defines the magnitude of what can still be considered
  * as a rounding error.
  */
#define ROUNDING_ERROR   0.000001

// Header files for the Xerces-c XML parser.
#ifndef DOXYGEN
#define XERCES_NEW_IOSTREAMS
#include <xercesc/util/PlatformUtils.hpp>
#include <xercesc/sax2/SAX2XMLReader.hpp>
#include <xercesc/sax2/Attributes.hpp>
#include <xercesc/sax2/DefaultHandler.hpp>
#include <xercesc/framework/MemBufInputSource.hpp>
#include <xercesc/sax2/XMLReaderFactory.hpp>
#include <xercesc/util/XMLUni.hpp>
#include <xercesc/framework/MemBufInputSource.hpp>
#include <xercesc/framework/LocalFileInputSource.hpp>
#include <xercesc/framework/StdInInputSource.hpp>
#include <xercesc/framework/URLInputSource.hpp>
#include <xercesc/util/XMLException.hpp>
#endif

/** @def DECLARE_EXPORT
  * Used to define which symbols to export from a Windows DLL.
  * @def MODULE_EXPORT
  * Signature used for a module initialization routine. It assures the
  * function is exported appropriately when running on Windows.<br>
  * A module will need to define a function with the following prototype:
  * @code
  * MODULE_EXPORT string initialize(const CommandLoadLibrary::ParameterList&);
  * @endcode
  */
#undef DECLARE_EXPORT
#undef MODULE_EXPORT
#if defined(WIN32) && !defined(DOXYGEN)
  #ifdef FREPPLE_CORE
    #define DECLARE_EXPORT __declspec (dllexport)
  #else
    #define DECLARE_EXPORT __declspec (dllimport)
  #endif
  #define MODULE_EXPORT  extern "C" __declspec (dllexport)
#else
  #define DECLARE_EXPORT
  #define MODULE_EXPORT extern "C"
#endif


namespace frepple
{
namespace utils
{

// Forward declarations
class Object;
class Keyword;
class XMLInput;
class AttributeList;

// Include the list of predefined tags
#include "frepple/tags.h"


/** This type defines what operation we want to do with the entity. */
enum Action
{
  /** or A.<br>
    * Add an new entity, and report an error if the entity already exists. */
  ADD = 0,
  /** or C.<br>
    * Change an existing entity, and report an error if the entity doesn't
    * exist yet. */
  CHANGE = 1,
  /** or D.<br>
    * Delete an entity, and report an error if the entity doesn't exist. */
  REMOVE = 2,
  /** or AC.<br>
    * Change an entity or create a new one if it doesn't exist yet.<br>
    * This is the default action.
    */
  ADD_CHANGE = 3
};


/** Writes an action description to an output stream. */
inline ostream & operator << (ostream & os, const Action & d)
{
  switch (d)
  {
    case ADD: os << "ADD"; return os;
    case CHANGE: os << "CHANGE"; return os;
    case REMOVE: os << "REMOVE"; return os;
    case ADD_CHANGE: os << "ADD_CHANGE"; return os;
    default: assert(false); return os;
  }
}


/** This type defines the types of callback events possible. */
enum Signal
{
  /** Adding a new entity. */
  SIG_ADD = 0,
  /** Deleting an entity. */
  SIG_REMOVE = 1
};


/** Writes a signal description to an output stream. */
inline ostream & operator << (ostream & os, const Signal & d)
{
  switch (d)
  {
    case SIG_ADD: os << "ADD"; return os;
    case SIG_REMOVE: os << "REMOVE"; return os;
    default: assert(false); return os;
  }
}


/** This is the datatype used for hashing an XML-element to a numeric value. */
typedef unsigned int hashtype;

/** This stream is the general output for all logging and debugging messages. */
extern DECLARE_EXPORT ostream logger;

/** Auxilary structure for easy indenting in the log stream. */
struct indent
{
  unsigned short level;
  indent(unsigned short l) : level(l) {}
  indent operator() (unsigned short l) {return indent(l);}
};

/** Print a number of spaces to the output stream. */
inline ostream& operator <<(ostream &os, const indent& i)
{
  for (unsigned int c = i.level; c; --c) os << ' ';
  return os;
}


/** @brief This class groups some functions used to interact with the operating
  * system environment.
  *
  * It handles:
  *   - The frePPLe home directory, which is typically set from the environment
  *     variable FREPPLE_HOME.
  *   - The expansion of environment variables.
  *   - The maximum number of processors / threads to be used by Frepple.
  */
class Environment
{
  private:
    /** Stores the number of processors on your machine.<br>
      * On windows it is automatically initialized to the value of the
      * environment variable NUMBER_OF_PROCESSORS.
      */
    static DECLARE_EXPORT int processors;

    /** A file where output is directed to. */
    static DECLARE_EXPORT ofstream logfile;

    /** The name of the log file. */
    static DECLARE_EXPORT string logfilename;

  public:
    /** Search for a file with a given name.<br>
      * The following directories are searched in sequence to find a match:
      *   - The current directory.
      *   - The directory reffered to by the variable FREPPLE_HOME, if it 
      *     is defined.
      *   - The data directory as configured during the compilation.
      *     This applies only to linux / unix.
      *   - The library directory as configured during the compilation.
      *     This applies only to linux / unix.
      */
    static DECLARE_EXPORT string searchFile(const string);

    /** Environment variables in the argument string are expanded with
      * their value.<br>
      * The variable to be expanded needs to be enclosed by ${ }<br>
      * E.g. 123${CNT}789 becomes 123456789 when the value of the environment
      * variable is 456.<br>
      *
      * Substitution with environment values is implemented for the following
      * types of input data:
      *  - command_setenv: field 'value'
      *  - command_system: field 'cmdline'
      *  - command_python: fields 'cmdline' and 'filename'
      *  - command_readxmlfile: field 'filename'
      *  - command_if: field 'condition'
      *  - command_loadlib: field 'filename'
      *  - command_save: field 'filename'
      *  - command_saveplan: field 'filename'
      *
      * This method works fine with utf-8 and single-byte encodings, but will
      * NOT work with other multibyte encodings (such as utf-116 or utf-32).
      */
    static DECLARE_EXPORT void resolveEnvironment(string& s);

    /** Returns the number of processors on your machine. */
    static int getProcessors() {return processors;}

    /** Updates the number of processors available on your machine. */
    static void setProcessors(int i) {if (i>=1) processors = i;}

    /** Returns the name of the logfile. */
    static const string& getLogFile() {return logfilename;}

    /** Updates the filename for logging error messages and warnings.
      * The file is also opened for writing and the standard output and
      * standard error output streams are redirected to it.<br>
      * If the filename starts with '+' the log file is appended to
      * instead of being overwritten.
      */
    static DECLARE_EXPORT void setLogFile(string x);
};


//
// CUSTOM EXCEPTION CLASSES
//


/** @brief An exception of this type is thrown when data errors are found.
  *
  * The normal handling of this error is to catch the exception and
  * continue execution of the rest of the program.<br>
  * When a DataException is thrown the object is expected to remain in
  * valid and consistent state.
  */
class DataException : public logic_error
{
  public:
    DataException(const char * c) : logic_error(c) {}
    DataException(const string s) : logic_error(s) {}
};


/** @brief An exception of this type is thrown when the library gets in an
  * inconsistent state from which the normal course of action can't continue.
  *
  * The normal handling of this error is to exit the program, and report the
  * problem. This exception indicates a bug in the program code.
  */
class LogicException: public logic_error
{
  public:
    LogicException(const char * c) : logic_error(c) {}
    LogicException(const string s) : logic_error(s) {}
};


/** @brief An exception of this type is thrown when the library runs into
  * problems that are specific at runtime. <br>
  * These could either be memory problems, threading problems, file system
  * problems, etc...
  *
  * Errors of this type can be caught by the client applications and the
  * application can continue in most cases.<br>
  * This exception shouldn't be used for issueing warnings. Warnings should
  * simply be logged in the logfile and actions continue in some default way.
  */
class RuntimeException: public runtime_error
{
  public:
    RuntimeException(const char * c) : runtime_error(c) {}
    RuntimeException(const string s) : runtime_error(s) {}
};


//
// UTILITY CLASS "NON-COPYABLE"
//

/** @brief Class NonCopyable is a base class.<br>Derive your own class from
  * it when you want to prohibit copy construction and copy assignment.
  *
  * Some objects, particularly those which hold complex resources like files
  * or network connections, have no sensible copy semantics.  Sometimes there
  * are possible copy semantics, but these would be of very limited usefulness
  * and be very difficult to implement correctly. Sometimes you're implementing
  * a class that doesn't need to be copied just yet and you don't want to
  * take the time to write the appropriate functions.  Deriving from
  * noncopyable will prevent the otherwise implicitly-generated functions
  * (which don't have the proper semantics) from becoming a trap for other
  * programmers.<br>
  * The traditional way to deal with these is to declare a private copy
  * constructor and copy assignment, and then document why this is done. But
  * deriving from NonCopyable is simpler and clearer, and doesn't require
  * additional documentation.
  */
class NonCopyable
{
  protected:
    NonCopyable() {}
    ~NonCopyable() {}

  private:
    /** This copy constructor isn't implemented.<br>
      * It's here just so we can declare them as private so that this, and
      * any derived class, do not have copy constructors.
      */
    NonCopyable(const NonCopyable&);

    /** This assignment operator isn't implemented.<br>
      * It's here just so we can declare them as private so that this, and
      * any derived class, do not have copy constructors.
      */
    NonCopyable& operator=(const NonCopyable&);
};


//
// UTILITY CLASSES FOR MULTITHREADING
//

/** @brief This class is a wrapper around platform specific mutex functions. */
class Mutex: public NonCopyable
{
  public:
#ifndef MT
    // No threading support, empty class
    Mutex() {}
    ~Mutex()  {}
    void lock() {}
    void unlock() {}
#elif defined(HAVE_PTHREAD_H)
    // Pthreads
    Mutex()         { pthread_mutex_init(&mtx, 0); }
    ~Mutex()        { pthread_mutex_destroy(&mtx); }
    void lock()    { pthread_mutex_lock(&mtx); }
    void unlock()    { pthread_mutex_unlock(&mtx); }
  private:
    pthread_mutex_t mtx;
#else
    // Windows critical section
    Mutex() { InitializeCriticalSection(&critsec); }
    ~Mutex()  { DeleteCriticalSection(&critsec); }
    void lock() { EnterCriticalSection(&critsec); }
    void unlock() { LeaveCriticalSection(&critsec); }
  private:
    CRITICAL_SECTION critsec;
#endif
};


/** @brief This is a convenience class that makes it easy (and
  * exception-safe) to lock a mutex in a scope.
  */
class ScopeMutexLock: public NonCopyable
{
  protected:
    Mutex& mtx;
  public:
    ScopeMutexLock(Mutex& imtx): mtx(imtx) { mtx.lock (); }
    ~ScopeMutexLock() { mtx.unlock(); }
};


//
// METADATA AND OBJECT FACTORY
//

/** @brief This class defines a keyword for the frePPLe data model.
  *
  * The keywords are used to define the attribute names for the objects.<br>
  * They are used as:
  *  - Element and attribute names in XML documents
  *  - Attribute names in the Python extension.
  *
  * Special for this class is the requirement to have a "perfect" hash
  * function, i.e. a function that returns a distinct number for each
  * defined tag. The class prints a warning message when the hash
  * function doesn't satisfy this criterion.
  */
class Keyword : public NonCopyable
{
  private:
    /** Stores the hash value of this tag. */
    hashtype dw;

    /** Store different preprocessed variations of the name of the tag.
      * These are all stored in memory for improved performance. */
    string strName, strStartElement, strEndElement, strElement, strAttribute;

    /** Name of the string transcoded to its Xerces-internal representation. */
    XMLCh* xmlname;

    /** A function to verify the uniquess of our hashes. */
    void check();

  public:
    /** Container for maintaining a list of all tags. */
    typedef map<hashtype,Keyword*> tagtable;

    /** This is the constructor.<br>
      * The tag doesn't belong to an XML namespace. */
    DECLARE_EXPORT Keyword(string);

    /** This is the constructor. The tag belongs to the XML namespace passed
      * as second argument.<br>
      * Note that we still require the first argument to be unique, since it
      * is used as a keyword for the Python extensions.
      */
    DECLARE_EXPORT Keyword(string, string);

    /** Destructor. */
    DECLARE_EXPORT ~Keyword();

    /** Returns the hash value of the tag. */
    hashtype getHash() const {return dw;}

    /** Returns the name of the tag. */
    const string& getName() const {return strName;}

    /** Returns a pointer to an array of XML characters. This format is used
      * by Xerces for the internal representation of character strings. */
    const XMLCh* getXMLCharacters() const {return xmlname;}

    /** Returns a string to start an XML element with this tag: <TAG */
    const string& stringStartElement() const {return strStartElement;}

    /** Returns a string to end an XML element with this tag: </TAG> */
    const string& stringEndElement() const {return strEndElement;}

    /** Returns a string to start an XML element with this tag: <TAG> */
    const string& stringElement() const {return strElement;}

    /** Returns a string to start an XML attribute with this tag: TAG=" */
    const string& stringAttribute() const {return strAttribute;}

    /** This is the hash function. See the note on the perfectness of
      * this function at the start. This function should be as simple
      * as possible while still garantueeing the perfectness.<br>
      * Currently we use the hash functions provided by Xerces. We use
      * 954991 as the hash modulus (954991 being the first prime number lower
      * than 1000000)
      */
    static hashtype hash(const char* c) {return xercesc::XMLString::hash(c,954991);}

    /** This is the hash function. */
    static hashtype hash(string c) {return xercesc::XMLString::hash(c.c_str(),954991);}

    /** This is the hash function taken an XML character string as input.<br>
      * The function is expected to return exactly the same result as when a
      * character pointer is passed as argument.
      * @see hash(const char*)
      */
    static hashtype hash(const XMLCh* c) {return xercesc::XMLString::hash(c,954991);}

    /** Finds a tag when passed a certain string. If no tag exists yet, it
      * will be created. */
    static DECLARE_EXPORT const Keyword& find(char const*);

    /** Return a reference to a table with all defined tags. */
    static DECLARE_EXPORT tagtable& getTags();

    /** Prints a list of all tags that have been defined. This can be useful
      * for debugging and also for creating a good hashing function.<br>
      * GNU gperf is a program that can generate a perfect hash function for
      * a given set of symbols.
      */
    static DECLARE_EXPORT void printTags();
};


/** @brief This abstract class is the base class used for callbacks.
  * @see MetaClass::callback
  * @see FunctorStatic
  * @see FunctorInstance
  */
class Functor : public NonCopyable
{
  public:
    /** This is the callback method.<br>
      * The return value should be true in case the action is allowed to
      * happen. In case a subscriber disapproves the action false is
      * returned.<br>
      * It is important that the callback methods are implemented in a
      * thread-safe and re-entrant way!!!
      */
    virtual bool callback(Object* v, const Signal a) const = 0;

    /** Destructor. */
    virtual ~Functor() {}
};


// The following handler functions redirect the call from Python onto a
// matching virtual function in a PythonExtensionBase subclass.
extern "C"
{
  /** Handler function called from Python. Internal use only. */
  DECLARE_EXPORT PyObject* getattro_handler (PyObject*, PyObject*);
  /** Handler function called from Python. Internal use only. */
  DECLARE_EXPORT int setattro_handler (PyObject*, PyObject*, PyObject*);
  /** Handler function called from Python. Internal use only. */
  DECLARE_EXPORT int compare_handler (PyObject*, PyObject*);
  /** Handler function called from Python. Internal use only. */
  DECLARE_EXPORT PyObject* iternext_handler (PyObject*);
  /** Handler function called from Python. Internal use only. */
  DECLARE_EXPORT PyObject* call_handler(PyObject*, PyObject*, PyObject*);
  /** Handler function called from Python. Internal use only. */
  DECLARE_EXPORT PyObject* str_handler(PyObject*);
}


/** @brief This class is a wrapper around the type information in Python.
  *
  * In the Python C API this is represented by the PyTypeObject structure.
  * This class defines a number of convenience functions to update and maintain
  * the type information.
  */
class PythonType : public NonCopyable
{
  private:
    /** This static variable is a template for cloning type definitions.<br>
      * It is copied for each type object we create.
      */
    static const PyTypeObject PyTypeObjectTemplate;

    /** Accumulator of method definitions. */
    vector<PyMethodDef> methodvector;

    /** Real method table created after initialization. */
    PyMethodDef *methods;

  public:
   /** A static function that evaluates an exception and sets the Python
      * error string properly.<br>
      * This function should only be called from within a catch-block, since
      * internally it rethrows the exception!
      */
    static DECLARE_EXPORT void evalException();

    /** Constructor, sets the tp_base_size member. */
    DECLARE_EXPORT PythonType(size_t base_size, const type_info*);

    /** Return a pointer to the actual Python PyTypeObject. */
    PyTypeObject* type_object() const {return const_cast<PyTypeObject*>(&table);}

    /** Add a new method. */
    DECLARE_EXPORT void addMethod(const char*, PyCFunction, int, const char*);

    /** Updates tp_name. */
    void setName (const string n)
    {
      name = "frepple." + n;
      table.tp_name = const_cast<char*>(name.c_str());
    }

    /** Updates tp_doc. */
    void setDoc (const string n)
    {
      doc = n;
      table.tp_doc = const_cast<char*>(doc.c_str());
    }

    /** Updates tp_base. */
    void setBase(PythonType& b)
    {
      table.tp_base = &b.table;
    }

    /** Updates the deallocator. */
    void supportdealloc(void (*f)(PyObject*))
    {
      table.tp_dealloc = f;
    }

    /** Updates tp_getattro.<br>
      * The extension class will need to define a member function with this
      * prototype:<br>
      *   PythonObject getattro(const XMLElement& name)
      */
    void supportgetattro() 
      {table.tp_getattro = getattro_handler;}

    /** Updates tp_setattro.<br>
      * The extension class will need to define a member function with this
      * prototype:<br>
      *   int setattro(const Attribute& attr, const PythonObject& field)
      */
    void supportsetattro() 
      {table.tp_setattro = setattro_handler;}

    /** Updates tp_compare.<br>
      * The extension class will need to define a member function with this
      * prototype:<br>
      *   int compare(const PythonObject& other)
      */
    void supportcompare() 
      {table.tp_compare = compare_handler;}

    /** Updates tp_iter and tp_iternext.<br>
      * The extension class will need to define a member function with this
      * prototype:<br>
      *   PyObject* iternext()
      */
    void supportiter()
    {
      table.tp_iter = PyObject_SelfIter;
      table.tp_iternext = iternext_handler;
    }

    /** Updates tp_call.<br>
      * The extension class will need to define a member function with this
      * prototype:<br>
      *   PyObject* call(const PythonObject& args, const PythonObject& kwds)
      */
    void supportcall() 
      {table.tp_call = call_handler;}

    /** Updates tp_str.<br>
      * The extension class will need to define a member function with this
      * prototype:<br>
      *   PyObject* str()
      */
    void supportstr() 
      {table.tp_str = str_handler;}

    /** Type definition for create functions. */
    typedef PyObject* (*createfunc)(PyTypeObject*, PyObject*, PyObject*);

    /** Updates tp_new with the function passed as argument. */
    void supportcreate(createfunc c) {table.tp_new = c;}

    /** This method needs to be called after the type information has all
      * been updated. It adds the type to the module that is passed as
      * argument. */
    DECLARE_EXPORT int typeReady(PyObject* m);

    /** Comparison operator. */
    bool operator == (const PythonType& i) const
    { 
      return *cppClass == *(i.cppClass);
    }

    /** Comparison operator. */
    bool operator == (const type_info& i) const
    { 
      return *cppClass == i;
    }

  private:
    /** The type object, as it is used by Python. */
    PyTypeObject table;

    /** Class name. */
    string name;

    /** Documentation string. */
    string doc;

    /** Type info of the registering class. */
    const type_info* cppClass;
};


class MetaCategory;
/** @brief This class stores metadata about the classes in the library.
  * The stored information goes well beyond the standard 'type_info'.
  *
  * A MetaClass instance represents metadata for a specific instance type.
  * A MetaCategory instance represents metadata for a category of object.
  * For instance, 'Resource' is a category while 'ResourceDefault' and
  * 'ResourceInfinite' are specific classes.<br>
  * The metadata class also maintains subscriptions to certain events.
  * Registered classes and objects will receive callbacks when objects are
  * being created, changed or deleted.<br>
  * The proper usage is to include the following code snippet in every
  * class:<br>
  * @code
  *  In the header file:
  *    class X : public Object
  *    {
  *      public:
  *        virtual const MetaClass& getType() {return metadata;}
  *        static const MetaClass metadata;
  *    }
  *  In the implementation file:
  *    const MetaClass X::metadata;
  * @endcode
  * Creating a MetaClass object isn't sufficient. It needs to be registered,
  * typically in an initialization method:
  * @code
  *    void initialize()
  *    {
  *      ...
  *      Y::metadata.registerCategory("Y","Ys", reader_method, writer_method);
  *      X::metadata.registerClass("Y","X", factory_method);
  *      ...
  *    }
  * @endcode
  * @see MetaCategory
  */
class MetaClass : public NonCopyable
{

  friend class MetaCategory;
  template <class T, class U> friend class FunctorStatic;
  template <class T, class U> friend class FunctorInstance;

  public:
     /** Type definition for a factory method calling the default
      * constructor.. */
    typedef Object* (*creatorDefault)();

    /** Type definition for a factory method calling the constructor that
      * takes a string as argument. */
    typedef Object* (*creatorString)(string);

    /** Type definition for a factory method that constructs Python
      * objects.<br>
      * The return value is actually a PyObject pointer.
      */
    typedef PyObject* (*creatorPythonProxy)(Object*);

    /** A string specifying the object type, i.e. the subclass within the
      * category. */
    string type;

    /** A reference to an Keyword of the base string. */
    const Keyword* typetag;

    /** The category of this class. */
    const MetaCategory* category;

    /** A factory method for the registered class. */
    union
    {
      creatorDefault factoryMethodDefault;
      creatorString factoryMethodString;
    };

    /** A factory method for a Python object that can act as a proxy for
      * the C++ object.
      */
    creatorPythonProxy factoryPythonProxy;

    /** Default constructor. */
    MetaClass() : type("unspecified"), typetag(&Keyword::find("unspecified")),
      category(NULL), factoryMethodDefault(NULL), factoryPythonProxy(NULL) {}

    /** Destructor. */
    virtual ~MetaClass() {}

    /** This constructor registers the metadata of a class. */
    DECLARE_EXPORT void registerClass(const char*, const char*, bool = false) const;

    /** This constructor registers the metadata of a class, with a factory
      * method that uses the default constructor of the class. */
    void registerClass (const char* cat, const char* cls, creatorDefault f,
      bool def = false) const
    {
      const_cast<MetaClass*>(this)->factoryMethodDefault = f;
      registerClass(cat,cls,def);
    }

    /** This constructor registers the metadata of a class, with a factory
      * method that uses a constructor with a string argument. */
    void registerClass (const char* cat, const char* cls, creatorString f,
      bool def = false) const
    {
      const_cast<MetaClass*>(this)->factoryMethodString = f;
      registerClass(cat,cls,def);
    }

    /** This function will analyze the string being passed, and return the
      * appropriate action.
      * The string is expected to be one of the following:
      *  - 'A' for action ADD
      *  - 'C' for action CHANGE
      *  - 'AC' for action ADD_CHANGE
      *  - 'R' for action REMOVE
      *  - Any other value will result in a data exception
      */
    static DECLARE_EXPORT Action decodeAction(const char*);

    /** This method picks up the attribute named "ACTION" from the list and
      * calls the method decodeAction(const XML_Char*) to analyze it.
      * @see decodeAction(const XML_Char*)
      */
    static DECLARE_EXPORT Action decodeAction(const AttributeList&);

    /** Sort two metaclass objects. This is used to sort entities on their
      * type information in a stable and platform independent way.
      * @see operator !=
      * @see operator ==
      */
    bool operator < (const MetaClass& b) const
    {
      return typetag->getHash() < b.typetag->getHash();
    }

    /** Compare two metaclass objects. We are not always sure that only a
      * single instance of a metadata object exists in the system, and a
      * pointer comparison is therefore not appropriate.
      * @see operator !=
      * @see operator <
      */
    bool operator == (const MetaClass& b) const
    {
      return typetag->getHash() == b.typetag->getHash();
    }

    /** Compare two metaclass objects. We are not always sure that only a
      * single instance of a metadata object exists in the system, and a
      * pointer comparison is therefore not appropriate.
      * @see operator ==
      * @see operator <
      */
    bool operator != (const MetaClass& b) const
    {
      return typetag->getHash() != b.typetag->getHash();
    }

    /** This method should be called whenever objects of this class are being
      * created, updated or deleted. It will run the callback method of all
      * subscribers.<br>
      * If the function returns true, all callback methods approved of the
      * event. If false is returned, one of the callbacks disapproved it and
      * the event action should be allowed to execute.
      */
    DECLARE_EXPORT bool raiseEvent(Object* v, Signal a) const;

    /** Connect a new subscriber to the class. */
    void connect(Functor *c, Signal a) const
      {const_cast<MetaClass*>(this)->subscribers[a].push_front(c);}

    /** Disconnect a subscriber from the class. */
    void disconnect(Functor *c, Signal a) const
      {const_cast<MetaClass*>(this)->subscribers[a].remove(c);}

    /** Print all registered factory methods to the standard output for