RTI Connext Java API  Version 5.1.0
RtpsWellKnownPorts_t Class Reference

RTPS well-known port mapping configuration. More...

Inherits Struct.

Public Attributes

int port_base
 The base port offset.
 
int domain_id_gain
 Tunable domain gain parameter.
 
int participant_id_gain
 Tunable participant gain parameter.
 
int builtin_multicast_port_offset
 Additional offset for metatraffic multicast port.
 
int builtin_unicast_port_offset
 Additional offset for metatraffic unicast port.
 
int user_multicast_port_offset
 Additional offset for usertraffic multicast port.
 
int user_unicast_port_offset
 Additional offset for usertraffic unicast port.
 

Static Public Attributes

static final RtpsWellKnownPorts_t RTI_BACKWARDS_COMPATIBLE_RTPS_WELL_KNOWN_PORTS
 Assign to use well-known port mappings which are compatible with previous versions of the RTI Connext middleware.
 
static final RtpsWellKnownPorts_t INTEROPERABLE_RTPS_WELL_KNOWN_PORTS
 Assign to use well-known port mappings which are compliant with OMG's DDS Interoperability Wire Protocol.
 

Additional Inherited Members

- Public Member Functions inherited from Struct
abstract boolean equals (Object obj)
 
abstract int hashCode ()
 
String toString ()
 
- Protected Member Functions inherited from Struct
 Struct ()
 
abstract void pull_from_nativeI (long native_status)
 
abstract void push_to_nativeI (long native_status)
 

Detailed Description

RTPS well-known port mapping configuration.

RTI Connext uses the RTPS wire protocol. The discovery protocols defined by RTPS rely on well-known ports to initiate discovery. These well-known ports define the multicast and unicast ports on which a Participant will listen for discovery metatraffic from other Participants. The discovery metatraffic contains all the information required to establish the presence of remote DDS entities in the network.

The well-known ports are defined by RTPS in terms of port mapping expressions with several tunable parameters, which allow you to customize what network ports are used by RTI Connext. These parameters are exposed in com.rti.dds.infrastructure.RtpsWellKnownPorts_t. In order for all Participants in a system to correctly discover each other, it is important that they all use the same port mapping expressions.

The actual port mapping expressions, as defined by the RTPS specification, can be found below. In addition to the parameters listed in com.rti.dds.infrastructure.RtpsWellKnownPorts_t, the port numbers depend on:

- domain_id, as specified in com.rti.dds.domain.DomainParticipantFactory.create_participant

- participant_id, as specified using com.rti.dds.infrastructure.WireProtocolQosPolicy.participant_id

The domain_id parameter ensures no port conflicts exist between Participants belonging to different domains. This also means that discovery metatraffic in one domain is not visible to Participants in a different domain. The participant_id parameter ensures that unique unicast port numbers are assigned to Participants belonging to the same domain on a given host.

The metatraffic_unicast_port is used to exchange discovery metatraffic using unicast.

metatraffic_unicast_port = port_base + (domain_id_gain * domain_id) + (participant_id_gain * participant_id) + builtin_unicast_port_offset 

The metatraffic_multicast_port is used to exchange discovery metatraffic using multicast. The corresponding multicast group addresses are specified via com.rti.dds.infrastructure.DiscoveryQosPolicy.multicast_receive_addresses on a com.rti.dds.domain.DomainParticipant entity.

metatraffic_multicast_port = port_base + (domain_id_gain * domain_id) + builtin_multicast_port_offset 

RTPS also defines the default multicast and unicast ports on which DataReaders and DataWriters receive usertraffic. These default ports can be overridden using the com.rti.dds.subscription.DataReaderQos.multicast, com.rti.dds.subscription.DataReaderQos.unicast, or by the com.rti.dds.publication.DataWriterQos.unicast QoS policies.

The usertraffic_unicast_port is used to exchange user data using unicast.

usertraffic_unicast_port = port_base + (domain_id_gain * domain_id) + (participant_id_gain * participant_id) + user_unicast_port_offset 

The usertraffic_multicast_port is used to exchange user data using multicast. The corresponding multicast group addresses can be configured using com.rti.dds.infrastructure.TransportMulticastQosPolicy.

usertraffic_multicast_port = port_base + (domain_id_gain * domain_id) + user_multicast_port_offset 

