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.

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.

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.

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

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.

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.

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

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.

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.

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.