RTI Connext Java API  Version 5.2.0
 All Classes Namespaces Functions Variables Groups Pages
Publisher Interface Reference

<<interface>> A publisher is the object responsible for the actual dissemination of publications. More...

Inheritance diagram for Publisher:
DomainEntity Entity

Public Member Functions

void get_default_datawriter_qos (DataWriterQos qos)
 Copies the default com.rti.dds.publication.DataWriterQos values into the provided com.rti.dds.publication.DataWriterQos instance.
 
void set_default_datawriter_qos (DataWriterQos qos)
 Sets the default com.rti.dds.publication.DataWriterQos values for this publisher.
 
void set_default_datawriter_qos_with_profile (String library_name, String profile_name)
 <<extension>> Set the default com.rti.dds.publication.DataWriterQos values for this publisher based on the input XML QoS profile.
 
DataWriter create_datawriter (Topic topic, DataWriterQos qos, DataWriterListener listener, int mask)
 Creates a com.rti.dds.publication.DataWriter that will be attached and belong to the com.rti.dds.publication.Publisher.
 
DataWriter create_datawriter_with_profile (Topic topic, String library_name, String profile_name, DataWriterListener listener, int mask)
 <<extension>> Creates a com.rti.dds.publication.DataWriter object using the com.rti.dds.publication.DataWriterQos associated with the input XML QoS profile.
 
void delete_datawriter (DataWriter a_datawriter)
 Deletes a com.rti.dds.publication.DataWriter that belongs to the com.rti.dds.publication.Publisher.
 
DataWriter lookup_datawriter (String topic_name)
 Retrieves the com.rti.dds.publication.DataWriter for a specific com.rti.dds.topic.Topic.
 
void set_qos (PublisherQos qos)
 Sets the publisher QoS.
 
void set_qos_with_profile (String library_name, String profile_name)
 <<extension>> Change the QoS of this publisher using the input XML QoS profile.
 
void get_qos (PublisherQos qos)
 Gets the publisher QoS.
 
String get_default_library ()
 <<extension>> Gets the default XML library associated with a com.rti.dds.publication.Publisher.
 
void set_default_library (String library_name)
 <<extension>> Sets the default XML library for a com.rti.dds.publication.Publisher.
 
String get_default_profile ()
 <<extension>> Gets the default XML profile associated with a com.rti.dds.publication.Publisher.
 
void set_default_profile (String library_name, String profile_name)
 <<extension>> Sets the default XML profile for a com.rti.dds.publication.Publisher.
 
String get_default_profile_library ()
 <<extension>> Gets the library where the default XML QoS profile is contained for a com.rti.dds.publication.Publisher.
 
void set_listener (PublisherListener l, int mask)
 Sets the publisher listener.
 
PublisherListener get_listener ()
 Get the publisher listener.
 
void suspend_publications ()
 Indicates to RTI Connext that the application is about to make multiple modifications using com.rti.dds.publication.DataWriter objects belonging to the com.rti.dds.publication.Publisher.
 
void resume_publications ()
 Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous com.rti.dds.publication.Publisher.suspend_publications.
 
void begin_coherent_changes ()
 Indicates that the application will begin a coherent set of modifications using com.rti.dds.publication.DataWriter objects attached to the com.rti.dds.publication.Publisher.
 
void end_coherent_changes ()
 Terminates the coherent set initiated by the matching call to com.rti.dds.publication.Publisher.begin_coherent_changes.
 
void copy_from_topic_qos (DataWriterQos a_datawriter_qos, TopicQos a_topic_qos)
 Copies the policies in the com.rti.dds.topic.TopicQos to the corresponding policies in the com.rti.dds.publication.DataWriterQos.
 
void get_all_datawriters (DataWriterSeq writers)
 Retrieve all the DataWriters created from this Publisher.
 
DomainParticipant get_participant ()
 Returns the com.rti.dds.domain.DomainParticipant to which the com.rti.dds.publication.Publisher belongs.
 
void delete_contained_entities ()
 Deletes all the entities that were created by means of the "create" operation on the com.rti.dds.publication.Publisher.
 
void wait_for_acknowledgments (Duration_t max_wait)
 Blocks the calling thread until all data written by the Publisher's reliable DataWriters is acknowledged, or until timeout expires.
 
void wait_for_asynchronous_publishing (Duration_t max_wait)
 <<extension>> Blocks the calling thread until asynchronous sending is complete.
 
