Beesnest/DcEnginesBank.h

Go to the documentation of this file.

/*
Copyright 2007 Erez Bibi (erezbibi@users.sourceforge.net)
This file is part of Beesnest.

Beesnest is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

Beesnest 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 General Public License for more details.

You should have received a copy of the GNU General Public License
along with Beesnest; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/

/* DcEnginesBank.h: interface for the CdcEnginesBank class. */

#ifndef CDC_ENGINES_BANK
#define CDC_ENGINES_BANK

#include "DcGlobals.h"
#include "DcParameters.h"
#include "DcEnginesSet.h"
#include "DcUserStatus.h"
#include "Interfaces/DcEngine.h"
#include "Interfaces/DcRequest.h"
#include "Interfaces/DcResponse.h"
#include "Interfaces/DcAdaptersSet.h"

#include _GET_INCLUDE_PATH (DcDynamicLibrary.h)

/**
 * The Engines Bank class is responsible for loading the scripts engines from
 * their libraries, and passing them to the CdcConnectionThread object so it can
 * execute scripts on the buffer that is going back to the client. This class
 * loads an engine library on the first request for this engine. Then it
 * initializes the engine, and stores the loaded library. The library will stay
 * loaded until Beesnest exits. EngineBank can store engines in the user
 * EnginesSet object (if the user is logged in so he has an Engine Set). When
 * CdcConnectionThread asks for an engine the class first looks if an engine
 * from this type (engine name) is in the user Engines Set. If not, it creates
 * the engine from it's library, and passes it down. For the same page though,
 * EnginesBank will store the engines it creates, so the engine can process
 * different sections of scripts under the same environment. But, as mentioned,
 * if the user is logged in, Engine Bank can store an engine over multiple
 * pages. That means a programmer can create a script that will start to run in
 * one page, and continue on another one (with all the data still in place).
 * <p>
 * This class built in a very smiler way to CdcAdaptersBank. Both works on the
 * exact same principle, But here, unlike in the Adapters Bank, the EnginesSet
 * is a server for this class.
 * <p>
 * This class is thread safe.
 *
 * <p>
 * @author Erez Bibi
 */
class CdcEnginesBank
{
private:
    typedef map <CdcString, CdcDynamicLibrary*> t_engines_lib_map;
    /** The static LIBs map. */
    static t_engines_lib_map mLibs;

    /** Static Mutex for this class. */
    static CdcMutex oMutex;

    typedef map <CdcString, IdcEngine*> t_engines_map;
    /** Map to store loaded engines. */
    t_engines_map mEngines;

    /** Pointer to the current Request interface. */
    IdcRequest* pRequest;

    /** Pointer to the current Response interface. */
    IdcResponse* pResponse;

    /** Pointer to the current Adapters Set interface (if exists!). */
    IdcAdaptersSet* pAdaptersSet;
    /** Pointer to the current Engines Set (if exists!). */
    CdcEnginesSet* pEnginesSet;

    /** The default engine name. */
    static CdcString sDefaultEngine;

    /**
     * This function loads an engine from it's library.
     * <p>
     * @param lib Reference to the library to load the engine from.
     * @param name The name of the engine (just so I can pass it to the engine
     *  itself).
     * @return (IdcEngine*) Pointer to this engine or NULL.\
     */
    IdcEngine* LoadEngine (CdcDynamicLibrary& lib, const CdcString& name);

    /**
     * Loads a library by its name.
     * <p>
     * @param name The library name.
     * @return (CdcDynamicLibrary*) Pointer to the library object. This pointer
     *  will not be NULL.
     */
    CdcDynamicLibrary* LoadLib (const CdcString& name);

    /**
     * This function executes an Init function in a library, if it exists.
     * <p>
     * @param oLib Reference to the library to load the function from.
     */
    static void ExecInit (CdcDynamicLibrary& olib);

    /**
     * This function executes a Term function in a library, if it exists.
     * <p>
     * @param oLib Reference to the library to load the function from.
     */
    static void ExecTerm (CdcDynamicLibrary& olib);

public:
    /**
     * Constructor, initialize an EnginesBank object with pointers to the
     * current Request, Response and AdaptersSet objects. This class does
     * nothing with these objects apart of passing them to every engine it loads.
     * Note: pstatus will be NULL if the user is not logged in!
     */
    CdcEnginesBank (IdcRequest* preq, IdcResponse* pres, CdcUserStatus* pstatus);

    /**
     * Destructor, stores or releases every engine this object loaded.
     */
    ~CdcEnginesBank ();

    /**
     * This function will look for a loaded engine from the type 'name' in the
     * engines map. If it founds one, it returns it's pointer, if not it loads
     * the engine from it's library, puts it in the map, and returns the pointer.
     * <p>
     * @param name The name of the engine to load. An empty string will load the
     *  default engine.
     * @return (IdcEngine*) Pointer to the engine, or NULL if it cannot be found.
     */
    IdcEngine* GetEngine (const CdcString& name);

    /**
     * This function will delete an loaded engine (if it exists). I use this
     * function to prevent the class from storing a "Storable" engine in the
     * Engines Set. Beesnest will call this function if the script ends with
     * "[delete]%>"
     * <p>
     * @param name The name of the engine to delete. An empty string will delete
     * the default engine.
     */
    void DeleteEngine (const CdcString& name);

    /**
     * Just set the default engine name. Getting it from the configuration file.
     */
    static void Init ();

    /**
     * Static function to terminate engines. Every engine library may have a
     * termination function, this function will call it.
     */
    static void Term ();
};
#endif /* CDC_ENGINES_BANK */