/***************************************************************************
 *   Copyright (C) 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 GCSGWORLDDATA_H
#define GCSGWORLDDATA_H

#include <GElementID.h>

#include <qobject.h>
#include <qvaluelist.h>

namespace GCS
{

class GElement;

/**
  \class GWorldData GWorldData.h
  \brief The interface to the world data for elements.
  
  @author Raphael Langerhorst
  
  To allow maximum flexibility in agent design, agents
  can access data of other elements(!) through this interface.
  The implementation must be provided externally (through the
  GWE normally).
  
  @note In case you hold sensitive data in one or another element
  and don't want all other elements to be able to access it, YOU
  need to provide security mechanisms. Potentially an agent can
  traverse through the whole element hierarchy and perform data
  mining. Be careful in untrusted environments were you are not
  in control of injected agents.
*/
class GWorldData : public QObject
{
  Q_OBJECT
  
  protected:
  
    /**
     * Constructor.
     */
    GWorldData(QObject *parent = 0, const char *name = 0)
    : QObject(parent,name)
    {}

  public:
  
    /**
     * Virtual Destructor.
     */
    virtual ~GWorldData()
    {}
    
    /**
     * The implementation is provided by the GWE, it allows read
     * access to any element in the world. Normally an element
     * more closely watches the element it is connected to. The
     * GWorldData provides the possibility to read data from it,
     * regardless how the remote element is accessed, which is
     * accomplished by the GWE.
     */
    virtual const GElement* read(const GElementID& id) const = 0;
    
    /**
     * @return the IDs of the children of given element.
     */
    virtual QValueList<GCS::GElementID> getChildren(const GCS::GElementID& parent) const = 0;

};

}

#endif