DataWriter lookup_datawriter_by_name (String datawriter_name)
 <<extension>> Retrieves a com.rti.dds.publication.DataWriter contained within the com.rti.dds.publication.Publisher the com.rti.dds.publication.DataWriter entity name.
 

Static Public Attributes

static final DataWriterQos DATAWRITER_QOS_DEFAULT
 Special value for creating com.rti.dds.publication.DataWriter with default QoS.
 
static final DataWriterQos DATAWRITER_QOS_USE_TOPIC_QOS = new DataWriterQos()
 Special value for creating com.rti.dds.publication.DataWriter with a combination of the default com.rti.dds.publication.DataWriterQos and the com.rti.dds.topic.TopicQos.
 

Detailed Description

<<interface>> A publisher is the object responsible for the actual dissemination of publications.

QoS:
com.rti.dds.publication.PublisherQos
Listener:
com.rti.dds.publication.PublisherListener

A publisher acts on the behalf of one or several com.rti.dds.publication.DataWriter objects that belong to it. When it is informed of a change to the data associated with one of its com.rti.dds.publication.DataWriter objects, it decides when it is appropriate to actually send the data-update message. In making this decision, it considers any extra information that goes with the data (timestamp, writer, etc.) as well as the QoS of the com.rti.dds.publication.Publisher and the com.rti.dds.publication.DataWriter.

The following operations may be called even if the com.rti.dds.publication.Publisher is not enabled. Other operations will fail with the value com.rti.dds.infrastructure.RETCODE_NOT_ENABLED if called on a disabled com.rti.dds.publication.Publisher:

See Also
Operations Allowed in Listener Callbacks

Member Function Documentation

void get_default_datawriter_qos ( DataWriterQos  qos)

Copies the default com.rti.dds.publication.DataWriterQos values into the provided com.rti.dds.publication.DataWriterQos instance.

The retrieved qos will match the set of values specified on the last successful call to com.rti.dds.publication.Publisher.set_default_datawriter_qos or com.rti.dds.publication.Publisher.set_default_datawriter_qos_with_profile, or else, if the call was never made, the default values from its owning com.rti.dds.domain.DomainParticipant.

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 com.rti.dds.publication.Publisher while another thread may be simultaneously calling com.rti.dds.publication.Publisher.set_default_datawriter_qos.
Parameters
qos<<inout>> com.rti.dds.publication.DataWriterQos to be filled-up. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes
See Also
com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT
com.rti.dds.publication.Publisher.create_datawriter
void set_default_datawriter_qos ( DataWriterQos  qos)

Sets the default com.rti.dds.publication.DataWriterQos values for this publisher.

This call causes the default values inherited from the owning com.rti.dds.domain.DomainParticipant to be overridden.

This default value will be used for newly created com.rti.dds.publication.DataWriter if com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT is specified as the qos parameter when com.rti.dds.publication.Publisher.create_datawriter is called.

Precondition
The specified QoS policies 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 set the default QoS value from a com.rti.dds.publication.Publisher while another thread may be simultaneously calling com.rti.dds.publication.Publisher.set_default_datawriter_qos, com.rti.dds.publication.Publisher.get_default_datawriter_qos or calling com.rti.dds.publication.Publisher.create_datawriter with com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT as the qos parameter.
Parameters
qos<<in>> Default qos to be set. The special value com.rti.dds.subscription.Subscriber.DATAREADER_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.publication.Publisher.set_default_datawriter_qos had never been called. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY
void set_default_datawriter_qos_with_profile ( String  library_name,
String  profile_name 
)

<<extension>> Set the default com.rti.dds.publication.DataWriterQos values for this publisher based on the input XML QoS profile.

This default value will be used for newly created com.rti.dds.publication.DataWriter if com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT is specified as the qos parameter when com.rti.dds.publication.Publisher.create_datawriter is called.

Precondition
The com.rti.dds.publication.DataWriterQos 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 set the default QoS value from a com.rti.dds.publication.Publisher while another thread may be simultaneously calling com.rti.dds.publication.Publisher.set_default_datawriter_qos, com.rti.dds.publication.Publisher.get_default_datawriter_qos or calling com.rti.dds.publication.Publisher.create_datawriter with com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT as the qos parameter.
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.publication.Publisher.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.publication.Publisher.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.publication.Publisher.DATAWRITER_QOS_DEFAULT
com.rti.dds.publication.Publisher.create_datawriter_with_profile
DataWriter create_datawriter ( Topic  topic,
DataWriterQos  qos,
DataWriterListener  listener,
int  mask 
)

