RTI_Routing_Service_UsersManual RTI Routing Service Users Manual
User Manual: Pdf
Open the PDF directly: View PDF .
Page Count: 174
Download | |
Open PDF In Browser | View PDF |
RTI Routing Service User’s Manual Version 5.2.3 © 2009-2016 Real-Time Innovations, Inc. All rights reserved. Printed in U.S.A. First printing. April 2016. Trademarks Real-Time Innovations, RTI, NDDS, RTI Data Distribution Service, DataBus, Connext, Micro DDS, the RTI logo, 1RTI and the phrase, “Your Systems. Working as one,” are registered trademarks, trademarks or service marks of Real-Time Innovations, Inc. All other trademarks belong to their respective owners. Copy and Use Restrictions No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form (including electronic, mechanical, photocopy, and facsimile) without the prior written permission of RealTime Innovations, Inc. The software described in this document is furnished under and subject to the RTI software license agreement. The software may be used or copied only under the terms of the license agreement. Technical Support Real-Time Innovations, Inc. 232 E. Java Drive Sunnyvale, CA 94089 Phone: (408) 990-7444 Email: support@rti.com Website: https://support.rti.com/ Contents 1 Welcome to RTI Routing Service 1.1 Available Documentation ......................................................................................................................... 1-3 1.2 Paths Mentioned in Documentation ....................................................................................................... 1-3 2 Configuring Routing Service 2.1 Terms to Know ........................................................................................................................................... 2-1 2.2 How to Load the XML Configuration .................................................................................................... 2-2 2.3 XML Syntax and Validation ..................................................................................................................... 2-3 2.4 XML Tags for Configuring Routing Service .......................................................................................... 2-5 2.4.1 Routing Service............................................................................................................................ 2-6 2.4.2 Domain Route .............................................................................................................................. 2-8 2.4.3 Administration........................................................................................................................... 2-12 2.4.4 Monitoring.................................................................................................................................. 2-14 2.4.5 Session......................................................................................................................................... 2-19 2.4.6 Routes.......................................................................................................................................... 2-21 2.4.7 Auto Routes................................................................................................................................ 2-31 2.4.8 Adapters ..................................................................................................................................... 2-36 2.5 Enabling and Disabling Routing Service Entities ............................................................................... 2-37 2.6 Enabling RTI Distributed Logger in Routing Service......................................................................... 2-38 2.7 Support for Extensible Types ................................................................................................................. 2-38 2.7.1 Example ...................................................................................................................................... 2-39 3 Running Routing Service 3.1 Starting Routing Service ........................................................................................................................... 3-1 3.2 Stopping Routing Service ......................................................................................................................... 3-2 3.3 Linking the Routing Service Library into Your Application ............................................................... 3-3 4 Transforming Data with Routing Service 4.1 Transformation Usage and Configuration ............................................................................................. 4-1 4.2 Transformations Distributed with Routing Service.............................................................................. 4-3 4.3 Creating New Transformations ............................................................................................................... 4-4 4.3.1 Transformation Plugin API ........................................................................................................ 4-5 5 Administering Routing Service from a Remote Location 5.1 Enabling Remote Administration ........................................................................................................... 5-1 iii 5.2 Remote Commands ................................................................................................................................... 5-1 5.2.1 add_peer ....................................................................................................................................... 5-3 5.2.2 create ............................................................................................................................................. 5-3 5.2.3 delete ............................................................................................................................................. 5-4 5.2.4 disable ........................................................................................................................................... 5-4 5.2.5 enable ............................................................................................................................................ 5-4 5.2.6 get .................................................................................................................................................. 5-4 5.2.7 load ................................................................................................................................................ 5-5 5.2.8 pause ............................................................................................................................................. 5-5 5.2.9 resume........................................................................................................................................... 5-5 5.2.10 save ................................................................................................................................................ 5-5 5.2.11 unload ........................................................................................................................................... 5-5 5.2.12 update ........................................................................................................................................... 5-6 5.3 Accessing Routing Service from a Connext Application ..................................................................... 5-8 6 Monitoring Routing Service from a Remote Location 6.1 Enabling Remote Monitoring................................................................................................................... 6-1 6.2 Monitoring Configuration Data .............................................................................................................. 6-2 6.2.1 Configuration Data for Routing Service .................................................................................. 6-2 6.2.2 Configuration Data for a Domain Route.................................................................................. 6-3 6.2.3 Configuration Data for a Session .............................................................................................. 6-5 6.2.4 Configuration Data for a Route................................................................................................. 6-6 6.2.5 Configuration Data for an Auto Route................................................................................... 6-10 6.3 Monitoring Status .................................................................................................................................... 6-14 6.3.1 How the Statistics are Generated ............................................................................................ 6-15 6.3.2 Status Information for the Routing Service ........................................................................... 6-16 6.3.3 Domain Route Status ................................................................................................................ 6-17 6.3.4 Status Information for a Session.............................................................................................. 6-18 6.3.5 Status Information for a Route ................................................................................................ 6-19 6.3.6 Status Information for an Auto Route.................................................................................... 6-19 7 Traversing Wide Area Networks 7.1 TCP Communication Scenarios ............................................................................................................... 7-2 7.1.1 Communication Within a Single LAN ..................................................................................... 7-2 7.1.2 Symmetric Communication Across NATs ............................................................................... 7-3 7.1.3 Asymmetric Communication Across NATs ............................................................................ 7-5 7.1.4 Secure Communication .............................................................................................................. 7-5 7.2 Configuring the TCP Transport ............................................................................................................... 7-6 7.2.1 TCP Transport Initial Peers ........................................................................................................ 7-6 7.2.2 Setting Up the TCP Transport Properties with the PropertyQoSPolicy .............................. 7-7 7.2.3 TCP/TLS Transport Properties ................................................................................................. 7-8 7.2.4 Support for External Hardware Load Balancers in TCP Transport Plugin ...................... 7-18 8 Extending Routing Service with Adapters 8.1 Adapter Usage and Configuration.......................................................................................................... 8-1 8.2 Adapter API And Entity Model .............................................................................................................. 8-2 8.2.1 Entity Creation............................................................................................................................. 8-8 8.2.2 Stream Discovery......................................................................................................................... 8-8 8.2.3 Reading Data................................................................................................................................ 8-9 iv 8.3 Creating New Adapters.......................................................................................................................... 8-10 8.3.1 Adapter SDK Components ...................................................................................................... 8-10 8.3.2 C Adapter API ............................................................................................................................8-11 8.3.3 My First C Adapter ................................................................................................................... 8-13 8.3.4 Debugging C Adapters............................................................................................................. 8-34 8.3.5 Java Adapter API....................................................................................................................... 8-36 8.3.6 My First Java Adapter............................................................................................................... 8-38 8.3.7 Debugging Java Adapters ........................................................................................................ 8-53 8.3.8 Testing an Adapter .................................................................................................................... 8-57 9 Propagating Content Filters 9.1 Enabling Filter Propagation ..................................................................................................................... 9-2 9.2 Filter Propagation Behavior ..................................................................................................................... 9-2 9.2.1 Filter Propagation Events........................................................................................................... 9-3 9.2.2 StreamReader’s Filter Set by Configuration............................................................................ 9-4 9.2.3 Remote Administration .............................................................................................................. 9-4 9.3 Restrictions ................................................................................................................................................. 9-5 v Chapter 1 Welcome to RTI Routing Service Welcome to RTI® Routing Service, an out- of-the-box solution for integrating disparate and geographically dispersed systems. It scales RTI Connext™ DDS applications across domains, LANs and WANs, including firewall and NAT traversal. Routing Service also supports DDS-to-DDS bridging by allowing you to make transformations in the data along the way. This allows unmodified DDS applications to communicate even if they were developed using incompatible interface definitions. This is often the case when integrating new and legacy applications or independently developed systems. Using RTI Routing Service Adapter SDK, you can extend Routing Service to interface with non-DDS systems using off-the-shelf or custom developed adapters, including to third-party JMS implementations and legacy code written to the network socket API. Traditionally, Connext DDS applications can only communicate with applications in the same domain. With Routing Service, you can send and receive data across domains. You can even transform and filter the data along the way! Not only can you change the actual data values, you can change the data’s type. So the sending and receiving applications don’t even need to use the same data structure. You can also control which data is sent by using allow and deny lists. Connext Application Connext Application Routing Service Routing Service JMS Application JMS Application Simply set up Routing Service to pass data from one domain to another and specify any desired data filtering and transformations. No changes are required in the Connext DDS applications. Key benefits of Routing Service: ❏ It can significantly reduce the time and effort spent integrating and scaling Connext DDS applications across Wide Area Networks and Systems-of-Systems. Many systems today already rely on Connext DDS to distribute their information across a Local Area Network (LAN). However, more and more of these systems are being integrated in Wide Area Networks (WANs). With Routing Service, you can scale Connext DDS real-time publish/subscribe data-distribution beyond the current local networks and make it available throughout a WAN—without making any changes to existing Connext DDS applications. You can take an existing, even deployed system and integrate it with new applications or other existing systems without changing those existing systems. 1-1 ❏ With Routing Service, you can build modular systems out of existing systems. Data can be contained in private domains within subsystems and you can designate that only certain “global topics” can be seen across domains. The same mechanism controls the scope of discovery. Both application-level and discovery traffic can be scoped, facilitating scalable designs. ❏ Routing Service provides secure deployment across multiple sites. You can partition networks and protect them with firewalls and NATS and precisely control the flow of data between the network segments. ❏ It allows you to manage the evolution of your data model at the subsystem level. You can use Routing Service to transform data on the fly, changing topic names, type definitions, QoS, etc., seamlessly bridging different generations of topic definitions. ❏ Routing Service provides features for development, integration and testing. Multiple sites can each locally test and integrate their core application, expose selected topics of data, and accept data from remote sites to test integration connectivity, topic compatibility and specific use-cases. ❏ It connects remotely to live, deployed systems so you can perform live data analytics, fault condition analysis, and data verification. ❏ RTI Routing Service Adapter SDK allows you to quickly build and deploy bridges to integrate DDS and non-DDS systems. This can be done in a fraction of the time required to develop completely custom solutions. Bridges automatically inherit advanced DDS capabilities, including automatic discovery of applications; data transformation and filtering; data lifecycle management and support across operating systems; programming languages and network transports. RTI Routing Service Adapter SDK offers an out-of-the-box solution for interfacing with third-party protocols and technology. It includes prebuilt adapters that can be used outof-the-box to interface with third-party Java Message Service (JMS) providers or legacy code written to the network socket API. Adapters include source code so they can be easily modified to meet application-specific requirements or serve as a template for quick creation of new custom adapters. Quickly build and deploy bridges between natively incompatible protocols and technologies using Connext DDS 1-2 Available Documentation 1.1 Available Documentation Routing Service documentation includes: ❏ Getting Started Guide (RTI_Routing_Service_GettingStarted.pdf)—Highlights the bene- fits of Routing Service. It provides installation and startup instructions, and walks you through several examples so you can quickly see the benefits of using Routing Service. ❏ Release Notes (RTI_Routing_Service_ReleaseNotes.pdf)—Describes system require- ments and compatibility, as well as any version-specific changes and known issues. ❏ User’s Manual (RTI_Routing_Service_UsersManual.pdf)—Describes how to configure Routing Service and use it remotely. 1.2 Paths Mentioned in Documentation The documentation refers to: ❏This refers to the installation directory for Connext DDS. The default installation paths are: • Mac OS X systems: /Applications/rti_connext_dds-version • UNIX-based systems, non-root user: /home/your user name/rti_connext_dds-version • UNIX-based systems, root user: /opt/rti_connext_dds-version • Windows systems, user without Administrator privileges: \rti_connext_dds-version • Windows systems, user with Administrator privileges: C:\Program Files\rti_connext_dds-version (for 64-bits machines) or C:\Program Files (x86)\rti_connext_dds-version (for 32-bit machines) You may also see $NDDSHOME or %NDDSHOME%, which refers to an environment variable set to the installation path. Wherever you see used in a path, replace it with your installation path. Note for Windows Users: When using a command prompt to enter a command that includes the path C:\Program Files (or any directory name that has a space), enclose the path in quotation marks. For example: “C:\Program Files\rti_connext_dds-version\bin\rtiddsgen” or if you have defined the NDDSHOME environment variable: “%NDDSHOME%\bin\rtiddsgen” 1-3 Paths Mentioned in Documentation ❏ RTI Workspace directory, rti_workspace The RTI Workspace is where all configuration files for the applications and example files are located. All configuration files and examples are copied here the first time you run RTI Launcher or any script in /bin. The default path to the RTI Workspace directory is: • Mac OS X systems: /Users/your user name/rti_workspace • UNIX-based systems: /home/your user name/rti_workspace • Windows systems: your Windows documents folder\rti_workspace Note: 'your Windows documents folder' depends on your version of Windows. For example, on Windows 7, the folder is C:\Users\your user name\Documents; on Windows Server 2003, the folder is C:\Documents and Settings\your user name\Documents. You can specify a different location for the rti_workspace directory. See the RTI Connext DDS Core Libraries Getting Started Guide for instructions. ❏ Examples are copied into your home directory the first time you run RTI Launcher or any script in /bin. This document refers to the location of these examples as . Wherever you see , replace it with the appropriate path. By default, the examples are copied to rti_workspace/version/examples So the paths are: • Mac OS X systems: /Users/your user name/rti_workspace/version/examples • UNIX-based systems: /home/your user name/rti_workspace/version/examples • Windows systems: your Windows documents folder\rti_workspace\version\examples Note: 'your Windows documents folder' is described above. You can specify that you do not want the examples copied to the workspace. See the RTI Connext DDS Core Libraries Getting Started Guide for instructions. 1-4 Chapter 2 Configuring Routing Service This document describes how to configure Routing Service. To see installation instructions, or to walk through some simple examples, please see the Getting Started Guide. When you start Routing 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. This chapter describes: ❏ ❏ ❏ ❏ ❏ ❏ ❏ 2.1 Terms to Know (Section 2.1) How to Load the XML Configuration (Section 2.2) XML Syntax and Validation (Section 2.3) XML Tags for Configuring Routing Service (Section 2.4) Enabling and Disabling Routing Service Entities (Section 2.5) Enabling RTI Distributed Logger in Routing Service (Section 2.6) Support for Extensible Types (Section 2.7) Terms to Know Before learning how to configure Routing Service, you should become familiar with a few key terms and concepts. ❏ A routing service entity refers to an execution of Routing Service. ❏ A domain route defines a two-way mapping between two data domains. For example, a domain route could define a mapping between two different domains or between a domain and a JMS provider's network. ❏ A session defines a single-threaded context for routes. Data cannot be read and written from two routes in the session concurrently. ❏ A route defines a one-way mapping between an “input” stream in one domain and an “output” stream in the other domain. For example, in a route between DDS and JMS, the input stream will be a DDS topic and the output stream will be a JMS topic or queue. ❏ An auto route defines a set of potential routes that can be instantiated based on deny/ allow filters on the stream name and registered type name. ❏ A transformation is a pluggable component that changes data from the “input” stream A to data in the “output” stream B. 2-1 How to Load the XML Configuration ❏ An adapter is a pluggable component that allows Routing Service to consume and produce data for different data domains. By default, Routing Service is distributed with a builtin DDS adapter. 2.2 How to Load the XML Configuration Routing Service loads its XML configuration from multiple locations. This section presents the various approaches, listed in load order. The first three locations only contain QoS Profiles and 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 The files (or XML strings) separated by semicolons referenced in this environment variable are loaded automatically. ❏ /USER_QOS_PROFILES.xml This file is loaded automatically if it exists. The next locations are specific to Routing Service. ❏ $NDDSHOME/resource/xml/RTI_ROUTING_SERVICE.xml This file contains the default Routing Service configuration; it is loaded if it exists. RTI_ROUTING_SERVICE.xml defines a service that automatically routes all types and topics between domains 0 and 1. ❏ /USER_ROUTING_SERVICE.xml This file is loaded automatically if it exists. ❏ File specified using the command line parameter -cfgFile The command-line option -cfgFile (see Table 3.1 on page 3-2) can be used to specify a configuration file. ❏ File specified using the remote command ‘load’ The load command (see Section 5.2.7) allows loading an XML file remotely. The file loaded using this command replaces to the file loaded using the -cfgFile command-line option. (Last to be loaded.) You may use a combination of the above approaches. Figure 2.1 shows an example configuration file. You will learn the meaning of each line as you read the rest of this chapter. 2-2 XML Syntax and Validation Figure 2.1 Example XML Configuration File This file configures a simple bridge from domain 0 to domain 1 and changes the data’s topic from Square to Circle. Both topics use the same data type (ShapeType). You will find this example in 0 1 ShapeType Square / roouting_service/shapes/topic_bridge.xml. Additional examples are in the same directory. 2.3 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 string. Legal values are alphanumeric characters. Routing Service’s parser will remove all leading and trailing spaces1 from the string before it is processed. For example, " value " is the same as "value ". ❏ All values are case-sensitive unless otherwise stated. 1. Leading and trailing spaces in enumeration fields will not be considered valid if you use the distributed XSD document to do validation at run-time with a code editor. 2-3 XML Syntax and Validation ❏ Comments are enclosed as follows: . ❏ The root tag of the configuration file must beand end with . Routing 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 routine service’s configuration—this provides helpful features in code editors such as Visual Studio and Eclipse, including validation and auto-completion while you are editing the XML file. The DTD and XSD definitions of the XML elements are in $NDDSHOME/resource/schema/ rti_routing_service.dtd and $NDDSHOME/resource/schema/rti_routing_service.xsd, respectively. To include a reference to the XSD document in your XML file, use the attribute xsi:noNamespaceSchemaLocation in thetag. For example: ... To include a reference to the DTD document in your XML file, use the tag. For example:... We recommend including a reference to the XSD file in the XML documents; this provides stricter validation and better auto-completion than the corresponding DTD file. 2-4 XML Tags for Configuring Routing Service 2.4 XML Tags for Configuring Routing Service This section describes the XML tags you can use in a Routing Service configuration file. The following diagram and Table 2.1 describe the top-level tags allowed within the roottag. Optional Required Table 2.1 Top-level Tags in the Configuration File Tags within Description Number of Tags Allowed Specifies a library of adapter plugins. See Adapters (Section 2.4.8) and Chapter 8: Extending Routing 0 or more Service with Adapters. Specifies a QoS library and profiles. The contents of this tag are specified in the same manner as for a 0 or more Connext DDS QoS profile file—see Chapter 15 in the RTI Connext DDS Core Libraries User’s Manual. Specifies a Routing Service configuration. See Routing Service 1 or more (Section 2.4.1). (required) Specifies a library of transformation plugins. See Data Transformation (Section 2.4.6.5) and Chapter 4: 0 or more Transforming Data with Routing Service. Defines types that can be used by the routing service. See Defining Types in the Configuration File (Section 0 or 1 2.4.6.2). 2-5 XML Tags for Configuring Routing Service 2.4.1 Routing Service A configuration file must have at least one tag; this tag is used to configure an execution of Routing Service. A configuration file may contain multiple tags. When you start Routing Service, you can specify which tag to use to configure the service using the -cfgName command-line parameter. For example: Starting Routing Service with the following command will use the ... ... tag with the name Router1: rtiroutingservice -cfgFile example.xml -cfgName Router1 Because a configuration file may contain multiple tags, one file can be used to configure multiple Routing Service executions. A routing service may belong to a group of several routing services identified by a common group_name. This common name can be used to implement a specific policy when the communication happens between routing services of the same group. For example, in the builtin DDS adapter, a participant will ignore other participants in the same group, as a way to avoid circular communication. If the tag does not have a group_name attribute, Routing Service will use the following name: RTI_RoutingService_ _ , such as RTI_RoutingService_myhost_20024. Optional Required Table 2.2 describes the tags allowed within a tag. Notice that the tag is required. Table 2.2 Routing Service Tags Tags within Description Number of Tags Allowed Enables and configures remote administration. See Administration (Section 2.4.3) and Chapter 5: Administering Routing Service from a 0 or 1 Remote Location. Contains a tag that can be used to provide a routing service description. This description will show up when you run Rout- 0 or 1 ing Service without the -cfgName command-line option. 2-6 XML Tags for Configuring Routing Service Table 2.2 Routing Service Tags Tags within Description Number of Tags Allowed 1 or more (required) Defines a mapping between two data domains. See Section 2.4.2. Enables and configures remote monitoring for the routing_service 0 or 1 entity. Configures the Java JVM used to load and run Java adapters such as the JMS Adapter. For example: You can use the SocketAdapter.jar 0 or 1-Xms32m -Xmx128m tag to specify options for the JVM, such as the initial and maximum Java heap sizes. Enables and configures general remote monitoring. General monitoring settings are applicable to all the Routing Service entities unless they 0 or 1 are explicitly overridden. See Monitoring (Section 2.4.4). 2-7 XML Tags for Configuring Routing Service 2.4.2 Domain Route A domain route defines a mapping between two data domains. Data available in either of these data domains can be routed to the other one. For example, a domain route could define a mapping between two different DDS domains or between a DDS domain and a JMS provider's network. How this data is actually read and written is defined in specific routes. A domain route creates two connections, known as connection_1 and connection_2. Each connection belongs to one of the two data domains. For example: ... . . . ... ... The connection tags require the specification of the attribute plugin_name, which will be used to associate a connection with an adapter plugin defined within (see Section 2.1). 2-8 XML Tags for Configuring Routing Service For DDS domains, the connections are specified using the tags participant_1 and participant_2. Each tag has one associated DomainParticipant. The following example routes information between two DDS domains. Configurations mixing connections and participants are allowed to provide communication between DDS domains and other data domains. ... 54 ...55 ...... The following example routes information between a JMS provider network and a DDS domain. Table 2.3 lists the tags allowed within a ... ... 55 ...... tag. Notice that most of these tags are required. Table 2.4 lists the tags allowed within and tags. 2-9 XML Tags for Configuring Routing Service Table 2.5 lists the tags allowed within and tags. Notice that the tag is required. Table 2.3 Domain Route Tags Tags within Table 2.4 Number of Tags Allowed Description Applicable to non-DDS domains. 1 (required) Configures the first connection. See Table 2.4. Applicable to non-DDS domains. 1 (required) Configures the second connection. See Table 2.4. Enables and configures remote monitoring for the domain route. See 0 or 1 Monitoring (Section 2.4.4). Only applicable to DDS domains. 1 (required) Configures the first participant. See Table 2.5. Only applicable to DDS domains. 1 (required) Configures the second participant. See Table 2.5. Defines a single-threaded context in which data is routed according 1 or more to specified routes. See Session (Section 2.4.5). (required) Connection Tags Tags within Number of Tags Allowed Description Registers a type name and associates it with a type representation. When you define a type in the configuration file (with the tag), 0 or more you have to register the type in order to use it in routes. See Route Types (Section 2.4.6.1). Sequence of name/value(string) pairs that can be used to configure the parameters of the connection. For example: 0 or 1 2-10 XML Tags for Configuring Routing Service Table 2.5 Participant Tags Tags within jms.connection.username myusername Description Sets the domain ID associated with the participant. Number of Tags Allowed 1 (required) Configures certain aspects of how Connext DDS allocates internal memory. The configuration is per domain_route's participant and therefore affects all the contained DataReaders and DataWriters. For example: ... 0 ...X true The tag can include the following tags: ❏ ❏ 0 or more sample_buffer_min_size: For all DataReaders and DataWriters, the way Connext DDS allocates memory for samples is as follows: Connext DDS pre-allocates space for samples up to size X in the reader and writer queues. If a sample has an actual size greater than X, the memory is allocated dynamically for that sample. The default size is 64KB. This is the maximum amount of pre-allocated memory. Dynamic memory allocation may occur when necessary if samples require a bigger size. sample_buffer_trim_to_size: If set to true, after allocating dynamic memory for very large samples, that memory will be released when possible. If false, that memory will not be released but kept for future samples if needed. The default is false. This feature is useful when a data type has a very high maximum size (e.g., megabytes) but most of the samples sent are much smaller than the maximum possible size (e.g., kilobytes). In this case, the memory footprint is reduced dramatically, while still correctly handling the rare cases in which very large samples are published. 2-11 XML Tags for Configuring Routing Service Table 2.5 Participant Tags Tags within Description Number of Tags Allowed Registers a type name and associates it with a type code. When you define a type in the configuration file (with the tag), you have 0 or more to register the type in order to use it in topic routes. See Route Types (Section 2.4.6.1). Sets the participant QoS. The contents of this tag are specified in the same manner as a Connext DDS QoS profile file—see Chapter 15 in the RTI Connext DDS Core Libraries User’s Manual. If not specified, the DDS defaults are used, except for the participant name which takes the following value: "RTI Routing Service: . #[1|2]" (for example "RTI Routing Service: MyService.MyDomainRoute#1"). Note: Changing the default participant name may prevent Routing Service from being detected by Admin Console. You can use a tag inside a / previously defined in your configuration file by referring to it like this: 0 or 1 To use that profile but override just some values: (This applies to all QoS tags: udpv4://192.168.1..12 shmem:// , in sessions; , in topic routes and auto topic routes.) 2.4.3 Administration You can create a Connext DDS application that can remotely control Routing Service. The tag is used to enable remote administration and configure its behavior. By default, remote administration is turned off in Routing Service for security reasons. A remote administration section is not required in the configuration file. For example: 2-12 XML Tags for Configuring Routing Service When remote administration is enabled, Routing Service will create a DomainParticipant, Publisher, Subscriber, DataWriter, and DataReader. These entities are used to receive commands and send responses. You can configure these entities with QoS tags within the ... 55 /home/david/mysaved_config.xml tag. Table 2.6 lists the tags allowed within tag. Notice that the tag is required. For more details, please see Chapter 5: Administering Routing Service from a Remote Location. Note: The command-line options used to configure remote administration take precedence over the XML configuration (see Table 3.1 on page 3-2). Table 2.6 Remote Administration Tags Tags within Number of Tags Allowed Description A boolean that, if true, automatically triggers a save command when configuration updates are received. It is false by default. This value is mutable when an update (Section 5.2.12) command targets a routing service. 0 or 1 This value is sent as part of the monitoring configuration data for the routing service (see Configuration Data for Routing Service (Section 6.2.1)). Configures the DataReader QoS for remote administration. If the tag is not defined, Routing Service will use the Connext DDS defaults with the following changes: reliability.kind = DDS_RELIABLE_RELIABILITY_QOS (this value 0 or 1 cannot be changed) history.kind = DDS_KEEP_ALL_HISTORY_QOS resource_limits.max_samples = 32 Configures the DataWriter QoS for remote administration. If the tag is not defined, Routing Service will use the Connext DDS defaults with the following changes: 0 or 1 history.kind = DDS_KEEP_ALL_HISTORY_QOS resource_limits.max_samples = 32 Configures RTI Distributed Logger. See Enabling RTI Distributed Logger in Routing Service (Section 2.6). 0 or 1 Specifies which domain ID Routing Service will use to enable remote 1 administration. (required) Configures the DomainParticipant QoS for remote administration. If the tag is not defined, Routing Service will use the Connext DDS 0 or 1 defaults. Configures the Publisher QoS for remote administration. If the tag is not defined, Routing Service will use the Connext DDS 0 or 1 defaults. 2-13 XML Tags for Configuring Routing Service Table 2.6 Remote Administration Tags Tags within Number of Tags Allowed Description Specifies the file that will contain the saved configuration. It is empty by default. A must be specified if you want to use the save (Section 5.2.10) command. If the file specified by already exists, the file will be overwritten when save is executed. This value is mutable when an update (Section 5.2.12) command targets a routing service. 0 or 1 This value is sent as part of the monitoring configuration data for the routing service (see Configuration Data for Routing Service (Section 6.2.1)). Configures the Subscriber QoS for remote administration. 2.4.4 If the tag is not defined, Routing Service will use the Connext DDS 0 or 1 defaults. Monitoring You can create a Connext DDS application that can remotely monitor the status of Routing Service. To enable remote monitoring and configure its behavior, use the and tags. By default, remote monitoring is turned off in Routing Service for security and performance reasons. A remote monitoring section is not required in the configuration file. For example: Routing Service allows monitoring of the following kinds of entities: ❏ ❏ ❏ ❏ ❏ ❏ ❏ true ... 55 1 (see Section 2.4.1) (see Section 2.4.2) (see Section 2.4.5) (see Section 2.4.6) (see Section 2.4.6) (see Section 2.4.7) (see Section 2.4.7) For each entity, Routing Service can publish two kinds of information: ❏ Entity data 2-14 XML Tags for Configuring Routing Service ❏ Entity status Entity data provides information about the configuration of the entity. For example, the route data contains information such as the stream name and the type name. Entity data information is republished every time the entity is enabled, disabled or has configuration changes. Entity status provides information about the operational status of an entity. This kind of information changes continuously and is computed and published periodically. For example, the route status contains information such as the route’s latency and throughput. For more information about entity data and status, see Chapter 6: Monitoring Routing Service from a Remote Location. When remote monitoring is enabled, Routing Service will create one DomainParticipant, one Publisher, five DataWriters for data publication (one for each kind of entity), and five DataWriters for status publication (one for each kind of entity). You can configure the QoS of these entities with the tag defined under . The general remote monitoring parameters specified using the tag in (except domain_id, participant_qos, publisher_qos, and datawriter_qos) can be overwritten on a per entity basis using the tag. For example: Table 2.7 lists the tags allowed within the ... 55 1 ... 4 tag. Table 2.7 Monitoring tags Tags within Description Number of Tags Allowed Configures the DataWriter QoS for remote monitoring. If the tag is not defined, Routing Service will use the Connext DDS 0 or 1 defaults with the following change: durability.kind = DDS_TRANSIENT_LOCAL_DURABILITY_QOS Specifies which domain ID Routing Service will use to enable remote 1 monitoring. (required) 2-15 XML Tags for Configuring Routing Service Table 2.7 Monitoring tags Tags within Description Number of Tags Allowed Enables/disables general remote monitoring. Setting this value to true (default value) in the tag under enables monitoring in all the entities unless they explicitly disable it by setting this tag to false in their local tags. 0 or 1 Setting this tag to false in the tag under disables monitoring in all the Routing Service entities. In this case, any monitoring configuration settings in the entities are ignored. Enables or disables the publication of statistics calculated within fixed time windows. By default, Routing Service only publishes the statistics corresponding to the window between two status publications. By using this tag, you can get the following additional windows: ❏ ❏ ❏ ❏ ❏ 5 seconds 1 minute 5 minutes 1 hour Up time (since the entity was enabled) 0 or 1 For example: If a window is not present (inside the tag true true false true false ), it is considered disabled. Historical statistics can be overwritten on a per entity basis. Configures the DomainParticipant QoS for remote monitoring. If the tag is not defined, Routing Service will use the Connext DDS 0 or 1 defaults with the following change: resource_limits.type_code_max_serialized_length = 4096 Configures the Publisher QoS for remote monitoring. If the tag is not defined, Routing Service will use the Connext DDS 0 or 1 defaults. 2-16 XML Tags for Configuring Routing Service Table 2.7 Monitoring tags Tags within Description Number of Tags Allowed Specifies the frequency at which status statistics are gathered. Statistical variables such as latency, are part of the entity status. For example: 0 or 1 The statistics period for a given entity should be smaller than the publication period. If the tag is not defined, the period is 1 second. The statistics sampling period defined in 1 0 is inherited by all the entities inside . An entity can overwrite the period. Specifies the frequency at which the status of an entity is published. For example: 0 or 1 If the tag is not defined, the period is 5 seconds. The status publication period defined in 3 0 is inherited by all the entities inside . An entity can overwrite the period. 2.4.4.1 Monitoring Configuration Inheritance The monitoring configuration defined in is inherited by all the entities defined inside the tag. An entity can overwrite three elements of the monitoring configuration: ❏ The status publication period ❏ The statistics sampling period ❏ The historical statistics windows Each one of this three elements is inherited and can be overwritten independently using the tag. For example: In the previous example, the domain route overwrites the status publication period to 4 seconds and inherits the statistics sampling period. Table 2.8 Entity Monitoring Tags Tags within ... 55 1 1 0 2-17 XML Tags for Configuring Routing Service... 4 Description Number of Tags Allowed Enables/disables remote monitoring for a given entity. If general monitoring is disabled this value is ignored. 0 or 1 Default value: true Enables or disables the publication of statistics calculated within fixed time windows. By default, Routing Service only publishes the statistics corresponding to the window between two status publications. By using this tag, you can get the following additional windows: ❏ ❏ ❏ ❏ ❏ 5 seconds 1 minute 5 minutes 1 hour Up time (since the entity was enabled) For example: 0 or 1 If a window is not present (inside the tag true true false true false ), it is considered disabled. If this tag is not defined, historical statistics are inherited from the general monitoring settings. 2-18 XML Tags for Configuring Routing Service Table 2.8 Entity Monitoring Tags Tags within Description Number of Tags Allowed Specifies the frequency at which status statistics are gathered. Statistical variables such as latency, are part of the entity status. For example: 1 0 publication period. If the tag is not defined, the period is inherited from the general monitoring settings. This tag is only present in the tag of , , , and . Specifies the frequency at which the status of an entity is published. For example: 0 or 1 If the tag is not defined, its value is inherited from the general monitoring settings. 2.4.5 Session A 3 0 tag defines a single-threaded context for data routing; The data is routed according to specified routes (Section 2.4.6) and auto routes (Section 2.4.7). Each session will have an associated session thread that will serialize access to the routes in the session. For example: ... 2-19 XML Tags for Configuring Routing Service Sessions that bridge domains will create a Publisher and a Subscriber in the participants (participant_1 or participant_2) associated with the domains. Table 2.9 lists the tags allowed within a... ...... ...... ...... ...tag. Table 2.9 Session Tags Tags within Number of Tags Allowe d Description Defines a general route based on type and stream filters. See Auto Routes (Sec0 or more tion 2.4.7). Defines a general topic route based on type and topic filters. See Auto Routes 0 or more (Section 2.4.7). Enables and configures remote monitoring for the session. See Monitoring (Section 2.4.4) and Chapter 6: Monitoring Routing Service from a Remote 0 or 1 Location. Sequence of name/value(string) pairs that can be used to configure certain parameters of the session. For example: 0 or 1 These properties are only used in non-DDS domains. Only applicable to Connext DDS. com.rti.socket.timeout 1 Sets the QoS associated with the session Publishers. There is one Publisher per participant. The contents of this tag are specified in the same manner as a Connext DDS 0 or 1 QoS profile file—see the chapter Configuring QoS with XML in the RTI Connext DDS Core Libraries User’s Manual. If the tag is not defined, Routing Service will use the Connext DDS defaults. Defines a data mapping between two streams. See Routes (Section 2.4.6) 0 or more Only applicable to Connext DDS. Sets the QoS associated with the session Subscribers. There is one Subscriber per participant. The contents of this tag are specified in the same manner as a Connext DDS 0 or 1 QoS profile file—see the chapter Configuring QoS with XML in the RTI Connext DDS Core Libraries User’s Manual. If the tag is not defined, Routing Service will use the Connext DDS defaults. 2-20 XML Tags for Configuring Routing Service Table 2.9 Session Tags Tags within Number of Tags Allowe d Description Sets the mask, priority and stack size of the thread associated with this session. Example: 0 or 1 Default values: mask = MASK_DEFAULT priority = THREAD_PRIORITY_DEFAULT stack_size = THREAD_STACK_SIZE_DEFAULT ... MASK_DEFAULT THREAD_PRIORITY_DEFAULT THREAD_STACK_SIZE_DEFAULT Defines a data mapping between two topics. See Routes (Section 2.4.6). 0 or more Configures the WaitSet used to sleep and notify the session thread when data is available. Example: 0 or 1 In the previous example, the session thread wakes up and tries to read data after a 1 second timeout expires (max_event_delay) or after it has been notified five times across routes that new data is available (max_event_count). Default values: max_event_count = 1 max_event_delay.sec = DURATION_INFINITE_SEC max_event_delay.nanosec = DURATION_INFINITE_NSEC 2.4.6 Routes A route explicitly defines a mapping between an “input” data stream on one domain and an “output” data stream on the other domain. For example, the following route defines a mapping between a topic called Square and a JMS queue called Square. ... 5 1 0 ... DDS inputs and outputs within a route are defined using the XML tags... 2-21 XML Tags for Configuring Routing Service ...... 54 ... ... ...... Square ShapeType ...and . Input and outputs from other data domains are defined using the tags and