//  Copyright (C) 2003  OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
//  CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS 
// 
//  This library is free software; you can redistribute it and/or 
//  modify it under the terms of the GNU Lesser General Public 
//  License as published by the Free Software Foundation; either 
//  version 2.1 of the License. 
// 
//  This library 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 
//  Lesser General Public License for more details. 
// 
//  You should have received a copy of the GNU Lesser General Public 
//  License along with this library; if not, write to the Free Software 
//  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA 
// 
//  See http://www.opencascade.org/SALOME/ or email : webmaster.salome@opencascade.org 
//
//
//
//  File   : SUPERV.idl
//  Author : Jean Rahuel
//  $Header: 

/*! \file SUPERV.idl This file contains a set of interfaces of the %SUPERVISION module
*/

#ifndef __SUPERV_IDL__
#define __SUPERV_IDL__

#include "SALOME_ModuleCatalog.idl"
#include "SALOME_Component.idl"
#include "SALOMEDS.idl"
/*! 
 The main package of interfaces of %SUPERVISION module
*/
module SUPERV {

/*!
This enumeration contains a set of elements defining the type of the port.
\note  <BR>In general, ports represent <STRONG>input or output parameters</STRONG> of the functions, 
implemented in different kinds of nodes of the graph.
*/
  enum KindOfPort { UndefinedParameter , ServiceParameter , GateParameter ,
                    InLineParameter , LoopParameter , SwitchParameter ,
                    EndSwitchParameter , GOTOParameter } ;

/*!
This enumeration contains a set of elements defining the type of the node.
*/
  enum KindOfNode { FactoryNode , DataFlowNode , ComputingNode ,
                    InLineNode , LoopNode , EndLoopNode ,
                    SwitchNode , EndSwitchNode , GOTONode , UnknownNode };

/*!
This struct contains fields defining the date.
*/
  struct SDate {
    short Second;
    short Minute;
    short Hour;
    short Day;
    short Month;
    short Year;
  };
/*!
This enumeration contains a set of elements defining the type of operation, which has been performed 
on this node(graph).
*/

  enum GraphEvent { UndefinedEvent , NoEvent , NewThreadEvent ,
                    WaitingEvent , ReadyEvent ,
                    RunningEvent , DoneEvent , ErroredEvent ,
                    SuspendEvent , ResumeEvent ,
                    KillEvent , StopEvent ,
                    ReRunEvent , ReStartEvent } ;

  // UndefinedState : Non existing Node, Port etc...
/*!
This enumeration contains a set of elements defining the current state of the node(graph).
*/

  enum GraphState { UndefinedState , NoState , EditingState , SuspendState ,
                    WaitingState , ReadyState , SuspendReadyState ,
                    RunningState ,
                    DoneState , ErrorState ,
                    SuspendDoneState , SuspendErroredState ,
                    KillState , StopState ,
                    ReRunState , ReStartState ,
                    NumberOfGraphStates } ;

  typedef sequence<string> ListOfStrings ;

  interface Value ;

  interface Link ;

  typedef sequence<Link> ListOfLinks ;

  interface Port ;

  typedef sequence<Port> ListOfPorts ;

  interface CNode ;
  interface FNode ;
  interface INode ;
  interface GNode ;
  interface LNode ;
  interface ELNode ;
  interface SNode ;
  interface ESNode ;
  typedef sequence<CNode>  ListOfCNodes ;
  typedef sequence<FNode>  ListOfFNodes ;
  typedef sequence<INode>  ListOfINodes ;
  typedef sequence<GNode>  ListOfGNodes ;
  typedef sequence<LNode>  ListOfLNodes ;
  typedef sequence<ELNode> ListOfELNodes ;
  typedef sequence<SNode>  ListOfSNodes ;
  typedef sequence<ESNode> ListOfESNodes ;

  struct ListOfNodes {
    ListOfCNodes  CNodes ;
    ListOfFNodes  FNodes ;
    ListOfINodes  INodes ;
    ListOfGNodes  GNodes ;
    ListOfLNodes  LNodes ;
    ListOfELNodes ELNodes ;
    ListOfSNodes  SNodes ;
    ListOfESNodes ESNodes ;
  } ;

