RTI Connext Java API  Version 5.3.1
 All Classes Namespaces Functions Variables Groups Pages
DomainParticipantFactory Class Referenceabstract

<<singleton>> <<interface>> Allows creation and destruction of com.rti.dds.domain.DomainParticipant objects. More...

Public Member Functions

abstract DomainParticipant create_participant (int domainId, DomainParticipantQos qos, DomainParticipantListener listener, int mask)
 Creates a new com.rti.dds.domain.DomainParticipant object.
 
abstract void delete_participant (DomainParticipant a_participant)
 Deletes an existing com.rti.dds.domain.DomainParticipant.
 
abstract void get_default_participant_qos (DomainParticipantQos qos)
 Initializes the com.rti.dds.domain.DomainParticipantQos instance with default values.
 
abstract void set_default_participant_qos (DomainParticipantQos qos)
 Sets the default com.rti.dds.domain.DomainParticipantQos values for this domain participant factory.
 
abstract void set_default_participant_qos_with_profile (String library_name, String profile_name)
 <<extension>> Sets the default com.rti.dds.domain.DomainParticipantQos values for this domain participant factory based on the input XML QoS profile.
 
abstract DomainParticipant lookup_participant (int domainId)
 Locates an existing com.rti.dds.domain.DomainParticipant.
 
abstract void get_qos (DomainParticipantFactoryQos qos)
 Gets the value for participant factory QoS.
 
abstract void set_qos (DomainParticipantFactoryQos qos)
 Sets the value for a participant factory QoS.
 
abstract void load_profiles ()
 <<extension>> Loads the XML QoS profiles.
 
abstract void reload_profiles ()
 <<extension>> Reloads the XML QoS profiles.
 
abstract void unload_profiles ()
 <<extension>> Unloads the XML QoS profiles.
 
abstract String get_default_library ()
 <<extension>> Gets the default XML library associated with a com.rti.dds.domain.DomainParticipantFactory.
 
abstract void set_default_library (String library_name)
 <<extension>> Sets the default XML library for a com.rti.dds.domain.DomainParticipantFactory.
 
abstract String get_default_profile ()
 <<extension>> Gets the default XML profile associated with a com.rti.dds.domain.DomainParticipantFactory.
 
abstract void set_default_profile (String library_name, String profile_name)
 <<extension>> Sets the default XML profile for a com.rti.dds.domain.DomainParticipantFactory.
 
abstract String get_default_profile_library ()
 <<extension>> Gets the library where the default XML profile is contained for a com.rti.dds.domain.DomainParticipantFactory.
 
abstract void get_participant_factory_qos_from_profile (DomainParticipantFactoryQos qos, String library_name, String profile_name)
 <<extension>> Gets the com.rti.dds.domain.DomainParticipantFactoryQos values associated with the input XML QoS profile.
 
abstract void get_participant_qos_from_profile (DomainParticipantQos qos, String library_name, String profile_name)
 <<extension>> Gets the com.rti.dds.domain.DomainParticipantQos values associated with the input XML QoS profile.
 
abstract void get_publisher_qos_from_profile (PublisherQos qos, String library_name, String profile_name)
 <<extension>> Gets the com.rti.dds.publication.PublisherQos values associated with the input XML QoS profile.
 
abstract void get_subscriber_qos_from_profile (SubscriberQos qos, String library_name, String profile_name)
 <<extension>> Gets the com.rti.dds.subscription.SubscriberQos values associated with the input XML QoS profile.
 
abstract void get_datawriter_qos_from_profile (DataWriterQos qos, String library_name, String profile_name)
 <<extension>> Gets the com.rti.dds.publication.DataWriterQos values associated with the input XML QoS profile.
 
abstract void get_datawriter_qos_from_profile_w_topic_name (DataWriterQos qos, String library_name, String profile_name, String topic_name)
 <<extension>> Gets the com.rti.dds.publication.DataWriterQos values associated with the input XML QoS profile while applying topic filters to the input topic name.
 
abstract void get_datareader_qos_from_profile (DataReaderQos qos, String library_name, String profile_name)
 <<extension>> Gets the com.rti.dds.subscription.DataReaderQos values associated with the input XML QoS profile.
 
abstract void get_datareader_qos_from_profile_w_topic_name (DataReaderQos qos, String library_name, String profile_name, String topic_name)
 <<extension>> Gets the com.rti.dds.subscription.DataReaderQos values associated with the input XML QoS profile while applying topic filters to the input topic name.
 
