The current signature of read() (and take) is:

public Sample.Iterator<TYPE> read();

This operation should return an Interable collection, to be aligned with the C++PSM:

public LoanedSamples<T> read();

An Iterable collection can be used in a foreach loop, and it can be managed by a try-with-resources block to return the loan automatically. An Iterator doesn't take advantage of these features.

The machine-readable file URLs on the
FTF report (ptc/15-09-21) and FTF 2 convenience document
(ptc/15-09-13) disagree.

The correct ones are the ones used in the FTF 2 document because these are consistent which the reference schema files that appear in the XML files also included as part of the specification.

If nothing is done the URLs on the cover of the report (ptc/15-09-21) take precedence over the ones in the FTF2 specification, so it is imperative to re-issue the report to correct this.

The org.omg.dds.core.status.Status class currently extends the java.util.EventObject.
The issue I have with this is that a status and an event are to different concepts.
A status represents a continuous value or set of values which are always defined,
while an event represents and happening. For instance an event could be used to notify
the change of status but not the status itself.

[Resolution]
That said the refactoring suggested is to re-organize the current status types
so to clearly distinguish what is are statuses and what are the events. As such,
all the status currently defined should remove reference to the source. Why?
Because the statuses are retrieved from the source thus it is kind of silly to
add back the source on the communication status.

Let me give you an example ("dr" below is a DataReader):

RequestedDeadlineMissedStatus s = dr.getRequestedDeadlineMissedStatus();

// this give back the reader we already know, thus it is not real useful
// information which should simply be removed.
s.source())

BTW the status types as well as the relative accessor methods should
drop the trailing "Status" as it is not so informative.

That said, we should add an event type associated to each status defined like this:

class RequestedDeadlineMissedEvent

The event type is the one that should be used as a parameter of the listener methods.

Finally, it is worth noticing that the suggested refactoring will fix the
DataAvailableStatus anomaly. This type currently defined as a status is actually
an event and as such should be treated. So where is the anomaly, for this status
there are no methods on the data reader and there is really no status information
such as saying... Yes there are 15 new samples or something like this.

That said the refactoring suggested is to re-organize the current status types so to clearly distinguish what is are statuses and what are the events. As such, all the status currently defined should remove reference to the source. Why? Because the statuses are retrieved from the source thus it is kind of silly to add back the source on the communication status.
Let me give you an example ("dr" below is a DataReader):
RequestedDeadlineMissedStatus s = dr.getRequestedDeadlineMissedStatus();
// this give back the reader we already know, thus it is not real useful
// information which should simply be removed.
s.source())
BTW the status types as well as the relative accessor methods should drop the trailing "Status" as it is not so informative.
That said, we should add an event type associated to each status defined like this:
class RequestedDeadlineMissedEvent

The event type is the one that should be used as a parameter of the listener methods.
Finally, it is worth noticing that the suggested refactoring will fix the DataAvailableStatus anomaly. This type, currently defined as a status, is actually an event and as such should be treated. So where is the anomaly, for this status there are no methods on the data reader and there is really no status information such as saying... Yes there are 15 new samples or something like this.

The read API currently seems a bit too complicated. In some in some instances
it provides part of the results as a return value and the rest by means of arguments.
This does not feel right and again violates one of the key goal of having a new PSM: simplcity
and usability.

The API does not provide a way of deciding if one wants to read/take only valid
data. This is a remark true in general for DDS which needs to be fixed for all PSM
as well as for the PIM!

The following methods on the DataReader interface are superfluous:

• cast
• createSample

[Resolution]
Refactor and cleanup the data-reader API.

This issue has three parts: removing unnecessary methods, reading only samples with valid data, and simplifying method overloads.
• The cast() method is not superfluous; it is the only type-safe way to narrow a DataReader<?> to a DataReader<Foo>. This method can potentially use internal state of the reader to provide immediate run-time type safety. The only alternative is for the application code to use a type cast like this: “(DataReader<Foo>)”. But such a cast is meaningless because of type erasure and will generate a compiler warning. If there is a type mismatch, it will potentially not be caught until later.
• Issue #16324 already eliminated the createSample method.
• Reading or taking only valid data samples may or may not be semantically meaningful and should be addressed in the PIM first, so that the semantics can be defined. At that point, the method can be introduced into this PSM in an RTF.
• Issue #16321 already proposes simplifying the read/take overloads. Since this is the only remaining part of this issue not addressed in the bullets above, this issue can be merged with that one.
Resolution:
Merge this issue with issue #16321.
Disposition: Merged with issue #16321

The dds-psm-java currently passes statuses via collections. However this
does not make it neither efficient nor simple to represent collections
of related statuses, such as the Read Status, etc.

[Resolution]
The suggestion is to add a ReadState as currently present on the dds-psm-cxx
to simplify the API and make it simpler to support the most common use cases.

[Angelo] The suggestion is to add a ReadState as currently present on the DDS-PSM-Cxx to simplify the API and make it simpler to support the most common use cases.
[Rick] This issue is unclear to me. I take it that this issue is not referring to actual Status objects. The reference to what is called “Read Status” or “Read State” and to DDS-PSM-Cxx makes me think it is related to the DDS-PSM-Cxx class called “ReaderState”, which encapsulates sets of Sample States, View States, and Instance States. This change is already proposed in DDS-PSM-Java as part of the proposed resolution to issue #16321.
Resolution:
Merge this issue with issue #16321.
Disposition: Merge with issue #16321

