Home

User`s Manual - Community RTI Connext Users

1. 8 27 siojdopy 8 Chapter 8 8 3 3 4 8 28 M reb cr fh stems Se Ss es cease em os pcr rco Ya ER Simple File Adapter StreamReader rc oo ned ns Ss Sa deg a E E het Tec ERE Ri ph RE ERR TOME ET REED RUE REED ERR RE NERIS RR a ERE RE Pn aa Ee ERE p Simple File Adapter StreamWriter EX Emtec ian Se es Nas pass ae Gt ERROR ROMERO ee Nc oe Nea hears haifa as EE fuk ca Sa saa ea ae A nde RE RE S LOC pE Simple File Adapter Adapter P e RU Entry point to the adapter plugin f DllExport struct RTI RoutingServiceAdapterPlugin SimpleFileAdapter create const struct RTI RoutingServiceProperties properties RTI RoutingServiceEnvironment env return NULL 5 Compile the SimpleFileAdapter skeleton by executing gmake from the adapter directory gt gmake After compilation you will find the adapter library in opt adapters simplefile lib lt architecture gt The next few sections will show you how to complete the adapter implementation Initializing the Adapter Entry Point Function Every adapter plugin must implement a plugin constructor entry point to the dynamic library that will be used by RTI Routing Service to create a plugin in
2. sss eee nne 2 7 24 Routing Service ns een oai indian nien e deor DEDI E Er He EE Eo 2 8 2 2 Domin ROWE serseri e in erroe eder eee epar ia eniin gig EEE e Eua Rae Peg PER dg e FIR deck EE 2 12 2 43 Administrations eerte teie ette each etel deve areas E EATE 2 17 24 4 JMOTDIOTIDg iieri drerit eiit rre Pr divas re Ieri in ene PvE Ee 2 18 24 5 GOSSIOM aniio eain e e e E EE PE HERR UR EIFE E te ER Ere PERDE EEEE EE E aa e RETO 2 26 ZAG ROUES iter tte en corteo tee E quta ve e keen Pene edge pae RI NEN RE Ree Vy vo chere Red 2 30 24 7 Auto ROUES si nini nee RE ERE nessa ER EXER FERE RR Ee FER U RE REX EAS aaas 2 43 24 8 Adapters eterni rt eer ertet ee ia a eoa eran 2 51 2 5 Enabling and Disabling RTI Routing Service Entities esee 2 52 3 Running RTI Routing Service 9 1 Starting RTI R utitig DEVICE oni sient b e He E HERE Ra 3 1 3 2 Stopping RTI Routing Service nennen nnne 3 2 4 Transforming Data with RTI Routing Service 4 1 Transformation Usage and Configuration ssssssseseeeee eene enne 4 1 4 2 Transformations Distributed with RTI Routing Service sse 4 4 43 Creating New Transformations c cscccecssergereessseegnsrsssenssaseoseevestasesessexeasuserseseatuasesesessuvunsesenses 4 5 4 3 1 Transformation Plugin APIsi aei anei aaa aeiae EE REE 4 6 5 Administering RTI Routing Service from a Remote Location 5 1 Enabling Remote Administrationin eren 5 1 5 2 Remote Commands
3. cccccccccessscssscsscessscessecsseecsscesseecseseessceseecsascessecsesecsssessecsersesaecsseesnesesaeensees 5 2 PZ OAC TE 5 4 522 unload A Gees We ete MUNI III 5 4 PAG amen ST ere RET 5 4 52A cdisable uciean rhe EEEE ites tents Ghats ete ace ence ieee TT LEER 5 5 929 update roae nemen eL A c DEUM MD 5 5 520 pausecoestentenebreanstendabri ten eli tata hr ert tte He o aS Le UL 5 8 VIV ROSUING RR 5 8 5 3 Accessing RTI Routing Service from a DDS Application sss 5 8 6 Monitoring RTI Routing Service from a Remote Location 6 1 Enabling Remote Monitoring eee piene teret tk oreet theta iai Rede date dee EES 6 2 6 2 Monitoring Configuration Data nein i nobit detenta te reta tate patera tota ts 6 2 6 21 Configuration Data for the Routing Service sse 6 3 6 2 2 Configuration Data for a Domain Route ene 6 4 6 2 3 Configuration Data for a Session sss e eene 6 7 6 24 X Configuration Data for a Route sssssssssesee ee eee eee enne 6 8 6 25 Configuration Data for an Auto Topic Route sse 6 13 6 3 Monitoring Status sic sisse ee iecit m dle deti Fe ne vd de D ed err du eer ver na de 6 19 6 3 1 How the Statistics are Generated sese enne 6 19 6 8 2 Status Information for the Routing Service sess 6 21 6 3 3 Domain Route Status sss eee eeeee E nnns ee tht ntis i nth ss
4. The name of the plugin used by the second connection connection 2 UOIJD20 6jOoUJO3 D WO GuuojJIuO N 9 Chapter 6 Table 6 2 6 6 DomainRouteData Field Name Key Description The sequence of properties defined in the tag prop connection 1 generic property erty gt inside lt eonnecton 1S The sequence of properties defined in the tag lt prop connection_2 generic property erty gt inside lt connection_2 gt DDS domain ID of the first domain route participant cconnection_1 dds domain_id This domain ID is configured using the XML tag lt domain_id gt inside lt participant_1 gt DDS domain ID of the second domain route partici ant cconnection_2 dds domain_id P n This domain ID is configured using the XML tag lt domain_id gt inside lt participant_1 gt connection_1 dds participant_key Unique identifier for the first DDS participant connection_2 dds participant_key Unique identifier for the second DDS participant A domain route using DDS can be correlated with its corresponding DDS participants using the fields connection_1 dds participant_key and or connection_2 dds participant_key For example let s assume that we want to get the value of the PropertyQosPolicy associ ated with the first DomainParticipant of a domain route To do that we would subscribe to the participant DDS builtin topic and look for a sample where the key member
5. Allocation settings applied to buffers used for an asynchronous non blocking write These settings configure the initial number of buffers the maximum number of buffers and the buffers to be allocated when more buffers are needed Default J write buffer allocation initial count 4 J write buffer allocation max count 1000 J write buffer allocation incremental count 10 Note that for the write buffer pool the max count is not set to unlimited This is to avoid having a fast writer quickly exhaust all the available system memory in case of a tempo rary network slowdown When this write buffer pool reaches the maximum the low level send command of the transport will fail at that point RTI Data Distribution Service will take the appropriate action retry to send or drop it according to the application s QoS if the transport is used for reliable communication the data will still be sent eventually 7 2 Configuring the TCP Transport Table 7 1 TCP TLS Transport Properties over LAN or WAN NDDS Transport TCPvA Property t Property Name prefix with dds transport TCPv4 tcp1 Description control buffer allocation Allocation settings applied to buffers used to serialize and send control messages These settings configure the initial number of buffers the maximum number of buffers and the buffers to be allocated when more buffers are needed Default J control buffer allocation initia
6. Run gdb gdb SROUTINGSERVICEHOME bin i86Linux2 6gcc4 1 1 rtiroutingservice Insert breakpoints in the functions that you want to debug For example gdb b SimpleFileAdapter_create_connection Function SimpleFileAdapter_create_connection not defined Make breakpoint pending on future shared library load y or n y 1 The location of your configuration file may be different Replace the value with the right location 8 3 Creating New Adapters Breakpoint 1 SimpleFileAdapter create connection pending 5 Execute RTI Routing Service and debug your adapter gdb r cfgFile simple file adapter xml cfgName file to file 8 3 5 Java Adapter API This section does not intend to give complete information on the entire Java API but rather to describe the aspects of the Java API that are specific to the Java language For detailed information about the Java API please see the online HTML RTI Routing Service documentation The Java Adapter API defines the interfaces in Table 8 10 Table 8 10 Java Adapter API Interfaces Interface Description com rti routingservice adapter Adapter Required The Adapter interface defines methods to getthe adapter version create destroy connections com rti routingservice adapter Connection Required The Connection interface defines methods to create destroy Sessions create destroy StreamReaders create destroy StreamWriters update the Co
7. The topic name filter allow topic name filter Oorl Default allow all The registered type name filter allow registered type name filter Oorl Default allow all 2 50 2 4 XML Tags for Configuring RTI Routing Service Table 2 19 DDS Input and Output Tags for the auto topic route and auto route Tags Tags within auto topic route input and auto route dds input Tags within auto topic route output and auto route dds output Description Number of Tags Allowed deny topic name filter A topic name filter that should be denied excluded This is applied after the lt allow_topic_name_filter gt Default Not applied Oorl lt deny_registered_type_name_filter gt A registered type name filter that should be denied excluded This is applied after the lt allow_registered_type_name_filter gt Default Not applied Oor1 1 As defined by the POSIX fnmatch API 1003 2 1992 section B 6 2 4 8 Adapters Adapters are pluggable components that allow RTI Routing Service to consume and pro duce data for different data domains e g DDS JMS Socket etc By default RTI Rout ing Service is distributed with a built in DDS adapter Any other adapters must be registered within the adapter library tag To support new data domains 1 Implement the adapter plugin API in Java or C See Chapter 8 Ex
8. niter mairie rn eris e rho reina 8 14 83 23 C Adapter APIs tete eite re teens err d iter uera 8 15 8 8 5 My First C Adapter asesteeeteeoeiegtintreieeti drerit ta den 8 19 8 3 4 Debugging C Adapters tette tette tet tei a io Poe h roes 8 48 895 Java Adapter ADI eremi rerit rate ER bee Re tope ie tere eve eet tsp 8 51 8 3 6 My First Java Adaptet iu eerte dert itte dereud eie renes urba ee ERR re 8 53 837 Debugging Java Adapters erieihin eieiei di iio EErEE E narrans 8 74 839 Tesine an Adapter eoo da adi adn diee pena 8 79 vi Chapter 1 Welcome to RTI Routing Service Welcome to RTI Routing Service This component of RTI Data Distribution Service Profes sional Elite Edition is an out of the box solution for integrating disparate and geograph ically dispersed systems It scales DDS applications across domains LANs and WANS including firewall and NAT traversal RTI 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 RTI Routing Service to interface with non DDS systems using off the shelf or custom developed adapters including to third party JMS imple mentations and legacy code writt
9. 2 32 2 4 XML Tags for Configuring RTI Routing Service Table 2 10 Route Tags Number Tags within route Description of Tags Allowed When this tag is true the data samples read from the input stream are written into the output stream with the same timestamp that was associated with them when they were made available in the input publish with original domain 0or1 tmestamp gt This option may not be applicable in some adapter implementations in which the concept of timestamp is unsupported Default false Sets a data transformation to be applied for every lt transformation gt data sample see Data Transformation Section 0 or 1 2 4 6 5 Configures remote monitoring for the route See entity monitoring Monitoring Section 2 4 4 and Chapter 6 Monitor 0 or 1 ing RTI Routing Service from a Remote Location Table 2 11 lists the tags allowed within a topic route Table 2 11 Topic Route Tags Number Tags within topic route Description of Tags Allowed input Defines the topic route s input topic See Table 2 13 1 required Defines the topic route s output topic See lt output gt Table 2 13 1 required lt route_types gt Defines if the input domain will use types discov ered in the output domain and vice versa for the cre ation of DataWriters and DataReaders in the topic route See Discovering Types Section 2 4 6 3 Default false
10. Enabling Remote Administration By default remote administration is disabled in RTI Routing Service for security reasons To enable remote administration you can use the lt administration gt tag see Section 2 4 3 or the remoteAdministrationDomainId ID command line parameter 5 1 UOHDISIUIWUpY ejowey G Chapter 5 which enables remote administration and sets the domain ID for remote communica tion For more information about the command line options see Section 3 1 in the Get ting Started Guide When remote administration is enabled RTI Routing Service will create a DomainPartici pant Publisher Subscriber DataWriter and DataReader in the designated domain The QoS values for these entities are described in Section 2 4 3 5 2 Remote Commands This section describes the remote commands using the shell interface Section 5 3 explains how to use remote administration from a DDS application The remote commands described later in this section are I load target routing service cfg name xml url remote local I unload target routing service I enable target routing service entity name 1 disable target routing service entity name L update target routing service entity name lt xml_url gt assignment expr2 remote local pause target routing service lt entity_name gt 1 resume target routing service entity name The parameters ar
11. domain id Sets the domain ID associated with the participant 1 required registered type participant qos Registers a type name and associates it with a type code When you define a type in the configuration file with the types tag you have 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 an RTI Data Distribution Service QoS profile file see Chapter 15 in the RTI Data Distribution Service User s Manual If not specified the default is used You can use a participant qos tag inside a qos library qos profile previously defined in your configuration file by referring to it like this participant qos base name MyLibrary MyProfile gt To use that profile but override just some values participant qos base_name MyLibrary MyProfile gt discovery initial peers lt element gt udpv4 192 168 1 12 lt element gt lt element gt shmem lt element gt lt initial_peers gt lt discovery gt lt participant_qos gt This applies to all QoS tags publisher qos lt subscriber_qos gt in sessions lt datareader_qos gt lt datawriter_qos gt in topic routes and auto topic routes 0 or more Oorl 2 4 XML Tags for Configuring RTI Routing Service 2 4 3 Administration You can create an RTI Data Di
12. 3 In opt adapters simplefile create a file called makefile with the following con tent EE E E E E E E E AE E AE TE AE E AE E TE TEE E E EHE HERE TE HEHEREEHEHEREEHEERE EHE ERE HE IEEE HERE ERE HE E EE HE E EE RE ERE E B EG E Makefile to build libsimplefileadapter so EE E E E E E E E E AE E AE AE AE E E HERE EHE E E TEE HERE E HEHERE E HERE EHE E HERE EHE ERE HE HE ERE HE E EE HE E EE RE EE E B EB E ARCH i86Linux2 6gcc4 1 1 Cc cc gcc c ld gcc ifeq DEBUG 1 c cc flags m32 g else c cc flags m32 endif c ld flags m32 static libgcc syslibs 1dl lnsl lm lpthread DEFINES_ARCH_SPECIFIC DRTI_UNIX DRTI_LINUX DEFINES DEFINES ARCH SPECIFIC INCLUDES I I NDDSHOME include I NDDSHOME include ndds I ROUTINGSERVICEHOME include LIBS LS NDDSHOME 1ib ARCH L ROUTINGSERVICEHOME bin ARCH lnddsc lnddscore lrtirsinfrastructure syslibs extralibs COMMONSOURCES SimpleFileAdapter c SHAREDLIB lib ARCH libsimplefileadapter so DIRECTORIES lib dir lib ARCH dir objs dir objs ARCH dir COMMONOBJS COMMONSOURCES c 0bjs ARCH 0 ARCH DIRECTORIES COMMONOBJS SHAREDLIB S SHAREDLIB COMMONOBJS c cc c 1d flags shared o S LIBS objs S ARCH 0 c 8 3 Creating New Adapters c cc c ce flags o S DEFINES INCLUDES c lt
13. In the next sections we will explain how to use and configure the TCP transport with RTI Routing Service 7 1 SOMJON DelY pPIM BulsiOADI Z Chapter 7 Figure 7 1 WAN Communication Using TCP Transport DDS application 1 DDS application 2 Transport Transport Transport Transport Firewall NAT Firewall NAT Router 7 7 e 7g Router TCP traffic only 7 1 TCP Communication Scenarios The TCP transport distributed with RTI Routing Service can be used to address multiple communication scenarios that go from simple communication within a single LAN to complex communication scenarios across LANs where NATs and firewalls may be involved 7 1 1 Communication Within a Single LAN TCP transport can be used as an alternative to UDPv4 to communicate DDS applica tions running inside the same LAN Figure 7 2 shows how to configure the TCP transport in this scenario 7 2 7 1 TCP Communication Scenarios Figure 7 2 7 1 2 E ES p TEE ON C oe STA eb E parent classid transport mode and server bind port are transport properties config ured using the PropertyQosPolicy of the participant Initial Peers represents the peers to which the participant will be announced to Usu ally these peers are configured using the DiscoveryQosPolicy of the participant or the environment variable NDDS DISCOVERY PEERS For information on the format of initial peers see Section 7 2 1 Com
14. lt property gt lt value gt lt element gt lt name gt username lt name gt lt value gt myusername lt value gt lt element gt lt value gt lt property gt Oor1 In an XML file Sessions are associated with the tag session see Section 2 4 5 See Table 8 5 Session Operations on page 8 9 4 StreamReader A StreamReader provides a way to read samples of a specific type from a data domain In the built in DDS adapter a StreamReader is mapped to a DataReader In an XML file StreamReaders are associated with the tag input within route or auto route see Section 2 4 6 See Table 8 6 StreamReader Operations on page 8 10 5 StreamWriter A StreamWriter provides a way to write samples of a specific type in a data domain In the built in DDS adapter a StreamWriter is mapped to a DataWriter In an XML file StreamWriters are associated with the tag output within route or auto route see Section 2 4 6 See Table 8 7 StreamWriter Operations on page 8 10 Figure 8 1 describes the adapter class model 8 5 slojdopy 9 Chapter 8 Figure 8 1 Adapter Class Model 8 6 8 2 Adapter API And Entity Model Table 8 3 Adapter Operations Operation Description create connection Creates a new connection Connection objects are created when the domain routes that contain them are enabled Implementation of this API is requi
15. 4 project for creating a Win32 application console application DLL or static library Name SimpleFileAdapter Location C adapters z Browse Solution Name SimpleFileAdapter Create directory for solution Cancel 1 Replace architecture with your existing architecture For example i86Win32VS2005 i86Linux2 6gcc4 1 1 etc 8 20 8 3 Creating New Adapters 3 Select Application Settings and choose DLL Click Finish Win32 Application Wizard SimpleFileAdapter Application Settings s 2 g e a4 rt symbols 4 Create a new file called SimpleFileAdapter c with the following content This file will contain the adapter implementation RR RR RRR RRR ER KERR EKER KER e ke kc e ERR ERE ke e ke ko KERR RRR ke e ke ho KER ERK ERK ERK e ek e i Simple File Adapter RR RR RRR ke ke koc ke ke ko ke kk e khoe ke e e kc e ke ko e khe e ke e ke ko ke ke hc ke ke e ke e kh ke ke ke ke he ek ke ke e ke e e kk include lt stdio h gt include lt string h gt ifdef RTI_WIN32 include lt process h gt else include lt pthread h gt endif include ndds ndds_c h include routingservice routingservice_adapter h 8 2 Chapter 8 8 22 ifdef RTI WIN32 Disable strtok fopen warnings pragma warning disable 4996 define DllExport __declspec dllexport else define DllExport endif pe Simple File Adapter Connection 5 5 5
16. Here is how we create those subdirectories automatically dir echo Checking directory Gif d then echo Making directory mkdir p fis clean rm rf objs rm rf lib The above makefile assumes that the architecture is i86Linux2 6gcc4 1 1 You can specify a different architecture by changing the value of the variable ARCH 4 Create a new file called SimpleFileAdapter c with the following content This file will contain the adapter implementation fCRCKCKCKCkCk kc kokckokck c kckokckckc ke ko ERE KERR RRR ERK K kc kokokck ck kokckckckckckckckck kckckckck ck ckckckckck kc k ck k ko kJ Simple File Adapter fCRCECKCKCkck kc kokckck kc kckokokckc kc kokokckckckckokckckckckckckck kc kokokck ck kokckckckckckckckck kckckckockckckckckckck kck ck k ko kJ include lt stdio h gt include lt string h gt ifdef RTI_WIN32 include lt process h gt else include lt pthread h gt endif include ndds ndds_c h include routingservice routingservice_adapter h ifdef RTI_WIN32 Disable strtok fopen warnings pragma warning disable 4996 define DI1Export __declspec dllexport telse define DllExport endif J Simple File Adapter Connection
17. Oor1 2 33 eoiues Buynoy I13 BuunByuod Z Chapter 2 Table 2 11 Topic Route Tags Tags within topic route Description Number of Tags Allowed publish with original info Writes the data sample as if they came from its origi nal writer Setting this option to true allows having redundant routing services and prevents the appli cations from receiving duplicate samples Default false O0or1 publish with original timestamp When this tag is set to true the data samples are written with their original source timestamp Default false Oorl lt propagate_dispose gt Indicates whether or not disposed samples NOT_ALIVE_DISPOSE must be propagated by the topic route This action maybe be overwritten by the execution of a transformation Default true Oorl lt propagate_unregister gt Indicates whether or not NOT_ALIVE_NO_WRITERS samples must be prop agated by the topic route by using the unregister instance operation This action maybe be overwritten by the execution of a transformation Default true Oorl lt transformation gt Sets a data transformation to be applied for every data sample see Data Transformation Section 2 4 6 5 Oorl lt entity_monitoring gt Configures remote monitoring for the topic route See Monitoring Section 2 4 4 and Chapter 6 Moni toring RTI Routing Service from a Remote Location
18. 12 With RTI Routing Service you can build modular systems out of existing sys tems 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 l RTI Routing Service provides secure deployment across multiple sites You can partition networks and protect them with firewalls and NATS and precisely con trol the flow of data between the network segments I It allows you to manage the evolution of your data model at the subsystem level You can use RTI Routing Service to transform data on the fly changing topic names type definitions QoS etc seamlessly bridging different generations of DDS topic definitions L RTI Routing Service provides features for development integration and test ing Multiple sites can each locally test and integrate their core application expose selected topics of data and accept data from remote sites to test integra tion connectivity topic compatibility and specific use cases 1 It connects remotely to live deployed systems so you can perform live data analytics fault condition analysis and data verification 11 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
19. RTI RoutingServiceEnvironment env const char readPeriodStr unsigned int readPeriod char file struct SimpleFileAdapterConnection self struct SimpleFileAdapterConnection connection struct SimpleFileAdapterStreamReader reader NULL struct DDS DynamicDataProperty t dynamicDataProps DDS DynamicDataProperty t INITIALIZER int error 0 ifndef RTI WIN32 pthread attr t threadAttr dendif int verbosity verbosity RTI RoutingServiceEnvironment get verbosity env if verbosity RTI ROUTING SERVICE VERBOSITY DEBUG printf CALL SimpleFileAdapterConnection create stream reader Wn Create StreamReader reader calloc 1 sizeof struct SimpleFileAdapterStreamReader if reader NULL RTI RoutingServiceEnvironment set error env Memory allocation error return NULL reader gt sample 0 DDS_DynamicData_new struct DDS_TypeCode stream_info gt type_info type_representation amp dynamicDataProps 8 38 8 3 Creating New Adapters if reader gt sample 0 NULL RTI_RoutingServiceEnvironment_set_error env Failure creating dynamic data sample free reader return NULL Open input file file malloc strlen self gt directory strlen strlen stream_info gt stream_name strlen txt 1 if file NULL RTI_RoutingServiceEnvironment_set_error env Memory allocation error DDS_DynamicData_delete
20. StreamWriter Read Write C s The figure to the right describes how the session thread reads sam ples from a StreamReader 8 13 siojdopy 8 Chapter 8 8 3 8 3 1 Creating New Adapters RTI Routing Service provides an adapter SDK in C and Java to support the creation of new adapter plugins The RTI Routing Service Adapter SDK is distributed as a separate component that must be installed over an existing installation of RTI Routing Service For more information see the RTI Routing Service Adapter SDK Installation Guide Adapter SDK Components After installing RTI Routing Service Adapter SDK the components in Table 8 8 will be available in the RTI Routing Service root folder Table 8 8 Adapter SDK Components 8 14 Component Description Release Notes and Adapter SDK release notes and installation guide Installation Guide RTI Routing Service home gt doc pdf Adapter SDK Pro gramming Guide Chapter 8 in the RTI Routing Service User s Manual this chapter C and Java API specification in HTML and PDF format The C API specification describes the Adapter and Transformation API see Chapter 4 The Java API specification describes the Adapter API RTI Routing Service home gt ReadMe html RTI Routing Service home gt doc pdf API Specification The SDK provides three buildable adapter implementations two in C file and socket and one in Java JMS For instruct
21. The route name is configured using the name attribute in the lt topic_route gt tag input_samples_per_s Statistic variable that provides information about the input samples per second in the route Input samples refer to the samples that are taken by the session from the route s StreamReader input_bytes_per_s Statistic variable that provides information about the input bytes per second in the route Input bytes refer to the bytes that are taken by the session from the route s StreamReader These bytes only refer to the serialized samples The protocol headers UDP RTPS are not included output_samples_per_ s Statistic variable that provides information about the output samples per second in the routes Output samples refer to the samples that are published out by the ses sion thread using the route s StreamWriters output bytes per s Statistic variable that provides information about the output bytes per second in routes Output bytes refer to the bytes that are published out by the session thread using the route s StreamWriter The variable only considers the bytes of the serialized samples Protocol headers UDP RTPS are not included latency s Statistic variable that provides information about the latency in seconds in the routes The latency in a route refers to the time elapsed between the sample read and write This is a good metric to monitor the health and perfor m
22. ai For DDS adapter Immutable QoS policies in For DDS adapter Mutable QoS policies in d lt publisher_qos gt and lt subscriber_qos gt Session publisher qos and subscriber qos E entity monitoring enity monitoring enabled Hy m MOT 8 i A ae blicati iod statistics sampling period Se arene cse s CC eanen OHIO entity monitoring historical statistics denen z Immutable properties in property adapter spe Route Mutable properties in property adapter specific dj e properties in lt property adaptersp Mutable QoS policies in lt datawriter_qos gt and lt datareader_qos gt Immutable QoS policies in lt datawriter_qos gt and lt route_types gt lt datareader_qos gt Topi lt propagate_dispose gt creation mode D propagate unregister content filter expression publish with original info entity monitoring content filter parameter statistics sampling period enity monitoring enabled entity monitoring historical statistics entity monitoring status publication period ae eps I tabl ties in lt ty gt adapter spe d Mutable properties in property adapter specific did dui a M Glee 5 6 5 2 Remote Commands Table 5 1 Changeable Parameters Entit Mutable Immutable i y changeable any time only changeable when entity is disabled Immutable QoS policies in lt datawriter_qos g
23. expression inside topic route input or lt route gt dds input input adapter data generic property Not applicable for DDS input The properties used to configure this route s StreamReader specified with the tag property inside route input output adapter data generic property Not applicable for DDS output The properties used to configure this route s StreamWriter specified with the tag property inside route output propagate dispose propagate unregister DDS auto topic routes only Indicates if the topic route propa gates NOT ALIVE DISPOSE samples The propagation of NOT ALIVE DISPOSE samples is configured using the tag propagate dispose in topic route DDS auto topic routes only Indicates if the topic routes propa gate NOT ALIVE NO WRITERS samples The propagation of NOT ALIVE NO WRITERS samples is con figured using the tag propagate unregister in auto topic route publish with original info DDS auto topic routes only Indicates if the topic routes publish the samples with original writer information Setting this option to true allows redundant topic routes and prevents applications from receiving duplicate samples The publication with original writer info is configured using the tag publish with original info inside auto topic route publish with original timestamp Indicates if the routes are configured to publ
24. if feof self gt fHandle self gt listener on_data_available 8 36 8 3 Creating New Adapters self self listener listener data return NULL Deletes a StreamReader void SimpleFileAdapterConnection delete stream reader RTI RoutingServiceConnection connection RTI RoutingServiceStreamReader stream reader RTI RoutingServiceEnvironment env struct SimpleFileAdapterStreamReader reader struct SimpleFileAdapterStreamReader stream reader ifndef RTI WIN32 void value NULL dendif int verbosity verbosity RTI RoutingServiceEnvironment get verbosity env if verbosity RTI ROUTING SERVICE VERBOSITY DEBUG printf CALL SimpleFileAdapterConnection delete stream reader reader gt run 0 ifdef RTI_WIN32 WaitForSingleObject reader gt thread INFINITE else pthread_join reader gt thread amp value dendif if reader gt fHandle fclose reader fHandle if reader sample 0 DDS DynamicData delete reader sample 0 free reader 8 37 siojdopy 8 Chapter 8 Creates a StreamReader RTI RoutingServiceStreamReader SimpleFileAdapterConnection create stream reader RTI RoutingServiceConnection connection RTI RoutingServiceSession session const struct RTI RoutingServiceStreamInfo stream info const struct RTI RoutingServiceProperties properties const struct RTI RoutingServiceStreamReaderListener listener
25. 2 Connection A Connection provides access to a data domain such as a DDS domain or JMS provider network and is a factory for Sessions StreamReaders and StreamWriters In the built in DDS adapter a Connection is mapped to a DomainParticipant In an XML configuration file connections are associated with the tags lt connection_1 gt and lt connection_2 gt within a domain route see Section 2 4 2 See Table 8 4 Connection Operations on page 8 7 slojdopy 8 Chapter 8 Table 8 1 C Adapter Plugin Tags Tags within adapter plugin Description Number of Tags Allowed dll Required Shared library containing the implementation of the adapter plugin The dll tag may specify the exact name of the file for example lib libmyadapter so or a general name no file extension which will be completed as follows dll value dir myadapter Final Path UNIX based systems dir libmyadapter so Final Path Windows systems dir myadapter dll If the library specified with the dll tag cannot be opened because the library path is not in the Path environment variable on a Windows system or the LD LIBRARY PATH environment variables on a UNIX based system RTI Routing Service will look for the library in RTI Routing Service installation directory bin lt architecture gt lt create_function gt Required This tag must contain the name of the function used to create the a
26. RTI 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 RTI Data Dis tribution Service see Chapter 15 in the RTI Data Distribution Service User s Manual I NDDSHOME resource qos profiles 4 5x xm NDDS QOS PROFILES xml This file contains the RTI Data Distribution Service 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 environ ment variable are loaded automatically L working directory gt USER_QOS_PROFILES xml This file is loaded automatically if it exists The next locations are specific to RTI Routing Service L RTI Routing Service executable location gt resource xml RTI ROUTING SERVICE xml This file contains the default RTI 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 working directory USER ROUTING SERVICE xml This file is loaded automatically if it exists I File specified using the command line parameter cfgFile The command line option cfgFile see Table 3 1 on page 3 3 can be used to specify a configuration file I File specified using the remote command load The load command
27. There are a few things to take care of before you start developing the simple file adapter 1 Set the environment variable ROUTINGSERVICEHOME Set the environment variable ROUTINGSERVICEHOME to the RTI Routing Ser vice installation directory RTI Routing Service itself does not require that you set the environment variable It is used to build compile and run the example adapter On Windows Systems To use a Java adapter you must have the Visual Studio 2005 service pack 1 redistributable libraries You can obtain this package from Microsoft or RTI see the RTI Data Distribution Service Release Notes for details Make sure Java 1 5 or higher is available Ensure that appropriate javac jar and jdb for debugging executables are on your path They can be found in the bin directory of your JDK installation Make sure you add the directory of the Java Virtual Machine dynamic library to your environment variable LD LIBRARY PATH on UNIX based systems or Path on Windows systems For example 8 53 slojdopy 8 Chapter 8 8 3 6 2 8 54 setenv LD LIBRARY PATH S LD LIBRARY PATH local java jdk1 5 0 07 jre lib i386 client 5 On UNIX based systems Add RTI Routing Service home gt bin lt architec ture to the environment variable LD LIBRARY PATH Creating a Build Script for UNIX based Systems In this section you will create a shell script to compile the Java adapter 1 Create a directory that w
28. lt input gt lt output gt lt registered_type_name gt ShapeType lt registered_type_name gt lt topic_name gt Circle lt topic_name gt lt output gt lt topic_route gt lt session gt lt domain_route gt lt routing_service gt lt dds gt When an entity is created disabled it can be enabled remotely using the commands enable Section 5 2 3 and disable Section 5 2 4 A routing service can be created dis abled by setting the attribute enabled to false or by using the noAutoEnable com mand line option The command line parameter takes precedence over the XML attribute value 2 52 Chapter 3 Running RTI Routing Service 3 1 This chapter describes I Starting RTI Routing Service Section 3 1 1 Stopping RTI Routing Service Section 3 2 Starting RTI Routing Service RTI Routing Service runs as a separate application The script to run the executable is located in RTI Routing Service installation directory gt scripts There are a few things to take care of before you execute RTI Routing Service 1 For UNIX based systems RTI Routing Service requires the dynamic libraries in RTI Routing Service home bin architecture Make sure the path to those dynamic libraries is in your LD LIBRARY PATH environment variable 2 RTI Routing Service supports loading Java adapters If your configuration is set up to load a Java adapter follow these steps a On Windows Systems To use a Java adapter you mu
29. or inside route dds input or the tag stream name inside route input input registered type name Input registered name The input registered name is configured using the tag registered type name inside topic route input route dds input or route input output stream name Output stream name The output stream name is configured using the tag topic name inside topic route output or inside route dds output or the tag stream name inside route output output registered type name Output registered name The output registered name is configured using the tag registered type name inside topic route output route dds output or route output input creation mode Indicates when the StreamReader is created in the input The input creation mode is configured using the tag creation mode 6 2 Monitoring Configuration Data Table 6 4 RouteData Field Name Key Description output creation mode Indicates when the StreamWriter in created in the output The output creation mode is lt creation_mode gt configured using the tag input adapter_data Contains the configuration of the route s input that is specific to either the DDS adapter or a generic adapter When a generic input is defined lt route gt lt input gt then the union discriminator i
30. readPeriod notification hread start 8 3 Creating New Adapters Fy void close throws AdapterException try notificationThread terminate notificationThread join if fileReader null fileReader close catch InterruptedException e throw new AdapterException 0 error finishing notification thread catch IOException e throw new AdapterException 0 error closing fileName F public void read List Object sampleList List Object infoList throws AdapterException String line if verbosity equals debug System out println CALL getClass getName read H try sampleList clear infoList clear dynamicData clear all members if fileReader ready line fileReader readLine dynamicData set string value DynamicData MEMBER ID UNSPECIFIED line sampleList add dynamicData H catch IOException e throw new AdapterException 0 error reading from file fileName e catch Exception e 8 65 siojdopy 9 Chapter 8 8 66 throw new AdapterException 0 error reading e public void returnLoan List Object sampleList List Object infoList throws AdapterException if verbosity equals debug System out println CALL getClass getName returnLoan H E public void update Properties properties throws AdapterException pa
31. s elds in the SessionStatusSet data type name Field Name Key Description routing service name V The routing service name assigned with appName domain route name V The domain route name V The session name The domain route name is configured using the name attribute in the lt session gt tag input_samples_per_s Statistic variable that provides information about the input samples per second across routes Input samples refer to the samples that are taken by the session from the routes s StreamReaders input_bytes_per_s Statistic variable that provides information about the input bytes per second across routes Input bytes refer to the bytes that are taken by the sessions from the routes s StreamReaders These bytes only refer to the serialized samples The protocol headers UDP RTPS are not included 6 24 6 3 Monitoring Status Table 6 8 SessionStatusSet Field Name Key Description output samples per s Statistic variable that provides information about the output samples per second across routes Output samples refer to the samples that are published out by the ses sion thread using the route s StreamWriters output bytes per s Statistic variable that provides information about the output bytes per second across routes Output bytes refer to the bytes that are published out by the session thread using the route s StreamWriters The
32. 5 5 5 5 5 5 5 5 5 5 5 7 77 55 5 5 5 5 5 5 Simple File Adapter StreamReader 7 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 Simple File Adapter StreamWriter 7 5 5 5 5 5 5 5 5 5 5 5 5 5 7 5 5 5 5 5 5 5 5 s Simple File Adapter Adapter 7 5 5 5 5 5 5 5 5 5 5 5 5 5 Entry point to the adapter plugin DllExport struct RTI RoutingServiceAdapterPlugin SimpleFileAdapter create const struct RTI RoutingServiceProperties properties RTI RoutingServiceEnvironment env return NULL uA xy E B x wes W ir uA 8 3 Creating New Adapters 5 Add the new file to the project SimpleFileAdapter Sa simpleFiieadapter Microsoft Visual Studio ES File Edit View project Build Debug Tools Test Window Help igl E3 gg kd s Ga amp O O d ER P Debug gt Win32 B processeds JRT E LAS mE EE E REESE 5 Solution Explorer S SimpleFileAdapter c seis Global Scope ay Solution SimpleFileAdapter 1 proje S 8AAXX AA RGG G ARRARARRRARERRETETAERTETERRREREERAERTEREEARRRREETEAARE S C SimpleFileadapter Simple File Adapter Gi Header Files RRERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERERE RS Gi Resource Files E y Source Files SimpleFileAdapter c include lt stdio h
33. D WOI 6uuojJIuo N 9 Chapter 6 Table 6 6 RoutingServiceStatusSet Field Name Key Description Statistic variable that provides the physical memory utilization of physical memory kb the routing service process This variable is only supported on Windows and Linux systems Statistic variable that provides the virtual memory utilization of total memory kb the routing service process This variable is only supported on Windows and Linux systems 6 3 3 Domain Route Status The topic that publishes domain route status is called rti routing service monitoring domain route status set The domain route status aggregates the statistics of the routes contained in it the mean of the means in the routes the absolute maximum and minimum across routes the mean of the standard deviation and the total count The IDL definition of the data type is struct DomainRouteStatusSet string ENTITY NAME MAX LENGTH routing service name key string ENTITY NAME MAX LENGTH name key 1j 1j StatisticVariable input samples per s StatisticVariable input bytes per s StatisticVariable output samples per s StatisticVariable output bytes per s StatisticVariable latency s E Table 6 7 describes the fields in the DomainRouteStatusSet data type Table 6 7 DomainRouteStatusSet Field Name Key Description routing service name V The routing service name assigned with appNam
34. Description routing service name V The routing service name assigned using appName domain route name V The domain route name session name V The session name The auto route name which is configured using the name attribute in the topic route tag The configuration of the auto route input as contained in the tag input input or lt dds_input gt inside lt auto_route gt or lt auto_topic_route gt The configuration of the auto route output as contained in the tag output lt output gt or lt dds_output gt inside lt auto_route gt or lt auto_topic_route gt Index of the input connection or participant 1 or 2 The value of this field is used to determine whether the input of this auto route is the domain route s connection 1 participant 1 or the connection 2 participant 2 input allow_stream_name_ filter Topics that do not pass this filter in the input participant will not trigger the creation of routes This filter is configured using the tag lt allow_topic_name_filter gt inside lt auto_topic_route gt lt input gt or inside lt auto_route gt lt dds_input gt or the tag lt allow_stream_name_filter gt inside lt auto_route gt lt input gt 6 15 UOIJD20 6jOoUJO3 D WOI GuuojJIuO N 9 Chapter 6 Table 65 AutoRouteData Field Name Key Description input allow_registered_ type_name_filter Topic with types that do not pass this filter in the in
35. Linker Manifest Tool XML Document Generator Browse Information Build Events E Custom Build Step Additional Include Directories gore or more directories to add to the include path use semi colon delimited list if more than one pati m om e Add the following to Additional Include Directories NDDSHOME Ninclude NDDSHOME include ndds ROUTINGSERVICEHOME include e Select Configuration Properties Linker General add the following to Additional Library Directories NDDSHOME 1lib i86Win32VS2008 ROUTINGSERVICEHOME bin i86Win32VS2008 e Select Configuration Properties Linker Input add the following to Additional Dependencies rtirsinfrastructure lib nddsc lib nddscore lib netapi32 lib advapi32 lib user32 1ib WS2 32 1ib n the Configuration combo box select Debug 8 24 8 3 Creating New Adapters e Select Configuration Properties C C Preprocessor replace the con tents of Preprocessor Definitions with WIN32 WIN32 LEAN AND MEAN NDDS DLL VARIABLE RTI WIN32 DEBUG Inthe Configuration combo box select Release e Select Configuration Properties C C Preprocessor replace the con tents of Preprocessor Definitions with WIN32 WIN32 LEAN AND MEAN NDDS DLL VARIABLE RTI WIN32 NDEBUG e Click OK 7 In the Solution Configuration combo box select Release B SimpleFileAdapter Microsoft Visual Studio File Edit View Project Build Debug Tools Test Wind
36. Service ReleaseNotes pdf Describes system requirements and compatibility as well as any version specific changes and known issues User s Manual RTI Routing Service UsersManual pdf Describes how to con figure RTI Routing Service and use it remotely If the optional RTI Routing Service Adapter SDK is installed you will also have the fol lowing documents LI RII Routing Service Adapter SDK Installation Guide RTI_Routing_Service_AdapterSDK_InstallationGuide pdf Describes installa tion instructions for RTI Routing Service Adapter SDK M RTI Routing Service Adapter SDK Release Notes RII Routing Service AdapterSDK ReleaseNotes pdf Describes system requirements and compatibility as well as any version specific changes and known issues for RTI Routing Service Adapter SDK Chapter 2 Configuring RTI Routing Service This document describes how to configure RTI Routing Service To see installation instructions or to walk through some simple examples please see the Getting Started Guide When you start RTI 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 ser vice This chapter describes how to write a configuration file This chapter describes LJ Terms to Know Section 2 1 LI How to Load the XML Configuration Section 2 2 1 XML Syntax and Validation Section 2 3 LI XML Tags for Configuring RTI Routing Ser
37. When this property is set to 1 TCP segments are always sent as soon as possible which may result in poor network utilization Default 0 logging_verbosity_ bitmap Bitmap that specifies the verbosity of log messages from the transport Logging values 1 Oxffffffff do not change the current verbosity 0x00 silence 0x01 errors 0x02 warnings 0x04 local 0x08 remote 0x10 period 0x80 other used for control protocol tracing Default 1 Note the logging verbosity is a global property shared across multiple instances of the TCP transport If you create a new TCP Transport instance with logging verbosity bitmap different than 1 the change will affect all the other instances as well O O O O O C The default TCP transport verbosity is errors and warnings Note The option of 0x80 other is used only for tracing the internal control protocol Sinc the output is very verbose this feature is enabled only in the debug version of the TCP Transport library 0 libnddstransporttcpd so LIBNDDSTRANSPORTD LIB SOMJON Dely pPIM BulsiOADI Z Chapter 7 Table 7 1 TCP TLS Transport Properties over LAN or WAN NDDS Transport TCPvA Property t Property Name prefix with D dds transport TCPv4 Description tcp1 Maximum number of outstanding connection cookies allowed by the transport when act ing as server A connection cookie is a token provided by a server to a client
38. adapter plugin name simple_file gt class name routingservice adapter simplefile SimpleFileAd apter class name java adapter plugin adapter library types struct name TextLine gt member name value type string stringMaxLength 2048 gt struct types routing service name file to file lt jvm gt lt class_path gt lt element gt class simplefileadapter jar lt element gt lt class_path gt jvm domain route name domain_route gt connection 1 plugin name adapters simple file registered type name TextLine type name TextLine property value element lt name gt directory lt name gt lt value gt opt adapters simplefile input lt value gt lt element gt lt value gt lt property gt lt connection_1 gt 8 72 8 3 Creating New Adapters connection 2 plugin name adapters simple file registered type name TextLine type name TextLine property value element lt name gt directory lt name gt lt value gt opt adapters simplefile output lt value gt lt element gt lt value gt lt property gt lt connection_2 gt lt session name session gt lt route name route gt lt input connection 1 gt lt stream_name gt HelloWorld lt stream_name gt lt registered_type_name gt TextLine lt registered_type_name gt lt input gt lt output gt lt stream_name gt HelloWorld lt stream_name
39. are factories of StreamReaders A StreamReader provides a way to read data samples of a specific type from a data domain In the configuration file StreamReaders are associated with the tag lt input gt within lt route gt or lt auto_route gt see Section 2 4 6 The StreamReaders created by the SimpleFileAdapter connections read text files from the connection directory 8 3 Creating New Adapters The data samples provided to RTI Routing Service using the read operation are Dynam icData with the following IDL type struct TextLine string lt 1024 gt value Fi When a SimpleFileAdapter StreamReader is created the name of the file is the input stream name with a txt extension You can use the read_period property to control how often the StreamReader notifies RTI Routing Service about new lines For example lt route name route gt lt input connection 1 gt stream name HelloWorld stream name registered type name TextLine registered type name lt property gt lt value gt lt element gt name read period name lt value gt 1000 lt value gt lt element gt lt value gt lt property gt lt input gt lt route gt In the above example the input StreamReader will read lines from a file called Hel loWorld txt and provide one line per second to RTI Routing Service The next step is to implement the StreamReader functionality You will implement five new functions _ SimpleFileAdap
40. at which the StreamReader notifies RTI Routing Service of new lines is configurable using the read_period property For example lt route name route gt lt input connection 1 gt lt stream_name gt HelloWorld lt stream_name gt lt registered_type_name gt TextLine lt registered_type_name gt lt property gt lt value gt lt element gt lt name gt read_period lt name gt lt value gt 1000 lt value gt lt element gt lt value gt lt property gt lt input gt lt route gt In the previous example the input StreamReader will read the lines of a a file called HelloWorld txt and it will provide one line per second to RTI Routing Service The next step consist on the implementation of the StreamReader class There are three main methods LJ read This method will be called by RTI Routing Service after being notified that the are new lines available Although the signature of the method allows returning more than one sample line for the sake of simplicity the implementation only returns one line every time the method is called RTI Routing Service will not call the read operation until it is notified of the pres ence of new data see Section 8 2 3 To provide data notification the Stream Reader implementation creates a thread NotificationThread that wakes up after read_period and notifies RTI Routing Service of new data if the end of the file has not been reached yet 8 3 Creating New Adapters LJ re
41. const struct RTI RoutingServiceStreamInfo stream info const struct RTI RoutingServiceProperties properties RTI RoutingServiceEnvironment env const char printToStdoutStr char file struct SimpleFileAdapterConnection self struct SimpleFileAdapterConnection connection struct SimpleFileAdapterStreamWriter writer NULL int verbosity verbosity RTI RoutingServiceEnvironment get verbosity env if verbosity RTI ROUTING SERVICE VERBOSITY DEBUG printf CALL SimpleFileAdapterConnection create stream writerWMn Create StreamWriter writer calloc 1 sizeof struct SimpleFileAdapterStreamWriter if writer NULL RTI RoutingServiceEnvironment set error env Memory allocation error return NULL Open output file file malloc strlen self gt directory strlen strlen stream_info gt stream_name strlen txt 1 if file NULL RTI_RoutingServiceEnvironment_set_error env Memory allocation error free writer return NULL sprintf file s s txt self directory stream info stream name writer gt fHandle fopen file wt 8 44 8 3 Creating New Adapters 8 3 3 8 if writer gt fHandle NULL RTI RoutingServiceEnvironment set error env Error opening s file free file free writer return NULL free file Creates notification thread printToStdoutStr RTI RoutingServiceProperties lookup
42. docs tooldocs windows jdb html 1 In a separate shell window start jdb UNIX based systems cd opt adapters simplefile jdb sourcepath attach 1024 Windows systems gt cd c adapters SimpleFileAdapter gt jdb sourcepath attach 1024 2 Set breakpoints in the methods or classes that you would like to debug For example to set a breakpoint in the SimpleFileAdapter constructor enter the following main 1 stop in routingservice adapter simplefile SimpleFileAdapter lt init gt 3 Resume the execution of RTI Routing Service by entering main 1 cont You will see output similar to gt Set deferred breakpoint routingservice adapter simplefile SimpleFile Adapter lt init gt Breakpoint hit thread main routingservice adapter simplefile Sim pleFileAdapter lt init gt line 23 bci 0 23 public SimpleFileAdapter Properties props Use the command help to get a list of the command that will allow you to con tinue the debugging process 8 76 8 3 Creating New Adapters 8 3 7 3 Debugging with NetBeans NetBeans is an IDE for developing and debugging Java applications This section is not intended to give complete coverage of all the NetBeans debugger functionality but rather to provide basic information on how to attach the NetBeans debugger to the RTI Routing Service JVM and start debugging 1 Verify that NetBeans IDE 6 9 is installed on your system The installation of Net Beans is beyond t
43. gt include lt string h gt G ifdef RTI_WIN32 L inelude lt process h gt G else L include lt pthread h gt Hendif xogioo X 480 dx3 404405 include ndds ndds c h include rout ingservice routingservice adapter ih Ejfifdef RTI_WIN32 Disbale strtok fopen warnings pragma warning disable 4996 define DllExport declspec dllexport E felse L define DllExport endif A yes aree Show output from Build 8 4 3 sx El code Definition Window ICall Browser eg Find Results 1 Ready 8 23 Chapter 8 6 Right click on SimpleFileAdapter Properties n the Configuration combo box select All Configurations e Select Configuration Properties C C General SimpleFileAdapter Property Pages Ei Configuration fa Configurations 7 Platform activetwinsz 7 Configuration Manager Common Properties Additional Include Directories Configuration Properties Resolve using References General Debug Information Format Debugging Suppress Startup Banner Yes nolago E C C Warning Level Level 3 W3 General j Detect 64 bit Portability Issues No Optimization Treat Warnings As Errors No Preprocessor Lise LINICODE Response Files Yes Code Generation Language Precompiled Headers Output Files Browse Information Advanced Command Line E
44. gt lt registered_type_name gt TextLine lt registered_type_name gt lt property gt lt value gt lt element gt lt name gt print_to_stdout lt name gt lt value gt 1 lt value gt lt element gt lt value gt lt property gt lt output gt lt route gt lt session gt lt domain_route gt lt routing_service gt lt dds gt 5 Start RTI Routing Service by entering the following in a command shell On UNIX based systems gt cd lt SimpleFileAdapter project directory gt gt SROUTINGSERVICEHOME scripts rtiroutingservice cfgFile simple file adapter xml cfgName file to file 8 73 slojdppy g Chapter 8 On Windows systems gt cd SimpleFileAdapter project directory gt SROUTINGSERVICEHOMES scripts rtiroutingservice cfgFile simple file adapter xml cfgName file to file 6 On the screen you will see RTI Routing Service 2 0 1 started with name file to file Hello World 1 Hello World 2 Hello World 3 Hello World 4 Hello World 5 Hello World 6 Hello World 7 Hello World 8 Hello World 9 Hello World 10 7 Verify that a file called HelloWorld txt has been generated into the output direc tory The content of this file should be identical to the content of the same file in the input directory 8 3 7 Debugging Java Adapters When you develop a custom adapter you will need to debug it and test it This section describes the tools and APIs that you have availabl
45. host names are not allowed in the public address because they may resolve to an internet address that is not what you want i e localhost may map to your local IP or to 127 0 0 1 SJJOMJON DOJV pPIM BuisIoADI Z Chapter 7 Table 7 1 TCP TLS Transport Properties over LAN or WAN NDDS Transport TCPvA Property t Property Name prefix with dds transport TCPv4 tcp1 Description server bind port Private IP port inside the LAN used by the transport to accept TCP connections If this property is set to zero the transport will disable the internal server socket making it impossible for external peers to connect to this node In this case the node is considered unreachable and will communicate only using the asynchronous mode with other reach able peers For WAN communication this port must be forwarded to a public port in the NAT enabled router that connects to the outer network Default 7400 read buffer allocation Allocation settings applied to read buffers These settings configure the initial number of buffers the maximum number of buffers and the buffers to be allocated when more buffers are needed Default J read buffer allocation initial count 2 read buffer allocation max count 1 unlimited J read buffer allocation incremental count 1 number of buffers will keep dou bling on each allocation until it reaches max count write buffer allocation
46. i lt count i sample DDS DynamicData sample list i line NULL retCode DDS DynamicData get string sample amp line NULL value DDS DYNAMIC DATA MEMBER ID UNSPECIFIED if retCode DDS RETCODE OK RTI RoutingServiceEnvironment set error env Error assigning value 8 3 Creating New Adapters else samplesWritten c fputs line self gt fHandle fputs n self gt fHandle fflush self fHandle if self gt printToStdout printf s n line fflush stdout DDS_String_free line return samplesWritten Deletes a StreamWriter xy void SimpleFileAdapterConnection_delete_stream_writer RTI_RoutingServiceConnection connection RTI_RoutingServiceEnvironment env struct SimpleFileAdapterStreamWriter writer struct SimpleFileAdapterStreamWriter int verbosity RTI_RoutingServiceStreamWriter stream_writer stream_writer verbosity RTI_RoutingServiceEnvironment_get_verbosity env if verbosity RTI_ROUTING_SERVICE_VERBOSITY_DEBUG printf CALL SimpleFileAdapterConnection_delete_stream_writer n if writer gt fHandle fclose writer gt fHandle free writer Creates a StreamWriter 8 43 siojdopy 9 Chapter 8 7 RTI RoutingServiceStreamWriter SimpleFileAdapterConnection create stream writer RTI RoutingServiceConnection connection RTI RoutingServiceSession session
47. licenseFile file Specifies the license file path and filename Only applicable to licensed versions of RTI Routing Service If not specified RTI Routing Service looks for the license as described in Installing the License File Section 2 3 in the Get ting Started Guide 3 3 eolA1es Buynoy lla Guruuny e Chapter 3 Table 3 1 RTI Routing Service Command line Options Option Description Appends the host name and process ID to the service name provided with the appName option This helps ensure unique identifyExecution names for remote administration and monitoring For example MyRoutingService myhost 20024 maxObjectsPerThread int Parameter for the DomainParticipantFactory noAutoEnable remoteAdministrationDomainId ID Starts RTI Routing Service in a disabled state Use this option if you plan to enable RTI Routing Service remotely as described in the User s Manual This option overwrites the value of the enable attribute in the routing service tag Enables remote administration and sets the domain ID for remote communication When remote administration is enabled RTI Routing Service will create a DomainParticipant Publisher Subscriber DataWriter and DataReader in the designated domain The QoS values for these entities are described in the RTI Routing Service User s Manual This option overwrites the value of the tag domain id within a admi
48. name MyTransfPlugin gt dll mytransformation dll create function 4 opoq 6uiuuojsupij y Chapter 4 MyTransfPlugin create create function transformation plugin Stsansf snati n Ties srouting services r E A d s Table 4 1 on page 4 3 lists the tags allowed within transformation plugin Table 4 2 on page 4 3 lists the tags allowed within a transformation tag Once a transformation plugin is registered a route can use it to create a data transforma tion For example the following route uses a transformation to switch the coordinates of the input sample x becomes y and y becomes x topic route name SquareSwitchCoord gt input participant 1 gt topic name Square topic name registered type name ShapeTypec registered type name lt input gt lt output gt lt topic_name gt Square lt topic_name gt lt registered_type_name gt ShapeType lt registered_type_name gt lt output gt transformation plugin name MyTransfLib MyTransPlugin property value element lt name gt X lt name gt lt value gt Y lt value gt lt element gt lt element gt lt name gt Y lt name gt lt value gt X lt value gt lt element gt lt value gt lt property gt lt transformation gt lt topic_route gt 4 2 4 1 Transformation Usage and Configuration Table 4 1 Transformation Plugin Tags Tags within Num
49. name route gt output stream name HelloWorld stream name registered type name TextLine registered type name lt property gt lt value gt lt element gt lt name gt print_to_stdout lt name gt lt value gt 1 lt value gt lt element gt lt value gt lt property gt lt output gt lt route gt In the previous example the output StreamWriter will store the lines provided by RTI Routing Service on a file called HelloWorld txt It will also print the lines on the screen Insert the following code in the Simple File Adapter StreamWriter section of Sim pleFileA dapter c 8 41 siojdopy 8 Chapter 8 8 42 StreamWriter xf struct SimpleFileAdapterStreamWriter int printToStdout FILE fHandle hi int SimpleFileAdapterStreamWriter write RTI RoutingServiceStreamWriter stream writer const RTI RoutingServiceSample sample list const RTI RoutingServiceSampleInfo info list int count RTI RoutingServiceEnvironment env int i samplesWritten DDS DynamicData sample DDS ReturnCode t retCode char line struct SimpleFileAdapterStreamWriter self struct SimpleFileAdapterStreamWriter stream writer int verbosity verbosity RTI RoutingServiceEnvironment get verbosity env if verbosity RTI ROUTING SERVICE VERBOSITY DEBUG printf CALL SimpleFileAdapterStreamWriter writeWn if self gt fHandle return 0 samplesWritten 0 for i 0
50. read from the routes inputs The data samples provided to the StreamWriters write operation are DynamicData with the following IDL type struct TextLine string lt 1024 gt value E 8 67 siojdbpy 8 Chapter 8 8 68 When a SimpleFileAdapter StreamWriter is created the name of the file is the output stream name with a txt extension For debugging purposes the StreamWriter can be configured to print the written samples on the console route name route gt output stream name HelloWorld stream name registered type name TextLine registered type name property value element name print to stdout name lt value gt 1 lt value gt lt element gt lt value gt lt property gt lt output gt lt route gt In the above example the output StreamWriter will store the lines provided by RTI Routing Service on a file called HelloWorld txt It will also print the lines on the screen Insert the following code in the Simple File Adapter StreamWriter section of Sim pleFileA dapter c Create a file called SimpleFileAdapterStreamWriter java under Adapter directory routingservice adapter simplefile Insert the following content fCRCCKCKCkckck Kokckckckckckokckck ck kokokckckckckckckckckckckckckck kokckck kokokckck ckckckckckckckckckck ck ckckckckckckckck ck ck ko kJ Simple File Adapter Stream Writer fRCECKCKCkCk kc kckckc kk ko koe ke kk kc ke ke ko kc
51. remotely monitor the status of RTI Routing Service To enable remote monitoring and configure its behavior use the monitoring and entity monitoring tags By default remote monitoring is turned off in RTI Routing Service for security and per formance reasons A remote monitoring section is not required in the configuration file 2 4 XML Tags for Configuring RTI Routing Service For example dds routing service lt enabled gt true lt enabled gt lt monitoring gt lt domain_id gt 55 lt domain_id gt lt status_publication_period gt lt sec gt 1 lt sec gt lt status_publication_period gt lt monitoring gt Biwouting sery ices lt dds gt RTI Routing Service allows monitoring of the following kinds of entities e routing service see Section 2 4 1 domain route see Section 2 4 2 e session see Section 2 4 5 e route see Section 2 4 6 e topic route see Section 2 4 6 auto route see Section 2 4 7 e auto topic route see Section 2 4 7 For each entity RTI Routing Service can publish two kinds of information LI Entity data 1 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 configura tion changes Entity status provides information about the ope
52. route gt lt dds_input gt Description Number of Tags Allowed lt registered_type_name gt Sets the registered type name of this topic See Route Types Section 2 4 6 1 1 required lt topic_name gt Sets the topic name 1 required lt creation_mode gt Specifies when to create the DataReader DataWriter Default IMMEDIATE See Creation Modes Controlling when StreamReaders and StreamWriters are Created Section 2 4 6 4 Oorl lt content_filter gt N A Defines a SQL content filter for the DataReader Example lt topic_route gt lt input gt lt content_filter gt lt expression gt x amp gt 100 lt expression gt lt content_filter gt lt input gt lt topic_route gt Oorl 2 4 XML Tags for Configuring RTI Routing Service Table 2 13 DDS Input and Output Tags for a Route or Topic Route 2 4 6 1 2 4 6 2 Tags within Tags within topic route topic route Number input and output and Description of Tags lt route gt lt route gt Allowed lt dds_input gt lt dds_output gt Sets the DataReader or DataWriter QoS The contents of this tag are specified in the same manner as an RTI Data Distribu tion Service QoS profile file see Chapter lt datareader_qos gt datawriter qos 15 in the RTI Data Distribution Service 0 or 1 User s Manual If the tag is not defined RTI Routing Ser vice wil
53. see Section 5 2 1 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 1 x stands for the version letter of the current release 2 3 eoiues Buynoy I134 Guun amp yuo z Chapter 2 Figure 2 1 shows an example configuration file You will learn the meaning of each line as you read the rest of this chapter Figure 2 1 Example XML Configuration File lt xml version 1 0 gt lt dds gt lt routing_service name TopicBridgeExample group_name MyGroup gt lt domain_route name DomainRoute gt lt participant_1 gt lt domain_id gt 0 lt domain_id gt lt participant_1 gt lt participant_2 gt lt domain_id gt 1 lt domain_id gt lt participant_2 gt lt session name Session gt lt topic_route name SquaresToCircles gt lt input participant 1 gt lt registered_type_name gt ShapeType lt registered_type_name gt lt topic_name gt Square lt topic_name gt lt input gt lt output gt lt registered_type_name gt ShapeType lt registered_type_name gt lt topic_name gt Circle lt topic_name gt lt output gt lt topic_route gt lt session gt lt domain_route gt lt routing_service gt lt dds gt This file age a simple bridge from DDS domain 0 to DDS domain 1 and changes the data s topic from Square to Circle Both topics us
54. tag content filter expres sion inside topic route input or route dds input UOIJD20 6jOoUJe3 D WOI GuuojJIuO N 9 Chapter 6 Table 6 4 RouteData Field Name Key Description input adapter data generic property Not applicable for DDS input The properties used to configure this route s StreamReader specified with the tag property inside route lt input gt output adapter data generic property Not applicable for DDS output The properties used to configure this route s StreamWriter specified with the tag property inside route output propagate dispose DDS topic routes only Indicates if the topic route propagates NOT ALIVE DISPOSE samples The propagation of NOT ALIVE DISPOSE samples is configured using the tag propagate dispose in topic route propagate unregister DDS topic routes only Indicates if the topic route propagates NOT ALIVE NO WRITERS samples The propagation of NOT ALIVE NO WRITERS samples is config ured using the tag propagate unregister in topic route publish with original info DDS topic routes only Indicates if the topic route publishes the sam ples with original writer info Setting this option to true allows redun dant topic routes and prevents the applications from receiving duplicate samples The publication with original writer info is configured using the tag publish
55. that provides information about the input samples per second across routes Input samples refer to the samples that are taken by the session from the auto routes s StreamReaders 6 27 UOIJD20 eJowWeY D WOI 6uuojJIuo N 9 Chapter 6 Table 6 10 AutoTopicRouteStatusSet Member Name Key Description Statistic variable that provides information about the input bytes per second across routes Input bytes refer to the bytes that are taken by the session from the i t_byt pues ee auto routes s StreamReaders These bytes only refer to the serialized samples The protocol headers UDP RTPS are not included Statistic variable that provides information about the output samples i 1 per second across routes output_samples_per_s elle i bale Output samples refer to the samples that are published out by the ses sion thread using the auto route s StreamWriters Statistic variable that provides information about the output bytes per second across routes Output bytes refer to the bytes that are published out by the session thread using the auto route s StreamWriters The variable only consid ers the bytes of the serialized samples Protocol headers UDP RTPS are not included output_bytes_per_s Statistic variable that provides information about the latency in sec onds across routes latency_s The latency in a route refers to the time elapsed between the sample read and write This is a g
56. value gt NDDS_Transport_TCPv4_create lt value gt lt element gt lt element gt lt name gt dds transport TCPv4 tcpl parent classid lt name gt lt value gt NDDS_TRANSPORT_CLASSID_TCPV4_WAN lt value gt lt element gt lt element gt lt name gt dds transport TCPv4 tcpl public address lt name gt lt value gt 18 181 0 31 8400 lt value gt lt element gt lt element gt lt name gt dds transport TCPv4 tcpl server bind port lt name gt lt value gt 7400 lt value gt lt element gt lt value gt lt property gt lt participant_qos gt lt participant_2 gt 7 8 7 2 Configuring the TCP Transport domain route routing service dds 7 2 3 TCP TLS Transport Properties Table 7 1 describes the TCP and TLS transport properties Table 7 1 TCP TLS Transport Properties over LAN or WAN NDDS Transport TCPvA Property t Property Name prefix with dds transport TCPv4 Description tcp1 Required dds transport MM i i load_plugins Comma separated strings indicating the prefix names of all plugins that will be loaded by i hi RTI Data Distribution Service For example dds transport TCPv4 tcp1 You will use this piss iB not string as the prefix to the property names See Footnote 1 on page 7 19 ake a prefix i Note you can load up to 8 plugins Required Must be nddstransporttcp library This library needs to be in the path during run time in th
57. with original info inside topic route publish with original timestamp Indicates if the route is configured to publish the output samples with the same timestamp as that of the input sample route types transformations Indicates if the input connection will use types discovered in the out put connection and viceversa for the creation of StreamWriters and StreamReaders The route types flag is configured using the tag route types inside route or topic route List of transformations associated with a route For each transformation you will be able to retrieve the transformation plugin name and the properties Transformations are defined using the transformation tag inside route or topic route Note in this version only one transformation per route is supported 6 2 Monitoring Configuration Data Table 6 4 RouteData Field Name Key Description input state Indicates whether or not the StreamReader associated with a route is created output state Indicates whether or not the StreamWriter associated with a route is created 6 2 5 equal to datawriter key From this sample we can get the DurabilityOosPolicy value accessing the member durability For additional information on how to subscribe to the DDS builtin topics see the RTI Data Distribution Service User s Manual Route data samples are published when 1 The route i
58. 4 XML Tags for Configuring RTI Routing Service Table 2 7 lists the tags allowed within monitoring tag Table 2 7 Monitoring tags c ig te ae Number of Tags within lt monitoring gt Description Tags Allowed Enables disables general remote monitoring Setting this value to true default value in the lt moni toring gt tag under lt routing_service gt enables monitor ing in all the entities unless they explicitly disable it by setting this tag to false in their local lt enabled gt Oor1 entity monitoring tags Setting this tag to false in the monitoring tag under routing service disables monitoring in all the RTT Routing Service entities In this case any monitoring configuration settings in the entities are ignored domain id Specifies which domain ID RTI Routing Service will use to enable remote monitoring 1 required participant qos Configures the DomainParticipant QoS for remote monitoring If the tag is not defined RTI Routing Service will use the RTI Data Distribution Service defaults with the following change resource limits type code max serialized length 4096 Oor1 publisher qos Configures the Publisher QoS for remote monitoring If the tag is not defined RTI Routing Service will use the RTI Data Distribution Service defaults Oor1 datawriter qos Configures the DataWriter QoS for remote monitoring If the tag is not defined
59. Connection cx int verbosity verbosity RTI RoutingServiceEnvironment get verbosity env if verbosity RTI ROUTING SERVICE VERBOSITY DEBUG printf CALL SimpleFileAdapter create connection n cx calloc 1 sizeof struct SimpleFileAdapterConnection if cx NULL RTI_RoutingServiceEnvironment_set_error env Memory allocation error return NULL 8 31 slojdppy g Chapter 8 8 3 3 6 8 32 directory RTI RoutingServiceProperties lookup property properties directory if directory NULL RTI RoutingServiceEnvironment set error env directory property is required free cx return NULL cx directory char malloc strlen directory 1 if cx gt directory NULL RTI_RoutingServiceEnvironment_set_error env Memory allocation error free cx return NULL strcpy cx directory directory return cx From the implementation you can see that the connection object encapsulates the name of the directory from which the StreamReaders and StreamWriters will read and write files The value of the RTI RoutingServiceAdapterPlugin structure created in SimpleFileAdapter_create must be updated to contain the two new functions adapter gt adapter_plugin_create_connection SimpleFileAdapter_create_connection adapter gt adapter_plugin_delete_connection SimpleFileAdapter_delete_connection Implementing the StreamReader The connection objects
60. D lt nanosec gt 0 lt nanosec gt lt status publication period 9 70 If the tag is not defined its value is inherited from the general monitoring settings Specifies the frequency at which status statistics are gathered Statistical variables such as latency are part of the entity sta tus For example statistics sampling period lt sec gt 1 lt sec gt lt nanosec gt 0 lt nanosec gt statistics sampling period statistics sampling period uu Oor1 The statistics period for a given entity should be smaller than the publication period If the tag is not defined the period is inherited from the gen eral monitoring settings This tag is only present in the entity monitoring tag of route topic route auto route auto topic route and routing service 2 25 Chapter 2 Table 2 8 Entity Monitoring Tags Number Tags within Descripti nuu escription of Tags entity monitoring Allowed Enables or disables the publication of statistics calculated within fixed time windows By default RTI Routing Service only publishes the statistics corresponding to the window between two status publica tions By using this tag you can get the following additional win dows LJ 5 seconds LJ 1 minute LJ 5 minutes LJ 1 hour historical statistics N Up time since the entity was enabled 0or1 For example historical statistics five second true five seco
61. Data dds case RTI ROUTING SERVICE GENERIC ADAPTER KIND RouteAdapterData generic 6 2 Monitoring Configuration Data struct RouteInputData Sstring TOPIC NAME MAX LENGTH stream name String TYPE NAME MAX LENGTH registered type name long connection RouteCreationMode creation mode DDSEntityState state RouteInputAdapterData adapter data iz struct RouteOutputData string TOPIC NAME MAX LENGTH stream name string TYPE NAME MAX LENGTH registered type name RouteCreationMode creation mode DDSEntityState state RouteOutputAdapterData adapter data 1 struct RouteData String ENTITY NAME MAX LENGTH routing service name Gkey string ENTITY NAME MAX LENGTH domain route name key Sstring ENTITY NAME MAX LENGTH session name key Sstring ENTITY NAME MAX LENGTH name key String ENTITY NAME MAX LENGTH auto route name boolean propagate dispose boolean propagate unregister boolean publish with original info boolean publish with original timestamp boolean route types RouteInputData input RouteOutputData output sequence lt TransformationData MAX TRANSFORMATIONS transformations Hi Table 6 4 describes the fields in the RouteData topic data type The correlation between a route using DDS and its DDS DataReader and DDS DataWriter can be done using the fields datareader_key and datawriter_key For example let s assume that we want to ret
62. EERE ko koc ke REE ko kc kc ke kc kc kc ck kc kc kckckck ck kckckck ck kckckck ko k package routingservice adapter simplefile import java io File import java io FileWriter import java io BufferedWriter import java io IOException import java util List import java util ListIterator import java util Properties 1 c adapters SimpleFileAdapter for Windows systems or opt adapters simplefile for UNIX based systems 8 3 Creating New Adapters import com import com import com import com public clas private private private private y private int Str pri 3f e 7 SimpleF Str rti dds dynamicdata DynamicData rti routingservice adapter StreamWriter rti routingservice adapter infrastructure AdapterException rti routingservice adapter infrastructure StreamInfo s SimpleFileAdapterStreamWriter implements StreamWriter String verbosity null String fileName null boolean printToStdout BufferedWriter fileWriter null void parseProperties Properties properties printToStdoutInt ing printToStdoutStr ntToStdoutStr properties getProperty print to stdout printToStdoutStr null printToStdout false lse printToStdoutInt new Integer printToStdoutStr intValue if printToStdoutInt 0 printToStdout true else printToStdout false ileAdapterStreamWriter eamInfo streamInfo Properties properties Str St
63. ERVICEHOME bin i86Win32VS2008 rtiroutingservice 8 49 siojdopy 8 Chapter 8 8 3 4 2 8 50 Under Configuration Properties Debugging go to Command Argu ments and add the following cfgFile c NadaptersNSimpleFileAdapterNsimple file adapter xml cfgName file to file e Click OK 5 Open the file SimpleFileAdapter c and insert breakpoints in the functions that you want to debug Then press F5 to run RTI Routing Service and debug the adapter If you get an information window that says there is no debugging information in rtiroutingservice press YES Although rtiroutingservice does not have debug ging symbols your adapter was built with debug information and you should not have any problems debugging it Debugging the Adapter with GDB only for UNIX based systems Let s see how to debug the adapter library with gdb using the SimpleFileAdapter implemented in Section 8 3 3 1 Go to the directory containing the SimpleFileAdapter makefile and build the debug version of the shared library as follows gmake clean gmake DEBUG 1 The debug version of the adapter replaces the release version because is gener ated in the same location Edit the configuration file simple file adapter xml generated in Section 8 3 3 8 and replace the library in the dll tag with the debug version of the adapter For example dll opt adapters simplefile lib i86Linux2 6gcc4 1 1 libsimplefile adapter so dll
64. Each connection belongs to one of the two data domains lt property gt For example lt dds gt lt routing_service name Router1 group_name Group1 gt domain route name DomainRoutel gt connection 1 plugin namez connection 2 registered type connection 1 BP Aa re AT connection 2 plugin_name gt property connection 2 session name Session gt session lt session gt lt domain_route gt lt routing_service gt lt dds gt 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 lt adapter_library gt see Section 2 1 2 12 2 4 XML Tags for Configuring RTI Routing Service For DDS domains the connections are specified using the tags participant 1 and participant 2 Each tag has one associated DDS domain participant The following example routes information between two DDS domains dds routing service name Router1 group_name Group1 gt domain route name DomainRoutel gt participant 1 domain id 54 domain id participant 1 participant 2 domain id 55 domain id participant 2 session name Session gt lt session gt lt domain_route gt lt routing_service gt lt dds gt Configurations mixing connections and participants are allowed to provide communic
65. IFF RUNNING flag implemented by some operating systems The RUNNING flag means that all resources are allocated and may be off if no link is detected e g the network cable is unplugged Two values are allowed 0 Do not check the RUNNING flag when enumerating interfaces just make sure the interface is UP 1 Check the flag when enumerating interfaces and ignore those that are not reported as RUNNING This can be used on some operating systems to cause the transport to ignore interfaces that are enabled but not connected to the network Default 1 7 2 Configuring the TCP Transport Table 7 1 TCP TLS Transport Properties over LAN or WAN NDDS Transport TCPvA Property t Property Name prefix with dds transport TCPv4 tcp1 Description transport priority mask Mask for the transport priority field This is used in conjunction with transport priority mapping low transport priority mapping high to define the mapping from DDS trans port priority to the IPv4 TOS field Defines a contiguous region of bits in the 32 bit trans port priority value that is used to generate values for the IPv4 TOS field on an outgoing socket For example the value 0x0000ff00 causes bits 9 16 8 bits to be used in the mapping The value will be scaled from the mask range 0x0000 Oxff00 in this case to the range speci fied by low and high If the mask is set to zero then the transport will not set IPv4 TOS for sen
66. IP address or hostname gt lt port gt For LAN communication tcpv4_lan lt IP address or hostname gt lt port gt For WAN TLS communication tlsv4_wan lt IP address or hostname gt port For LAN TLS communication tlsv4_lan lt IP address or hostname gt port For example setenv NDDS DISCOVERY PEERS tcpv4 wan 10 10 1 165 7400 tcpv4 wan 10 10 1 111 7400 tcpv4 1lan 192 168 1 1 7500 When the TCP transport is configured for LAN communication with the parent classid property the IP address is the LAN address of the peer and the port is the server port used by the transport the server bind port property When the TCP transport is configured for WAN communication with the par ent classid property the IP address is the WAN or public address of the peer and the port is the public port that is used to forward traffic to the server port in the TCP trans port When TLS is enabled the transport settings are similar to WAN and LAN over TCP 7 2 Configuring the TCP Transport Figure 7 5 Initial Peers in WAN Communication LAN IP address LAN IP address 192 168 1 11 192 168 5 11 Server Bind Port Server Bind Port 7400 7500 Initial Peers Initial Peers 18 181 0 32 8500 192 168 1 11 8400 WAN IP address 18 181 0 31 WAN IP address 18 181 0 32 Port forward settings Port forward settings WAN port 8400 to 192 168 5 11 7400 WAN port 8500 to 192 168 5 11 7500 7 2 2 Setting Up the TCP Transport Properties wi
67. ME MAX LENGTH allow stream name filter string lt 1 YPE NAME MAX LENGTH gt allow registered type name filter string TOPIC NAME MAX LENGTH deny stream name filter string TYPE NAME MAX LENGTH deny registered type name filter long connection RouteCreationMode creation mode AutoRouteInputAdapterData adapter data hi struct Aut oRouteOutputData string lt TOPIC_NAME_MAX LENGTH allow stream name filter string YPE NAME MAX LENGTH allow registered type name filter string TOPIC NAME MAX LENGTH deny stream name filter string TYPE NAME MAX LENGTH deny registered type name filter RouteCreationMode creation mode AutoRouteOutputAdapter J3 struct Aut string lt ENTITY_NAME string lt ENTITY_NAME_MAX_LENGTH gt domain_route_name string lt ENTITY_NAME_MAX_LENGTH gt session_name oRouteData Data adapter_data string lt ENTITY_NAME_MAX_LENGTH gt name key boolean propagate_dispose boolean propagate_unregister _MAX_LENGTH gt routing service name key key key 6 2 Monitoring Configuration Data boolean publish with original info boolean publish with original timestamp long enabled route count AutoRouteInputData input AutoRouteOutputData output is Table 6 5 describes the fields in the AutoRouteData data type Table 65 AutoRouteData input connection Field Name Key
68. NATs To enable secure communication modify the previous configurations as follows L Change the transport class ID property parent classid to be one of the follow ing values NDDS TRANSPORT CLASSID TLSV4 LAN NDDS TRANSPORT CLASSID TLSV4 WAN 7 4 7 1 TCP Communication Scenarios Figure 7 4 Asymmetric Communication Across NATs parent classid A t A NDDS TRANSPORT ON parent classid TCPv4 Transport CLASSID TCPV4 WAN NS NDDS TRANSPORT TCPv4 Transport CLASSID TCPV4 WAN public address unset IP address 192 168 1 11 IP address public address 192 168 5 11 18 181 0 32 8500 server bind port 0 Unreachable node Reachable node H 11 Data NAT Router NAT Router Initial Peers server_bind_port 7400 18 181 0 32 8500 Initial Peers lt unset gt WAN IP address WAN IP address 18 181 0 32 18 181 0 31 Public Server Bind Port 8500 Port forward settings WAN port 8500 to 192 168 5 11 7400 Notice that the RTI Routing Service on LAN 1 now does not have a public address set and its server bind port is set to zero meaning that it cannot be reached from the outside network 1 Set at least a certificate of authority through either the tls verify ca file or tls verify ca path properties and the certificate identity through either the tls identity certificate chain or tls identity certificate chain file properties L Make sure t
69. Oorl 2 34 2 4 XML Tags for Configuring RTI Routing Service Table 2 12 lists the tags allowed within the input and output tags in a route tag Table 2 12 Input and Output Tags for a Route Tags within input Tags within output Description Number of Tags Allowed registered type name Sets the registered type name of this stream See Route Types Section 2 4 6 1 1 required stream name Sets the stream name 1 required Specifies when to create the Stream Reader StreamWriter Default IMMEDIATE creation mode 0or1 See Creation Modes Controlling when StreamReaders and StreamWriters are Created Section 2 4 6 4 Sequence of name value string pairs that can be used to configure certain parameters of the StreamReaders StreamWriters For example lt property gt lt value gt lt property gt lt element gt 0or1 lt name gt com rti socket port lt name gt lt value gt 16556 lt value gt lt element gt lt value gt lt property gt 2 35 eolA1es Buynoy I134 Guun amp yuo z Chapter 2 Table 2 13 lists the tags allowed within the DDS input and output tags in a route or topic route tag Table 2 13 DDS Input and Output Tags for a Route or Topic Route 2 36 Tags within topic route output and lt route gt lt dds_output gt Tags within lt topic_route gt lt input gt and lt
70. RTI Routing Service for RTI Data Distribution Service User s Manual Version 2 0 PT 2009 2010 Real Time Innovations Inc All rights reserved Printed in U S A First printing re TI June 2010 Trademarks Real Time Innovations and RTI are registered trademarks of Real Time Innovations Inc All other trademarks used in this document are the property of 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 Real Time 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 385 Moffett Park Drive Sunnyvale CA 94089 Phone 408 990 7444 Email supportGrti com Website http www rti com support Contents 1 Welcome to RTI Routing Service T T Available Documentations is ie ieeecc saec scene enero ani e Ue Eee eT RO nie 1 3 2 Configuring RTI Routing Service 21 Terms to KNOW d PB PM 2 2 2 2 How to Load the XML Configuration esee e eee e een enne 2 3 23 XML Syntax and Validation sses esardi portas itta dbi to ase tbe ea hiaai 2 5 24 XML Tags for Configuring RTI Routing Service
71. RTI Routing Service will use the RTI Data Distribution Service defaults with the following change durability kind DDS TRANSIENT LOCAL DURABILITY QOS Oor1 2 2 dIA1eg 6uunoy 11a Guun amp yuo z Chapter 2 Table 2 7 Monitoring tags Tags within monitoring Description Number of Tags Allowed status publication period Specifies the frequency at which the status of an entity is published For example status publication period sec 3 sec lt nanosec gt 0 lt nanosec gt lt status_publication_period gt If the tag is not defined the period is 5 seconds The status publication period defined in routing service is inherited by all the entities inside routing service An entity can overwrite the period Oor1 statistics sampling period 2 22 Specifies the frequency at which status statistics are gathered Statistical variables such as latency are part of the entity status For example statistics sampling period lt sec gt 1 lt sec gt lt nanosec gt 0 lt nanosec gt lt statistics_sampling_period gt 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 routing service is inherited by all the entities inside routing service An entity can overwrite the period Oor1 2 4 XML Tags fo
72. RTI RoutingServiceStreamInfo int disposed char stream name struct RTI RoutingServiceTypeInfo type info hi The dispose member is used to indicate whether the stream is a new discovered stream or a disposed stream The type_info member provides information about the type associated with the stream struct RTI RoutingServiceTypeInfo char type name RTI RoutingServiceTypeRepresentationKind type representation kind RTI RoutingServiceTypeRepresentation type representation Lr The content associated with the type representation depends on the type representation kind For example if the representation kind is RTI ROUTING SERVICE TYPE REPRESENTATION DYNAMIC TYPE the type representation member will contain an RTI Data Distribution Service TypeCode The method copy type representation is used by RTI Routing Service to copy the type representation associated with a discovered stream Reading Data RTI Routing Service uses the session threads there is one per session tag to read data from StreamReaders Each session thread will block waiting for new data using a WaitSet When a StreamReader receives new data it will use the StreamReaderListener s on data available callback operation to wake up the session thread associated with it After that the session thread will invoke the StreamReader s read operation to get the new data Session Thread on data available Wait StreamReader
73. ServiceConfigurableEntity UpdateFcn transformation update void user object 1 The rest of this section introduces the different transformation functions For detailed information about the API please see the online HTML RTI Routing Service documen tation 4 3 Creating New Transformations LL delete Deletes the transformation plugin instance typedef void RTI RoutingServiceTransformationPlugin delete struct RTI RoutingServiceTransformationPlugin plugin RTI RoutingServiceEnvironment env create transformation Creates a new transformation The function is called when the route containing the transformation is ready to forward data typedef RTI RoutingServiceTransformation RTI RoutingServiceTransformationPlugin create transformation struct RTI RoutingServiceTransformationPlugin plugin const struct RTI RoutingServiceTypeInfo input type info const struct RTI RoutingServiceTypeInfo output type info const struct RTI RoutingServiceProperties properties RTI RoutingServiceEnvironment env The behavior of the transformation can be configured using the properties parameter delete transformation Deletes a transformation The function is called when the route containing the transformation is disabled typedef void RTI RoutingServiceTransformationPlugin delete transformation struct RTI RoutingServiceTransformationPlugin plugin RTI RoutingServiceTransformatio
74. TI ROUTING SERVICE DomainRouteParticipantData dds case RTI ROUTING SERVICE GENERIC ADAPTER KIND DomainRouteAdapterConnectionData generic ls struct DomainRouteData String ENTITY NAME MAX LENGTH routing service name key string ENTITY NAME MAX LENGTH name key DomainRouteConnectionData connection 1 DomainRouteConnectionData connection 2 Table 6 2 on page 6 5 describes the members of the DomainRouteData data type Table 6 2 DomainRouteData Field Name Key Description routing service name V The routing service name assigned using appName The domain route name This is configured using the name y name attribute in the lt domain_route gt tag connection_1 The configuration of the connection 1 or lt participant_1 gt If it is a connection 1 the union discriminator is RII ROUTING SERVICE GENERIC ADAPTER KIN D if itis a participant 1 the union discriminator is RII ROUTING SERVICE DDS ADAPTER KIND connection 2 The configuration of the connection 2 or participant 2 If it is a connection 2 the union discriminator is RII ROUTING SERVICE GENERIC ADAPTER KIN D if it is a participant 2 the union discriminator is RII ROUTING SERVICE DDS ADAPTER KIND connection l generic plugin name The name of the plugin used by the first connection connection 1 connection 2 generic plugin name
75. TI Routing Service A configuration file may contain multiple routing service tags When you start RTI Routing Service you can specify which routing service tag to use to configure the service using the cfgName command line parameter 2 8 2 4 XML Tags for Configuring RTI Routing Service For example lt dds gt routing service name Router1 group name Group1 routing service routing service name Router2 group name Group1 routing service lt dds gt Starting RTI Routing Service with the following command will use lt routing_service gt tag with the name Router1 rtiroutingservice cfgFile example xml cfgName Router1 the Because a configuration file may contain multiple routing service tags one file can be used to configure multiple RTI 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 hap pens 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 circu lar communication If the routing service tag does not have a group name attribute RTT Routing Service will use the following name RTI RoutingService Host Name Process ID such as RTI RoutingService myhost 20024 routing servic
76. The route StreamReader is not created until the associ ated connection discovers a data Producer on the same stream For example for a DDS domain RTI Routing Service will not create the route DataReader until a DataWriter for the same topic is discovered on the same domain The routing service StreamWriter is not created until the associated connection discovers a data Consumer on the same stream For example for a DDS domain RTI Routing Service will not create the route DataWriter until a DataReader for the same topic is discover on the same domain ON ROUTE MATCH The routing service StreamReader StreamWriter is not created until its counterpart in the route is created ON DOMAIN AND ROUTE MATCH Both conditions must be true ON DOMAIN OR ROUTE MATCH At least one of the conditions must be true Route Destruction The same rules that are applied to create the route StreamWriter and StreamReader also apply to their destruction When the condition that triggered the creation of that entity becomes false the entity is destroyed Note that IMMEDIATE will never become false 2 4 XML Tags for Configuring RTI Routing Service For example if the creation mode of a topic route s input tag is ON DOMAIN MATCH when all the matching user DataWriters in the input domain are deleted the topic route s DataReader is deleted Example 1 In this example data is routed as soon as a user DataWriter i
77. address 8192 server y suspend y lt element gt lt options gt lt jvm gt The JVM option Xdebug is used to enable debugging The JVM option Xrunjdwp loads the JDPA reference implementation of JOWP Java Debug Wire Protocol and starts listening on port 8192 to communicate with a separate debugger application such as jdb and NetBeans For additional details on Java debugging see http java sun com javase technologies core toolsapis jpda 3 Save the changes 4 Run RTI Routing Service On UNIX based systems cd SimpleFileAdapter project directory gt SROUTINGSERVICEHOME scripts rtiroutingservice cfgFile simple file adapter xml cfgName file to file On Windows systems cd SimpleFileAdapter project directory gt SROUTINGSERVICEHOME scripts rtiroutingservice cfgFile simple file adapter xml cfgName file to file You should see output like this Listening for transport dt socket at address 1024 At this point the execution of RTI Routing Service is suspended and waiting for a debugger to attach 8 75 siojdopy 8 Chapter 8 8 3 7 2 Debugging with JDB jdb is the command line debugger of Java This section is not intended to give complete coverage on all the jdb functionality and commands but rather to provide basic infor mation on how to attach to the RTI Routing Service JVM and start debugging For more information about JDB see the following web page http java sun com j2se 1 5 0
78. alue returned by the function create transformation update This function is called when the configuration of a transformation changes as a result of a remote update command typedef void RTI RoutingServiceTransformation UpdateFon RTI RoutingServiceTransformation transformation const struct RTI RoutingServiceProperties properties RTI RoutingServiceEnvironment env Chapter 5 Administering RTI Routing Service from 5 1 a Remote Location RTI Routing Service can be controlled remotely by sending commands through a special DDS Topic Any DDS application can be implemented to send these commands and receive the corresponding responses A shell application that sends receives these com mands is provided with RTI Routing Service The script for the shell application is in lt RTI Routing Service installation directory gt scripts rtirssh Entering rtirssh help will show you the command line options RTI Routing Service Shell 1 0 0 Usage rtirssh options Options domainId lt integer gt Domain id for the remote configuration timeout lt seconds gt Max time to wait a remote response help Displays this information Note The RTI Routing Service shell requires the dynamic libraries in the lt RTI Routing Service installation directory gt bin lt architecture gt directory If you are running on a UNIX based system make sure the path to those dynamic libraries is in your LD_LIBRARY_PATH environment variable
79. amWriters The adapter discovery API is used to provide stream and type infor mation in a data domain to RTI Routing Service The discovery API consists of four methods L Connection get input stream discovery reader L Connection get output stream discovery reader L Connection copy type representation L Connection delete type representation The first two methods provide access to StreamReaders used to discover streams in the data domain associated with a connection The input StreamReader get input stream discovery reader provides information about input streams An input stream is a stream from which a StreamReader read data Disposed scenarios where an input stream disappears are also notified using the input StreamReader In the built in DDS adapter the input StreamReader is associated with the publication built in DataReader of the DomainParticipant The output StreamReader get output stream discovery reader provides informa tion about output streams An output stream is a stream to which StreamWriters can write data Disposed scenarios where an output stream disappears are also notified using the output StreamReader In the built in DDS adapter the output StreamReader is associated with the subscription built in DataReader of the DomainParticipant The samples provided by the discovery StreamReaders have the type RoutingServiceStreamInfo 8 2 Adapter API And Entity Model 8 2 3 struct
80. ance of transformations 6 3 Monitoring Status 6 3 6 Status Information for an Auto Route The topic that publishes auto route status is called rti routing service monitoring topic route status set The auto route status aggregates the statistics of the routes created from it the mean of the means in the routes the absolute maximum and minimum across routes the mean of the standard deviation and the total count The IDL definition of the data type is struct AutoRouteStatusSet String ENTITY NAM E MAX LENGTH routing service name key String ENTITY NAME MAX LENGTH domain route name key String ENTITY NAME MAX LENGTH session name key String ENTITY NAME MAX LENGTH name key StatisticVariable StatisticVariable StatisticVariable StatisticVariable StatisticVariable is input samples per s input bytes per s output samples per s output bytes per s latency s Table 6 10 describes the fields in the AutoRouteStatusSet data type Table 6 10 AutoTopicRouteStatusSet Member Name Key Description routing service name The routing service name assigned with appname domain route name session name The domain route name The session name name SISINIS The auto route name The auto route name is configured using the name attribute in the lt auto_topic_route gt tag input_samples_per_s Statistic variable
81. articipant qos Oor1 If the tag is not defined RTI Routing Service will use the RTI Data Distribution Service defaults eoiues Buynoy I134 Guun amp yuo z Chapter 2 Table 2 6 Remote Administration Tags 2 4 4 AI Number Tags within ius i Description of Tags administration Allowed Configures the Publisher QoS for remote administration publisher qos If the tag is not defined RTI Routing Service will use the RTI Oor 1 Data Distribution Service defaults Configures the Subscriber QoS for remote administration subscriber qos If the tag is not defined RTI Routing Service will use the RTI 0 or 1 Data Distribution Service defaults Configures the DataReader QoS for remote administration If the tag is not defined RTI Routing Service will use the RTI Data Distribution Service defaults with the following changes datareader qos reliability kind DDS RELIABLE RELIABILITY QOS this 0 or 1 value 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 RTI Routing Service will use the RTI datawriter qos Data Distribution Service defaults with the following changes Oor1 history kind DDS KEEP ALL HISTORY QOS resource limits max samples 32 Monitoring You can create an RTI Data Distribution Service application that can
82. as static NAT or port forwarding and it allows traffic originating in outer networks to reach designated peers in the LAN behind the NAT router 7 3 SJJOMJON DOJV pPIM BuisIoADI Z Chapter 7 Figure 7 3 Symmetric Communication across NATs poem parent classid ici NDDS TRANSPORT 4 Transport CLASSID TCPV4 WAN parent classid NDDS TRANSPORT TCPv4Transport CLASSID TCPV4 WAN public address 18 181 0 31 8400 IP address 192 168 1 11 IP address public address 192 168 5 11 18 181 0 32 8500 server bind port 7400 g server_bind_port 7400 Initial Peers 18 181 0 32 8500 Initial Peers 18 181 0 31 8400 Connection EE ES E Quem Data NAT Router NAT Router WAN IP address 18 181 0 31 WAN IP address 18 181 0 32 Public Server Bind Port 8400 Public Server Bind Port 8500 Port forward settings Port forward settings WAN port 8400 to 192 168 1 11 7400 WAN port 8500 to 192 168 5 11 7400 7 1 3 Asymmetric Communication Across NATs This scenario is similar to the previous one except in this case the TCP connections can be initiated only by the RTI Routing Service instance in LANI For security reasons incoming connections to LANI are not allowed Figure 7 4 shows how to configure the TCP transport in this scenario 7 1 4 Secure Communication Security can be added on top of any of the above scenarios You can have secure com munication within the same LAN or across
83. ation between DDS domains and other data domains The following example routes information between a JMS provider network and a DDS domain lt domain_route gt lt participant_1 gt i lt participant_qos gt lt registered_type gt lt participant_2 gt lt domain_id gt lt participant_qos gt lt registered_type gt lt session gt 2 13 eolA1es Buynoy La Guun amp yuo z Chapter 2 lt dds gt routing service name Router1 group name Group1 domain route name DomainRoutel gt connection 1 plugin name adapter library jms connection 1 participant 2 domain id 55 domain id participant 2 session name Session gt lt session gt lt domain_route gt lt routing_service gt lt dds gt Table 2 3 lists the tags allowed within a lt domain_route gt tag Table 2 3 Domain Route Tags Tags within Description domain route P Number of Tags Allowed 7 Applicable to non DDS domains lt connection_1 gt Configures the first connection See Table 2 4 Only applicable to DDS domains participant 1 N Ba Configures the first participant See Table 2 5 1 required E Applicable to non DDS domains connection 2 Configures the second connection See Table 2 4 m Only applicable to DDS domains participant 2 D Configures the second participant See Table 2 5 1 required Defi
84. atistics corresponding to the time between two status publications publication period metrics You can also select additional windows on a per entity basis using the tag historical statistics see Section 2 4 4 The sequence historical metrics in StatisticVariable contains values corresponding to the windows that have been enabled l 5 sec metrics correspond to activity in the last five seconds 1 min metrics correspond to activity in the last minute L 5 min metrics correspond to activity in the last five minutes l 1 hour metrics correspond to activity in the last hour l Up time metrics correspond to activity since the entity was enabled Each window has a field called period ms that identifies its size in milliseconds For the publication period metrics this field contains the publication period For the up time metrics this field contains the time since the entity was enabled For the other windows this field contains a fixed value that identifies the window size 5000 for the 5 second window 60000 for the one minute window etc 6 3 Monitoring Status 6 3 1 2 6 3 2 Statistics Calculation The accuracy of the statistics calculation process is determined by the value of the statis tics sampling period This period specifies how often statistics are gathered and is con figured on a per entity basis using the tag cstatistics sampling period see Section 2 4 4 As a general rule the statistics sampling pe
85. ave an associated StreamReader and StreamWriter respectively For DDS domains the StreamReader will contain a DataReader and the StreamWriter will contain a DataWriter The DDS DataReaders and DataWriters belong to the corresponding session s Subscriber and Publisher The read and write operations in a route will be performed in the context of the thread associated with the session Routes vs Auto Routes A route is an explicit route of data for two specific streams An auto route defined with a different tag auto route is a way to automatically create routes based on filters see Auto Routes Section 2 4 7 Table 2 10 lists the tags allowed within a route Table 2 10 Route Tags Number Tags within route Description of Tags Allowed dds input Only applicable to DDS inputs Defines the route s input topic See Table 2 13 1 required input Applicable to non DDS inputs Defines the route s input stream See Table 2 13 dds output Only applicable to DDS outputs Defines the route s output topic See Table 2 13 1 required Applicable to non DDS outputs output P Defines the route s output stream See Table 2 13 Defines if the input connection will use types dis covered in the output connection and vice versa for the creation of StreamWriters and StreamReaders in route types the route ort See Discovering Types Section 2 4 6 3 Default false
86. ber lt transformation_ Description of Tags plugin gt Allowed Shared library containing the implementation of the transformation plugin The dll tag may specify the exact name of the file for example lib lib mytransformation so or a general name no file extension which will be completed as follows dll value dir mytransformation dll Final Path UNIX based systems dir libmytransformation so 1 Final Path Windows systems dir mytransformation dll required If the library specified with the dll tag cannot be opened because the library path is not in the Path environment variable on Windows or the LD LIBRARY PATH environment variables on UNIX based systems RTI Routing Service will look for the library in RTI Routing Service installa tion directory gt bin lt architecture gt This tag will contain the name of the function used to create the transfor 4 create function mation plugin see Section 4 3 1 The function must be implemented in the shared library required Table 4 2 Transformation Tags T Number Tags within S aan tens Description ES Sequence of name value string pairs that can be used to configure the parameters of the transformation For example lt property gt lt value gt lt element gt lt name gt X lt name gt lt value gt Y lt value gt lt element gt lt property gt lt element gt Oor1 name Y name lt value gt X lt value gt lt element gt lt value gt lt p
87. d sockets Default 0 transport priority mapping low transport priority mapping high Sets the low and high values of the output range to IPv4 TOS These values are used in conjunction with transport priority mask to define the mapping from DDS transport priority to the IPv4 TOS field Defines the low and high values of the output range for scaling Note that IPv4 TOS is generally an 8 bit value Default transport priority mapping low 0 Default transport priority mapping high OxFF server socket backlog Determines the maximum length of the queue of pending connections Default 5 public address Required for WAN communication Public IP address and port WAN address and port associated with the transport instanti ation The address and port must be separated with For example 10 10 9 10 4567 This field is only used when parent classid is NDDS TRANSPORT CLASSID TCPVA4 WAN or NDDS TRANSPORT CLASSID TLSV4 WAN The public address and port are necessary to support communication over a WAN that involves Network Address Translators NATs Typically the address is the public address of the IP router that provides access to the WAN The port is the IP router port that is used to reach the private server bind port inside the LAN from the outside This value is expressed as a string in the form ip port where ip represents the IPv4 address and port is the external port number of the router Note that
88. dapter plugin The function must be implemented in the adapter shared library lt property gt Sequence of name value string pairs that can be used to config ure the parameters of the adapter For example lt property gt lt value gt lt element gt lt name gt username lt name gt lt value gt myusername lt value gt lt element gt lt value gt lt property gt Oor1 3 Session A Session is a concurrency unit within a connection that has an associ ated set of StreamReaders and StreamWriters Access to the StreamReaders and StreamWriters in the same Session is serialized by RTI Routing Service two Stream Readers StreamWiriters cannot be accessed concurrently In the built in DDS adapter a Session is mapped to a Publisher Subscriber pair 8 2 Adapter API And Entity Model Table 8 2 Java Adapter Plugin Tags Tags within lt java_adapter_plugin gt Description Number of Tags Allowed lt class_name gt Required Name of the class that implements the adapter plugin For exam ple com rti adapters JMSAdapter The classpath required to run the Java adapter must be part of the RTI Routing Service JVM configuration See Routing Service Tags Table 2 2 for additional information on JVM creation and configuration with the routing service lt property gt Sequence of name value string pairs that can be used to config ure the parameters of the adapter For example
89. dapterConnection create stream reader This function is called when a new StreamReader is created Among other things the implementation will open the file that will be read and create the notification thread Insert the following code in the Simple File Adapter StreamReader section of Sim pleFileAdapter c StreamReader struct SimpleFileAdapterStreamReader int run ifdef RTI_WIN32 HANDLE thread else pthread_t thread endif DDS_DynamicData sample 1 struct DDS Duration t readPeriod struct RTI RoutingServiceStreamReaderListener listener FILE fHandle hi Returns sample loan 4 void SimpleFileAdapterStreamReader return loan RTI RoutingServiceStreamReader stream reader RTI RoutingServiceSample sample list RTI RoutingServiceSampleInfo info list int count RTI RoutingServiceEnvironment env 8 3 Creating New Adapters int verbosity verbosity RTI_RoutingServiceEnvironment_get_verbosity env if verbosity RTI_ROUTING_SERVICE_VERBOSITY_DEBUG printf CALL SimpleFileAdapterStreamReader_return_loan n return j Reads one line from the StreamReader file x void SimpleFileAdapterStreamReader read RTI RoutingServiceStreamReader stream reader RTI RoutingServiceSample sample list RTI RoutingServiceSampleInfo info list int count RTI RoutingServiceEnvironment env DDS ReturnCode t retCode char line 2048 char str struc
90. de creation mode is configured using the tag Contains the configuration of the auto route s input that is specific to either the DDS adapter or a generic adapter When a generic input is defined auto route input the union discriminator is RII ROUTING SERVICE GENERIC ADAPTER KIND if it is a DDS input auto topic route input or auto route dds input the union discriminator is RTI ROUTING SERVICE DDS ADAPTER KIND output adapter data Contains the configuration of the auto route s output that is spe cific to either the DDS adapter or a generic adapter When a generic output is defined auto route output the union discriminator is RII ROUTING SERVICE GENERIC ADAPTER KIND if it is a DDS output auto topic route output or auto route dds output the union discriminator is RTI ROUTING SERVICE DDS ADAPTER KIND input adapter data dds domain id DDS input only Domain ID of the input participant output adapter data dds domain id DDS output only Domain ID of the output participant UOIJD20 6jOoUJO3 D WOI GuuojJIuO N 9 Chapter 6 Table 65 AutoRouteData Field Name Key Description input adapter_data dds content_filter_expression DDS input only Content filter expression associated with the content filter for the topic route DataReader The expression is configured using the tag lt content_filter gt
91. develop completely custom solutions Bridges automati cally inherit advanced RTI Data Distribution Service capabilities including auto matic discovery of applications data transformation and filtering data lifecycle management and support across operating systems programming languages and network transports 1 1 Available Documentation 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 out of 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 require ments or serve as a template for quick creation of new custom adapters Real Time Applications ua Plug in Adapters ey Service rss tc ea 3 au d Quickly build and deploy bridges between natively incompatible protocols and technologies using RTI Data Distribution Service Available Documentation RTI Routing Service documentation includes L Getting Started Guide RTI Routing Service GettingStarted pdf Highlights the benefits of RTI Routing Service It provides installation and startup instruc tions and walks you through several examples so you can quickly see the bene fits of using RTI Routing Service QWOIIOM L Chapter 1 L Release Notes RTI Routing
92. e V The domain route name name The domain route name is configured using the name attribute in the domain route tag 6 22 6 3 Monitoring Status Table 6 7 DomainRouteStatusSet Field Name Key Description input_samples_per_s Statistic variable that provides information about the input samples per second across routes Input samples refer to the samples that are taken by the sessions from the routes s StreamReaders input_bytes_per_s Statistic variable that provides information about the input bytes per second across routes Input bytes refer to the bytes that are taken by the sessions from the routes s StreamReaders These bytes only refer to the serialized samples The protocol headers UDP RTPS are not included output_samples_per_s Statistic variable that provides information about the output samples per second across routes Output samples refer to the samples that are published out by the ses sion threads using the route s StreamWriters output_bytes_per_s Statistic variable that provides information about the output bytes per second across routes Output bytes refer to the bytes that are published out by the session threads using the route s StreamWriters The variable only considers the bytes of the serialized samples Protocol headers UDP RTPS are not included latency_s Statistic variable that provides information about th
93. e target routing service can be e The application name of a routing service such as MyRoutingServicel as specified at start up with the command line option appName e A regular expression fora routing service name such as MyRoutingService y 1 As defined by the POSIX fnmatch API 1003 2 1992 section B 6 5 2 5 2 Remote Commands I entity name is a fully qualified name For example consider the following XML configuration routing service name ShapeRoutingService gt domain route name DomainRoutel gt session name Session gt topic route name SquaresToCircles gt The above XML configuration would allow you to use commands such as enable ShapeRoutingService DomainRoutel Session SquaresToCircles enable ShapeRoutingService DomainRoutel Note that the fully qualified name does not include the name of the routing ser vice LI xml url can be e A file URL such as file home user myconfig xml e Astring URL such as str topic route input datareader gos datareader qos input topic route If you omit the URL schema name RTI Routing Service will assume a file name for example home user myconfig xml is equivalent to file home user myconfig xml In either case the XML code can represent either a whole DTD valid configura tion file such as the one you specify through the command line when you start RTI Routing Service o
94. e administration Section 2 4 3 monitoring Section 2 4 4 Optional entity monitoring Section 2 4 4 domain route Section 2 4 2 Required 2 9 eolA1es Buynoy I1 Guun amp yuo z Chapter 2 Table 2 2 describes the tags allowed within a routing service tag Table 2 2 Routing Service Tags 2 10 n Number Tags within Descrivti fT lt routing_service gt en pues vd Allowed Contains a lt documentation gt tag that can be used to provide a routing service description This description will show up annotation 0 or1 when you run RTI Routing Service without the cfgName com mand line option s Defines a mapping between two data domains See 1 or more domain route Section 2 4 2 required Enables and configures remote administration See Adminis lt administration gt tration Section 2 4 3 and Chapter 5 Administering RTI Rout 0 or 1 ing Service from a Remote Location Enables and configures general remote monitoring General es monitoring settings are applicable to all the RTI Routing Service monitoring entities unless they are explicitly overridden 0or1 See Monitoring Section 2 4 4 MENT Enables and configures remote monitoring for the entity monitoring Oorl routing service entity 2 4 XML Tags for Configuring RTI Routing Service Table 22 Routing Service Tags Tags within routing service Desc
95. e To change an immutable parameter you must disable the routing service entity change the parameter and then enable the routing service entity again 5 5 uoupijsiulup v ejouiey G Chapter 5 Table 5 1 Changeable Parameters Entit Mutable Immutable P y changeable any time only changeable when entity is disabled monitoring statistics sampling period monitoring enabled monitoring historical statistics Routing monitoring status publication period monitoring domain id Service enity monitoring enabled entity monitoring entity monitoring status publication period statistics sampling period entity monitoring historical statistics E connection x Immutable properties in prop connection x Mutable properties in property vs a erty gt adapter specific adapter specific gt A PET W BEA participant qos Immutable QoS policies in D participant x Mutable QoS policies in EMEND da id participant qos P Paes route enity monitoring enabled SENUIY monitoring nu m statistics sampling period entity monitoring status publication period NE d m entity monitoring historical statistics TE For non DDS adapter Mutabl operties in For non DDS adapter Mutable properties in prop r Be i Mo propers erty gt adapter specific lt property gt adapter specific
96. e 2 1 describe the top level tags allowed within the root lt dds gt tag qos library See RTI Data Distribution Service User s Manual Ch 15 Optional routing service Required i Section 2 4 1 2 7 eoiues Buynoy I134 Guun amp yuo z Chapter 2 Table 2 1 Top level Tags in the Configuration File Number Tags within lt dds gt Description of Tags Allowed Specifies an RTI Routing Service configuration See 1 or more routing service Routing Service Section 2 4 1 required Specifies a QoS library and profiles The contents of this tag are specified in the same qos library manner as for an RTI Data Distribution Service QoS 0 or more profile file see Chapter 15 in the RTI Data Distribu tion Service User s Manual Specifies a library of transformation plugins See Data Transformation Section 2 4 6 5 and Chapter 4 Transforming Data with RTI Routing Ser vice transformation library 0 or more Specifies a library of adapter plugins adapter library See Adapters Section 2 4 8 and Chapter 8 Extend 0 or more ing RTI Routing Service with Adapters Defines types that can be used by the routing ser vice t Oor1 ypes gt See Defining Types in the Configuration File a Section 2 4 6 2 2 4 1 Routing Service A configuration file must have at least one routing service tag this tag is used to configure an execution of R
97. e 2 45 lists the tags allowed within an auto topic route tag I Table 2 17 on page 2 46 lists the tags allowed within an auto topic route tag l Table 2 18 on page 2 47 lists the tags allowed within input and output tags nested within an auto route tag l Table 2 19 on page 2 50 lists the tags allowed within the DDS input and output tags nested within an auto topic route or a topic route tag Table 2 16 Auto Route Tags T Number Tag within Descripti escription of Tags auto topic route Allowed Only applicable to DDS inputs lt dds_input gt Defines the auto route s input stream topic See Auto Routes Section 2 4 7 1 required Applicable to non DDS inputs input Defines the auto route s input stream See Auto Routes Section 2 4 7 2 45 eolA1es Buynoy La Buun6Byuosd z Chapter 2 Table 2 16 Auto Route Tags Tag within auto topic route Description Number of Tags Allowed dds output Only applicable to DDS outputs Defines the auto route s output stream topic See Auto Routes Section 2 4 7 output Applicable to non DDS outputs Defines the auto route s output stream See Auto Routes Section 2 4 7 1 required publish with original When this tag is true the data samples read from the input streams are written into the output streams with the same timestamp that was associated with them whe
98. e LD LIBRARY PATH environ create function ment variable on UNIX systems in PATH for Windows systems Required Must be NDDS Transport TCPv4 create aliases Used to register the transport plugin returned by NDDS Transport TCPv4 create as specified by TCP prefix create function to the DomainParticipant Aliases should be specified as a comma separated string with each comma delimiting an alias Default the transport prefix see Footnote parent classid Must be set to one of the following values NDDS TRANSPORT CLASSID TCPV4 LAN for TCP communication within a LAN NDDS TRANSPORT CLASSID TLSV4 LAN for TLS communication within a LAN NDDS TRANSPORT CLASSID TCPV4 WAN for TCP communication across LANs and firewalls NDDS TRANSPORT CLASSID TLSV4 WAN for TLS communication across LAN and firewalls Default NDDS_TRANSPORT_CLASSID_TCPV4_LAN SJJOMJON Dely OpIM BulsiOADI Z Chapter 7 Table 7 1 TCP TLS Transport Properties over LAN or WAN NDDS Transport TCPvA Property t Property Name prefix with dds transport TCPv4 tcp1 Description parent gather_send_ buffer_count_max Specifies the maximum number of buffers that RTI Data Distribution Service can pass to the send function of the transport plugin The transport plugin send operation supports a gather send concept where the send call can take several discontiguous buffers assemble and send th
99. e functions that create and delete a connection Insert the following code in the Simple File Adapter Connection section of SimpleFi leAdapter c Connection R struct SimpleFileAdapterConnection char directory H Deletes a connection void SimpleFileAdapter delete connection struct RTI RoutingServiceAdapterPlugin adapter RTI RoutingServiceConnection connection RTI RoutingServiceEnvironment env struct SimpleFileAdapterConnection cx struct SimpleFileAdapterConnection connection int verbosity 8 3 Creating New Adapters verbosity RTI RoutingServiceEnvironment get verbosity env if verbosity RTI ROUTING SERVICE VERBOSITY DEBUG printf CALL SimpleFileAdapter delete connection n if cx gt directory NULL free cx gt directory free cx Creates a connection ey RTI_RoutingServiceConnection SimpleFileAdapter_create_connection struct RTI_RoutingServiceAdapterPlugin adapter const char routing_service_name const char routing_service_group_name const struct RTI_RoutingServiceStreamReaderListener input_disc_listener const struct RTI_RoutingServiceStreamReaderListener output_disc_listener const struct RTI RoutingServiceTypeInfo registeredTypes int registeredTypeCount const struct RTI RoutingServiceProperties properties RTI RoutingServiceEnvironment env const char directory struct SimpleFileAdapter
100. e latency in sec onds across routes The latency in a route refers to the time elapsed between the sample read and write This is a good metric to monitor the health and perfor mance of transformations 1 The throughput measured in bytes can only be computed if the samples are DynamicData samples If not only the throughput measured in samples per second is available This statement applies to all the statistic variables described in this chapter that measure throughput in bytes per second 6 23 UOIJD20 6jOoUJO3 D WOI GuuojIuO N 9 Chapter 6 6 3 4 Status Information fo r a Session The topic that publishes session status is called rti routing service monitoring session status set The session status aggre gates the statistics of the routes contained in it the mean of the means in the routes the absolute maximum and minimum across routes the mean of the standard deviation and the total count The IDL definition of the data type is struct SessionStatusSet String ENTITY NAME MAX LENGTH routing service name key string ENTITY NAMI MAX LENGTH domain route name key string ENTITY NAMI StatisticVariable StatisticVariable StatisticVariable StatisticVariable StatisticVariable E Table 6 8 describes the fi Table 6 8 SessionStatusSet E MAX LENGTH name key input samples per s input bytes per s output samples per s output bytes per s latency
101. e the same data type ShapeType You will find this example in lt RTI Routing Service installation directory gt example shapes topic_bridge xml Additional examples are in the same directory 2 4 2 3 XML Syntax and Validation XML Syntax and Validation The XML configuration file must follow these syntax rules l The syntax is XML the character encoding is UTF 8 l Opening tags are enclosed in lt gt closing tags are enclosed in lt gt LIA tag value is a UTF 8 encoded string Legal values are alphanumeric characters RTI Routing Service s parser will remove all leading and trailing spaces from the string before it is processed For example tag value lt tag gt is the same as lt tag gt value lt tag gt LJ All values are case sensitive unless otherwise stated LJ Comments are enclosed as follows lt comment gt 1 The root tag of the configuration file must be lt dds gt and end with lt dds gt RTI 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 RTI Routing Service instal lation directory lresource schema rti rout
102. e to debug and detect problems in RTI Routing Service adapters written in Java The first debugging capability is provided by the RTI Routing Service Adapter SDK The adapter SDK provides a way to access the verbosity level of RTI Routing Service as a property called rti routingservice verbosity which can be obtained from the properties passed to the adapter constructor It is highly recommended that as part of the adapter implementation you instrument the code by adding status messages that will be printed with the INFO and DEBUG verbosity levels This level of instrumentation will help you to capture run time information for troubleshooting The second debugging capability is provided by third party tools The rest of this sec tion shows how to debug a Java adapter using jdb the command line debugger of Java and NetBeans IDE 6 9 8 3 7 1 Enabling Debugging in the RTI Routing Service JVM Before you start debugging with jdb or NetBeans you have to enable debugging in the JVM created RTI Routing Service 8 74 8 3 Creating New Adapters 1 If you have not done so already stop the existing RTI Routing Service execution by pressing CTRL C 2 Edit java simple adapter xml and replace the content of the JVM tag with lt jvm gt lt class_path gt lt element gt class simplefileadapter jar lt element gt lt class_path gt lt options gt lt element gt Xdebug lt element gt lt element gt Xrunjdwp transport dt socket
103. eader fHandle return NULL return reader The value of the RTI RoutingServiceAdapterPlugin structure created in SimpleFileAdapter_create must be updated to contain the StreamReader functions adapter gt connection_create_stream_reader SimpleFileAdapterConnection_create_stream_reader adapter gt connection_delete_stream_reader SimpleFileAdapterConnection_delete_stream_reader adapter gt stream_reader_read 8 40 8 3 Creating New Adapters 8 3 3 7 SimpleFileAdapterStreamReader read adapter stream reader return loan SimpleFileAdapterStreamReader return loan Implementing the StreamWriter The connection objects are factories of StreamWriters A StreamWriter provides a way to write samples of a specific type into a data domain In the configuration file StreamWriters are associated with the tag output within route or auto route see Section 2 4 6 The SimpleFileAdapter StreamWriters create new files into the connection directory and store the lines read from the routes inputs The data samples provided to the write operation of the StreamWriters are Dynamic Data with the following IDL type struct TextLine string lt 1024 gt value un When a SimpleFileAdapter StreamWriter is created the name of the file is the output stream name with txt extension For debugging purposes the StreamWriter can be configured to print the written samples on the console route
104. em in a single message This enables RTI Data Distribution Service to send a message from parts obtained from dif ferent sources without first having to copy the parts into a single contiguous buffer However most transports that support a gather send concept have an upper limit on the number of buffers that can be gathered and sent Setting this value will prevent RTI Data Distribution Service from trying to gather too many buffers into a send call for the transport plugin RTI Data Distribution Service requires all transport plugin implementations to support a gather send of least a minimum number of buffers This minimum number is defined as NDDS TRANSPORT PROPERTY GATHER SEND BUFFER COUNT MIN Default 128 parent message size max The maximum size of a message in bytes that can be sent or received by the transport plugin If you set this higher than the default the DomainParticipant s buffer size in the RECEIVER POOL QosPolicy see the RTI Data Distribution Service User s Manual should also be changed Default 9216 parent allow interfaces list A list of strings each identifying a range of interface addresses that can be used by the transport Interfaces must be specified as comma separated strings with each comma delimiting an interface For example 10 10 10 15 If the list is non empty this white list is applied before parent deny interfaces list Default All available interfaces are u
105. en to the network socket API Traditionally DDS applications can only communicate with applications in the same domain With RTI 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 appli cations don t even need to use the same data structure You can also control which data is sent by using allow and deny lists Simply set up RTI Routing Service to pass data from one domain to another and specify any desired data filtering and transformations No changes are required in the DDS applications eUJO9JI9M L Chapter 1 Key benefits of RTI Routing Service I It can significantly reduce the time and effort spent integrating and scaling DDS applications across Wide Area Networks and Systems of Systems Many systems today already rely on 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 RTI Routing Service you can scale 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 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
106. ence of properties defined in the tag property inside property q prop 8 lt property session Session data samples are published when I The session is enabled 1 The session is disabled dispose sample LJ An auto route route inside the session is enabled LJ An auto route route inside the session is disabled L1 Monitoring is enabled via remote administration UOIJD20 6jOoUJO3 D WOI GuuojJIuo N 9 Chapter 6 6 2 4 6 8 Configuration Data for a Route The topic that publishes route configuration data is called rti routing service monitor ing route data The IDL definition of the data type RTI RoutingService Monitoring RouteData is struct TransformationData string lt ENTITY_NAME_MAX LENGTH gt plugin_name sequence lt Property MAX PROPERTIES property E struct RouteAdapterData sequence lt Property MAX PROPERTIES property struct RouteDdsInputData long domain_id BuiltinTopicKey t datareader key String EXPRESSION MAX LENGTH content filter expression hi union RouteInputAdapterData switch AdapterKind case RTI_ROUTING_SERVICE_DDS_ADAPTER_KIND RouteDdsInputData dds case RTI_ROUTING_SERVICE_GENERIC_ADAPTER_KIND RouteAdapterData generic l7 struct RouteDdsOutputData long domain id BuiltinTopicKey t datawriter key E union RouteOutputAdapterData switch AdapterKind case RTI ROUTING SERVICE DDS ADAPTER KIND RouteDdsOutput
107. enne 6 22 6 3 4 Status Information for a Session sese enne 6 24 6 8 5 Status Information for a Route neret etnnn enn 6 25 6 8 6 Status Information for an Auto Route eese nnne 6 27 7 Traversing Wide Area Networks 74 TEP Communication Scenarios o tree rette PE Pete sues Fede edat E E 7 2 7 11 Communication Within a Single LAN esee eee eene 7 2 7 1 2 Symmetric Communication Across NATS sese eee 7 3 7 13 Asymmetric Communication Across NATSs sssssseseeeee ee 7 4 7 144 Sec re Comnimunicatioti decerneret Wake EEEE Ree e dae REN e bot 7 4 Ta Configuring the TOP Transport edet eret entre i a eere ne s 7 6 72 1 TCP Transport Initial Peers eerte cette rhe aiena E 7 6 7 2 2 Setting Up the TCP Transport Properties with the PropertyQoSPolicy 7 7 42 3 TCP TLS Transport Properties cete terree ient ions 7 9 8 Extending RTI Routing Service with Adapters 8 1 Adapter Usage and Configuration sese eene 8 2 8 2 Adapter API And Entity Model erret rte pintor teer t ie derer te Fete on 8 3 8 2 1 Entity Creation T H 8 11 8 22 Stream DISCOVeZLy isceetee piene sterne rtis teer restet s paa ere ierat oa dg oA 8 12 829 Reading Datacenter ater ute a e aet d 8 13 8 3 Creating New Adapters nien nme rni terra eei tat rae ni iian isu Isa E e ERE IRSE ne beds 8 14 8 3 1 Adapter SDK Component
108. erbosity 3 or higher the TestAdapter will also print the DynamicData samples as they arrive For an example of how to use and configure the TestAdapter see RTI Routing Service home gt example testing test_adapter xml This example tests the simple C file adapter introduced in previous sections You can also write your own adapter to extend the TestAdapter class The source code is in rtirsadapter jar
109. ervice installation directory gt lib lt architecture gt rtirsinfrastructure dll for Windows systems The transformation plugin will link with this library Transformation plugins working with TypeCode and DynamicData must also link with RTI Data Distribution Service Important Because RTI only distributes the release version of RTI Routing Service your transformation should be linked against the release version of the RTI Data Distribution Service shared libraries when needed Transformation Plugin API Every transformation plugin will implement a plugin constructor entry point to the shared library that will be used by RTI Routing Service to create a plugin instance typedef struct RTI RoutingServiceTransformationPlugin RTI RoutingServiceTransformationPlugin create RTI RoutingServiceEnvironment env The structure RTI RoutingServiceTransformationPlugin will contain the plugin imple mentation as a set of function pointers struct RTI RoutingServiceTransformationPlugin RTI RoutingServiceTransformationPlugin DeleteFcn transformation plugin delete RTI RoutingServiceTransformationPlugin CreateTransformationFcn transformation plugin create transformation RTI RoutingServiceTransformationPlugin DeleteTransformationFcn transformation plugin delete transformation RTI RoutingServiceTransformation TransformFcn transformation transform RTI RoutingServiceTransformation ReturnLoanFcn transformation return loan RTI Routing
110. format for type definitions For more information see Section 3 4 in the RTI Data Distribution Service User s Manual Discovering Types If a route refers to types that are not defined in the configuration file RTI Routing Service has to discover their type representation e g typecode A route cannot be created without the type representation information By default the StreamReader creation will be tied to the discovery of types e g type codes in the input domain and the StreamWriter creation will be tied to the discovery of types e g typecodes in the output domain If you want to use types discovered in either one of the domains for the creation of both the StreamReader and StreamWriter you must set the route types tag to true In the following example both the StreamWriter and StreamReader will be created as soon as the type ShapeType is discovered in either domain 2 4 XML Tags for Configuring RTI Routing Service topic route route types true c route types input participant 1 gt creation mode IMMEDIATE creation mode registered type name ShapeType registered type name lt input gt lt output gt lt creation_mode gt IMMEDIATE lt creation_mode gt lt registered_type_name gt ShapeType lt registered_type_name gt lt output gt lt topic_route gt In this next example the StreamReader will be created only when the type ShapeType is discovered in the input domain the StreamWri
111. gt lt period gt lt sec gt 10 lt sec gt lt period gt lt deadline gt 5 9 UOHDISIUIWUpY ejowey G Chapter 5 lt datareader_qos gt lt input gt lt topic_route gt The content above is small enough to send it in one sample Otherwise if the length were gt XML_URL_MAX LENGTH we would have to split it in multiple partial strings each lt XML_URL_MAX LENGTH and set final 0 for all the samples but the last one cmdRequest command u entity desc xml url final 1 RTI RoutingService CommandRequest writer write cmdRequest 5 10 Chapter 6 Monitoring RTI Routing Service from a Remote Location You can monitor RTI Routing Service remotely by subscribing to special DDS topics By subscribing to these topics any DDS application can receive information about the con figuration and operational status of RTI Routing Service Being able to monitor the state of an RTI Routing Service instance is an important tool that allows you to detect problems For example looking at the latency statistics for a route might show you that the performance of a transformation in the route is not as expected Looking at the input samples per second in the different sessions you might see that one session is receiving most of the traffic In that case you could reassign some of the routes to other sessions to improve load balancing RTI Routing Service can publish status for the following kinds of e
112. gt include routingservice_infrastructure h RTI Routing Service home include routingservice adapter h C Adapter API This section does not intend to give complete information on all the C API functions but rather to describe the aspects of the API that are specific to the C language For detailed information about the C API please see the online HTML RTI Routing Ser vice documentation Every adapter plugin will implement a plugin constructor entry point to the shared library that will be used by RTI Routing Service to create a plugin instance typedef struct RTI_RoutingServiceAdapterPlugin RTI_RoutingServiceAdapterPlugin_CreateFcn const struct RTI_RoutingServiceProperties properties RTI_RoutingServiceEnvironment env slojdopy 8 Chapter 8 8 16 The entry point function is specified in the configuration file using the tag create function within adapter plugin see Section 8 1 The structure RTI RoutingServiceAdapterPlugin will contain the plugin implementa tion as a set of function pointers This structure also encapsulates the plugin version information that will be used by RTI Routing Service for logging purposes struct RTI RoutingServiceAdapterPlugin int init struct RTI RoutingServiceVersion rs version The version of the adapter struct RTI RoutingServiceVersion plugin version RTI RoutingServiceAdapterPlugin DeleteFcn adapter plugin delete Adapter API RTI Rou
113. gt MASK_DEFAULT lt mask gt lt priority gt THREAD PRIORITY DEFAULT priority stack size THREAD STACK SIZE DEFAULT stack size lt thread gt ajaen sionS Default values mask MASK_DEFAULT priority THREAD_PRIORITY_DEFAULT stack_size THREAD_STACK_SIZE_DEFAULT Oor1 2 4 XML Tags for Configuring RTI Routing Service Table 2 9 Session Tags Tags within session Description Number of Tags Allowed lt property gt Sequence of name value string pairs that can be used to con figure certain parameters of the session For example lt property gt lt value gt lt element gt lt name gt com rti socket timeout lt name gt lt value gt 1 lt value gt lt element gt lt value gt lt property gt These properties are only used in non DDS domains Oor1 wait set Configures the WaitSet used to sleep and notify the session thread when data is available Example session wait set max event count 5 max event count max event delay lt sec gt 1 lt sec gt lt nanosec gt 0 lt nanosec gt lt max_event_delay gt lt wait_set gt lt session gt 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
114. guments MyA dapter Error Notification RTI Routing Service must be notified about errors in the adapter s logic To do so use the following exception com rti routingservice adapter infrastructure AdapterException Adapter Verbosity The property rti routingservice verbosity provided to the Adapter constructor can be used to get the verbosity level used to run RTI Routing Service Table 8 11 describes the mapping between the command line option verbosity and the values of the property rti routingservice verbosity 8 3 Creating New Adapters Table 8 11 Mapping between verbosity and rti routingservice verbosity 8 3 6 8 3 6 1 verbosity rti routingservice verbosity 0 none 1 exception 2 warn 3 and 4 info 5and 6 debug My First Java Adapter This section shows how to create a simple Java adapter on Windows and UNIX based architectures It is not intended to give complete coverage of the entire adapter API but rather to introduce the adapter technology and provide the basics of the development process of a Java adapter The new Adapter will be a simple file adapter where the input adapter reads lines from a text file and the output adapter saves the provided lines to an output text file The source code and scripts that you will create in the next sections are provided in lt RTI Routing Service home gt adapters tutorial Java Setting the Environment on the Development Machine
115. he scope of this document please refer to NetBeans documen tation 2 Start NetBeans 3 Make the adapter source code available to the debugger a Select Window Debugging Sources b Right click the Remote Attach window and select Add Source Root c Enter the adapter directory Selected Project Source Root Iv C adapters SimpleFileAdapter 8 77 siojdopy 8 Chapter 8 4 Set breakpoints in the methods or classes that you would like to debug For example to set a breakpoint in the SimpleFileAdapter constructor follow the following steps a Select Debug New Breakpoint b In the New Breakpoint window select Method as the breakpoint type and provide routingservice adapter simplefile SimpleFileAdapter as the class name and init as the method name E New Breakpoint outingservice adapter simplefile SimpleFileAdapter pom pee Bess D restpont thread m Method breakpoint hit in className methodName at line 4 c Press OK 8 78 8 3 Creating New Adapters 8 3 8 5 Attach the debugger to RTI Routing Service JVM a Select Debug Attach Debugger b For the Host enter the name of the host where RTI Routing Service is running c For the Port enter 8192 x Debugger Java Debugger JPDA Transport tsoket Host host 70 0 ooo Port Biy ooo ooo Timeout ms NENNEN Cancel Help d Press OK to start debugging the adapter Te
116. he tag lt property gt within lt java_adapter_plugin gt and other values are set by RTI Routing Service One of the pre defined values is rti routingservice verbosity This property provides information about the verbosity level used to run RTI Routing Service see Section 8 3 5 3 Adapter objects are factories for Connection objects 8 57 siojdopy 8 Chapter 8 8 3 6 5 8 58 Implementing the Connection Class Connection objects provide access to data domains such as DDS domains or JMS net work providers and they are configured using the XML tags connection 1 and connection 2 in a domain route see Section 2 4 2 In the SimpleFileAdapter example the connection objects will provide access to a directory in your computer s file system The next step consists of implementing the Connection Java class Create a file called SimpleFileAdapterConnection java under Adapter directory routingservice adapter simplefile Insert the following content fCRCKCKCkckck Kokckckckckckckckckckckokokckckckckckckckckckckokckckckokckck ko kokokck ckckckckckckckckckck ck ck ckckckckckckckck ck ko k Simple File Adapter Connection fCRCKCKCkckck Kokckckckckckokckck ck kokokckckckckckck ck REE ERE kokckck ck kokckck ckckckckckckckckckck ck ck ckckckckckckck ck k ko k package routingservice adapter simplefile import java util Properties import com rti routingservice adapter Connection import com rti routingse
117. how to debug the adapter library with Visual Studio 2008 using the SimpleFile Adapter implemented in Section 8 3 3 1 Start Microsoft Visual Studio 2008 and open the solution SimpleFileAdapter 2 In the Solution Configuration combo box select Debug configuration and recom pile the SimpleFileAdapter project 3 Edit simple file adapter xml the configuration file generated in Section 8 3 3 8 Replace the library in the dll tag with the debug version of the adapter For example lt dll gt c adapters SimpleFileAdapter Debug SimpleFileAdapter dll lt dll1 gt 4 Right click on SimpleFileAdapter Properties SimpleFileAdapter Property Pages xi Configuration Jactive Debug 7 Platform Jactive winz Configuration Manager E Common Properties Debugger to launch Configuration Properties Local Windows Debugger x General Command ROUTINGSERVICEHOME bin i86win32VS2008 rtiroutingse t ci C Command Arguments cfgFile c adapters SimpleFileAdapter simple_file_adapter x Linker Working Directory Manifest Tool Attach No XML Document Generator Debugger Type AU Browse Information Build Events Environment Custom Build Step Merge Environment Yes SQL Debugging No Command The debug command to execute MD e In the configuration combo box select Debug Under Configuration Properties Debugging go to Command and add the following ROUTINGS
118. ile For example lt xml version 1 0 gt lt dds gt adapter library name MyAdapterLibrary adapter plugin name MyCAdapterPlugin dll mycadapter dll create function MyCAdapterPlugin create create function adapter plugin java adapter plugin name MyJavaAdapter class name com rti adapters MyJavaAdapter class name java adapter plugin adapter library lt dds gt C adapters are registered using the tag lt adapter_plugin gt Java adapters use the tag lt java_adapter_plugin gt Table 8 1 lists the tags allowed within lt adapter_plugin gt Table 8 2 lists the tags allowed within lt java_adapter_plugin gt Once the adapter plugins are registered they can be used to create connections within a domain route see Section 2 4 2 8 2 8 2 Adapter API And Entity Model For example lt dds gt routing service name Router1 group name Groupl domain route name DomainRoutel gt connection 1 plugin name MyAdapterLibrary MyCAdapterPlugin connection 1 connection 2 plugin name MyAdapterLibrary MyJavaAdapter connection 2 lt session name Session gt lt session gt lt domain_route gt lt routing_service gt lt dds gt 8 2 Adapter API And Entity Model There are five main classes in the adapter class model 1 Adapter An Adapter is a factory for Connections See Table 8 3 Adapter Operations on page 8 7
119. ill contain the build script and the adapter implementa tion The rest of this section assumes that you will use opt adapters simplefile as the adapter directory 2 In opt adapters simplefile create a file called build sh with the following con tent bin sh FEAE EEE E HE FE HE AERE RETE TEE FE HE E HE HE HE HE FE FE TEE REE HEGRE EET EAE EEG HEE EH HEE RTI Routing Service File Simple Adapter HEH HH HE HE E HE HE HH FE FE HE HE FE HE FE FE FE FE HE FE FE FE FE HE HEE HEH HEE HE HEE E FEFE HE FE FE HE HE HE HE FE HE HE FE FE FE HE FE HE FE HE HE FE FE FE HE FE FE FE FE HE HE FE FE FE FE FE HE FE FE HE FE HE FE FE FHE FE FHE FE FE HE HE FE FE FE HE FHE FE FE HE HE HE HE HE HE HE HE HE H Java compiler JAVAC javac JAR jar Path to RTI Routing Service Adapter API ADAPTER CLASSPATH SROUTINGSERVICEHOME class rtirsadapter jar Path to RTI DDS Java API DDS CLASSPATH SROUTINGSERVICEHOME class nddsjava jar ALL SRC find routingservice adapter simplefile name java mkdir p class Builds all files from routingservice to class echo Building all the sources in rtiroutingservice into class directory SJAVAC d class sourcepath classpath SADAPTER CLASSPATH S DDS CLASSPATH SALL SRC SJAR cf class simplefileadapter jar C class routingservice rm rf class routingservice 1 Replace architecture with your existing architecture For example i86Linux2 6gcc4 1 1 8 3 Creating New Ada
120. in is implemented in the shared library lt RTI Routing Service installation directory gt bin lt architecture gt librtirsassigntransf so or rtirsassign transf dll for Windows systems Important The assign transformation only supports the assignment of primitive fields including strings that are not part of arrays or sequences For example transformation plugin name TransformationLib Assignment lt property gt lt value gt lt element gt lt name gt position x lt name gt lt value gt position y lt value gt lt element gt lt element gt lt not supported gt lt name gt x 0 lt name gt value y 0 value lt element gt lt element gt lt supported gt lt name gt position lt name gt lt value gt position lt value gt lt element gt lt value gt lt property gt lt transformation gt Creating New Transformations RTI Routing Service provides a transformation SDK in C to support the creation of cus tom transformation plugins The SDK contains two main components L API header file RTI Routing Service installation directory gt include routing service routingservice transformation h The transformation plugin will include this header 4 5 opoq 6uiuuojsupij y Chapter 4 4 3 1 I Infrastructure library RTI Routing Service installation directory gt lib lt archi tecture gt librtirsinfrastructure so for UNIX based systems and RTI Routing S
121. ind For example if the representation kind is RTI ROUTING SERVICE TYPE REPRESENTATION DYNAMIC TYPE the type representation will be an RTI Data Distribution Service TypeCode copy type Werde Med on This method is part of the adapter discovery API and is used by RTI Routing Ser vice to copy the type representation of discovered streams see Stream Discovery Section 8 2 2 Implementation of this API is optional and tied to the implementation of get input stream discovery reader and get output stream discovery reader Deletes a previously created type representation object delete type This method is part of the adapter discovery API representation Implementation of this API is optional and tied to the implementation of get input stream discovery reader and get output stream discovery reader Updates the connection s configuration update This method is called when the update command is received by the domain route containing the connection see Section 5 2 5 Implementation of this API is optional Table 8 5 Session Operations Operation Description Updates the configuration of a session update This method is called when the update command is received by the routing ser vice session lt session gt tag containing the adapter session see Section 5 2 5 Implementation of this API is optional 8 9 siejdbpy 9 Chapter 8 Table 8 6 StreamReader Operations Operati
122. ing service dtd and RTI Routing Service installation directory lresource schema rti routing service xsd respectively To include a reference to the XSD document in your XML file use the attribute xsi noNamespaceSchemaLocation in the lt dds gt tag For example lt xml version 1 0 encoding UTF 8 gt dds xmlns xsi http www w3 org 2001 XMLSchema instance xsi noNamespaceSchemaLocation lt installation directory for RTI Routing Service resource schema rti routing service xsd lt dds gt To include a reference to the DTD document in your XML file use the lt DOCTYPE gt tag 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 5 dIA1eg Buynoy La Guun amp yuo z Chapter 2 For example lt xml version 1 0 encoding UTF 8 gt lt DOCTYPE dds SYSTEM lt installation directory for RTI Routing Service gt resource schema rti_routing_service dtd gt lt dds gt lt dds gt We recommend including a reference to the XSD file in the XML documents this pro vides stricter validation and better auto completion than the corresponding DTD file 2 6 2 4 XML Tags for Configuring RTI Routing Service 2 4 XML Tags for Configuring RTI Routing Service This section describes the XML tags you can use in an RTI Routing Service configuration file The following diagram and Tabl
123. ing this name See the RTI Routing Service User s Manual for more information In addition the name of DomainParticipants created by RTI Routing Service will be based on this name Default The name given with cfgName if present otherwise it is RTI Routing Service cfgFile file Specifies the XML configuration file The contents of the XML file are described in the RTI Routing Service User s Manual In addition to the file provided using this command line option the router can load other XML files see the RTI Rout ing Service User s Manual cmdName file Specifies the name of a file that contains commands to be exe cuted A command file may contain any number of commands one per line exactly as they would be entered in the shell prompt See also sleep cfgName This name is used to find the matching routing service tag in the configuration file It is required unless both remoteAd ministrationDomainId and noAutoStart are used in which case no configuration is loaded at start up and RTI Routing Ser vice will simply wait to be configured remotely domainIdBase ID Sets the base domain ID This value is added to the domain IDs in the configuration file For example if you set domainIdBase to 50 and use domain IDs 0 and 1 in the configuration file then the RTI Routing Ser vice will use domains 50 and 51 Default 0 help Displays help information
124. ion Service see the RTI Data Distribution Service Getting Started Guide As part of the installation process make sure that NDDSHOME points to the RTI Data Distribution Service installation directory 8 19 slojdopy 8 Chapter 8 2 Set the environment variable ROUTINGSERVICEHOME Set ROUTINGSERVICEHOME to the RTI Routing Service installation directory RTI Routing Service itself does not require that you set the environment variable It is used to build and compile new adapters 3 For UNIX based systems RTI Routing Service requires the dynamic libraries in the RTI Routing Service home bin architecture Make sure the path to those dynamic libraries is in your LD LIBRARY PATH environment variable 8 3 3 2 Creating a Visual Studio Project Only for Windows systems In this section you will create a Visual Studio project for the adapter dynamic library We will use Microsoft Visual Studio 2008 1 Start Microsoft Visual Studio 2008 2 Select File New Project Visual C Win32 Win32 Project Name the project SimpleFileAdapter and select a location New Project Project types Templates NET Framework 3 5 x Visual C Visual Studio installed templates ATL CLR EA win32 Console Application E Win32 Project General MFC My Templates Smart Device Test Win32 Other Languages E Other Project Types Test Projects Gglsearch Online Templates
125. ion of data samples and sample infos in the data domain associ write ated with the StreamWriter 8 10 Implementation of this API is required if the adapter is used to produce data 8 2 Adapter API And Entity Model 8 2 1 Entity Creation The sequence diagram in Figure 8 2 shows how the different RTI Routing Service entities are created Figure 8 2 Entity Creation Sequence Diagram adapter library name adapters gt adapter plugin name file gt lt dll gt fileadapter lt dll gt lt create_function gt adapter plugin Jadapter library 2 create_connection 3 create Connection Connection domain route connection 1 plugin_name adapters file gt property value s element 5 create Connection Connection lt value gt lt property gt lt connection_1 gt lt connection_2 plugin_name adapters file gt property value element lt value gt lt property gt lt connection_2 gt lt domain_route gt 6 create_session gt 7 create Session lt session name session gt lt property gt lt value gt lt element gt J 8 create session Nalue 9 createl ESSET lt property gt lt session gt 10 create stream reader 11 createl route na
126. ions on compiling and using the sample adapters see Adapter Sample Code Section 4 9 Section 4 10 and Section 4 11 in the Getting Started Guide Sample Code RTI Routing Service home gt adapters Sample Configuration Files RTI Routing Service home gt example shapes 8 3 Creating New Adapters Table 8 8 Adapter SDK Components Component Description SDK jar file rtirsadapter jar The SDK jar file provides the necessary interfaces and support classes to implement Java adapters see Section 8 3 5 In addition the JAR file also includes an implementation of a test adapter TestAdapter that can be used to test new input adapters implementa tions JAR Location lt RTI Routing Service home gt class rtirsadapter jar SDK infrastructure shared library lib rtirsinfrastruc ture dll so The infrastructure library provides environment see Section 8 3 2 1 and properties management functions for C adapters The C adapters will have to link with this library Library Location lt RTI Routing Service home gt bin lt architecture gt lib rtirsinfrastructure dll so 8 3 2 The C adapters will have to include two SDK header files routingservice_adapter h This header file defines the adapter API routingservice_infrastructure h This header file defines the public inter SDK header files face of the infrastructure library Header Location lt RTI Routing Service home
127. is equal to participantl key From this sample we can get the PropertyQosPolicy by accessing the member called property For additional information on how to subscribe to DDS builtin topics see the RTI Data Distribution Service User s Manual Domain route data samples are published when L The domain route is enabled l The domain route is disabled dispose sample L1 Monitoring is enabled via remote administration 6 2 Monitoring Configuration Data 6 2 3 Table 6 3 Configuration Data for a Session The topic that publishes session configuration data is called rti routing service moni toring session data The session data describes the configuration of the session but not its contained entities The IDL definition of the data type is struct SessionData String ENTITY NAME MAX LENGTH routing service name key Sstring ENTITY NAME MAX LENGTH domain route name key Sstring ENTITY NAME MAX LENGTH name key long enabled route count sequence lt Property MAX PROPERTIES property Table 6 3 describes the fields in the SessionData data type SessionData Field Name Key Description routing service name v The routing service name assigned using appName domain route name Y The domain route name The session name which is configured with the name attribute in name V the session tag enabled route count The number of enabled routes The sequ
128. is set to true the data samples are written 0or1 timestamp with their original source timestamp Default false The topic routes are created with this configuration When this flag is set to true the NOT ALIVE DISPOSE propagate dispose samples received by the topic routes DataReaders are not 0 or 1 published with the topic routes DataWriters Default true The topic routes are created with this configuration When this flag is set to true the mm Leite ed dis NOT ALIVE NO WRITERS samples received by the bert propagate_unregis topic routes DataReaders are not published with the topic routes DataWriters as unregister samples Default true Enables and configures remote monitoring for the auto lt entity_monitoring gt topic route See Monitoring Section 2 4 4 and Chapter 6 0 or 1 Monitoring RTI Routing Service from a Remote Location 18 Input and Output Tags for the auto route Tag Tags within Tags within NET pod input output Besenphon 0 ags Allowed lt creation_mode gt 2 4 6 4 The routes are created with this configuration See Creation Modes Controlling when Stream Readers and StreamWriters are Created Section Oor1 2 47 eoiues Buynoy I134 Guun amp yuo z Chapter 2 Table 2 18 Input and Output Tags for the auto route Tag 2 48 Tags within Tags within 2 rv popu input output Description of Tags Allowed The topic route
129. ish the output samples with the same timestamp as that of the input sample enabled route count The number of enabled routes associated with the auto route Auto topic route data samples are published when LJ The auto route is enabled 1 The auto route is disabled dispose sample 1 The auto route configuration is modified using the remote command update 6 3 Monitoring Status 6 3 6 3 1 6 3 1 1 LJ A new route is created from the auto route lL Monitoring is enabled via remote administration Monitoring Status Operational status for RTI Routing Service entities is published in entity status set top ics This information changes continuously and is computed and published periodically The status information for the different entities is composed primarily of statistics Section 6 3 1 explains how these statistics are calculated and published These sections describe the status information associated with each kind of entity I Status Information for the Routing Service Section 6 3 2 LJ Domain Route Status Section 6 3 3 J Status Information for a Session Section 6 3 4 LJ Status Information for a Route Section 6 3 5 J Status Information for an Auto Route Section 6 3 6 Each section describes the IDL for the topics underlying data types The IDL is also in the file RTI Routing Service installation directory gt resource idl RoutingService Monitoring idl How the Statistic
130. it is used to establish a data connection Until the data connection is established the cookie cannot be reused by the server outstanding connection cookies To avoid wasting memory it is good practice to set a cap on the maximum number of con nection cookies pending connections When the maximum value is reached a client will not be able to connect to the server until new cookies become available Range 1 or higher or 1 which means an unlimited number Default 100 outstanding connection cookies life span Maximum lifespan in seconds of the cookies associated with pending connections If a client does not connect to the server before the lifespan of its cookie expires it will have to request a new cookie Range 1 second or higher or 1 Default 1 which means an unlimited amount of time effectively disabling the feature tls verify ca file A string that specifies the name of a file containing Certificate Authority certificates The file should be in PEM format See the OpenSSL manual page for SSL load verify locations for more information To enable TLS ca file or ca path is required both may be specified at least one is required tls verify ca path A string that specifies paths to directories containing Certificate Authority certificates Files should be in PEM format and follow the OpenSSL required naming conventions See the OpenSSL manual page for SSL CTX load verify locatio
131. l count 2 LJ control buffer allocation max count 1 unlimited J control buffer allocation incremental count 1 number of buffers will keep doubling on each allocation until it reaches max count control message allocation Allocation settings applied to control messages These settings configure the initial number of messages the maximum number of mes sages and the messages to be allocated when more messages are needed Default LJ control message allocation initial count 2 J control message allocation max count 1 unlimited 1 control message allocation incremental count 1 number of messages will keep doubling on each allocation until it reaches max count control attribute allocation Allocation settings applied to control messages attributes These settings configure the initial number of attributes the maximum number of attri butes and the attributes to be allocated when more attributes are needed Default LJ control attribute allocation initial count 2 J control attribute allocation max count 1 unlimited J control attribute allocation incremental count 1 number of attributes will keep doubling on each allocation until it reaches max count 7 15 SJJOMJON Dely pPIM BuisIoADI Z Chapter 7 Table 7 1 TCP TLS Transport Properties over LAN or WAN NDDS Transport TCPv4 Property t Property Name prefix with dds transport TCPv4 tcp1 De
132. l use the RTI Data Distribution Ser vice defaults Route Types The tag registered type name within the input and output tags contains the registered type name of the stream The actual definition of that type can be set in the configuration file see Section 2 4 6 2 or it can be discovered by the connections see Section 2 4 6 3 Defining Types in the Configuration File To define and use a type in your XML configuration file 1 Define your type within the types tag This is one of the top level tags see Table 2 1 2 Register it in the connection s participant s where you will use it 3 Refer to it in the domain route s that will use it For example lt dds gt lt types gt lt struct name PointType gt lt struct gt lt types gt routing service name MyRoutingService 2 37 eoiues Buynoy I13 BuunByuod Z Chapter 2 2 4 6 3 2 38 domain route connection 1 registered type name Position type name PointType connection 1 participant 2 registered type name Position type name PointType participant 2 session topic route input participant 2 registered type name Position registered type name input output lt output gt lt topic_route gt lt session gt lt domain_route gt lt routing_service gt lt dds gt The type description is done using the RTI Data Distribution Service XML
133. lt topic_route name SquareSwitchCoord gt lt input participant 1 gt lt topic_name gt Square lt topic_name gt lt registered_type_name gt ShapeType lt registered_type_name gt lt input gt lt output gt lt topic_name gt Square lt topic_name gt lt registered_type_name gt ShapeType lt registered_type_name gt lt output gt lt transformation plugin_name transformationLib assign gt lt property gt lt value gt lt element gt name X name value Y value element element name Y name value X value element value property transformation topic route 2 42 2 4 XML Tags for Configuring RTI Routing Service To include a transformation in a route 1 Implement the transformation plugin API and generate a shared library See Chapter 4 Transforming Data with RTI Routing Service for more information 2 Register that library in the configuration file by creating lt transformation_plugin gt tag inside a lt transformation_library gt tag As noted in Table 2 1 lt transformation_library gt is a top level tag 3 Instantiate a transformation by creating a lt transformation gt tag inside a lt route gt or a lt topic_route gt tag Table 2 15 lists the tags allowed within a lt transformation gt tag For additional information about transformations see Chapter 4 Transforming Data with RTI Routing Service Table 2 15 Transfor
134. mation Tags a 2 4 7 Auto Routes The tag lt auto_route gt defines a set of potential routes with the same input and output type and the same input and output stream name A route can eventually be instanti ated when a new stream is discovered with a type name and a stream name that match the filters in the auto route When this happens a route is created but not necessarily ir Number Tags within Description of Tags transformation Allowed input type name Type name of the data samples this transformation receives Oor1 output type name Type name of the data samples this transformation creates Oor1 Sequence of name value string pairs that can be used to con figure certain parameters of the transformation For example lt property gt lt value gt lt property gt lt element gt 0 or 1 lt name gt scaling_factor lt name gt lt value gt 2 lt value gt lt element gt lt value gt lt property gt started see Section 2 4 6 4 with the configuration defined in the auto route tag 2 43 dIA1eg Buynoy La Guun amp yuo z Chapter 2 For example lt dds gt lt routing_service gt lt domain_route gt lt participant_1 gt lt domain_id gt 54 lt domain_id gt participant 1 connection 2 plugin name my adapter library jms connection 2 session auto route name AutoRoute1 gt dds input participant 1 gt allow topic name filte
135. max_event_delay sec DURATION_INFINITE_SEC max_event_delay nanosec DURATION_INFINITE_NSEC Oor1 monitoring Enables and configures remote monitoring for the session See Monitoring Section 2 4 4 and Chapter 6 Monitoring RTI Rout ing Service from a Remote Location Oor1 2 29 eolA1es Buynoy I134 Guun amp yuo z Chapter 2 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 DDS topic called Square and a JMS queue called Square lt dds gt lt routing_service gt lt domain_route gt lt participant_1 gt lt domain_id gt 54 lt domain_id gt participant 1 connection 2 plugin name my adapter library jms connection 2 session name Session1 route name DDSSquaresToJMSSquares dds input participant 1 gt topic name Square topic name registered type name ShapeType registered type name dds input output stream name Square topic name registered type name ShapeType registered type name lt output gt lt route gt lt session gt lt domain_route gt lt routing_service gt lt dds gt 2 30 2 4 XML Tags for Configuring RTI Routing Service DDS inputs and outputs within a route are defined using the XML tags dds input and dds output Input a
136. me route gt tt ereste J StreamReader lt input connection 1 gt lt property gt lt value gt 7 12 create_stream_writer lt element gt 13 create 75 Writer Nalue lt property gt linput output lt property gt N lt value gt lt element gt lt halue gt lt property gt lt output gt lt route gt IJ An Adapter object is created when the first domain route that refers to it is enabled L A Connection object is created when the domain route domain route that contain it is enabled 1 A Session object is created when the associated routing service session lt ses sion is enabled 8 11 SsioJdbpy 8 Chapter 8 8 2 2 8 12 J A route s StreamReader is created when the route is enabled and the creation mode condition associated with the input tag becomes true see Section 2 4 6 4 LJ A route s StreamWriter is created when the route is enabled and the creation mode condition associated with the output tag becomes true see Section 2 4 6 4 Stream Discovery A route cannot forward data until the type representations e g TypeCode associated with the input and output streams are available If a route refers to types that are not defined in the configuration file RTI Routing Service has to discover their type representation e g TypeCode before creating StreamReaders and Stre
137. ment lt name gt com rti socket port lt name gt lt value gt 16556 lt value gt lt element gt lt value gt lt property gt 1 As defined by the POSIX fnmatch API 1003 2 1992 section B 6 2 49 eolA1es Buynoy La BuunGByuod z Chapter 2 Table 2 19 DDS Input and Output Tags for the auto topic route and auto route Tags Tags within Tags within auto topic route auto topic route Number input and output and Description of Tags auto route auto route Allowed dds input dds output The topic routes are created with this configu uci modes ration See Creation Modes Controlling Oorl when StreamReaders and StreamWriters are Created Section 2 4 6 4 The topic routes are created with a SQL con tent filter topic with this expression lt auto_topic_route gt lt input gt lt content_filter gt lt content_filter gt N A lt expression gt Oorl x amp gt 100 lt expression gt lt content_filter gt lt input gt lt auto_topic_route gt The topic routes are created with this configu ration The contents of this tag are specified in the same manner as for an RTI Data Distribution lt datareader_qos gt lt datawriter_qos gt Service QoS profile file see Chapter 15 in the 0 or 1 RTI Data Distribution Service User s Manual If the tag is not defined RTI Routing Service will use the RTI Data Distribution Service defaults
138. munication within a Single LAN parent classid NDDS TRANSPORT CLASSID TCPV4 LAN parent classid NDDS TRANSPORT CLASSID TCPV4 LAN ipar TCPv4T ransport TCPv4 Tra sport IP address 192 168 1 11 IP address 192 168 1 12 server bind port 7400 server bind port 7400 Initial Peers 192 168 1 11 7400 Initial Peers 192 168 1 12 7400 Symmetric Communication Across NATs In NAT communication scenarios each one of the LANs has a private IP address space The communication with other LANs is done through NAT routers that translate pri vate IP addresses and ports into public IP addresses and ports In symmetric communication scenarios any instance of RTI Routing Service can initiate TCP connections with other routing services Figure 7 3 shows how to configure the TCP transport in this scenario Notice that initial peers refer to the public address of the RTI Routing Service instances and not the LAN address In addition the transport associated with an RTI Routing Ser vice instance will have to be configured with its public address so that this information can be propagated as part of the discovery process Because the public address and port of the RTI Routing Service instances must be known before the communication is established the NAT Routers will have to be configured statically to translate forward the private server bind port into a public port This process is known
139. n the route is enabled and the creation mode condi tion associated with the input tag becomes true see Section 2 4 6 4 One of the parameters received by the create stream reader operation is the StreamReaderListener The StreamReaderListener interface provides a callback which will be used by the adapter to notify RTI Routing Service of the existence of new data create stream reader Implementation of this API is required only when there are routes using the adapter to receive data Deletes a previously created StreamReader This method is called when the route is disabled or when the creation mode delete_ condition associated with the lt input gt tag becomes false see Section 2 4 6 4 stream_reader Implementation of this API is required only when there are routes using the adapter to receive data Creates a new StreamWriter within a routing service route This method is called when the route is enabled and the creation mode condi create tion associated with the lt output gt tag becomes true see Section 2 4 6 4 stream_writer Implementation of this API is required only when there are routes using the adapter to produce data Deletes a previously created StreamWriter This method is called when the route is disabled or when the creation mode delete_ condition associated with the lt output gt tag becomes false see Section 2 4 6 4 stream_writer Impleme
140. n they were made available in the input domain Table 2 timestamp This option may not be applicable in some adapter s Dord implementations where the concept of timestamp is not supported Default false Enables and configures remote monitoring for the auto lt entity_monitoring gt route See Monitoring Section 2 4 4 and Chapter 6 Moni 0 or 1 toring RTI Routing Service from a Remote Location 17 Auto topic Route Tags Tag within p auto topic route DESSHPHON i aBn Allowed input Defines the auto topic route s input topic See Auto Routes Section 2 4 7 1 required output Defines the auto topic route s output topic See Auto Routes Section 2 4 7 1 required 2 46 publish with original info The topic routes are created with this configuration When this flag is set to true if you have N topic routes for the same topic in different routers or in the same one each sample that was written from a DataWriter in the input domain will be routed N times but DataReaders on the output domain will only see one Default false Oor1 2 4 XML Tags for Configuring RTI Routing Service Table 2 17 Auto topic Route Tags Table 2 Number Tag within Descripti fT lt auto_topic_route gt escription e m E Allowed The topic routes are created with this configuration publish with original When this tag
141. n transformation RTI RoutingServiceEnvironment env The transformation parameter corresponds to the value returned by the function create transformation transform This function is called in a route to transform a sequence of input data samples into a sequence of output data samples typedef void RTI RoutingServiceTransformation transform RTI RoutingServiceTransformation transformation RTI RoutingServiceSample out sample lst RTI RoutingServiceSampleInfo out info lst unsigned int out count RTI RoutingServiceSample in sample lst RTI RoutingServiceSampleInfo in info lst 4 7 ood 6uiuuojsunij y Chapter 4 4 8 unsigned int in count RTI RoutingServiceEnvironment env When the routing service is done using the output samples it will return the loan to the transformation by calling the return loan operation The transformation parameter corresponds to the value returned by the function create transformation return loan Indicates to the transformation that the routing service is done accessing the sequence of data samples obtained by an earlier invocation of transform typedef void RTI RoutingServiceTransformation return loan RTI RoutingServiceTransformation transformation RTI RoutingServiceSample sample 1st RTI RoutingServiceSampleInfo info lst unsigned int count RTI RoutingServiceEnvironment env The transformation parameter corresponds to the v
142. nd one minute truec one minute five minute false five minute one hour true one hour up time false up time historical statistics If a window is not present inside the tag historical statistics it is considered disabled If this tag is not defined historical statistics are inherited from the general monitoring settings 2 4 5 Session A session 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 2 26 2 4 XML Tags for Configuring RTI Routing Service For example dds REA name MyRoutingService domain Gutes session name Session1 gt ecules name Routel gt Emcee lt sessions lt donain routes grouting services ej dss Sessions that bridge DDS domains will create a Publisher and a Subscriber in the partic ipants participant_1 or participant_2 associated with the DDS domains Table 2 9 lists the tags allowed within a lt session gt tag Table 2 9 Session Tags Number Tags within Descripti fT eseasi ns escription of Tags Allowed Pm Defines a general route based on type and stream filters See ee AUO KOUTE Auto Routes Section 2 4 7 P Defines a general DDS topic route based on type and topic fil lt a
143. nd outputs from other data domains are defined using the tags input and output A topic route is a special kind of route that defines a map ping between an input topic on one DDS domain and an output topic on other DDS domain For example the following topic route will subscribe to topic Square on domain 54 and will republish those samples on domain 55 as samples of topic Circle dds routing service domain route participant 1 domain id 54 domain id participant 1 participant 2 domain id 55 domain id participant 2 session name Sessioni gt topic route name SquaresToCircles gt input participant 1 gt topic name Square topic name registered type name ShapeType registered type name lt input gt lt output gt lt topic_name gt Circle lt topic_name gt lt registered_type_name gt ShapeType lt registered_type_name gt Si mutus cep te routes lt session gt siama in routes s rout ing Services dds 2 3 eolA1es Buynoy I134 Guun amp yuo z Chapter 2 In the previous example the direction of the mapping is defined by the attribute partic ipant of the tag input Therefore to change the above example to read Squares from domain 55 and write Circles on domain 54 we would use input participant 2 There is an equivalent attribute for non DDS inputs called connection Inputs and outputs in a route or topic route h
144. ndently using the entity monitoring tag For example dds routing service name MonitoringExample monitoring domain id 55 domain id status publication period sec l sec status publication period statistics sampling period lt sec gt 1 lt sec gt lt nanosec gt 0 lt nanosec gt lt statistics_sampling_period gt lt monitoring gt lt domain_route gt entity monitoring status publication period lt sec gt 4 lt sec gt lt status_publication_period gt lt entity_monitoring gt lt domain_route gt lt routing_service gt lt dds gt 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 pos Number Tags within Descripti aum escription of Tags entity monitoring Allowed Enables disables remote monitoring for a given entity If general monitoring is disabled this value is ignored enabled Oor1 Default value true 2 24 2 4 XML Tags for Configuring RTI Routing Service Table 2 8 Entity Monitoring Tags ss Number Tags within ae lt entity_monitoring gt Descriptad a Tipe y 8 Allowed Specifies the frequency at which the status of an entity is pub JN lished eo For example 9 lt status_publication_period gt bi B status publication period lt sec gt 3 lt sec gt Oorl
145. nes a single threaded context in which data is routed session aR according to specified routes See Session Section 2 4 5 1 or more required Enables and configures remote monitoring for the domain enti itori que entity monitor gos route See Monitoring Section 2 4 4 Oor1 2 14 2 4 XML Tags for Configuring RTI Routing Service Table 2 4 lists the tags allowed within connection 1 and connection 2 tags Table 2 4 Connection Tags Tags within connection 1 2 Description Number of Tags Allowed registered type Registers a type name and associates it with a type representa tion When you define a type in the configuration file with the types tag you have to register the type in order to use it in routes See Route Types Section 2 4 6 1 0 or more lt property gt Sequence of name value string pairs that can be used to config ure the parameters of the connection For example property value element lt name gt jms connection username lt name gt lt value gt myusername lt value gt lt element gt lt value gt lt property gt Oor1 2 15 eolA1es Buynoy I134 Guun amp yuo z Chapter 2 Table 2 5 lists the tags allowed within participant 1 and participant 2 tags Table 2 5 Participant Tags Tags within participant 1 2 Description Number of Tags Allowed
146. ng the lt property gt tag within lt connection_x gt For the SimpleFileAdapter example there is one property called directory that is used to specify the directory con taining the files to read write For example connection 1 plugin_name adapters simple_file gt registered type name TextLine type name TextLine property value element lt name gt directory lt name gt lt value gt tmp SimpleFileAdapter input lt value gt lt element gt lt value gt lt property gt connection 1 Connection objects are factories for Session StreamReader and StreamWriter objects In the next sections you will implement StreamReader and StreamWriters Session objects are not used in this example Implementing the StreamReader Class A StreamReader provides a way to read data samples of a specific type from a data domain In the configuration file StreamReaders are associated with the tag input within route or auto route see Section 2 4 6 The StreamReaders created by the SimpleFileAdapter connections read text files from the connection directory The data samples provided to RTI Routing Service using the read operation are Dynam icData with the following IDL type 8 61 siojdopy 8 Chapter 8 8 62 struct TextLine string lt 1024 gt value bi When a SimpleFileAdapter StreamReader is created the name of the file is the input stream name with a txt extension The frequency
147. ngServiceStreamReader ReadFcn Stream reader read RTI RoutingServiceStreamReader ReturnLoanFcn Stream reader return loan RTI RoutingServiceAdapterEntity UpdateFcn stream reader update Stream Writer API RTI RoutingServiceStreamWriter WriteFcn stream writer write RTI RoutingServiceAdapterEntity UpdateFcn stream writer update void user object The adapter plugin instance created by the entry point function must be initialized using the macro RTI RoutingServiceAdapterPlugin initialize that is part of the adapter API For example struct RTI RoutingServiceAdapterPlugin MyAdapterPlugin create const struct RTI RoutingServiceProperties properties RTI RoutingServiceEnvironment env struct RTI RoutingServiceAdapterPlugin adapter NULL struct RTI RoutingServiceVersion version 1 0 0 0 adapter calloc 1 sizeof struct RTI RoutingServiceAdapterPlugin if adapter NULL RTI_RoutingServiceEnvironment_set_error env Memory allocation error return NULL 8 17 siojdopy 8 Chapter 8 8 3 2 1 8 3 2 2 RTI RoutingServiceAdapterPlugin initialize adapter adapter gt plugin_version version Assign the function pointers EY Environment The last parameter of each adapter API is the environment RTI RoutingServiceEnvironment This parameter is used to get information about the RTI Routing Service execution such as the version or the verbosity The environmen
148. nistration tag See the RTI Routing Service User s Manual for information on configuring remote access Default remote administration is not enabled unless it is enabled from the XML file remoteMonitoringDomainId ID Enables remote monitoring and sets the domain ID for status publication When remote monitoring is enabled RTI 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 The QoS values for these entities are described in the RTI Rout ing Service User s Manual This option overwrites the value of the tag domain id within a monitoring tag See the RTI Routing Service User s Manual for information on configuring remote monitoring Default remote monitoring is not enabled unless it is enabled from the XML file 3 2 Stopping RTI Routing Service Table 3 1 RTI Routing Service Command line Options Option Description sleep lt seconds gt Sleeps for x seconds before executing the next command This is useful when issuing commands from a command file see cmdName stopAfter sec Stops the service after the specified number of seconds use42eAlignment Enables compatibility with RTI Data Distribution Service 4 2e This option should be used when compatibility with 4 2e is required and the topic data t
149. nnection configuration com rti routingservice adapter DiscoveryConnection The DiscoveryConnection interface defines methods to get the discovery StreamReaders see Section 8 2 2 copy delete TypeRepresentations com rti routingservice adapter Session Required The Session interface defines methods to update the Session configuration 8 51 slojdopy 8 Chapter 8 Table 8 10 Java Adapter API Interfaces Interface Description Required for input adapters The StreamReader interface defines methods to com rti routingservice adapter StreamReader read samples return the loan on the read samples update the StreamReader configuration com rti routingservice adapter StreamWriter Required for output adapters The StreamWriter interface defines methods to write samples update the StreamWriter configuration 8 3 5 1 8 3 5 2 8 3 5 3 8 52 Adapter Entry Point Every Java adapter must create an Adapter class that implements the com rti routing service adapter Adapter interface Adapter classes are registered with RTI Routing Service using the tag class name within java adapter plugin see Section 8 1 When RTI Routing Service creates a new adapter object it will look for the following con structor MyAdapter java utils Properties properties If the constructor does not exist RTI Routing Service will use the default constructor without ar
150. ns for more information To enable TLS ca file or ca path is required both may be specified at least one is required tls verify verify depth Maximum certificate chain length for verification tls verify crl file Name of the file containing the Certificate Revocation List File should be in PEM format tls cipher cipher list List of available TLS ciphers See the OpenSSL manual page for SSL set cipher list for more information on the format of this string 7 2 Configuring the TCP Transport Table 7 1 TCP TLS Transport Properties over LAN or WAN NDDS Transport TCPv4 Property t Property Name prefix with NE dds transport TCPv4 Description tcp1 List of available Diffie Hellman DH key files For example foo pem 512 bar pem 256 means tls cipher dh param files 0 file foo pem dh param files dh param files 0 bits 512 dh param files 1 file bar pem dh param files 1 bits 256 tls cipher engine id String ID of OpenSSL cipher engine to request tls identity certificate_chain A string containing an identifying certificate chain in PEM format An identifying certificate is required for secure communication The string must be sorted starting with the certificate to the highest level root CA Either certificate_chain or certificate_chain_file is required You must set exactly one of these Do not set both of them this would produce a config
151. ntation of this API is required only when there are routes using the adapter to produce data Returns a StreamReader that is used by RTI Routing Service to discover output streams An output stream is a stream to which StreamWriters can write data Disposed scenarios where an output stream disappears are also notified using get_output_ the discovery StreamReader stream_discovery_ adei For additional information see Stream Discovery Section 8 2 2 Implementation of this API is optional However if none of the adapters in a domain route implement the discovery API the routes types must be declared in the configuration file 8 2 Adapter API And Entity Model Table 8 4 Connection Operations Operation Description get input stream discovery reader Returns a StreamReader that is used by RTI Routing Service to discover input streams An input stream is a stream from which a StreamReader can read data Disposed scenarios where an input stream disappears are also notified using the discovery StreamReader For additional information see Stream Discovery Section 8 2 2 Implementation of this API is optional However if none of the adapters in a domain route implement the discovery API the routes types must be declared in the configuration file Copies a type representation object RoutingServiceTypeRepresentation The format of the type representation is given by the representation k
152. ntities 1 RTI Routing Service itself routing service 2 Domain Route domain route 3 Session session 4 Route route and topic route 5 Topic Route auto route and auto topic route For each of the above kinds of entities RTI Routing Service creates two topics 1 rti routing service monitoring tag data describes the entity s configuration M rti routing service monitoring tag status set describes the entity s opera tional status With the corresponding types _ RTI RoutingService Monitoring lt tag gt Data 6 1 UOIJD20 eJowWeY D WOI GuuojIuo N 9 Chapter 6 6 1 6 2 6 2 1 RTI RoutingService Monitoring lt tag gt StatusSet Where tag is one of the following entity kind tags routing service domain route session route or auto route Enabling Remote Monitoring By default remote monitoring is disabled in RTI Routing Service for security and perfor mance reasons To enable remote monitoring you can use the monitoring tag see Section 2 4 4 or the remoteMonitoringDomainId command line parameter which enables remote monitoring and sets the domain ID for data publication For more information about the command line options see Section 3 1 in the Getting Started Guide When remote monitoring is enabled RTI Routing Service creates L 1 DomainParticipant J 1 Publisher 1 5 DataWriters for publishing configuration data one for each kind of entit
153. o World 10 4 In the adapter project directory create an RTI Routing Service XML configuration file called simple file adapter xml with the following content Replace the value of the directory property under both connections with the location of the input and output directories Replace the content of the dll tag under adapter plugin with the location of the release version of the SimpleFileAdapter shared library lt xml version 1 0 gt lt dds gt lt adapter_library name adapters gt adapter plugin name simple_file gt dll c adapters SimpleFileAdapter Release SimpleFileAdapter dll dll create function SimpleFileAdapter create create function adapter plugin adapter library types struct name TextLine gt member name value type string stringMaxLength 2048 gt struct types routing service name file to file domain route name domain_route gt connection 1 plugin name adapters simple file registered type name TextLine type name TextLine property value 1 Your directory may be different if you did not use the default locations 8 46 8 3 Creating New Adapters element lt name gt directory lt name gt lt value gt c adapters SimpleFileAdapter input lt value gt lt element gt lt value gt lt property gt lt connection_1 gt lt connection_2 plugin_name adapters simple_file gt registered ty
154. o start routing data between input and output streams However data routing will not start until the StreamWriter and StreamReader associated with a route are created see Section 2 4 6 4 for additional information disable disable target routing service entity name The disable command disables a routing service entity by destroying its sub entities and its corresponding DDS objects l Routing service When a routing service is disabled all of its domain routes are destroyed You don t need to specify the entity name to disable a routing service J Domain route When a domain route is disabled all its routes topic routes auto routes and auto topic routes are destroyed as well as both Connections DomainParticipants for DDS All the session threads are stopped and their cor responding adapter sessions Publisher and Subscriber for DDS are deleted too I Route topic route auto route and auto topic route When a route topic route auto route or auto topic route is disabled its StreamReaders and StreamWriters are destroyed so data will no longer be routed update update target routing service lt entity_name gt xml url assignment expr remote local The update command changes the configuration of a specific entity Table 5 1 on page 5 6 shows the parameters that can be changed for each entity If you try to change an immutable parameter in an entity that is enabled you will receive an error messag
155. o use tlsv4 lan or tlsv4 wan in the initial peers list as the prefix for all destination addresses To see the differences between a WAN scenario and the same scenario with TLS enabled you can compare the two example configuration files I shapes tcp transport xml 1 shapes tcp transport tls xml SJJOMJON Dolly OpIM Buisi1eADIJJ Z Chapter 7 7 2 7 2 1 7 6 Configuring the TCP Transport The TCP transport is distributed as a shared library in lt RTI Routing Service installa tion directory gt bin lt architecture gt The library is called nddstransporttcp dll on Win dows and libnddstransporttcp so on UNIX based systems For an example on how to use and configure the TCP transport with RTI Routing Service see Example 8 Using the TCP Transport with RTI Routing Service Section 4 8 in the Getting Started Guide As seen in the example you can configure the properties of the transport in the XML configuration file using the appropriate name value pairs in the DomainParticipant s PropertyQoSPolicy This will cause RTI Routing Service to dynamically load the TCP transport library at run time and then implicitly create and register the transport plugin with RTI Data Distribution Service TCP Transport Initial Peers With the TCP transport the addresses of the initial peers NDDS_DISCOVERY_PEERS that will be contacted during the discovery process have the following format For WAN communication tcpv4_wan lt
156. oad the plugin If not change the prefix to match the string used with dds transport load plugins SJJOMJON DOJV pPIM BuisioADI Z Chapter 7 Chapter 8 Extending RTI Routing Service with Adapters As described in Section 2 4 8 adapters are pluggable components that allow RTI Routing Service to consume and produce data for different data domains e g DDS JMS Socket etc By default RTI Routing Service is distributed with a built in DDS adapter Any other adapter plugins must be provided as shared libraries or Java classes and registered within the adapter library tag The figure to the right describes the RTI Routing Service adapter architec ture Input adapters are used to collect data samples from different data domains such as DDS or JMS The input samples are pro cessed by the RTI Routing Service engine and are passed along to custom transformations if they are defined Finally the transformed data is pro vided to the output adapters Routing S Input Adapters 2 2 2 S x o The adapter plugin API is used to create new adapters it is supported in C and Java 8 1 Chapter 8 The rest of this chapter describes 1 Adapter Usage and Configuration Section 8 1 J Adapter API And Entity Model Section 8 2 I Creating New Adapters Section 8 3 8 1 Adapter Usage and Configuration Adapter plugins must be registered within an adapter library in the XML configuration f
157. on Description The StreamReader API is required only when the adapter is used to receive data Otherwise it is optional update Updates the configuration of a StreamReader providing a new set of properties This method is called after the update command is received by the routing ser vice route containing the StreamReader see Section 5 2 5 Implementation of this API is optional read Reads a collection of data samples and sample infos from the StreamReader When RTI Routing Service is done using the samples it will return the loan to the StreamReader by calling return loan Implementation of this API is required if the adapter is used to receive data return loan Returns the loan on the read samples and infos RTI Routing Service calls this method to indicate that it is done accessing the col lection of data samples and sample infos obtained by an earlier invocation to read Implementation of this API is required if the adapter is used to receive data Table8 7 StreamWriter Operations Description The StreamWriter API is only required when the adapter is used Operation to produce data Otherwise it is optional Updates the configuration of a StreamWriter providing a new set of properties nds This method is called after the update command is received by the routing ser P vice route containing the StreamWriter see Section 5 2 5 Implementation of this API is optional Writes a collect
158. onfiguration Sec tion 2 2 The XML code received must represent a valid routing service configuration file The name of the routing service tag to load is identified with cfg name unload unload target routing service The unload command unloads the current configuration that the target routing service is using so you can change it with a subsequent load command The target routing service must be disabled for this command to succeed enable enable target routing service entity name The enable command enables an entity that has been disabled or marked as enabled false in the configuration file This command can be used to enable the following entities Routing service When a routing service is enabled it uses the currently loaded configuration and starts You don t need to specify the entity name to enable a routing service 5 2 Remote Commands 5 2 4 5 2 5 IJ Domain route When a domain route is enabled it creates the DDS participants routes topic routes auto routes and auto topic routes that it contains The routes topic routes auto routes and auto topic routes will be created enabled or disabled depending on their current configuration Enabling a domain route is required to start routing data from the input domain to the output domain Route topic route auto route and auto topic route Enabling a route topic route auto route or auto topic route is a necessary condition t
159. ood metric to monitor the health and perfor mance of transformations 6 28 Chapter 7 Traversing Wide Area Networks Many systems today already rely on 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 RTI Routing Service you can scale DDS real time publish subscribe data distribution beyond the current local networks and make it available throughout a WAN Out of the box RTI Routing Service only uses UDPv4 and Shared Memory transports to communicate with other RTI Routing Services and DDS applications This configuration is appropriate for systems running within a single LAN However the usage of UDPv4 introduces several problems when we try to communicate DDS applications running in different LANs L UDPv4 traffic is usually filtered out by the LAN firewalls for security reasons 1 Forwarded ports are usually TCP ports IJ Each LAN may run in its own private IP address space and use NAT Network Address Translation to communicate with other networks To overcome these three issues RTI Routing Service is distributed with a TCP transport that is NAT friendly The transport can be configured via XML using the Property QosPolicy of the RTI Routing Service s participants Figure 7 1 shows a typical scenario where two RTI Routing Services are used to bridge two DDS applications running in two different LANs
160. ow Help AB A 7 GI DIEM HL mo ae 8 z9 D8gmugRS5 WL x Solution Explorer SimpleFile 4 amp El og Solution SimpleFileAdapter 1 proje EA SimpleFileAdapter Header Files Resource Files E Source Files SimpleFileAdapter c include lt stdio h gt _ include lt string h gt ifdef RTI WIN32 L include lt process h gt else E include lt pthread h gt endif SimpleFileAdapter c j Global Scope X qt m e n n A n B RN A amp B AAA B n n AAA n A ATTA AAT AT Simple File Ada d NCRUNCRCNCRCRCRCRCHCRCRCECRCRCRCRCHCRCRCRCACRCHCA CA CA CA A EST 8 Build the SimpleFileAdapter project and verify that there are no errors 8 3 3 3 Creating an Adapter makefile Only for UNIX based systems In this section you will create a makefile to generate and compile the adapter shared library 1 The makefile that you will generate is intended to be used with the GNU distri bution of the make utility On modern Linux systems the make binary typically is GNU make On other systems GNU make is called gmake The instructions below use gmake Make sure that the GNU make binary is on your path before continuing 8 25 siojdopy 8 Chapter 8 8 26 2 Create a directory that will contain the adapter makefile and implementation The rest of this section assumes that opt adapters simplefile is the adapter directory
161. pe name TextLine type_name TextLine gt lt property gt lt value gt lt element gt lt name gt directory lt name gt lt value gt c adapters SimpleFileAdapter output lt value gt lt element gt lt value gt lt property gt lt connection_2 gt lt session name session gt lt route name route gt lt input connection 1 gt stream name HelloWorld stream name registered type name TextLine registered type name input output stream name HelloWorld stream name registered type name TextLine registered type name lt property gt lt value gt lt element gt lt name gt print_to_stdout lt name gt lt value gt 1 lt value gt lt element gt lt value gt lt property gt lt output gt lt route gt lt session gt lt domain_route gt lt routing_service gt lt dds gt 5 Start RTI Routing Service by entering the following in a command shell 8 47 siojdopy 8 Chapter 8 On UNIX based systems gt cd SimpleFileAdapter project directory gt SROUTINGSERVICEHOME scripts rtiroutingservice cfgFile simple file adapter xml cfgName file to file On Windows systems gt cd SimpleFileAdapter project directory gt SROUTINGSERVICEHOME S scripts rtiroutingservice cfgFile simple file adapter xml cfgName file to file 6 On the screen you will see RTI Routing Service 2 0 1 started with name file to file Hello Wo
162. property properties print to stdout if printToStdoutStr NULL writer gt printToStdout atoi printToStdoutStr else writer gt printToStdout 0 return writer The value of the RTI RoutingServiceAdapterPlugin structure created in SimpleFileAdapter_create must be updated to contain the StreamWriter functions adapter gt connection_create_stream_writer SimpleFileAdapterConnection_create_stream_writer adapter gt connection_delete_stream_writer SimpleFileAdapterConnection_delete_stream_writer adapter gt stream_writer_write SimpleFileAdapterStreamWriter_write Running the SimpleFileAdapter This section describes the steps required to use and run the SimpleFileAdapter with RTI Routing Service You will create a configuration file with a single route that reads a Hel loWorld text file from an input directory and saves it into an output directory 1 If you have not done it yet compile and build the SimpleFileAdapter 2 Under the adapter project directory c adapters SimpleFileAdapter on Win dows systems opt adapters simplefile on UNIX based systems create two directories called input and output 8 45 slojdopy 8 Chapter 8 3 In the input directory create a file called HelloWorld txt with the following con tent Hello World 1 Hello World 2 Hello World 3 Hello World 4 Hello World 5 Hello World 6 Hello World 7 Hello World 8 Hello World 9 Hell
163. pter public class SimpleFileAdapter implements Adapter String verbosity Entry point to the adapter Sf public SimpleFileAdapter Properties props verbosity props getProperty rti routingservice verbosity if verbosity equals debug System out println CREATE getClass getName 1 c adapters SimpleFileAdapter for Windows systems or opt adapters simplefile for UNIX based systems 8 3 Creating New Adapters wif public Connection createConnection String routingServiceName String routingServiceGroupName StreamReaderListener inputStreamDiscoveryListener StreamReaderListener outputStreamDiscoveryListener Properties properties throws AdapterException if verbosity equals debug System out println CALL getClass getName createConnection return new SimpleFileAdapterConnection properties verbosity J public void deleteConnection Connection connection throws AdapterException if verbosity equals debug System out println CALL getClass getName deleteConnection Returns the adapter version Ey public Version getVersion return new Version 1 0 0 0 To create a SimpleFileAdapter object RTI Routing Service will use the constructor Sim pleFileAdapter Properties props The props parameter is used to configure the adapter object Some of the values can be set from the XML configuration file using t
164. pter infrastructure StreamInfo public class SimpleFileAdapterStreamReader implements StreamReader private String verbosity private int readPeriod private String fileName null 1 c adapters SimpleFileAdapter for Windows systems or opt adapters simplefile for UNIX based systems 8 63 siojdbpy 8 Chapter 8 8 64 private BufferedReader fileReader null private NotificationThread notificationThread null private DynamicData dynamicData null uU private void parseProperties Properties properties String readPeriodStr readPeriodStr properties getProperty read period if readPeriodStr null readPeriod 1000 else readPeriod new Integer readPeriodStr intValue Zy SimpleFileAdapterStreamReader StreamReaderl Listener listener StreamInfo s treamInfo Properties properties String direc tory String verbosity throws AdapterException this verbosi ty verbosity parseProperties properties fileName s try treamInfo getStreamName txt fileReader new BufferedReader new FileReader new File directory fileName catch IOException e throw new AdapterException 0 error opening fileName dynamicData new DynamicData TypeCode streamInfo getTypeInfo getTypeRepresentation DynamicData PROPERTY DEFAULT notification Thread new NotificationThread this listener fileReader
165. pters 8 3 6 3 Creating a Build Script for Windows Systems In this section you will create a script to compile the Java adapter 1 Create a directory that will contain the build script and the adapter implementa tion The rest of this section assumes that you will use c NadaptersNSimpleFile Adapter as the adapter directory 2 In c adapters SimpleFileAdapter create a file called build cmd with the fol lowing content ECHO OFF REM HEHHEHE HEHE HE HEE HEHE E HE HE HE HE FE E HE HE FE FE HE FE FE FE AE FE HE FE FE AE HE AE HE E FE HE FE TE FE FE E FE HE TE HE FE TE AE EEE SHEE E BE REM RTI Routing Service Simple File Adapter REM HEHEHEHEHE HE E BERE HE FE HE HE FE TE HE HE HE E FE HE HE FE HE AE FE HE FE FE AE HE FE FE E FE HE FE FE FE FE E FE HE TE HE FE TE AE TE HE E E H E E E E H E E H SETLOCAL enabledelayedexpansion REM Get rid of quotes SET ROUTINGSERVICEHOME_NQ ROUTINGSERVICEHOME REM Path to Java SET JAVAC javac exe SET JAR jar exe REM Path to RTI Routing Service Adapter API SET ADAPTER_CLASSPATH ROUTINGSERVICEHOME_NQ class rtirs adapter jar RI S M Path to RTI DDS Java API T DDS_CLASSPATH SROUTINGSERVICEHOME_NQ class nddsjava jar I REM Ensure the objs directory exists IF NOT EXIST class MD class ECHO Building all the sources in routingservice into class directory FOR R routingservice F IN java DO JAVAC d class source pa
166. put participant will not trigger the creation of routes This filter is configured using the tag lt allow_registered_type_name_filter gt inside lt auto_topic_route gt lt input gt lt auto_route gt lt dds_input gt or lt auto_route gt lt input gt out put allow_stream_name_ filter Topics that do not pass this filter in the output participant will not trigger the creation of routes This filter is configured using the tag lt allow_topic_name_filter gt inside lt auto_topic_route gt lt output gt or inside lt auto_route gt lt dds_output gt or the tag lt allow_stream_name_filter gt inside auto route output output allow registered type name filter Topics with types that do not pass this filter in the output partici pant will not trigger the creation of routes This filter is configured using the tag allow registered type name filter inside auto topic route output auto route dds ioutput or auto route out put input deny stream name filter Topics that pass this filter in the input participant will not trigger the creation of routes This filter is configured using the tag deny topic name filter inside auto topic route input or inside auto route dds input or the tag deny stream name filter inside auto route input input deny registered type name filter Topics with types that pass this filter in
167. r allow topic name filter allow registered type name filter ShapeType allow registered type name filter lt input gt lt output gt lt allow_stream_name_filter gt A lt allow_stream_name_filter gt allow registered type name filter B allow registered type name filter output auto topic route lt session gt lt domain_route gt lt routing_service gt lt dds gt 2 44 2 4 XML Tags for Configuring RTI Routing Service The previous auto route will lead to the creation of a route every time any topic of type ShapeType is discovered on the DDS domain or a JMS queue topic starting with A with a type starting with B is discovered on the output JMS connection For example discovering the topic Triangle of ShapeType will trigger the creation of a topic route that routes triangles from the DDS domain to the JMS domain Discover ing a topic Atopic of type Btype on the JMS domain will trigger the creation of a topic route that routes Atopic from the DDS domain to the JMS domain DDS inputs and outputs within an auto route are defined using the XML tags dds input and dds output Input and outputs from other data domains are defined using the tags input and output An auto topic route is a special kind of route that defines a mapping between two DDS domains Please see the following tables for more information on allowable tags I Table 2 16 on pag
168. r thi par fil ing directory ing verbosity throws AdapterException s verbosity verbosity seProperties properties eName streamInfo getStreamName txt 8 69 siojdopy 9 Chapter 8 8 70 try fileWriter new BufferedWriter new FileWriter new File directory fileName catch IOException e throw new AdapterException 0 error opening fileName void close throws AdapterException try if fileWriter null fileWriter close H catch IOException e throw new AdapterException 0 error closing fileName public int write List Object sampleList List Object infoList throws AdapterException String line ListIterator iterator sampleList listIterator DynamicData dynamicData null if verbosity equals debug System out println CALL getClass getName write try while iterator hasNext dynamicData DynamicData iterator next line dynamicData get_string value DynamicData MEMBER_ID_UNSPECIFIED fileWriter write line fileWriter newLine if printToStdout System out println line 8 3 Creating New Adapters catch IOException e throw new AdapterException 0 error writing to file fileName e catch Exception e throw new AdapterException 0 error writing e H return 0 f public void update Properties properties throws AdapterExcep
169. r Configuring RTI Routing Service Table 27 Monitoring tags pe sc ge Number of Tags within lt monitoring gt Description Tags Allowed Enables or disables the publication of statistics calcu lated within fixed time windows By default RTI Routing Service only publishes the statis tics corresponding to the window between two status publications By using this tag you can get the following additional windows LJ 5 seconds J 1 minute 5 minutes J 1 hour historical statistics M Up time since the entity was enabled Oor1 For example historical statistics five second true five second one minute true c one minute five minute false five minute one hour true c one hour up time false c up time historical statistics If a window is not present inside the tag historical statistics it is considered disabled Historical statistics can be overwritten on a per entity basis eolA1es Buynoy I13 BuunByuod Z 2 4 4 1 Monitoring Configuration Inheritance The monitoring configuration defined in routing service is inherited by all the enti ties defined inside the tag An entity can overwrite three elements of the monitoring configuration 1 The status publication period 1 The statistics sampling period LJ The historical statistics windows 2 23 Chapter 2 Each one of this three elements is inherited and can be overwritten indepe
170. r a snippet of XML that only refers to a specific entity this is further explained in Section 5 2 5 The remote local parameter is used with file URLs to indicate if the file is local to the shell local or local to the routing service remote If the file is local to the shell local the shell application will read it and will send it as a string URL If the file is local to the routing service remote the shell will send it as a file URL that will be read by the routing service The default value is remote If a relative path is specified the path will be relative to the working directory in which the routing service if remote is specified or shell if local is specified is running 5 3 uoypijsiulup v ejouiey G Chapter 5 5 2 1 5 2 2 5 2 3 l assignment expr can be used instead of xml url to modify single values in an entity configuration The assignment expression has the form fully qualified value name value For example update ShapeRouter DomainRoutel Sessionl SquareToCircles topic route input datareader qgos deadline period sec 3 update ShapeRouter DomainRoutel Sessionl SquareToCircles topic route input content filter expression x 30 load load target routing service cfg name xml url remote local The load command loads specific XML configuration code The target routing service must be disabled For more information see How to Load the XML C
171. rational 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 through put For more information about entity data and status see Chapter 6 Monitoring RTI Rout ing Service from a Remote Location 2 19 eoiues Buynoy I134 Guun amp yuo z Chapter 2 2 20 When remote monitoring is enabled RTI Routing Service will create one DomainPartici pant 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 config ure the QoS of these entities with the monitoring tag defined under routing service The general remote monitoring parameters specified using the monitoring tag in routing service except domain id participant qos publisher qos and datawriter qos can be overwritten on a per entity basis using the entity monitoring tag For example dds routing service monitoring domain id 55 domain id status publication period lt sec gt 1 lt sec gt lt status_publication_period gt lt monitoring gt lt domain_route gt lt entity_monitoring gt lt status_publication_period gt lt sec gt 4 lt sec gt lt status_publication_period gt lt entity_monitoring gt lt domain_route gt lt routing_service gt lt dds gt 2
172. reader gt sample 0 free reader return NULL sprintf file s s txt self gt directory stream_info gt stream_name reader gt fHandle fopen file r if reader gt fHandle NULL RTI_RoutingServiceEnvironment_set_error env Error opening s file free file DDS_DynamicData_delete reader gt sample 0 free reader return NULL free file Creates notification thread readPeriodStr RTI RoutingServiceProperties lookup property properties read period if readPeriodStr NULL readPeriod atoi readPeriodStr else readPeriod 1000 1 Sec 8 39 siojdopy 9 Chapter 8 reader gt readPeriod sec readPeriod 1000 reader readPeriod nanosec readPeriod 1000 1000000 reader run 1 reader gt listener listener ifdef RTI_WIN32 reader gt thread HANDLE _beginthread void cdecl void SimpleFileAdapterStreamReader run 0 void reader if reader thread error 1 else pthread attr init amp threadAttr pthread_attr_setdetachstate amp threadAttr PTHREAD CREATE JOINABLE error pthread create amp reader gt thread amp threadAttr SimpleFileAdapterStreamReader_run void reader pthread attr destroy amp threadAttr endif if error RTI_RoutingServiceEnvironment_set_error env Error creating notification thread DDS_DynamicData_delete reader gt sample 0 free reader fclose r
173. red delete connection Deletes a previously created connection Connection objects are deleted when the domain routes that contain them are disabled Implementation of this API is required getVersion Returns the Adapter s version This method is only available in Java In C the version of the adapter is set on a member called plugin version in the plugin structure RTI RoutingServiceAdapterPlugin see Section 8 3 2 The version of the adapter is only used for logging purposes Implementation of this API is required Table 8 4 Connection Operations Operation Description connection to string Returns the string representation of a connection for logging purposes Implementation of this API is optional If the API is not implemented RTI Rout ing Service will use the fully qualified name of the adapter plugin create session Creates a new session Connection session objects are created when the associated routing service ses sions are enabled Implementation of this API is optional delete session Deletes a previously created session Connection session objects are deleted when the routing service sessions that contain them are disabled Implementation of this API is optional siojdopy 8 Chapter 8 Table 8 4 Connection Operations Operation Description Creates a new StreamReader within a routing service route This method is called whe
174. rieve the value of the DurabilityQosPolicy associated with the route s DDS DataWriter To do that we would subscribe to the pub lication DDS builtin topic and we would look for a sample where the key member is 6 9 UOIJD20 6joUJe3 D WOI GuuojIuO N 9 Chapter 6 Table 6 4 RouteData 6 10 Field Name Key Description routing service name The routing service name assigned with appName domain route name V The domain route name session name V The session name name The route name which is configured using the name attribute in the route or topic route tag auto route name If the route is contained in an auto route this field contains the auto route name Otherwise the field is initialized with the empty string input output The configuration of the route s input as contained in the tag input or dds input inside route or topic route The configuration of the route s output as contained in the tag out put or dds output inside route or topic route input connection Index of the input connection or participant 1 or 2 The value of this field is used to determine whether the input of this route is the domain route s connection 1 participant 1 or the connec tion 2 participant 2 input stream name Input stream name The input stream name is configured using the tag topic name inside topic route input
175. riod of an entity must be smaller than its status publication period A small statistics sampling period provides more accu rate statistics at expense of increasing the memory consumption and decreasing perfor mance Status Information for the Routing Service The topic that publishes routing service status is called rti routing service monitoring routing service status set The IDL definition of the data type is struct RoutingServiceStatusSet String ENTITY NAME MAX LENGTH name key StatisticVariable cpu usage percentage StatisticVariable physical memory kb StatisticVariable total memory kb Table 6 6 describes the fields in the RoutingServiceStatusSet data type Table 6 6 RoutingServiceStatusSet Field Name Key Description Name of the routing service instance The name associated with the routing service instance can be assigned explicitly by using the appName command line parame ter If appName is not used the routing service tag name pro vided with cfgName is used If you use the identifyExecution command line parameter the host name and the process ID are appended to the name For example RTI_RoutingService_myhost_1234 name 4 Statistic variable that provides the percentage of CPU usage of the cpu usage percentage routing service process over different time windows This variable is only supported on Windows and Linux systems 6 21 UOIJD20 6jOoUJe3
176. ription Number of Tags Allowed lt jvm gt Configures the Java JVM used to load and run Java adapters such as the JMS Adapter For example lt jvm gt lt class_path gt lt element gt SocketAdapter jar lt element gt lt class_path gt lt options gt lt element gt Xms32m lt element gt lt element gt Xmx128m lt element gt lt options gt lt jvm gt The class path for the Java adapters can be set using either the lt class_path gt tag or by setting the CLASSPATH environment variable RTI Routing Service will always add lt RTI Routing Service executable location gt class rtiroutingser vicesdk jar and RTI Routing Service executable location gt class dds jar at the end of the user defined class path You can use the options tag to specify options for the JVM such as the initial and maximum Java heap sizes Oorl 2 11 eolA1es Buynoy I1 Guun amp yuo z Chapter 2 2 4 2 Domain Route A domain route defines a mapping between two data domains Data available in either of these data domain route 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 actu ally read and written is defined in specific routes I A domain route creates two connections known as registered type connection 1 and connection 2
177. rld 1 Hello World 2 Hello World 3 Hello World 4 Hello World 5 Hello World 6 Hello World 7 Hello World 8 Hello World 9 Hello World 10 7 Verify that a file called HelloWorld txt has been generated into the output direc tory The content of this file should de identical to the content of the same file in the input directory 8 3 4 Debugging C Adapters When you develop a custom adapter you will need to debug it and test it This section talks about the tools and APIs that you have available to debug and detect problems in RTI Routing Service adapters written in C The first debugging capability is provided by the RTI Routing Service SDK The adapter SDK provides a way to access the verbosity level of RTI Routing Service through the usage of the environment function RTI RoutingServiceEnvironment get verbosity It is highly recommendable that as part of the adapter implementation you instrument the code by adding status messages that will be printed with the INFO and DEBUG verbos ity levels This level of instrumentation will help you to capture run time information for troubleshooting The second debugging capability is provided by third party tools On a Windows sys tem you can debug the adapter shared libraries using Visual Studio On a UNIX based system you can use GDB the GNU Project debugger 8 48 8 3 Creating New Adapters 8 3 4 1 Debugging the Adapter with Visual Studio only for Windows Systems Let s see
178. roperty gt In this example the properties are used to define the field assignments The semantics associated with the transformation property value depends on the plugin implementation 4 3 ojoq Bulwiojsupl y Chapter 4 4 2 Transformations Distributed with RTI Routing Service RTI Routing Service provides a transformation that is able to map fields of the input type to fields of the output type using the property tag inside the transformation to provide this mapping For example dds transformation library name TransformationLib gt transformation plugin name Assignment gt dll rtirsassigntransf dll create function RTI RoutingServiceAssignTransformationPlugin create create function transformation plugin transformation library routing service name MyService domain route name MyDomainRoute session name MySession gt route name MyRoute gt transformation plugin name TransformationLib Assignment lt property gt lt value gt lt element gt lt name gt X lt name gt lt value gt Y lt value gt lt element gt lt element gt lt name gt Y lt name gt lt value gt X lt value gt lt element gt lt value gt lt property gt lt transformation gt lt route gt lt session gt lt domain_route gt 4 4 4 3 Creating New Transformations 4 3 routing service lt dds gt This transformation plug
179. rseProperties properties notificationThread setReadPeriod readPeriod Notification thread This thread will notify of data availability in the file class NotificationThread extends Thread private BufferedReader fileReader null private int notificationPeriod private boolean terminate private StreamReaderListener listener null private StreamReader streamReader null E NotificationThread StreamReader streamReader StreamReaderListener listener BufferedReader fileReader int notificationPeriod this listener listener this fileReader fileReader this notificationPeriod notificationPeriod this streamReader streamReader terminate false 8 3 Creating New Adapters 8 3 6 7 f public void run while terminate try Thread sleep notificationPeriod if fileReader ready listener onDataAvailable streamReader catch Exception e xf public void terminate terminate true EJ public void setReadPeriod int readPeriod notificationPeriod readPeriod Implementing the StreamWriter Class A StreamWriter provides a way to write samples of a specific type into a data domain In the configuration file StreamWriters are associated with the tag lt output gt within lt route gt or lt auto_route gt see Section 2 4 6 The SimpleFileAdapter StreamWriters create new files in the connection directory and store the lines
180. rsion const RTI RoutingServiceEnvironment self struct RTI RoutingServiceVersion version My First C Adapter This section shows how to create a simple C adapter on Windows and UNIX based sys tems It is not intended to give complete coverage of the entire adapter API but rather to introduce the adapter technology and provide the basic process for developing a C adapter The new Adapter will be a simple file adapter where the input adapter reads lines from a text file and the output adapter saves the provided lines to an output text file A more flexible and complex file adapter that is able to work with structured informa tion is provided under RTI Routing Service home gt adapters file The source code and projects that you will create in the next sections are provided in RTI Routing Service home gt adapters tutorial C Setting the Environment on the Development Machine There are a few things to take care of before you start developing the simple file adapter 1 Install RTI Data Distribution Service see the RTI Routing Service Release Notes for the compatible version of RTI Data Distribution Service The C adapter will use TypeCode as the type representation format and Dynam icData as the data representation format This will require linking against the RTI Data Distribution Service libraries and including the header files defining the TypeCode and DynamicData APIs For information on how to install RTI Data Distribut
181. rvice adapter Session import com rti routingservice adapter StreamReader import com rti routingservice adapter StreamReaderListener import com rti routingservice adapter StreamWriter import com rti routingservice adapter infrastructure AdapterException import com rti routingservice adapter infrastructure StreamInfo Simple file connection public class SimpleFileAdapterConnection implements Connection private String verbosity private String directory null Baa SimpleFileAdapterConnection Properties properties String verbosity throws AdapterException this verbosity verbosity 1 c adapters SimpleFileAdapter for Windows systems or opt adapters simplefile for UNIX based systems 8 3 Creating New Adapters directory properties getProperty directory if directory null throw new AdapterException 0 directory property is required public Session createSession Properties properties throws AdapterException We dont need a session for the simple file adapter but we cannot return null return new Session public void update Properties properties throws AdapterException sy public void deleteSession Session session throws AdapterException F public StreamReader createStreamReader Session session StreamInfo streamInfo Properties properties StreamReaderListener listener throws AdapterException if verbosity equals debug S
182. s Routing services in the same group will not communicate with each other The group name is assigned using the attribute group name in the routing service tag If the attribute is not defined the group name is automatically set to RTI RoutingService Host Name Process ID host name Name of the host where the routing service is running host id Identifies the host where the routing service instance is running app id Process task ID of the routing service instance Configuration Data for a Domain Route The topic that publishes domain route configuration data is called rti routing service monitoring domain route data The domain route data describes the configuration of the domain route and its connections but not its contained entities Each connection can be defined with two different types depending on if it is a DDS connection participant 1 or participant 2 or a generic connection using an adapter connection 1 or connection 2 The IDL definition of the data type RTI RoutingService Monitoring DomainRoute Data is struct DomainRouteParticipantData long domain_id BuiltinTopicKey t participant key hi struct DomainRouteAdapterConnectionData string lt E ENTITY NAME MAX LENGTH plugin name sequence Property MAX PROPERTIES property 6 2 Monitoring Configuration Data union DomainRouteConnectionData switch AdapterKind DDS ADAPTER KIND case R
183. s RTI ROUTING SERVICE GENERIC ADAPTER KIND if it is a DDS input topic route input or route dds input then the union discriminator is RII ROUTING SERVICE DDS ADAPTER KIND output adapter data Contains the configuration of the route s output that is specific to either the DDS adapter or a generic adapter When a generic output is defined lt route gt lt output gt then the union discriminator is RTI ROUTING SERVICE GENERIC ADAPTER KIND if itis a DDS output topic route output or route dds output then the union discriminator is RII ROUTING SERVICE DDS ADAPTER KIND input adapter data dds domain id DDS input only Domain ID of the input participant output adapter data dds domain id DDS output only Domain ID of the output participant input adapter data dds datareader key DDS input only Unique identifier for the DDS DataReader The value of this field is meaningful only when the state is RII ROUTING SERVICE CREATED AND ENABLED output dapter data dds datawriter key DDS output only Unique identifier for the DDS DataWriter The value of this field is only meaningful when datawriter state is RII ROUTING SERVICE CREATED AND ENABLED input adapter data dds content filter expression DDS input only Content filter expression associated with the content filter for the topic route DataReader The expression is configured using the
184. s are Generated Statistics Publication RTI Routing Service reports multiple statistics as part of the different status sets For example for a route the status contains statistical metrics about the input and output samples per second throughput struct RouteStatusSet StatisticVariable input_samples_per_s StatisticVariable output_samples_per_s hi The statistical information is published periodically in the form StatisticVariables 6 19 UOIJD20 6joUJe3 D WOI 6uuojJIuo N 9 Chapter 6 6 20 The period at which statistics are published is configurable using the tag status publication period see Section 2 4 4 For a given variable RTI Routing Service computes the metrics in StatisticMetrics dur ing specific time frames struct StatisticMetrics unsigned long long period ms long long count float mean float minimum float maximum float std dev LT struct StatisticVariable StatisticMetric publication period metrics sequence lt StatisticMetrics MAX HISTORICAL METRICS historical metrics E The count is the sum of all the values received during the time frame For example in the case of input sample per s and output sample p s count is the number of sam ples received during the time frame For latency count is the sum of all the latency times for the samples received during the time frame If status publication is enabled see Section 2 4 4 RTI Routing Service always publishes the st
185. s are created with this configura tion The contents of this tag are specified in the same sdatsreader sou eatis pr bite manner as for an RTI Data Distribution Service 0or1 4 a QoS profile file see Chapter 15 in the RTI Data Distribution Service User s Manual If the tag is not defined RTI Routing Service will use the RTI Data Distribution Service defaults 1 The stream name filter allow stream name filter 0 or 1 Default allow all g The registered type name filter lt allow_registered_type_name_filter gt Oorl Default allow all A stream name filter that should be denied excluded This is applied after the deny topic name filter allow stream name filter Qori Default Not applied A registered type name filter that should be denied excluded This is applied after the deny registered type name filter Oorl lt allow_registered_type_name_filter gt Default Not applied 2 4 XML Tags for Configuring RTI Routing Service Table 2 18 Input and Output Tags for the auto route Tag Tags within Tags within D Sp pora input output Seen puon 25 ADS Allowed The topic routes are created with this configura tion Sequence of name value string pairs that can be used to configure certain parameters of the StreamReaders StreamWriters associated with the routes created from the auto route For exam ple lt property gt lt property gt value Oor1 ele
186. s enabled I The route is disabled dispose sample I The route configuration is modified using the remote command update 1 The route s StreamReader is created 1 The route s StreamReader is destroyed I The route s StreamWriter is created 1 The route s StreamWriter is destroyed M Monitoring is enabled via remote administration Configuration Data for an Auto Topic Route The topic that publishes auto route configuration data is called rti routing service monitoring auto route data The IDL definition of the data type RTT RoutingService Monitoring AutoRouteData is struct AutoRouteAdapterData sequence lt Property MAX PROPERTIES property struct AutoRouteDdsInputData long domain id String EXPRESSION MAX LENGTH content filter expression E UOIJD20 6joUJe3 D UJoJj GuuojJIuO N 9 Chapter 6 6 14 union AutoRouteInputAdapterData switch AdapterKind case RI AutoRouteDdsInputData dds case RI AutoRouteAdapterData generic bi struct Aut oRouteDdsOutputData long domain_id E UI ROUTING SERVICE DDS ADAPTER KIND CI ROUTING SERVICE GENERIC ADAPTER KIND union AutoRouteOutputAdapterData switch AdapterKind case RI I ROUTING SERVICE DDS ADAPT AutoRouteDdsOutputData dds case RI AutoRouteAdapterData generic hi struct Aut oRouteInputData ER KIND CI ROUTING SERVICE GENERIC ADAPTER KIND string TOPIC NA
187. s publishing it on the first domain topic route input participant 1 gt creation mode ON DOMAIN MATCH creation mode lt input gt lt output gt lt creation_mode gt ON_ROUTE_MATCH lt creation_mode gt lt output gt lt topic_route gt Example 2 In this example data is not routed until a user DataWriter is publishing and a user DataReader is already expecting it lt topic_route gt lt input participant 1 gt creation mode ON DOMAIN AND ROUTE MATCH creation mode lt input gt lt output gt creation mode ON DOMAIN AND ROUTE MATCH creation mode lt output gt lt topic_route gt Example 3 In this example all the data is received by the topic route s DataReader because it is cre ated as soon as a user DataWriter is discovered on the first domain However the data is not resent until a user DataReader on the other domain subscribes to it topic route input participant 1 gt creation mode ON DOMAIN MATCH creation mode input output 2 4 eolA1es Buynoy I13 BuunByuod Z Chapter 2 creation mode ON DOMAIN AND ROUTE MATCH creation mode lt output gt lt topic_route gt 2 4 6 5 Data Transformation A route can transform the incoming data using a transformation an object created by a transformation plugin For example the following transformation switches the coordinates of the input sample x becomes y and y becomes x
188. scription force asynchronous send Forces an asynchronous send When this parameter is set to 0 the TCP transport will attempt to send data as soon as the internal send function is called When it is set to 1 the transport will make a copy of the data to send and enqueue it in an internal send buf fer Data will be sent as soon as the low level socket buffer has space Normally setting it to 1 delivers better throughput in a fast network but will result in a longer time to recover from various TCP error conditions Setting it to 0 may cause the low level send function to block until the data is physically delivered to the lower socket buffer For an application writing data at a very fast rate it may cause the caller thread to block if the send socket buffer is full This could produce lower throughput in those condi tions the caller thread could prepare the next packet while waiting for the send socket buffer to become available Default 0 max packet size The maximum size of a TCP segment This parameter is only supported on Linux architectures By default the maximum size of a TCP segment is based on the network MTU for destina tions on a local network or on a default 576 for destinations on non local networks This behavior can be changed by setting this parameter to a value between 1 and 65535 Default 1 default behavior enable_keep_alive Configures the sending of KEEP_ALIVE messages in TCP Se
189. sed 7 2 Configuring the TCP Transport Table 7 1 TCP TLS Transport Properties over LAN or WAN NDDS Transport TCPvA Property t Property Name prefix with Description dds transport TCPv4 P tcp1 A list of strings each identifying a range of interface addresses that will not be used by the transport If the list is non empty deny the use of these interfaces Interfaces must be specified as comma separated strings with each comma delimiting an parent interface deny interfaces list For example 10 10 This black list is applied after parent allow interfaces list and filters out the interfaces that should not be used Default No interfaces are denied Size in bytes of the send buffer of a socket used for sending On most operating systems setsockopt will be called to set the SENDBUF to the value of this parameter This value must be greater than or equal to parent message size max send socket orai buffer_size The maximum value is operating system dependent Default 1 setsockopt or equivalent will not be called to size the send buffer of the socket Size in bytes of the receive buffer of a socket used for receiving On most operating systems setsockopt will be called to set the RECVBUF to the value of this parameter This value must be greater than or equal to parent message size max or 1 The maximum value is operating system dependent Default 1 set
190. sionl SquareToCircles topic route input datareader qos deadline period sec 1 The topic route DomainRoute1 Session1 SquareToCircles will only change the period value in the Deadline QoS for that particular DataReader Now suppose that later on you send this command update ShapeRouter DomainRoutel Sessionl SquareToCircles str lt topic_route gt lt input gt lt datareader_qos gt lt property gt lt value gt lt element gt lt name gt MyProp lt name gt lt value gt MyValueRemote lt value gt lt element gt lt value gt lt property gt lt datareader_qos gt lt input gt lt topic_route gt 5 7 UOHDISIUIWUpY ejowey G Chapter 5 This would only change the Property QoS the Deadline QoS would keep the set ting from the prior command L If you send a well formed configuration file starting with lt dds gt lt routing_service gt the properties in the route QoS values in the topic route will be completely replaced with the properties QoS values defined in the XML code If a QoS value for a topic route is not defined in the XML code RTI Routing Service will use the DDS default 5 2 6 pause pause target routing service entity name When the pause command is called in a route the session thread containing this route will stop reading data from the route s StreamReader For routing service domain routes auto routes and auto topic routes the execution of this command will pause the contained
191. sockopt or equivalent will not be called to size the receive buffer of the socket recv socket buffer size SJJOMJON Dely pPIM BuisIoADI Z Chapter 7 Table 7 1 TCP TLS Transport Properties over LAN or WAN NDDS Transport TCPvA Property t Property Name prefix with dds transport TCPv4 tcp1 Description ignore loopback interface Prevents the transport plugin from using the IP loopback interface This property is ignored when parent classid is NDDS TRANSPORT CLASSID TCPVA4 WAN or NDDS TRANSPORT CLASSID TLSV4 WAN Two values are allowed 0 Enable local traffic via this plugin The plugin will use and report the IP loopback inter face only if there are no other network interfaces NICs up on the system 1 Disable local traffic via this plugin This means do not use the IP loopback interface even if no NICs are discovered This setting is useful when you want applications running on the same node to use a more efficient plugin like shared memory instead of the IP loopback Default 1 ignore nonrunning interfaces Prevents the transport plugin from using a network interface that is not reported as RUN NING by the operating system The transport checks the flags reported by the operating system for each network interface upon initialization An interface which is not reported as UP will not be used This prop erty allows the same check to be extended to the
192. st have the Visual Studio 2005 service pack 1 redistributable libraries You can obtain this package from Microsoft or RTI see the RTI Data Distribution Service Release Notes for details b Make sure Java 1 5 or higher is available 1 Replace architecture with your existing architecture For example i86Win32VS2005 i86Linux2 6gcc4 1 1 etc 3 eolA1es Buynoy lla Guiuuna E Chapter 3 3 2 c Make sure you add the directory of the Java Virtual Machine dynamic library to your environment variable LD LIBRARY PATH on UNIX based systems or Path on Windows systems For example setenv LD_LIBRARY_PATH LD_LIBRARY_PATH local java jdk1 5 0_07 jre 1ib i386 client To start RTI Routing Service enter cd lt installation directory for RTI Routing Service gt scripts rtiroutingservice options Example cd lt installation directory for RTI Routing Service gt scripts rtiroutingservice cfgFile example shapes topic_bridge xml cfgName example Table 3 1 describes the command line options Stopping RTI Routing Service To stop RTI Routing Service press Ctrl c RTI Routing Service will perform a clean shut down 3 2 Stopping RTI Routing Service Table 3 1 RTI Routing Service Command line Options Option Description appName lt name gt Assigns a name to the execution of the RTI Routing Service Remote commands and status information will refer to the routing service us
193. stance see Section 8 3 2 In this example the entry point is the function SimpleFileAdapter_create in the file SimpleFileAdapter c You have to initialize this function to create a new plugin Plugin destructor x void SimpleFileAdapter delete struct RTI RoutingServiceAdapterPlugin adapter RTI RoutingServiceEnvironment env 8 3 Creating New Adapters free adapter Entry point to the adapter plugin ee DI1Export struct RTI_RoutingServiceAdapterPlugin SimpleFileAdapter_create const struct RTI_RoutingServiceProperties properties RTI_RoutingServiceEnvironment env struct RTI_RoutingServiceAdapterPlugin adapter NULL struct RTI_RoutingServiceVersion version 1 0 0 0 int verbosity verbosity RTI_RoutingServiceEnvironment_get_verbosity env if verbosity RTI_ROUTING_SERVICE_VERBOSITY_DEBUG printf CALL SimpleFileAdapter_create n adapter calloc 1 sizeof struct RTI RoutingServiceAdapterPlugin if adapter NULL RTI RoutingServiceEnvironment set error env Memory allocation error return NULL RTI RoutingServiceAdapterPlugin initialize adapter adapter plugin version version Assign the function pointers Fy adapter gt adapter_plugin_delete SimpleFileAdapter delete return struct RTI RoutingServiceAdapterPlugin adapter The structure RTI RoutingServiceAdapterPlugin contains the plugin implementation as a set of function pointers For no
194. sting an Adapter A simple Java test adapter is provided with RTI Routing Service Adapter SDK You will find the class com rti routingservice adapter test TestAdapter in rtirsadapter jar This is a convenient way to test your own adapters The TestAdapter is used as an out put adapter that counts the number of samples that meet certain conditions defined in the configuration file Your adapter will act as the input and its samples will be passed to the TestAdapter If the number of samples received by the TestAdapter is not between a defined range when you stop RTI Routing Service you will see a failure message Success or failure is determined when you stop RTI Routing Service and it destroys the adapter To use the TestAdapter to test your input adapter 1 Write a configuration file in which your adapter is the input for one or more routes and the TestAdapter is the output Configure the TestAdapter with the expected number of samples within a range specified using the properties MinExpectedSamples and MaxExpectedSamples in the output tag 8 79 slojdppy 8 Chapter 8 8 80 2 Run RTI Routing Service using that configuration file 3 Wait the amount of time your adapter may require 4 Stop RTI Routing Service The TestAdapter will print a failure or success message You can avoid steps 3 4 by starting RTI Routing Service with the stopAfter seconds command line option If you run RTI Routing Service with v
195. stribution Service application that can remotely control RTI Routing Service The administration tag is used to enable remote administration and configure its behavior By default remote administration is turned off in RTI Routing Service for security rea sons A remote administration section is not required in the configuration file For example dds routing service administration domain id 55 domain id lt administration gt lt routing_service gt lt dds gt When remote administration is enabled RTI Routing Service will create a DomainPartici pant Publisher Subscriber DataWriter and DataReader These DDS entities are used to receive commands and send responses You can configure these entities with QoS tags within the lt administration gt tag Table 2 6 lists the tags allowed within lt administration gt tag For more details please see Chapter 5 Administering RTI Routing Service from a Remote Location Note The command line options used to configure remote administration take prece dence over the XML configuration see Table 3 1 on page 3 3 Table 2 6 Remote Administration Tags saps Number Tags within ar dm Description of Tags lt administration gt Allowed lt domain_id gt Specifies which domain ID RTI Routing Service will use to A 1 required enable remote administration treg Configures the DomainParticipant QoS for remote administra tion p
196. t and lt datareader_qos gt Mutable QoS policies in lt datawriter_qos gt and a creation mode datareader qos allow topic name filter propagate dispose j f Auto allow registered type name filter propagate unregister Topic AM deny topic name filter publish with original info Route i deny registered type name filter content filter parameter i up content filter expression enity monitoring enabled ae DU cage entity monitoring entity monitoring status publication period Ein statistics sampling period entity monitoring historical statistics 1 Monitoring parameters can also be changed when monitoring is disabled even when the entity is enabled You can send an XML snippet or an assignment expression that only contains the val ues you want to change for that entity or you can send a whole well formed configura tion file 1 If you send an XML snippet or an assignment expression only the changes you specify will take effect For example suppose you send this command update ShapeRouter DomainRoutel Sessionl SquareToCircles str lt topic_route gt lt input gt lt datareader_qos gt lt deadline gt lt period gt lt sec gt 1 lt sec gt lt period gt lt deadline gt lt datareader_qos gt lt input gt lt topic_route gt or update ShapeRouter DomainRoutel Ses
197. t SimpleFileAdapterStreamReader self struct SimpleFileAdapterStreamReader stream reader int verbosity int length verbosity RTI RoutingServiceEnvironment get verbosity env if verbosity RTI ROUTING SERVICE VERBOSITY DEBUG printf CALL SimpleFileAdapterStreamReader_read n count 0 sample_list NULL We don t provide sample info in this adapter which is an optional feature T info list NULL DDS DynamicData clear all members self sample 0 8 35 slojdppy g Chapter 8 str fgets line sizeof line self gt fHandle if str return length strlen str if length gt 0 amp amp str length 1 n str length 1 0 if length gt 1 amp amp str length 2 r str length 2 0 retCode DDS_DynamicData_set_string self gt sample 0 value DDS DYNAMIC DATA MEMBER ID UNSPECIFIED line if retCode DDS RETCODE OK RTI RoutingServiceEnvironment set error env Error assigning value s line return sample_list RTI_RoutingServiceSample self gt sample eount 1 return Notification thread This thread will notify of data availability in the file void SimpleFileAdapterStreamReader_run void threadParam struct SimpleFileAdapterStreamReader self struct SimpleFileAdapterStreamReader threadParam while self run NDDS Utility sleep amp self readPeriod
198. t is also used by the adapter implementations to provide error notification Adapter verbosity The C adapter implementations can access the verbosity level used to run RTI Routing Service by using the following environment function RTI_RoutingServiceVerbosity RTI RoutingServiceEnvironment get verbosity const RTI RoutingServiceEnvironment self The mapping between the command line option verbosity and the RTI_RoutingServiceVerbosity enumeration is as follows Table 8 9 Mapping between verbosity and RTI RoutingServiceVerbosity verbosity RTI RoutingServiceVerbosity 0 RTI ROUTING SERVICE VERBOSITY NONE 1 RTI ROUTING SERVICE VERBOSITY EXCEPTION 2 RTI ROUTING SERVICE VERBOSITY WARN 3and4 RTI ROUTING SERVICE VERBOSITY INFO 5and 6 RTI ROUTING SERVICE VERBOSITY DEBUG 8 3 Creating New Adapters 8 3 2 3 8 3 3 8 3 3 1 Version Information RTI Routing Service and the different adapter implementations are identified by a ver sion number The adapter version is provided to RTI Routing Service using the member plugin version in the RTI RoutingServiceAdapterPlugin structure This member must be initialized in the adapter entry point function it is used by RTI Routing Service for logging purposes The RTI Routing Service version is provided to the C adapters through the environment The adapters can access this information with the following function void RTI RoutingServiceEnvironment get ve
199. tending RTI Routing Service with Adapters for more information 2 Register the plugin in the configuration file by creating an adapter plugin tag or a java adapter plugin inside an adapter library tag As noted in Table 2 1 adapter library is a top level tag 3 Instantiate an adapter connection by creating a connection tag inside a domain route tag that refers to the adapter plugin For additional information about adapters see Chapter 8 Extending RTI Routing Ser vice with Adapters 2 51 eoiues Buynoy I3 BuunByuod z Chapter 2 2 5 Enabling and Disabling RTI Routing Service Entities The RTI Routing Service entities associated with the tags routing service domain route route topic route auto route and auto topic route can be created enabled or disabled using the attribute enabled By default the value of the enabled attribute is true For example lt dds gt lt routing service name TopicBridgeExample group_name rti router default enabled true gt lt domain_route name DomainRoute enabled false gt participant 1 domain id 0 domain id participant 1 participant 2 domain id 1 domain id participant 2 session name Session gt topic route name SquaresToCircles enabled false gt input participant 1 gt registered type name ShapeType registered type name topic name Square topic name
200. ter will be created only when the type ShapeType is discovered in the output domain lt topic_route gt lt route_types gt false lt route_types gt lt input participant 1 gt lt creation_mode gt IMMEDIATE lt creation_mode gt lt registered_type_name gt ShapeType lt registered_type_name gt lt input gt lt output gt lt creation_mode gt IMMEDIATE lt creation_mode gt lt registered_type_name gt ShapeType lt registered_type_name gt lt output gt lt topic_route gt 2 39 eolA1es Buynoy Ila Guun amp yuo z Chapter 2 2 4 6 4 Creation Modes Controlling when StreamReaders and StreamWriters are Created The way a route creates its StreamReader and StreamWriter and starts reading and writ ing data can be configured The creation mode tag in a route s input and output tags controls when the routing service StreamReader StreamWriter is created Table 2 14 lists the possible val ues for the creation mode tag Table 2 14 Creation Modes 2 40 creation mode Values Description IMMEDIATE default ON DOMAIN MATCH The route StreamReader StreamWriter is created as soon as possible that is as soon as the types are avail able Note that if the type is defined in the configuration file the creation will occur when the routing service starts If the type is not defined in the configuration file it has to be discovered see Discovering Types Section 2 4 6 3
201. terStreamReader_read This function will be called by RTI Routing Service after being notified that the are new lines available Although the signature of the function allows returning more than one sample line for the sake of simplicity the implementation only returns one line each time the func tion is called L SimpleFileAdapterStreamReader return loan The loan on the samples pro vided by SimpleFileAdapterStreamReader read is returned to the adapter using this function The SimpleFileAdapter implementation of return_loan is empty because e The read operation does not create new samples and always returns a sin gle sample stored in the StreamReader 8 33 siojdopy 8 Chapter 8 8 34 e Two calls to SimpleFileAdapterStreamReader read cannot occur in par allel M SimpleFileAdapterStreamReader run RTI Routing Service will not call the read operation until it is notified of the presence of new data see Section 8 2 3 To provide data notification the StreamReader implementation creates a thread that wakes up after read period and notifies RTI Routing Service of new data if the end of the file has not been reached yet SimpleFileAdapterStreamReader run is the function executed by the notifica tion thread _ SimpleFileAdapterConnection delete stream reader This function is called to destroy a StreamReader The implementation will finalize the notification thread and close the file handle M SimpleFileA
202. th classpath ADAPTER CLASSPATH DDS CLASSPATH F SJAR cf class simplefileadapter jar C class routingservice RD S Q classNroutingservice 8 55 Ssiojdbpy 8 Chapter 8 8 3 6 4 8 56 Implementing the Adapter Class In this section you will create the adapter class for the simple file adapter Every Java adapter has to create an Adapter class that implements the com rti routing service adapter Adapter interface Adapter classes are registered with RTI Routing Service using the tag class name within java adapter plugin Section 8 1 Using your favorite Java editor create a file called SimpleFileAdapterjava under Adapter directory routingservice adapter simplefile Insert the following content fORCRCKCKCkCkc kc kokckck kc ko koc kc EKER RRR EKER ck kckokokck ck kokckck ck kokckck ck ckckckckckckckckckck ck kckckck ck kckckck oko k Simple File Adapter fCRCECKCKCk ck kc kckckcke ko ke koe ke kk kc ke kc ko kc kc ERE kc koc ke kc ko KERR EEK e ke kc kc kc ck kc kc kckckck ck kokckck ck kckckck ck k package routingservice adapter simplefile import com rti routingservice adapter Adapter import com rti routingservice adapter Connection import com rti routingservice adapter StreamReaderListener import com rti routingservice adapter infrastructure AdapterException import com rti routingservice adapter infrastructure Version import java util Properties Simple file ada
203. th the PropertyQoSPolicy The PropertyQosPolicy allows you to set up name value pairs of data and attach them to an entity such as a DomainParticipant The configuration of the TCP transport with RTI Routing Service is done using the PropertyQosPolicy of the Domain Participants that are going to use the transport For a list of the properties that you can set for the TCP transport see the RTI Data Distri bution Service User s Manual In the following example participant_1 will communicate with other participants on the same LAN using UDP and Shared Memory transports participant_2 will communi cate with other participants in different LANs using the TCP transport lt dds gt routing service name MyRoutingService gt domain route name MyDomainRoute participant 1 domain id 56 domain id participant 1 participant 2 domain id 57 domain id S4IOMJON Daly PIM uisieADIJJ Z Chapter 7 participant qos transport builtin lt mask gt MASK_NONE lt mask gt lt transport_builtin gt lt property gt lt value gt lt element gt lt name gt dds transport load_plugins lt name gt value dds transport TCPv4 tcpl value lt element gt lt element gt lt name gt dds transport TCPv4 tcpl library lt name gt lt value gt libnddstransporttcp so lt value gt lt element gt lt element gt lt name gt dds transport TCPv4 tcpl create function lt name gt lt
204. the input participant will not trigger the creation of routes The input deny registered type name filter is configured using the tag deny registered type name filter inside auto topic route input auto route dds input or auto route input out put deny stream name filter Topics that pass this filter in the output participant will not trigger the creation of routes The output deny topic name filter is configured using the tag deny topic name filter inside auto topic route output Or inside auto route dds output Or the tag deny stream name filter inside auto route output 6 2 Monitoring Configuration Data Table 65 AutoRouteData Field Name Key Description output deny_registered_ type_name_filter Topics with types that pass this filter in the output participant will not trigger the creation of routes The output deny registered type name filter is configured using the tag lt deny_registered_type_name_filter gt inside lt auto_topic_route gt lt output gt lt auto_route gt lt dds_output gt or auto route output input creation mode Indicates when the StreamReader is created in the input The input creation mode is creation mode configured using the tag output creation mode input adapter data Indicates when the StreamWriter in created in the output The output creation mo
205. tingServiceAdapterPlugin CreateConnectionFcn adapter plugin create connection RTI RoutingServiceAdapterPlugin DeleteConnectionFcn adapter plugin delete connection Connection API RTI RoutingServiceConnection CreateSessionFcn connection create session RTI RoutingServiceConnection DeleteSessionFcn connection delete session RTI RoutingServiceConnection CreateStreamReaderFcn connection create stream reader RTI RoutingServiceConnection DeleteStreamReaderFcn connection delete stream reader RTI RoutingServiceConnection CreateStreamWriterFcn connection create stream writer RTI RoutingServiceConnection DeleteStreamWriterFcn connection delete stream writer RTI RoutingServiceConnection GetDiscoveryReaderFcn connection get input stream discovery reader RTI RoutingServiceConnection GetDiscoveryReaderFcn connection get output stream discovery reader RTI RoutingServiceConnection CopyTypeRepresentationFcn connection copy type representation RTI RoutingServiceConnection DeleteTypeRepresentationFcn connection delete type representation 8 3 Creating New Adapters RTI RoutingServiceConnection GetAttributesFcn connection get attributes RTI RoutingServiceConnection ToStringFcn connection to string RTI RoutingServiceAdapterEntity UpdateFcn connection update Session API RTI RoutingServiceAdapterEntity UpdateFcn session update Stream Reader API RTI Routi
206. tion parseProperties properties 8 3 6 8 Running the SimpleFileAdapter This section describes the steps required to use and run the SimpleFileAdapter with RTI Routing Service You will create a configuration file with a single route that reads a Hel loWorld text file from an input directory and saves it into an output directory 1 Compile and build the SimpleFileAdapter UNIX based systems gt cd opt adapters simplefile build sh Windows systems gt cd c adapters SimpleFileAdapter gt build cmd 2 In the adapter project directory c adapters SimpleFileAdapter on Windows systems opt adapters simplefile on UNIX based systems create two directo ries called input and output 3 In the input directory create a file called HelloWorld txt with the following con tent Hello World 1 Hello World 2 Hello World 3 Hello World 4 Hello World 5 Hello World 6 1 Your directory may be different if you did not use the default locations 8 71 S1ioJdbDpy 8 Chapter 8 Hello World 7 Hello World 8 Hello World 9 Hello World 10 4 In the adapter project directory create an RTI Routing Service XML configuration file called simple file adapter xml with the following content Replace the value of the directory property under both connections with the location of the input and output directories lt xml version 1 0 gt lt dds gt lt adapter_library name adapters gt java
207. topic routes and routes 5 2 7 resume resume target routing service entity name When the resume command is called in a route the session thread containing this route will continue reading data from the route s StreamReader For routing service domain routes auto routes and auto topic routes the execution of this command will resume the contained topic routes and routes 5 3 Accessing RTI Routing Service from a DDS Application You can send commands to control a RTI Routing Service instance from your own DDS application You will need to create a DataWriter for a specific topic and type Then you can send a sample that contains a command and its parameters Optionally you can cre ate a DataReader for a specific topic to receive the results of the execution of your com mands The topics are M rti routing service administration command request Ll rti routing service administration command response The types are LI RTI RoutingService Administration CommandRequest 5 8 5 3 Accessing RTI Routing Service from a DDS Application LI RTI RoutingService Administration CommandResponse You can find the IDL definitions for these types in RTI Routing Service installation directory lresource idl RoutingServiceAdministration idl The QoS configuration of your DataWriter and DataReader must be compatible with the one used by the routing service see how this QoS is configured in Section 2 4 3 When you send an XML s
208. tring URL str xml code with the load and update commands if the string is longer than XML URL MAX LENGTH in the IDL file you will have to split the string and send several samples setting the final field to false in all but the last sample The following example shows how to send a command to update the Deadline QoS pol icy for a topic route s DataReader Create DDS entities participant publisher topic datawriter EP uus RTI RoutingService CommandRequest cmdRequest RTI RoutingService CommandRequestTypeSupport create data By specifying an unique ID for this command you will be able to identify its response later on cmdRequest id host host ID cmdRequest gt id app process ID cmdRequest gt id invocation invocationCounter Send this command to a routing service called MyRouter strcpy cmdRequest gt target_router MyRouter The command type is update cmdRequest gt command _d RTI_ROUTING_SERVICE_COMMAND_UPDATE Specify entity name to update and the XML code to define the new configuration strcpy cmdRequest command u entity desc name DomainRoutel Sessionl TopicRoutel When we use an XML snippet the first tag we specify is that of the entity lt topic_route gt in this case strcpy cmdRequest gt command _u entity_desc xml_url content str lt topic_route gt lt input gt lt datareader_qos gt lt deadline
209. tting this value to 1 causes a KEEP_ALIVE packet to be sent to the remote peer if a long time passes with no other data sent or received This feature is implemented only on architectures that provide a low level implementa tion of the TCP keep alive feature On Windows systems the TCP keep alive feature can be globally enabled through the sys tem s registry HKEY_LOCAL_MACHINE SYSTEM CurrentControlSet Tcpip Parameters Refer to MSDN documentation for more details On Solaris systems most of the TCP keep alive parameters can be changed though the kernel properties Default 0 keep_alive_time Specifies the interval of inactivity in seconds that causes TCP to generate a KEEP_ALIVE message This parameter is only supported on Linux architectures Default 1 OS default value 7 2 Configuring the TCP Transport Table 7 1 TCP TLS Transport Properties over LAN or WAN NDDS Transport TCPvA Property t Property Name prefix with dds transport TCPv4 tcp1 Description keep_alive_interval Specifies the interval in seconds between KEEP_ALIVE retries This parameter is only supported on Linux architectures Default 1 OS default value keep_alive_retry_count The maximum number of KEEP_ALIVE retries before dropping the connection This parameter is only supported on Linux architectures Default 1 OS default value disable_nagle Disables the TCP nagle algorithm
210. turn loan The loan on the samples provided by read is returned to the StreamReader using this method The SimpleFileAdapter implementation of return loan is empty because of these reasons e The read operation does not create new samples and it always return a sin gle sample stored in the StreamReader Two calls to read cannot occur in parallel I update The update methods will be called when the read_period is changed using remote administration Create a file called SimpleFileA dapterStreamReader java under Adapter directory gt routingservice adapter simplefile Insert the following content fORCRCKCECkCk kckckckckckckckokckck ck kokokck ck ckckckckckckckckckckckckokckckckckokokck ck RKEER ckckckck ck ck kckckckck kc k ko k ko k J Simple File Adapter Stream Reader x fORCRCKCECkCk kc kokckckckc kc kokckck ck kokokck ck ckckckckckckckckckckckckokokckckckokokckckckckckckckckckckckck ck kckckckck kc k ko k kk package routingservice adapter simplefile import java io File import java io BufferedReader import java io FileReader import java io IOException import java util List import java util Properties import com rti dds dynamicdata DynamicData import com rti dds typecode TypeCode import com rti routingservice adapter StreamReader import com rti routingservice adapter StreamReaderListener import com rti routingservice adapter infrastructure AdapterException import com rti routingservice ada
211. uration error tls identity certificate_chain_file A string that specifies the name of a file containing an identifying certificate chain in PEM format An identifying certificate is required for secure communication The file must be sorted starting with the certificate to the highest level root CA Optionally a private key may be appended to this file If a private key is not appended to this file then either private_key or private_key_file is required Either certificate_chain or certificate_chain_file is required You must set exactly ONE of these Do not set both of them this would produce a configuration error tls identity private key passwor d A string that specifies the password for private key tls identity private key A string containing a private key in PEM format Either private key or private key file may be specified Do not set both of them this would produce a configuration error If both are unspecified NULL the private key must be appended to the certificate chain file tls identity private key file A string that specifies the name of a file containing a private key in PEM format Either private key or private key file may be specified Do not set both of them this would produce a configuration error If both are unspecified NULL the private key must be appended to the certificate chain file 1 Assuming you used dds transport TCPv4 tcp1 as the alias to l
212. urce idl RoutingService Monitoring idl Configuration Data for the Routing Service The topic that publishes configuration data for the routing service is called rti routing service monitoring routing service data This topic describes the configura tion of the routing service but not its contained entities The IDL definition of the data type is struct RoutingServiceData String ENTITY NAME MAX LENGTH name key String ENTITY NAME MAX LENGTH group name String ENTITY NAME MAX LENGTH host name long host id long app id hi Table 6 1 on page 6 4 describes the members of RoutingServiceData data type Routing service data samples are published when 1 The routing service instance is enabled 1 The routing service instance is disabled dispose sample I Monitoring is enabled via remote administration 6 3 UOIJD20 6jOUJO3 D WOI GuuojJIuO N 9 Chapter 6 Table 6 1 6 2 2 RoutingServiceData Field Name Key Description name Name of the routing service instance The name associated with the routing service instance can be assigned explicitly using the command line parameter appName If appName is not used the routing service tag name provided with cfgName is used If you use identifyExecution the host name and process ID are appended to the name For example RTI RoutingService myhost 1234 group name Name of the group to which the routing service belong
213. uto_topic route gt ters See Auto Routes Section 2 4 7 REIR Defines a data mapping between two streams See Routes Sec route 0 or more tion 2 4 6 Defines a data mapping between two DDS topics See Routes lt topic_route gt A 0 or more Section 2 4 6 2 27 eolA1es Buynoy I13 BuunByuod Z Chapter 2 Table 2 9 Session Tags 2 28 Tags within session Description Number of Tags Allowed publisher qos subscriber qos Only applicable to DDS 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 an RTI Data Distribution Service QoS profile file see Chapter 15 in the RTI Data Distribution Service User s Manual If the tag is not defined RTI Routing Service will use the RTI Data Distribution Service defaults Only applicable to 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 an RTI Data Distribution Service QoS profile file see Chapter 15 in the RTI Data Distribution Service User s Manual If the tag is not defined RTI Routing Service will use the RTI Data Distribution Service defaults Oor1 Oor1 thread Sets the mask priority and stack size of the thread associated with this session Example session thread lt mask
214. variable only considers the bytes of the serialized samples Protocol headers UDP RTPS are not included latency s Statistic variable that provides information about the latency in sec onds across routes The latency in a route refers to the time elapsed between the sample read and write This is a good metric to monitor the health and per formance of transformations 6 3 5 Status Information fo ra Route The topic that publishes route status is called rti routing service monitoring route status set The IDL definition of the data type is struct TopicRouteStatusSet string ENTITY NAME MAX LENGTH routing service name key String ENTITY NAME MAX LENGTH domain route name key Sstring ENTITY NAME MAX LENGTH session name key String ENTITY NAME MAX LENGTH name key StatisticVariable StatisticVariable StatisticVariable StatisticVariable StatisticVariable lj input samples per s input bytes per s output samples per s output bytes per s latency s Table 6 9 describes the fields in the RouteStatusSet data type 6 25 UOIJD20 6jOoUJO3 D UJoJj 6uuojJIuo N 9 Chapter 6 Table 6 9 TopicRouteStatusSet 6 26 Member Name Key Description routing service name v Therouting service name assigned with appName domain route name V The domain route name session name V The session name V The route name name
215. vice Section 2 4 2 1 dIA1es Buynoy ILa BuunByuod Z Chapter 2 2 1 Terms to Know Before learning how to configure RTI Routing Service you should become familiar with a few key terms and concepts LI A routing service entity refers to an execution of RTI Routing Service L A domain route defines a two way mapping between two data domains 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 1 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 Ql A transformation is a pluggable component that changes data from the input stream A to data in the output stream B IJ An adapter is a pluggable component that allows RTI Routing Service to consume and produce data for different data domains By default RTI Routing Service is distributed with a built in DDS adapter 2 2 2 2 How to Load the XML Configuration 2 2 How to Load the XML Configuration
216. w you only need to implement adapter plugin delete that deletes the plugin instances created by SimpleFileAdapter create You will ini 8 29 siojdopy 8 Chapter 8 8 3 3 5 8 30 tialize the other pointers in the plugin structure as you implement the adapter function ality The entry point function receives two parameters the adapter properties and the envi ronment env The properties parameter not used by the SimpleFileAdapter is used to configure the adapter instance The values contained in this parameter are provided as name value pairs using the tag property within adapter plugin see Adapter Usage and Con figuration Section 8 1 The environment parameter env is part of every function in the adapter API This parameter is used to get information about the RTI Routing Service execution such as the version or the verbosity In addition the environment is also used to notify RTI Routing Service of any error in the adapter execution Implementing the Adapter Connection The adapter plugin instances are connection factories Connection objects provide access to data domains such as DDS domains or JMS network providers and they are configured using the XML tags connection 1 and connection 2 in a domain route see Section 2 4 2 In the SimpleFileAdapter example the connection objects will provide access to a directory on your computer s file system The next step consist on implementing th
217. y I 5 DataWriters for publishing status one for each kind of entity The QoS values for these entities are described in Section 2 4 4 Monitoring Configuration Data Configuration data for RTI Routing Service entities is published in entity data topics These topics are similar to the DDS builtin topics DCPSParticipant DCPSPublication and DCPSSubscription that provide information about the configuration of remote DDS entities This configuration data is published when 1 An entity is created or enabled I An entity is disabled or destroyed a dispose message is published The entity s configuration is modified using the remote command update see Section 5 2 5 6 2 Monitoring Configuration Data 6 2 1 1 The entity s configuration is modified due to certain events in RTI Routing Ser vice For example discovery events may trigger the creation of StreamWriters and StreamReaders in a route The following sections describe the data available for each kind of RTI Routing Service entity 1 Configuration Data for the Routing Service Section 6 2 1 1 Configuration Data for a Domain Route Section 6 2 2 LI Configuration Data for a Session Section 6 2 3 1 Configuration Data for a Route Section 6 2 4 J Configuration Data for an Auto Topic Route Section 6 2 5 Each section describes the IDL for the topics underlying data types The IDL is also in the file RTI Routing Service installation directory gt reso
218. ypes contain double long long unsigned long long or long double members Default disabled verbosity n Controls what type of messages are logged 0 Silent 1 Exceptions DDS and service default 2 Warnings service 3 Information service 4 Warnings DDS and service 5 Tracing service 6 Tracing DDS and service Each verbosity level n includes all the verbosity levels smaller than n version Prints the RTI Routing Service version number eolA1es Buynoy lla Guruuna E Chapter 3 3 6 Chapter 4 Transforming Data with RTI Routing 4 1 Service As described in Data Transformation Section 2 4 6 5 a route can transform the incom ing data using a transformation which is an object created by a transformation plugin Transformation plugins implement the transformation API and must be provided as shared libraries that RTI Routing Service will load dynamically Currently the transformation plugin API is only supported in C This chapter describes I Transformation Usage and Configuration Section 4 1 J Transformations Distributed with RTI Routing Service Section 4 2 N Creating New Transformations Section 4 3 Transformation Usage and Configuration In the XML configuration file transformation plugins must be defined within a trans formation library For example lt dds gt transformation library name MyTransfLib transformation plugin
219. ystem out println CALL getClass getName createStreamReader return new SimpleFileAdapterStreamReader listener streamInfo properties directory verbosity 8 59 slojdppy g Chapter 8 uA public void deleteStreamReader StreamReader streamReader throws AdapterException if verbosity equals debug System out println CALL getClass getName deleteStreamReader SimpleFileAdapterStreamReader streamReader close public StreamWriter createStreamWriter Session session StreamInfo streamInfo Properties properties throws AdapterException if verbosity equals debug System out println CALL getClass getName createStreamWriter return new SimpleFileAdapterStreamWriter streamInfo properties directory verbosity Ey public void deleteStreamWriter StreamWriter streamWriter throws AdapterException if verbosity equals debug System out println CALL getClass getName deleteStreamWriter SimpleFileAdapterStreamWriter streamWriter close 8 60 8 3 Creating New Adapters 8 3 6 6 ey public Properties getAttributes throws AdapterException throw new AdapterException 0 operation not supported public void update Properties properties throws AdapterException j Connection objects are configurable using properties name value pairs The proper ties are set usi

User`s Manual - Community RTI Connext Users

Contents

Download Pdf Manuals

Related Search

Related Contents