abstract void get_topic_qos_from_profile (TopicQos qos, String library_name, String profile_name)
 <<extension>> Gets the com.rti.dds.topic.TopicQos values associated with the input XML QoS profile.
 
abstract void get_topic_qos_from_profile_w_topic_name (TopicQos qos, String library_name, String profile_name, String topic_name)
 <<extension>> Gets the com.rti.dds.topic.TopicQos values associated with the input XML QoS profile while applying topic filters to the input topic name.
 
abstract void get_qos_profile_libraries (StringSeq library_names)
 <<extension>> Gets the names of all XML QoS profile libraries associated with the com.rti.dds.domain.DomainParticipantFactory
 
abstract void get_qos_profiles (StringSeq profile_names, String library_name)
 <<extension>> Gets the names of all XML QoS profiles associated with the input XML QoS profile library.
 
abstract DomainParticipant create_participant_with_profile (int domainId, String library_name, String profile_name, DomainParticipantListener listener, int mask)
 <<extension>> Creates a new com.rti.dds.domain.DomainParticipant object using the com.rti.dds.domain.DomainParticipantQos associated with the input XML QoS profile.
 
abstract void unregister_thread ()
 <<extension>> Allows the user to release thread specific resources kept by the middleware.
 
abstract DomainParticipant create_participant_from_config (String configuration_name)
 <<extension>> Creates a com.rti.dds.domain.DomainParticipant given its configuration name from a description provided in an XML configuration file.
 
abstract DomainParticipant create_participant_from_config_w_params (String configuration_name, DomainParticipantConfigParams_t params)
 <<extension>> Creates a com.rti.dds.domain.DomainParticipant given its configuration name from a description provided in an XML configuration file and a set of parameters that allow chaging some properties of such configuration.
 
abstract DomainParticipant lookup_participant_by_name (String participant_name)
 <<extension>> Looks up a com.rti.dds.domain.DomainParticipant by its entity name in the com.rti.dds.domain.DomainParticipantFactory.
 
abstract void register_type_support (TypeSupport type_support, String type_name)
 <<extension>> Registers a com.rti.dds.topic.TypeSupport with the com.rti.dds.domain.DomainParticipantFactory to enable automatic registration if the corresponding type, should it be needed by a com.rti.dds.domain.DomainParticipant.
 

Static Public Member Functions

static final
DomainParticipantFactory 
get_instance ()
 Gets the singleton instance of this class.
 
static final void finalize_instance ()
 <<extension>> Destroys the singleton instance of this class.
 

Static Public Attributes

static final DomainParticipantQos PARTICIPANT_QOS_DEFAULT
 Special value for creating a DomainParticipant with default QoS.
 
static DomainParticipantFactory TheParticipantFactory = create_singletonI()
 Can be used as an alias for the singleton factory returned by the operation com.rti.dds.domain.DomainParticipantFactory.get_instance().
 
static
DomainParticipantConfigParams_t 
PARTICIPANT_CONFIG_PARAMS_DEFAULT
 Special value for creating a com.rti.dds.domain.DomainParticipant from configuration using default parameters.
 

Detailed Description

<<singleton>> <<interface>> Allows creation and destruction of com.rti.dds.domain.DomainParticipant objects.

The sole purpose of this class is to allow the creation and destruction of com.rti.dds.domain.DomainParticipant objects. This class itself is a <<singleton>>, and accessed via the get_instance() method, and destroyed with finalize_instance() method.

A single application can participate in multiple domains by instantiating multiple com.rti.dds.domain.DomainParticipant objects.

An application may even instantiate multiple participants in the same domain. Participants in the same domain exchange data in the same way regardless of whether they are in the same application or different applications or on the same node or different nodes; their location is transparent.

There are two important caveats:

  • When there are multiple participants on the same node (in the same application or different applications) in the same domain, the application(s) must make sure that the participants do not try to bind to the same port numbers. You must disambiguate between the participants by setting a participant ID for each participant (com.rti.dds.infrastructure.WireProtocolQosPolicy.participant_id). The port numbers used by a participant are calculated based on both the participant index and the domain ID, so if all participants on the same node have different participant indexes, they can coexist in the same domain.
  • You cannot mix entities from different participants. For example, you cannot delete a topic on a different participant than you created it from, and you cannot ask a subscriber to create a reader for a topic created from a participant different than the subscriber's own participant. (Note that it is permissable for an application built on top of RTI Connext to know about entities from different participants. For example, an application could keep references to a reader from one domain and a writer from another and then bridge the domains by writing the data received in the reader callback.)
