DDD_Connection.h

Go to the documentation of this file.

#ifndef _DDD_Connection_h_
#define _DDD_Connection_h_

/*! \file DDD_Connection.h
  \brief  The DDD_Connection class.  Base class for connections between 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_ConnectionEndpoint.h"
#include "DDD_ConvertBase.h"
#include "dynamic_ptr_array.h"

namespace disti
{


/** \brief The DDD_Connection class. Base class for connections between assets.
  */
class DDD_EXPORT DDD_Connection : public DDD_AttributeObserver
{
public:
    /** constructor */
    DDD_Connection();

    /** destructor */
    ~DDD_Connection();

    /** process pending connections that have inputs with updated values */
    static void ProcessPending();

    /** This method removes all connections from the the pending list.
     */
    static void ClearPendingList();

    /** Add an input to the connection at the end of the list
      * \param input  The input to add
      */
    bool AddInput( DDD_AttributeBase *input);

    /** Replace the input to the connection at specified index.
      * \param input  The input to add
      * \param index  The index to add at
      */
    bool ReplaceInput( DDD_AttributeBase *input, unsigned int index);

    /** Add an output to the connection at the end of the list
      * \param output  The input to add
      */
    bool AddOutput( DDD_AttributeBase *output);

    /** Replace the output to the connection at specified index.
      * \param output  The output to add
      * \param index   The index to add at
      */
    bool ReplaceOutput( DDD_AttributeBase *output, unsigned int index);

    /** Returns whether or not the specified output is already 
      * used as an output by this connection
      * \param output  The output to check
      * \return True if the output is already used
      */
    bool IsOutputAlreadyUsed(DDD_AttributeBase *output);

    /** Iterates through the inputs and outputs of this connection and 
      * disconnects any endpoints that come from the specified asset
      * \param asset   The asset to disconnect
      * \return The number of endpoints that were disconnected
      */
    int DisconnectAsset( DDD_AssetBase *asset );

    /** Iterates through the inputs and outputs of this connection and 
      * for each endpoint that has the same asset name as the specified asset
      * that connection endpoint is reestablished.  The purpose of this is to 
      * handle reconnection of endpoints in the case where the user deletes
      * an asset in the editor and then loads a new asset
      * \param asset  Pointer to the asset to revalidate
      */
    void RevalidateEndpoints( DDD_AssetBase *asset );

    /** Remove the specified input endpoint from the connection
      * \param index  Index of the input endpoint to remove
      */
    void RemoveInput(unsigned int index);

    /** Remove the specified output endpoint from the connection
      * \param endpoint   Index of the output endpoint to remove
      */
    void RemoveOutput(unsigned int index);

    /** Chooses the converter function to use for this connection.  
      * \param className  The class name of the converter. This will be used by the
      * converter factory to dynamically load the converter.
      * \param params  The initialization parameters for the converter.  The string 
      * must contain the parameters in the form param1=value1;param2=value2 etc.
      * \return True if the converter was successfully loaded
      */
    bool UseConvertFunction(const std::string &className, const std::string &params);

    /** Chooses the converter function to use for this connection.  
      * \param className  The class name of the converter. This will be used by the
      * converter factory to dynamically load the converter.
      * \return True if the converter was successfully loaded
      */
    bool UseConvertFunction(const std::string &className);

    /** Initializes the converter with the parameters specified as a string 
      * The string must contain the parameters in the form param1=value1;param2=value2 etc.
      * The initialization string may contain the initial parameter values for the converter.
      * \param params  The parameters to the converter
      * \return True if the parameters were accepted by the converter
      */
    bool InitConverter(const std::string& params);

    /** \return Returns true if all the endpoints for this connection are valid
      * This is used by the GUI to indicate if a connection has invalid endpoints
      */
    bool AllEndpointsValid();

    /**\return Gets the list of input endpoints for this connection
      */
    DDD_EndpointList &GetInputs()   { return _inputs; }

    /** \return Gets the list of output endpoints for this connection
      */
    DDD_EndpointList &GetOutputs()  { return _outputs; }

    /** \return Gets a pointer to the converter for this connection or NULL if no
      * converter has been set.
      */
    DDD_ConvertBase* GetConverter();

    /** Handles the case when the instance name of a connected asset is changed.
      * Iterates through all connected endpoints and reconfigures them to use 
      * the new asset name.
      * \param oldname  The old name of the asset
      * \param newname  The new name of the asset
      */
    void NotifyAssetNameChange(const std::string& oldname, const std::string& newname);

    // From DDD_AttributeObserver interface
    virtual void OnAttributeChanged(DDD_AttributeBase *attribute);

    /** Set the "DisplayNumber", which is used by the DataDirector GUI for sorting connections
      * \param num  The DisplayNumber to set
      */
    void DisplayNumber(int num) { _displayNumber = num; }

    /** \return Gets the "DisplayNumber", which is used by the DataDirector GUI 
      * for sorting connections
      */
    int DisplayNumber() const { return _displayNumber; }

    /** Allows whether connection can be forced to update when ForceProcess() is called
     * \param allowForcePump  If true, this connection will be processed when ForceProcess() is called. 
     *      If false, it will ignore the request.
     */
    void AllowForcePump(bool allowForcePump);

    /** Adds connection to pending connections list, as long as force pumps are allowed */
    void ForceProcess();

private:

    /** This method adds this connection to pending connections list.
     */
    void AddToPendingProcesses();

    /** Rechecks the Valid status of all the connections endpoints and caches the
      * result in _allEndpointsValid
      */
    void RecheckEndpoints();
    
    /** Iterates through the input endpoints and updates the names. 
      * Called whenever the converter changes or the inputs change.
      */
    void RefreshConverterInputEndpoints();

    /** Iterates through the output endpoints and updates the names. 
      * Called whenever the converter changes or the outputs change.
      */
    void RefreshConverterOutputEndpoints();
    
    /** Processes the inputs and executes the converter which will
      * also notify the outputs if they have changed
      * \return True if the converter was processed
      */
    bool Process(); 

private:
    int _displayNumber;          /**< "DisplayNumber", used by GUI */
    DDD_EndpointList _inputs;    /**< The list of inputs for the connection */
    DDD_EndpointList _outputs;   /**< The list of outputs for the connection */
    DDD_ConvertBase* _converter; /**< The converter to use */
    bool _allEndpointsValid;     /**< True if all connection endpoints are valid, used by GUI */

    /** The pending connections list.  Whenever an input changes, any connections that are 
      * listening to that input are added to the pendingConnections list.  
      */
    static DynamicPtrArray<DDD_Connection*> pendingConnections;

    bool _allowForcePump;        /**< If false, this connection will not be updated when ForceProcess() is called */

};

}   // end namespace disti
#endif