The methods that access the communication statuses should simply return
an object as opposed to also require it as an argument. As the Status
is immutable there is no risk in the client code changing it, thus no copies
required!

[Resolution]
Apply the changes suggested in the description above.

[Rick] This issue seems to apply only to writer status accessors. It is unclear to me why this issue is filed against the writer and not all other such status accessors.
Resolution:
Issue #16587 is a blanket issue about “bucket” accessors; this issue should be merged with that one.
Disposition: Merge with issue #16587

What is the value of having the DomainEntity class?

[Resolution]
The DomainEntity class should be removed and the getParent method should be migrated to the Entity class.

Close this issue with no change. DomainEntity is a classifier directly from the DDS PIM. Its value is to capture the invariant that domain participants have no parent entity, and entities of all other types do. If this type is removed, and getParent is moved to Entity, this static invariant will become a run-time invariant (i.e. getParent will have to return null when the object is a participant), making application code less robust.
Disposition: Closed, no change

Description
----------------
The DDS-PSM-Java provides bucket accessors that allow to "return" an object
by "filling" a method parameter.

As an example, for a property Foo there would be a method:

Foo f = // some foo
x.getFoo(f)

The rationale for this API is to avoid a defensive copy of Foo each time it is accessed.
However the cost of this "optimization" is an API that has side-effects everywhere,
with all the nasty implications of side-effects.

Resolution
---------------
The solution suggested to avoid bucket accessors and thus side-effects is to
rely as much as possible on immutable objects (e.g. value-types). This ensures
that (1) defensive copies are unnecessary since the attribute returned is immutable,
and (2) new objects are created when new values are required.

If properly designed (as shown on an issue posted on QoS and Policies) this approach
not only leads to a simpler and safer API, but it also leads to actually save memory in most
of the cases.

The only case where the suggested approach has a cost is when a property changes
very often. However, in many of these cases (often found in loops) the new JDK7
escape analysis will help greatly help in dealing with the potential garbage as it
will allocate these short-lived objects on the stack.

Proposed Resolution:
The solution suggested to avoid bucket accessors and thus side-effects is to rely as much as possible on immutable objects (e.g. value-types). This ensures that (1) defensive copies are unnecessary since the attribute returned is immutable, and (2) new objects are created when new values are required.
If properly designed (as shown on an issue posted on QoS and Policies) this approach not only leads to a simpler and safer API, but it also leads to actually save memory in most of the cases.
The only case where the suggested approach has a cost is when a property changes very often. However, in many of these cases (often found in loops) the new JDK7 escape analysis will help greatly help in dealing with the potential garbage as it will allocate these short-lived objects on the stack.

The Sample Class as defined in the Beta1 of the DDS-PSM-Java does not define
a method "isValid(): Boolean" to check wether the data is actually valid. This is a simple
to fix oversight.

Resolution
---------------
Add an "isValid () : Boolean" method to the Sample Class

This issue is closed without any changes. The Sample class does provide a method to check whether the data is valid. There is no oversight. As described in section 7.6.2, “Sample Interface”:
Each sample is represented by an instance of the org.omg.dds.sub.Sample interface. It provides its data via a getData method; if there is no valid data (corresponding to a false value for SampleInfo.valid_data in the IDL PSM), this operation returns null.
The existing design is appropriate. The alternative—returning a non-null data object, and then making people check a flag that tells them not to use that object—would be extremely error-prone.
Disposition: Closed, no change

The name of the classes DataReaderAdapter/DataWriterAdapter are misleading since what
they are really providing are listeners with some default behaviour.

Resolution
---------------
Rename the classes DataReaderAdapter/DataWriterAdapter to
SimpleDataReaderListener and SimpleDataWriterListener.

For the SimpleDataReaderListener one could implement trivially all
the method but the one that notifies the availability of data,
e.g. <onDataAvailable>

This issue is closed without any changes. Providing no-op listener implementations, and replacing “Listener” with “Adapter” in the class name, is a common JDK idiom. You will see it throughput AWT and Swing, for example, which abound with listeners. The rationale for this pattern is described in section 7.2.7.2, “Listeners”.
Disposition: Closed, no change

Close this issue without any change. This type serves two purposes for the DDS user: it gives them a way to work with QoS policies polymorphically, and it binds a type parameter of the Entity interface to provide static type safety.
Disposition: Closed, no change

The absence of a DSL for facilitating the correct creation of QoS (in QoS classes such as:
TopicQos, DataWriterQos, etc.) in the
dds-psm-java not only makes QoS manipulation cumbersone, but it also
introduces potential for errors.

[Resolution]
Define a QoS DSL for the dds-psm-cxx which might look like this:

TopicQos topicQos =
(new TopicQos())
.with(Reliability.Reliable(), Durability.Transient());

This is also legal:

TopicQos topicQos =
(new TopicQos())
.with(Reliability.Reliable())
.with(Durability.Transient());

• These class should implement the Comparable interface as they need to
  provide a total order... Otherwise how can one do RxO?