See Also
com.rti.dds.domain.DomainParticipant

Member Function Documentation

static final DomainParticipantFactory get_instance ( )
static

Gets the singleton instance of this class.

MT Safety:
On non-Linux systems: UNSAFE for multiple threads to simultaneously make the FIRST call to either com.rti.dds.domain.DomainParticipantFactory.get_instance() or com.rti.dds.domain.DomainParticipantFactory.finalize_instance(). Subsequent calls are thread safe. (On Linux systems, these calls are thread safe.)

com.rti.dds.domain.DomainParticipantFactory.TheParticipantFactory can be used as an alias for the singleton factory returned by this operation.

Returns
The singleton com.rti.dds.domain.DomainParticipantFactory instance.
See Also
com.rti.dds.domain.DomainParticipantFactory.TheParticipantFactory
static final void finalize_instance ( )
static

<<extension>> Destroys the singleton instance of this class.

Only necessary to explicitly reclaim resources used by the participant factory singleton. Note that on many OSs, these resources are automatically reclaimed by the OS when the program terminates. However, some memory-check tools still flag these as unreclaimed. So this method provides a way to clean up memory used by the participant factory.

Precondition
All participants created from the factory have been deleted.
Postcondition
All resources belonging to the factory have been reclaimed. Another call to com.rti.dds.domain.DomainParticipantFactory.get_instance will return a new lifecycle of the singleton.
MT Safety:
On non-Linux systems: UNSAFE for multiple threads to simultaneously make the FIRST call to either com.rti.dds.domain.DomainParticipantFactory.get_instance() or com.rti.dds.domain.DomainParticipantFactory.finalize_instance(). Subsequent calls are thread safe. (On Linux systems, these calls are thread safe.)
Exceptions
Oneof the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET
abstract DomainParticipant create_participant ( int  domainId,
DomainParticipantQos  qos,
DomainParticipantListener  listener,
int  mask 
)
pure virtual

Creates a new com.rti.dds.domain.DomainParticipant object.

Precondition
The specified QoS policies must be consistent or the operation will fail and no com.rti.dds.domain.DomainParticipant will be created.

If you want to create multiple participants on a given host in the same domain, make sure each one has a different participant index (set in the com.rti.dds.infrastructure.WireProtocolQosPolicy). This in turn will ensure each participant uses a different port number (since the unicast port numbers are calculated from the participant index and the domain ID).

Note that if there is a single participant per host in a given domain, the participant index can be left at the default value (-1).

Parameters
domainId<<in>> ID of the domain that the application intends to join. [range] [>=0], and does not violate guidelines stated in com.rti.dds.infrastructure.RtpsWellKnownPorts_t.
qos<<in>> the DomainParticipant's QoS. The special value com.rti.dds.domain.DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT can be used to indicate that the com.rti.dds.domain.DomainParticipant should be created with the default com.rti.dds.domain.DomainParticipantQos set in the com.rti.dds.domain.DomainParticipantFactory. Cannot be NULL.
listener<<in>> the domain participant's listener.
mask<<in>>. Changes of communication status to be invoked on the listener. See com.rti.dds.infrastructure.StatusKind.
Returns
domain participant or NULL on failure
See Also
Specifying QoS on entities for information on setting QoS before entity creation
com.rti.dds.domain.DomainParticipantQos for rules on consistency among QoS
com.rti.dds.domain.DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT
NDDS_DISCOVERY_PEERS
com.rti.dds.domain.DomainParticipantFactory.create_participant_with_profile
com.rti.dds.domain.DomainParticipantFactory.get_default_participant_qos
com.rti.dds.domain.DomainParticipant.set_listener
abstract void delete_participant ( DomainParticipant  a_participant)
pure virtual

Deletes an existing com.rti.dds.domain.DomainParticipant.

