/***************************************************************************
 *   Copyright (C) 2004 - 2005 by Raphael Langerhorst                      *
 *   raphael-langerhorst@gmx.at                                            *
 *                                                                         *
 *   Permission is hereby granted, free of charge, to any person obtaining *
 *   a copy of this software and associated documentation files (the       *
 *   "Software"), to deal in the Software without restriction, including   *
 *   without limitation the rights to use, copy, modify, merge, publish,   *
 *   distribute, sublicense, and/or sell copies of the Software, and to    *
 *   permit persons to whom the Software is furnished to do so, subject to *
 *   the following conditions:                                             *
 *                                                                         *
 *   The above copyright notice and this permission notice shall be        *
 *   included in all copies or substantial portions of the Software.       *
 *                                                                         *
 *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,       *
 *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF    *
 *   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*
 *   IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR     *
 *   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, *
 *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR *
 *   OTHER DEALINGS IN THE SOFTWARE.                                       *
 ***************************************************************************/

#ifndef GDATACONTROLLER_H
#define GDATACONTROLLER_H

#include <qobject.h>

#include <GElement.h>
#include <GElementID.h>
#include <GElementInfluence.h>
#include <GVector3.h>

#include <GWorldData.h>

#include <qvaluelist.h>

namespace GWE
{

/**
 * \Interface GDataController GDataController.h
 * \brief Interface for GWE data controllers, includes network and database.
 * @author Raphael Langerhorst
 * 
 * The Data Controller is responsible for all data management:
 * transportation, storing, synchronizing, ...
 */
class GDataController : public GCS::GWorldData
{
  Q_OBJECT
  
  public:
  
    /**
    * Constructor.
    */
    GDataController(QObject *parent = 0, const char *name = 0)
      : GCS::GWorldData(parent,name)
      {}
      
    /**
    * Virtual destructor.
    */
    virtual ~GDataController()
      {}
      
    // ELEMENT MANAGEMENT //
      
    /**
     * Open an element for reading only.
     *
     * @return NULL if element does not exist.
     */
    virtual const GCS::GElement* read(const GCS::GElementID& ) const = 0;
    
    /**
     * Open an element for general purposes (e.g. executing the agents,...)
     *
     * @note Every element should only be opened once.
     *
     * @return NULL if element does not exist or is already opened.
     * @see close()
     */
    virtual GCS::GElement* open(const GCS::GElementID& ) = 0;
    
    /**
     * Get an already opened element. The element must previously
     * have been opened with open(), otherwise NULL is returned.
     * @return a currently open element with given ID or NULL if element is not opened.
     */
    virtual GCS::GElement* getOpenElement(const GCS::GElementID& ) = 0;

    /**
     * @return a list with IDs of all open elements.
     */
    virtual const QValueList<GCS::GElementID> getListOfOpenElements() = 0;

    /**
     * @return a list with all IDs of all stored elements.
     */
    virtual const QValueList<GCS::GElementID> getListOfAllElements() = 0;
    
    public slots:
      
    // ELEMENT MANAGEMENT - THESE ROUTINES CAN ACT AS SLOTS //
  
    /**
     * Adds given element to the GWE
     * 
     * If false is returned, either the element already exists or
     * it could not be added for various reasons.
     *
     * @return true on success
     */
    virtual bool add(GCS::GElement*) = 0;
    
    /**
     * Forces a full backup of specified element. This is useful
     * when some changes were made to an open element and the complete
     * element should be written back to the storage.
     */
    virtual bool writeOpenElementToStorage(const GCS::GElementID& ) = 0;
    
    /**
     * Closes given element.
     *
     * @return true when the specified element was found and closed;
     * @see open()
     */
    virtual bool close(const GCS::GElementID& ) = 0;
    
    /**
     * In order to persistently remove an element this method needs
     * to be used, it makes sure that the element stops executing and is
     * properly removed (persistent) from memory.
     *
     * Although it may take some time until the element is truly removed,
     * the call itself is (or should be) non-blocking.
     *
     * @return true if the specified element was found and queued for deletion.
     */
    virtual bool postDelete(const GCS::GElementID& ) = 0;

    /**
     * This should be called before closing the application,
     * all required cleanup is done here.
     */
    virtual void shutdown() = 0;
    
  signals:
  
    // SIGNALS INTERESTING FOR DATA MANAGEMENT (DB,...) //
    
    //@todo I think it's better to emit with const GCS::GElementID&, except for added maybe
    
    /**
     * Emitted after an element was added.
     * @note Of course emitting needs be done in the derived class.
     */
    void elementAdded(const GCS::GElementID& );
    
    /**
     * Emitted after an element was updated.
     * This can be an update when receiving data
     * from other GWE Servers for example. Normally the
     * GWE Controller should close opened elements without
     * saving them and open it again if needed.
     * @note Of course emitting needs be done in the derived class.
     */
    void elementUpdated(const GCS::GElementID& );
  
    /**
     * Emitted when an element is opened.
     * @note Of course emitting needs be done in the derived class.
     */
    void elementOpened(const GCS::GElementID& );
    
    /**
     * Emitted when an element was closed.
     * Closed elements are NOT in memory anymore.
     * @note Of course emitting needs be done in the derived class.
     */
    void elementClosed(const GCS::GElementID& );
    
    /**
     * Emitted when an element was removed.
     * @note Of course emitting needs be done in the derived class.
     */
    void elementDeleted(const GCS::GElementID& );
};

}

#endif //GDATACONTROLLER_H