Define a QoS DSL for the dds-psm-cxx which might look like this:
TopicQos topicQos =
(new TopicQos())
.with(Reliability.Reliable(), Durability.Transient());
This is also legal:
TopicQos topicQos =
(new TopicQos())
.with(Reliability.Reliable())
.with(Durability.Transient());

• These class should implement the Comparable interface as they need to
  provide a total order... Otherwise how can one do RxO?

Some of the DDS QoS Policies are Request vs. Offered in the sense that
the value of matching policies on communicating entities have to satisfy a
specific ordering relationship. Specifically, the policy set on the receiving side
should always be less or equal than the analogous QoS Policy on the
sending side. As a result there is a natural total ordering for RxO Policies
which is not currently captured nor reflected in the API.

As a consequence also QoS should be defining a total order.

[Resolution]
Ensure that all RxO Policies implement the Comparable interface. This is
pretty logical as for this QoS Policies it has to be established
a total order.

Let QoS classes also implement a comparable interface.

Define an interface RequestedOffered; all QoS policy types that require requested/offered compatibility extend this interface. The interface has one method, requestedOfferedContract, which returns a Comparable object. That objects compares the policy against another instance of the policy based on the requested/offered compatibility rule(s) for that policy type.

The boostrap class is a pain for users which is in place only to allow
users to run 2 different DDS implementations on the same application.
The introduction of the Bootstrap object makes it impossible to use
natural constructors for creating DDS types, even for types such as
Time and Duration.
As one of the main goal of the new DDS PSM was to simplify the
user experience and make the API as simple and natural as possible,
it seems that the introduction of the Bootstrap object goes exactly
on the opposite direction – all of this to be able to cover the case
in which a user wants 2 different DDS implementation on the same
application. Considering the wire-protocol interoperability
this use case seems marginal and perhaps does not even count for 1% of
DDS uses.

[Resolution]
The bootstrap should be removed and the resulting API should be simplified.

No Data Available

The dds-psm-java makes use of import as a way to take care of the
@link directive on Javadoc. This is not a good practice and it
is better to use the fully qualified type name on the @link javadoc
directive

[Resolution]
Clean up all the spurious import and use fully qualified types on the @link directives.

There are no changes in the specification document for this issue. Discussion:
Spurious import statements have been removed (as indicated by the Checkstyle plugin for Eclipse). Java doc comments are updated to use the fully qualified class names. This issue does not affect the specification text.
See Revision 181: https://code.google.com/p/datadistrib4j/source/detail?r=181
See Revision 210: https://code.google.com/p/datadistrib4j/source/detail?r=210

Constant values such as the infinite duration, etc. should be defined
by the standard as opposed than the implementation.

[Resolution]
Define constants as part of the API.

Close this issue without any change.
Disposition: Closed, no change

QoS Policies define a nested ID class for capturing the Policy ID and PolicyName.

[Resolution]
Remove the ID class and (1) use Java introspection for accessing the policy name,
and (2) define an integral ID for specifiying the policy ID.

Notice that getid and getName methods are also needed.

[Angelo] Remove the ID class and (1) use Java introspection for accessing the policy name, and (2) define an integral ID for specifying the policy ID.
Notice that getId and getName methods are also needed.
[Rick] This issue is unclear to me. I do not understand what problem it is describing. It seems to be redundant with issue #16369.
Resolution:
This issue is a duplicate of issue #16369 and should be merged with that one.
Disposition: Duplicate of issue #16369

The dds-psm-java uses a superfluous Policy suffix to name the DDS policies
which themselves are already included in a "policy" namespace.

[Resolution]
This suffix should be removed.

Close this issue without any change. In Java, fully qualified names are almost never used, and Eclipse (the most commonly used editing environment) commonly collapses imports so they will not be seen. Therefore, it is relevant and important to include this suffix in the names of QoS policy types (not to mention consistent with the PIM). “Reliability” and “Durability” are just attributes; they don’t make sense unless we know what they describe.
Disposition: Closed, no change

The Entity provides some generic methods that seem of doubtful usefulness
but then on the other end open up a door for messing up with the invariant
of a type or at least raising runtime errors. For instance via the
Entity type I can add a non-applicable QoS policy to a DDS entity –
this seems weakening the API.

[Resolution]
Remove all method that might break invariants such as setQos, setListener, etc.

Reject this issue. The generic parameters of this type provide static type safety and polymorphic behavior.
Disposition: Closed, no change

The dds-psm-java introduces modifiable versions for conceptually immutable classes
as a way to safe a few object allocations. However this is done for QoS which
are not changed so often and that are overall very "thin" object.

[Suggested Resolution]
The proposed resolution is to get rid of this modifiable types and to ensure that
value types are used everywhere.
Althought this solution might lead to think that immutable types induce the creation
of more objects this is not necessarily the case if the API si designed carefully as
done for policies and Qos on simd-java (see git@github.com:kydos/simd-java.git).

As an example, with the API included in the current DDS-PSM-Java modifying a policy
would require the following steps:

// Get unmodifiable QoS for inspection:
DataWriterQos udwq = dw.getQos();

// Get the Modifiable QoS
ModifiableDataWriterQos mdwq = udwq.modify();

// Modify the Qos
mdwq.setReliability(...);

With immutable Policies and QoS the same code could be rewritten as follows:

DataWriterQos dwq = dw.getQos().with(Reliability.Reliable());