  interface Graph ;

  typedef sequence<Graph> ListOfGraphs ;

  // ToSuspendState : will be Suspended before running if waiting or
  //                  will be Suspended while running or
  //                  will be Suspended after run
  // ToSuspendStartState : will be Suspended at the beginning of execution
  // ToSuspendDoneState : will be Suspended after run
/*!
This enumeration contains a set of elements defining the %ControlState of the node. 
The %ControlState gives a possibility to determine the "control actions" which have been done by
the user (Suspend, SuspendDone, Kill, etc...).
*/ 
  enum ControlState { VoidState , ToSuspendStartState ,
                      ToSuspendState , ToSuspendDoneState ,
                      ToKillState , ToKillDoneState , ToStopState ,
                      NumberOfControlStates } ;
/*!
The AutomatonState is an internal state of the automaton of the Executor
of the %SuperVision %Engine. It is used for inner debugging purposes only.
*/

  enum AutomatonState { UnKnownState ,
                        DataUndefState , 
                        DataWaitingState ,
                        DataReadyState ,
                        SuspendedReadyState, 
                        SuspendedReadyToResumeState ,
                        ResumedReadyState ,
                        KilledReadyState ,
                        StoppedReadyState ,
                        ExecutingState ,
                        SuspendedExecutingState , 
                        ResumedExecutingState ,
                        KilledExecutingState , 
                        StoppedExecutingState ,
                        SuccessedExecutingState , 
                        ErroredExecutingState ,
                        SuspendedSuccessedState ,
                        SuspendedErroredState,
                        ResumedSuccessedState , 
                        ResumedErroredState ,
		             KilledSuccessedState , 
                        KilledErroredState ,
		             StoppedSuccessedState ,
                        StoppedErroredState ,
                        SuccessedState , 
                        ErroredState ,
                        SuspendedState ,
                        KilledState , 
                        StoppedState ,
                        SuspendedSuccessedToReStartState ,
                        SuspendedErroredToReStartState ,
                        ReRunnedState , 
                        ReStartedState ,
                        NumberOfAutomatonStates 
                     } ;








  ////////////////
/*! \brief interface %SuperG

This interface contains a set of methods necessary for management of a %graph.
*/
  interface SuperG : Engines::Component, SALOMEDS::Driver {
  ////////////////
/*! 
  Constructs a graph with possibility to read/edit it
  \param aGraph  %aGraphName or %aGraphXmlFile
*/
    SUPERV::Graph Graph(in string aGraph ) ; // aGraphName or aGraphXmlFile

/*!  
  Constructs a read Only graph ( for execution ).
 \note <BR>In this graph there is also a possibility to update nodes, coordinates of the links,
  of container names and input data.
  \param aGraph  %aGraphName or %aGraphXmlFile
*/
    SUPERV::Graph GraphE(in string aGraph ) ; // aGraphName or aGraphXmlFile

/*! 
Creates a value for %Input method in interface %Node.
*/
    SUPERV::Value StringValue( in string aString ) ;
    SUPERV::Value AnyValue( in any anAny ) ;
/*!
 Gets a graph from its %IOR 
*/
    SUPERV::Graph getGraph(in string ior); // get Graph from is IOR

  };

/*! \brief Interface of a node

This interface includes a set of methods used for management of the nodes in the graph.
*/ 

  //////////////
  interface CNode : Engines::Component {
  //////////////


/*! 
Returns the name of the node(graph).
*/
    string Name() ;
/*! 
Returns the service of this node .
*/
    SALOME_ModuleCatalog::Service Service() ;
/*! 
Returns the type of the node.
*/
    SUPERV::KindOfNode Kind() ;
/*! 
Returns the date of creation of the node(graph).
*/ 
    SUPERV::SDate CreationDate() ;
/*! 
Returns the date of last update of the node(graph).
*/
    SUPERV::SDate LastUpdateDate() ;
/*! 
Returns the name of the version of the node(graph).
*/
    string Version() ;
/*! 
Returns the name of the author of the node(graph).
*/
    string Author() ;
/*! 
Returns the string containing comments about this node(graph).
*/
    string Comment() ;
   

/*! 
Sets the name of the node(graph). Returns True if it is updated. 
*/
    boolean SetName(in string aNewName ) ;
/*! 
Sets the name of the author. Returns True if it is updated. 
*/
    boolean SetAuthor(in string anAuthor ) ;
/*!
Allows to update the comments about this node(graph).
*/ 
    boolean SetComment(in string aComment ) ;

/*!
 Gets a port of the node.
*/ 
    SUPERV::Port Port( in string aParameterName ) ;

/*!
 Enters a value into an Input %Port
*/ 
    SUPERV::Port Input( in string InputParameterName ,
                        in Value aValue ) ;


