-//=============================================================================
-// File : SALOME_Component.idl
-// Created : jeu jui 12 08:11:23 CEST 2001
-// Author : Paul RASCLE, EDF
-// Project : SALOME
-// Copyright : EDF 2001
-// $Header: /dn05/salome/CVS/SALOME_ROOT/idl/SALOME_Component.idl
-//=============================================================================
+// Copyright (C) 2007-2012 CEA/DEN, EDF R&D, OPEN CASCADE
+//
+// Copyright (C) 2003-2007 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.salome-platform.org/ or email : webmaster.salome@opencascade.com
+//
+// File : SALOME_Component.idl
+// Author : Paul RASCLE, EDF
#ifndef _SALOME_COMPONENT_IDL_
#define _SALOME_COMPONENT_IDL_
-/*! \ingroup Kernel
-This is a package of interfaces used for connecting new components to %SALOME application. It also contains a set of interfaces used
-for management of %MED component in %SALOME application.
+#include "SALOME_GenericObj.idl"
+#include "SALOMEDS.idl"
+#include "SALOME_Exception.idl"
+#include "SALOME_PyNode.idl"
+
+/*! \file SALOME_Component.idl \brief interfaces for EngineComponent and Container
+*/
+
+/*! \brief
+This is a package of interfaces used for connecting new components to %SALOME
+application. It also contains a set of interfaces used for management of %MED
+component in %SALOME application.
*/
module Engines
{
- interface Component ;
+ /*!
+ A byte stream which is used for binary data transfer between different
+ components
+ */
+ typedef sequence<octet> TMPFile;
+
+ //! General Key Value Structure to set or get properties, for component
+ struct KeyValuePair
+ {
+ string key;
+ any value;
+ };
-/*! \brief Interface of the %Container
+ //! Structure data type to hold reference on data
+ struct dataref
+ {
+ string ref;
+ };
+
+ typedef sequence<KeyValuePair> FieldsDict;
+
+ interface EngineComponent ;
+ interface fileRef ;
+ interface fileTransfer ;
+ interface Salome_file;
+
+ /*! \brief Interface of the %Container.
+ This interface defines the process of loading and registration
+ of new components in %SALOME application
+ */
- This interface defines the process of loading and registration
- of new components in SALOME application
-*/
interface Container
{
-/*!
- Initializes the %container with a definite name.
-*/
- Container start_impl( in string ContainerName ) ;
-/*!
- Loads into the container a new component, registers it and starts it's CORBA servant.
- \param nameToRegister Name of the component which will be registered in Registry (or Name Service)
- \param componentName Name of the constructed library of the %component
-*/
- Component load_impl(in string nameToRegister, in string componentName);
+ /*! \brief Loads a new component class (dynamic library).
-/*!
- Stops the component servant, and deletes all related objects
-*/
- void remove_impl(in Component component_i);
+ \param componentName like COMPONENT, (Python or C++ implementation)
+ try to make a Python import of COMPONENT,
+ then a lib open of libCOMPONENTEngine.so
+ \param reason in case of error (return false) a string explaining the error
+ \return true if load successfull or already done, false otherwise
+ */
+ boolean load_component_Library(in string componentName, out string reason);
-/*!
- Discharges all components from the container.
-*/
+ //! Create a new servant instance of a component.
+ /*!
+ Component library must be loaded.
+ \param componentName Name of the component which will be registered
+ in Registry and Name Service,
+ (instance number suffix added to the registered name)
+ \param studyId 0 if instance is not associated to a study,
+ >0 otherwise (== study id)
+ \return a loaded component
+ */
+ Engines::EngineComponent create_component_instance(in string componentName,
+ in long studyId);
+
+ //! Create a new servant instance of a component with environment variables specified.
+ /*!
+ Component library must be loaded.
+ \param componentName Name of the component which will be registered
+ in Registry and Name Service,
+ (instance number suffix added to the registered name)
+ \param studyId 0 if instance is not associated to a study,
+ >0 otherwise (== study id)
+ \param env a dict of env variables
+ \param reason in case of error (return nil) a string explaining the error
+ \return a loaded component
+ */
+ Engines::EngineComponent create_component_instance_env(in string componentName,
+ in long studyId, in FieldsDict env,
+ out string reason);
+ //! Find a servant instance of a component
+ /*!
+ \param registeredName Name of the component in Registry or Name Service,
+ without instance suffix number
+ \param studyId 0 if instance is not associated to a study,
+ >0 otherwise (== study id)
+ \return the first instance found with same studyId
+ */
+ EngineComponent find_component_instance(in string registeredName,
+ in long studyId);
+
+ //! Find a servant instance of a component, or create a new one.
+ /*!
+ Loads the component library if needed.
+ Only applicable to multiStudy components.
+ \param nameToRegister Name of the component which will be registered
+ in Registry (or Name Service)
+ \param componentName Name of the constructed library of the %component
+ (not used any more, give empty string)
+ \return a loaded component
+ */
+ EngineComponent load_impl(in string nameToRegister,
+ in string componentName);
+
+ //! Remove the component servant, and deletes all related objects
+ /*!
+ \param component_i Component to be removed
+ */
+ void remove_impl(in EngineComponent component_i);
+
+ //! Unload component libraries from the container.
void finalize_removal() ;
-/*!
- Determines whether the server has been loaded or not.
-*/
+ //! Determines whether the server has been loaded or not.
void ping();
-/*!
- Name of the %container
-*/
+
+ //! Name of the %container
readonly attribute string name ;
-/*!
- Name of the machine containing this container (location of the container).
-*/
- readonly attribute string machineName ;
-/*!
- Returns True if the %container has been killed
-*/
+
+ //! working directory of the %container
+ readonly attribute string workingdir ;
+
+ //! name of the %container log file (this has been set by the launcher)
+ attribute string logfilename ;
+
+ //! Shutdown the Container process.
+ void Shutdown();
+
+ //! Returns the hostname of the container
+ string getHostName();
+
+ //! Returns the PID of the container
+ long getPID();
+
+ //! Kill the container
+ /*!
+ Returns True if the %container has been killed.
+ Kept for Superv compilation but can't work, unless oneway...
+ TO REMOVE !
+ */
boolean Kill_impl() ;
+
+ //! Create a fileRef
+ /*!
+ returns a fileRef object if origFileName exists and is readable
+ else returns null object. Only one fileRef is created for a given
+ file name, so, several calls with the same file name returns the
+ same object.
+ */
+ fileRef createFileRef(in string origFileName);
+
+ //! Create a Salome_file
+ /*!
+ returns a Salome_file object if origFileName exists and is readable
+ else returns null object.
+
+ \param origFileName name of the file to be managed (can contain the path).
+
+ \return Salome_file CORBA reference.
+ */
+ Salome_file createSalome_file(in string origFileName);
+
+ //! Create a fileTransfer
+ /*!
+ returns a fileTransfer object used to copy files from the container
+ machine to the clients machines. Only one fileTransfer instance is
+ created in a container.
+ */
+ fileTransfer getFileTransfer();
+
+ //! Copy a file from a remote host (container) to a local file
+ /*!
+ \param contai the remote container
+ \param remoteFile the file on the remote host to copy
+ \param localFile the local file to create by copy
+ */
+ void copyFile(in Container contai, in string remoteFile, in string localFile);
+
+ //! Create a PyNode in the container
+ /*!
+ \param nodeName the name of the PyNode
+ \param code python code as text to load in the node
+ */
+ PyNode createPyNode(in string nodeName, in string code) raises(SALOME::SALOME_Exception);
+
+ //! Create a PyScriptNode in the container
+ /*!
+ \param nodeName the name of the PyScriptNode
+ \param code python code as text to load in the node
+ */
+ PyScriptNode createPyScriptNode(in string nodeName, in string code) raises(SALOME::SALOME_Exception);
};
-/*! \brief Interface of the %component
- This interface is used for interaction between the %container and the %component and between
- the components inside the container.
-*/
- interface Component
+ /*! \brief Interface of the %component.
+ This interface is used for interaction between the %container and the
+ %component and between the components inside the container.
+ */
+ interface EngineComponent
{
-/*!
- The name of the instance of the %Component
-*/
+ //! The name of the instance of the %Component
readonly attribute string instanceName ;
-/*!
- The name of the interface of the %Component
-*/
+
+ //! The name of the interface of the %Component
readonly attribute string interfaceName ;
-/*!
- Determines whether the server has already been loaded or not.
-*/
+
+ //! Determines whether the server has already been loaded or not.
void ping();
-/*!
- Deactivates the %Component.
-*/
+
+ //! Get study associated to component instance
+ /*!
+ get study associated to component instance
+ \return -1: not initialised (Internal Error)
+ 0: multistudy component instance
+ >0: study id associated to this instance
+ */
+ long getStudyId();
+
+ //! Remove component instance from container
+ /*!
+ Deactivates the %Component.
+ -- TO BE USED BY CONTAINER ONLY (Container housekeeping) --
+ use remove_impl from Container instead !
+ */
void destroy() ;
-/*!
- Returns the container that the %Component refers to.
-*/
+
+ //! Returns the container that the %Component refers to.
Container GetContainerRef() ;
-/*!
- This method is used by the %SUPERVISOR component. It sets the names of the graph and of the node.
-*/
+
+ //! Set component instance properties
+ /*!
+ Gives a sequence of (key=string,value=any) to the component.
+ Base class component stores the sequence in a map.
+ The map is cleared before.
+ This map is for use by derived classes.
+ */
+ void setProperties(in FieldsDict dico);
+
+ //! Get component instance properties
+ /*!
+ returns a previously stored map (key=string,value=any) as a sequence.
+ See setProperties(in FieldsDict dico).
+ */
+ FieldsDict getProperties();
+
+ //! Set an option value
+ /*!
+ This method is to set an option specific to a certain EngineComponent.
+ */
+ void SetOption(in string optionName, in string value);
+
+ //! Return an option value
+ /*!
+ This method is to get value of an option specific to a certain EngineComponent.
+ */
+ string GetOption(in string optionName);
+
+ //! Set name of a node in a graph (for %SUPERVISOR use)
+ /*!
+ This method is used by the %SUPERVISOR component. It sets the names of
+ the graph and of the node.
+ \param aGraphName Name of graph
+ \param aNodeName Name of node
+ */
void Names( in string aGraphName , in string aNodeName ) ;
-/*!
- Returns True if the %Component has been killed.
-*/
+
+ //! Kill the component (if you can)
+ /*!
+ Returns True if the %Component has been killed.
+ */
boolean Kill_impl() ;
-/*!
- Returns True if the activity of the %Component has been stopped. (It's action can't be resumed)
-*/
+
+ //! Stop the component (if you can)
+ /*!
+ Returns True if the activity of the %Component has been stopped.
+ (It's action can't be resumed)
+ */
boolean Stop_impl() ;
-/*!
- Returns True if the activity of the %Component has been suspended. (It's action can be resumed)
-*/
+
+ //! Suspend the component
+ /*!
+ Returns True if the activity of the %Component has been suspended.
+ (It's action can be resumed)
+ */
boolean Suspend_impl() ;
-/*!
- Returns True if the activity of the %Component has been resumed.
-*/
+
+ //! Resume the component
+ /*!
+ Returns True if the activity of the %Component has been resumed.
+ */
boolean Resume_impl() ;
+
+ //! Get the cpu used
+ /*!
+ Returns the Cpu used
+ */
+ long CpuUsed_impl() ;
+
+ //! Get a python dump
+ /*!
+ Returns a python script, which is being played back reproduces
+ the data model of component
+ */
+ TMPFile DumpPython(in Object theStudy,
+ in boolean isPublished,
+ in boolean isMultiFile,
+ out boolean isValidScript);
+
+
+ //! Returns a CORBA Ref of a input Salome_file managed by a service.
+ /*!
+
+ \param service_name service's name.
+ \param file_name name of the requested file.
+
+ \return CORBA Ref of the requested file.
+
+ \exception contains informations of what if the component cannot
+ sends the file's reference.
+ */
+ Engines::Salome_file getInputFileToService(in string service_name,
+ in string Salome_file_name) raises(SALOME::SALOME_Exception);
+
+ //! Check service input files (transfer them if needed)
+ /*!
+ This method is used before the activation of the service. It calls
+ recvFiles() on all the input Salome_file files of the service.
+
+ Before each recvFiles(), it uses the callback method named configureSalome_file.
+ This method allows the user to configure the files managed by the Salome_file.
+
+ By default, there is no files managed when a Salome_file is created,
+ but the supervisor set some files managed by the Salome_file from the information contained
+ into the schema file.
+
+ \param service_name service's name.
+
+ \exception contains informations about files that are not in a good state.
+ */
+ void checkInputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
+
+ //! This method adds a input Salome_file to a service of the component.
+ /*!
+
+ \param service_name service's name.
+ \param Salome_file_name name of the Salome_file
+
+ \return a reference of the Salome_file
+
+ \exception raises an exception if there is already
+ a Salome_file with this name for the service.
+ */
+ Engines::Salome_file setInputFileToService(in string service_name,
+ in string Salome_file_name) raises(SALOME::SALOME_Exception);
+
+ //! Returns a CORBA Ref of a output Salome_file managed by a service.
+ /*!
+
+ \param service_name service's name.
+ \param file_name name of the requested file.
+
+ \return CORBA Ref of the requested file.
+
+ \exception contains informations of what if the component cannot
+ sends the file's reference.
+ */
+ Engines::Salome_file getOutputFileToService(in string service_name,
+ in string Salome_file_name) raises(SALOME::SALOME_Exception);
+
+ //! Check service output files (transfer them if needed)
+ /*!
+ This method is used at the end of the service. It calls
+ recvFiles() on all the output Salome_file files of the service.
+
+ Before each recvFiles(), it uses the callback method named configureSalome_file.
+ This method allows the user to configure the files managed by the Salome_file.
+
+ By default, there is no files managed when a Salome_file is created,
+ but the supervisor set some files managed by the Salome_file from the information contained
+ into the schema file.
+
+ \param service_name service's name.
+
+ \exception contains informations about files that are not in a good state.
+ */
+ void checkOutputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
+
+ //! This method adds an output Salome_file to a service of the component.
+ /*!
+
+ \param service_name service's name.
+ \param Salome_file_name name of the Salome_file
+
+ \return a reference of the Salome_file
+
+ \exception raises an exception if there is already
+ a Salome_file with this name for the service.
+ */
+ Engines::Salome_file setOutputFileToService(in string service_name,
+ in string Salome_file_name) raises(SALOME::SALOME_Exception);
+
+ //! Indicate if the component instance provides custom information about its objects.
+ /*!
+ Returns true if the component provides custom information about its objects, false otherwise.
+ Should be redefined in the certain component to return true in case of this
+ component provides such information.
+ */
+ boolean hasObjectInfo();
+
+ //! Get custom information about the given object.
+ /*!
+ This method is used to get the custom information about the given object.
+ Should be redefined in the certain component in case of this
+ component provides such information.
+ It is worth using this method only if hasObjectInfo() method returns true.
+
+ \param entry object's entry.
+ \param studyId study id
+
+ \return an information about the given object.
+ */
+ string getObjectInfo(in long studyId, in string entry);
} ;
-} ;
+
+ /*!
+ \brief Base interface of the %component that supports exporting data.
+ */
+ interface ImportableComponent
+ {
+ /*! \brief Get a list of supported formats */
+ SALOME::StringSeq GetImportableFormats();
+ boolean ImportDataAs(in string format, in SALOME::GenericObj exporter);
+ };
+
+ //! A block of binary data used for file transfer. The maximum size of the block is defined on server side.
+ typedef sequence<octet> fileBlock;
+
+ /*! \brief Interface of fileTransfer.
+ The fileTransfer and fileRef interfaces provide a file transfer service
+ between different computers.
+ */
+ interface fileTransfer : SALOME::GenericObj
+ {
+ //! Open the file transfer
+ /*!
+ open method returns a key (fileId) that identifies the structure
+ (ex: C FILE), associated to the original file on the server.
+ The structure is created by a container for transfer of files availables
+ on the computer which runs the container.
+ Each open gives a unique fileId, to allow concurrent reads of the same
+ File.
+ */
+ long open(in string fileName);
+ //! Open the file transfer in write mode for file fileName
+ /*!
+ \param fileName the file to copy into with putBlock
+ \return the id to use with putBlock
+ */
+ long openW(in string fileName);
+
+ //! Close the file transfer
+ /*!
+ when the file transfer is finished, close method releases structures
+ created by open method, identified by fileId.
+ */
+ void close(in long fileId);
+
+ //! Get a file data block
+ /*!
+ Get successive blocks of octets from the original file.
+ The last block is empty, and identifies the end of file.
+ */
+ fileBlock getBlock(in long fileId);
+
+ //! Put a file data block
+ /*!
+ \param fileId identification of the file obtained by openW
+ \param block a data block to copy into the file identified by fileId
+ */
+ void putBlock(in long fileId, in fileBlock block);
+
+ };
+
+ //! A file managed by a Salome_file.
+ struct file {
+ //! file name
+ string file_name;
+ //! path name
+ string path;
+ string type;
+ string source_file_name;
+ //! status ("present" or "notpresent")
+ string status;
+ long node;
+ Engines::Container container;
+ };
+
+ //! A sequence of Engines::file.
+ typedef sequence<Engines::file> files;
+
+
+ //! The state of a Salome_file.
+ struct SfState {
+ //! file name
+ string name;
+ //! hdf5 file where the file can be saved
+ string hdf5_file_name;
+ //! number of files managed
+ long number_of_files;
+ //! information if all the files are received
+ boolean files_ok;
+
+ };
+
+ /*! \brief Interface of a Salome_file managed
+ This file is independent of a Salome module. It can managed one or more
+ real files. It's useful for parallel files. Currently Salome_file cannot manage
+ two files that have the same name but not the same path.
+ */
+ interface Salome_file : Engines::fileTransfer
+ {
+ //! Load a Salome_file from a hdf5 file.
+ /*!
+
+ \param hdf5_file name (with path) of the hdf5_file.
+
+ \exception contains informations of errors if the loading doesn't succeed.
+ */
+ void load(in string hdf5_file) raises (SALOME::SALOME_Exception);
+
+ //! Save a Salome_file into a hdf5_file.
+ /*!
+
+ \param hdf5_file name (with path) of the hdf5_file.
+
+ \exception contains informations of errors if the save doesn't succeed.
+
+ */
+ void save(in string hdf5_file) raises (SALOME::SALOME_Exception);
+
+ //! Save a Salome_file into a hdf5_file.
+ /*!
+ All files that are managed are saved into the hdf5_file
+
+ \param hdf5_file name (with path) of the hdf5_file.
+
+ \exception contains informations of errors if the save doesn't succeed.
+
+ */
+ void save_all(in string hdf5_file) raises (SALOME::SALOME_Exception);
+
+/**************/
+
+ //! Add a Local file to the Salome_file.
+ /*!
+
+ \param file_name name of the file with the path.
+
+ \exception raised if the file is already added into the Salome_file.
+ */
+ void setLocalFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
+
+ //! Add a Distributed file to the Salome_file.
+ /*!
+
+ \param comp_file_name name of the file with the path.
+
+ \exception raised if the file is already added into the Salome_file.
+ */
+ void setDistributedFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
+
+ //! Connect a Salome_file with another Salome_file.
+ /*!
+ It works only if the Salome_file managed only one file
+
+ \param source_Salome_file Salome_file that managed the distributed version of the file.
+
+ \exception raised if there is more or less than one file.
+ */
+ void connect(in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
+
+ //! Connect the managed file file_name to a Salome_file.
+ /*!
+
+ \param file_name name of the file without the path.
+ \param source_Salome_file Salome_file that managed the distributed version of the file.
+
+ \exception raised if the file doesn't exist.
+ */
+ void connectDistributedFile(in string file_name,
+ in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
+
+ //! Connect the file_name with a Distributed file_name.
+ /*!
+
+ \param file_name name of the file without the path.
+ \param source_file_name It's the name of the file managed by the distributed source Salome_file.
+
+ \exception raised if the file doesn't exist.
+ */
+ void setDistributedSourceFile(in string file_name,
+ in string source_file_name) raises (SALOME::SALOME_Exception);
+
+/**************/
+
+ //! Get all the distributed files managed by the Salome_file and check all the local files.
+ /*!
+
+ \exception raised if some of the files are not ok.
+ */
+ void recvFiles() raises (SALOME::SALOME_Exception) ;
+
+/**************/
+
+ //! Remove a file of the Salome_file.
+ /*!
+
+ \param file_name name of the file.
+
+ \exception raised if the file doesn't exist.
+ */
+ void removeFile(in string file_name) raises (SALOME::SALOME_Exception);
+
+ //! Remove all the files of the Salome_file.
+ void removeFiles();
+
+/**************/
+
+ //! Get the list of the files managed by the Salome_file.
+ /*!
+ The list can be empty.
+ */
+ Engines::files getFilesInfos();
+
+ //! Get a file managed by the Salome_file.
+ /*!
+
+ \param file_name the name of the file.
+
+ \return CORBA file reference.
+
+ \exception raised if the file doesn't exist.
+ */
+ Engines::file getFileInfos(in string file_name) raises (SALOME::SALOME_Exception);
+
+ //! Return the state of the Salome_file.
+ Engines::SfState getSalome_fileState();
+
+
+ //! Set the container where files are.
+ /*!
+
+ \param container container CORBA's reference.
+ */
+ void setContainer(in Engines::Container container);
+ };
+
+ /*! \brief Interface of fileRef.
+ The fileTransfer and fileRef interfaces provide a file transfer service
+ between different computers.
+
+ A fileRef object is associated to an original file (origFileName) on a
+ machine (refMachine).
+ It is created by a container (factoryServer) on refMachine,
+ with createFileRef(in string origFileName) method.
+ The fileRef object maintains a list of (machine,filename) for copies.
+ If a copy exists on myMachine, getRef(myMachine) returns the file name
+ of the copy on myMachine, else returns empy string.
+ If there is no copy on myMachine, method getFileTransfer() from container
+ factoryServer on refMachine provides a fileTransfer object dedicated to
+ CORBA file copy.
+ After the copy, addRef(myMachine, localFileNameOnMyMachine) registers
+ the file name of the copy on myMachine.
+ */
+ interface fileRef
+ {
+ //! the original file
+ readonly attribute string origFileName;
+ //! the machine of the original file
+ readonly attribute string refMachine;
+
+ Container getContainer();
+
+ boolean addRef(in string machine,
+ in string fileName);
+
+ string getRef(in string machine);
+ };
+};
#endif
