12.4. Plugin Management

Some RTI services allows for custom behavior through the use of pluggable components or plugins . The type of plugins is described in Section 7. 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.

Figure 12.7 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.

|SERVICE| plugins objects

Figure 12.7 Plugin object management

Figure 12.7 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.

12.4.1. 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 Section 12.4.1.1). 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 (Section 3.1).

The plugin lifecycle is as follows:

  1. 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.
  2. Service calls operations on the plugin objects as needed and keeps them alive while the Service remains started.
  3. During stop, the Service deletes each plugin object by calling the class abstract deleter.

12.4.1.1. 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 Routing Service 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.

Table 12.16 and Table 12.17 describe the configuration of each different plugin language.

Table 12.16 Configuration tags for C/C++ plugins.
Tags within <[class]_plugin> Description Multiplicity
<dll>

Shared library containing the implementation of the adapter plugin.
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), Routing Service will look for the library in the following locations, in this order:

  • [plugin_search_path]: Provided as part of the service parameters (see Section 3)
  • [executable_dir]: Directory where the executable lives
 1
<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
<property>

A sequence of name-value string pairs that allow you to configure the plugin instance.

Example:
<property>
    <value>
        <element>
            <name>myplugin.user_name</name>
            <value>myusername</value>
        </element>
    </value>
</property>
0..1
Table 12.17 Configuration tags for Java plugins
Tags within <java_[class]_plugin> Description Multiplicity
<class_name>

Name of the class that implements the plugin.

For example: com.myplugins.CustomPlugin

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
<property>

A sequence of name-value string pairs that allow you to configure the plugin instance.

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

12.4.2. 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:

  1. User instantiates plugin objects and provides them to the Service through the attach_[class]_plugin() operation. This is allowed only before the Service starts.
  2. 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.
  3. On stop, the Service deletes each registered plugin object by calling the class abstract deleter.