By default, the port mapping parameters are configured to compliant with OMG's DDS Interoperability Wire Protocol (see also com.rti.dds.infrastructure.RtpsWellKnownPorts_t.INTEROPERABLE_RTPS_WELL_KNOWN_PORTS).

The OMG's DDS Interoperability Wire Protocol compliant port mapping parameters are not backwards compatible with previous versions of the RTI Connext middleware.

When modifying the port mapping parameters, care must be taken to avoid port aliasing. This would result in undefined discovery behavior. The chosen parameter values will also determine the maximum possible number of domains in the system and the maximum number of participants per domain. Additionally, any resulting mapped port number must be within the range imposed by the underlying transport. For example, for UDPv4, this range typically equals [1024 - 65535].

QoS:
com.rti.dds.infrastructure.WireProtocolQosPolicy

Member Data Documentation

int port_base

The base port offset.

All mapped well-known ports are offset by this value.

[default] 7400

[range] [>= 1], but resulting ports must be within the range imposed by the underlying transport.

int domain_id_gain

Tunable domain gain parameter.

Multiplier of the domain_id. Together with participant_id_gain, it determines the highest domain_id and participant_id allowed on this network.

In general, there are two ways to setup domain_id_gain and participant_id_gain parameters.

If domain_id_gain > participant_id_gain, it results in a port mapping layout where all com.rti.dds.domain.DomainParticipant instances within a single domain occupy a consecutive range of domain_id_gain ports. Precisely, all ports occupied by the domain fall within:

(port_base + (domain_id_gain * domain_id)) 

and:

(port_base + (domain_id_gain * (domain_id + 1)) - 1) 

Under such a case, the highest domain_id is limited only by the underlying transport's maximum port. The highest participant_id, however, must satisfy:

max_participant_id < (domain_id_gain / participant_id_gain) 

On the contrary, if domain_id_gain <= participant_id_gain, it results in a port mapping layout where a given domain's com.rti.dds.domain.DomainParticipant instances occupy ports spanned across the entire valid port range allowed by the underlying transport. For instance, it results in the following potential mapping:

Mapped Port Domain Id Participant ID
higher port number Domain Id = 1 Participant ID = 2
Domain Id = 0 Participant ID = 2
Domain Id = 1 Participant ID = 1
Domain Id = 0 Participant ID = 1
Domain Id = 1 Participant ID = 0
lower port number Domain Id = 0 Participant ID = 0

Under this case, the highest participant_id is limited only by the underlying transport's maximum port. The highest domain_id, however, must satisfy:

max_domain_id < (participant_id_gain / domain_id_gain) 

Additionally, domain_id_gain also determines the range of the port-specific offsets.

domain_id_gain > abs(builtin_multicast_port_offset - user_multicast_port_offset) 
domain_id_gain > abs(builtin_unicast_port_offset - user_unicast_port_offset) 

Violating this may result in port aliasing and undefined discovery behavior.

[default] 250

[range] [> 0], but resulting ports must be within the range imposed by the underlying transport.

int participant_id_gain

Tunable participant gain parameter.

Multiplier of the participant_id. See com.rti.dds.infrastructure.RtpsWellKnownPorts_t.domain_id_gain for its implications on the highest domain_id and participant_id allowed on this network.

Additionally, participant_id_gain also determines the range of builtin_unicast_port_offset and user_unicast_port_offset.

participant_id_gain > abs(builtin_unicast_port_offset - user_unicast_port_offset) 

[default] 2

[range] [> 0], but resulting ports must be within the range imposed by the underlying transport.

int builtin_multicast_port_offset

Additional offset for metatraffic multicast port.

It must be unique from other port-specific offsets.

[default] 0

[range] [>= 0], but resulting ports must be within the range imposed by the underlying transport.

int builtin_unicast_port_offset

Additional offset for metatraffic unicast port.

It must be unique from other port-specific offsets.

[default] 10

[range] [>= 0], but resulting ports must be within the range imposed by the underlying transport.

int user_multicast_port_offset

Additional offset for usertraffic multicast port.

It must be unique from other port-specific offsets.

[default] 1

[range] [>= 0], but resulting ports must be within the range imposed by the underlying transport.

int user_unicast_port_offset

Additional offset for usertraffic unicast port.

It must be unique from other port-specific offsets.

[default] 11

[range] [>= 0], but resulting ports must be within the range imposed by the underlying transport.


RTI Connext Java API Version 5.1.0 Copyright © Mon Feb 3 2014 Real-Time Innovations, Inc