But you could also do:
DataWriterQos dwq = dw.getQos().with(
Reliability.Reliable(),
Durability.Transient());

Notice that both code fragment both lead the lead the creation of a single new object.
Yet the propsed approach not only gets rid of the complexity of the mutable objects,
but it also get rids of the danger introduced by having mutable objects into multi-threaded
applications. In summary, the proposed change (1) simplifies the API, (2) makes it safer, and (3) does
not introduce runtime overhead (it actually allows for an higher degree of object sharing and thus
better space efficiency).

NOTE:
Cloneable interface
No need to implement the interface once the mutable pkg is removed

No Data Available

In the DDS PIM, each QoS policy has a name and an ID that uniquely identify it. In this PSM, these two things are encapsulated in the enumeration QosPolicy.Id. But the Java platform already provides equivalent information: the Class object. The ability to quickly compare Class object pointers is equivalent to comparing ID integer values, and each Class already has a name string.

Proposed Resolution:

Remove the enumeration QosPolicy.Id. Replace its uses with Class<? extends QosPolicy>.

Remove the enumeration QosPolicy.Id. Replace its uses with Class<? extends QosPolicy>.

Title: Remove unnecessary DataWriter.write overloads

Source:

RTI (Rick Warren, rick.warren@rti.com)

Summary:

The specification currently provides overloads for DataWriter.write that take the following combinations of parameters

1. The sample to write, without an instance handle. (If the type is not keyed, no instance handle is necessary. If it is keyed, the instance handle is implicitly nil and will be inferred by the implementation.)

2. The sample to write, without an instance handle but with a time stamp.

3. The sample to write, with an instance handle.

4. The sample to write, with both an instance handle and a time stamp.

The overloads would be easier to understand if they formed a progression from fewer parameters to more. We can do this by removing (2).

Proposed Resolution:

Remove the following methods:

• public void write(

• TYPE instanceData,

• Time sourceTimestamp) throws TimeoutException;

• public void write(

• TYPE instanceData,

• long sourceTimestamp,

• TimeUnit unit) throws TimeoutException;

Also, update the documentation of the remaining overloads to clarify that if the topic is not keyed, they can be called with a nil or null InstanceHandle.

No Data Available

Source:

RTI (Rick Warren, rick.warren@rti.com)

Summary:

The specification does not provide a simple, portable way to create a new data sample to use with the middleware. Instead, there are several partial solutions:

· Instantiate a concrete sample type directly: “new Foo()”. This approach doesn’t work in generic methods—i.e. when the concrete type is not statically known. It also doesn’t work with DynamicData.

· Instantiate DynamicData from DynamicDataFactory. But samples of statically known, user-defined types don’t have a “data factory”.

· Use DataReader.createData(). But there is not equivalent on the publishing side.

There should be a single way that works uniformly and generically.

Proposed Resolution:

The proposed resolution has several parts:

1. Introduce a new factory instance method to the TypeSupport class: TypeSupport.newData(). The name of this method is parallel to that of other value type “constructor-like” factories.

2. Support navigation from the TopicDescription to the TypeSupport. Add a new method TopicDescription.getTypeSupport().

3. Simplify the number of ways to get from the data type’s TypeSupport to its Class. Add a method TypeSupport.getType(). Remove the existing methods TopicDescription.getType(), DataWriter.getType(), and DataReader.getType(): they are redundant.

4. Remove the existing method DataReader.createData() and the existing class DynamicDataFactory. They are not needed.

There will therefore be a single polymorphic and generic way to instantiate a sample of any type: by using its TypeSupport. (You can get the TypeSupport from any related TopicDescription, or transitively any DataReader or DataWriter.)

Likewise, there will be a single polymorphic and generic way to get the Class object for any data type: from its TypeSupport. As described in the previous paragraph, you can get to the TypeSupport from a variety of places.

The proposed resolution has several parts:
1. Introduce a new factory instance method to the TypeSupport class: TypeSupport.newData(). The name of this method is parallel to that of other value type “constructor-like” factories.
2. Support navigation from the TopicDescription to the TypeSupport. Add a new method TopicDescription.getTypeSupport().
3. Simplify the number of ways to get from the data type’s TypeSupport to its Class. Add a method TypeSupport.getType(). Remove the existing methods TopicDescription.getType(), DataWriter.getType(), and DataReader.getType(): they are redundant.
4. Remove the existing method DataReader.createData() and the existing class DynamicDataFactory. They are not needed. In the specification document, rename section 7.7.1.1, “DynamicTypeFactory and DynamicDataFactory Interfaces”, to “DynamicTypeFactory Interface”. In the single paragraph of that section, make the word “factories” singular.
See revision #123, which includes the above changes: http://code.google.com/p/datadistrib4j/source/detail?r=123.
5. Remove the factory methods on the built-in topic data classes. Objects of these types can be constructed like those of any other sample type. See also revision #137, which includes this change: http://code.google.com/p/datadistrib4j/source/detail?r=137.
There will therefore be a single polymorphic and generic way to instantiate a sample of any type: by using its TypeSupport. You can get the TypeSupport from any related TopicDescription, or transitively any DataReader or DataWriter.
Likewise, there will be a single polymorphic and generic way to get the Class object for any data type: from its TypeSupport. As described in the previous paragraph, you can get to the TypeSupport from a variety of plac

