Unify the context in transaction-like methods: [ECR-4303]

Use `TransactionContext` in transaction-like methods:
- Service#initialize, #resume, #before- and #afterTransactions
- Configurable

That enables easier re-use of @transaction methods, as they
already accept TransactionContext; and makes the API a little
easier to learn because there are fewer immediate abstractions
(though you will have to use TransactionContext#getBlockchainData
to access the data anyway).

Author: dmitry-timofeev

exonum-java-binding/CHANGELOG.md

@@ -98,6 +98,13 @@ stable Exonum release. See [release notes][exonum-1.0.0-rc.1] for details.
   Any exceptions thrown in these methods are saved in the blockchain
   in `Blockchain#getCallErrors` and can be retrieved by any services or
   light clients.
+- Replaced `BlockchainData` argument in transaction-like `Service` and 
+  `Configurable` methods with `TransactionContext`. The `BlockchainData`
+  remains accessible via `TransactionContext#getBlockchainData`,
+  and service data via `TransactionContext#getServiceData`.
+  <!-- TODO: Shall we rename it into `ExecutionContext` (as
+  TransactionExecutionException has become ExecutionException)?
+  -->
 - `Blockchain#getTxResults` is replaced by `Blockchain#getCallErrors`.
   - Use `CallInBlocks` to concisely create `CallInBlock`s.
 - The specification of `Configurable` operations and `Service#initialize` 

exonum-java-binding/core/src/main/java/com/exonum/binding/core/blockchain/Blockchain.java

@@ -33,6 +33,7 @@
 import com.exonum.binding.core.storage.indices.MapIndex;
 import com.exonum.binding.core.storage.indices.ProofListIndexProxy;
 import com.exonum.binding.core.storage.indices.ProofMapIndexProxy;
+import com.exonum.binding.core.transaction.TransactionContext;
 import com.exonum.messages.core.Blockchain.CallInBlock;
 import com.exonum.messages.core.Blockchain.Config;
 import com.exonum.messages.core.Proofs;