    // Create an Input %Port and an Output Port in LabelNode or ControlNode
    //    boolean BusPort( in string InOutParameterName ,
    //                     in string InOutParameterType ,
    //                     out SUPERV::Port InputPort ,
    //                     out SUPERV::Port OutputPort ) ;
    //    boolean BusPorts( in string InputParameterName ,
    //                      in string InputParameterType ,
    //                      in string OutputParameterName ,
    //                      in string OutputParameterType ,
    //                      out SUPERV::Port InputPort ,
    //                      out SUPERV::Port OutputPort ) ;

/*!  
  Gets a list of ports of the node(graph)
*/
    SUPERV::ListOfPorts Ports() ;

    // Get list of Links
    SUPERV::ListOfLinks Links() ;

/*!
Returns True if this node is a graph. 
\note <BR>A node of the graph can also represent in its turn another graph.
*/
    boolean IsGraph() ;
/*!
Returns True if the node appears to be a %computing node.
*/
    boolean IsComputing() ;
    boolean IsFactory() ;
    boolean IsInLine() ;
    boolean IsGOTO() ;
    boolean IsLoop() ;
    boolean IsEndLoop() ;
    boolean IsSwitch() ;
    boolean IsEndSwitch() ;

/*! 
 Returns the number of  SubGraphs
*/
    long SubGraph() ;

/*! 
Returns nuber of threads.
*/
    long Thread() ;

/*! 
 Returns True if the node(graph) is waiting for Data input
*/
    boolean IsWaiting() ;

/*! 
 Returns True if the node(graph) is ready for execution
*/
     boolean IsReady() ;

 /*! 
 Returns True if the node(graph) is running
*/
    boolean IsRunning() ;

/*! 
 Returns True if execution is finished 
*/
 
    boolean IsDone() ;
/*! 
 Returns True if execution is suspended
*/
 
    boolean IsSuspended() ;
/*!
Returns the current state of the graph.
*/
    SUPERV::GraphState State() ;

    // wait for ready_to_run state, Suspend and return
    boolean ReadyW() ;

    // wait for running state, Suspend and return
    boolean RunningW() ;

    // wait for done state, Suspend and return
    boolean DoneW() ;

    // wait for Suspend state and return
    boolean SuspendedW() ;

    //    boolean Ping();

    // if not running : will be killed when ready to run
    // if running : Kill immediatly
    boolean Kill();

    // will be killed only just after running (only for nodes)
    boolean KillDone();

    // if not running : will be stopped when ready to run
    // if running : Stop immediatly
    boolean Stop();

    // if not running : will be Suspended when ready to run
    // if running : Suspend immediatly
    boolean Suspend();

    // will be Suspended only just after running
    boolean SuspendDone();

    // if Suspended : running will continue
    // if not Suspended : cancel current ControlState ( Suspend, Kill, ...)
    boolean Resume();

/*!
 Restarts execution of the node.
*/
    boolean ReRun();
/*!
Restarts execution of the graph beginning from a definite node.
*/
    boolean ReRunAt( in string aNodeName );

/*!
 Restarts and suspends execution of the node(graph).
*/ 
    boolean ReStart();
/*!
Restarts and suspends execution of the graph beginning from a defined node.
*/
    boolean ReStartAt( in string aNodeName );

/*!
 Returns automaton execution state of the node(graph).
*/
    SUPERV::AutomatonState AutoState() ;

    // Control state required : Kill, Suspend, Stop
    SUPERV::ControlState Control() ;
/*!
Clears the control state of the node(graph).
*/
    void ControlClear() ;