Precondition
All domain entities belonging to the participant must have already been deleted. Otherwise it fails with the error com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.
Postcondition
Listener installed on the com.rti.dds.domain.DomainParticipant will not be called after this method returns successfully.
MT Safety:
UNSAFE. It is not safe to delete an entity while another thread may be simultaneously calling an API that uses the entity.
Parameters
a_participant<<in>> com.rti.dds.domain.DomainParticipant to be deleted.
Exceptions
Oneof the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.
abstract void get_default_participant_qos ( DomainParticipantQos  qos)
pure virtual

Initializes the com.rti.dds.domain.DomainParticipantQos instance with default values.

The retrieved qos will match the set of values specified on the last successful call to com.rti.dds.domain.DomainParticipantFactory.set_default_participant_qos, or com.rti.dds.domain.DomainParticipantFactory.set_default_participant_qos_with_profile, or else, if the call was never made, the default values listed in com.rti.dds.domain.DomainParticipantQos.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters
qos<<out>> the domain participant's QoS Cannot be NULL.
MT Safety:
UNSAFE. It is not safe to retrieve the default QoS value from a domain participant factory while another thread may be simultaneously calling com.rti.dds.domain.DomainParticipantFactory.set_default_participant_qos
Exceptions
Oneof the Standard Return Codes
See Also
com.rti.dds.domain.DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT
com.rti.dds.domain.DomainParticipantFactory.create_participant
abstract void set_default_participant_qos ( DomainParticipantQos  qos)
pure virtual

Sets the default com.rti.dds.domain.DomainParticipantQos values for this domain participant factory.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

MT Safety:
UNSAFE. It is not safe to retrieve the default QoS value from a domain participant factory while another thread may be simultaneously calling com.rti.dds.domain.DomainParticipantFactory.set_default_participant_qos
Parameters
qos<<inout>> Qos to be filled up. The special value com.rti.dds.domain.DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if com.rti.dds.domain.DomainParticipantFactory.set_default_participant_qos had never been called. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes
See Also
com.rti.dds.domain.DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT
com.rti.dds.domain.DomainParticipantFactory.create_participant
abstract void set_default_participant_qos_with_profile ( String  library_name,
String  profile_name 
)
pure virtual

<<extension>> Sets the default com.rti.dds.domain.DomainParticipantQos values for this domain participant factory based on the input XML QoS profile.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

This default value will be used for newly created com.rti.dds.domain.DomainParticipant if com.rti.dds.domain.DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT is specified as the qos parameter when com.rti.dds.domain.DomainParticipantFactory.create_participant is called.

Precondition
The com.rti.dds.domain.DomainParticipantQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY
MT Safety:
UNSAFE. It is not safe to retrieve the default QoS value from a domain participant factory while another thread may be simultaneously calling com.rti.dds.domain.DomainParticipantFactory.set_default_participant_qos
Parameters
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).

If the input profile cannot be found the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions
Oneof the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY
See Also
com.rti.dds.domain.DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT
com.rti.dds.domain.DomainParticipantFactory.create_participant_with_profile
abstract DomainParticipant lookup_participant ( int  domainId)
pure virtual

Locates an existing com.rti.dds.domain.DomainParticipant.

If no such com.rti.dds.domain.DomainParticipant exists, the operation will return NULL value.

If multiple com.rti.dds.domain.DomainParticipant entities belonging to that domainId exist, then the operation will return one of them. It is not specified which one.

Parameters
domainId<<in>> ID of the domain participant to lookup.
Returns
domain participant if it exists, or NULL
abstract void get_qos ( DomainParticipantFactoryQos  qos)
pure virtual

Gets the value for participant factory QoS.

Parameters
qos<<inout>> QoS to be filled up. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes
abstract void set_qos ( DomainParticipantFactoryQos  qos)
pure virtual

Sets the value for a participant factory QoS.

The com.rti.dds.domain.DomainParticipantFactoryQos.entity_factory can be changed. The other policies are immutable.

Note that despite having QoS, the com.rti.dds.domain.DomainParticipantFactory is not an com.rti.dds.infrastructure.Entity.

Parameters
qos<<in>> Set of policies to be applied to com.rti.dds.domain.DomainParticipantFactory. Policies must be consistent. Immutable policies can only be changed before calling any other RTI Connext methods except for com.rti.dds.domain.DomainParticipantFactory.get_qos Cannot be NULL.
Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_IMMUTABLE_POLICY if immutable policy is changed, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY if policies are inconsistent
See Also
com.rti.dds.domain.DomainParticipantFactoryQos for rules on consistency among QoS
abstract void load_profiles ( )
pure virtual

