DDD_AssetBase.h

Go to the documentation of this file.

#ifndef _DDD_AssetBase_h_
#define _DDD_AssetBase_h_

/*! \file DDD_AssetBase.h
  \brief  The DDD_AssetBase class.  Base class for Data Director assets.

  \par Copyright Information

  Copyright (c) 2012 The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBLITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/

#include "DDD_Base.h"
#include "DDD_AttributeBase.h"
#include "DDD_RevertableAttribute.h"
#include "dynamic_array.h"
#include <string>

namespace disti
{
class DDD_LogFacade;
class DDD_AssetBase;
class DDD_AssetList;
class DDD_ObjectEvent;
class DDD_ObjectEventSubscriber;

/** \brief  A virtual interface class for observers of assets.  
   AssetObservers are able to be notified when an asset deletes and readds its attribute list.
  */
class DDD_EXPORT DDD_AssetObserver
{
public:
    /** A callback method that will be called when the asset being observed deletes its attributes 
      * if this observer has registered to be notified on asset change
      * \param attribute  A pointer to the asset that changed
      */
    virtual void OnAssetAttributeListDeleted(DDD_AssetBase *asset) = 0;

    /** A callback method that will be called when the asset being observed added its attributes 
      * if this observer has registered to be notified on asset change
      * \param attribute  A pointer to the asset that changed
      */
    virtual void OnAssetAttributeListAdded(DDD_AssetBase *asset) = 0;
};

/** \brief  A virtual interface class for containers of assets.  
   Allows assets to find each other, exchange events and update attributes of each other
  */
class DDD_EXPORT DDD_AssetContainer
{
public:
    
    /** Add a new event subscriber to subscriber list
      * \param subscriber  The event subscriber to add
      */
    virtual void AddEventSubscriber(DDD_ObjectEventSubscriber *subscriber) = 0;

    /** Remove an event subscriber from the subscriber list
      * \param subscriber  The event subscriber to remove
      */  
    virtual void RemoveEventSubscriber(DDD_ObjectEventSubscriber *subscriber) = 0;

    /** Post a new event that will be received by all event subscribers
      * \param event  The object event to post
      */
    virtual void PostEvent(DDD_ObjectEvent *event) = 0;

    /** Searches the asset list for an asset with the specified instance name
      * \param assetName  The instance name of the asset to find
      * \return Returns a pointer to the asset or NULL if not found
      */
    virtual DDD_AssetBase* FindAsset(const std::string &assetName) = 0;

    /** Searches all instantiated assets for the attribute.  
      * \param name  The fully qualified name of the attribute to find (e.g. assetName.attribName)
      * \return Returns a pointer to the attribute or NULL if not found
      */
    virtual DDD_AttributeBase *FindAttribute(const std::string &name) = 0;
};


/** \brief  A virtual interface class for all DataDirector assets.
  */
class DDD_EXPORT DDD_AssetBase : public DDD_AttributeContainer, public DDD_Base
{
protected:

    DDD_AttributeList _attributes;  /**< This list contains all attributes that have been requested of this asset, 
                                     not necessarily all of the attributes the asset supports.  In the DataDirector 
                                     editor this list is populated by PopulateAttributeList and generally contains
                                     all of the supported attributes of the asset. At runtime this list will typically
                                     contain the names of attributes that are connected. */
    
    bool _refreshAttributeList; /**< Flag indicating whether or not the attribute list needs to be refreshed.
                                     This is intended only for use by the DataDirector Producer GUI for updating
                                     GUI elements and is not used in the runtime.  */

    DDD_AssetContainer *_container;   /**< Container that owns this asset. Allows this asset to access siblings. */

public:
    /** Constructor */
    DDD_AssetBase(DDD_AssetContainer *container);

    /** Destructor */
    virtual  ~DDD_AssetBase();

    /** \return Returns string identifying which version of DataDirector this asset was built against 
      */
    const char* DataDirectorVersion();

    /** \return Returns a pointer the attribute with the given name.  This will first search the _attributes list
      * for the object.  If an attribute is found there, it will be returned.  Otherwise if no matching attribute 
      * is found there, then the asset's internal dictionary will be searched.  NULL is returned if no matching
      * attribute is found.
      * \param name  The name of the attribute to find
      */
    DDD_AttributeBase* GetAttribute(const char *attributeName);

    /** \return Returns a pointer the attribute with the given index.  It returns NULL if the index
      * is out of range
      * \param name  The name of the attribute to find
      */
    DDD_AttributeBase* GetAttribute(int index);

    /** \return  Returns a string listing attribute names (from the _attributes list), delimited by a ";" */
    const char* GetAttributeNames();

    /** \return A pointer to this asset's container 
      */
    DDD_AssetContainer *GetContainer() { return _container; }

    /** \return Returns number of times each of its attributes are referenced in connections
      */
    int NumberOfConnections();

