HOWTO Develop Java RTI Routing Service Adapters using Eclipse

RTI Routing Service allows users to build complex adapters to address protocol and data mediation/virtualization challenges, when targeting non-DDS domains (JMS, legacy black-box, Altova MapForce-generated data mediation plug-ins, etc). The purpose of this document is to describe how to set up the JVM and Eclipse, so that you can attach to the Routing Service runtime and place breakpoints/debug/step inside your adapters that are in development.

Note: This document assumes you have Eclipse installed and are familiar with its use. 
This document also assumes you know how to build DDS-based solutions in Eclipse, if not, take a look at How do I create an RTI Connext Java application in Eclipse? in our Knowledge Base.

Enabling the JVM debugger requires passing command line arguments to the JVM.  From the command line, you would use something similar to

java -cp "..." -Xdebug -Xrunjdwp:... ...

To add both of these elements (the classpath value, and the debug enablers) to the Routing Service's call when it starts the jvm, use the //routing_service/jvm element in the configuration file:

    <routing_service name="myFirstJavaAdapter">
        <jvm>
            <class_path>
                <element>./</element>
                <element>c:/Users/rip/workspace/MapForce/bin</element>
                <!-- <element>...</element> additional as needed -->
                <!-- below as appropriate for your environment -->
                <element>c:/RTI/RTI_Routing_Service_5.1.0/class</element>
            </class_path>
            <options>
                <element>-Xdebug</element>
                <element>-Xrunjdwp:transport=dt_socket,address=7390,server=n,suspend=y</element>
            </options>
        </jvm>
        ...
    </routing_service>

There are two ways to enable debugging within the JVM, as server and as client.  It is important to remember which one you've configured in the XML file, as the other side of the connection needs to be provided by the Eclipse debug perspective.  The above sets server=n, so Eclipse needs to provide the debug server/service.  With the above settings, the JVM will force Routing Service to halt and wait for the internal debug client to connect to the Eclipse provided server.

In Eclipse, in the "Debug Configurations" panel, find the "Remote Java Application" entry, select it, and click on the "New" icon (blank document with a small +). 

1. Set a memorable Name for the configuration,
2. Under the Connect pane,
1. choose the Project you are working in via the Browse...
2. Set the Connection Type to "Standard (Socket Listen)" [see note 1]
3. Set the Port to the 'address=xxxx' value from the config (in this case, 7390)
4. Optionally, check Allow termination of remote VM (suggested initially, later you can disable it)
3. Under the Source pane, Add... any specific .jar files (for example, nddsjava.jar, rtirsadapter.jar).  If you get "class not found errors, this is where you will correct for that by adding the necessary directories or jar files.
4. Under the Common pane, I use Save as Local file, check Display in favorites menu Debug, check Default encoding, Allocate console and Launch in background options.

With these settings, you will need to launch the Routing Service instance, such that it loads the XML file with the -Xdebug stuff shown above, and uses the correct configuration.  Routing Service will start its launch sequence, then break in a "waiting for server connection".  When you launch the Debug Configuration, they will connect and RS will complete its startup.

You can now set breakpoints in your adapter code, and catch the connection/session/StreamReader/StreamWriter events as they happen.

Note:  If you selected server=y in the XML configuration, choose "Standard (Socket Attach)" here.  You'll need to add the Host address (either an IP address, or host name, or 'localhost' also works) as well as set the Port to the address=xxxx value.