Creates a com.rti.dds.publication.DataWriter that will be attached and belong to the com.rti.dds.publication.Publisher.

For each application-defined type, com.rti.ndds.example.Foo, there is an implied, auto-generated class com.rti.ndds.example.FooDataWriter that extends com.rti.dds.publication.DataWriter and contains the operations to write data of type com.rti.ndds.example.Foo.

Note that a common application pattern to construct the QoS for the com.rti.dds.publication.DataWriter is to:

When a com.rti.dds.publication.DataWriter is created, only those transports already registered are available to the com.rti.dds.publication.DataWriter. See Built-in Transport Plugins for details on when a builtin transport is registered.

Precondition
If publisher is enabled, topic must have been enabled. Otherwise, this operation will fail and no com.rti.dds.publication.DataWriter will be created.
The given com.rti.dds.topic.Topic must have been created from the same participant as this publisher. If it was created from a different participant, this method will fail.
MT Safety:
UNSAFE. If com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the datawriter while another thread may be simultaneously calling com.rti.dds.publication.Publisher.set_default_datawriter_qos.
Parameters
topic<<in>> The com.rti.dds.topic.Topic that the com.rti.dds.publication.DataWriter will be associated with. Cannot be NULL.
qos<<in>> QoS to be used for creating the new com.rti.dds.publication.DataWriter. The special value com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT can be used to indicate that the com.rti.dds.publication.DataWriter should be created with the default com.rti.dds.publication.DataWriterQos set in the com.rti.dds.publication.Publisher. The special value com.rti.dds.publication.Publisher.DATAWRITER_QOS_USE_TOPIC_QOS can be used to indicate that the com.rti.dds.publication.DataWriter should be created with the combination of the default com.rti.dds.publication.DataWriterQos set on the com.rti.dds.publication.Publisher and the com.rti.dds.topic.TopicQos of the com.rti.dds.topic.Topic. Cannot be NULL.
listener<<in>> The listener of the com.rti.dds.publication.DataWriter.
mask<<in>>. Changes of communication status to be invoked on the listener. See com.rti.dds.infrastructure.StatusMask.
Returns
A com.rti.dds.publication.DataWriter of a derived class specific to the data type associated with the com.rti.dds.topic.Topic or NULL if an error occurred.
See Also
com.rti.ndds.example.FooDataWriter
Specifying QoS on entities for information on setting QoS before entity creation
com.rti.dds.publication.DataWriterQos for rules on consistency among QoS
com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT
com.rti.dds.publication.Publisher.DATAWRITER_QOS_USE_TOPIC_QOS
com.rti.dds.publication.Publisher.create_datawriter_with_profile
com.rti.dds.publication.Publisher.get_default_datawriter_qos
com.rti.dds.topic.Topic.set_qos
com.rti.dds.publication.Publisher.copy_from_topic_qos
com.rti.dds.publication.DataWriter.set_listener
DataWriter create_datawriter_with_profile ( Topic  topic,
String  library_name,
String  profile_name,
DataWriterListener  listener,
int  mask 
)

<<extension>> Creates a com.rti.dds.publication.DataWriter object using the com.rti.dds.publication.DataWriterQos associated with the input XML QoS profile.

The com.rti.dds.publication.DataWriter will be attached and belong to the com.rti.dds.publication.Publisher.

For each application-defined type, com.rti.ndds.example.Foo, there is an implied, auto-generated class com.rti.ndds.example.FooDataWriter that extends com.rti.dds.publication.DataWriter and contains the operations to write data of type com.rti.ndds.example.Foo.

When a com.rti.dds.publication.DataWriter is created, only those transports already registered are available to the com.rti.dds.publication.DataWriter. See Built-in Transport Plugins for details on when a builtin transport is registered.