<<extension>> Loads the XML QoS profiles.

The XML QoS profiles are loaded implicitly after the first com.rti.dds.domain.DomainParticipant is created or explicitly, after a call to this method.

This has the same effect as com.rti.dds.domain.DomainParticipantFactory.reload_profiles().

Exceptions
Oneof the Standard Return Codes
See Also
com.rti.dds.infrastructure.ProfileQosPolicy
abstract void reload_profiles ( )
pure virtual

<<extension>> Reloads the XML QoS profiles.

The XML QoS profiles are loaded implicitly after the first com.rti.dds.domain.DomainParticipant is created or explicitly, after a call to this method.

This has the same effect as com.rti.dds.domain.DomainParticipantFactory.load_profiles().

Exceptions
Oneof the Standard Return Codes
See Also
com.rti.dds.infrastructure.ProfileQosPolicy
abstract void unload_profiles ( )
pure virtual

<<extension>> Unloads the XML QoS profiles.

The resources associated with the XML QoS profiles are freed. Any reference to the profiles after calling this method will fail with an error.

Exceptions
Oneof the Standard Return Codes
See Also
com.rti.dds.infrastructure.ProfileQosPolicy
abstract String get_default_library ( )
pure virtual

<<extension>> Gets the default XML library associated with a com.rti.dds.domain.DomainParticipantFactory.

Returns
The default library or null if the default library was not set.
See Also
com.rti.dds.domain.DomainParticipantFactory.set_default_library
abstract void set_default_library ( String  library_name)
pure virtual

<<extension>> Sets the default XML library for a com.rti.dds.domain.DomainParticipantFactory.

Any API requiring a library_name as a parameter can use null to refer to the default library.

See Also
com.rti.dds.domain.DomainParticipantFactory.set_default_profile for more information.
Parameters
library_name<<in>> Library name. If library_name is null any previous default is unset.
Exceptions
Oneof the Standard Return Codes
See Also
com.rti.dds.domain.DomainParticipantFactory.get_default_library
abstract String get_default_profile ( )
pure virtual

<<extension>> Gets the default XML profile associated with a com.rti.dds.domain.DomainParticipantFactory.

Returns
The default profile or null if the default profile was not set.
See Also
com.rti.dds.domain.DomainParticipantFactory.set_default_profile
abstract void set_default_profile ( String  library_name,
String  profile_name 
)
pure virtual

<<extension>> Sets the default XML profile for a com.rti.dds.domain.DomainParticipantFactory.

This method specifies the profile that will be used as the default the next time a default DomainParticipantFactory profile is needed during a call to a DomainParticipantFactory method. When calling a com.rti.dds.domain.DomainParticipantFactory method that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)

This method does not set the default QoS for newly created DomainParticipants; for this functionality, use com.rti.dds.domain.DomainParticipantFactory.set_default_participant_qos_with_profile (you may pass in NULL after having called set_default_profile()).

Parameters
library_name<<in>> The library name containing the profile.
profile_name<<in>> The profile name. If profile_name is null any previous default is unset.
Exceptions
Oneof the Standard Return Codes
See Also
com.rti.dds.domain.DomainParticipantFactory.get_default_profile
com.rti.dds.domain.DomainParticipantFactory.get_default_profile_library
abstract String get_default_profile_library ( )
pure virtual

<<extension>> Gets the library where the default XML profile is contained for a com.rti.dds.domain.DomainParticipantFactory.

The default profile library is automatically set when com.rti.dds.domain.DomainParticipantFactory.set_default_profile is called.

This library can be different than the com.rti.dds.domain.DomainParticipantFactory default library (see com.rti.dds.domain.DomainParticipantFactory.get_default_library).

Returns
The default profile library or null if the default profile was not set.
See Also
com.rti.dds.domain.DomainParticipantFactory.set_default_profile
abstract void get_participant_factory_qos_from_profile ( DomainParticipantFactoryQos  qos,
String  library_name,
String  profile_name 
)
pure virtual

<<extension>> Gets the com.rti.dds.domain.DomainParticipantFactoryQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).

If the input profile cannot be found, the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions
Oneof the Standard Return Codes
abstract void get_participant_qos_from_profile ( DomainParticipantQos  qos,
String  library_name,
String  profile_name 
)
pure virtual

<<extension>> Gets the com.rti.dds.domain.DomainParticipantQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).

