.. _`Language mapping for |product_name| RMI`:

#######################################
Language mapping for |product_name| RMI
#######################################

.. ifconfig:: 'Java' in (rmi_languages)

  Rmipp compilation follows a set of mapping rules to generate language-specific
  source code. Most of these rules come from the standard OMG IDL-to-C++ and
  IDL-to-Java mapping specifications but with some specific differences.
  This chapter focuses on specific parts of this mapping. For more information,
  please refer to the relevant OMG specifications.

.. ifconfig:: 'Java' not in (rmi_languages)

  Rmipp compilation follows a set of mapping rules to generate language-specific
  source code. Most of these rules come from the standard OMG IDL-to-C++
  mapping specification but with some specific differences.
  This chapter focuses on specific parts of this mapping. For more information,
  please refer to the relevant OMG specifications.

The following figure shows the language mapping of the ``HelloService`` 
IDL interface previously defined.

.. _`IDL Interface Mapping`:

.. figure:: /images/RMI-diag-05.png
   :height: 100mm
   :alt: IDL Interface Mapping

**IDL Interface Mapping**


**********************
Mapping for interfaces
**********************

.. ifconfig:: 'Java' in (rmi_languages)

  An interface is mapped to two C++ (or Java) classes that contain public
  definitions of the operations defined in the interface.

.. ifconfig:: 'Java' not in (rmi_languages)

  An interface is mapped to two C++ classes that contain public
  definitions of the operations defined in the interface.

The ``HelloServiceInterface`` abstract class is the base class of the
``HelloService`` implementation class. The ``HelloServiceInterfaceProxy``
class is the proxy object that represents locally the remote service.
The client application should get a reference to this class to be able
to invoke the remote service.

**********************
Mapping for operations
**********************

.. ifconfig:: 'Java' in (rmi_languages)

  Each IDL operation, if not oneway, is mapped to two C++ functions
  (Java methods). The first one, having the same name as the IDL operation,
  is used for synchronous invocations. The second one, having ``async_``
  concatenated to the IDL operation, is used for asynchronous invocations.
  A oneway operation maps only to the synchronous form of the operations.

  The operations parameters and return types obey the same parameter
  passing rules as for the standard OMG IDL-to-C++ and IDL-to-Java mapping.
  The asynchronous functions (methods) will return void and take only the
  in/inout parameters of the IDL operation, as well as a callback object
  used as a reply handler. This handler class is also generated for each
  non-void operation as an inner abstract class of the proxy class as
  depicted in the diagram with the ``greet_Reply_Handler`` class. This
  latter should be implemented by the user to handle the asynchronous
  invocation reply. Hence, the ``greet_Reply`` function (method) provides
  all the inout/out/return parameters of the corresponding IDL operation.

.. ifconfig:: 'Java' not in (rmi_languages)

  Each IDL operation, if not oneway, is mapped to two C++ functions.
  The first one, having the same name as the IDL operation,
  is used for synchronous invocations. The second one, having ``async_``
  concatenated to the IDL operation, is used for asynchronous invocations.
  A oneway operation maps only to the synchronous form of the operations.

  The operations parameters and return types obey the same parameter
  passing rules as for the standard OMG IDL-to-C++ mapping.
  The asynchronous functions (methods) will return void and take only the
  in/inout parameters of the IDL operation, as well as a callback object
  used as a reply handler. This handler class is also generated for each
  non-void operation as an inner abstract class of the proxy class as
  depicted in the diagram with the ``greet_Reply_Handler`` class. This
  latter should be implemented by the user to handle the asynchronous
  invocation reply. Hence, the ``greet_Reply`` function (method) provides
  all the inout/out/return parameters of the corresponding IDL operation.

***********************
Mapping for basic types
***********************

The table below shows the |rmi_langs| mapping of the IDL types that
can be declared in the RMI services description file.

IDL sequences are mapped as specified by the DDS standard.

**Mapping for basic types**

.. ifconfig:: 'Java' in (rmi_languages)

  ===================  ==============  =======
  IDL type             C++             Java
  ===================  ==============  =======
  boolean              DDS::Boolean    boolean
  char                 DDS::Char       char
  octet                DDS::Octet      byte
  short                DDS::Short      short
  unsigned short       DDS::UShort     short
  long                 DDS::Long       int
  unsigned long        DDS::ULong      int
  long long            DDS::LongLong   long
  unsigned long long   DDS::ULongLong  long
  float                DDS::Float      float
  double               DDS::Double     double
  string               DDS::String     String
  ===================  ==============  =======

.. ifconfig:: 'Java' not in (rmi_languages)

  ===================  ==============
  IDL type             C++
  ===================  ==============
  boolean              DDS::Boolean
  char                 DDS::Char
  octet                DDS::Octet
  short                DDS::Short
  unsigned short       DDS::UShort
  long                 DDS::Long
  unsigned long        DDS::ULong
  long long            DDS::LongLong
  unsigned long long   DDS::ULongLong
  float                DDS::Float
  double               DDS::Double
  string               DDS::String
  ===================  ==============

|caution| |cpp|
  Please be aware that the RMI middleware assumes ownership of any
  ``DDS::String`` that is provided to it (either by an in/inout argument
  or return value). This also means that it'll free the given string. This
  can cause issues when the application keeps using the provided string after
  the RMI call or if RMI is called with a const string literal. It is advised
  to apply ``DDS::string_dup(str)`` when using strings in conjunction with
  RMI. This is also applicable to sequences of strings.




.. |caution| image:: ./images/icon-caution.*
            :height: 6mm
.. |info|   image:: ./images/icon-info.*
            :height: 6mm
.. |windows| image:: ./images/icon-windows.*
            :height: 6mm
.. |unix| image:: ./images/icon-unix.*
            :height: 6mm
.. |linux| image:: ./images/icon-linux.*
            :height: 6mm
.. |c| image:: ./images/icon-c.*
            :height: 6mm
.. |cpp| image:: ./images/icon-cpp.*
            :height: 6mm
.. |csharp| image:: ./images/icon-csharp.*
            :height: 6mm
.. |java| image:: ./images/icon-java.*
            :height: 6mm

