12.5. Plugin Management
Some RTI Services allow for custom behavior through the use of pluggable
components or plugins . The type of plugins is described in
Software Development Kit. A plugin is represented as a top-level service-owned
object whose main role is a factory of other pluggable components, which
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.
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.5.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
Configuration). 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 an RTI Service is deployed through an
already linked executable, such as the shipped command-line executable
(Command-Line Executable).
The plugin lifecycle is as follows:
After start, the 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.
The 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.
12.5.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:
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.18 and Table 12.19 describe the
configuration of each different plugin language.
Table 12.18 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:
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:
|
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.19 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.5.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.
The plugin lifecycle is as follows:
The 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.