The third bullet at the end of section 7.1.5, “Method Signature Conventions”, reads:

· Accessors for properties that are of mutable types, and that may change asynchronously after they are retrieved, are named get<PropertyName>. They take a pre-allocated object of the property type as their first argument, the contents of which shall be overwritten by the method. To facilitate method chaining, these methods also return a reference to this argument. This pattern forces the caller to make a copy, thereby avoiding unexpected changes to the property. An Entity’s status is an example of a property of this kind.

(This pattern of passing a container to an object for that object to “fill in” has sometimes been referred to as a “bucket” pattern.)

In cases where object-allocation performance is not a significant concern, the usability of this pattern can be improved with a trivial addition: allow the caller to pass in a null “bucket”, and require the implementation to allocate and return a new object with the appropriate contents.

Proposed Resolution:

Add a sentence to the bullet that indicates that a null argument is permitted.

Proposed Revised Text:

Replace the third bullet in section 7.1.5, “Method Signature Conventions” with the following:

· Accessors for properties that are of mutable types, and that may change asynchronously after they are retrieved, are named get<PropertyName>. They take a pre-allocated object of the property type as their first argument, the contents of which shall be overwritten by the method. To facilitate method chaining, these methods also return a reference to this argument. The caller may alternatively pass a null argument into such accessor methods, in which case the implementation shall allocate a new object, set its contents appropriately, and return it. This pattern forces the caller to make a copy, thereby avoiding unexpected changes to the property. An Entity’s status is an example of a property of this kind.

No Data Available

Some parts of the interface (javadoc) are poorly documented especially with respect to behaviour. This Java documentation will be the key documentation for the new DDS application programmers. It may be trivial or implicit for the ones writing the standard but it will not be for the application programmers which are not familiar with the existing DDS standard will use it

For example have a look at the method createDataWriter(Topic<TYPE> topic) on the Publisher interface. What will happen if the middleware cannot create the datawriter. Will an unchecked exception be thrown or is a null value returned or even worse the datawriter is simply returned and will fail when the first write action is performed?

I now that the existing OpenSplice DDS implementation will return null when the middleware is not able to create the datawriter but it would be nice that applications are not only portable from interface compliance aspect but also from behavioural aspect! (and that application programmers are aware of it)

Merge the descriptions of classes and operations from the DDS specification into the appropriate JavaDoc comments. This PSM does not introduce new concepts, so no merge is necessary in that case. DDS-XTypes is in finalization, so its contents are not yet fixed. Therefore, to avoid the possibility of errors and inconsistencies, we should put it aside for now.

Source:

RTI (Rick Warren, rick.warren@rti.com)

Summary:

The method signature for Entity.setListener does not include the listener “mask” (actually, a collection of status classes in this PSM) parameter from the PIM.

Discussion:

The current signature is useful as a convenience for the common case where the application wants all callbacks. But it lacks the expressiveness of the PIM, so an additional overload should be provided.

Proposed Resolution:

Add the following method to the Entity interface:

public void setListener(

LISTENER listener,

Collection<Class<? extends Status<?, ?>>> statuses);

Include the appropriate JavaDoc copied from the DDS specification

Add the following method to the Entity interface:
public void setListener(
LISTENER listener,
Collection<Class<? extends Status<?, ?>>> statuses);
Include the appropriate JavaDoc copied from the DDS specification

Source:

RTI (Rick Warren, rick.warren@rti.com)

Summary:

The (first) DDS-XTypes FTF has completed. Some of the issue resolutions result in API changes that impact this specification. Those changes should be reflected here to keep this specification aligned with the PIM.

These issues potentially include:

· #15689, Identifiers TypeId and Module collide with IDL keywords

· #15691, Unclear member names when programming language doesn’t support typedef

· #15693, Extensibility kinds of new QoS policies are not specified in a consistent way

· #15696, Incorrect FooDataWriter overloads for built-in types

· #15706, Reduce size of DynamicData API

Note that this issue applies to DDS-PSM-Cxx too.

See the following revisions:
• Revision #128: http://code.google.com/p/datadistrib4j/source/detail?r=128. Reflects DDS-XTypes issue #15696—overloads in writers of built-in types.
• Revision #129: http://code.google.com/p/datadistrib4j/source/detail?r=129. Reflects DDS-XTypes issue #15691—clarity of member names in the absence of typedef.
• Revision #130: http://code.google.com/p/datadistrib4j/source/detail?r=130. Reflects DDS-XTypes issue #15706—simplified DynamicData.
Other aspects of issue #15689 and 15691 were already addressed in the drafting of DDS-PSM-Java. Issue #15693 is a no-op because of the way inheritance and annotations are used

Source:

RTI (Rick Warren, rick.warren@rti.com)

Summary:

According to DDS-XTypes, the operation DynamicDataFactory.create_data (createData in this PSM) takes a parameter that indicates the DynamicType of the new data object to create. That parameter is missing, leaving implementations with no way to determine—and applications with no way to specify—the type of the created object.

Proposed Resolution:

Add the missing argument.

Proposed Revised Text:

Apply the following difference to the method signature:

• public abstract DynamicData createData();

+ public abstract DynamicData createData(DynamicType type);