    boolean ContainerKill();
/*! 
Sets the position of the node in the window.
*/
    void Coords( in long X , in long Y ) ;
/*! 
Returns the position of the node along X-axis.
*/
    long X() ;
/*! 
Returns the position of the node along Y-axis.
*/
    long Y() ;
/*! 
Returns the Cpu used by a node in seconds.
*/
    long CpuUsed() ;

  } ;

  //////////////
  interface FNode : CNode {
  //////////////

    string GetComponentName() ;
    string GetInterfaceName() ;
    string GetContainer() ;
    boolean SetComponentName(in string aComponentName ) ;
    boolean SetInterfaceName(in string anInterfaceName ) ;
    boolean SetContainer(in string aContainer ) ;
  } ;

  // InLine Nodes
  //////////////
  interface INode : CNode {
  //////////////

    void SetPyFunction( in string FuncName ,
                        in SUPERV::ListOfStrings aPyInitFunction ) ;
    SUPERV::ListOfStrings PyFunction() ;
    string PyFuncName() ;

    // Create Input/Output Port in InLineNodes
    SUPERV::Port InPort( in string aParameterName , in string aParameterType ) ;
    SUPERV::Port OutPort( in string aParameterName , in string aParameterType ) ;
  } ;

  // GOTO/EndLoop/EndSwitch Nodes
  ///////////////
  interface GNode : INode {
  ///////////////

    boolean SetCoupled( in string anInLineNode ) ;
    SUPERV::INode Coupled() ;
  } ;

  // Loop Nodes
  ///////////////
  interface LNode : GNode {
  ///////////////

    void SetPyInit( in string MoreName ,
                            in SUPERV::ListOfStrings aPyMoreFunction ) ;
    SUPERV::ListOfStrings PyInit() ;
    string PyInitName() ;

    void SetPyMore( in string MoreName ,
                            in SUPERV::ListOfStrings aPyMoreFunction ) ;
    SUPERV::ListOfStrings PyMore() ;
    string PyMoreName() ;

    void SetPyNext( in string NextName ,
                            in SUPERV::ListOfStrings aPyNextFunction ) ;
    SUPERV::ListOfStrings PyNext() ;
    string PyNextName() ;

  } ;

  // EndOfLoop Nodes
  ////////////////
  interface ELNode : GNode {
  ////////////////
  } ;

  // Switch Nodes
  ///////////////
  interface SNode : GNode {
  ///////////////
  } ;

  // EndOfSwitch Nodes
  ////////////////
  interface ESNode : GNode {
  ////////////////
  } ;

/*! \brief Interface of a graph

This interface includes a set of methods used for management of the graphs in %SUPERVISION module.
*/ 

  ///////////////
  interface Graph : INode {
  ///////////////

    // Create a Computing Node in a Graph
    SUPERV::CNode CNode( in SALOME_ModuleCatalog::Service aService ) ;

    // Create a Factory Node in a Graph
    SUPERV::FNode FNode( in string aComponentName ,
                         in string anInterfaceName ,
                         in SALOME_ModuleCatalog::Service aService ) ;

    // Create an InLine Node in a Graph
    SUPERV::INode INode( in string FuncName , in ListOfStrings aPythonFunction ) ;

    // Create a GOTO node and link to the corresponding InLine node
    SUPERV::GNode GNode( in string FuncName , in ListOfStrings aPythonFunction ,
                         in string anINode ) ;

    // Create a "for" or "while" node and the corresponding end of loop node
    SUPERV::LNode LNode( in string InitName , in ListOfStrings InitFunction ,
                         in string MoreName , in ListOfStrings MoreFunction ,
                         in string NextName , in ListOfStrings NextFunction ,
                         out SUPERV::INode anEndOfLoop ) ;

    // Create a "if/elseif/else" or "switch" node and the corresponding end node
    SUPERV::SNode SNode( in string FuncName , in ListOfStrings aPythonFunction ,
                         out SUPERV::INode anEndOfSwitch ) ;

