11. Tutorials¶

This chapter describes several examples, all of which use RTI Shapes Demo to publish and subscribe to topics which are colored moving shapes.

In each example, you can start all the applications on the same computer or on different computers in your network. If you don’t have Shapes Demo installed already, you should download and install it from RTI’s Downloads page or the RTI Support Portal (the latter requires an account name and password). If you are not already familiar with how to start Shapes Demo and change its domain ID, please see the Shapes Demo User’s Manual for details.

Important Notes:

Please review Section 1.2 to understand where to find the examples (referred to as <path to examples>).
The following instructions include commands that you will enter in a command shell. These instructions use forward slashes in directory paths, such as bin/rtiroutingservice. If you are using a Windows platform, replace all forward slashes in such paths with backwards slashes, such as bin\rtiroutingservice.
If you run Shapes Demo and Routing Service on different machines and these machines do not communicate over multicast, you will have to set the environment variable NDDS_DISCOVERY_PEERS to enable communication. For example, assume that you run Routing Service on Host 1 and Shapes Demo on Host 2 and Host 3. In this case, the environment variable would be set as follows:

Host 1:
```
set NDDS_DISCOVERY_PEERS=<host2>,<host3> (on Windows systems)
export NDDS_DISCOVERY_PEERS=<host2>,<host3> (on UNIX-based systems)
```
Host 2:
```
set NDDS_DISCOVERY_PEERS=<host1>
```
Host 3:
```
export NDDS_DISCOVERY_PEERS=<host1>
```

11.1. Starting Shapes Demo¶

You can start Shapes Demo from the Learn tab in RTI Launcher.

Or from a command shell:

<NDDSHOME>/bin/rtishapesdemo

NDDSHOME is described in Section 1.2.

11.2. Example: Routing All Data from One Domain to Another¶

This example uses the default configuration file [1] for Routing Service, which routes all data published on domain 0 to subscribers on domain 1.

Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.
Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:
- Open its Configuration dialog (under Controls).
- Press Stop.
- Change the domain ID to 1.
- Press Start.
In the Publishing Demo, publish some Squares, Circles, and Triangles.
In the Subscribing Demo, subscribe to Squares, Circles and Triangles.

Notice that the Subscribing Demo does not receive any shapes. Since we haven’t started Routing Service yet, data from domain 0 isn’t routed to domain 1.
Start Routing Service by entering the following in a command shell:
cd <NDDSHOME> bin/rtiroutingservice -cfgName default
Now you should see all the shapes in the Subscribing Demo.
Stop Routing Service by pressing Ctrl-c.

You should see that the Subscribing Demo stops receiving shapes.

Additionally, you can start Routing Service (Step 5) with the following parameters:

-verbosity 3, to see messages from Routing Service including events that have triggered the creation of routes.
-domainIdBase X, to use domains X and X+1 instead of 0 and 1 (in this case, you need to change the domain IDs used by Shapes Demo accordingly). This option adds X to the domain IDs in the configuration file.

Note

-domainIdBase only affects the domain IDs of DomainRoute participants; it does not affect the domain IDs of participants used for monitoring or administration.

[1]	<NDDSHOME>/resource/xml/RTI_ROUTING_SERVICE.xml

11.3. Example: Changing Data to a Different Topic of Same Type¶

In this example, Routing Service receives samples of topic Square and republishes them as samples of topic Circle.

Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.
Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:
- Open its Configuration dialog (under Controls).
- Press Stop.
- Change the domain ID to 1.
- Press Start.
In the Publishing Demo, publish some Squares, Circles, and Triangles.

Start Routing Service by entering the following in a command shell:

cd <NDDSHOME>
bin/rtiroutingservice
-cfgFile <path to examples>/routing_service/shapes/topic_bridge.xml \
-cfgName example

In the Subscribing Demo, subscribe to Squares, Circles and Triangles.

