Publisher Interface Reference
[Publishers]

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

Inheritance diagram for Publisher:

DomainEntity Entity

List of all members.

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 reliable com.rti.dds.publication.DataWriter entities 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.

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 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 retreived 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 is 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:
One of the Standard Return Codes
See also:
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 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 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 Publisher.DATAWRITER_QOS_DEFAULT as the qos parameter.
Parameters:
qos <<in>> Default qos to be set. The special value 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:
One of the Standard Return Codes, or 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 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 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 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 RETCODE_ERROR.

Exceptions:
One of the Standard Return Codes, or RETCODE_INCONSISTENT_POLICY
See also:
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, Foo, there is an implied, auto-generated class com.rti.dds.topic.example.FooDataWriter that extends com.rti.dds.publication.DataWriter and contains the operations to write data of type 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 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 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 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.
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.dds.topic.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

Publisher.DATAWRITER_QOS_DEFAULT

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, Foo, there is an implied, auto-generated class com.rti.dds.topic.example.FooDataWriter that extends com.rti.dds.publication.DataWriter and contains the operations to write data of type 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.
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.dds.topic.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 DestinationOrderQosPolicyKind.BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, calls to delete_datawriter() may fail if your application has previously used the 'with timestamp' APIs (write_w_timestamp(), register_instance_w_timestamp(), unregister_instance_w_timestamp(), or dispose_w_timestamp()) with a timestamp larger (later) than the time at which delete_datawriter() is called. To prevent delete_datawriter() 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 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.
Exceptions:
One of the Standard Return Codes or 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.

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.
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.

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 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:
One of the Standard Return Codes, RETCODE_IMMUTABLE_POLICY, or 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:
One of the Standard Return Codes, RETCODE_IMMUTABLE_POLICY, or 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:
One of 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:
One of 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:
One of 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:
One of the Standard Return Codes
See also:
set_listener (abstract)

PublisherListener 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, PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS com.rti.dds.publication.DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

Exceptions:
One of the Standard Return Codes or RETCODE_NOT_ENABLED.
See also:
com.rti.dds.publication.FlowController

com.rti.dds.publication.FlowController.trigger_flow

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, 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 RETCODE_PRECONDITION_NOT_MET.

Exceptions:
One of the Standard Return Codes or RETCODE_PRECONDITION_NOT_MET or RETCODE_NOT_ENABLED.
See also:
com.rti.dds.publication.FlowController

com.rti.dds.publication.FlowController.trigger_flow

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:
One of the Standard Return Codes or RETCODE_NOT_ENABLED.

void end_coherent_changes (  ) 

Terminates the coherent set initiated by the matching call to com.rti.dds.publication.Publisher.begin_coherent_changes.

Precondition:
If there is no matching call to com.rti.dds.publication.Publisher.begin_coherent_changes the operation will fail with RETCODE_PRECONDITION_NOT_MET.

Exceptions:
One of the Standard Return Codes, RETCODE_PRECONDITION_NOT_MET or RETCODE_NOT_ENABLED.

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:
One of 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:
One of the Standard Return Codes

DomainParticipant get_participant (  ) 

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 RETCODE_PRECONDITION_NOT_MET if any of the contained entities is in a state where it cannot be deleted.

Exceptions:
One of the Standard Return Codes or RETCODE_PRECONDITION_NOT_MET.

void wait_for_acknowledgments ( Duration_t  max_wait  ) 

Blocks the calling thread until all data written by reliable com.rti.dds.publication.DataWriter entities is acknowledged, or until timeout expires.

This operation blocks the calling thread until either all data written by the reliable com.rti.dds.publication.DataWriter entities is acknowledged by all matched reliable com.rti.dds.subscription.DataReader entities, or else the duration specified by the max_wait parameter elapses, whichever happens first. A successful completion indicates that all the samples written have been acknowledged by all reliable matched data readers; a return value of TIMEOUT indicates that max_wait elapsed before all the data was acknowledged.

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:
One of the Standard Return Codes, RETCODE_NOT_ENABLED, 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 PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS, the operation will complete immediately, with RETCODE_OK.

Parameters:
max_wait <<in>> Specifies maximum time to wait for acknowledgements com.rti.dds.infrastructure.Duration_t.
Exceptions:
One of the Standard Return Codes, RETCODE_NOT_ENABLED, RETCODE_TIMEOUT


RTI Connext Java API Version 4.5f Copyright © 17 Mar 2012 Real-Time Innovations, Inc