From 83f37417ae25426e0a24ec4e63b51239b9dfc50c Mon Sep 17 00:00:00 2001 From: Joel Dudley Date: Sat, 7 Oct 2017 12:48:16 +0100 Subject: [PATCH] Fixes the API docs. --- docs/source/api-flows.rst | 119 ++++++++---------- docs/source/api-identity.rst | 4 +- docs/source/api-transactions.rst | 78 ++++++------ .../java/net/corda/docs/FlowCookbookJava.java | 32 ++--- .../kotlin/net/corda/docs/FlowCookbook.kt | 32 ++--- 5 files changed, 124 insertions(+), 141 deletions(-) diff --git a/docs/source/api-flows.rst b/docs/source/api-flows.rst index 931aa493df..4a0e284621 100644 --- a/docs/source/api-flows.rst +++ b/docs/source/api-flows.rst @@ -221,14 +221,14 @@ There are several ways to retrieve a notary from the network map: .. literalinclude:: ../../docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt :language: kotlin - :start-after: DOCSTART 1 - :end-before: DOCEND 1 - :dedent: 12 + :start-after: DOCSTART 01 + :end-before: DOCEND 01 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java - :start-after: DOCSTART 1 - :end-before: DOCEND 1 + :start-after: DOCSTART 01 + :end-before: DOCEND 01 :dedent: 12 Specific counterparties @@ -239,32 +239,14 @@ We can also use the network map to retrieve a specific counterparty: .. literalinclude:: ../../docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt :language: kotlin - :start-after: DOCSTART 2 - :end-before: DOCEND 2 - :dedent: 12 + :start-after: DOCSTART 02 + :end-before: DOCEND 02 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java - :start-after: DOCSTART 2 - :end-before: DOCEND 2 - :dedent: 12 - -Specific services -~~~~~~~~~~~~~~~~~ -Finally, we can use the map to identify nodes providing a specific service (e.g. a regulator or an oracle): - -.. container:: codeset - - .. literalinclude:: ../../docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt - :language: kotlin - :start-after: DOCSTART 3 - :end-before: DOCEND 3 - :dedent: 12 - - .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java - :language: java - :start-after: DOCSTART 3 - :end-before: DOCEND 3 + :start-after: DOCSTART 02 + :end-before: DOCEND 02 :dedent: 12 Communication between parties @@ -295,7 +277,7 @@ InitiateFlow :language: kotlin :start-after: DOCSTART initiateFlow :end-before: DOCEND initiateFlow - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -318,14 +300,14 @@ Once we have a ``FlowSession`` object we can send arbitrary data to a counterpar .. literalinclude:: ../../docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt :language: kotlin - :start-after: DOCSTART 4 - :end-before: DOCEND 4 - :dedent: 12 + :start-after: DOCSTART 04 + :end-before: DOCEND 04 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java - :start-after: DOCSTART 4 - :end-before: DOCEND 4 + :start-after: DOCSTART 04 + :end-before: DOCEND 04 :dedent: 12 The flow on the other side must eventually reach a corresponding ``receive`` call to get this message. @@ -350,14 +332,14 @@ be what it appears to be! We must unwrap the ``UntrustworthyData`` using a lambd .. literalinclude:: ../../docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt :language: kotlin - :start-after: DOCSTART 5 - :end-before: DOCEND 5 - :dedent: 12 + :start-after: DOCSTART 05 + :end-before: DOCEND 05 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java - :start-after: DOCSTART 5 - :end-before: DOCEND 5 + :start-after: DOCSTART 05 + :end-before: DOCEND 05 :dedent: 12 We're not limited to sending to and receiving from a single counterparty. A flow can send messages to as many parties @@ -367,14 +349,14 @@ as it likes, and each party can invoke a different response flow: .. literalinclude:: ../../docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt :language: kotlin - :start-after: DOCSTART 6 - :end-before: DOCEND 6 - :dedent: 12 + :start-after: DOCSTART 06 + :end-before: DOCEND 06 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java - :start-after: DOCSTART 6 - :end-before: DOCEND 6 + :start-after: DOCSTART 06 + :end-before: DOCEND 06 :dedent: 12 .. warning:: If you initiate several flows from the same ``@InitiatingFlow`` flow then on the receiving side you must be @@ -392,14 +374,14 @@ type of data sent doesn't need to match the type of the data received back: .. literalinclude:: ../../docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt :language: kotlin - :start-after: DOCSTART 7 - :end-before: DOCEND 7 - :dedent: 12 + :start-after: DOCSTART 07 + :end-before: DOCEND 07 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java - :start-after: DOCSTART 7 - :end-before: DOCEND 7 + :start-after: DOCSTART 07 + :end-before: DOCEND 07 :dedent: 12 Counterparty response @@ -417,14 +399,14 @@ Our side of the flow must mirror these calls. We could do this as follows: .. literalinclude:: ../../docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt :language: kotlin - :start-after: DOCSTART 8 - :end-before: DOCEND 8 - :dedent: 12 + :start-after: DOCSTART 08 + :end-before: DOCEND 08 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java - :start-after: DOCSTART 8 - :end-before: DOCEND 8 + :start-after: DOCSTART 08 + :end-before: DOCEND 08 :dedent: 12 Why sessions? @@ -481,7 +463,7 @@ explicit in the ``initiateFlow`` function call. To port existing code: :language: kotlin :start-after: DOCSTART FlowSession porting :end-before: DOCEND FlowSession porting - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -489,7 +471,6 @@ explicit in the ``initiateFlow`` function call. To port existing code: :end-before: DOCEND FlowSession porting :dedent: 12 - Subflows -------- @@ -560,14 +541,14 @@ the transaction's states: .. literalinclude:: ../../docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt :language: kotlin - :start-after: DOCSTART 9 - :end-before: DOCEND 9 - :dedent: 12 + :start-after: DOCSTART 09 + :end-before: DOCEND 09 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java - :start-after: DOCSTART 9 - :end-before: DOCEND 9 + :start-after: DOCSTART 09 + :end-before: DOCEND 09 :dedent: 12 We can also choose to send the transaction to additional parties who aren't one of the state's participants: @@ -578,7 +559,7 @@ We can also choose to send the transaction to additional parties who aren't one :language: kotlin :start-after: DOCSTART 10 :end-before: DOCEND 10 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -601,7 +582,7 @@ transaction ourselves, we can automatically gather the signatures of the other r :language: kotlin :start-after: DOCSTART 15 :end-before: DOCEND 15 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -618,7 +599,7 @@ transaction and provide their signature if they are satisfied: :language: kotlin :start-after: DOCSTART 16 :end-before: DOCEND 16 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -639,7 +620,7 @@ transaction data vending requests as the receiver walks the dependency chain usi :language: kotlin :start-after: DOCSTART 12 :end-before: DOCEND 12 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -656,7 +637,7 @@ dependencies and verify the transaction: :language: kotlin :start-after: DOCSTART 13 :end-before: DOCEND 13 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -672,7 +653,7 @@ We can also send and receive a ``StateAndRef`` dependency chain and automaticall :language: kotlin :start-after: DOCSTART 14 :end-before: DOCEND 14 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -731,7 +712,7 @@ To provide a progress tracker, we have to override ``FlowLogic.progressTracker`` :language: kotlin :start-after: DOCSTART 17 :end-before: DOCEND 17 - :dedent: 8 + :dedent: 4 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -747,7 +728,7 @@ We then update the progress tracker's current step as we progress through the fl :language: kotlin :start-after: DOCSTART 18 :end-before: DOCEND 18 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java diff --git a/docs/source/api-identity.rst b/docs/source/api-identity.rst index 270e31bafd..c87b50a45f 100644 --- a/docs/source/api-identity.rst +++ b/docs/source/api-identity.rst @@ -69,6 +69,7 @@ You can see an example of it being used in ``TwoPartyDealFlow.kt``: :language: kotlin :start-after: DOCSTART 2 :end-before: DOCEND 2 + :dedent: 8 The swap identities flow goes through the following key steps: @@ -100,6 +101,7 @@ entities (counterparties) to require to know which well known identities those c :language: kotlin :start-after: DOCSTART 6 :end-before: DOCEND 6 + :dedent: 12 The identity synchronization flow goes through the following key steps: @@ -126,4 +128,4 @@ identity. This is important for more complex transaction cases with 3+ parties, Alice may know all of the confidential identities ahead of time, but Bob not know about Charlie's and vice-versa. The assembled transaction therefore has three input states *x*, *y* and *z*, for which only Alice possesses certificates for all confidential identities. ``IdentitySyncFlow`` must send not just Alice's confidential identity but also any other -identities in the transaction to the Bob and Charlie. +identities in the transaction to the Bob and Charlie. \ No newline at end of file diff --git a/docs/source/api-transactions.rst b/docs/source/api-transactions.rst index 7d76a0624b..0c02f4b565 100644 --- a/docs/source/api-transactions.rst +++ b/docs/source/api-transactions.rst @@ -59,7 +59,7 @@ An input state is added to a transaction as a ``StateAndRef``, which combines: :language: kotlin :start-after: DOCSTART 21 :end-before: DOCEND 21 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -78,7 +78,7 @@ A ``StateRef`` uniquely identifies an input state, allowing the notary to mark i :language: kotlin :start-after: DOCSTART 20 :end-before: DOCEND 20 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -102,7 +102,7 @@ add them to the transaction directly: :language: kotlin :start-after: DOCSTART 22 :end-before: DOCEND 22 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -119,7 +119,7 @@ it on the input state: :language: kotlin :start-after: DOCSTART 23 :end-before: DOCEND 23 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -139,7 +139,7 @@ wrapping the output state in a ``StateAndContract``, which combines: :language: kotlin :start-after: DOCSTART 47 :end-before: DOCEND 47 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -160,7 +160,7 @@ A command is added to the transaction as a ``Command``, which combines: :language: kotlin :start-after: DOCSTART 24 :end-before: DOCEND 24 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -178,7 +178,7 @@ Attachments are identified by their hash: :language: kotlin :start-after: DOCSTART 25 :end-before: DOCEND 25 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -199,7 +199,7 @@ time, or be open at either end: :language: kotlin :start-after: DOCSTART 26 :end-before: DOCEND 26 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -215,7 +215,7 @@ We can also define a time window as an ``Instant`` plus/minus a time tolerance ( :language: kotlin :start-after: DOCSTART 42 :end-before: DOCEND 42 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -231,7 +231,7 @@ Or as a start-time plus a duration: :language: kotlin :start-after: DOCSTART 43 :end-before: DOCEND 43 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -255,7 +255,7 @@ that will notarise the inputs and verify the time-window: :language: kotlin :start-after: DOCSTART 19 :end-before: DOCEND 19 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -274,7 +274,7 @@ instantiated without one: :language: kotlin :start-after: DOCSTART 46 :end-before: DOCEND 46 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -317,7 +317,7 @@ Here's an example usage of ``TransactionBuilder.withItems``: :language: kotlin :start-after: DOCSTART 27 :end-before: DOCEND 27 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -335,7 +335,7 @@ Here are the methods for adding inputs and attachments: :language: kotlin :start-after: DOCSTART 28 :end-before: DOCEND 28 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -351,7 +351,7 @@ An output state can be added as a ``ContractState``, contract class name and not :language: kotlin :start-after: DOCSTART 49 :end-before: DOCEND 49 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -367,7 +367,7 @@ We can also leave the notary field blank, in which case the transaction's defaul :language: kotlin :start-after: DOCSTART 50 :end-before: DOCEND 50 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -383,7 +383,7 @@ Or we can add the output state as a ``TransactionState``, which already specifie :language: kotlin :start-after: DOCSTART 51 :end-before: DOCEND 51 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -399,7 +399,7 @@ Commands can be added as a ``Command``: :language: kotlin :start-after: DOCSTART 52 :end-before: DOCEND 52 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -415,7 +415,7 @@ Or as ``CommandData`` and a ``vararg PublicKey``: :language: kotlin :start-after: DOCSTART 53 :end-before: DOCEND 53 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -431,7 +431,7 @@ For the time-window, we can set a time-window directly: :language: kotlin :start-after: DOCSTART 44 :end-before: DOCEND 44 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -447,7 +447,7 @@ Or define the time-window as a time plus a duration (e.g. 45 seconds): :language: kotlin :start-after: DOCSTART 45 :end-before: DOCEND 45 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -467,7 +467,7 @@ We can either sign with our legal identity key: :language: kotlin :start-after: DOCSTART 29 :end-before: DOCEND 29 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -483,7 +483,7 @@ Or we can also choose to use another one of our public keys: :language: kotlin :start-after: DOCSTART 30 :end-before: DOCEND 30 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -527,13 +527,13 @@ and output states: :language: kotlin :start-after: DOCSTART 33 :end-before: DOCEND 33 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java :start-after: DOCSTART 33 :end-before: DOCEND 33 - :dedent: 12 + :dedent: 16 Checking that the transaction meets the contract constraints is only part of verifying the transaction's contents. We will usually also want to perform our own additional validation of the transaction contents before signing, to ensure @@ -552,13 +552,13 @@ We achieve this by using the ``ServiceHub`` to convert the ``SignedTransaction`` :language: kotlin :start-after: DOCSTART 32 :end-before: DOCEND 32 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java :start-after: DOCSTART 32 :end-before: DOCEND 32 - :dedent: 12 + :dedent: 16 We can now perform our additional verification. Here's a simple example: @@ -568,13 +568,13 @@ We can now perform our additional verification. Here's a simple example: :language: kotlin :start-after: DOCSTART 34 :end-before: DOCEND 34 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java :start-after: DOCSTART 34 :end-before: DOCEND 34 - :dedent: 12 + :dedent: 16 Verifying the transaction's signatures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -589,13 +589,13 @@ We can verify that all the transaction's required signatures are present and val :language: kotlin :start-after: DOCSTART 35 :end-before: DOCEND 35 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java :start-after: DOCSTART 35 :end-before: DOCEND 35 - :dedent: 12 + :dedent: 16 However, we'll often want to verify the transaction's existing signatures before all of them have been collected. For this we can use ``SignedTransaction.verifySignaturesExcept``, which takes a ``vararg`` of the public keys for @@ -607,13 +607,13 @@ which the signatures are allowed to be missing: :language: kotlin :start-after: DOCSTART 36 :end-before: DOCEND 36 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java :start-after: DOCSTART 36 :end-before: DOCEND 36 - :dedent: 12 + :dedent: 16 If the transaction is missing any signatures without the corresponding public keys being passed in, a ``SignaturesMissingException`` is thrown. @@ -626,13 +626,13 @@ We can also choose to simply verify the signatures that are present: :language: kotlin :start-after: DOCSTART 37 :end-before: DOCEND 37 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java :start-after: DOCSTART 37 :end-before: DOCEND 37 - :dedent: 12 + :dedent: 16 Be very careful, however - this function neither guarantees that the signatures that are present are required, nor checks whether any signatures are missing. @@ -650,7 +650,7 @@ We can sign using our legal identity key, as follows: :language: kotlin :start-after: DOCSTART 38 :end-before: DOCEND 38 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -666,7 +666,7 @@ Or we can choose to sign using another one of our public keys: :language: kotlin :start-after: DOCSTART 39 :end-before: DOCEND 39 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -684,7 +684,7 @@ We can do this with our legal identity key: :language: kotlin :start-after: DOCSTART 40 :end-before: DOCEND 40 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java @@ -700,7 +700,7 @@ Or using another one of our public keys: :language: kotlin :start-after: DOCSTART 41 :end-before: DOCEND 41 - :dedent: 12 + :dedent: 8 .. literalinclude:: ../../docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java :language: java diff --git a/docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java b/docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java index 1946a2501d..e007e3af6f 100644 --- a/docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java +++ b/docs/source/example-code/src/main/java/net/corda/docs/FlowCookbookJava.java @@ -122,7 +122,7 @@ public class FlowCookbookJava { // - To serve as a timestamping authority if the transaction has a // time-window // We retrieve a notary from the network map. - // DOCSTART 1 + // DOCSTART 01 CordaX500Name notaryName = new CordaX500Name("Notary Service", "London", "GB"); Party specificNotary = getServiceHub().getNetworkMapCache().getNotary(notaryName); // Alternatively, we can pick an arbitrary notary from the notary @@ -130,15 +130,15 @@ public class FlowCookbookJava { // explicitly, as the notary list might change when new notaries are // introduced, or old ones decommissioned. Party firstNotary = getServiceHub().getNetworkMapCache().getNotaryIdentities().get(0); - // DOCEND 1 + // DOCEND 01 // We may also need to identify a specific counterparty. We do so // using the identity service. - // DOCSTART 2 + // DOCSTART 02 CordaX500Name counterPartyName = new CordaX500Name("NodeA", "London", "GB"); Party namedCounterparty = getServiceHub().getIdentityService().wellKnownPartyFromX500Name(counterPartyName); Party keyedCounterparty = getServiceHub().getIdentityService().partyFromKey(dummyPubKey); - // DOCEND 2 + // DOCEND 02 /*------------------------------ * SENDING AND RECEIVING DATA * @@ -162,9 +162,9 @@ public class FlowCookbookJava { // In other words, we are assuming that the counterparty is // registered to respond to this flow, and has a corresponding // ``receive`` call. - // DOCSTART 4 + // DOCSTART 04 counterpartySession.send(new Object()); - // DOCEND 4 + // DOCEND 04 // We can wait to receive arbitrary data of a specific type from a // counterparty. Again, this implies a corresponding ``send`` call @@ -185,7 +185,7 @@ public class FlowCookbookJava { // instance. This is a reminder that the data we receive may not // be what it appears to be! We must unwrap the // ``UntrustworthyData`` using a lambda. - // DOCSTART 5 + // DOCSTART 05 UntrustworthyData packet1 = counterpartySession.receive(Integer.class); Integer integer = packet1.unwrap(data -> { // Perform checking on the object received. @@ -193,13 +193,13 @@ public class FlowCookbookJava { // Return the object. return data; }); - // DOCEND 5 + // DOCEND 05 // We can also use a single call to send data to a counterparty // and wait to receive data of a specific type back. The type of // data sent doesn't need to match the type of the data received // back. - // DOCSTART 7 + // DOCSTART 07 UntrustworthyData packet2 = counterpartySession.sendAndReceive(Boolean.class, "You can send and receive any class!"); Boolean bool = packet2.unwrap(data -> { // Perform checking on the object received. @@ -207,16 +207,16 @@ public class FlowCookbookJava { // Return the object. return data; }); - // DOCEND 7 + // DOCEND 07 // We're not limited to sending to and receiving from a single // counterparty. A flow can send messages to as many parties as it // likes, and each party can invoke a different response flow. - // DOCSTART 6 + // DOCSTART 06 FlowSession regulatorSession = initiateFlow(regulator); regulatorSession.send(new Object()); UntrustworthyData packet3 = regulatorSession.receive(Object.class); - // DOCEND 6 + // DOCEND 06 /*------------------------------------ * EXTRACTING STATES FROM THE VAULT * @@ -564,9 +564,9 @@ public class FlowCookbookJava { // We notarise the transaction and get it recorded in the vault of // the participants of all the transaction's states. - // DOCSTART 9 + // DOCSTART 09 SignedTransaction notarisedTx1 = subFlow(new FinalityFlow(fullySignedTx, FINALISATION.childProgressTracker())); - // DOCEND 9 + // DOCEND 09 // We can also choose to send it to additional parties who aren't one // of the state's participants. // DOCSTART 10 @@ -629,11 +629,11 @@ public class FlowCookbookJava { // 3. They sent a ``String`` instance and waited to receive a // ``Boolean`` instance back // Our side of the flow must mirror these calls. - // DOCSTART 8 + // DOCSTART 08 Object obj = counterpartySession.receive(Object.class).unwrap(data -> data); String string = counterpartySession.sendAndReceive(String.class, 99).unwrap(data -> data); counterpartySession.send(true); - // DOCEND 8 + // DOCEND 08 /*----------------------------------------- * RESPONDING TO COLLECT_SIGNATURES_FLOW * diff --git a/docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt b/docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt index 1fbee1e1be..1ef82f8a1b 100644 --- a/docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt +++ b/docs/source/example-code/src/main/kotlin/net/corda/docs/FlowCookbook.kt @@ -102,7 +102,7 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty: // - To serve as a timestamping authority if the transaction has a // time-window // We retrieve the notary from the network map. - // DOCSTART 1 + // DOCSTART 01 val notaryName: CordaX500Name = CordaX500Name( organisation = "Notary Service", locality = "London", @@ -113,11 +113,11 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty: // explicitly, as the notary list might change when new notaries are // introduced, or old ones decommissioned. val firstNotary: Party = serviceHub.networkMapCache.notaryIdentities.first() - // DOCEND 1 + // DOCEND 01 // We may also need to identify a specific counterparty. We do so // using the identity service. - // DOCSTART 2 + // DOCSTART 02 val counterpartyName: CordaX500Name = CordaX500Name( organisation = "NodeA", locality = "London", @@ -126,7 +126,7 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty: throw IllegalArgumentException("Couldn't find counterparty for NodeA in identity service") val keyedCounterparty: Party = serviceHub.identityService.partyFromKey(dummyPubKey) ?: throw IllegalArgumentException("Couldn't find counterparty with key: $dummyPubKey in identity service") - // DOCEND 2 + // DOCEND 02 /**----------------------------- * SENDING AND RECEIVING DATA * @@ -150,9 +150,9 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty: // In other words, we are assuming that the counterparty is // registered to respond to this flow, and has a corresponding // ``receive`` call. - // DOCSTART 4 + // DOCSTART 04 counterpartySession.send(Any()) - // DOCEND 4 + // DOCEND 04 // We can wait to receive arbitrary data of a specific type from a // counterparty. Again, this implies a corresponding ``send`` call @@ -173,7 +173,7 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty: // instance. This is a reminder that the data we receive may not // be what it appears to be! We must unwrap the // ``UntrustworthyData`` using a lambda. - // DOCSTART 5 + // DOCSTART 05 val packet1: UntrustworthyData = counterpartySession.receive() val int: Int = packet1.unwrap { data -> // Perform checking on the object received. @@ -181,13 +181,13 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty: // Return the object. data } - // DOCEND 5 + // DOCEND 05 // We can also use a single call to send data to a counterparty // and wait to receive data of a specific type back. The type of // data sent doesn't need to match the type of the data received // back. - // DOCSTART 7 + // DOCSTART 07 val packet2: UntrustworthyData = counterpartySession.sendAndReceive("You can send and receive any class!") val boolean: Boolean = packet2.unwrap { data -> // Perform checking on the object received. @@ -195,16 +195,16 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty: // Return the object. data } - // DOCEND 7 + // DOCEND 07 // We're not limited to sending to and receiving from a single // counterparty. A flow can send messages to as many parties as it // likes, and each party can invoke a different response flow. - // DOCSTART 6 + // DOCSTART 06 val regulatorSession: FlowSession = initiateFlow(regulator) regulatorSession.send(Any()) val packet3: UntrustworthyData = regulatorSession.receive() - // DOCEND 6 + // DOCEND 06 /**----------------------------------- * EXTRACTING STATES FROM THE VAULT * @@ -543,9 +543,9 @@ class InitiatorFlow(val arg1: Boolean, val arg2: Int, private val counterparty: // We notarise the transaction and get it recorded in the vault of // the participants of all the transaction's states. - // DOCSTART 9 + // DOCSTART 09 val notarisedTx1: SignedTransaction = subFlow(FinalityFlow(fullySignedTx, FINALISATION.childProgressTracker())) - // DOCEND 9 + // DOCEND 09 // We can also choose to send it to additional parties who aren't one // of the state's participants. // DOCSTART 10 @@ -603,11 +603,11 @@ class ResponderFlow(val counterpartySession: FlowSession) : FlowLogic() { // 3. They sent a ``String`` instance and waited to receive a // ``Boolean`` instance back // Our side of the flow must mirror these calls. - // DOCSTART 8 + // DOCSTART 08 val any: Any = counterpartySession.receive().unwrap { data -> data } val string: String = counterpartySession.sendAndReceive(99).unwrap { data -> data } counterpartySession.send(true) - // DOCEND 8 + // DOCEND 08 /**---------------------------------------- * RESPONDING TO COLLECT_SIGNATURES_FLOW *