Notice that the Subscribing Demo does not receive any shapes. Since we haven’t started Routing Service yet, data from domain 0 isn’t routed to domain 1.
Stop Routing Service by pressing Ctrl-c.
Try writing your own topic route that republishes triangles on domain 0 to circles on domain 1. Create some Triangle publishers and a Circle subscriber in the respective Shapes Demo windows.

11.4. Example: Changing Some Values in Data¶

So far, we have learned how to route samples from one topic to another topic of the same data type. Now we will see how to change the value of some fields in the samples and republish them.

Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.
Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:
- Open its Configuration dialog (under Controls).
- Press Stop.
- Change the domain ID to 1.
- Press Start.
In the Publishing Demo, publish some Squares, Circles, and Triangles.

Start Routing Service by entering the following in a command shell:

cd <NDDSHOME>
bin/rtiroutingservice
-cfgFile <path to examples>/routing_service/shapes/topic_bridge_w_transf1.xml \
-cfgName example

In the Subscribing Demo, subscribe to Squares, Circles and Triangles.

Notice that the (x,y) coordinates of the shapes are inverted form what appears in the Publishing Demo.
Stop Routing Service by pressing Ctrl-c.
Try changing the transformation to assign the output shapesize to the input x.

11.5. Example: Transforming the Data’s Type and Topic with an Assignment Transformation¶

This example shows how to transform the data topic and type. We will use rtiddsspy to verify the result. rtiddsspy is a utility provided with Connext DDS; it monitors publications on any DDS domain.

Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.
In the Publishing Demo, publish some Squares, Circles, and Triangles.

Start Routing Service by entering the following in a command shell:

cd <NDDSHOME>
bin/rtiroutingservice
-cfgFile <path to examples>/routing_service/shapes/topic_bridge_w_transf2.xml \
-cfgName example

We will use the rtiddsspy utility to verify the transformation of the data topic and type. Run these commands:
cd <NDDSHOME> bin/rtiddsspy -domainId 0 -printSample bin/rtiddsspy -domainId 1 -printSample
You will notice that the publishing samples received by rtiddsspy for domain 0 are of type ShapeType and topic Square. The subscribing samples received by rtiddsspy for domain 1 are of type Point and topic Position. Notice that the two data structures are different.
Stop Routing Service by pressing Ctrl-c.

11.6. Example: Transforming the Data with a Custom Transformation¶

Now we will use our own transformation between shapes. Routing Service allows you to install plug-ins that implement the Transformation API to create custom transformations. To build a custom transformation, you must have the Connext DDS libraries installed.

Note

This example assumes your working directory is <path to examples>/routing_service/shapes/transformation/[make or windows]. If your working directory is different, you will need to modify the configuration topic_bridge_w_custom_transf.xml to update the paths.

Compile the transformation in <path to examples>/routing_service/shapes/transformation/[make or windows]:
- On UNIX-based systems:
  - Set the environment variable NDDSHOME (see Section 1.2). For details on how to set it, see the RTI Connext DDS Core Libraries Getting Started Guide.
  - Enter:
    
    cd <path to examples>/routing_service/shapes/transformation/make gmake -f Makefile.<architecture>
- On Windows systems:
  - Set the environment variable NDDSHOME (see Section 1.2). For details on how to set it, see the RTI Connext DDS Core Libraries Getting Started Guide.
  - Open the Visual Studio solution under <path to examples>\routing_service\shapes\transformation\windows.
  - Select the Release DLL build mode and build the solution.
Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.
In the Publishing Demo, publish some Squares.

Start Routing Service by entering the following in a command shell:

cd <NDDSHOME>
bin/rtiroutingservice
-cfgFile <path to examples>/routing_service/shapes/topic_bridge_w_custom_transf.xml \
-cfgName example

Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:
- Open its Configuration dialog (under Controls).
- Press Stop.
- Change the domain ID to 1.
- Press Start.
In the Subscribing Demo, subscribe to Squares.

