CORDA-908 - Support private properties in AMQP serialization (#2336)

CORDA-908 - Support private properties in AMQP serialization

* Review comments

* Fix tests

* Review Comments

* review comments

* review comments

docs/source/serialization.rst

@@ -1,6 +1,8 @@
 Object serialization
 ====================
 
+.. contents::
+
 What is serialization (and deserialization)?
 --------------------------------------------
 
@@ -52,7 +54,7 @@ was a compelling use case for the definition and development of a custom format
 
     #.  A desire to have a schema describing what has been serialized along-side the actual data:
 
-        #.  To assist with versioning, both in terms of being able to interpret long ago archivEd data (e.g. trades from
+        #.  To assist with versioning, both in terms of being able to interpret long ago archived data (e.g. trades from
             a decade ago, long after the code has changed) and between differing code versions.
         #.  To make it easier to write user interfaces that can navigate the serialized form of data.
         #.  To support cross platform (non-JVM) interaction, where the format of a class file is not so easily interpreted.
@@ -76,7 +78,7 @@ Finally, for the checkpointing of flows Corda will continue to use the existing
 
 This separation of serialization schemes into different contexts allows us to use the most suitable framework for that context rather than
 attempting to force a one size fits all approach. Where ``Kryo`` is more suited to the serialization of a programs stack frames, being more flexible
-than our AMQP framework in what it can construct and serialize, that flexibility makes it exceptionally difficult to make secure. Conversly
+than our AMQP framework in what it can construct and serialize, that flexibility makes it exceptionally difficult to make secure. Conversely
 our AMQP framework allows us to concentrate on a robust a secure framework that can be reasoned about thus made safer with far fewer unforeseen
 security holes.
 
@@ -282,22 +284,6 @@ serialised form
 
         val e2 = e.serialize().deserialize() // e2.c will be 20, not 100!!!
 
-.. warning:: Private properties in Kotlin classes render the class unserializable *unless* a public
-    getter is manually defined. For example:
-
-    .. container:: codeset
-
-        .. sourcecode:: kotlin
-
-            data class C(val a: Int, private val b: Int) {
-                // Without this C cannot be serialized
-                public fun getB() = b
-            }
-
-    .. note:: This is particularly relevant as IDE's can often point out where they believe a
-        property can be made private without knowing this can break Corda serialization. Should
-        this happen then a run time warning will be generated when the class fails to serialize
-
 Setter Instantiation
 ''''''''''''''''''''
 
@@ -330,6 +316,75 @@ For example:
             public void setC(int c) { this.c = c; }
         }
 
+Inaccessible Private Properties
+```````````````````````````````
+
+Whilst the Corda AMQP serialization framework supports private object properties without publicly
+accessible getter methods this development idiom is strongly discouraged.
+
+For example.
+
+    .. container:: codeset
+
+        Kotlin:
+
+        .. sourcecode:: kotlin
+
+            data class C(val a: Int, private val b: Int)
+
+        Java:
+
+        .. sourcecode:: Java
+
+            class C {
+                public Integer a;
+                private Integer b;
+
+                C(Integer a, Integer b) {
+                    this.a = a;
+                    this.b = b;
+                }
+            }
+
+When designing stateful objects is should be remembered that they are not, despite appearances, traditional
+programmatic constructs. They are signed over, transformed, serialised, and relationally mapped. As such,
+all elements should be publicly accessible by design
+
+.. warning:: IDEs will indiciate erroneously that properties can be given something other than public
+    visibility. Ignore this as whilst it will work, as discussed above there are many reasons why this isn't
+    a good idea and those are beyond the scope of the IDEs inference rules
+
+Providing a public getter, as per the following example, is acceptable
+
+    .. container:: codeset
+
+        Kotlin:
+
+        .. sourcecode:: kotlin
+
+            data class C(val a: Int, private val b: Int) {
+                public fun getB() = b
+            }
+
+        Java:
+
+        .. sourcecode:: Java
+
+            class C {
+                public Integer a;
+                private Integer b;
+
+                C(Integer a, Integer b) {
+                    this.a = a;
+                    this.b = b;
+                }
+
+                public Integer getB() {
+                    return b;
+                }
+            }
+
+
 Enums
 `````