doc/accesCorba.rst

   1
   2 .. _secaccescorba:
   3
   4 Component with remote access (through CORBA)
   5 ================================================
   6 Principle
   7 ----------
   8 The interfaces necessary to “see” an internal object like a remote component are based on the definition of a “contract” that
   9 specifies the services proposed by a component and the mode of accessing these services (input and output parameters, exceptions returned).
  10
  11 These declarations are contained in an **IDL file** that is used as a reference to define the interface code at the component end
  12 and at the clients end of the component.  Examples are given later.  The designer of the component starts from the IDL file and
  13 develops a server end interface to set up communication between the network (through CORBA) and the internal object.
  14 The designer of each client starts from the IDL file and develops an interface to set up communication between the
  15 network (through CORBA) and the component user code.
  16
  17   .. _figaccescorba2:
  18
  19
  20   .. image:: images/accesCorbaIDL.png
  21      :align: center
  22
  23   .. centered::   Access from CORBA
  24
  25 IDL file
  26 -----------
  27 The first step is for the component developer to define a list of proposed services and the method of calling them, in
  28 a file called the IDL file.  This file contains data structures declarations and classes (“interface” in the CORBA terminology) in
  29 a language defined by the CORBA (IDL) standard.
  30 `OMG IDL Syntax and Semantics <http://doc.ece.uci.edu/CORBA/formal/01-12-07.pdf>`_ [IDL]_ is a reference document on the IDL language syntax.
  31
  32 **Note**
  33   This language is similar to a sub-set of the C++ and java languages.  CORBA defined its own interface language to achieve
  34   transparency relative to client and server implementation languages.  A client written with a programming language can connect
  35   through CORBA to a server implemented in another language.  The only condition is that there are two CORBA ORBs (or systems)
  36   interfaced with languages used in the server and the client.  There are ORBs capable of managing many
  37   languages (C, C++, java, python, etc.).  A single ORB (omniORB) was chosen within SALOME, making it possible to use clients
  38   and servers written in C++ or in python indifferently.
  39
  40 Example 6 (Part 1)
  41 ^^^^^^^^^^^^^^^^^^^^^^^
  42 An IDL file is written to access objects (C++) in the alglin class from CORBA (see the ``alglin.hxx`` file in Example 1 and
  43 other examples).  The corresponding IDL file may for example contain:
  44
  45 .. _alglin.idl:
  46
  47
  48 ``alglin.idl``
  49
  50 .. include:: ./exemples/exemple6/alglin.idl
  51    :literal:
  52
  53 **Comments**
  54
  55 #. The IDL file begins with the ``module Distant {`` line.  Whenever possible, it is recommended that interface declarations
  56    should be contained within a module.
  57 #. The ``vecteur`` class of the C++ version does not have to be declared in IDL.  The IDL language has a base type (``sequence <double>``)
  58    that can manage a simple vector.
  59
  60 Example 7 (Part 1)
  61 ^^^^^^^^^^^^^^^^^^^^^^^
  62 An IDL file is constructed to access (python) objects in the FreeFem class from CORBA (see ``FreeFem.py``, Example 4 and
  63 subsequent examples).  The corresponding IDL file may for example contain:
  64
  65 .. _freefem.idl:
  66
  67
  68 ``FreeFem.idl``
  69
  70 .. include:: ./exemples/exemple7/FreeFem.idl
  71    :literal:
  72
  73
  74 Server end interface
  75 ----------------------
  76 A server end interface has to be developed from the IDL file.  The principle consists of defining an object communicating
  77 firstly with the internal object and secondly with the CORBA communication layer.  It will be written in a manner that will
  78 depend on the implementation language of the internal object (C++ or python).
  79
  80 .. _interfacec++:
  81
  82 C++ server interface
  83 ^^^^^^^^^^^^^^^^^^^^^
  84
  85 .. image:: images/objCorbaCpp.png
  86    :align: center
  87
  88 .. centered::   CORBA C++ interface generation
  89
  90 When the internal object is written in C++ (or it has a C++ higher layer), a C++ implementation class will have to be
  91 defined at the server end that
  92
  93 - is derived from the ``POA_<module name>::<idl class name>`` class (class generated by the system starting from the IDL file)
  94 - is derived from the ``PortableServer::ServantBase`` class (class provided by the system, that provides a reference
  95   counter to the implementation class)
  96 - defines methods corresponding to the methods and attributes of the IDL class
  97 - has a pointer to the internal object as an attribute.
  98
  99 **Note**
 100   The final point above can be replaced by:
 101
 102 .. epigraph::
 103
 104    is derived from the class of the internal object
 105
 106   The first version is recommended in preference, because it is easier to implement.
 107
 108 **Important**:  Most CORBA implementations can generate skeletons of implementation classes.  It is strongly recommended
 109 that this feature should be used to facilitate writing implementation classes.
 110
 111 In the case of omniORB::
 112
 113    omniidl -bcxx -Wbexample <nom>.idl
 114
 115 (note the –Wbexample option) generates a ``<name>_i.cc`` file that contains the implementation class and an example of
 116 the main program at the server end.  This file then has to be “cleaned” (keeping the method call prototypes) and completed.
 117 Methods for implementation classes receive and return CORBA objects.  Therefore, if necessary, each method must:
 118
 119 - convert CORBA objects in input into C++ objects (or into simple types)
 120 - call the method(s) of the internal object
 121 - convert the C++ objects resulting from the methods of the internal object into CORBA objects
 122
 123 .. _implc++:
 124
 125 Example 6 (continued)
 126 ^^^^^^^^^^^^^^^^^^^^^^^
 127 Consider an example consisting of a server end implementation class that calls objects in the ``alglin`` class from CORBA:
 128
 129 .. _alglini.hxx:
 130
 131
 132 ``alglin_i.hxx``
 133
 134 .. include:: ./exemples/exemple6/alglin_i.hxx
 135    :literal:
 136
 137 .. _alglini.cxx:
 138
 139
 140 ``alglin_i.cxx``
 141
 142 .. include:: ./exemples/exemple6/alglin_i.cxx
 143    :literal:
 144
 145 **Note**
 146   Note that the ``create_vector`` and ``destroy_vector`` functions are not exported in IDL, because a standard CORBA type
 147   is used (``sequence<double>``).
 148
 149 Python server interface
 150 ^^^^^^^^^^^^^^^^^^^^^^^^
 151 This case is similar to the previous case.  It can be simpler (it is not always necessary to include input and output
 152 parameter conversion phases).
 153
 154   .. _interfacepython:
 155
 156
 157   .. image:: images/objCorbapy.png
 158      :align: center
 159
 160   .. centered::   Generation of the python CORBA interface
 161
 162 **Note**
 163   This is due to the fact that python is not as strongly typed as C++:  a python function can be executed if the input parameters
 164   possess all methods and attributes called in the function.  This is the case if the methods in the implementation class have
 165   the same signatures as methods in the internal object class, as in example 7 below.
 166
 167 Example 7 (continued)
 168 ^^^^^^^^^^^^^^^^^^^^^^^^^
 169 We will consider an example consisting of the python implementation class at the server end used to call objects in
 170 the ``FreeFem`` class from CORBA:
 171
 172 .. _freefemi.py:
 173
 174
 175 ``FreeFem_i.py``
 176
 177 .. include:: ./exemples/exemple7/FreeFem_i.py
 178    :literal:
 179
 180 Client interface
 181 ----------------
 182 The client end interface code can be written in any language (provided that there is a CORBA implementation in this
 183 language), independently of the language(s) used at the server end.
 184
 185 Essentially, it is necessary:
 186
 187 - during compilation, to have the CORBA interface generated at the client end (generally, CORBA generates the two
 188   interfaces at the client and server ends simultaneously) and to integrate it into the client code,
 189 - during execution, retrieve the CORBA reference of the server end component,
 190 - call component methods on this CORBA reference.
 191
 192 Example 8
 193 ^^^^^^^^^
 194 In the context of SALOME, there is no need to write clients for user components.  However, consider a C++ client example
 195 and a python client example in the CORBA AlgLin class:
 196
 197 ``client.cxx``
 198
 199 .. include:: ./exemples/exemple8/client.cxx
 200    :literal:
 201
 202
 203 ``client.py``
 204
 205 .. include:: ./exemples/exemple8/client.py
 206    :literal:
 207