Notice that squares on domain 1 have only two possible values for x.
Stop Routing Service by pressing Ctrl-c.
Change the fixed ‘x’ values for the Squares in the configuration file and restart Routing Service.
Stop Routing Service by pressing Ctrl-c.
Edit the source code (in shapestransf.c) to make the transformation multiply the value of the field by the given integer constant instead of assigning the constant.

Hint

Look for the function ShapesTransformationPlugin_createOutputSample(), called from ShapesTransformation_transform() and use DDS_DynamicData_get_long() before DDS_DynamicData_set_long().
Recompile the transformation (the new shared library will be copied automatically) and run Routing Service as before.

11.7. Example: Using Remote Administration¶

In this example, we will configure Routing Service remotely. We won’t see data being routed until we remotely enable an AutoTopicRoute after the application is started. Then we will change a QoS value and see that it takes effect on the fly.

Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.
In the Publishing Demo, publish some Squares, Circles and Triangles.

Start Routing Service by entering the following in a command shell:

cd <NDDSHOME>
bin/rtiroutingservice
-cfgFile <path to examples>/routing_service/shapes/administration.xml \
-cfgName example -appName MyRoutingService

Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:
- Open its Configuration dialog (under Controls).
- Press Stop.
- Change the domain ID to 1.
- Press Start.
In the Subscribing Demo, subscribe to Squares, Circles and Triangles.

Notice that no data is routed to domain 1.
On a different or the same machine, start the Routing Service remote shell:
cd <NDDSHOME> bin/rtirssh -domainId 0
Note

We use domain 0 in the shell because Routing Service is configured in administration.xml to receive remote commands on that domain. You could have started Routing Service with the -remoteAdministrationDomainId command-line option and then used domain X for the shell.
In the shell, enter the following command:
enable MyRoutingService RemoteConfigExample::Session::Shapes
Notice that the shapes are now received on domain 1. The above command consists of two parts: the name of the Routing Service, which you gave when you launched the application with the option -appName, and the name of the entity you wanted to enable. That name is formed by appending its parent entities’ names starting from the domain route as defined in the configuration file administration.xml.

You could have run Routing Service without -appName. Then the name would be the one provided with -cfgName (“example”). You could also have used -identifyExecution to generate the name based on the host and application ID. In this case, you would have used this automatic name in the shell.
Examine the file <path to examples>/routing_service/shapes/time_filter_qos.xml on the Routing Service machine. It contains an XML snippet that defines a QoS value for an auto topic route’s DataReader. Execute the following command in the shell:
update MyRoutingService RemoteConfigExample::Session::Shapes \ <path to examples>/routing_service/shapes/time_filter_qos.xml
Notice that the receiving application only gets shapes every 2 seconds. The AutoTopicRoute has been configured to read (and forward) samples with a minimum separation of 2 seconds.

Routing Service can be configured remotely using files located on the remote machine or the shell machine. In the next step you will edit the configuration files on both machines. Then you will see how to specify which of the two configuration files you want to use.

Note

If you are running the shell and Routing Service on the same machine, skip steps 9 and 10.
Edit the XML configuration files on both machines:
- In <path to examples>/routing_service/shapes/time_filter_qos.xml on the service machine, change the minimum separation to 0 seconds.
- In <path to examples>/routing_service/shapes/time_filter_qos.xml on the shell machine, change the minimum separation to 5 seconds.
Run the following commands in the shell:
- Enter the following command. Notice the use of remote at the end—this means you want to use the XML file on the service machine (the remote machine, which is the default if nothing is specified).
  update MyRoutingService RemoteConfigExample::Session::Shapes \ <path to examples>/routing_service/shapes/time_filter_qos.xml remote
  Note
  
  The path to the XML file in this example is relative to the working directory from which you run Routing Service.
  
  Since no time filter applies, the shapes are received as they are published.