Precondition
If publisher is enabled, topic must have been enabled. Otherwise, this operation will fail and no com.rti.dds.publication.DataWriter will be created.
The given com.rti.dds.topic.Topic must have been created from the same participant as this publisher. If it was created from a different participant, this method will return NULL.
Parameters
topic<<in>> The com.rti.dds.topic.Topic that the com.rti.dds.publication.DataWriter will be associated with. 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.publication.Publisher.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.publication.Publisher.set_default_profile).
listener<<in>> The listener of the com.rti.dds.publication.DataWriter.
mask<<in>>. Changes of communication status to be invoked on the listener. See com.rti.dds.infrastructure.StatusMask.
Returns
A com.rti.dds.publication.DataWriter of a derived class specific to the data type associated with the com.rti.dds.topic.Topic or NULL if an error occurred.
See Also
com.rti.ndds.example.FooDataWriter
Specifying QoS on entities for information on setting QoS before entity creation
com.rti.dds.publication.DataWriterQos for rules on consistency among QoS
com.rti.dds.publication.Publisher.create_datawriter
com.rti.dds.publication.Publisher.get_default_datawriter_qos
com.rti.dds.topic.Topic.set_qos
com.rti.dds.publication.Publisher.copy_from_topic_qos
com.rti.dds.publication.DataWriter.set_listener
void delete_datawriter ( DataWriter  a_datawriter)

Deletes a com.rti.dds.publication.DataWriter that belongs to the com.rti.dds.publication.Publisher.

The deletion of the com.rti.dds.publication.DataWriter will automatically unregister all instances. Depending on the settings of the WRITER_DATA_LIFECYCLE QosPolicy, the deletion of the com.rti.dds.publication.DataWriter may also dispose all instances.

Special Instructions if Using 'Timestamp' APIs and BY_SOURCE_TIMESTAMP Destination Ordering:

If the DataWriter's com.rti.dds.infrastructure.DestinationOrderQosPolicy.kind is com.rti.dds.infrastructure.DestinationOrderQosPolicyKind.DestinationOrderQosPolicyKind.BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, deleting the DataWriter may fail if your application has previously used the operations that receive a timestamp (com.rti.ndds.example.FooDataWriter.write_w_timestamp, com.rti.ndds.example.FooDataWriter.register_instance_w_timestamp, com.rti.ndds.example.FooDataWriter.FooDataWriter.unregister_instance_w_timestamp, or com.rti.ndds.example.FooDataWriter.dispose_w_timestamp) with a timestamp larger (later) than the time at which the writer is deleted. To prevent the deletion from failing in this situation, either:

Precondition
If the com.rti.dds.publication.DataWriter does not belong to the com.rti.dds.publication.Publisher, the operation will fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.
Postcondition
Listener installed on the com.rti.dds.publication.DataWriter will not be called after this method completes successfully.
Parameters
a_datawriter<<in>> The com.rti.dds.publication.DataWriter to be deleted. One of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.
DataWriter lookup_datawriter ( String  topic_name)

Retrieves the com.rti.dds.publication.DataWriter for a specific com.rti.dds.topic.Topic.

This returned com.rti.dds.publication.DataWriter is either enabled or disabled.

If more than one com.rti.dds.publication.DataWriter is attached to the com.rti.dds.publication.Publisher with the same topic_name, then this operation may return any one of them.

MT Safety:
UNSAFE. It is not safe to lookup a com.rti.dds.publication.DataWriter in one thread while another thread is simultaneously creating or destroying that com.rti.dds.publication.DataWriter.
Parameters
topic_name<<in>> Name of the com.rti.dds.topic.Topic associated with the com.rti.dds.publication.DataWriter that is to be looked up. Cannot be NULL.
Returns
A com.rti.dds.publication.DataWriter that belongs to the com.rti.dds.publication.Publisher attached to the com.rti.dds.topic.Topic with topic_name. If no such com.rti.dds.publication.DataWriter exists, this operation returns NULL.
void set_qos ( PublisherQos  qos)

Sets the publisher QoS.

This operation modifies the QoS of the com.rti.dds.publication.Publisher.

The com.rti.dds.publication.PublisherQos.group_data, com.rti.dds.publication.PublisherQos.partition and com.rti.dds.publication.PublisherQos.entity_factory can be changed. The other policies are immutable.

Parameters
qos<<in>> com.rti.dds.publication.PublisherQos to be set to. Policies must be consistent. Immutable policies cannot be changed after com.rti.dds.publication.Publisher is enabled. The special value com.rti.dds.domain.DomainParticipant.PUBLISHER_QOS_DEFAULT can be used to indicate that the QoS of the com.rti.dds.publication.Publisher should be changed to match the current default com.rti.dds.publication.PublisherQos set in the com.rti.dds.domain.DomainParticipant. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_IMMUTABLE_POLICY, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY.
See Also
com.rti.dds.publication.PublisherQos for rules on consistency among QoS
set_qos (abstract)
Operations Allowed in Listener Callbacks
void set_qos_with_profile ( String  library_name,
String  profile_name 
)

