Merge pull request #988 from corda/merges/june-13-13-27

Merges: June 13 at 13:27

docs/Makefile

@@ -16,6 +16,8 @@ endif
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+HTMLSPHINXOPTS   = $(ALLSPHINXOPTS) -t htmlmode
+PDFSPHINXOPTS   = $(ALLSPHINXOPTS) -t pdfmode
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
@@ -52,17 +54,17 @@ clean:
 	rm -rf $(BUILDDIR)/*
 
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -b html $(HTMLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	$(SPHINXBUILD) -b dirhtml $(HTMLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	$(SPHINXBUILD) -b singlehtml $(HTMLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
@@ -77,7 +79,7 @@ json:
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	$(SPHINXBUILD) -b htmlhelp $(HTMLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
@@ -114,20 +116,20 @@ epub:
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD) -b latex $(PDFSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
 latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD) -b latex $(PDFSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD) -b latex $(PDFSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through platex and dvipdfmx..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
@@ -192,4 +194,4 @@ pseudoxml:
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
 
 pdf:
-	$(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $(BUILDDIR)/pdf
+	$(SPHINXBUILD) -b pdf $(PDFSPHINXOPTS) $(BUILDDIR)/pdf

docs/make-docsite.sh

@@ -13,11 +13,10 @@ fi
 
 # TODO: The PDF rendering is pretty ugly and can be improved a lot.
 echo "Generating PDF document ..."
-make pdf
+make latexpdf
 
 echo "Generating HTML pages ..."
 make html
 
-echo "Moving PDF file into place ..."
+echo "Moving PDF file from $(eval echo $PWD/build/pdf/corda-developer-site.pdf) to $(eval echo $PWD/build/html/_static/corda-developer-site.pdf)"
-mv $PWD/build/pdf/corda-developer-site.pdf $PWD/build/html/_static/corda-developer-site.pdf
+mv $PWD/build/latex/corda-developer-site.pdf $PWD/build/html/_static/corda-developer-site.pdf
-

docs/source/changelog.rst

@@ -8,6 +8,8 @@ Unreleased
 ==========
 * Introduced a hierarchy of ``DatabaseMigrationException``s, allowing ``NodeStartup`` to gracefully inform users of problems related to database migrations before exiting with a non-zero code.
 
+* Improved documentation PDF quality. Building the documentation now requires ``LaTex`` to be installed on the OS.
+
 * Add ``devModeOptions.allowCompatibilityZone`` to re-enable the use of a compatibility zone and ``devMode``
 
 * Fixed an issue where ``trackBy`` was returning ``ContractStates`` from a transaction that were not being tracked. The
@@ -153,12 +155,15 @@ Version 3.1
 
 * Update the fast-classpath-scanner dependent library version from 2.0.21 to 2.12.3
 
+  .. note:: Whilst this is not the latest version of this library, that being 2.18.1 at time of writing, versions
+     later than 2.12.3 (including 2.12.4) exhibit a different issue.
+
 * Added `database.hibernateDialect` node configuration option
 
 .. _changelog_r3_v3:
 
 Corda Enterprise 3.0 Developer Preview
-------------------------------
+--------------------------------------
 
 * Fix CORDA-1229. Setter-based serialization was broken with generic types when the property was stored as the raw type, List for example.
 

docs/source/conf.py

@@ -14,7 +14,6 @@
 
 import sphinx_rtd_theme
 
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -33,6 +32,7 @@ pdf_documents = [('index', u'corda-developer-site', u'Corda Developer Documentat
 pdf_stylesheets = ['sphinx', 'kerning', 'a4', 'murphy', 'tenpoint']
 pdf_compressed = True
 pdf_fit_mode = "shrink"
+pdf_fit_background_mode = "shrink"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -79,6 +79,8 @@ language = None
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = []
+if tags.has('pdfmode'):
+    exclude_patterns = ['./design']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -109,7 +111,6 @@ highlight_language = 'kotlin'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -215,27 +216,7 @@ htmlhelp_basename = 'R3doc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
-latex_elements = {
+latex_documents = [('index', u'corda-developer-site.tex', u'Corda Developer Documentation', u'R3', 'manual', False)]
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
-
-# Latex figure (float) alignment
-#'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-  (master_doc, 'R3Prototyping.tex', u'R3 Prototyping Documentation',
-   u'R3 CEV', 'manual'),
-]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
@@ -256,3 +237,21 @@ latex_documents = [
 
 # If false, no module index is generated.
 # latex_domain_indices = True
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    # 'figure_align': 'htbp',
+
+    'maxlistdepth': 2000,
+
+    'extraclassoptions': 'openany',
+}

docs/source/index.rst

@@ -57,6 +57,8 @@ application development please continue to refer to `the main project documentat
    loadtesting.rst
    certificate-revocation
 
+.. only:: htmlmode
+
    .. toctree::
       :caption: Design docs
       :maxdepth: 2

docs/source/key-concepts-consensus.rst

@@ -7,6 +7,8 @@ Consensus
    * *Validity consensus requires contractual validity of the transaction and all its dependencies*
    * *Uniqueness consensus prevents double-spends*
 
+.. only:: htmlmode
+
    Video
    -----
    .. raw:: html
@@ -14,6 +16,7 @@ Video
        <iframe src="https://player.vimeo.com/video/214138438" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
        <p></p>
 
+
 Two types of consensus
 ----------------------
 Determining whether a proposed transaction is a valid ledger update involves reaching two types of consensus:

docs/source/key-concepts-contracts.rst

@@ -7,6 +7,8 @@ Contracts
    * *Contracts are written in a JVM programming language (e.g. Java or Kotlin)*
    * *Contract execution is deterministic and its acceptance of a transaction is based on the transaction's contents alone*
 
+.. only:: htmlmode
+
    Video
    -----
    .. raw:: html
@@ -14,6 +16,7 @@ Video
        <iframe src="https://player.vimeo.com/video/214168839" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
        <p></p>
 
+
 Transaction verification
 ------------------------
 Recall that a transaction is only valid if it is digitally signed by all required signers. However, even if a

docs/source/key-concepts-flows.rst

@@ -7,6 +7,8 @@ Flows
    * *Communication between nodes only occurs in the context of these flows, and is point-to-point*
    * *Built-in flows are provided to automate common tasks*
 
+.. only:: htmlmode
+
     Video
     -----
     .. raw:: html
@@ -14,6 +16,7 @@ Video
         <iframe src="https://player.vimeo.com/video/214046145" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
         <p></p>
 
+
 Motivation
 ----------
 Corda networks use point-to-point messaging instead of a global broadcast. This means that coordinating a ledger update
@@ -22,10 +25,20 @@ what order.
 
 Here is a visualisation of the process of agreeing a simple ledger update between Alice and Bob:
 
+.. only:: htmlmode
+
    .. image:: resources/flow.gif
       :scale: 25%
       :align: center
 
+
+.. only:: pdfmode
+
+   .. image:: resources/flow.png
+      :scale: 25%
+      :align: center
+
+
 The flow framework
 ------------------
 Rather than having to specify these steps manually, Corda automates the process using *flows*. A flow is a sequence

docs/source/key-concepts-ledger.rst

@@ -6,6 +6,8 @@ The ledger
    * *The ledger is subjective from each peer's perspective*
    * *Two peers are always guaranteed to see the exact same version of any on-ledger facts they share*
 
+.. only:: htmlmode
+
    Video
    -----
    .. raw:: html
@@ -13,6 +15,7 @@ Video
        <iframe src="https://player.vimeo.com/video/213812040" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
        <p></p>
 
+
 Overview
 --------
 In Corda, there is **no single central store of data**. Instead, each node maintains a separate database of known

docs/source/key-concepts-node.rst

@@ -11,6 +11,8 @@ Nodes
 
    * *The node's functionality is extended by installing CorDapps in the plugin registry*
 
+.. only:: htmlmode
+
    Video
    -----
    .. raw:: html
@@ -19,6 +21,7 @@ Video
        <iframe src="https://player.vimeo.com/video/214168860" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
        <p></p>
 
+
 Node architecture
 -----------------
 A Corda node is a JVM run-time environment with a unique identity on the network that hosts Corda services and

docs/source/key-concepts-notaries.rst

@@ -7,6 +7,8 @@ Notaries
    * *Notary clusters may optionally also validate transactions*
    * *A network can have several notary clusters, each running a different consensus algorithm*
 
+.. only:: htmlmode
+
     Video
     -----
     .. raw:: html
@@ -14,6 +16,7 @@ Video
         <iframe src="https://player.vimeo.com/video/214138458" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
         <p></p>
 
+
 Overview
 --------
 A *notary cluster* is a network service that provides **uniqueness consensus** by attesting that, for a given

docs/source/key-concepts-oracles.rst

@@ -6,6 +6,8 @@ Oracles
    * *A fact can be included in a transaction as part of a command*
    * *An oracle is a service that will only sign the transaction if the included fact is true*
 
+.. only:: htmlmode
+
     Video
     -----
     .. raw:: html
@@ -13,6 +15,7 @@ Video
         <iframe src="https://player.vimeo.com/video/214157956" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
         <p></p>
 
+
 Overview
 --------
 In many cases, a transaction's contractual validity depends on some external piece of data, such as the current

docs/source/key-concepts-states.rst

@@ -7,6 +7,8 @@ States
    * *States are evolved by marking the current state as historic and creating an updated state*
    * *Each node has a vault where it stores any relevant states to itself*
 
+.. only:: htmlmode
+
    Video
    -----
    .. raw:: html
@@ -14,6 +16,7 @@ Video
        <iframe src="https://player.vimeo.com/video/213812054" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
        <p></p>
 
+
 Overview
 --------
 A *state* is an immutable object representing a fact known by one or more Corda nodes at a specific point in time.

docs/source/key-concepts-time-windows.rst

@@ -7,6 +7,8 @@ Time-windows
    * *The notary is the timestamping authority, refusing to commit transactions outside of that window*
    * *Time-windows can have a start and end time, or be open at either end*
 
+.. only:: htmlmode
+
     Video
     -----
     .. raw:: html
@@ -14,6 +16,7 @@ Video
         <iframe src="https://player.vimeo.com/video/213879314" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
         <p></p>
 
+
 Time in a distributed system
 ----------------------------
 A notary also act as the *timestamping authority*, verifying that a transaction occurred during a specific time-window
@@ -38,10 +41,20 @@ For this reason, times in transactions are specified as time *windows*, not abso
 there can never be "true time", only an approximation of it. Time windows can be open-ended (i.e. specify only one of
 "before" and "after") or they can be fully bounded.
 
+.. only:: htmlmode
+
    .. image:: resources/time-window.gif
       :scale: 25%
       :align: center
 
+
+.. only:: pdfmode
+
+   .. image:: resources/time-window.png
+      :scale: 25%
+      :align: center
+
+
 In this way, we express the idea that the *true value* of the fact "the current time" is actually unknowable. Even when
 both a before and an after time are included, the transaction could have occurred at any point within that time-window.
 

docs/source/key-concepts-transactions.rst

@@ -10,6 +10,8 @@ Transactions
      * *It is contractually valid*
      * *It is signed by the required parties*
 
+.. only:: htmlmode
+
    Video
    -----
    .. raw:: html
@@ -17,6 +19,7 @@ Video
        <iframe src="https://player.vimeo.com/video/213879807" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
        <p></p>
 
+
 Overview
 --------
 Corda uses a *UTXO* (unspent transaction output) model where every state on the ledger is immutable. The ledger

node-api/src/main/kotlin/net/corda/nodeapi/internal/ArtemisMessagingClient.kt

@@ -50,7 +50,7 @@ class ArtemisMessagingClient(
         val locator = ActiveMQClient.createServerLocatorWithoutHA(tcpTransport).apply {
             // Never time out on our loopback Artemis connections. If we switch back to using the InVM transport this
             // would be the default and the two lines below can be deleted.
-            connectionTTL = -1
+            connectionTTL = 60000
             clientFailureCheckPeriod = -1
             minLargeMessageSize = maxMessageSize
             isUseGlobalPools = nodeSerializationEnv != null
@@ -62,7 +62,7 @@ class ArtemisMessagingClient(
         // using our TLS certificate.
         // Note that the acknowledgement of messages is not flushed to the Artermis journal until the default buffer
         // size of 1MB is acknowledged.
-        val session = sessionFactory!!.createSession(NODE_P2P_USER, NODE_P2P_USER, false, autoCommitSends, autoCommitAcks, locator.isPreAcknowledge, DEFAULT_ACK_BATCH_SIZE)
+        val session = sessionFactory!!.createSession(NODE_P2P_USER, NODE_P2P_USER, false, autoCommitSends, autoCommitAcks, false, DEFAULT_ACK_BATCH_SIZE)
         session.start()
         // Create a general purpose producer.
         val producer = session.createProducer()

node/src/main/kotlin/net/corda/node/services/messaging/InternalRPCMessagingClient.kt

@@ -26,7 +26,7 @@ class InternalRPCMessagingClient(val sslConfig: SSLConfiguration, val serverAddr
         locator = ActiveMQClient.createServerLocatorWithoutHA(tcpTransport).apply {
             // Never time out on our loopback Artemis connections. If we switch back to using the InVM transport this
             // would be the default and the two lines below can be deleted.
-            connectionTTL = -1
+            connectionTTL = 60000
             clientFailureCheckPeriod = -1
             minLargeMessageSize = maxMessageSize
             isUseGlobalPools = nodeSerializationEnv != null

node/src/main/kotlin/net/corda/node/services/messaging/P2PMessagingClient.kt

@@ -26,11 +26,7 @@ import net.corda.core.serialization.SingletonSerializeAsToken
 import net.corda.core.serialization.deserialize
 import net.corda.core.serialization.internal.nodeSerializationEnv
 import net.corda.core.serialization.serialize
-import net.corda.core.utilities.ByteSequence
+import net.corda.core.utilities.*
-import net.corda.core.utilities.NetworkHostAndPort
-import net.corda.core.utilities.OpaqueBytes
-import net.corda.core.utilities.contextLogger
-import net.corda.core.utilities.trace
 import net.corda.node.VersionInfo
 import net.corda.node.internal.LifecycleSupport
 import net.corda.node.internal.artemis.ReactiveArtemisConsumer
@@ -43,15 +39,12 @@ import net.corda.node.services.statemachine.SenderDeduplicationId
 import net.corda.node.utilities.AffinityExecutor
 import net.corda.nodeapi.ArtemisTcpTransport.Companion.p2pConnectorTcpTransport
 import net.corda.nodeapi.internal.ArtemisMessagingComponent
-import net.corda.nodeapi.internal.ArtemisMessagingComponent.ArtemisAddress
+import net.corda.nodeapi.internal.ArtemisMessagingComponent.*
 import net.corda.nodeapi.internal.ArtemisMessagingComponent.Companion.BRIDGE_CONTROL
 import net.corda.nodeapi.internal.ArtemisMessagingComponent.Companion.BRIDGE_NOTIFY
 import net.corda.nodeapi.internal.ArtemisMessagingComponent.Companion.JOURNAL_HEADER_SIZE
 import net.corda.nodeapi.internal.ArtemisMessagingComponent.Companion.P2PMessagingHeaders
 import net.corda.nodeapi.internal.ArtemisMessagingComponent.Companion.PEERS_PREFIX
-import net.corda.nodeapi.internal.ArtemisMessagingComponent.NodeAddress
-import net.corda.nodeapi.internal.ArtemisMessagingComponent.RemoteInboxAddress
-import net.corda.nodeapi.internal.ArtemisMessagingComponent.ServiceAddress
 import net.corda.nodeapi.internal.bridging.BridgeControl
 import net.corda.nodeapi.internal.bridging.BridgeEntry
 import net.corda.nodeapi.internal.persistence.CordaPersistence
@@ -61,12 +54,7 @@ import org.apache.activemq.artemis.api.core.Message.HDR_DUPLICATE_DETECTION_ID
 import org.apache.activemq.artemis.api.core.Message.HDR_VALIDATED_USER
 import org.apache.activemq.artemis.api.core.RoutingType
 import org.apache.activemq.artemis.api.core.SimpleString
-import org.apache.activemq.artemis.api.core.client.ActiveMQClient
+import org.apache.activemq.artemis.api.core.client.*
-import org.apache.activemq.artemis.api.core.client.ClientConsumer
-import org.apache.activemq.artemis.api.core.client.ClientMessage
-import org.apache.activemq.artemis.api.core.client.ClientProducer
-import org.apache.activemq.artemis.api.core.client.ClientSession
-import org.apache.activemq.artemis.api.core.client.ServerLocator
 import rx.Observable
 import rx.Subscription
 import rx.subjects.PublishSubject
@@ -167,7 +155,7 @@ class P2PMessagingClient(val config: NodeConfiguration,
             locator = ActiveMQClient.createServerLocatorWithoutHA(tcpTransport).apply {
                 // Never time out on our loopback Artemis connections. If we switch back to using the InVM transport this
                 // would be the default and the two lines below can be deleted.
-                connectionTTL = -1
+                connectionTTL = 60000
                 clientFailureCheckPeriod = -1
                 minLargeMessageSize = maxMessageSize + JOURNAL_HEADER_SIZE
                 isUseGlobalPools = nodeSerializationEnv != null
@@ -178,7 +166,7 @@ class P2PMessagingClient(val config: NodeConfiguration,
             // using our TLS certificate.
             // Note that the acknowledgement of messages is not flushed to the Artermis journal until the default buffer
             // size of 1MB is acknowledged.
-            val createNewSession = { sessionFactory!!.createSession(ArtemisMessagingComponent.NODE_P2P_USER, ArtemisMessagingComponent.NODE_P2P_USER, false, true, true, locator!!.isPreAcknowledge, ActiveMQClient.DEFAULT_ACK_BATCH_SIZE) }
+            val createNewSession = { sessionFactory!!.createSession(ArtemisMessagingComponent.NODE_P2P_USER, ArtemisMessagingComponent.NODE_P2P_USER, false, true, true, false, ActiveMQClient.DEFAULT_ACK_BATCH_SIZE) }
 
             producerSession = createNewSession()
             bridgeSession = createNewSession()