    // Create a CORBA Component Object Reference
    Engines::Component ComponentRef( in string aComputerContainer ,
                                     in string aComponentName ) ;

/*!
 Creates a link  connecting two ports (%Output %Port and %Input %Port) of the nodes in a Graph
*/
    SUPERV::Link Link( in SUPERV::Port OutputPort ,
                       in SUPERV::Port InputPort ) ;

/*! 
Imports a graph into a file with XML format
*/
    boolean Import( in string anXmlFile ) ;
/*! 
Exports a graph from a file with XML format
*/
    boolean Export( in string anXmlFile ) ;
/*!
Returns True if the graph is read Only.
*/
    boolean IsReadOnly() ;

/*!
 Starts asynchronous execution of the graph.
*/
    boolean Run() ;

/*! 
 Assigns to the %Node an %Event and a %State of the %Node, if the Event is
 available. And returns immediately Nil, NoEvent and NoState if not.
 Returns false if the graph is finished, suspended, killed or stopped.
\param aNode  %Node for which this method is called
\param anEvent  An operation, which has been performed on this node(graph).
\param aState   Current state of the graph
*/
    boolean EventNoW( out SUPERV::CNode aNode , out SUPERV::GraphEvent anEvent ,
                      out SUPERV::GraphState aState ) ;

/*! 
 Assigns to the %Node an %Event and a %State of the %Node, if the Event is
 available. Waits if it is not available at the current moment. 
 Returns false if the graph is finished, suspended, killed or stopped.
\param aNode  %Node for which this method is called
\param anEvent  An operation, which has been performed on this node(graph).
\param aState   Current state of the graph
*/
    boolean Event( out SUPERV::CNode aNode , out SUPERV::GraphEvent anEvent ,
                   out SUPERV::GraphState aState ) ;

    // Same as Event but execution of the thread is suspended between the
    // return of EventW and the next call to EventW
/*! 
 Assigns to the %Node an %Event and a %State of the %Node, if the Event is
 available. And returns immediately Nil, NoEvent and NoState if not.
 Returns false if the graph is finished, suspended, killed or stopped.
\note <BR>Execution of the thread is suspended between the return of this 
method and its next usage.
\param aNode  %Node for which this method is called
\param anEvent  An operation, which has been performed on this node(graph).
\param aState   Current state of the graph
*/
    boolean EventW( out SUPERV::CNode aNode , out SUPERV::GraphEvent anEvent ,
                    out SUPERV::GraphState aState ) ;

    long LevelMax() ;
    SUPERV::ListOfNodes LevelNodes( in long aLevel ) ;
    long ThreadsMax() ;
/*!
Returns the number of independent subgraphs
*/
    long GraphsNumber() ;
/*!
Returns the number of currently running threads.
*/
    long Threads();
/*!
Returns the number of suspended threads.
*/
    long SuspendedThreads();
/*!
Returns True if the graph is valid.
*/ 
    boolean IsValid() ;
/*!
Returns True if the graph can be executed.
*/ 
    boolean IsExecutable() ;
/*!
Returns True if the graph represents a working algorithm.
*/ 
    boolean IsDataFlow() ;

/*!
Returns True if the graph is being currently edited. 
*/
    boolean IsEditing() ;
/*!
Returns True if the graph is being currently executed. 
*/
    boolean IsExecuting() ;

    long LastLevelDone() ;

/*!
 Launches step-by-step execution of the graph.
\note  The execution is suspended immediatly after performance of operations of the first node and
user can specify the nodes, where execution will be again suspended after its resuming.
*/
    boolean Start() ;
/*!
Allows to copy one graph into another.
*/
    SUPERV::Graph Copy() ;
/*!
Merges two graphs
*/
    boolean Merge( in Graph aGraph ) ;
/*!
Returns a list of nodes of the graph.
*/
    SUPERV::ListOfNodes Nodes() ;
/*!
Returns a list of links of the graph.
*/
    SUPERV::ListOfLinks GLinks() ;
/*!
Gets IOR of the garph.
*/
    string getIOR();

/*!
Returns a list of graphs.
\note  Not implemented
*/
    SUPERV::ListOfGraphs Graphs() ;

  } ;





/*! \brief Interface of the %link

This interface contains a set of methods used for representation and management of the links 
connecting nodes in a %graph.
*/ 

