4. Loading a Connector

4.1. Import the Connector package

To use the rticonnextdds_connector package, require it. For example:

const rti = require('rticonnextdds-connector')

4.2. Creating a new Connector

To create a new Connector(), pass an XML file and a configuration name to the constructor:

const connector = new rti.Connector('MyParticipantLibrary::MyParticipant', 'ShapeExample.xml')

The XML file defines your types, QoS profiles, and DDS Entities. Connector uses the XML schema of RTI’s XML-Based Application Creation.

The previous code loads the <domain_participant> named MyParticipant in the <domain_participant_library> named MyParticipantLibrary, which is defined in the file ShapeExample.xml:

<domain_participant_library name="MyParticipantLibrary">
  <domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain">
    ...
  </domain_participant>
</domain_participant_library>

See the full file here: ShapeExample.xml.

When you create a Connector(), the DDS DomainParticipant that you selected and all of its contained entities (Topics, Subscribers, DataReaders, Publishers, DataWriters) are created.

For more information about the DDS entities, see Core Concepts in the RTI Connext DDS Core Libraries User’s Manual.

Note

Operations on the same Connector() instance or its contained entities are not protected for multi-threaded access. See Threading model for more information.

4.3. Closing a Connector

To destroy all the DDS entities that belong to a previously created Connector(), call Connector.close():

const connector = new rti.Connector('MyParticipantLibrary::MyParticipant', 'ShapeExample.xml')
// ...
connector.close()

Connector.close() returns a Promise that will resolve once the Connector object has been destroyed. The Connector.close() operation is only asynchronous (and therefore, it is only necessary to wait for the Promise to resolve) if you have installed a listener for the 'on_data_available' event.

For more information, see Additional considerations when using event-based functionality.

4.4. Getting the Inputs and Outputs

Once you have created a Connector() instance, Connector.getOutput() returns the Output() that allows writing data, and Connector.getInput() returns the Input() that allows reading data.

Note

If the <domain_participant> you load contains both <data_writer> tags (Outputs) and <data_reader> tags (Inputs) for the same Topic and they have matching QoS, when you write data, the Inputs will receive the data even before you call Connector.getInput(). To avoid that, you can configure the <subscriber> that contains the <data_reader> with <subscriber_qos>/<entity_factory>/<autoenable_created_entities> set to false. Then the Inputs will only receive data after you call Connector.getInput().

For more information see:

Writing Data (Output)

Reading Data (Input)

4.5. Class reference: Connector

class Connector(configName, url)

Loads a configuration and creates its Inputs and Outputs.

Note

The Connector() class inherits from EventEmitter. This allows us to support event-based notification for data, using the following syntax:

connector.on('on_data_available', () => { } )

Please refer to Reading Data (Input) for more information.

A Connector() instance loads a configuration file from an XML document. For example:

const connector = new rti.Connector('MyParticipantLibrary::MyParticipant', 'MyExample.xml')

After creating it, the Connector() object’s Inputs can be used to read data, and the Outputs to write data. The methods Connector.getOutput() and Connector.getInput() return an Input() and Output(), respectively.

An application can create multiple Connector() instances for the same or different configurations.

Arguments:

configName (string) – The configuration to load. The configName format is LibraryName::ParticipantName, where LibraryName is the name attribute of a <domain_participant_library> tag, and ParticipantName is the name attribute of a <domain_participant> tag within that library.
url (string) – A URL locating the XML document. It can be a file path (e.g., /tmp/my_dds_config.xml), a string containing the full XML document with the following format: str://"<dds>...</dds>", or a combination of multiple files or strings, as explained in the URL Groups section of the Connext DDS Core Libraries User’s Manual.

Connector.close(timeout)

Frees all the resources created by this Connector() instance.

Arguments:

timeout (number) – Optional parameter to indicate the timeout of the operation, in seconds. By default, 10s. If this operation does not complete within the specified timeout, the returned Promise will be rejected.

Returns:

Promise – Which resolves once the Connector() object has been freed. It is only necessary to wait for this promise to resolve if you have attached a listener for the on_data_available event.

Connector.getInput(inputName)

Returns the Input() named inputName.

inputName identifies a <data_reader> tag in the configuration loaded by the Connector(). For example:

const connector = new rti.Connector('MyParticipantLibrary::MyParticipant', 'MyExample.xml')
connector.getInput('MySubscriber::MyReader')

Loads the Input in this XML:

<domain_participant_library name="MyParticipantLibrary">
  <domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain">
    <subscriber name="MySubscriber">
      <data_reader name="MyReader" topic_ref="MyTopic"/>
      ...
    </subscriber>
    ...
  </domain_participant>
  ...
<domain_participant_library>

Arguments:

inputName (string) – The name of the data_reader to load, with the format SubscriberName::DataReaderName.

Returns:

Input – The Input, if it exists.

Connector.getOutput(outputName)

Returns the Output() named outputName.

outputName identifies a <data_writer> tag in the configuration loaded by the Connector(). For example:

const connector = new rti.Connector('MyParticipantLibrary::MyParticipant', 'MyExample.xml')
connector.getOutput('MyPublisher::MyWriter')

Loads the Input in this XML:

<domain_participant_library name="MyParticipantLibrary">
  <domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain">
    <publisher name="MyPublisher">
      <data_writer name="MyWriter" topic_ref="MyTopic"/>
      ...
    </publisher>
    ...
  </domain_participant>
  ...
<domain_participant_library>

Arguments:

outputName (string) – The name of the data_writer to load, with the format PublisherName::DataWriterName.

Returns:

Output – The Output, if it exists.

Connector.wait(timeout)

Waits for data to be received on any Input.

Note

This operation is asynchronous.

Arguments:

timeout (number) – The maximum time to wait, in milliseconds. By default, infinite.

Throws:

TimeoutError – TimeoutError() will be thrown if the timeout expires before data is received.

Returns:

Promise – A Promise which will be resolved once data is available, or rejected once the timeout expires.

Connector.waitForCallbackFinalization(timeout)

Returns a Promise that will resolve once the resources used internally by the Connector() are no longer in use.

Note

This returned promise will be rejected if there are any listeners registered for the on_data_available event. Ensure that they have all been removed before calling this method using connector.removeAllListeners(on_data_available).

It is currently only necessary to call this method if you remove all of the listeners for the on_data_available event and at some point in the future wish to use the same Connector() object to get notifications of new data (via the Connector.wait() method, or by re-adding a listener for the on_data_available event).

This operation does not free any resources. It is still necessary to call Connector.close() when the Connector() is no longer required.

Arguments:

timeout (number) – Optional parameter to indicate the timeout of the operation, in seconds. By default, 10s. If this operation does not complete within the specified timeout, the returned Promise will be rejected.

Returns:

Promise – A Promise that will be resolved once the resources being used internally by the Connector() object are no longer in use.

static Connector.getVersion()

Returns the version of Connector.

This static method provides the build IDs of the native libraries being used by Connector, as well as the version of the Connector API.

Note

This is a static method. It can be called before creating a Connector() instance.

Returns:: string – A string containing information about the version of Connector.