<<extension>> Change the QoS of this publisher using the input XML QoS profile.

This operation modifies the QoS of the com.rti.dds.publication.Publisher.

The com.rti.dds.publication.PublisherQos.group_data, com.rti.dds.publication.PublisherQos.partition and com.rti.dds.publication.PublisherQos.entity_factory can be changed. The other policies are immutable.

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.publication.Publisher.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.publication.Publisher.set_default_profile).
Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_IMMUTABLE_POLICY, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY.
See Also
com.rti.dds.publication.PublisherQos for rules on consistency among QoS
Operations Allowed in Listener Callbacks
void get_qos ( PublisherQos  qos)

Gets the publisher QoS.

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

Parameters
qos<<in>> com.rti.dds.publication.PublisherQos to be filled in. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes
See Also
get_qos (abstract)
String get_default_library ( )

<<extension>> Gets the default XML library associated with a com.rti.dds.publication.Publisher.

Returns
The default library or null if the default library was not set.
See Also
com.rti.dds.publication.Publisher.set_default_library
void set_default_library ( String  library_name)

<<extension>> Sets the default XML library for a com.rti.dds.publication.Publisher.

This method specifies the library that will be used as the default the next time a default library is needed during a call to one of this Publisher's operations.

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

If the default library is not set, the com.rti.dds.publication.Publisher inherits the default from the com.rti.dds.domain.DomainParticipant (see com.rti.dds.domain.DomainParticipant.set_default_library).

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.publication.Publisher.get_default_library
String get_default_profile ( )

<<extension>> Gets the default XML profile associated with a com.rti.dds.publication.Publisher.

Returns
The default profile or null if the default profile was not set.
See Also
com.rti.dds.publication.Publisher.set_default_profile
void set_default_profile ( String  library_name,
String  profile_name 
)

<<extension>> Sets the default XML profile for a com.rti.dds.publication.Publisher.

This method specifies the profile that will be used as the default the next time a default Publisher profile is needed during a call to one of this Publisher's operations. When calling a com.rti.dds.publication.Publisher 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.)

If the default profile is not set, the com.rti.dds.publication.Publisher inherits the default from the com.rti.dds.domain.DomainParticipant (see com.rti.dds.domain.DomainParticipant.set_default_profile).

This method does not set the default QoS for com.rti.dds.publication.DataWriter objects created by the com.rti.dds.publication.Publisher; for this functionality, use com.rti.dds.publication.Publisher.set_default_datawriter_qos_with_profile (you may pass in NULL after having called set_default_profile()).

This method does not set the default QoS for newly created Publishers; for this functionality, use com.rti.dds.domain.DomainParticipant.set_default_publisher_qos_with_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.publication.Publisher.get_default_profile
com.rti.dds.publication.Publisher.get_default_profile_library
String get_default_profile_library ( )

<<extension>> Gets the library where the default XML QoS profile is contained for a com.rti.dds.publication.Publisher.

The default profile library is automatically set when com.rti.dds.publication.Publisher.set_default_profile is called.

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

Returns
The default profile library or null if the default profile was not set.
See Also
com.rti.dds.publication.Publisher.set_default_profile
void set_listener ( PublisherListener  l,
int  mask 
)

Sets the publisher listener.

Parameters
l<<in>> com.rti.dds.publication.PublisherListener to set to.
mask<<in>> com.rti.dds.infrastructure.StatusMask associated with the com.rti.dds.publication.PublisherListener.
Exceptions
Oneof the Standard Return Codes
See Also
set_listener (abstract)
PublisherListener get_listener ( )

Get the publisher listener.

Returns
com.rti.dds.publication.PublisherListener of the com.rti.dds.publication.Publisher.
See Also
Entity_get_listener
void suspend_publications ( )

Indicates to RTI Connext that the application is about to make multiple modifications using com.rti.dds.publication.DataWriter objects belonging to the com.rti.dds.publication.Publisher.

It is a hint to RTI Connext so it can optimize its performance by e.g., holding the dissemination of the modifications and then batching them.

The use of this operation must be matched by a corresponding call to com.rti.dds.publication.Publisher.resume_publications indicating that the set of modifications has completed.

If the com.rti.dds.publication.Publisher is deleted before com.rti.dds.publication.Publisher.resume_publications is called, any suspended updates yet to be published will be discarded.

