.. include:: ../../../router.1.0/srcDoc/vars.rst

.. _section-Common-PluginManagement:

*****************
Plugin Management
*****************

Some |RTI_SERVICE|\s allows for custom behavior through the use of *pluggable*
components or *plugins* . The type of plugins is described in
:numref:`section-sdk`. A plugin is represented as a top-level service-owned
object whose main role is a factory of other pluggable components, which
themselves are responsible for providing the user-defined behavior.

:numref:`FigureRouterPluginManagement` shows that for each *class* of pluggable
components there is a top-level object with the suffix ``Plugin``. This is the
object that the |SERVICE| obtains at the moment of loading the plugin. Multiple
``Plugin`` objects can be registered from the same class, each uniquely
identified by its *registered name*.

.. figure:: ../../../router.1.0/srcDoc/static/RouterPluginManagement.svg
    :alt: |SERVICE| plugins objects
    :name: FigureRouterPluginManagement
    :align: center
    :figwidth: 90%

    Plugin object management

:numref:`FigureRouterPluginManagement` also shows that there are two mechanisms
through which a |SERVICE| obtains a plugin object: a *shared library* or the
Service API. Both mechanisms are complementary and are described with more
detail in the next sections.

.. _section-Common-PluginManagement-SharedLib:

Shared Library
==============

A plugin object is instantiated through a *create function*, which is included
and addressable as part of a shared library. This function is also known as the
*entry point* and each |RTI_SERVICE| defines the signature for each plugin
class. This method requires specifying the path to the shared library and the
name of the entry point (see
:numref:`section-Common-PluginManagement-SharedLib-Config`). The |SERVICE|
loads the library the first time an instance of the plugin is needed (lazy
initialization) and looks up the specified entry point symbol in the loaded
library. The |SERVICE| will always delete the plugin on |SERVICE| stop.

This is the only method suitable when a |RTI_SERVICE| is deployed through an
already linked executable, such as the shipped command-line executable
(:numref:`section-usage-executable`).

The plugin lifecycle is as follows:

#. After start, |SERVICE| creates a plugin object for each registered plugin
   in the configuration. The plugin object is instantiated through the shared
   library entry point, specified in the configuration.
#. |SERVICE| calls operations on the plugin objects as needed and keeps them
   alive while the |SERVICE| remains started.
#. During stop, the |SERVICE| deletes each plugin object by calling the class
   abstract deleter.


.. _section-Common-PluginManagement-SharedLib-Config:

Configuration
-------------

An |RTI_SERVICE| configures the pluggable components within the
``<plugin_library>`` tag. |RTI_SERVICEs| that support plugins will define a
set of tags within in the form:

- ``<[class]_plugin>`` for C/C++ plugins
- ``<java_[class]_plugin>`` for Java plugins

where ``[class]`` refers to the name of the plugin class. For example, in |RS|
an available tag is ``<adapter_plugin>``.

The definition of these tags is the same regardless of the plugin class and
is described in the tables below.

:numref:`TableNativePluginTag` and :numref:`TableJavaPluginTag` describe the
configuration of each different plugin language.


.. list-table:: Configuration tags for C/C++ plugins.
    :name: TableNativePluginTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<[class]_plugin>`
      - Description
      - Multiplicity
    * - :litrep:`<dll>`
      - Shared library containing the implementation of the adapter plugin. |br|
        This tag may specify the exact path (absolute or relative) of the file
        (for example, **lib/libmyplugin.so**) or a general name (no file extension).

        If no extension is provided, the path will be completed based on the
        running platform. For example, assuming a value for this tag of
        **dir/myplugin**:

            - UNIX-based systems: **dir/libmyplugin.so**
            - Windows systems: **dir/myplugin.dll**

        If the library specified in this tag cannot be loaded (because the
        environment library path is not pointing to the path where the library
        is located), |RS| will look for the library in the following locations,
        in this order:

        - **[plugin_search_path]**: Provided as part of the service parameters
          (see :numref:`section-usage`)
        - **[executable_dir]**: Directory where the executable lives

      - 1
    * - :litrep:`<create_function>`
      - Entry point. This tag must contain the name of the function used to
        create the plugin instance. The function symbol must be present in the
        shared library specified in ``<dll>``
      - 1
    * - :litrep:`<property>`
      - A sequence of name-value string pairs that allow you to configure the
        plugin instance. |br|

        Example:
            .. code-block:: xml

                <property>
                    <value>
                        <element>
                            <name>myplugin.user_name</name>
                            <value>myusername</value>
                        </element>
                    </value>
                </property>
      - 0..1

.. list-table:: Configuration tags for Java plugins
    :name: TableJavaPluginTag
    :widths: 30 60 10
    :header-rows: 1
    :class: longtable

    * - Tags within :litrep:`<java_[class]_plugin>`
      - Description
      - Multiplicity
    * - :litrep:`<class_name>`
      - Name of the class that implements the plugin. |br|

        For example: com.myplugins.CustomPlugin |br|

        The classpath required to run the Java plugin must be part of the
        |RTI_SERVICE| JVM configuration. See the ``<jvm>`` tag within the
        specific service configuration for additional information on JVM
        creation and configuration.
      - 1
    * - :litrep:`<property>`
      - A sequence of name-value string pairs that allow you to configure the
        plugin instance. |br|

        Example:
            .. code-block:: xml

                <property>
                    <value>
                        <element>
                            <name>myplugin.user_name</name>
                            <value>myusername</value>
                        </element>
                    </value>
                </property>
      - 0..1


.. _section-Arm-PluginManagement-ServiceAPI:

Service API
===========

The user provides the plugin object via the Service API, through one of the
available ``attach_[class]_plugin()`` operations. Upon successful return of
the operation, the |SERVICE| takes ownership of the plugin object and will
delete it on |SERVICE| stop.

Plugin lifecycle goes as follows:

#. User instantiates plugin objects and provides them to the |SERVICE| through
   the ``attach_[class]_plugin()`` operation. This is allowed only before the
   |SERVICE| starts.
#. After start, the |SERVICE| becomes the owner of the registered plugin objects,
   calls operations on the plugin objects as needed, and keeps them alive while
   the |SERVICE| remains started.
#. On stop, the |SERVICE| deletes each registered plugin object by calling the
   class abstract deleter.