This issue is obsolete if the proposal for issue #16324 is accepted: that proposal calls for DynamicDataFactory to be eliminated entirely. Merge this issue with that one.
Disposition: Merged with issue #16324

The DataReader interface defines a very large number of read and take variants. While each one has a clear meaning, the sheer number of them makes the API harder to understand.

Discussion:

One possibility would be to follow the example of the C++ PSM, and combine things like condition, handle, etc. into a “filter” parameter.

Note that this issue should be resolved at the same time as #16056.

No Data Available

Source:

RTI (Rick Warren, rick.warren@rti.com)

Summary:

The DataReader interface provides two overloads for the createDataReader method: one that takes no arguments and another that takes the appropriate sample states, view states, and instance states. The existence of the first overload supposes that it will be common to create a ReadCondition with any sample state, any view state, and any instance state. But in fact, such a ReadCondition is not very useful at all: there’s no point in passing it to read/take, because it will not filter the available samples in any way. And although you could use it with a WaitSet, it doesn’t do anything that you couldn’t do with a StatusCondition on the DATA_AVAILABLE status.

Proposed Resolution:

Remove the no-argument overload of DataReader.createReadCondition. Leave the three-argument overload unchanged.

Remove the no-argument overload of DataReader.createReadCondition. Leave the three-argument overload unchanged.

Source:

RTI (Rick Warren, rick.warren@rti.com)

Summary:

All DomainEntity interfaces, and some Condition interfaces, can provide a reference to the parent object. In the case of Entities, this accessor has been captured in the form of a generic base interface method:

PARENT DomainEntity.getParent();

However, StatusCondition and ReadCondition are not parallel. They provide the following methods:

ENTITY StatusCondition.getEntity();

DataReader<TYPE> ReadCondition.getDataReader();

It would be more consistent if we renamed both of the above methods to getParent.

Proposed Resolution:

Rename StatusCondition.getEntity to getParent.

Rename ReadCondition.getDataReader to getParent.

Rename StatusCondition.getEntity to getParent.
Rename ReadCondition.getDataReader to getParent.

The method DomainParticipant.createMultiTopic specifies the type of the resulting object using a registered type name in string form. However, this is inconsistent with the way type registration is handled elsewhere in this PSM: callers provide a Class or TypeSupport object, and the implementation registers the type implicitly as necessary.

Discussion:

We should follow the model of createTopic: provide two overloads, one taking a Class and the other a TypeSupport.

Proposed Resolution:

Replace the existing createMultiTopic method declaration with two new overloads. In place of the typeName string, the first new overload shall take a Class parameter. The second shall take a TypeSupport parameter

Replace the existing createMultiTopic method declaration with two new overloads. In place of the typeName string, the first new overload shall take a Class parameter. The second shall take a TypeSupport parameter

Source:

RTI (Rick Warren, rick.warren@rti.com)

Summary:

The method WaitSet.waitForConditions is provided with several overloads, including some that do not take an explicit timeout. These are intended to wait indefinitely. However, they still throw TimeoutException. How can they time out if they wait forever?

Discussion:

Object.wait allows indefinite waiting, so it makes sense for this specification to allow it as well. However, these overloads should not ever throw TimeoutException.

Proposed Resolution:

Remove the clause “throws TimeoutException” from these method declarations.

Remove the clause “throws TimeoutException” from these method declarations.

Source:

RTI (Rick Warren, rick.warren@rti.com)

Summary:

Several of the types defined in this PSM have a natural order (such as Time). In order to better integrate with the Java platform, these types should implement the standard java.lang.Comparable interface.

Proposed Resolution:

Implement Comparable in the following types:

· Bit—ordered based on index within a bit set

· Duration—ordered from shorter durations to longer ones

· Time—ordered from earlier points in time to later ones

Implement Comparable in the following types:
• Bit—ordered based on index within a bit set
• Duration—ordered from shorter durations to longer ones
• InstanceHandle—ordered in an implementation-specific way (DDS specification of DataReader::read() requires such an ordering)
• Time—ordered from earlier points in time to later ones

Proposed Resolution:

Change the signatures as follows:

In Publisher.java:

• public void copyFromTopicQos(DataWriterQos dst, TopicQos src);

+ public ModifiableDataWriterQos copyFromTopicQos(

+ ModifiableDataWriterQos dst, TopicQos src);

In Subscriber.java:

• public void copyFromTopicQos(DataReaderQos dst, TopicQos src);

+ public ModifiableDataReaderQos copyFromTopicQos(

+ ModifiableDataReaderQos dst, TopicQos src);

No Data Available

ISSUE
The newly introduced XML Based Policy configuration adds new methods in the core DDS entities that allow to fetch QoS from XML filers. This solution is not ideal since if generalized, e.g. QoS configuration from an URI, JSON stream, etc., would lead to an explosion of the core DDS API.

The suggestion is to remove the added methods from the core API and use instead a Builder pattern (of some form).

A sketch of the suggested change is provided below:

PolicyBuilder builder = PolicyBuilder::load("XMLBuilder");

TopicQos tqos = builder.topic_qos(file_name, profile_name);

==============================================================================

Notice that the suggested approach allows to easily extend the supported format for QoS representation w/o any impact on the core DDS API and overall facilitate the support for multiple approaches.