RTI Connext is not required and does not currently make use of this hint in any way. However, similar results can be achieved by using asynchronous publishing. Combined with com.rti.dds.publication.FlowController, com.rti.dds.infrastructure.PublishModeQosPolicyKind.PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS com.rti.dds.publication.DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

Exceptions
Oneof the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.
See Also
com.rti.dds.publication.FlowController
com.rti.dds.publication.FlowController.trigger_flow
com.rti.dds.publication.FlowController.ON_DEMAND_FLOW_CONTROLLER_NAME
com.rti.dds.infrastructure.PublishModeQosPolicy
void resume_publications ( )

Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous com.rti.dds.publication.Publisher.suspend_publications.

This is a hint to RTI Connext that can be used for example, to batch all the modifications made since the com.rti.dds.publication.Publisher.suspend_publications.

RTI Connext is not required and does not currently make use of this hint in any way. However, similar results can be achieved by using asynchronous publishing. Combined with com.rti.dds.publication.FlowController, com.rti.dds.infrastructure.PublishModeQosPolicyKind.PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS com.rti.dds.publication.DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

Precondition
A call to com.rti.dds.publication.Publisher.resume_publications must match a previous call to com.rti.dds.publication.Publisher.suspend_publications. Otherwise the operation will fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.
Exceptions
Oneof the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.
See Also
com.rti.dds.publication.FlowController
com.rti.dds.publication.FlowController.trigger_flow
com.rti.dds.publication.FlowController.ON_DEMAND_FLOW_CONTROLLER_NAME
com.rti.dds.infrastructure.PublishModeQosPolicy
void begin_coherent_changes ( )

Indicates that the application will begin a coherent set of modifications using com.rti.dds.publication.DataWriter objects attached to the com.rti.dds.publication.Publisher.

A 'coherent set' is a set of modifications that must be propagated in such a way that they are interpreted at the receiver's side as a consistent set of modifications; that is, the receiver will only be able to access the data after all the modifications in the set are available at the receiver end.

A connectivity change may occur in the middle of a set of coherent changes; for example, the set of partitions used by the com.rti.dds.publication.Publisher or one of its com.rti.dds.subscription.Subscriber s may change, a late-joining com.rti.dds.subscription.DataReader may appear on the network, or a communication failure may occur. In the event that such a change prevents an entity from receiving the entire set of coherent changes, that entity must behave as if it had received none of the set.

These calls can be nested. In that case, the coherent set terminates only with the last call to com.rti.dds.publication.Publisher.end_coherent_changes.

The support for coherent changes enables a publishing application to change the value of several data-instances that could belong to the same or different topics and have those changes be seen atomically by the readers. This is useful in cases where the values are inter-related (for example, if there are two data-instances representing the altitude and velocity vector of the same aircraft and both are changed, it may be useful to communicate those values in a way the reader can see both together; otherwise, it may e.g., erroneously interpret that the aircraft is on a collision course).

Exceptions
Oneof the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.
void end_coherent_changes ( )
void copy_from_topic_qos ( DataWriterQos  a_datawriter_qos,
TopicQos  a_topic_qos 
)

Copies the policies in the com.rti.dds.topic.TopicQos to the corresponding policies in the com.rti.dds.publication.DataWriterQos.

Copies the policies in the com.rti.dds.topic.TopicQos to the corresponding policies in the com.rti.dds.publication.DataWriterQos (replacing values in the com.rti.dds.publication.DataWriterQos, if present).

This is a "convenience" operation most useful in combination with the operations com.rti.dds.publication.Publisher.get_default_datawriter_qos and com.rti.dds.topic.Topic.get_qos. The operation com.rti.dds.publication.Publisher.copy_from_topic_qos can be used to merge the com.rti.dds.publication.DataWriter default QoS policies with the corresponding ones on the com.rti.dds.topic.Topic. The resulting QoS can then be used to create a new com.rti.dds.publication.DataWriter, or set its QoS.

This operation does not check the resulting com.rti.dds.publication.DataWriterQos for consistency. This is because the 'merged' com.rti.dds.publication.DataWriterQos may not be the final one, as the application can still modify some policies prior to applying the policies to the com.rti.dds.publication.DataWriter.

Parameters
a_datawriter_qos<<inout>> com.rti.dds.publication.DataWriterQos to be filled-up. Cannot be NULL.
a_topic_qos<<in>> com.rti.dds.topic.TopicQos to be merged with com.rti.dds.publication.DataWriterQos. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes
void get_all_datawriters ( DataWriterSeq  writers)