- Enter the following command. This time use local at the end—this means you want to use the XML file on the shell machine (the local machine).
  update MyRoutingService RemoteConfigExample::Session::Shapes \ <path to examples>/routing_service/shapes/time_filter_qos.xml local
  Note
  
  The path to the XML file in this example is relative to the working directory from which you run the Routing Service shell.
  
  You will see that now the shapes are only received every 5 seconds.
- Enter the following command. Once again, we use remote at the end to switch back to the XML file on the remote machine.
  update MyRoutingService RemoteConfigExample::Session::Shapes \ <path to examples>/routing_service/shapes/time_filter_qos.xml remote
  Shapes are once again received as they are published
Disable the AutoTopicRoute again by entering:
disable MyRoutingService RemoteConfigExample::Session::Shapes
The shapes are no longer received on Domain 1.

Note

At this point, you could still update the AutoTopicRoute’s configuration. You could also change immutable QoS values, since the DataWriter and DataReader haven’t been created yet. These changes would take effect the next time you called enable.
Run these commands in the shell and see what happens after each one:
enable MyRoutingService RemoteConfigExample::Session::SquaresToCircles disable MyRoutingService RemoteConfigExample::Session::SquaresToCircles enable MyRoutingService RemoteConfigExample::Session::SquaresToTriangles
These commands change the output topic that is published after receiving the input Square topic. As you can see, you can use the shell to switch TopicRoutes after Routing Service has been started.
Perform a remote shutdown of the service. Run the following command:
shutdown MyRoutingService
You should receive a reply indicating that the shutdown sequence has been initiated. Verify in the terminal in which Routing Service was running that the process is exiting or has already exited.
Stop the shell by running this command in the shell:
exit

11.8. Example: Monitoring¶

You can publish status information with Routing Service. The monitoring configuration is quite flexible and allows you to select the entities that you want to monitor and how often they should publish their status.

Start Shapes Demo. We’ll call this the Publishing Demo. It uses domain ID 0.
In the Publishing Demo, publish two Squares, two Circles and two Triangles.
Start a second copy of Shapes Demo. We’ll call this the Subscribing Demo. Then:
- Open its Configuration dialog (under Controls).
- Press Stop.
- Change the domain ID to 1.
- Press Start.
In the Subscribing Demo, subscribe to Squares, Circles and Triangles.

At this point you will not see any shapes moving in the Subscribing Demo. It isn’t receiving shapes from the Publishing Demo because they use different domain IDs.
On a different or the same machine, start the Routing Service remote shell:
cd <NDDSHOME> bin/rtirssh -domainId 0
Note

We use domain 0 in the shell because Routing Service is configured in administration.xml to receive remote commands on that domain. You could have started Routing Service with the -remoteAdministrationDomainId command-line option and then used domain X for the shell.

Start Routing Service by entering the following in a command shell:

cd <NDDSHOME>
bin/rtiroutingservice
-cfgFile <path to examples>/routing_service/shapes/monitoring.xml \
-cfgName example -appName MyRoutingService
This configuration file routes Squares and Circles using two different TopicRoutes.

Now you can subscribe to the monitoring topics (see Section 6). You can do it in your own application, or by using RTI Admin Console or rtiddsspy. Enter the following in a terminal:
cd <NDDSHOME> bin/rtiddsspy -domainId 2 –printSample
Note

We use domain 2 because Routing Service is configured in monitoring.xml to publish status information on that domain. You could have started Routing Service with the -remoteMonitoringDomainId X command-line option and then used domain X for rtiddsspy.
Depending on the publication period of the entity in the XML file we used, you will receive status samples at different rates. In the output from rtiddsspy, check the statistics about the two topic routes we are using.

We will focus on the input samples per second. The number of samples per second in our case is 32. That value depends on the publication rate of Shapes Demo configurable with the option -pubInterval <milliseconds between writes>.
Create two additional Square publishers in the Publishing Demo (domain 0).
Check rtiddsspy again for new status information.

In the TopicRoute for Squares, we are receiving double the amount of data.
Look at the status of the DataReader in the output from rtiddsspy.

