doc/etapes.rst

   1
   2 .. _secetapes:
   3
   4 Steps in integration of a component
   5 ========================================
   6 Concept of component
   7 -----------------------
   8 There are many definitions of the software component.  We will use the following for SALOME:
   9
  10 **Component**
  11
  12   A component is a software entity with the following characteristics and behaviours:
  13
  14   - **physically identifiable**:  in other words a component is not a concept or a design “pattern”, but
  15     is a “genuine” portion of binary code and can be directly executed (or interpreted) after deployment;
  16   - **composable**:  it must be possible to create a relation between a component and other components:  it has
  17     one (or several) interfaces that interact like communication channels between components;
  18   - one component **interacts with the other components** only through its interface(s);
  19   - a component is **integrated into an application architecture** by a deployment process.
  20     This deployment process is dependent on the hardware and software platform sub-tending the architecture
  21
  22 General scheme
  23 --------------
  24
  25 .. index:: single: architecture
  26
  27 A calculation code is integrated in the form of a component in the PAL architecture in several steps, diagrammatically
  28 represented by the following figure:
  29
  30 .. image:: images/phases.png
  31    :align: center
  32
  33 .. centered:: Component integration phases
  34
  35 To use the component:
  36
  37 - locally through a python interpretor, a python interface needs to be written using tools such as **SWIG** [SWIG]_ or **Boost** [BOOST]_;
  38 - remotely through CORBA [CORBA]_, a CORBA interface (IDL file, implementation class) must be written. SALOME offers services that can simplify the use of CORBA;
  39 - 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).
  40
  41 Initial code
  42 --------------
  43 Specific cases may differ widely, depending on the form of the code to be integrated in SALOME.
  44 In this document, we will consider situations in which we initially have:
  45
  46 - a code in the form of one or several separate executables
  47 - a set of f77 functions / C routines / C++ classes
  48 - a set of python scripts that can control f77 / C / C++ routines, functions or classes.
  49
  50 .. _compinterne:
  51
  52 Putting the initial code in the form of an internal object
  53 ----------------------------------------------------------------
  54
  55 .. index:: single: internal object
  56
  57 A first work to simplify the next phases consists of presenting the initial code in the form of a C++ or python object.
  58
  59 **internal object**
  60
  61   This C++ or python object will be called "**internal object**" in this document.  It will be composed of
  62   public or private methods and attributes (according to the standard object oriented terminology):
  63
  64   .. index:: single: methods; public
  65
  66   - **public methods** are calculation services that are to be made available to users of the internal object
  67
  68   .. index:: single: attributes; public
  69
  70   - **public attributes** are object data that are to be made available to users of this internal object
  71
  72   .. index::
  73      single: methods; private
  74      single: attributes; private
  75
  76   - **private methods and attributes** are services and data of the internal object that are not to be
  77     made available to users of the internal object (and that will only be visible from other methods of this object).
  78
  79 .. index::
  80       single: internal state
  81       single: common fortran77
  82       single: global variables
  83
  84 **Notes**
  85
  86 1.  The “public/private” distinction is not really meaningful in Python, in which everything is public by default.
  87 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)
  88 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]_).
  89
  90 .. index::
  91    single: service; internal object
  92    single: internal state
  93
  94 The first part of the work, a design step, consists of defining the services and the internal state of this object.  In particular:
  95
  96 - choose the different services,
  97 - for each service, define input and output data,
  98 - for each input and each output, define the data type and also the associated pre-conditions and post-conditions,
  99 - define the internal state of the object and possibly its value before and after the call to the different services.
 100
 101 Depending on the case, the internal object may:
 102
 103 * “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;
 104
 105     .. _figinterne1:
 106
 107
 108     .. image:: images/objint1.png
 109          :align: center
 110
 111     .. centered:: Internal object encompassing the initial code
 112
 113 * communicate with the source code through the operating system (Unix, Windows, etc.), this is the case for an initial code
 114   in the form of a binary executable:
 115
 116     .. _figinterne2:
 117
 118
 119     .. image:: images/objint2.png
 120          :align: center
 121
 122     .. centered:: Internal object communicating with an external code
 123
 124   **Note**:  The communication with the binary external code may be made through files, or for example through the command line.
 125
 126 * if the initial code is already in the form of a python class, there is nothing to be done.
 127
 128     .. _figinterne3:
 129
 130
 131     .. image:: images/objint3.png
 132          :align: center
 133
 134     .. centered:: Initial code already in the form of an internal object
 135
 136 Access from a local python interpreter
 137 -----------------------------------------
 138 The C++/python object constructed in the (:ref:`compinterne`) section may be embedded in a component manipulated from a
 139 local python interpreter as shown on the following figure.
 140
 141 .. _python_local:
 142
 143
 144 .. image:: images/accesLocal.png
 145    :align: center
 146
 147 .. centered:: Access from a local python interpreter
 148
 149 It may or may not be necessary to provide an interface, depending on the type and implementation of the
 150 internal object (C++ or python).  Tools such as **swig** and **boost** can simplify this task [#f2]_.
 151
 152 Access from CORBA
 153 ------------------
 154 An interface has to be provided to enable a remote access to the component through CORBA, independently of the access from
 155 a local python interpreter.  Operation of CORBA as a client-server is selected as shown in the figure
 156 :ref:`Access from CORBA <figaccescorba>`, which shows communication between a client and a server through CORBA.
 157
 158 **CORBA server**
 159   A server is an executable, for the purposes of this document and in the SALOME environment.
 160   It is connected to a communication channel called a CORBA bus that transmits requests to it and to which
 161   the server returns the results of these requests.  A server can host several CORBA objects to which it delegates
 162   execution of these requests.  The CORBA client-server relation is specified by an interface file called the **IDL file**.
 163   This represents a contract between the component and the clients that use the component.
 164
 165 In this operating mode, the components will be CORBA objects.  The server – component relation will be specified
 166 in the :ref:`contfab` paragraph.
 167
 168 **Note**:  Requests cannot be executed correctly unless the client and the server respect the IDL file.  This is why
 169 in SALOME, the different IDL files are assembled in directories seen by all CORBA clients and servers.
 170
 171 .. _figaccescorba:
 172
 173
 174 .. image:: images/accesCorba.png
 175    :align: center
 176
 177 .. centered:: Access from CORBA
 178
 179 The code integrator must provide a part of the component server interface in the form of a so-called **implementation**
 180 class (similar procedure in python and C++, at the server end).  The remainder of the interface is generated
 181 from the IDL interface file.  On the other hand, the CORBA interface is generated almost entirely at the client
 182 end (particularly if the client is written in Python).
 183
 184 Specific features of the SALOME environment
 185 ------------------------------------------------
 186 SALOME services
 187 ^^^^^^^^^^^^^^^^^^
 188 SALOME provides a number of services above CORBA that simplify its use.  For example:
 189
 190 Access to the naming service
 191 """"""""""""""""""""""""""""""
 192 An IOR (CORBA reference) is a remote pointer, which is not always easy to handle.  The following is an example of an IOR::
 193
 194    IOR:010000003400000049444c3a6174742e636f6d2f4174744e6f74696669
 195    636174696f6e2f4576656e744368616e6e656c466163746f72793a312e3000
 196    010000000000000026000000010100000a0000003132372e302e302e310006
 197    800e000000fedd112a3d000007ef0000000001
 198
 199 which has the following meaning::
 200
 201    Type ID: "IDL:att.com/AttNotification/EventChannelFactory:1.0"
 202    Profiles: 1. IIOP 1.0 127.0.0.1 32774 POA(root) 0x00000001  (4 bytes)
 203
 204 With the CORBA naming service, the user can associate a name with this IOR.  SALOME provides a class (C++ or python)
 205 that makes it easy to use this association.
 206
 207 Standard data structures
 208 """""""""""""""""""""""""""""""""""""""""
 209 In addition to CORBA data structures (scalar, character strings, vectors, generic structures) SALOME offers typical structures
 210 to represent meshes, support (parts of meshes) and value fields on these supports.  These structures are grouped under the
 211 name of the *data exchange model (MED)* [MED]_.
 212
 213 Use of the CORBA notification service
 214 """""""""""""""""""""""""""""""""""""""""
 215 CORBA offers a service to send notifications (for example calculation progress).  SALOME offers features to make it easier
 216 for components to send messages and an events channel in which customers can monitor how component calculations are progressing.
 217
 218 A registry service
 219 """""""""""""""""""""""""""""""""""""""""
 220 With this service, the customer can know all components to which he can send requests.
 221
 222 A modules catalog
 223 """""""""""""""""""""""""""""""""""""""""
 224 With this service, the User and SALOME can know the different available components with the different available
 225 services and the location of these components on disks on different machines.
 226
 227 A study management service
 228 """""""""""""""""""""""""""""""""""""""""
 229 This service groups different items of information used or produced by components during a SALOME usage session (at the choice of the user).
 230
 231 Basic components
 232 """""""""""""""""""""""""""""""""""""""""
 233 SALOME is a generic CAD-Calculation platform that offers CAD, mesh, display and calculation supervision components.
 234
 235 .. _contfab:
 236
 237 Containers and factories
 238 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 239 .. index::
 240    single: container
 241    single: factory
 242
 243 SALOME is based on the concept of containers and factories.
 244
 245 **Container-factory**
 246   A **container** is a CORBA server that hosts CORBA components and is responsible for the life cycle (load/unload, initialize)
 247   of these components.  Each container contains a particular CORBA object called a factory, to which requests to load or unload
 248   components can be sent.
 249
 250 Example
 251 """""""
 252 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.
 253 The different arrows on the :ref:`Container, factory and components<figconteneur>` figure show the operation:
 254
 255 #.  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.
 256 #.  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.
 257 #.  The “factory” object in container B dynamically loads the library containing the code of component A starting from the disk.
 258 #.  The component is created and registered in the SALOME kernel, that forwards the reference on the component to the client.
 259 #.  The client can issue requests to the component.
 260
 261 **Note**:  When a reference on a component has been obtained using the previous process (items 1 to 4), the client can keep it
 262 and issue requests to the component throughout the remainder of the calculation without repeating the same steps.
 263 In the current version of SALOME, an automatic restart procedure has not yet been set up for the case in which the component
 264 (or the container that contains it) is lost.
 265
 266 .. _figconteneur:
 267
 268
 269 .. image:: images/conteneur.png
 270    :align: center
 271
 272 .. centered:: Container, factory and components
 273
 274 .. rubric:: Footnotes
 275
 276 .. [#f1] Appendix 1 contains some information about processing of Fortran common and C++ global variables.
 277
 278 .. [#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).