Merge remote-tracking branch 'origin/release/os/5.2' into CORE-18984/…

…mediator-configs

# Conflicts:
#	gradle.properties

application/scans/corda-application-5.2.0.yaml

@@ -1328,9 +1328,10 @@ net.corda.v5.application.messaging.FlowMessaging:
           annotation:
             - NotNull
           type: net.corda.v5.base.types.MemberX500Name
-        requireClose:
-          annotation: []
-          type: boolean
+        sessionConfiguration:
+          annotation:
+            - NotNull
+          type: net.corda.v5.application.messaging.FlowSessionConfiguration
         flowContextPropertiesBuilder:
           annotation:
             - NotNull
@@ -1460,6 +1461,53 @@ net.corda.v5.application.messaging.FlowSession:
           annotation:
             - NotNull
           type: Object
+net.corda.v5.application.messaging.FlowSessionConfiguration:
+  annotations: []
+  type: public final class
+  extends: null
+  implements: []
+  interface: false
+  methods:
+    getTimeout:
+      annotations: []
+      default: false
+      type: public
+      returnType: java.time.Duration
+    isRequireClose:
+      annotations: []
+      default: false
+      type: public
+      returnType: boolean
+net.corda.v5.application.messaging.FlowSessionConfiguration$Builder:
+  annotations: []
+  type: public static final class
+  extends: null
+  implements: []
+  interface: false
+  methods:
+    build:
+      annotations: []
+      default: false
+      type: public
+      returnType: net.corda.v5.application.messaging.FlowSessionConfiguration
+    requireClose:
+      annotations: []
+      default: false
+      type: public
+      returnType: net.corda.v5.application.messaging.FlowSessionConfiguration$Builder
+      params:
+        requireClose:
+          annotation: []
+          type: boolean
+    timeout:
+      annotations: []
+      default: false
+      type: public
+      returnType: net.corda.v5.application.messaging.FlowSessionConfiguration$Builder
+      params:
+        timeout:
+          annotation: []
+          type: java.time.Duration
 net.corda.v5.application.persistence.CordaPersistenceException:
   annotations: []
   type: public final class
@@ -1571,7 +1619,7 @@ net.corda.v5.application.persistence.ParameterizedQuery:
           type: String
         value:
           annotation:
-            - NotNull
+            - Nullable
           type: Object
     setParameters:
       annotations:

application/src/main/java/net/corda/v5/application/messaging/FlowMessaging.java

