.. _secetapes:
-Etapes dans l'intégration d'un composant
+Steps in integration of a component
========================================
+Concept of component
+-----------------------
+There are many definitions of the software component. We will use the following for SALOME:
+**Component**
-Notion de composant
--------------------
+ A component is a software entity with the following characteristics and behaviours:
-Il existe de nombreuses définitions de composant logiciel. Dans le cadre de
-Salomé, nous retiendrons la suivante :
+ - **physically identifiable**: in other words a component is not a concept or a design “pattern”, but
+ is a “genuine” portion of binary code and can be directly executed (or interpreted) after deployment;
+ - **composable**: it must be possible to create a relation between a component and other components: it has
+ one (or several) interfaces that interact like communication channels between components;
+ - one component **interacts with the other components** only through its interface(s);
+ - a component is **integrated into an application architecture** by a deployment process.
+ This deployment process is dependent on the hardware and software platform sub-tending the architecture
-**Composant**
-
- Un composant est une entité logicielle possédant les caractéristiques et les comportements suivants :
-
- * **physiquement identifiable**, c'est à dire qu'un composant n'est pas un
- concept ou un "pattern" de conception mais un "vrai" morceau de code binaire,
- directement exécutable - ou interprétable - après déploiement ;
-
- * **composable**, un composant doit pouvoir être mis en relation avec d'autres
- composants : il expose une - ou plusieurs - interfaces qui agissent comme des
- canaux de communication entre composants ;
-
- * un composant **interagit avec les autres composants** uniquement au travers
- de sa (ou ses) interface(s);
-
- * un composant est **intégré dans une architecture** applicative par un
- processus de déploiement. Ce processus de déploiement est dépendant de la
- plate-forme matérielle et logicielle sous-tendant l'architecture ;
-
-
-Schéma général
+General scheme
--------------
.. index:: single: architecture
-L'intégration d'un code de calcul sous forme de composant dans l'architecture
-PAL se fait en plusieurs étapes, schématisées par la figure suivante :
+A calculation code is integrated in the form of a component in the PAL architecture in several steps, diagrammatically
+represented by the following figure:
.. image:: images/phases.png
- :width: 56ex
:align: center
-.. centered:: Phases d'intégration d'un composant
-
+.. centered:: Component integration phases
-Pour utiliser le composant :
+To use the component:
-* localement, via un interpréteur python, il faudra écrire une interface python
- via des outils tels que **SWIG** [SWIG]_ ou **Boost** [BOOST]_;
-
-* à distance, à travers CORBA [CORBA]_, il faudra écrire une interface CORBA
- (fichier IDL, classe d'implémentation), Salomé offrant des services permettant
- de simplifier l'utilisation de CORBA;
-
-* via l'application SALOME, il faudra spécialiser les fichiers écrits au point
- précédent et spécifier les fichiers de ressources éventuels (graphiques et
- autres).
-
-
-Code de départ
+- locally through a python interpretor, a python interface needs to be written using tools such as **SWIG** [SWIG]_ or **Boost** [BOOST]_;
+- remotely through CORBA [CORBA]_, a CORBA interface (IDL file, implementation class) must be written. SALOME offers services that can simplify the use of CORBA;
+- through the SALOME application, files written according to the above point must be specialised and resource files, if any, must be specified (graphic and other).
+
+Initial code
--------------
+Specific cases may differ widely, depending on the form of the code to be integrated in SALOME.
+In this document, we will consider situations in which we initially have:
-Les cas de figures peuvent être très différents les uns des autres suivant la
-forme du code à intégrer dans Salomé. Dans ce document, on envisagera les
-situations dans lesquelles on dispose au départ :
-
-* d'un code sous forme d'un ou plusieurs exécutables séparés.
-
-* d'un ensemble de fonctions f77/routines C/classes C++.
-
-* d'un ensemble de scripts python, qui contrôlent éventuellement des routines,
- fonctions ou classes f77/C/C++.
-
+- a code in the form of one or several separate executables
+- a set of f77 functions / C routines / C++ classes
+- a set of python scripts that can control f77 / C / C++ routines, functions or classes.
.. _compinterne:
-Mise sous forme d'objet interne
--------------------------------
-
-.. index:: single: objet interne
+Putting the initial code in the form of an internal object
+----------------------------------------------------------------
-Pour simplifier les phases suivantes, un premier travail consiste à présenter
-le code de départ sous la forme d'un objet C++ ou python.
+.. index:: single: internal object
+A first work to simplify the next phases consists of presenting the initial code in the form of a C++ or python object.
-**objet interne**
+**internal object**
- Cet objet C++ ou python sera appelé "**objet interne**" dans ce document. Il sera composé de
- méthodes et d'attributs, publics et privés (suivant la terminologie standard
- orientée-objet) :
+ This C++ or python object will be called "**internal object**" in this document. It will be composed of
+ public or private methods and attributes (according to the standard object oriented terminology):
- .. index:: single: méthodes; publiques
+ .. index:: single: methods; public
- * les **méthodes publiques** sont les services de calcul que l'on veut rendre
- disponibles aux utilisateurs de l'objet interne,
+ - **public methods** are calculation services that are to be made available to users of the internal object
- .. index:: single: attributs; publics
+ .. index:: single: attributes; public
- * les **attributs publics** sont les données de l'objet que l'on veut rendre
- disponibles aux utilisateurs de cet objet interne,
+ - **public attributes** are object data that are to be made available to users of this internal object
.. index::
- single: méthodes; privées
- single: attributs; privés
+ single: methods; private
+ single: attributes; private
- * les **méthodes et attributs privés** sont les services et les données de
- l'objet interne que l'on ne veut pas rendre disponibles aux utilisateurs de
- l'objet interne (et qui ne seront visibles que des autres méthodes de ce même
- objet).
+ - **private methods and attributes** are services and data of the internal object that are not to be
+ made available to users of the internal object (and that will only be visible from other methods of this object).
.. index::
- single: etat interne
+ single: internal state
single: common fortran77
- single: variables globales
-
-**Remarques**
-
- 1. La distinction "public/privé" n'a pas réellement de sens en python où tout
- est public par défaut.
+ single: global variables
- 2. L'objet interne est vu de l'utilisateur comme un ensemble de méthodes
- publiques (par ex. services de calcul) qui délèguent les requêtes au code
- encapsulé (voir figures :ref:`Objet interne englobant le code initial <figinterne1>`,
- :ref:`Objet interne communicant avec un code extérieur <figinterne2>` et
- :ref:`Code initial déjà sous forme d'objet interne <figinterne3>`.
+**Notes**
- 3. Entre 2 appels successifs de services de l'objet, les attributs gardent la
- "mémoire de l'objet" (l'état interne, par exemple : common fortran77 ou
- variables globales [#f1]_ C/C++).
+1. The “public/private” distinction is not really meaningful in Python, in which everything is public by default.
+2. The user sees the internal object as a set of public methods (e.g. calculation services) that delegate requests to the encapsulated code (see the :ref:`Internal object embedding the initial code <figinterne1>`, :ref:`Internal object communicating with an external code <figinterne2>` and :ref:`Initial code already in the form of an internal object <figinterne3>` figures)
+3. Attributes keep the “object memory” between 2 successive calls to object services (internal state, for example fortran77 common or C/C++ global variables [#f1]_).
.. index::
- single: service; de l'objet interne
- single: etat interne
+ single: service; internal object
+ single: internal state
-La première partie du travail, une étape de conception, consiste à définir les
-services et l'état interne de cet objet. En particulier :
+The first part of the work, a design step, consists of defining the services and the internal state of this object. In particular:
-* choisir les différents services,
+- choose the different services,
+- for each service, define input and output data,
+- for each input and each output, define the data type and also the associated pre-conditions and post-conditions,
+- define the internal state of the object and possibly its value before and after the call to the different services.
-* pour chaque service, définir les données d'entrée et de sortie
+Depending on the case, the internal object may:
-* pour chaque entrée et chaque sortie, définir le type de la donnée et
- éventuellement les pré-conditions et post-conditions associées,
-
-* définir l'état interne de l'objet et éventuellement sa valeur avant et après
- l'appel aux différents services.
-
-Suivant les cas, l'objet interne pourra :
-
-* "englober" le code initial, c'est le cas d'un code initial sous forme d'une
- librairie ou dont le code source est disponible;
+* “encompass” the initial code, this is the case for an initial code in the form of a library or for which the source code is available;
.. _figinterne1:
.. image:: images/objint1.png
- :width: 40ex
:align: center
- .. centered:: Objet interne englobant le code initial
+ .. centered:: Internal object encompassing the initial code
-* communiquer avec le code source via le système d'exploitation (Unix, Windows,
- etc), c'est le cas d'un code initial sous la forme d'un exécutable binaire;
+* communicate with the source code through the operating system (Unix, Windows, etc.), this is the case for an initial code
+ in the form of a binary executable:
.. _figinterne2:
.. image:: images/objint2.png
- :width: 58ex
:align: center
- .. centered:: Objet interne communicant avec un code extérieur
+ .. centered:: Internal object communicating with an external code
- **Remarque**
- La communication avec le code extérieur binaire pourra se faire par fichiers, ou
- par la ligne de commandes, par exemple.
+ **Note**: The communication with the binary external code may be made through files, or for example through the command line.
-* dans le cas où le code initial est déjà sous la forme d'une classe python, il
- n'y a rien à faire.
+* if the initial code is already in the form of a python class, there is nothing to be done.
.. _figinterne3:
.. image:: images/objint3.png
- :width: 36ex
:align: center
- .. centered:: Code initial déjà sous forme d'objet interne
-
+ .. centered:: Initial code already in the form of an internal object
-
-Accès depuis un interpréteur python local
+Access from a local python interpreter
-----------------------------------------
-
-L'objet C++/python construit au paragraphe (:ref:`compinterne`)
-peut être enrobé dans un composant manipulé depuis un
-interpréteur python local, suivant la figure suivante.
+The C++/python object constructed in the (:ref:`compinterne`) section may be embedded in a component manipulated from a
+local python interpreter as shown on the following figure.
.. _python_local:
.. image:: images/accesLocal.png
- :width: 46ex
:align: center
-.. centered:: Accès depuis un interpréteur python local
+.. centered:: Access from a local python interpreter
-Suivant le type et l'implémentation de l'objet interne (C++ ou python), il
-faudra ou non fournir une interface. Des outils tels que **swig**
-ou **boost** permettent de simplifier cette tâche [#f2]_.
+It may or may not be necessary to provide an interface, depending on the type and implementation of the
+internal object (C++ or python). Tools such as **swig** and **boost** can simplify this task [#f2]_.
-
-Accès depuis CORBA
+Access from CORBA
------------------
+An interface has to be provided to enable a remote access to the component through CORBA, independently of the access from
+a local python interpreter. Operation of CORBA as a client-server is selected as shown in the figure
+:ref:`Access from CORBA <figaccescorba>`, which shows communication between a client and a server through CORBA.
+
+**CORBA server**
+ A server is an executable, for the purposes of this document and in the SALOME environment.
+ It is connected to a communication channel called a CORBA bus that transmits requests to it and to which
+ the server returns the results of these requests. A server can host several CORBA objects to which it delegates
+ execution of these requests. The CORBA client-server relation is specified by an interface file called the **IDL file**.
+ This represents a contract between the component and the clients that use the component.
-Indépendamment de l'accès depuis un interpréteur python local, il faut fournir
-une interface permettant un accès distant au composant via CORBA. Le
-fonctionnement de CORBA retenu est celui de client-serveur comme illustré par la
-figure :ref:`Accès depuis CORBA <figaccescorba>` où on représente la
-communication entre un client et un serveur via CORBA.
-
-**Serveur CORBA**
- Dans ce document et
- dans l'environnement Salomé, un serveur est un exécutable. Il est branché sur
- un canal de communication appelé bus CORBA qui lui transmet des requêtes et
- vers lequel le serveur renvoie les résultats de ces requêtes. Un serveur peut
- héberger plusieurs objets CORBA auxquels il délègue l'exécution des requêtes.
- La relation client-serveur CORBA est spécifiée par un fichier d'interface, dit
- **fichier IDL**. Celui-ci représente un contrat entre le composant et les
- clients qui utilisent le composant.
-
-Les composants dans ce mode de
-fonctionnement seront des objets CORBA. La relation serveur - composant sera
-précisée au paragraphe :ref:`contfab`.
-
-**Remarque**
- Le respect du fichier IDL par le
- client et le serveur conditionne la bonne exécution des requêtes. Pour cette
- raison, dans Salomé, les différents fichiers IDL sont rassemblés dans des
- répertoires vus par tous les clients et serveurs CORBA.
+In this operating mode, the components will be CORBA objects. The server – component relation will be specified
+in the :ref:`contfab` paragraph.
+
+**Note**: Requests cannot be executed correctly unless the client and the server respect the IDL file. This is why
+in SALOME, the different IDL files are assembled in directories seen by all CORBA clients and servers.
.. _figaccescorba:
.. image:: images/accesCorba.png
- :width: 58ex
:align: center
-.. centered:: Accès depuis CORBA
-
-L'intégrateur de code doit fournir une partie de l'interface serveur du
-composant, sous forme d'une classe dite d'**implémentation** (démarche
-similaire en python et C++, côté serveur). Le reste de l'interface est générée
-à partir du fichier d'interface IDL. Du côté des clients, par contre,
-l'interface CORBA est presque entièrement générée (particulièrement si le
-client est écrit en python).
-
+.. centered:: Access from CORBA
-Particularités de l'environnement Salomé
-----------------------------------------
+The code integrator must provide a part of the component server interface in the form of a so-called **implementation**
+class (similar procedure in python and C++, at the server end). The remainder of the interface is generated
+from the IDL interface file. On the other hand, the CORBA interface is generated almost entirely at the client
+end (particularly if the client is written in Python).
-
-Services de Salomé
+Specific features of the SALOME environment
+------------------------------------------------
+SALOME services
^^^^^^^^^^^^^^^^^^
+SALOME provides a number of services above CORBA that simplify its use. For example:
-Salomé fournit un certain nombre de services au-dessus de CORBA permettant de
-simplifier son utilisation. On citera:
-
-
-L'accès au service de nommage:
+Access to the naming service
""""""""""""""""""""""""""""""
-
-Une IOR (référence CORBA) est un pointeur distant, dont le maniement n'est pas
-toujours aisé. Un exemple d'IOR est le suivant : ::
+An IOR (CORBA reference) is a remote pointer, which is not always easy to handle. The following is an example of an IOR::
IOR:010000003400000049444c3a6174742e636f6d2f4174744e6f74696669
636174696f6e2f4576656e744368616e6e656c466163746f72793a312e3000
010000000000000026000000010100000a0000003132372e302e302e310006
800e000000fedd112a3d000007ef0000000001
-dont la signification est : ::
+which has the following meaning::
Type ID: "IDL:att.com/AttNotification/EventChannelFactory:1.0"
Profiles: 1. IIOP 1.0 127.0.0.1 32774 POA(root) 0x00000001 (4 bytes)
-Le service de nommage CORBA permet à l'utilisateur d'associer un nom à cette
-IOR. Salomé fournit une classe (C++ ou python) permettant d'utiliser de
-façon simple cette association.
+With the CORBA naming service, the user can associate a name with this IOR. SALOME provides a class (C++ or python)
+that makes it easy to use this association.
-
-Des structures de données standardisées :
+Standard data structures
"""""""""""""""""""""""""""""""""""""""""
+In addition to CORBA data structures (scalar, character strings, vectors, generic structures) SALOME offers typical structures
+to represent meshes, support (parts of meshes) and value fields on these supports. These structures are grouped under the
+name of the *data exchange model (MED)* [MED]_.
-En plus des structures de données CORBA (scalaires, chaînes de caractères,
-vecteurs, structures génériques), Salomé propose des structures type pour
-représenter les maillages, support (parties de maillages) et champs de valeurs
-sur ces supports. Ces structures sont regroupées sous le nom de *modèle
-d'échange de données (MED)* [MED]_.
-
-
-L'utilisation du service de notification CORBA :
-""""""""""""""""""""""""""""""""""""""""""""""""
-
-CORBA propose un service d'envoi de notification (avancement du calcul par
-exemple). Salomé propose des fonctionnalités pour simplifier l'envoi de
-messages par les composants et un canal d'événements où les clients peuvent
-suivre l'évolution des calculs par les composants.
-
-
-Un service d'enregistrement (registry) :
-""""""""""""""""""""""""""""""""""""""""
-
-Ce service permet à l'utilisateur de connaître l'ensemble des composants
-auxquels il peut envoyer des requêtes.
-
-
-Un catalogue de modules:
-""""""""""""""""""""""""
-
-Ce service permet à l'utilisateur et à Salomé de connaître les différents
-composants disponibles avec les différents services disponibles ainsi que
-l'emplacement de ces composants sur les disques des différentes machines.
-
-
-Un service de gestion d'études :
-""""""""""""""""""""""""""""""""
-
-Ce service permet de regrouper (au choix de l'utilisateur) différentes
-informations utilisées ou produites par les composants lors d'une session
-d'utilisation de Salomé.
+Use of the CORBA notification service
+"""""""""""""""""""""""""""""""""""""""""
+CORBA offers a service to send notifications (for example calculation progress). SALOME offers features to make it easier
+for components to send messages and an events channel in which customers can monitor how component calculations are progressing.
+A registry service
+"""""""""""""""""""""""""""""""""""""""""
+With this service, the customer can know all components to which he can send requests.
-Des composants de base :
-""""""""""""""""""""""""
+A modules catalog
+"""""""""""""""""""""""""""""""""""""""""
+With this service, the User and SALOME can know the different available components with the different available
+services and the location of these components on disks on different machines.
-Salomé est une plateforme générique de liaison CAO-Calcul qui propose des
-composants de CAO, de maillage et de visualisation et de supervision des
-calculs.
+A study management service
+"""""""""""""""""""""""""""""""""""""""""
+This service groups different items of information used or produced by components during a SALOME usage session (at the choice of the user).
+Basic components
+"""""""""""""""""""""""""""""""""""""""""
+SALOME is a generic CAD-Calculation platform that offers CAD, mesh, display and calculation supervision components.
.. _contfab:
-Conteneurs et fabriques
-^^^^^^^^^^^^^^^^^^^^^^^
-
+Containers and factories
+^^^^^^^^^^^^^^^^^^^^^^^^^^
.. index::
single: container
- single: factory
- single: conteneur
- single: fabrique
-
-Salomé est basé sur la notion de conteneur (ou "container") et de fabrique (ou
-"factory").
+ single: factory
-**Conteneur-fabrique**
- Un **conteneur** est un serveur CORBA chargé d'héberger des
- composants CORBA et est responsable du cycle de vie (chargement/déchargement,
- initialisation) de ces composants. Chaque conteneur contient un objet CORBA
- particulier appelé **fabrique**, auquel on peut envoyer des requêtes pour
- charger ou décharger des composants.
+SALOME is based on the concept of containers and factories.
-Exemple
+**Container-factory**
+ A **container** is a CORBA server that hosts CORBA components and is responsible for the life cycle (load/unload, initialize)
+ of these components. Each container contains a particular CORBA object called a factory, to which requests to load or unload
+ components can be sent.
+
+Example
"""""""
+Assume that a client would like to use the services of a component named A in a container named B on a machine named M.
+The different arrows on the :ref:`Container, factory and components<figconteneur>` figure show the operation:
-Supposons qu'un client désire utiliser des services d'un composant nommé A dans
-un conteneur nommé B sur une machine nommée M. Les différentes flèches sur
-la figure :ref:`Conteneur, fabrique et composants<figconteneur>` illustrent le fonctionnement :
-
-#. Le client s'adresse au noyau Salomé (sur sa machine) et lui demande de lui
- fournir une référence sur le composant A dans un conteneur B sur une machine M.
- Le noyau cherche si un tel composant est déjà référencé.
-
-#. Si le composant n'est pas référencé, le noyau Salomé cherche le conteneur B
- sur la machine M. Si le conteneur n'existe pas, Salomé le crée. Le noyau
- récupère une référence sur l'objet "fabrique" dans le conteneur B.
-
-#. L'objet "fabrique" du conteneur B charge dynamiquement la librairie
- contenant le code du composant A à partir du disque.
-
-#. Le composant est créé et enregistré dans le noyau Salomé, qui renvoie au
- client la référence sur le composant.
-
-#. Le client peut émettre des requêtes au composant.
+#. The client contacts the SALOME kernel (on its machine) and asks the kernel to provide it with a reference to component A in a container B on a machine M. The kernel searches if such a component is already referenced.
+#. If the component is not referenced, the SALOME kernel searches for container B on machine M. If the container does not exist, SALOME creates it. The kernel retrieves a reference on the “factory” object in container B.
+#. The “factory” object in container B dynamically loads the library containing the code of component A starting from the disk.
+#. The component is created and registered in the SALOME kernel, that forwards the reference on the component to the client.
+#. The client can issue requests to the component.
-**Remarque**
- Quand une référence sur un composant a été obtenue par le processus précédent
- (points 1 à 4), le client peut la conserver et émettre des requêtes au composant
- pendant toute la suite du calcul sans repasser par les mêmes étapes. Dans la
- version actuelle de Salomé, on n'a pas encore mis en place une procédure de
- reprise automatique si le composant (ou le conteneur qui le contient) tombe.
+**Note**: When a reference on a component has been obtained using the previous process (items 1 to 4), the client can keep it
+and issue requests to the component throughout the remainder of the calculation without repeating the same steps.
+In the current version of SALOME, an automatic restart procedure has not yet been set up for the case in which the component
+(or the container that contains it) is lost.
.. _figconteneur:
.. image:: images/conteneur.png
- :width: 50ex
:align: center
-.. centered:: Conteneur, fabrique et composants
+.. centered:: Container, factory and components
.. rubric:: Footnotes
-.. [#f1] On donnera à l'annexe 1, quelques indications sur le traitement des common fortran et variables globales C++.
+.. [#f1] Appendix 1 contains some information about processing of Fortran common and C++ global variables.
-.. [#f2] Au moment où est écrit ce document, l'outil retenu par Salomé est swig. Tant que ce choix n'est pas remis en cause, on ne conseille pas l'utilisation de boost pour l'intégration de composants dans Salomé (l'interopérabilité des deux outils n'ayant pas été testée).
+.. [#f2] At the time of writing this document, the tool selected by SALOME is swig. As long as the choice is not modified, it is not recommended that boost should be used to integrate components into SALOME (since interoperability of the two tools has not been tested).