    /** \return Returns the total number of attributes in the _attributes list for this asset
      *  This is not necessarily the total number of attributes supported by the asset, but just
      *  the total number of attributes that have been requested by the data director.
      */
    int NumberOfAttributes();

    /** Adds a dynamic attribute to the asset's _attributes structure.  This is called by the framework.
      */
    virtual void AddDynamicAttribute(DDD_AttributeBase *attrib);

    /** Called every time the editor needs an update on the current attributes. Some Assets
      * can change their Attribute lists dynamically. By default, it simply populates them the first time
      * and leaves it. Assets with dynamically changing lists of attributes may reallocate their attribute list
      */
    virtual void RefreshAttributesList();

    // For DDD_AssetObserver
    /** Adds an observer to this asset that will be notified whenever this asset changes
      * \param observer  The observer to add.  The observer to add must not already be observing this asset.
      * \return True if the observer was successfully added, false otherwise
      * \pre The observer to add must not already be observing this asset.
      */
    bool AddAssetObserver(DDD_AssetObserver *observer);

    /** Removes an observer from the observer list
      * \param observer  The observer to remove.
      * \return True if the observer was found and removed, false if it wasn't found
      */
    bool RemoveAssetObserver(DDD_AssetObserver *observer);

protected:
    /** Notifies all observers of this asset that its attribute list has been deleted */
    void NotifyAttributeListAdded();

    /** Notifies all observers of this asset that its attribute list has been added or readded */
    void NotifyAttributeListDeleted();
public:

    //////////////////// Required overrides ////////////////////

    /** Describes the Asset (for UI) */
    virtual const char *Description() = 0;

    /** Is this asset currently running? */
    virtual bool Live() = 0;

    /** Returns asset type (class) name */ 
    virtual const char* ClassName() = 0;

    /** Start asset.  Do allocations, initializations that should only happen once. */
    virtual void Start();

    /** Stop asset. Do deallocations, cleanups that should only happen once. */
    virtual void Stop();

    /** Pause asset.  Do cleanup that should happen when the asset is paused. */
    virtual void Pause();

    /** Resume asset.  Do allocations, initializations that should happen when the asset is resumed */
    virtual void Resume();

    /** calculate to pump the asset */
    virtual void Calculate(double time) = 0;

    /** Checks for illegal characters in asset name
      * \param  The asset name to check
      * \return True if the asset name is legal
      */
    static bool IsAssetNameLegal(const std::string& assetName);


    /** Reverts all of the attributes in this list that are marked with the "Revertable" flag
      */
    void RevertAttributes();

    // From DDD_AttributeContainer interface
    virtual const char* GetName() {return GetInstanceName();}

    /** Searches this assets for the attribute.  Not pure virtual.  Child classes can override if
      * they need to provide their own specialized local scoping of attribute names
      * \param name  The fully qualified name of the attribute to find (e.g. assetName.attribName)
      * \param userData  Data to be used by asset for local scoping of attribute names
      * \return Returns a pointer to the attribute or NULL if not found
      */
    virtual DDD_AttributeBase *FindAttributeLocalScope(const std::string &name,void *userData) { return NULL; }

    /** Executes a LUA script.
      * \param script  A string containing the script
      * \param userData User data passed to the script by the invoking asset
      */
    virtual void ExecuteLuaScript(const char *script,void *userData);

    /** Executes a LUA script and returns true if the script set the variable "DDD_Result" to true
      * \param script  A string containing the script
      * \param userData User data passed to the script by the invoking asset
      * \return true if the script set the variable "DDD_Result" to true
      */
    virtual bool EvaluateLuaScript(const char *script,void *userData);

protected:

    /** Create a LUA parser instance for use by this asset */
    void CreateLua();

    /** Destroy the LUA parser instance for this asset */
    void DestroyLua();

    void            *_luaState;           /**< Stores the context for the LUA script engine */ 

    typedef DynamicPtrArray<DDD_AssetObserver*> AssetObserverList;

    AssetObserverList _assetObserverList;       /**< The list of observers to notify when this asset changes */

    /** Poll asset, put all "discovered" assets into _attributList
      * \pre   _attributeList is empty
      * \post  _attributeList will contain the list of attributes discovered from the asset
      */
    virtual void PopulateAttributeList() = 0;

    /** Gets an attribute from the assets internal dictionary and add it to the list of 
      * published attributes for the asset.
      * \param  attributeName  The name of the attribute to get
      * \return A pointer to the attribute or NULL if it doesn't exist.
      */
    virtual DDD_AttributeBase* GetDictionaryAttribute(const char *attributeName) = 0;

    /** Generates unique asset instance name
      * \param assetList List of assets used to check uniqueness of name
      * \post _instanceName will have a unique identifier string
      */
    virtual void GenerateInstanceName(const DDD_AssetList& assetList);
};

}   // end namespace disti
#endif