It contains an aggregation of the two contained TopicRoutes, giving us a mean of nearly 48 samples per second.
We can update the monitoring configuration at run time using the remote administration feature. In the configuration file, we enabled remote administration on domain 0.

On a different or the same machine, start the Routing Service remote shell:
```
cd <NDDSHOME>
bin/rtirssh -domainId 0
```

We are receiving the status of the TopicRoute Circles every five seconds. To receive it more often, use the following command:

update MyRoutingService DomainRoute::Session::Circles \
        topic_route.entity_monitoring.status_publication_period.sec=2

In some cases, you might want to know only about one specific TopicRoute. If you only want to know about the topic route Circles but not Squares, you can disable monitoring for Squares:
update MyRoutingService DomainRoute::Session::Squares \ topic_route.entity_monitoring.enabled=false

To enable it again, enter:

update MyRoutingService DomainRoute::Session::Squares \
    topic_route.entity_monitoring.enabled=true

If you are no longer interested in monitoring this service, you can completely disable it with the following command:
update MyRoutingService routing_service.monitoring.enabled=false
Now you won’t receive any more status samples.

You can enable it again any time by entering:

update MyRoutingService routing_service.monitoring.enabled=true

Stop rtiddsspy by pressing Ctrl-c.
Stop the shell:
exit
Stop Routing Service by pressing Ctrl-c.

11.9. Example: Using the TCP Transport¶

This example shows how to use Routing Service to bridge data between different LANs over TCP. Routing Service will act as the gateway in a LAN with which other Connext DDS applications can communicate to send or receive data. Section 10 has more information about scenarios and detailed configuration parameters.

You will run two copies of Routing Service. One copy will run on a machine that is behind a firewall/network router with a public IP (First Peer); the other will run on a machine in another LAN (Second Peer).

On the First Peer (behind a firewall/router with a public IP):
1. In the First Peer’s network, configure the firewall to forward the TCP ports used by Routing Service.
  
  In this example, we will use port 7400. You do not need to configure your firewall for every single Connext DDS application in your LAN; doing it just once for Routing Service will allow other applications to communicate through the firewall.
2. Include the Second Peer’s public IP address and port in the NDDS_DISCOVERY_PEERS environment variable.
  
  For example, on a UNIX-based system:
  export NDDS_DISCOVERY_PEERS=tcpv4_wan://<server’s public IP address>:<port>
  On a Windows system:
  set NDDS_DISCOVERY_PEERS=tcpv4_wan://<server’s public IP address>:<port>
  When you configure NDDS_DISCOVERY_PEERS, make sure to use a transport class prefix (tcpv4_wan, udpv4, shmem) for each entry. See discovery peer configuration for details.
3. Set the public IP address and port in the configuration file:
  - Open the file <path to examples>/routing_service/shapes/tcp_transport.xml.
  - The file contains several configurations. Find the configuration with name “TCP_1”. Then find the “public_address” property (<name>dds.transport.TCPv4.tcp1.public_address</name>) within that configuration.
  - Set the local public IP address and port. For example, to set the address to 10.10.1.150 and port 7400:
    
    <element> <name>dds.transport.TCPv4.tcp1.public_address</name> <value>10.10.1.150:7400</value> </element>
  - Save and close the file.
4. Start Routing Service by entering the following in a command shell:
  cd <NDDSHOME> bin/rtiroutingservice -cfgFile <path to examples>/routing_service/shapes/tcp_transport.xml \ -cfgName TCP_1
5. On any computer in this LAN, start Shapes Demo and publish some shapes on domain 0.
On the Second Peer (a machine in any other LAN):
1. Include the First Peer’s public IP address and port in the NDDS_DISCOVERY_PEERS environment variable the same way you did before.
2. Set the public IP address and port in the configuration file:
  - Open the file <path to examples>/routing_service/shapes/tcp_transport.xml.
  - The file contains several configurations. Find the configuration with name “TCP_2”. Then find the “public_address” property (<name>dds.transport.TCPv4.tcp1.public_address</name>) within that configuration.
  - Set the local public IP address and port. For example, to set the address to 10.10.1.10 and port 7400:
    
    <element> <name>dds.transport.TCPv4.tcp1.public_address</name> <value>10.10.1.10:7400</value> </element>
  - Save and close the file.
