-Composant Salomé
+SALOME component
================
-
-
-Principe
---------
-
-Un composant Salomé est un composant CORBA tel que décrit au chapitre
-précédent, utilisant des services du noyau Salomé. Il faut également "déclarer"
-ce composant auprès de Salomé (i.e. fournir ou compléter des fichiers de
-ressources Salomé avec des informations relatives à ce composant). Les
-différentes opérations à effectuer sont :
-
-1. adapter le fichier IDL,
-
-2. déclarer le composant auprès du catalogue de modules de Salomé,
-
-3. modifier la classe d'implémentation (C++ ou python) pour
-
- - suivre l'adaptation du fichier IDL (point 1),
- - permettre la supervision du composant par Salomé, dans les différents services du composant.
- - préparer l'utilisation du service de notification (envoi de messages pour suivre
- le déroulement des calculs dans le composant) - optionel (mais utile),
-
-4. déclarer les éventuelles ressources graphiques.
-
-
-Fichier IDL
+Principle
-----------
+A SALOME component is a CORBA component as described in the previous chapter, using services of the SALOME kernel.
+This component also has to be “declared” to SALOME (i.e. SALOME resource files need to be supplied or completed with
+information about this component). The following operations need to be carried out:
+1. adapt the IDL file
+2. declare the component to the SALOME modules catalog
+3. modify the implementation class (C++ or python) to
-Principe
-^^^^^^^^
-
-La description IDL est semblable à celle d'un composant CORBA standard avec les
-particularités :
-
-* le composant doit faire partie du module (CORBA) de base ``Engines``,
-
-* le composant doit hériter du composant de base de Salomé :
- ``Engines::Component`` (défini dans le fichier IDL ``"SALOME_Component.idl"``),
-
-* les services du composant peuvent avoir des paramètres ``in``, ``out``
- et/ou une valeur de retour, mais pas de paramètres ``inout``.
+ - monitor adaptation of the IDL file (point 1)
+ - enable supervision of the component by SALOME, in the different component services
+ - prepare use of the notification service (send messages to monitor execution of calculations in the component) – optional (but useful)
+4. Declare any graphic resources
-**Remarques**
-
- #. Le module ``Engines`` regroupe tous les composants de Salomé, autres que les
- composants centraux de Salomé.
+IDL file
+-----------
+Principle
+^^^^^^^^^^^^
+The IDL description is similar to the description of a standard CORBA component with the following special features:
- #. Le composant de base ``Engines::Component`` permet de ne pas devoir
- redéfinir pour chaque composant ajouté au système, les services communs (arrêt,
- reprise, etc.).
+- the component must form part of the basic ``Engines`` module (CORBA)
+- the component must inherit from the SALOME basic component: ``Engines::EngineComponent`` (defined in the IDL ``“SALOME_Component.idl”`` file)
+- the services of the component may have ``in``, ``out`` parameters and /or a return value, but no ``inout`` parameters.
- #. Ceci n'est pas une limitation, un paramètre ``inout`` peut se découpler en
- un paramètre ``in`` et un paramètre ``out`` (de toute façon, c'est sous cette
- forme que le verront les clients python).
+**Notes**
+#. The ``Engines`` module includes all SALOME components other than the SALOME central components
+#. The ``Engines::EngineComponent`` basic component avoids the need to redefine common services (stop, restart, etc.) for each
+ component added to the system
+#. This is not a limitation, an ``inout`` parameter can be decoupled into an ``in`` parameter and an ``out``
+ parameter (in any case, this is the form in which python clients will see it).
-Exemple 9 (début)
+Example 9 (start)
^^^^^^^^^^^^^^^^^
-
-Reprenons le fichier IDL ``alglin.idl`` et adaptons-le :
-
+We will reuse the ``alglin.idl`` file and adapt it:
``alglin.idl``
.. include:: ./exemples/exemple9/alglin.idl
:literal:
-**Remarque**
- Il faut faire attention quand on définit des structures dans l'IDL (comme la
- structure ``vecteur`` dans ``alglin.idl``). Le nom choisi ``vecteur`` risque
- d'être déjà "réservé" par un autre composant Salomé.
-
-
-Exemple 10 (début)
+**Note**
+ It is important to take care when structures are defined in the IDL (like the ``vecteur`` structure in ``algin.idl``).
+ The chosen name ``vecteur`` might be “reserved” by another SALOME component.
+
+Example 10 (start)
^^^^^^^^^^^^^^^^^^
-
-Des modifications analogues sont effectuées sur le fichier IDL ``FreeFem.idl`` :
-
+Similar modifications are made on the IDL ``FreeFem.idl`` file:
``FreeFem.idl``
:literal:
-Inscription au catalogue de modules
------------------------------------
-
-Pour être utilisables dans Salomé, les composants doivent s'inscrire auprès de
-l'un des catalogues de modules de Salomé. Ce catalogue est réparti entre
-plusieurs fichiers (catalogue général, catalogue utilisateur). On supposera
-que le composant sera déclaré dans le catalogue personnel d'un utilisateur.
-Le fichier de catalogue de composants est un fichier XML qui contient
-
-#. la liste des services du composant et leurs paramètres,
-
-#. la (les) machine(s) où le composant peut être chargé en mémoire, le nom du
- fichier contenant l'icone du composant, des informations de version,
- commentaires, service par défaut, etc (ces informations sont optionelles).
+Registration into the modules catalog
+--------------------------------------------
+Before they can be used in SALOME, components must be registered in one of the SALOME modules catalogs. This catalog is
+distributed in several files (general catalog, user catalog). It will be assumed that the component will be declared in
+a user's personal catalog. The component catalog file is an XML file that contains:
-On peut compléter à la main ce catalogue ou utiliser un utilitaire fourni par
-Salomé qui génère les informations du point 1 ci-dessus (il faudra malgré tout
-éditer le fichier pour entrer les informations du point 2). Cet outil est
-disponible dans l'interface graphique Salomé (menu ``Tools->Catalog Generator``)
-en indiquant le nom du catalogue (fichier XML) et le nom du fichier IDL du
-composant.
+#. the list of services of the component and their parameters
+#. the name of the file containing the icon of the component, version information, comments, default service, etc. (this information is optional).
+This catalog can be completed by hand or a utility supplied by SALOME can be used that generates information in
+point 1 above (nevertheless, this file must be edited to enter information in point 2). This tool is available in
+the SALOME graphic interface (``Tools->Catalog Generator`` menu) indicating the name of the catalog (XML file) and
+the name of the IDL file of the component.
-Classe d'implémentation C++
+C++ implementation class
---------------------------
+**In this section, it will be assumed that the IDL file defines a CORBA class: A and that the C++ implementation class A_impl will be used.**
-**On supposera dans ce paragraphe, que le fichier IDL définit une classe CORBA :
-A et qu'on utilisera la classe d'implémentation C++ : A_impl.**
-
-
-Mise en conformité avec l'IDL du composant
+Making conforming with the component IDL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Proceed as follows to adapt the standard CORBA / C++ implementation classes (as seen in the previous chapter):
-Pour adapter les classes d'implémentation CORBA/C++ standards (telles que vues
-au chapitre précédent), il faut :
-
-#. insérer le fichier ``SALOMEconfig.h`` : ::
+#. Insert the ``SALOMEconfig.h`` file that contains a number of useful definitions to make the code of the implementation
+ class independent from the CORBA version used::
- #include <SALOMEconfig.h>
+ #include <SALOMEconfig.h>
- Le fichier ``SALOMEconfig.h`` contient un certain nombre de définitions utiles
- pour assurer l'indépendance du code de la classe d'implémentation par rapport à
- la version de CORBA utilisée.
+#. then insert the ``SALOME_Component_i.hxx`` file that contains the interface of the C++ implementation class of the SALOME basic component::
-#. insérer ensuite le fichier ``SALOME_Component_i.hxx`` ::
+ #include "SALOME_Component_i.hxx"
- #include "SALOME_Component_i.hxx"
+#. for the CORBA class that is implemented, add the following line::
- qui contient l'interface de la classe d'implémentation C++ du composant de base
- de Salomé
+ #include CORBA_SERVER_HEADER(A)
-#. pour la classe CORBA qui est implémentée, ajouter la ligne : ::
+ ``CORBA_SERVER_HEADER`` is a macro defined in ``SALOMEconfig.h`` that makes CORBA inclusion file names independent
+ from the CORBA implementation used.
- #include CORBA_SERVER_HEADER(A)
+#. for each CORBA class used in the implementation class, add the following line::
- ``CORBA_SERVER_HEADER`` est une macro définie dans ``SALOMEconfig.h`` et qui
- assure l'indépendance des noms de fichiers d'inclusion CORBA par rapport à
- l'implémentation de CORBA utilisée.
+ #include CORBA_CLIENT_HEADER(<CORBA class name>)
-#. pour chaque classe CORBA qui est utilisée dans la classe d'implémentation,
- ajouter la ligne : ::
+ ``CORBA_CLIENT_HEADER`` is a macro defined in ``SALOMEconfig.h`` that makes CORBA inclusion file names independent
+ from the CORBA implementation used.
- #include CORBA_CLIENT_HEADER(<nom de la classe CORBA>)
-
- ``CORBA_CLIENT_HEADER`` est une macro définie dans ``SALOMEconfig.h`` et qui
- assure l'indépendance des noms de fichiers d'inclusion CORBA par rapport à
- l'implémentation de CORBA utilisée.
-
-#. faire dériver la classe d'implémentation de celle du composant Salome de
- base : ::
+#. derive the implementation class from the class of the basic SALOME component::
class A_impl :
public POA_Engines::A,
public Engines_Component_i {
-#. définir le (seul) constructeur de la façon suivante dans le fichier d'entête
- C++ (.hxx) : ::
+#. define the (sole) constructor as follows in the C++ header file (.hxx)::
A_impl(CORBA::ORB_ptr orb,
PortableServer::POA_ptr poa,
const char *instanceName,
const char *interfaceName);
- et dans le fichier d'implémentation C++ (.cxx) : ::
+ and in the C++ implementation file (.cxx)::
A_impl:: A_impl
(CORBA::ORB_ptr orb,
_id = _poa->activate_object(_thisObj);
}
- Ce constructeur sera éventuellement responsable de la création et de
- l'initialisation de l'objet interne associé au composant CORBA.
+ This constructor may possibly be responsible for creation and initialisation of the internal object associated with the CORBA component.
-#. si des structures sont définies par le fichier IDL dans le module Engines,
- adapter les déclarations des méthodes de la classe d'implémentation.
-
-L'exemple ci-dessus illustre les modifications effectuées sur l'exemple 6.
+#. If structures are defined by the IDL file in the Engines module, adapt declarations of the implementation class methods.
+The above example illustrates the modifications made on example 6.
+
.. _remsuper:
-
-Permettre la supervision du composant
+Enable component supervision
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following needs to be inserted in each service of the component (i.e. in each method of the implementation class
+called during a CORBA request), before the component can be controlled from supervision.
-Pour pouvoir piloter le composant depuis la supervision, il faut insérer dans
-chaque service du composant (i.e. dans chaque méthode de la classe
-d'implémentation qui est appelée lors d'une requète CORBA),
-
-* au début, l'instruction : ::
+- at the beginning, the instruction::
beginService(<nom du service>);
-* à la fin, l'instruction : ::
+- at the end, the instruction::
endService(<nom du service>);
-Ces deux instructions signalent à la supervision de Salomé que le service du
-composant a bien reçu la requète CORBA (beginService) et que l'exécution du
-service s'est bien terminée (endService).
+These two instructions notify the SALOME supervision that the component service has actually received the CORBA request (beginService)
+and that execution of the service has actually terminated (endService).
-**Remarque**
- Mettre beginService et endService
- dans les méthodes de la classe d'implémentation d'un composant déclare à Salomé
- que le composant est "supervisable". Ce n'est pas une assurance que l'on pourra
- utiliser ce composant sans précautions dans le cas où le composant possède un
- état interne modifié par un ou plusieurs services.
-
- **Exemple**
- On considère un composant ayant une variable interne ``Quantite`` et deux services :
+**Note**
+ Put beginService and endService in the methods of the implementation class of a component declares to SALOME that the component
+ is "supervisable”. This is not an assurance that this component can be used without precautions in the case in which the
+ component has an internal state modified by one or more services.
- * ``S1(x) : Quantite = Quantite + x;`` retourne ``Quantite`` et
+ **Example**:
+ Consider a component with an internal variable ``Quantity`` and two services:
- * ``S2(x) : Quantite = Quantite * x;`` retourne ``Quantite``.
+ * ``S1(x): Quantity = Quantity + x;`` returns ``Quantity`` and
+ * ``S2(x) : Quantity = Quantity * x ;`` returns ``Quantity``.
- Il n'est pas possible *a priori* de connaître la valeur de ``Quantite`` après
- exécution du graphe de calcul sur la figure suivante.
+ *A priori*, it is impossible to know the value of ``Quantity`` after the calculation graph on the following figure has been executed.
.. _figpara:
.. image:: images/parallele.png
- :width: 26ex
:align: center
.. centered::
- Graphe de calcul contenant des branches parallèles
+ Calculation graph containing parallel branches
-Utilisation de la notification
+Using the notification
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Pour signaler l'utilisation de la notification (qui provoquera l'ouverture
-d'une connexion à un canal d'événements), il faut modifier le constructeur de
-la classe d'implémentation comme suit : ::
+The constructor of the implementation class must be modified as follows, so as to signal use of the notification (that will
+cause opening of a connection to an events channel)::
A_impl:: A_impl
(CORBA::ORB_ptr orb,
_id = _poa->activate_object(_thisObj);
}
-où on a ajouté le paramètre "1" à la fin de l'appel du constructeur de
-``Engines_Component_i``. Le composant pourra ensuite utiliser l'instruction
-::
+in which the parameter “1” has been added to the end of the call to the ``Engines_Component_i`` of the constructor.
+The component can then use the instruction::
void sendMessage(const char *event_type, const char *message);
-pour envoyer des messages indiquant le déroulement du calcul ou une situation
-anormale, etc. Ces messages seront visibles de l'utilisateur de Salomé. Le
-premier paramètre indique le type de message ("warning", "step", "trace",
-"verbose"), le second paramètre, le contenu (chaîne de caractères) du message.
-
+to send messages indicating progress with the calculation or an abnormal situation, etc. These messages will be visible to the
+SALOME user. The first parameter indicates the message type (“warning”, “step”, “trace”, “verbose”), and the second parameter
+indicates the message contents (character string).
-Connexion à l'objet "fabrique" d'un conteneur
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Afin de permettre le chargement et l'initialisation d'un composant par un
-conteneur, il faut fournir une fonction C dont le nom et le code sont imposés :
-::
+Connection to the “factory” object of a container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A “C” function has to be provided with an imposed name and code, for a component to be loaded and initialised by a container::
extern "C"
{
}
}
-``<nom du composant>`` (ou nom de la classe CORBA, ``A`` ici) et ``<classe
-d'implementation>`` (``A_impl`` ici) sont spécifiques à chaque composant.
-Cette fonction est appelée par le conteneur lors du chargement d'un composant.
-Elle crée un objet CORBA qui réceptionnera les requètes au composant et les
-transmettra au différents services du composant.
-
-
-Exemple 9 (suite)
-^^^^^^^^^^^^^^^^^
-
-Reprenons les fichiers d'implémentation ``alglin_i.hxx`` et ``alglin_i.cxx``
-et adaptons-les :
+``<component name>`` (or CORBA class name, ``A`` in this case) and ``<implementation class>`` (``A_impl`` here) are specific
+to each component. This function is called by the container when a component is loaded. It creates a CORBA object that
+will receive requests to the component and will forward them to the different services of the component.
+Example 9 (continued)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+We will use the implementation files ``algin_i.hxx`` and ``algin_i.cxx`` again and adapt them:
``alglin_i.hxx``
.. include:: ./exemples/exemple9/alglin_i.cxx
:literal:
-
-Classe d'implémentation python
+Python implementation class
------------------------------
+**In this section, it is assumed that the IDL file defines a CORBA class: B and that we will use the python implementation class: B.**
-**On supposera dans ce paragraphe, que le fichier IDL définit une classe CORBA :
-B et qu'on utilisera la classe d'implémentation python : B.** La démarche
-est analogue au cas de l'interface serveur C++ :
-
+The procedure is similar to the case of the C++ server interface:
-Mise en conformité avec l'IDL du composant
+Making conforming with the component IDL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-#. importer la classe du composant de base : ::
+#. import the class of the basic component::
from SALOME_ComponentPy import *
-#. faire dériver la classe d'implémentation de celle du composant Salome de
- base : ::
+#. derive the implementation class from the class of the basic SALOME component::
class B(Engines__POA.B,
SALOME_ComponentPy_i):
-#. le constructeur de la classe d'implémentation doit débuter par : ::
+#. The constructor of the implementation class must begin by::
def __init__(self, orb, poa, this, containerName,
instanceName, interfaceName):
SALOME_ComponentPy_i.__init__(self, orb, poa, this,
containerName, instanceName,
- interfaceName, 0)
+ interfaceName, False)
-
-Permettre la supervision du composant
+Enable supervision of the component
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Before the component can be controlled from supervision, the following have to be inserted in each service of the
+component (i.e. in each method of the implementation class called during a CORBA request).
-Pour pouvoir piloter le composant depuis la supervision, il faut insérer dans
-chaque service du composant (i.e. dans chaque méthode de la classe
-d'implémentation qui est appelée lors d'une requète CORBA),
-
-* au début, l'instruction : ::
+* at the beginning, the instruction::
- beginService(<nom du service>);
+ beginService(<service name>);
-* à la fin, l'instruction : ::
+* at the end, the instruction::
- endService(<nom du service>);
+ endService(<service name>);
-Ces deux instructions signalent à la supervision de Salomé que le service du
-composant a bien reçu la requète CORBA (beginService) et que l'exécution du
-service s'est bien terminée (endService). Même remarque que dans le cas C++
-(:ref:`remsuper`)
+These two instructions notify the SALOME supervision that the component service has actually received the CORBA
+request (beginService) and that execution of the service has actually terminated (endService).
+Same comment as in the C++ case (:ref:`remsuper`).
-
-Utilisation de la notification
+Using the notification
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Pour signaler l'utilisation de la notification, il faut modifier le
-constructeur de la classe d'implémentation comme suit : ::
+The implementation class constructor should be modified as follows to signal use of the notification::
def __init__(self, orb, poa, this, containerName,
instanceName, interfaceName):
SALOME_ComponentPy_i.__init__(self, orb, poa, this,
containerName, instanceName,
- interfaceName, 1)
+ interfaceName, True)
-où on a ajouté le paramètre "1" à la fin de l'appel du constructeur de
-``SALOME_ComponentPy_i``. Le composant pourra ensuite utiliser l'instruction
-::
+in which the parameter “1” is added to the end of the call to the ``SALOME_ComponentPy_i`` of the constructor.
+The component can then use the following instruction::
sendMessage(event_type, message);
-pour envoyer des messages indiquant le déroulement du calcul ou une situation
-anormale, etc. Ces messages seront visibles de l'utilisateur de Salomé. Le
-premier paramètre indique le type de message ("warning", "step", "trace",
-"verbose"), le second paramètre, le contenu (chaîne de caractères) du message.
+to send messages providing information about progress with the calculation or an abnormal situation, etc.
+These messages will be visible to the SALOME user. The first parameter indicates the message
+type (“warning”, “step”, “trace”, “verbose”), and the second parameter indicates the message contents (character string).
-Exemple 10 (suite)
-^^^^^^^^^^^^^^^^^^
-
-Reprenons le fichier d'implémentation ``FreeFem.py`` et adaptons le :
-
+Example 10 (continued)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Consider the ``FreeFem.py`` implementation file and adapt it:
``FreeFemComponent.py``
:literal:
-Utilisation de l'environnement de compilation et d'exécution de Salomé
+Using the SALOME compilation and execution environment
-----------------------------------------------------------------------
+Autotools like SALOME will be used.
-On utilisera les autotools comme Salomé.
-
-Utilisation des structures de données fournies par Salomé ou renvoyées par le composant
+Using data structures provided by SALOME or returned by the component
---------------------------------------------------------------------------------------
+This part will be done with reference to CORBA [CORBA]_ specifications, and particularly IDL specifications – languages [LANG]_
+or the different CORBA manuals, for example [HENVIN]_ (C++) and [PyCorba]_ (python).
-Pour cette partie, on se référera aux spécifications CORBA [CORBA]_, et en
-particulier les spécifications IDL - langages [LANG]_ ou aux différents
-manuels CORBA, par exemple [HENVIN]_ (C++) et [PyCorba]_ (python).
-
-
-Maillages et champs MED
+Meshes and MED fields
^^^^^^^^^^^^^^^^^^^^^^^
-
-Pour cette partie, on se réfèrera à la documentation de MED et MEDMemory
-[MEDDoc]_ et [MEDMemory]_.
+This part will be done with reference to MED and MEDMemory documentation [MEDDoc]_ and [MEDMemory]_.