If the input profile cannot be found, the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions
Oneof the Standard Return Codes
abstract void get_publisher_qos_from_profile ( PublisherQos  qos,
String  library_name,
String  profile_name 
)
pure virtual

<<extension>> Gets the com.rti.dds.publication.PublisherQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).

If the input profile cannot be found, the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions
Oneof the Standard Return Codes
abstract void get_subscriber_qos_from_profile ( SubscriberQos  qos,
String  library_name,
String  profile_name 
)
pure virtual

<<extension>> Gets the com.rti.dds.subscription.SubscriberQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).

If the input profile cannot be found, the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions
Oneof the Standard Return Codes
abstract void get_datawriter_qos_from_profile ( DataWriterQos  qos,
String  library_name,
String  profile_name 
)
pure virtual

<<extension>> Gets the com.rti.dds.publication.DataWriterQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).

If the input profile cannot be found, the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions
Oneof the Standard Return Codes
abstract void get_datawriter_qos_from_profile_w_topic_name ( DataWriterQos  qos,
String  library_name,
String  profile_name,
String  topic_name 
)
pure virtual

<<extension>> Gets the com.rti.dds.publication.DataWriterQos values associated with the input XML QoS profile while applying topic filters to the input topic name.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).
topic_name<<in>> Topic name that will be evaluated against the topic_filter attribute in the XML QoS profile. If topic_name is null, RTI Connext will match only QoSs without explicit topic_filter expressions.

If the input profile cannot be found, the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions
Oneof the Standard Return Codes
abstract void get_datareader_qos_from_profile ( DataReaderQos  qos,
String  library_name,
String  profile_name 
)
pure virtual

<<extension>> Gets the com.rti.dds.subscription.DataReaderQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).

If the input profile cannot be found, the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions
Oneof the Standard Return Codes
abstract void get_datareader_qos_from_profile_w_topic_name ( DataReaderQos  qos,
String  library_name,
String  profile_name,
String  topic_name 
)
pure virtual

<<extension>> Gets the com.rti.dds.subscription.DataReaderQos values associated with the input XML QoS profile while applying topic filters to the input topic name.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).
topic_name<<in>> Topic name that will be evaluated against the topic_filter attribute in the XML QoS profile. If topic_name is null, RTI Connext will match only QoSs without explicit topic_filter expressions.

If the input profile cannot be found, the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions
Oneof the Standard Return Codes
abstract void get_topic_qos_from_profile ( TopicQos  qos,
String  library_name,
String  profile_name 
)
pure virtual

<<extension>> Gets the com.rti.dds.topic.TopicQos values associated with the input XML QoS profile.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).

If the input profile cannot be found, the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions
Oneof the Standard Return Codes
abstract void get_topic_qos_from_profile_w_topic_name ( TopicQos  qos,
String  library_name,
String  profile_name,
String  topic_name 
)
pure virtual

<<extension>> Gets the com.rti.dds.topic.TopicQos values associated with the input XML QoS profile while applying topic filters to the input topic name.

Parameters
qos<<out>> Qos to be filled up. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).
topic_name<<in>> Topic name that will be evaluated against the topic_filter attribute in the XML QoS profile. If topic_name is null, RTI Connext will match only QoSs without explicit topic_filter expressions.

If the input profile cannot be found, the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions
Oneof the Standard Return Codes
abstract void get_qos_profile_libraries ( StringSeq  library_names)
pure virtual

<<extension>> Gets the names of all XML QoS profile libraries associated with the com.rti.dds.domain.DomainParticipantFactory

Parameters
library_names<<out>> com.rti.dds.infrastructure.StringSeq to be filled with names of XML QoS profile libraries. Cannot be NULL.
abstract void get_qos_profiles ( StringSeq  profile_names,
String  library_name 
)
pure virtual

<<extension>> Gets the names of all XML QoS profiles associated with the input XML QoS profile library.

Parameters
profile_names<<out>> com.rti.dds.infrastructure.StringSeq to be filled with names of XML QoS profiles. Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
abstract DomainParticipant create_participant_with_profile ( int  domainId,
String  library_name,
String  profile_name,
DomainParticipantListener  listener,
int  mask 
)
pure virtual

<<extension>> Creates a new com.rti.dds.domain.DomainParticipant object using the com.rti.dds.domain.DomainParticipantQos associated with the input XML QoS profile.