  //////////////
  interface Link : Engines::Component {
  //////////////
/*!
Associates an %Output %Port to the Link
*/
    SUPERV::Port OutPort() ;

/*!
Associates an %Input %Port to the Link
*/
    SUPERV::Port InPort() ;

    // For GUI :
/*! \name Methods used for representation of links in GUI of %SALOME application :
*/
/*@{*/ 
/*!
Returns the number of coordinate points which are included in the link.
\note  <BR>Every link can contain a set of coordinate points which constitute it. These points have 
index numbers (beginning from 1) and coordinates defining their position in the window. Indexing of 
the points starts from input port to output port of the corresponding link.
*/
    long CoordsSize() ;
/*!
Adds a coordinate point to the link.
\param index  Index of the point. 
\param X  Coordinates of the point.
\param Y  Coordinates of the point.
*/
    boolean AddCoord( in long index , in long X , in long Y ) ;
/*!
Changes the location of a definite coordinate point of the link.
\param index  Index of the point. 
\param X  Coordinates of the point.
\param Y  Coordinates of the point.
*/

    boolean ChangeCoord( in long index , in long X , in long Y ) ;
/*!
Removes a coordinate point of the link.
\param index  Index of the point. 
*/

    boolean RemoveCoord( in long index ) ;

/*!
Sets the location of a coordinate point of the link.
\param index  Index of the point. 
\param X  Coordinates of the point.
\param Y  Coordinates of the point.
*/

    boolean Coords( in long index , out long X , out long Y ) ;
/*@}*/ 

    //    void Destroy() ;

  } ;

/*! \brief  %Value interface

This interface contains a set of methods used for setting initial parameters of the ports
*/

  ///////////////
  interface Value : Engines::Component {
  ///////////////
/*!
Converts the given value into a value of string type.
*/
    string ToString() ;
/*!
Converts the given value into a value of independant data type.
*/
    any ToAny() ;
/*!
Returns True if the value represents an IOR.
*/
    boolean IsIOR() ;
/*! 
Gets data type of the component.
*/
    string ComponentDataType() ;

    //    void Destroy() ;

  } ;
/*! \brief  %Port interface

This interface contains a set of methods used for management of the ports.
*/

  //////////////
  interface Port : Value {
  //////////////

/*!
  Gives a value to an Input %Port 
*/
    boolean Input( in SUPERV::Value aValue ) ;

/*! 
Returns the node of the port
*/
    SUPERV::CNode Node() ;
/*! 
Sets the name of the port.
*/
    string Name() ;

    // Type of a Port
    string Type() ;

    // Link of an Input Port
/*! 
Returns the link of an %Input %Port
*/
    SUPERV::Link Link() ;

/*!
Returns a list of links of an Input %Port of an EndSwitchNode
*/
    SUPERV::ListOfLinks Links() ;

/*! 
Returns True if this port appears to be an %Input %Port of a Node
*/
    boolean IsInput() ;

/*! 
Returns True if an %Input %Value exists for that %Input %Port (without link)
*/
    boolean HasInput() ;

/*! 
Returns True if the %Port is linked (without value)
*/
// Port with link (without Value)
    boolean IsLinked() ;

    // Kind of a Port
    SUPERV::KindOfPort Kind() ;

    // Port from the service of the node
/*! 
Returns True if the %Port is a parameter of a service 
*/
    boolean IsParam() ;
    // Port is a Gate of the node
/*! 
Returns True if the %Port appears to be a GatePort of the node  
*/
    boolean IsGate() ;
    // Port is a parameter of an InLineNode
    boolean IsInLine() ;
    // Port is a LoopParameter (InitLoop or DoLoop) of an LoopNode
    boolean IsLoop() ;
    // Port is an output parameter of a SwitchNode connected to an InGate
/*! 
Returns True if the %Port appears to be a parameter of a switch node  
*/
    // Port is a parameter of a switch node
    boolean IsSwitch() ;
    // Port is an Input parameter of a EndSwitchNode connected to several output ports
    boolean IsEndSwitch() ;

    SUPERV::GraphState State() ;
    boolean IsDone() ;

  } ;

};
#endif