@@ -95,17 +95,40 @@ public interface FlowMessaging {
      * context has no effect on the context of the session after this point, and therefore it has no effect on the
      * context of the initiated flow either.
      *
+     * @deprecated
+     * Use {@link FlowMessaging#initiateFlow(MemberX500Name, FlowSessionConfiguration)} instead.
+     *
      * @param x500Name The X500 name of the member to communicate with.
      * @param requireClose When set to true, the initiated party will send a close message after calling FlowSession.close()
      *                     and the initiating party will suspend and wait to receive the message when they call FlowSession.close().
      *                     When set to false the session is marked as terminated immediately when close() is called.
      *
      * @return The session.
      */
+    @Deprecated(since = "5.2")
     @Suspendable
     @NotNull
     FlowSession initiateFlow(@NotNull MemberX500Name x500Name, boolean requireClose);
 
+    /**
+     * Creates a communication session with a counterparty's {@link ResponderFlow}. Subsequently, you may send/receive using
+     * this session object. Note that this function does not communicate in itself. The counter-flow will be kicked off
+     * by the first send/receive.
+     * <p>
+     * Initiated flows are initiated with context based on the context of the initiating flow at the point in time this
+     * method is called. The context of the initiating flow is snapshotted by the returned session. Altering the flow
+     * context has no effect on the context of the session after this point, and therefore it has no effect on the
+     * context of the initiated flow either.
+     *
+     * @param x500Name The X500 name of the member to communicate with.
+     * @param sessionConfiguration Session configuration (see {@link FlowSessionConfiguration}).
+     *
+     * @return The session.
+     */
+    @Suspendable
+    @NotNull
+    FlowSession initiateFlow(@NotNull MemberX500Name x500Name, @NotNull FlowSessionConfiguration sessionConfiguration);
+
     /**
      * Creates a communication session with another member. Subsequently, you may send/receive using this session object.
      * Note that this function does not communicate in itself. The counter-flow will be kicked off by the first
@@ -171,6 +194,10 @@ public interface FlowMessaging {
      * });
      * ```
      *
+     * @deprecated
+     * Use {@link FlowMessaging#initiateFlow(MemberX500Name, FlowSessionConfiguration, FlowContextPropertiesBuilder)}
+     * instead.
+     *
      * @param x500Name The X500 name of the member to communicate with.
      * @param requireClose When set to true, the initiated party will send a close message after calling FlowSession.close()
      *                     and the initiating party will suspend and wait to receive the message when they call FlowSession.close().
@@ -185,10 +212,58 @@ public interface FlowMessaging {
      * exception thrown by the builder will also be thrown through here and should be avoided in the provided
      * implementation, see {@link FlowContextPropertiesBuilder}.
      */
+    @Deprecated(since = "5.2")
     @Suspendable
     @NotNull
     FlowSession initiateFlow(@NotNull MemberX500Name x500Name, boolean requireClose, @NotNull FlowContextPropertiesBuilder flowContextPropertiesBuilder);
 
+    /**
+     * Creates a communication session with another member. Subsequently, you may send/receive using this session object.
+     * Note that this function does not communicate in itself. The counter-flow will be kicked off by the first
+     * send/receive.
+     * <p>
+     * This overload takes a builder of context properties. Any properties set or modified against the context passed to
+     * this builder will be propagated to initiated flows and all that flow's initiated flows and sub flows down the
+     * stack. The properties passed to the builder are pre-populated with the current flow context properties, see
+     * {@link FlowContextProperties}. Altering the current flow context has no effect on the context of the session after the
+     * builder is applied and the session returned by this method, and therefore it has no effect on the context of the
+     * initiated flow either.
+     * <p>
+     * Example of use in Kotlin.
+     * ```Kotlin
+     * val sessionConfig = FlowSessionConfiguration.Builder().requireClose(false).build()
+     * val flowSession = flowMessaging.initiateFlow(virtualNodeName, sessionConfig) { flowContextProperties ->
+     *      flowContextProperties["key"] = "value"
+     * }
+     * ```
+     * Example of use in Java.
+     * ```Java
+     * FlowSessionConfiguration sessionConfig = new FlowSessionConfiguration.Builder().requireClose(false).build();
+     * FlowSession flowSession = flowMessaging.initiateFlow(virtualNodeName, sessionConfig, (flowContextProperties) -> {
+     *      flowContextProperties.put("key", "value");
+     * });
+     * ```
+     *
+     * @param x500Name The X500 name of the member to communicate with.
+     * @param sessionConfiguration Session configuration (see {@link FlowSessionConfiguration}).
+     * @param flowContextPropertiesBuilder A builder of context properties.
+     *
+     * @return The session.
+     *
+     * @throws IllegalArgumentException if the builder tries to set a property for which a platform property already
+     * exists or if the key is prefixed by {@link FlowContextProperties#CORDA_RESERVED_PREFIX}. See also
+     * {@link FlowContextProperties}. Any other
+     * exception thrown by the builder will also be thrown through here and should be avoided in the provided
+     * implementation, see {@link FlowContextPropertiesBuilder}.
+     */
+    @Suspendable
+    @NotNull
+    FlowSession initiateFlow(
+            @NotNull MemberX500Name x500Name,
+            @NotNull FlowSessionConfiguration sessionConfiguration,
+            @NotNull FlowContextPropertiesBuilder flowContextPropertiesBuilder
+    );
+
     /**
      * Suspends until a message has been received for each session in the specified {@code sessions}.
      * <p>

application/src/main/java/net/corda/v5/application/messaging/FlowSessionConfiguration.java

@@ -0,0 +1,62 @@
+package net.corda.v5.application.messaging;
+
+import java.time.Duration;
+
+/**
+ * Flow session configuration. Instances should be created using {@link Builder}.
+ */
+public final class FlowSessionConfiguration {
+    private final boolean requireClose;
+    private final Duration timeout;
+
+    private FlowSessionConfiguration(Builder builder) {
+        this.requireClose = builder.requireClose;
+        this.timeout = builder.timeout;
+    }
+
+    public boolean isRequireClose() {
+        return requireClose;
+    }
+
+    public Duration getTimeout() {
+        return timeout;
+    }
+
+    public static final class Builder {
+        private boolean requireClose = true;
+        private Duration timeout;
+
+        /**
+         * When set to true, the initiated party will send a close message after calling FlowSession.close()
+         * and the initiating party will suspend and wait to receive the message when they call FlowSession.close().
+         * When set to false the session is marked as terminated immediately when close() is called.
+         * Default value is true.
+         * @param requireClose Flag that indicates whether close message is required.
+         * @return {@link Builder}.
+         */
+        public Builder requireClose(boolean requireClose) {
+            this.requireClose = requireClose;
+            return this;
+        }
+
+        /**
+         * The duration that Corda waits when no message has been received from a counterparty before
+         * causing the session to error. If set to null, value set in Corda Configuration will be used.
+         * Default value is null.
+         * @param timeout Session timeout.
+         * @return {@link Builder}.
+         */
+        public Builder timeout(Duration timeout) {
+            this.timeout = timeout;
+            return this;
+        }
+
+        /**
+         * Builds a new instance of {@link FlowSessionConfiguration}.
+         * @return a new instance of {@link FlowSessionConfiguration}.
+         */
+        public FlowSessionConfiguration build() {
+            return new FlowSessionConfiguration(this);
+        }
+    }
+}

application/src/main/java/net/corda/v5/application/persistence/ParameterizedQuery.java

@@ -1,6 +1,7 @@
 package net.corda.v5.application.persistence;
 
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.Map;
 
@@ -54,7 +55,7 @@ public interface ParameterizedQuery<R> extends PagedQuery<R> {
      * @return the same {@link ParameterizedQuery} instance.
      */
     @NotNull
-    ParameterizedQuery<R> setParameter(@NotNull String name, @NotNull Object value);
+    ParameterizedQuery<R> setParameter(@NotNull String name, @Nullable Object value);
 
     /**
      * Sets the parameters as a {@link Map}.

application/src/test/java/net/corda/v5/application/messaging/FlowMessagingJavaApiTest.java

@@ -28,7 +28,7 @@ public void initiateFlowParty() {
     @Test
     public void initiateFlowPartyWithBuilder() {
         final MemberX500Name counterparty = new MemberX500Name("Alice Corp", "LDN", "GB");
-        when(flowMessaging.initiateFlow(eq(counterparty), any())).thenReturn(flowSession);
+        when(flowMessaging.initiateFlow(eq(counterparty), any(FlowContextPropertiesBuilder.class))).thenReturn(flowSession);
 
         FlowSession result = flowMessaging.initiateFlow(counterparty, (contextProperties) -> contextProperties.put("key", "value"));
 
@@ -39,7 +39,7 @@ public void initiateFlowPartyWithBuilder() {
     @Test
     public void initiateFlowPartyWithBuilderRequireCloseTrue() {
         final MemberX500Name counterparty = new MemberX500Name("Alice Corp", "LDN", "GB");
-        when(flowMessaging.initiateFlow(eq(counterparty), eq(true), any())).thenReturn(flowSession);
+        when(flowMessaging.initiateFlow(eq(counterparty), eq(true), any(FlowContextPropertiesBuilder.class))).thenReturn(flowSession);
 
         FlowSession result = flowMessaging.initiateFlow(counterparty, true, (contextProperties) -> contextProperties.put("key", "value"));
 
@@ -50,7 +50,7 @@ public void initiateFlowPartyWithBuilderRequireCloseTrue() {
     @Test
     public void initiateFlowPartyWithBuilderRequireCloseFalse() {
         final MemberX500Name counterparty = new MemberX500Name("Alice Corp", "LDN", "GB");
-        when(flowMessaging.initiateFlow(eq(counterparty), eq(false), any())).thenReturn(flowSession);
+        when(flowMessaging.initiateFlow(eq(counterparty), eq(false), any(FlowContextPropertiesBuilder.class))).thenReturn(flowSession);
 
         FlowSession result = flowMessaging.initiateFlow(counterparty, false, (contextProperties) -> contextProperties.put("key", "value"));
 

data/avro-schema/src/main/resources/avro/net/corda/data/crypto/wire/ops/encryption/request/DecryptRpcCommand.avsc

@@ -0,0 +1,23 @@
+{
+  "type": "record",
+  "name": "DecryptRpcCommand",
+  "namespace": "net.corda.data.crypto.wire.ops.encryption.request",
+  "doc": "Request to decrypt the given byte array",
+  "fields": [
+    {
+      "name": "category",
+      "type": "string",
+      "doc": "The category of HSM e.g. ENCRYPTION_SECRET, TLS, etc."
+    },
+    {
+      "name": "alias",
+      "type": ["null", "string"],
+      "doc": "The symmetric key alias."
+    },
+    {
+      "name": "cipherBytes",
+      "type": "bytes",
+      "doc": "The data to decrypt."
+    }
+  ]
+}

data/avro-schema/src/main/resources/avro/net/corda/data/crypto/wire/ops/encryption/request/EncryptRpcCommand.avsc

@@ -0,0 +1,23 @@
+{
+  "type": "record",
+  "name": "EncryptRpcCommand",
+  "namespace": "net.corda.data.crypto.wire.ops.encryption.request",
+  "doc": "Request to encrypt the given byte array",
+  "fields": [
+    {
+      "name": "category",
+      "type": "string",
+      "doc": "The category of HSM e.g. ENCRYPTION_SECRET, TLS, etc."
+    },
+    {
+      "name": "alias",
+      "type": ["null", "string"],
+      "doc": "The symmetric key alias."
+    },
+    {
+      "name": "plainBytes",
+      "type": "bytes",
+      "doc": "The data to encrypt."
+    }
+  ]
+}

data/avro-schema/src/main/resources/avro/net/corda/data/crypto/wire/ops/encryption/response/CryptoDecryptionResult.avsc

@@ -0,0 +1,13 @@
+{
+  "type": "record",
+  "name": "CryptoDecryptionResult",
+  "namespace": "net.corda.data.crypto.wire.ops.encryption.response",
+  "doc": "Decryption operation response",
+  "fields": [
+    {
+      "name": "plainBytes",
+      "type": "bytes",
+      "doc": "Decrypted byte array"
+    }
+  ]
+}

data/avro-schema/src/main/resources/avro/net/corda/data/crypto/wire/ops/encryption/response/CryptoEncryptionResult.avsc

@@ -0,0 +1,13 @@
+{
+  "type": "record",
+  "name": "CryptoEncryptionResult",
+  "namespace": "net.corda.data.crypto.wire.ops.encryption.response",
+  "doc": "Encryption operation response",
+  "fields": [
+    {
+      "name": "cipherBytes",
+      "type": "bytes",
+      "doc": "Encrypted byte array"
+    }
+  ]
+}

data/avro-schema/src/main/resources/avro/net/corda/data/crypto/wire/ops/encryption/response/DecryptionOpsResponse.avsc

@@ -0,0 +1,16 @@
+{
+  "type": "record",
+  "name": "DecryptionOpsResponse",
+  "namespace": "net.corda.data.crypto.wire.ops.encryption.response",
+  "doc": "Response for crypto's decryption operations envelope",
+  "fields": [
+    {
+      "name": "response",
+      "type": [
+        "net.corda.data.crypto.wire.ops.encryption.response.CryptoDecryptionResult",
+        "net.corda.data.crypto.wire.ops.encryption.response.EncryptionOpsError"
+      ],
+      "doc": "Response's payload, depends on the requested operation"
+    }
+  ]
+}