Precondition
The com.rti.dds.domain.DomainParticipantQos in the input profile must be consistent, or the operation will fail and no com.rti.dds.domain.DomainParticipant will be created.

If you want to create multiple participants on a given host in the same domain, make sure each one has a different participant index (set in the com.rti.dds.infrastructure.WireProtocolQosPolicy). This in turn will ensure each participant uses a different port number (since the unicast port numbers are calculated from the participant index and the domain ID).

Note that if there is a single participant per host in a given domain, the participant index can be left at the default value (-1).

Parameters
domainId<<in>> ID of the domain that the application intends to join. [range] [>=0], and does not violate guidelines stated in com.rti.dds.infrastructure.RtpsWellKnownPorts_t.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.domain.DomainParticipantFactory.set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.domain.DomainParticipantFactory.set_default_profile).
listener<<in>> the DomainParticipant's listener.
mask<<in>>. Changes of communication status to be invoked on the listener. See com.rti.dds.infrastructure.StatusKind.
Returns
domain participant or NULL on failure
See Also
Specifying QoS on entities for information on setting QoS before entity creation
com.rti.dds.domain.DomainParticipantQos for rules on consistency among QoS
com.rti.dds.domain.DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT
NDDS_DISCOVERY_PEERS
com.rti.dds.domain.DomainParticipantFactory.create_participant()
com.rti.dds.domain.DomainParticipantFactory.get_default_participant_qos()
com.rti.dds.domain.DomainParticipant.set_listener()
abstract void unregister_thread ( )
pure virtual

<<extension>> Allows the user to release thread specific resources kept by the middleware.

This function should be called by the user right before exiting a thread where DDS API were used. In this way the middleware will be able to free all the resources related to this specific thread. The best approach is to call the function during the thread deletion after all the DDS related API have have been called.

Exceptions
Oneof the Standard Return Codes
abstract DomainParticipant create_participant_from_config ( String  configuration_name)
pure virtual

<<extension>> Creates a com.rti.dds.domain.DomainParticipant given its configuration name from a description provided in an XML configuration file.

This operation creates a com.rti.dds.domain.DomainParticipant registering all the necessary data types and creating all the contained entities (com.rti.dds.topic.Topic, com.rti.dds.publication.Publisher, com.rti.dds.subscription.Subscriber, com.rti.dds.publication.DataWriter, com.rti.dds.subscription.DataReader) from a description given in an XML configuration file.

The configuration name is the fully qualified name of the XML participant object, consisting of the name of the participant library plus the name of participant configuration.

For example the name "MyParticipantLibrary::PublicationParticipant" can be used to create the domain participant from the description in an XML file with contents shown in the snippet below:

<participant_library name="MyParticipantLibrary">
<domain_participant name="PublicationParticipant" domain_ref="MyDomainLibrary::HelloWorldDomain">
<publisher name="MyPublisher">
<data_writer name="HelloWorldWriter" topic_ref="HelloWorldTopic"/>
</publisher>
</domain_participant>
</participant_library>

The entities belonging to the newly created com.rti.dds.domain.DomainParticipant can be retrieved with the help of lookup operations such as: com.rti.dds.domain.DomainParticipant.lookup_datareader_by_name.

This operation is equivalent to call com.rti.dds.domain.DomainParticipantFactory.create_participant_from_config_w_params passing com.rti.dds.domain.DomainParticipantFactory.PARTICIPANT_CONFIG_PARAMS_DEFAULT as parameters.

Parameters
configuration_name<<in>> Name of the participant configuration in the XML file.
Returns
The created com.rti.dds.domain.DomainParticipant or NULL on error.
See Also
com.rti.dds.domain.DomainParticipantFactory.lookup_participant_by_name
com.rti.dds.domain.DomainParticipant.lookup_topicdescription
com.rti.dds.domain.DomainParticipant.lookup_publisher_by_name
com.rti.dds.domain.DomainParticipant.lookup_subscriber_by_name
com.rti.dds.domain.DomainParticipant.lookup_datareader_by_name
com.rti.dds.domain.DomainParticipant.lookup_datawriter_by_name
com.rti.dds.publication.Publisher.lookup_datawriter_by_name
com.rti.dds.subscription.Subscriber.lookup_datareader_by_name
abstract DomainParticipant create_participant_from_config_w_params ( String  configuration_name,
DomainParticipantConfigParams_t  params 
)
pure virtual