The suggestion is to remove the added methods from the core API and use instead a Builder pattern (of some form).
A sketch of the suggested change is provided below:
PolicyBuilder builder = PolicyBuilder::load("XMLBuilder");
TopicQos tqos = builder.topic_qos(file_name, profile_name);
Notice that the suggested approach allows to easily extend the supported format for QoS representation w/o any impact on the core DDS API and overall facilitate the support for multiple approaches

Currently the DataReader provides read() and take() methods that return a special type of java.util.ListIterator: Sample.Iterator. The Iterator is not the most convenient way to access data retrieved from the DataReader (e.g. an Iterator can only be traversed once).

Propose to modify all read()/take() operations currently returning an Iterator to let them return a java.util.List. The List is more developer friendly, as it can be traversed multiple times and a List is also an Iterable with the added benefit that it can be used in Java’s “foreach” statement:

List<Sample<TYPE>> data = dataReader.read();

for (Sample<Type> sample : data)

Merge this issue with #16321, which proposes other changes to the read/take overloads.
• Overloads that return a loan should do so in the form of a ListIterator implementation, which will allows multiple forward and backward navigation of elements. The loaned samples should not be returned as a List, as retrieving an iterator from a list would force critical-path memory allocation—in direct contradiction of the low-latency goal of the loaning operations.
• Overloads that return a copy should continue to accept a List to be filled in and should return a reference to the same list for convenience. These overloads will therefore support the “for-each” construct requested by this issue.
Disposition: Merged with issue #16321

The ModifiableEntityQos contains put() definition that, after type erasure, cannot be distinguished from the inherited put definition in EntityQos (or the one inherited from Map) resulting in duplicate definitions of put: QosPolicy<?,?> put(QosPolicy.Id, QosPolicy<?,?>)

Possible ways to resolve this:

·Drop the “extends Map” in EntityQos and put a dedicated get() in EntityQos and a dedicated put()/set() in ModifiableEntityQos and leave it up to the implementation on how to manage these values. This is the preferred solution as it prevents the user of the API to accidently use the Map inherited modification methods like put/remove/clear on a non-modifiable EntityQos.

·Modify the signature of put() in ModifiableEntityQos to match the inherited definitions in EntityQos and Map:

public QosPolicy<?,?> put(QosPolicy.Id key, QosPolicy<?,?> value);

See the modifications described below.

The DDS-PSM-Java currently provides examples of the the new mapping from the DDS type system to the Java programming language but does not provide a formal description of how topic types are mapped to Java classes. This underspecification should be filled to align the DDS-PSM-Java with the DDS-PSM-Cxx and to ensure that different/old mappings are used by DDS implementations.

No Data Available

DDS code will be easier to integrate into third-party I/O code if the Entity, ReadCondition, and TopicDescription interfaces implement the java.util.Closeable interface. This is especially true under Java 7, which provides specific new language constructs for dealing with this interface.

The only method in the interface is a no-argument close(), which all of these interfaces already have.

Proposed Resolution:
Update Entity, ReadCondition, and TopicDescription to inherit from java.io.Closeable.

The base interface for all Entity-level QoS objects (e.g. DataReaderQos) is org.omg.dds.core.EntityQos. At one time during the evolution of the specification, this interface was called org.omg.dds.core.Qos. Due to an editorial oversight, this obsolete name persists in the specification document and should be updated.

• Section 7.2.5, "QoS and QoS Policies"
• Section 7.2.5.2, "Entity QoS"

Update the specification document.

ContentFiltered topics, QueryCondition, and MultiTopic all require a "Query" parameter made by an expression and a set of parameters. The current API, however treats the expression and the parameter as individual parameters and does not provide any abstraction of what could represent a generic DDS query. This makes the API more verbose and more error prone.

Resolution
---------------
Add a Query class that abstracts over the concept of a DDS query: an expression and a collection of mutable parameters

Add a Query class that abstracts over the concept of a DDS query: an expression and a collection of mutable parameters

Java 7 has a try-with-resources construct that allows a close() method to be called automatically when a certain code block ends. Java PSM can support this construct with sample loans in a way that's backwards compatible with Java 5. All we have to do is to rename the Sample.Iterator.returnLoan() method to close() and make Sample.Iterator implement the interface java.io.Closeable. Note: java.lang.AutoCloseable is available only since 1.7

Proposed Resolution:
Inherit Sample.Iterator from Java.io.Closeable and rename the Sample.Iterator.returnLoan() method to close()

The second FTF of the DDS-XTypes spec introduced several API changes that should be incorporated into the DDS-PSM-Java spec.

At the same time, the contents of the relevant portions of the DDS-XTypes spec should be incorporated as JavaDoc comments, just as has already been done for DDS itself.

No Data Available

The dds-psm-java uses a superfluous "QoSPolicy" suffix to name the DDS policies which themselves are already included in a "policy" namespace.

This issue is identical to issue #16530. This issue is created to revote on the decision taken on issue #16530 in the earlier FTF.

Proposed Resolution:

This suffix should be removed. This resolution will also make Java PSM consistent with the C++ PSM, which does not use "QosPolicy" suffix.

This suffix should be removed. This resolution will also make Java PSM consistent with the C++ PSM, which does not use "QosPolicy" suffix. This issue requires no changes to the specification document

The EntityQos interface implements java.util.Map. However, all checking of which policies apply to which Entity types is deferred to run time. The extension of Map should be updated to constrain which policies may legally be used.

