Feature/con 188 (#18)

* CON-188: Added docs + tests

* CON-188: Revert changes to package.json

* CON-188: Change of functionality

Previously, any non-key fields would be returned as null when obtain
via DD_GET operations. This is no longer the case.

* CON-188: Remove debug

* CON-188: PR feedback

- doc related

* CON-188: PR Feedback

- Do not access non-key fields in the unit tests
- Fix docs

Co-authored-by: Sam Raeburn <sam@rti.com>

Author: samuelraeburn

docs/data.rst

@@ -452,3 +452,54 @@ In an :class:`Input`, you can obtain the selected member as a string::
     if (input.samples.get(0).getString('my_union#') == 'point') {
         value = input.samples.get(0).getNumber('my_union.point.x')
     }
+
+Accessing key values of disposed samples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Using :meth:`Output.write`, an :class:`Output` can write data, or dispose or 
+unregister an instance.
+Depending on which of these operations is performed, the ``instance_state`` of the
+received sample will be ``'ALIVE'``, ``'NOT_ALIVE_NO_WRITERS'`` or ``'NOT_ALIVE_DISPOSED'``.
+If the instance was disposed, this ``instance_state`` will be ``'NOT_ALIVE_DISPOSED'``.
+In this state, it is possible to access the key fields of the instance that was disposed.
+
+.. note::
+    :attr:`SampleInfo.valid_data` will be false when the :attr:`SampleInfo.instance_state`
+    is ``'NOT_ALIVE_DISPOSED'``. In this situation it's possible to access the
+    key fields in the received sample.
+
+The key fields can be accessed as follows:
+
+.. code-block::
+
+    // The output and input are using the following type:
+    // struct ShapeType {
+    //     @key string<128> color;
+    //     long x;
+    //     long y;
+    //     long shapesize;
+    // }
+
+    output.instance.set('x', 4)
+    output.instance.set('color', 'Green')
+    // Assume that some data associated with this instance has already been sent
+    output.write({ action: 'dispose' })
+    await input.wait()
+    input.take()
+    let sample = input.samples.get(0)
+
+    if (sample.info.get('instance_state') === 'NOT_ALIVE_DISPOSED') {
+        // sample.info.get('valid_data') will be false in this situation
+        // Only the key-fields should be accessed
+        let color = sample.get('color') // 'Green'
+        // The fields 'x','y' and 'shapesize' cannot be retrieved because they're
+        // not part of the key
+        // You can also call getJson() to get all of the key fields in a JSON object.
+        // Again, only the key fields returned within the JSON object should
+        // be used.
+        let keyValues = sample.getJson() // { color: 'Green', x: 0, y: 0, shapesize: 0 }
+    }
+
+.. warning::
+    When the sample has an instance state of ``'NOT_ALIVE_DISPOSED'`` only the
+    key fields should be accessed.

docs/input.rst

@@ -121,7 +121,7 @@ After calling :meth:`Input.read()` or :meth:`Input.take()`,
 
 :meth:`SampleIterator.getJson()` retrieves all the fields of a sample.
 
-If you don't need to access the meta-data (see :ref:`Accessing the SampleInfo`),
+If you don't need to access the meta-data (see :ref:`Accessing sample meta-data`),
 the simplest way to access the data is to use :attr:`Samples.validDataIter` 
 to skip samples with invalid data:
 
@@ -177,15 +177,11 @@ for example:
 
 See more information and examples in :ref:`Accessing the data`.
 
-Accessing the SampleInfo
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-*Connext DDS* can produce samples with invalid data, which contain meta-data only.
-For more information about this, see `Valid Data Flag 
-<https://community.rti.com/static/documentation/connext-dds/current/doc/manuals/connext_dds/html_files/RTI_ConnextDDS_CoreLibraries_UsersManual/index.htm#UsersManual/The_SampleInfo_Structure.htm#receiving_2076951295_727613>`__
-in the *RTI Connext DDS Core Libraries User's Manual*.
+Accessing sample meta-data
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can access a field of the sample meta-data, the *SampleInfo*, as follows:
+Every sample contains an associated *SampleInfo* with meta-information about the
+sample:
 
 .. code-block::
 
@@ -195,6 +191,19 @@ You can access a field of the sample meta-data, the *SampleInfo*, as follows:
 
 See :attr:`SampleIterator.info` for the list of available meta-data fields.
 
+*Connext DDS* can produce samples with invalid data, which contain meta-data only.
+For more information about this, see `Valid Data Flag 
+<https://community.rti.com/static/documentation/connext-dds/current/doc/manuals/connext_dds/html_files/RTI_ConnextDDS_CoreLibraries_UsersManual/index.htm#UsersManual/The_SampleInfo_Structure.htm#receiving_2076951295_727613>`__
+in the *RTI Connext DDS Core Libraries User's Manual*.
+These samples indicate a change in the instance state. Samples with invalid data
+still provide the following information:
+
+* The :class:`SampleInfo`
+* When an instance is disposed (``sample.info.get('instance_state')`` is
+  ``'NOT_ALIVE_DISPOSED'``), the sample data contains the value of the key that
+  has been disposed. You can access the key fields only. See
+  :ref:`Accessing key values of disposed samples`.
+
 Matching with a Publication
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

test/nodejs/test_rticonnextdds_data_access.js

@@ -70,7 +70,7 @@ describe('Data access tests with a pre-populated input', function () {
     } catch (err) {
       console.log('Caught err: ' + err)
       // Fail the test
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
     // Write data on the the output
     output.instance.setFromJson(testJsonObject)
@@ -81,7 +81,7 @@ describe('Data access tests with a pre-populated input', function () {
     } catch (err) {
       console.log('Caught err: ' + err)
       // Fail the test
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
     // Take the data on the input so that we can access it from the test
     prepopulatedInput.take()
@@ -388,7 +388,7 @@ describe('Tests with a testOutput and testInput', () => {
       expect(newMatches).to.deep.equals(1)
     } catch (err) {
       console.log('Caught err ' + err)
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
   })
 
@@ -512,7 +512,7 @@ describe('Tests with a testOutput and testInput', () => {
       await testInput.wait(testExpectSuccessTimeout)
     } catch (err) {
       console.log('Caught err: ' + err)
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
     testInput.take()
     const received = testInput.samples.get(0).get('my_int_sequence')
@@ -531,7 +531,7 @@ describe('Tests with a testOutput and testInput', () => {
       await testInput.wait(testExpectSuccessTimeout)
     } catch (err) {
       console.log('Caught error: ' + err)
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
     testInput.take()
     const received = testInput.samples.get(0).get('my_point_sequence')
@@ -545,7 +545,7 @@ describe('Tests with a testOutput and testInput', () => {
       await testInput.wait(testExpectSuccessTimeout)
     } catch (err) {
       console.log('Caught error: ' + err)
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
     testInput.take()
     const sample = testInput.samples.get(0)
@@ -1017,14 +1017,14 @@ describe('Tests with two readers and two writers', () => {
       expect(newMatches).to.deep.equals(1)
     } catch (err) {
       console.log('Caught err: ' + err)
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
     try {
       const newMatches = await testOutput2.waitForSubscriptions(testExpectSuccessTimeout)
       expect(newMatches).to.deep.equals(1)
     } catch (err) {
       console.log('Caught err: ' + err)
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
   })
 
@@ -1041,7 +1041,7 @@ describe('Tests with two readers and two writers', () => {
     try {
       await connector.wait(testExpectFailureTimeout)
       console.log('Expected connector.wait to timeout but it did not')
-      expect(true).to.deep.equals(false)
+      throw(err)
     } catch (err) {
       expect(err).to.be.an.instanceof(rti.TimeoutError)
     }
@@ -1051,7 +1051,7 @@ describe('Tests with two readers and two writers', () => {
     try {
       await testInput1.wait(testExpectFailureTimeout)
       console.log('Expected testInput1.wait to timeout but it did not')
-      expect(true).to.deep.equals(false)
+      throw(err)
     } catch (err) {
       expect(err).to.be.an.instanceof(rti.TimeoutError)
     }
@@ -1061,7 +1061,7 @@ describe('Tests with two readers and two writers', () => {
     try {
       await testInput2.wait(testExpectFailureTimeout)
       console.log('Expected testInput2.wait to timeout but it did not')
-      expect(true).to.deep.equals(false)
+      throw(err)
     } catch (err) {
       expect(err).to.be.an.instanceof(rti.TimeoutError)
     }
@@ -1073,7 +1073,7 @@ describe('Tests with two readers and two writers', () => {
       await connector.wait(testExpectSuccessTimeout)
     } catch (err) {
       console.log('Caught err: ' + err)
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
   })
 
@@ -1083,7 +1083,7 @@ describe('Tests with two readers and two writers', () => {
       await testInput1.wait(testExpectSuccessTimeout)
     } catch (err) {
       console.log('Caught err: ' + err)
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
   })
 
@@ -1092,7 +1092,7 @@ describe('Tests with two readers and two writers', () => {
     try {
       await testInput2.wait(testExpectFailureTimeout)
       console.log('Expected testInput2.wait to timeout but it did not')
-      expect(true).to.deep.equals(false)
+      throw(err)
     } catch (err) {
       expect(err).to.be.an.instanceof(rti.TimeoutError)
     }
@@ -1104,7 +1104,7 @@ describe('Tests with two readers and two writers', () => {
       await connector.wait(testExpectSuccessTimeout)
     } catch (err) {
       console.log('Caught err: ' + err)
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
   })
 
@@ -1114,7 +1114,7 @@ describe('Tests with two readers and two writers', () => {
       await testInput2.wait(testExpectSuccessTimeout)
     } catch (err) {
       console.log('Caught err: ' + err)
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
   })
 
@@ -1123,7 +1123,7 @@ describe('Tests with two readers and two writers', () => {
     try {
       await testInput1.wait(testExpectFailureTimeout)
       console.log('Expected testInput2.wait to timeout but it did not')
-      expect(true).to.deep.equals(false)
+      throw(err)
     } catch (err) {
       expect(err).to.be.an.instanceof(rti.TimeoutError)
     }

test/nodejs/test_rticonnextdds_dataflow.js

@@ -39,7 +39,7 @@ params.forEach((retrievalMethod) => {
         expect(matches).to.be.at.least(1)
       } catch (err) {
         console.log('Caught err: ' + err)
-        expect(true).to.deep.equals(false)
+        throw(err)
       }
     })
 
@@ -57,7 +57,7 @@ params.forEach((retrievalMethod) => {
         await input.wait(testExpectSuccessTimeout)
       } catch (err) {
         console.log('Caught err: ' + err)
-        expect(true).to.deep.equals(false)
+        throw(err)
       }
       input[retrievalMethod]()
       expect(input.samples.length).to.be.at.least(1)

test/nodejs/test_rticonnextdds_discovery.js

@@ -188,7 +188,7 @@ describe('Discovery tests', function () {
       } catch (err) {
         console.log('Caught error: ' + err)
         // Fail the test
-        expect(true).to.deep.equals(false)
+        throw(err)
       }
     }
     expect(totalMatches).to.be.at.least(2)
@@ -223,7 +223,7 @@ describe('Discovery tests', function () {
       } catch (err) {
         console.log('Caught error: ' + err)
         // Fail the test
-        expect(true).to.deep.equals(false)
+        throw(err)
       }
     }
     expect(totalMatches).to.be.at.least(2)
@@ -369,7 +369,7 @@ describe('Discovery tests', function () {
     } catch (err) {
       console.log('Caught error: ' + err)
       // Fail the test
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
 
     // Get the entity names of the matched subs
@@ -395,7 +395,7 @@ describe('Discovery tests', function () {
     } catch (err) {
       console.log('Caught error: ' + err)
       // Fail the test
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
     const matches = output.matchedSubscriptions
     expect(matches.length).to.deep.equals(1)

test/nodejs/test_rticonnextdds_events.js

@@ -78,7 +78,7 @@ describe('Connector EventEmitter tests', function () {
       .then(() => {
         // This should not have been possible
         console.log('Error occurred. Expected wait to fail due to waitSetBusy')
-        expect(true).to.deep.equals(false)
+        throw(err)
       })
       .catch((err) => {
         expect(err.message).to.deep.equals('Can not concurrently wait on the same Connector object')

test/nodejs/test_rticonnextdds_input.js

@@ -97,7 +97,7 @@ describe('Subscriber not automatically enabled tests', () => {
       expect(newMatches).to.deep.equals(1)
     } catch (err) {
       console.log('Caught err: ' + err)
-      expect(true).to.deep.equals(false)
+      throw(err)
     }
   })
 })