<<extension>> Creates a com.rti.dds.domain.DomainParticipant given its configuration name from a description provided in an XML configuration file and a set of parameters that allow chaging some properties of such configuration.

The operation will create a com.rti.dds.domain.DomainParticipant the same way specified in com.rti.dds.domain.DomainParticipantFactory.create_participant_from_config.

In addition, this operation allows overriding the domain ID, participant name, and entities QoS specified in the configuration.

Parameters
configuration_name<<in>> Name of the participant configuration in the XML file.
params<<in>> input parameters that allow changing some properties of the configuration referred to by configuration_name.
Returns
The created com.rti.dds.domain.DomainParticipant or NULL on error.
abstract DomainParticipant lookup_participant_by_name ( String  participant_name)
pure virtual

<<extension>> Looks up a com.rti.dds.domain.DomainParticipant by its entity name in the com.rti.dds.domain.DomainParticipantFactory.

Every com.rti.dds.domain.DomainParticipant in the system has an entity name which is configured and stored in the EntityName policy, ENTITY_NAME.

This operation retrieves a com.rti.dds.domain.DomainParticipant within the com.rti.dds.domain.DomainParticipantFactory given the entity's name. If there are several com.rti.dds.domain.DomainParticipant with the same name within the com.rti.dds.domain.DomainParticipantFactory this function returns the first matching occurrence.

Parameters
participant_name<<in>> Entity name of the com.rti.dds.domain.DomainParticipant.
Returns
The first com.rti.dds.domain.DomainParticipant found with the specified name or NULL if it is not found.
abstract void register_type_support ( TypeSupport  type_support,
String  type_name 
)
pure virtual

<<extension>> Registers a com.rti.dds.topic.TypeSupport with the com.rti.dds.domain.DomainParticipantFactory to enable automatic registration if the corresponding type, should it be needed by a com.rti.dds.domain.DomainParticipant.

Types refered by the com.rti.dds.topic.Topic entities within a com.rti.dds.domain.DomainParticipant must be registered with the com.rti.dds.domain.DomainParticipant.

Type registration in a com.rti.dds.domain.DomainParticipant is performed by a call to the com.rti.ndds.example.FooTypeSupport.register_type operation. This can be done directly from the application code or indirectly by the RTI Connext infrastructure as a result of parsing an XML configuration file that refers to that type.

The com.rti.dds.domain.DomainParticipantFactory.register_type_support operation provides the com.rti.dds.domain.DomainParticipantFactory with the information it needs to automatically call the com.rti.ndds.example.FooTypeSupport.register_type operation and register the corresponding type if the type is needed as a result of parsing an XML configuration file.

Automatic type registration while parsing XML files can also be done by the RTI Connext infrastructure based on the type description provided in the XML files. If the com.rti.dds.topic.TypeSupport has been registered with the com.rti.dds.domain.DomainParticipantFactory this definition takes precedence over the description of the type given in the XML file.

The com.rti.dds.domain.DomainParticipantFactory.register_type_support operation receives a com.rti.ndds.example.FooTypeSupport object as a parameter. This object's class is normally generated using rtiddsgen from a description of the corresponsing type in IDL, XML, or XSD.

The typical workflow when using this function is as follows: Define the data-type in IDL (or XML, or XSD) in a file. E.g. Foo.idl Run rtiddsgen in that file to generate the TypeSupport files, for the desired programming language. E.g. in C++ FooTypeSupport.h FooTypeSupport.cxx Include the proper header file (e.g. FooTypeSupport.h) in your program and call com.rti.dds.domain.DomainParticipantFactory.register_type_support passing the function that was generated by rtiddsgen. E.g. FooTypeSupport::register_type Include the TypeSupport source file in your project such that it is compiled and linked. E.g. FooTypeSupport.cxx

You may refer to the Getting Started Guide for additional details in this process.

Note that only one register function is allowed per registered type name.

Parameters
type_support<<in>> com.rti.dds.topic.TypeSupport object to be used for registering the type with a com.rti.dds.domain.DomainParticipant.
Parameters
type_name<<in>> Name the type is registered with.
Exceptions
Oneof the Standard Return Codes

RTI Connext Java API Version 5.3.1 Copyright © Mon Feb 19 2018 Real-Time Innovations, Inc