Real-Time Innovations  Web Integration Service
  • Installation
  • Configuration
  • Usage
  • REST API
  • Tutorials
  • API Reference
  • Release Notes
  • 3rd Party Software

Configuration

1 Configuring Web Integration Service

This document describes how to configure Web Integration Service. To see installation instructions or walk through some simple examples, please see the appropriate section.

When you start Web Integration Service, you can specify a configuration file in XML format (it is not required). In that file, you can set properties that control the behavior of the service. This chapter describes how to write a configuration file.

2 Terms to Know

Before learning how to configure Web Integration Service, you should become familiar with a few key terms and concepts:

  • A Web Integration Service Configuration—represented by the <web_integration_service> XML tag—refers to an execution of Web Integration Service.
  • An Application—represented by the <application> XML tag—defines a collection of DomainParticipants and their contained entities. Applications are instantiated in the context of a Web Integration Service Configuration. That is, a Web Integration Service Configuration contains a set of applications that contain entities that are accessible for clients of the service.

3 How to Load the XML Configuration

Web Integration Service loads its XML configuration from multiple locations. This section presents the various approaches, listed in load order.

The first three locations are inherited from Connext DDS (see the RTI Connext DDS Core Libraries User's Manual).

  • $NDDSHOME/resource/xml/NDDS_QOS_PROFILES.xml This file contains the Connext DDS default QoS values; it is loaded automatically if it exists. (First to be loaded.).
  • File in NDDS_QOS_PROFILES environment variable: The files (or XML strings) separated by semicolons referenced in this environment variable are loaded automatically.
  • <working directory>/USER_QOS_PROFILES.xml This file is loaded automatically if it exists.

The next locations are specific to Web Integration Service.

  • $NDDSHOME/resource/xml/RTI_WEB_INTEGRATION_SEVICE.xml This file contains the default Web Integration Service configuration; it is loaded if it exists. RTI_WEB_INTEGRATION_SERVICE.xml defines an empty service that clients can add applications to, as well as an example "ShapesDemo" service.
  • <working directory>/USER_WEB_INTEGRATION_SERVICE.xml This file is loaded automatically if it exists.
  • File specified using the command-line parameter -cfgFile.

You may use a combination of the above approaches.

Here is an example configuration file. You will learn the meaning of each line as you read the rest of this section.

<?xml version="1.0"?>
<dds>
    <types>
        <struct name="MyType">
            <member name="name" key="true"
                    type="string" stringMaxLength="128"/>
            <member name="count" type="long" />
        </struct>
    </types>
    <web_integration_service name="ExampleService">
        <application name="ExampleApplication">
            <domain_participant name="MyParticipant" domain_id="1">
                <topic name="MyTopic" register_type_ref="MyType" />
                <register_type name="MyType" kind="dynamicData"
                        type_ref="ShapeType" />
                <publisher name="MyPublisher">
                    <data_writer name="MyWriter"
                            topic_ref="MyTopic" />
                </publisher>
                <subscriber>
                    <data_reader name="MyReader" topic_ref="MyTopic" />
                </subscriber>
            </domain_participant>
        </application>
    </web_integration_service>
</dds>

4 XML Syntax and Validation

The XML configuration file must follow these syntax rules:

  • The syntax is XML; the character encoding is UTF-8.
  • Opening tags are enclosed in <>; closing tags are enclosed in </>.
  • A tag value is a UTF-8 encoded strings. Legal values are alphanumeric characters. Web Integration Service's parser will remove all leading and trailing spaces from the string before it is processed. For instance "<tag> value </tag>" is the same as "<tag>value</tag>".
  • All values are case-sensitive unless otherwise stated.
  • Comments are enclosed as follows: <!-- comment -->.
  • The root tag of the configuration file must be <dds> and end with </dds>.

Web Integration Service provides DTD and XSD files that describe the format of the XML content. We recommend including a reference to one of these documents in the XML file that contains the service's configuration—this provides helpful features in code editors such as Visual Studio® and Eclipse®, including validation and autocompletion while you are editing the XML file.

The DTD and XSD definitions of the XML elements are in $NDDSHOME/resources/schema/rti_web_integration_service.dtd and $NDDSHOME/resources/schema/rti_web_integration_service.xsd, respectively.

To include a reference to the XSD document in your XML file, use the attribute xsi:noNamespaceSchemaLocation in the <dds> tag. For example:

<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="<NDDSHOME>/resource/schema/rti_web_integration_service.xsd">
  ...
</dds>

To include a reference to the DTD document in your XML file, use the <!DOCTYPE> tag.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dds SYSTEM
    "<NDDSHOME>/resource/schema/rti_web_integration_service.dtd">
<dds>
...
</dds>

We recommend including a reference to the XSD file in the XML documents; this provides stricter validation and better autocompletion than the corresponding DTD file.

5 XML Tags for Configuring Web Integration Service

This section describes the XML tags you can use in a Web Integration Service configuration file. The following diagram and Table 1 describe the top-level tags allowed within the root <dds> tag.

Web Integration Service XML Tags

Figure 1: Top-level Tags in the Configuration File

Tags within <dds>DescriptionNumber of Tags Allowed
<qos_library>Specifies a QoS library and profiles. The contents of this tag are specified in the same manner as for the Connext DDS QoS profile file—see Chapter 17, Configuring QoS with XML, in the RTI Connext DDS Core Libraries User's Manual.0 or more
<domain_library>Specifies a domain library. That is, a set ofdefinitions.0 or more
<types>Defines types that can be used by Web Integration Service.1 (required)
<web_integration_service>Specifies a Web Integration Service configuration. See Web Integration Service (Section 5.1).1 or more (required)
Table 1: Top-level Tags in the Configuration File

5.1 Web Integration Service

A configuration file must have at least one <web_integration_service> tag; this tag is used to configure an execution of Web Integration Service. A configuration file may contain multiple <web_integration_service> tags.

When you start Web Integration Service, you can specify which <web_integration_service> tag to use to configure the service using the -cfgName command-line parameter.

For example:

<dds>
    <web_integration_service name="EmptyConfiguration"/>
    <web_integration_service name="ShapesDemoConfiguration">
    ...
    </web_integration_service>
</dds>

Starting Web Integration Service with the following command will use the <web_integration_service> tag with the name EmptyConfiguration.

$ <NDDSHOME>/bin/rtiwebintegrationservice \
  -cfgFile file.xml -cfgName EmptyConfiguration

Because a configuration file may contain multiple <web_integration_service> tags, one file can be used to configure multiple Web Integration Service executions.

The following diagram and Table 2 describe the tags allowed within a <web_integration_service> tag.

Web Integration Service XML Tag

Figure 2: Web Integration Service Tag

Tags within <web_integration_service>DescriptionNumber of Tags Allowed
<application>Applications are a collection of instantiated DomainParticipants and their contained DDS entities.0 or more
Attributes:
  • name: Application name
Table 2: Web Integration Service Tag

5.1.1 Application

An <application> provides a way to organize a set of instantiated participants belonging to the same logical application. That is, it provides a namespace that client applications can leverage to categorize their DomainParticipants within a Web Integration Service instance.

When a certain Web Integration Service configuration is instantiated using the -cfgName command-line argument, all its contained applications—along with the DDS entities associated with them—are automatically instantiated as well. This also applies to the creation of new applications via Web Integration Service's REST API, as the creation of a new application will also trigger the instantiation of all its contained DomainParticipants and entities.

Tags within <application>DescriptionNumber of Tags Allowed
<domain_participant>Specifies a DomainParticipant configuration.0 or more
Attributes:
  • name: Participant name.
  • domain_ref(optional): Reference (fully qualified name) to a defined <domain> in the domain library.
  • domain_id (optional): Domain ID. If specified, overrides the ID of the domain it refers to. If no domain_id is specified directly or in the referenced domain, then the default domain_id is 0.
Table 3: Application Tag

5.1.2 Domain Participant and Contained Entities

A <domain_participant> is defined by specifying the set of Entities it contains. This is done using tags such as <publisher>, <subscriber>, <data_writer>, and <data_reader>, which specify an Entity of their corresponding type. These Entities are created within the DomainParticipant instantiated by the <application>, which is instantiated when the Web Integration Service configuration that contains it is created or when a new application is created by the REST API.

The <domain_participant> also specifies <register_type> and <topic>, which can be associated with a Domain where topics and their associated types are either already defined (see section on Domain Libraries) or are defined within the <domain_participant>.

Domain Participant XML Tag

Figure 3: Domain Participant Tag

Tags within <domain_participant>DescriptionNumber of Tags Allowed
<register_type>Registers a type within the DomainParticipant. The type definition will be instantiated when an associated Topic is created.0 or more
Attributes:
  • name: Name under which the type is registered with the DomainParticipants.
  • kind: Specifies whether the type is built-in, dynamic data, or generated by the user. In Web Integration Service it is mandatory to set kind="dynamicData".
  • type_ref: Reference (fully qualified name) to a defined type within <types>. This is the type that is being registered.
<topic>Specifies a Topic configuration.0 or more
Attributes:
  • name: Topic name.
  • register_type_ref: Reference (name) to a register_type within the domain or DomainParticipant.
<publisher>Specifies a Publisher configuration.0 or more
Attributes:
  • name: Publisher name.
<subscriber>Specifies a Subscriber configuration.0 or more
Attributes:
  • name: Subscriber name.
Table 4: Domain Participant Tag

The <publisher> tag specifies a Publisher configuration. That is, it defines a set of DataWriters using the <data_writer> tag, as well as the Publisher's QoS settings using the <publisher_qos> tag.

Web Integration Service does not support the use of implicit Publishers. Therefore, clients need to define DataWriters under an existing <publisher> tag in the configuration file.

Tags within <publisher>DescriptionNumber of Tags Allowed
<data_writer>Specifies a DataWriter configuration.0 or more
Attributes:
  • name: DataWriter name.
  • topic_ref: Name of a <topic> associated with the <domain_participant>.
<publisher_qos>Publisher QoS configuration.0 or 1
Table 5: Publisher Tag

The <subscriber> tag specifies a Subscriber configuration. That is, it defines a set of DataReaders using the <data_reader> tag, as well as the Subscriber's QoS settings using the <subscriber_qos> tag.

Web Integration Service does not support the use of implicit Subscribers. Therefore, clients need to define DataReaders under an existing <subscriber> tag in the configuration file.

Tags within <subscriber>DescriptionNumber of Tags Allowed
<data_reader>Specifies a DataReader configuration.0 or more
Attributes:
  • name: DataReader name.
  • topic_ref: Name of a <topic> associated with the <domain_participant>.
<subscriber_qos>Subscriber QoS configuration.0 or 1
Table 6: Subscriber Tag

The <data_writer> tag specifies the topic it is associated with (see Table 5), as well as its QoS configuration (see Table 7).

Tags within <data_writer>DescriptionNumber of Tags Allowed
<datawriter_qos>DataWriter QoS configuration.0 or 1
Table 7: DataWriter Tag

The <data_reader> tag specifies the topic it is associated with (see Table 6), as well as its QoS configuration (see Table 8). DataReaders can also specify filter expressions that enable content filtering.

Tags within <data_reader>DescriptionNumber of Tags Allowed
<datareader_qos>DataReader QoS configuration.0 or 1
<filter>Enables the creation of the DataReader with this configuration from a ContentFilteredTopic0 or 1
Attributes:
  • name: Name of the ContentFilteredTopic that will be associated with the same Topic referenced by the containing <data_reader>.
  • filter_kind: Specifies which ContentFilter to use. It defaults to using the built-in SQL filter. That is, <filter name="AFilter" kind="builtin.sql">
Table 8: DataWriter Tag

The <filter> tag within a <data_reader> enables content filtering. It causes the corresponding DataReader to be created from a ContentFilteredTopic with the specified filter characteristics.

Tags within <filter>DescriptionNumber of Tags Allowed
<expression>Filter expression.0 or 1
<parameter_list>List of parameters. Parameters are specified using <param> tags. The maximum number of parameters is 100.
<parameter_list><param>param_0<param>...</parameter_list>
0 or 1
Table 9: DataWriter Tag

For example:

<domain_participant name="MyParticipant">
    <topic name="MyTopic"  register_type_ref="MyType"/>
    <register_type name="MyType" kind="dynamicData" typeRef="AType"/>
    <publisher name="MyPublisher">
        <data_writer name="MyWriter" topic_ref="MyTopic"/>
    </publisher>
    <subscriber name="MySubscriber">
        <data_reader name="MyReader" topic_ref="MyTopic">
            <filter name="MyFilter" kind="builtin.sql">
                <expression> count &lt; %0</expression>
                <parameter_list>
                    <param>10</param>
                </parameter_list>
            </filter>
        </data_reader>
    </subscriber>
</domain_participant>

The above configuration defines a <domain_participant> that defines a topic MyTopic for a MyType. The DomainParticipant contains:

  • A Publisher that has a DataWriter created from the Topic MyTopic.
  • A Subscriber that has a DataReader created from a ContentFilteredTopic whose related Topic, MyTopic, uses a SQL filter.

5.2 Types, QoS Library, and Domain Library

The rest of tags are part of the XML-based Application Creation API for Connext DDS.

  • The <types> tag is defined in Section 3.4 of the RTI Connext DDS Core Libraries User's Manual.
  • The <qos_library> tag is defined in Section 17.2 of the RTI Connext DDS Core Libraries User's Manual.
  • The <domain_library> tag is defined in Section 4.5.1 of the RTI Connext DDS XML-Based Application Creation Getting Started Guide.
  • 1 Configuring Web Integration Service
  • 2 Terms to Know
  • 3 How to Load the XML Configuration
  • 4 XML Syntax and Validation
  • 5 XML Tags for Configuring Web Integration Service