3. Start Routing Service by entering the following in a command shell:
  cd <NDDSHOME> bin/rtiroutingservice -cfgFile <path to examples>/routing_service/shapes/tcp_transport.xml \ -cfgName TCP_2
4. On any computer in this LAN, start Shapes Demo and create subscribers on domain 2. Do not use an already running instance of Shapes Demo—you need a new one that uses a different domain ID. You should receive what is being published in the server’s LAN.
Notes:
- Running Shapes Demo on a Different Computer
  
  If the computer running Shapes Demo is different than the computer running the client Routing Service, add the address of the client (IP address or host name) to the Shapes Demo discovery peers before starting Shapes Demo. To do so, set the NDDS_DISCOVERY_PEERS environment variable.
- Using Two Computers in the Same LAN
  
  If both machines are in the same LAN, run both Routing Service with the configuration file tcp_transport_lan.xml and use tcpv4_lan:// as the peer prefix in the environment variable NDDS_DISCOVERY_PEERS. At least one of the peer descriptors must contain the port number.
  
  For example, suppose the first peer is 192.168.1.3, the second peer is 192.168.1.4, and you want to use port 7400. On the first peer set NDDS_DISCOVERY_PEERS to tcpv4_lan:// 192.168.1.4:7400 and on the second peer set it to tcpv4_lan://192.168.1.3:7400. You don’t need to specify an IP address in the configuration file.
- Running the Example on One Computer
  
  To run the example on the same machine, open the file <path to examples>/routing_service/ shapes/tcp_transport_lan.xml and change the property dds.transport.TCPv4.tcp1.server_bind_port within TCP_1 to 7401. Run both Routing Service with the modified tcp_transport_lan.xml configuration file and use tcpv4_lan:// as the peer prefix in the environment variable NDDS_DISCOVERY_PEERS. You will also need to specify port 7401 in the tcpv4_lan peer in the NDDS_DISCOVERY_PEERS environment variable of the Routing Service in the Second Peer to reflect this port change in the configuration file.
- Using a Secure Connection over WAN
  
  To run the example using a secure connection between the two Routing Service instances, use the configuration file tcp_transport_tls.xml. You will also need to set the peer prefix to tlsv4_wan:// in the NDDS_DISCOVERY_PEERS environment variable. The tcp_transport_tls.xml file is based on tcp_transport.xml and uses a WAN configuration to establish communication. Because TLS is enabled, you must ensure that the RTI TLS Support and OpenSSL libraries are present in your library path before starting the applications.
  
  Note
  
  To run this example, you need the RTI TCP Transport, which is shipped with RTI Connext DDS. Additionally, you will need to install the optional packages RTI TLS support and OpenSSL.
- Using a Secure Connection over LAN
  
  Similar to the previous point, but instead you will use the file tcp_transport_tls_lan.xml and prefix tlsv4_lan://.

11.10. Example: Using a File Adapter¶

The previous examples showed how to use Routing Service with Connext DDS. In this one you will learn how to use RTI Routing Service Adapter SDK to create an adapter that writes and reads data from files. Routing Service allows you to bridge data from different data domains with a pluggable adapter interface.

To learn how to implement your own adapter, you can follow this example and the next examples and inspect the code that is distributed with these adapters. The file adapter can read data from files with a specific format and provide it to Routing Service, or receive data from Routing Service and write it into files.

In this example, we will first write topic data (a colored square and circle) into a file and then use that file to write it back into Connext DDS, allowing us to modify the data with a text editor.