Proposal: Introduce marker interfaces for each Entity type and parameterize Map with these interfaces.

Introduce marker interfaces for each Entity type and parameterize Map with these interfaces. This issue requires no changes in the specification document.

The Entity interface inherits from java.io.Closeable and overrides the close() operation to NOT throw java.io.IOException. But some inherited entities such as DataReader and DataWriter might have to throw IOException on closure as their implementation might use sockets.

On the other hand the Sample.Iterator interface also inherits from java.io.Closeable but its close() operation declare to throw IOException. There should not be any IOException in this case since the Samples are already received by the DaraReader

The use of Collection for providing a single "parameter" is rather cumbersome and could be greatly improved by providing a "varargs" alternative.

Here is an example that showcases the issue:
p = dp.createPublisher(
dp.getDefaultPublisherQos().withPolicy(
pf.Partition().withName(Arrays.asList("MyPartition"))
));

In this case a withName(String... names) operation will simplify the code as shown below:
p = dp.createPublisher(
dp.getDefaultPublisherQos().withPolicy(
pf.Partition().withName("MyPartition")
));

Moreover the use of Collection type could lead to compilation error as in the following case:

statusCondition.setEnabledStatuses(Arrays.toList(DataAvailableStatus.class));

The StatusCondition should be immutable and follow the same pattern than QoS policies:

public interface StatusCondition<ENTITY extends Entity<?, ?>>
extends Condition

This allow simpler code such as following:
waitset.attachCondition(
reader.getStatusCondition().withEnabledStatuses(DataAvailableStatus.class));

The Javadoc description of the DomainParticipantFactory.createParticipant(domain, qos, listener, statuses) operation is following:

"This operation creates a new DomainParticipant object having default QoS and no listener..."

It should be replaced with following:

"This operation creates a new DomainParticipant object with the specified QoS and the specified listener..."

In DomainParticipantFactoryQoS interface the following operation are defined:

public DomainParticipantFactoryQos withPolicy(
QosPolicy.ForDataWriter policy);

public DomainParticipantFactoryQos withPolicies(
QosPolicy.ForDataWriter... policy);

In both operations the correct parameter type should be QosPolicy.ForDomainParticipantFactory.

The PolicyFactory class provides operation to create all Policies but Presentation and TopicData.

Also, the Representation() operation should be renamed as DataRepresentation() to ensure consistency with the other factory operations (each is named accordingly to the type it returns).

"many of which do support Java EE"

should be

"many of which do not support Java EE"

The resolution for the ISSUE 15996 required to remove all the operations of the kind:

"public void setQos(String qosLibraryName, String qosProfileName);"

from all DDS entities since this operation pollutes the DDS API with a specific way of configuring QoS policies. The accepted resolution was to introduce the concept of a QoSProvider that could provide QoS settings by fetching them from a URI.

That said the type org.omg.dds.core.Entity still contains the operation:

public void setQos(String qosLibraryName, String qosProfileName);

This should be removed!

The DataReaderQos specifies accessors for all QosPolicy.ForDataReader policies but Reliability.

In TypeSupport class the newTypeSupport() operation is implemented as following:

public static <TYPE> TypeSupport<TYPE> newTypeSupport(
Class<TYPE> type,
ServiceEnvironment env)

The correct implementation should be:

public static <TYPE> TypeSupport<TYPE> newTypeSupport(
Class<TYPE> type,
ServiceEnvironment env)

Since type.getClass().getName() always return "java.lang.Class".

In WaitSet class, all waitForCondition() operation should return a Collection of the triggered conditions. The "activeConditions" parameter should be removed.

The WaitSet class should be aligned to the ISO C++ IDDS PSM with regard to the dispatch() operation and associated functor.

The ModifiableInstanceHandle was not removed along with all other modifiable types.
As such it should be removed for consistency, useability and performances.

Specificaly the following methods should be removed:

• ServiceEnvironment.newInstanceHandle()
• DataReader.lookupInstance(ModifiableInstanceHandle handle, TYPE keyHolder)
• DataWriter.lookupInstance(ModifiableInstanceHandle handle, TYPE keyHolder)

And the following method should be modified to return InstanceHandle:

• Sample.getInstanceHandle()
• Sample.getPublicationHandle()

Notice: the returning ModifialbeInstanceHandle forces defensive copying with obvious consequences in term of performances.

The current Java PSM makes an implicit assumptions on member ordering when defining DDS Types in POJO that is not inherently guaranteed by the Java Language Specification. The possible resolution for this issue is to require @ID annotations when defining DDS Types using POJOs. In this case the ID would be used to uniquely defining the order to the attribute members.

Bucket accessors were supposed to be removed for all types (with exception of Time) as part of the FTF.
Apparently some bucket accessors are still present (in some cases as the only possibility - e.g. Subscriber.getDataReaders()).

This is very unfortunate since it forces defensive copies with the obvious performance impacts.
Furthermore it makes the API inconsistent.

Instead of providing the requestedOfferedContract() method for RxO comparison, the inherited Compare implementation should follow the RxO rules.

For instance: Deadline(2) > Deadline(5)
This change simplify the API and avoids the creation of temporary object when trying to evaluate RxO. Notice that, in this case, the natural ordering is still available via the Duration type.