Document JSON/Jackson support

build.gradle

@@ -198,7 +198,7 @@ dokka {
     moduleName = 'corda'
     outputDirectory = 'docs/build/html/api/kotlin'
     processConfigurations = ['compile']
-    sourceDirs = files('core/src/main/kotlin', 'client/src/main/kotlin', 'node/src/main/kotlin', 'finance/src/main/kotlin')
+    sourceDirs = files('core/src/main/kotlin', 'client/src/main/kotlin', 'node/src/main/kotlin', 'finance/src/main/kotlin', 'client/jackson/src/main/kotlin')
 }
 
 task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {
@@ -206,7 +206,7 @@ task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {
     outputFormat = "javadoc"
     outputDirectory = 'docs/build/html/api/javadoc'
     processConfigurations = ['compile']
-    sourceDirs = files('core/src/main/kotlin', 'client/src/main/kotlin', 'node/src/main/kotlin', 'finance/src/main/kotlin')
+    sourceDirs = files('core/src/main/kotlin', 'client/src/main/kotlin', 'node/src/main/kotlin', 'finance/src/main/kotlin', 'client/jackson/src/main/kotlin')
 }
 
 task apidocs(dependsOn: ['dokka', 'dokkaJavadoc'])

client/jackson/build.gradle

@@ -3,7 +3,12 @@ apply plugin: 'kotlin'
 apply plugin: 'net.corda.plugins.publish-utils'
 
 repositories {
+    mavenLocal()
     mavenCentral()
+    jcenter()
+    maven {
+        url 'https://dl.bintray.com/kotlin/exposed'
+    }
 }
 
 dependencies {

client/jackson/src/main/kotlin/net/corda/jackson/JacksonSupport.kt

@@ -28,6 +28,8 @@ import java.time.LocalDateTime
  * Note that Jackson can also be used to serialise/deserialise other formats such as Yaml and XML.
  */
 object JacksonSupport {
+    // If you change this API please update the docs in the docsite (json.rst)
+
     interface PartyObjectMapper {
         fun partyFromName(partyName: String): Party?
         fun partyFromKey(owningKey: CompositeKey): Party?
@@ -84,13 +86,16 @@ object JacksonSupport {
         }
     }
 
-    /* Mapper requiring RPC support to deserialise parties from names */
+    /** Mapper requiring RPC support to deserialise parties from names */
+    @JvmStatic
     fun createDefaultMapper(rpc: CordaRPCOps): ObjectMapper = configureMapper(RpcObjectMapper(rpc))
 
-    /* For testing or situations where deserialising parties is not required */
+    /** For testing or situations where deserialising parties is not required */
+    @JvmStatic
     fun createNonRpcMapper(): ObjectMapper = configureMapper(NoPartyObjectMapper())
 
-    /* For testing with an in memory identity service */
+    /** For testing with an in memory identity service */
+    @JvmStatic
     fun createInMemoryMapper(identityService: IdentityService) = configureMapper(IdentityObjectMapper(identityService))
 
     private fun configureMapper(mapper: ObjectMapper): ObjectMapper = mapper.apply {

docs/source/index.rst

@@ -109,6 +109,7 @@ Documentation Contents:
    network-simulator
    clauses
    merkle-trees
+   json
 
 .. toctree::
    :maxdepth: 2

docs/source/json.rst

@@ -0,0 +1,42 @@
+.. highlight:: kotlin
+.. raw:: html
+
+   <script type="text/javascript" src="_static/jquery.js"></script>
+   <script type="text/javascript" src="_static/codesets.js"></script>
+
+JSON
+====
+
+Corda provides a module that extends the popular Jackson serialisation engine. Jackson is often used to serialise
+to and from JSON, but also supports other formats such as YaML and XML. Jackson is itself very modular and has
+a variety of plugins that extend its functionality. You can learn more at the `Jackson home page <https://github.com/FasterXML/jackson>`_.
+
+To gain support for JSON serialisation of common Corda data types, include a dependency on ``net.corda:jackson:XXX``
+in your Gradle or Maven build file, where XXX is of course the Corda version you are targeting (0.9 for M9, for instance).
+Then you can obtain a Jackson ``ObjectMapper`` instance configured for use using the ``JacksonSupport.createNonRpcMapper()``
+method. There are variants of this method for obtaining Jackson's configured in other ways: if you have an RPC
+connection to the node (see ":doc:`clientrpc`") then your JSON mapper can resolve identities found in objects.
+
+The API is described in detail here:
+
+* `Kotlin API docs <api/kotlin/corda/net.corda.jackson/-jackson-support/index.html>`_
+* `JavaDoc <api/javadoc/net/corda/jackson/package-summary.html>`_
+
+.. container:: codeset
+
+   .. sourcecode:: kotlin
+
+      import net.corda.jackson.JacksonSupport
+
+      val mapper = JacksonSupport.createNonRpcMapper()
+      val json = mapper.writeValueAsString(myCordaState)  // myCordaState can be any object.
+
+   .. sourcecode:: java
+
+      import net.corda.jackson.JacksonSupport
+
+      ObjectMapper mapper = JacksonSupport.createNonRpcMapper()
+      String json = mapper.writeValueAsString(myCordaState)  // myCordaState can be any object.
+
+
+.. note:: The way mappers interact with identity and RPC is likely to change in a future release.