Retrieve all the DataWriters created from this Publisher.

Parameters
writers<<inout>> Sequence where the DataWriters will be added
Exceptions
Oneof the Standard Return Codes
void delete_contained_entities ( )

Deletes all the entities that were created by means of the "create" operation on the com.rti.dds.publication.Publisher.

Deletes all contained com.rti.dds.publication.DataWriter objects. Once com.rti.dds.publication.Publisher.delete_contained_entities completes successfully, the application may delete the com.rti.dds.publication.Publisher, knowing that it has no contained com.rti.dds.publication.DataWriter objects.

The operation will fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET if any of the contained entities is in a state where it cannot be deleted.

Exceptions
Oneof the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.
void wait_for_acknowledgments ( Duration_t  max_wait)

Blocks the calling thread until all data written by the Publisher's reliable DataWriters is acknowledged, or until timeout expires.

This operation blocks the calling thread until either all data written by the reliable DataWriters entities is acknowledged by (a) all reliable com.rti.dds.subscription.DataReader entities that are matched and alive and (b) by all required subscriptions, or until the duration specified by the max_wait parameter elapses, whichever happens first. A successful completion indicates that all the samples written have been acknowledged; a return value of TIMEOUT indicates that max_wait elapsed before all the data was acknowledged.

Note that if a thread is blocked in the call to this operation on a com.rti.dds.publication.Publisher and a different thread writes new samples on any of the reliable DataWriters that belong to this Publisher, the new samples must be acknowledged before unblocking the thread that is waiting on this operation.

If none of the com.rti.dds.publication.DataWriter instances have com.rti.dds.infrastructure.ReliabilityQosPolicy kind set to RELIABLE, the operation will complete successfully.

Parameters
max_wait<<in>> Specifies maximum time to wait for acknowledgements com.rti.dds.infrastructure.Duration_t .
Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_NOT_ENABLED, com.rti.dds.infrastructure.RETCODE_TIMEOUT
void wait_for_asynchronous_publishing ( Duration_t  max_wait)

<<extension>> Blocks the calling thread until asynchronous sending is complete.

This operation blocks the calling thread (up to max_wait) until all data written by the asynchronous com.rti.dds.publication.DataWriter entities is sent and acknowledged (if reliable) by all matched com.rti.dds.subscription.DataReader entities. A successful completion indicates that all the samples written have been sent and acknowledged where applicable; if it times out, this indicates that max_wait elapsed before all the data was sent and/or acknowledged.

In other words, this guarantees that sending to best effort com.rti.dds.subscription.DataReader is complete in addition to what com.rti.dds.publication.Publisher.wait_for_acknowledgments provides.

If none of the com.rti.dds.publication.DataWriter instances have com.rti.dds.infrastructure.PublishModeQosPolicy.kind set to com.rti.dds.infrastructure.PublishModeQosPolicyKind.PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS, the operation will complete immediately , with com.rti.dds.infrastructure.RETCODE_OK.

Parameters
max_wait<<in>> Specifies maximum time to wait for acknowledgements com.rti.dds.infrastructure.Duration_t.
Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_NOT_ENABLED, com.rti.dds.infrastructure.RETCODE_TIMEOUT
DataWriter lookup_datawriter_by_name ( String  datawriter_name)

<<extension>> Retrieves a com.rti.dds.publication.DataWriter contained within the com.rti.dds.publication.Publisher the com.rti.dds.publication.DataWriter entity name.

Every com.rti.dds.publication.DataWriter in the system has an entity name which is configured and stored in the <<extension>> EntityName policy, ENTITY_NAME.

This operation retrieves the com.rti.dds.publication.DataWriter within the com.rti.dds.publication.Publisher whose name matches the one specified. If there are several com.rti.dds.publication.DataWriter with the same name within the com.rti.dds.publication.Publisher, the operation returns the first matching occurrence.

Parameters
datawriter_name<<in>> Entity name of the com.rti.dds.publication.DataWriter.
Returns
The first com.rti.dds.publication.DataWriter found with the specified name or NULL if it is not found.
See Also
com.rti.dds.domain.DomainParticipant.lookup_datawriter_by_name

RTI Connext Java API Version 5.2.0 Copyright © Sun Jun 21 2015 Real-Time Innovations, Inc