Compile the Adapter in adapters/file/src:
- Set NDDSHOME to point to your RTI Connext DDS installation.
- On UNIX-based systems, enter:
```
cd <path to examples>/routing_service/adapters/file/make
gmake -f Makefile.<architecture>
```
  The adapter shared library, libfileadapter.so, will be copied to <path to examples>/routing_service/adapters/file.
- On Windows systems:
  - Open the Visual Studio solution under <path to examples>/routing_service/adapters/file/windows. For example, if you are using Visual Studio 2013, open fileadapter-vs2013.sln.
  - Build the solution. The adapter shared library, fileadapter.dll, will be copied to <path to examples>/routing_service/adapters/file.
From Connext DDS to files:
1. Run Shapes Demo and Routing Service as in the previous examples:
  - Start Shapes Demo on domain 0 (the default domain).
  - Start Routing Service by entering the following in a command shell:
    
    cd <NDDSHOME> bin/rtiroutingservice -cfgFile <path to examples>/routing_service/shapes/file_bridge.xml \ -cfgName dds_to_file
2. In Shapes Demo, publish some Squares.
3. Wait a few seconds and then stop Routing Service by pressing Ctrl-c.
4. A file called MySquare.txt should have been created in the current directory. Open it with a text editor of your choice. It should contain several lines, each consisting of a list of <field>=<value> elements. Each line represents a sample (Square) published by Shapes Demo and written by Routing Service and the file adapter.
  
  On UNIX-based systems, you can see how new samples are appended to the file by running the following command while Routing Service runs:
  tail - f MySquare.txt
From a file to Connext DDS:
1. In Shapes Demo, delete the Square publisher and create a Square subscriber.
2. Start Routing Service by entering the following in a command shell:
```
cd <NDDSHOME>
bin/rtiroutingservice
     -cfgFile <path to examples>/routing_service/shapes/file_bridge.xml \
     -cfgName file_to_dds
```
  You should see squares being received by Shapes Demo. These samples come from what we recorded before.
  
  You might have noticed that the rate at which the shape moves is much slower. This is the rate at which the file adapter is providing data to Routing Service. To change this rate, open file_bridge.xml and look for <route name=”square_file”> within <routing service name=”file_to_dds”>. In the <property>` tag, change the property ReadPeriod from 1000 (milliseconds) to 100.
3. Stop Routing Service and restart it as described in previous steps. The squares should be received and displayed about ten times faster.
4. Other properties that you can configure in the file adapter are: In the input, FileName, MaxSampleSize, Loop and SamplesPerRead; in the output, FileName.
5. You can also edit the text file and publish the new data. Open MySquare.txt and replace all the occurrences of “shapesize=30” with “shapesize=100”.
6. Stop Routing Service and restart it as described in previous steps. The squares will have the same position and color, but they will be bigger now.
Customize the File Adapter:

In the example, the file adapters use a specific format, which you already saw in the file MySquare.txt. Now try adapting the example to your own format.

The code that reads/writes from the file is in adapters/file/src/LineConversion.c.
1. Edit the function RTI_RoutingServiceFileAdapter_read_sample to implement how file data maps into a sample.
2. Edit the function RTI_RoutingServiceFileAdapter_write_sample to implement how a sample is written to a file.

11.11. Example: Using a Shapes Processor¶

This example shows how to implement a custom Processor plug-in, build it into a shared library and load it with Routing Service.

This example illustrates the realization of two common enterprise patterns: aggregation and splitting. There is a single plug-in implementation, ShapesProcessor that is a factory of two types of Processor, one for each pattern implementation:

ShapesAggregator: Processor implementation that performs the aggregation of two ShapeType objects into a single ShapeType object.
ShapesSplitter: Processor implementation that performs the separation of a single ShapeType object into two ShapeType objects.

In the example, these processors are instantiated as part of a TopicRoute, in which all its inputs and outputs represent instantiations of the Connext DDS Adapter StreamReader and StreamWriter, respectively.

You can find the full example in the RTI Community Examples Repository.