@@ -195,7 +196,7 @@ public BlockProof createBlockProof(long blockHeight) {
    *     logic, an index may remain uninitialized indefinitely. Therefore, if proofs for an
    *     empty index need to be created, it must be initialized early in the service lifecycle
    *     (e.g., in {@link
-   *     com.exonum.binding.core.service.Service#initialize(BlockchainData, Configuration)}.
+   *     com.exonum.binding.core.service.Service#initialize(TransactionContext, Configuration)}.
    *     <!-- TODO: Simplify once initialization happens automatically: ECR-4121 -->
    */
   public IndexProof createIndexProof(String fullIndexName) {

exonum-java-binding/core/src/main/java/com/exonum/binding/core/runtime/ServiceRuntime.java

@@ -20,8 +20,10 @@
 import static com.google.common.base.Preconditions.checkNotNull;
 import static com.google.common.base.Preconditions.checkState;
 
+import com.exonum.binding.common.crypto.CryptoFunctions.Ed25519;
 import com.exonum.binding.common.crypto.PublicKey;
 import com.exonum.binding.common.hash.HashCode;
+import com.exonum.binding.common.hash.Hashing;
 import com.exonum.binding.common.runtime.ServiceArtifactId;
 import com.exonum.binding.core.blockchain.BlockchainData;
 import com.exonum.binding.core.service.BlockCommittedEvent;
@@ -66,6 +68,10 @@ public final class ServiceRuntime implements AutoCloseable {
   @VisibleForTesting
   static final String API_ROOT_PATH = "/api/services";
   private static final Logger logger = LogManager.getLogger(ServiceRuntime.class);
+  @VisibleForTesting static final PublicKey ZERO_PK =
+      PublicKey.fromBytes(new byte[Ed25519.PUBLIC_KEY_BYTES]);
+  @VisibleForTesting static final HashCode ZERO_HASH =
+      HashCode.fromBytes(new byte[Hashing.DEFAULT_HASH_SIZE_BYTES]);
 
   private final ServiceLoader serviceLoader;
   private final ServicesFactory servicesFactory;
@@ -200,7 +206,8 @@ public void initiateAddingService(BlockchainData blockchainData, ServiceInstance
         ServiceWrapper service = createServiceInstance(instanceSpec);
 
         // Initialize it
-        service.initialize(blockchainData, new ServiceConfiguration(configuration));
+        TransactionContext context = newContext(service, blockchainData).build();
+        service.initialize(context, new ServiceConfiguration(configuration));
       }
 
       // Log the initialization event
@@ -234,7 +241,8 @@ public void initiateResumingService(BlockchainData blockchainData,
       synchronized (lock) {
         checkStoppedService(instanceSpec.getId());
         ServiceWrapper service = createServiceInstance(instanceSpec);
-        service.resume(blockchainData, arguments);
+        TransactionContext context = newContext(service, blockchainData).build();
+        service.resume(context, arguments);
       }
       logger.info("Resumed service: {}", instanceSpec);
     } catch (Exception e) {
@@ -383,13 +391,9 @@ public void executeTransaction(int serviceId, String interfaceName, int txId,
       PublicKey authorPublicKey) {
     synchronized (lock) {
       ServiceWrapper service = getServiceById(serviceId);
-      String serviceName = service.getName();
-      TransactionContext context = TransactionContext.builder()
-          .blockchainData(blockchainData)
+      TransactionContext context = newContext(service, blockchainData)
           .txMessageHash(txMessageHash)
           .authorPk(authorPublicKey)
-          .serviceName(serviceName)
-          .serviceId(serviceId)
           .build();
       try {
         service.executeTransaction(interfaceName, txId, arguments, callerServiceId, context);
@@ -410,7 +414,8 @@ public void beforeTransactions(int serviceId, BlockchainData blockchainData) {
     synchronized (lock) {
       ServiceWrapper service = getServiceById(serviceId);
       try {
-        service.beforeTransactions(blockchainData);
+        TransactionContext context = newContext(service, blockchainData).build();
+        service.beforeTransactions(context);
       } catch (Exception e) {
         logger.error("Service {} threw exception in beforeTransactions.", service.getName(), e);
         throw e;
@@ -435,7 +440,8 @@ public void afterTransactions(int serviceId, BlockchainData blockchainData) {
     synchronized (lock) {
       ServiceWrapper service = getServiceById(serviceId);
       try {
-        service.afterTransactions(blockchainData);
+        TransactionContext context = newContext(service, blockchainData).build();
+        service.afterTransactions(context);
       } catch (Exception e) {
         logger.error("Service {} threw exception in afterTransactions."
             + " Any changes will be rolled-back", service.getName(), e);
@@ -444,6 +450,17 @@ public void afterTransactions(int serviceId, BlockchainData blockchainData) {
     }
   }
 
+  /** Creates a fully-initialized builder of a 'zero' context for the given service. */
+  private static TransactionContext.Builder newContext(ServiceWrapper service,
+      BlockchainData blockchainData) {
+    return TransactionContext.builder()
+        .blockchainData(blockchainData)
+        .serviceName(service.getName())
+        .serviceId(service.getId())
+        .txMessageHash(ZERO_HASH)
+        .authorPk(ZERO_PK);
+  }
+
   /**
    * Notifies the services in the runtime of the block commit event.
    * @param snapshot a snapshot of the current database state

exonum-java-binding/core/src/main/java/com/exonum/binding/core/runtime/ServiceWrapper.java

@@ -20,7 +20,6 @@
 import static com.google.common.base.Throwables.throwIfInstanceOf;
 import static java.lang.String.format;
 
-import com.exonum.binding.core.blockchain.BlockchainData;
 import com.exonum.binding.core.service.BlockCommittedEvent;
 import com.exonum.binding.core.service.Configurable;
 import com.exonum.binding.core.service.Configuration;
@@ -102,12 +101,12 @@ int getId() {
     return instanceSpec.getId();
   }
 
-  void initialize(BlockchainData blockchainData, Configuration configuration) {
-    callServiceMethod(() -> service.initialize(blockchainData, configuration));
+  void initialize(TransactionContext context, Configuration configuration) {
+    callServiceMethod(() -> service.initialize(context, configuration));
   }
 
-  void resume(BlockchainData blockchainData, byte[] arguments) {
-    callServiceMethod(() -> service.resume(blockchainData, arguments));
+  void resume(TransactionContext context, byte[] arguments) {
+    callServiceMethod(() -> service.resume(context, arguments));
   }
 
   void executeTransaction(String interfaceName, int txId, byte[] arguments, int callerServiceId,
@@ -141,27 +140,26 @@ private void executeConfigurableTransaction(int txId, byte[] arguments, int call
         callerServiceId, SUPERVISOR_SERVICE_ID);
     // Invoke the Configurable operation
     Configurable configurable = (Configurable) service;
-    BlockchainData fork = context.getBlockchainData();
     Configuration config = new ServiceConfiguration(arguments);
     switch (txId) {
       case VERIFY_CONFIGURATION_TX_ID:
-        callServiceMethod(() -> configurable.verifyConfiguration(fork, config));
+        callServiceMethod(() -> configurable.verifyConfiguration(context, config));
         break;
       case APPLY_CONFIGURATION_TX_ID:
-        callServiceMethod(() -> configurable.applyConfiguration(fork, config));
+        callServiceMethod(() -> configurable.applyConfiguration(context, config));
         break;
       default:
         throw new IllegalArgumentException(
             format("Unknown txId (%d) in Configurable interface", txId));
     }
   }
 
-  void beforeTransactions(BlockchainData blockchainData) {
-    callServiceMethod(() -> service.beforeTransactions(blockchainData));
+  void beforeTransactions(TransactionContext context) {
+    callServiceMethod(() -> service.beforeTransactions(context));
   }
 
-  void afterTransactions(BlockchainData blockchainData) {
-    callServiceMethod(() -> service.afterTransactions(blockchainData));
+  void afterTransactions(TransactionContext context) {
+    callServiceMethod(() -> service.afterTransactions(context));
   }
 
   /**

exonum-java-binding/core/src/main/java/com/exonum/binding/core/service/Configurable.java

@@ -16,7 +16,7 @@
 
 package com.exonum.binding.core.service;
 
-import com.exonum.binding.core.blockchain.BlockchainData;
+import com.exonum.binding.core.transaction.TransactionContext;
 
 /**
  * A configurable Exonum service. Allows services to update their configuration through
@@ -27,12 +27,11 @@
  * and application of the new configuration. The protocol of the proposal and approval steps
  * is determined by the installed supervisor service. The verification and application
  * of the parameters are implemented by the service with
- * {@link #verifyConfiguration(BlockchainData, Configuration)}
- * and {@link #applyConfiguration(BlockchainData, Configuration)} methods.
+ * {@link #verifyConfiguration(TransactionContext, Configuration)}
+ * and {@link #applyConfiguration(TransactionContext, Configuration)} methods.
  *
  * <p>Services may use the same configuration parameters as
- * in {@link Service#initialize(com.exonum.binding.core.blockchain.BlockchainData, Configuration)},
- * or different.
+ * in {@link Service#initialize(TransactionContext, Configuration)}, or different.
  * <!--
  * TODO: Link the appropriate documentation section on updating the service configuration
  *   through the supervisor when it becomes available (ideally, on the site; or in published
@@ -48,22 +47,23 @@ public interface Configurable {
    * configuration is correct, this method shall return with no changes to the service data.
    * If it is not valid, this method shall throw an exception.
    *
-   * @param blockchainData a read-only access object representing the current database state
+   * @param context a read-only execution context object, providing access to the current database
+   *     state
    * @param configuration a proposed configuration
    * @throws com.exonum.binding.core.transaction.ExecutionException if the proposed configuration
    *     is not valid to prevent the configuration application
    */
-  void verifyConfiguration(BlockchainData blockchainData, Configuration configuration);
+  void verifyConfiguration(TransactionContext context, Configuration configuration);
 
   /**
    * Applies the given configuration to this service. The configuration is guaranteed to be
-   * valid according to {@link #verifyConfiguration(BlockchainData, Configuration)}.
+   * valid according to {@link #verifyConfiguration(TransactionContext, Configuration)}.
    *
    * <p>The implementation shall make any changes to the service persistent state to apply
    * the new configuration, because the supervisor does <em>not</em> store them for later retrieval.
    *
-   * @param blockchainData blockchain data accessor for this service to apply changes to
+   * @param context an execution context for this service
    * @param configuration a new valid configuration
    */
-  void applyConfiguration(BlockchainData blockchainData, Configuration configuration);
+  void applyConfiguration(TransactionContext context, Configuration configuration);
 }

exonum-java-binding/core/src/main/java/com/exonum/binding/core/service/Configuration.java

@@ -27,16 +27,16 @@
  * <p>Network administrators agree on and pass
  * the configuration parameters as a service-specific protobuf message when adding
  * that service instance to the network. After Exonum starts the service, it
- * {@linkplain Service#initialize(com.exonum.binding.core.blockchain.BlockchainData, Configuration)
- * passes the configuration parameters} to the newly created service instance.
+ * {@linkplain Service#initialize(com.exonum.binding.core.transaction.TransactionContext,
+ * Configuration) passes the configuration parameters} to the newly created service instance.
  *
  * <p>Services that have few arguments are encouraged to use the standard protobuf
  * message {@link ServiceConfiguration}. It supports common text-based configuration formats.
  *
  * <p>Reconfiguration of a started service may be implemented with a supervisor service
  * and {@link Configurable} interface.
  *
- * @see Service#initialize(com.exonum.binding.core.blockchain.BlockchainData, Configuration)
+ * @see Service#initialize(com.exonum.binding.core.transaction.TransactionContext, Configuration)
  * @see Configurable
  */
 public interface Configuration {

exonum-java-binding/core/src/main/java/com/exonum/binding/core/service/Schema.java

@@ -17,7 +17,6 @@
 package com.exonum.binding.core.service;
 
 import com.exonum.binding.core.blockchain.Block;
-import com.exonum.binding.core.blockchain.BlockchainData;
 import com.exonum.binding.core.transaction.Transaction;
 
 /**
@@ -33,8 +32,8 @@
  * <p>Exonum starts aggregating a service collection state hash once it is <em>initialized</em>:
  * created for the first time with a read-write
  * {@link com.exonum.binding.core.blockchain.BlockchainData} (e.g., in a
- * {@linkplain Service#initialize(BlockchainData, Configuration) service constructor},
- * or in a {@linkplain Transaction}).
+ * {@linkplain Service#initialize(com.exonum.binding.core.transaction.TransactionContext,
+ * Configuration) service constructor}, or in a {@linkplain Transaction}).
  *
  * <p>Please note that if the service does not use any Merkelized collections,
  * the framework will not be able to verify that its transactions cause the same

exonum-java-binding/core/src/main/java/com/exonum/binding/core/service/Service.java

@@ -16,8 +16,8 @@
 
 package com.exonum.binding.core.service;
 
-import com.exonum.binding.core.blockchain.BlockchainData;
 import com.exonum.binding.core.transaction.ExecutionException;
+import com.exonum.binding.core.transaction.TransactionContext;
 import io.vertx.ext.web.Router;
 
 /**
@@ -40,8 +40,7 @@ public interface Service {
    * or save all or some configuration parameters as is for later retrieval in transactions
    * and/or read requests.
    *
-   * @param blockchainData blockchain data accessor for this service. Not valid after this method
-   *     returns
+   * @param context the execution context
    * @param configuration the service configuration parameters
    * @throws ExecutionException if the configuration parameters are not valid (e.g.,
    *     malformed, or do not meet the preconditions). Exonum will stop the service if
@@ -50,7 +49,7 @@ public interface Service {
    *     the registry of call errors}
    * @see Configurable
    */
-  default void initialize(BlockchainData blockchainData, Configuration configuration) {
+  default void initialize(TransactionContext context, Configuration configuration) {
     // No configuration
   }
 
@@ -66,13 +65,12 @@ default void initialize(BlockchainData blockchainData, Configuration configurati
    * when the block is committed.
    * <!--TODO: Add a link to the migration procedure -->
    *
-   * @param blockchainData blockchain data accessor for this service. Not valid after this method
-   *     returns
+   * @param context the execution context
    * @param arguments the service arguments
    * @throws ExecutionException if the arguments are not valid (e.g.,
    *     malformed, or do not meet the preconditions)
    */
-  default void resume(BlockchainData blockchainData, byte[] arguments) {
+  default void resume(TransactionContext context, byte[] arguments) {
     // No actions by default
   }
 
@@ -108,12 +106,12 @@ default void resume(BlockchainData blockchainData, byte[] arguments) {
 
   /**
    * An optional callback method invoked by the blockchain <em>before</em> any transactions
-   * in a block are executed. See {@link #afterTransactions(BlockchainData)} for details.
+   * in a block are executed. See {@link #afterTransactions(TransactionContext)} for details.
    *
-   * @see #afterTransactions(BlockchainData)
+   * @see #afterTransactions(TransactionContext)
    * @see com.exonum.binding.core.transaction.Transaction
    */
-  default void beforeTransactions(BlockchainData blockchainData) {}
+  default void beforeTransactions(TransactionContext context) {}
 
   /**
    * Handles the changes made by all transactions included in the upcoming block.
@@ -131,15 +129,14 @@ default void beforeTransactions(BlockchainData blockchainData) {}
    * in {@linkplain com.exonum.binding.core.blockchain.Blockchain#getCallErrors(long)
    * the registry of call errors} with appropriate error kinds.
    *
-   * @param blockchainData blockchain data accessor for this service. Not valid after this method
-   *     returns
+   * @param context the execution context
    * @throws ExecutionException if an error occurs during the method execution;
    *     it is saved as a call error of kind "service". Any other exceptions
    *     are considered unexpected. They are saved with kind "unexpected".
-   * @see #beforeTransactions(BlockchainData)
+   * @see #beforeTransactions(TransactionContext)
    * @see com.exonum.binding.core.transaction.Transaction
    */
-  default void afterTransactions(BlockchainData blockchainData) {}
+  default void afterTransactions(TransactionContext context) {}
 
   /**
    * Handles read-only block commit event. This handler is an optional callback method which is