Extract #getIndexHash in HashableIndex interface [ECR-4064].

exonum-java-binding/CHANGELOG.md

@@ -66,7 +66,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Transaction index in block type changed from `long` to `int`. (#1348)
 - Extracted artifact version to the separate field from the artifact name.
   Artifact name format is `groupId/artifactId` now.
-  PluginId format is `runtimeId:artifactName:artifactVersion` now. (#1349) 
+  PluginId format is `runtimeId:artifactName:artifactVersion` now. (#1349)
+- Extracted `#getIndexHash` into `HashableIndex` interface. (#1366)
 
 ### Removed
 - Classes supporting no longer used tree-like list proof representation.

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

@@ -17,9 +17,6 @@
 package com.exonum.binding.core.service;
 
 import com.exonum.binding.core.blockchain.Block;
-import com.exonum.binding.core.storage.indices.ProofEntryIndexProxy;
-import com.exonum.binding.core.storage.indices.ProofListIndexProxy;
-import com.exonum.binding.core.storage.indices.ProofMapIndexProxy;
 
 /**
  * A schema of the collections (a.k.a. indices) of a service.
@@ -38,9 +35,7 @@
  * the framework will not be able to verify that its transactions cause the same
  * results on different nodes.
  *
- * @see ProofListIndexProxy#getIndexHash()
- * @see ProofMapIndexProxy#getIndexHash()
- * @see ProofEntryIndexProxy#getIndexHash()
+ * @see com.exonum.binding.core.storage.indices.HashableIndex
  * @see com.exonum.binding.core.blockchain.Blockchain
  */
 public interface Schema {

exonum-java-binding/core/src/main/java/com/exonum/binding/core/storage/indices/HashableIndex.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2020 The Exonum Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.exonum.binding.core.storage.indices;
+
+import com.exonum.binding.common.hash.HashCode;
+
+/**
+ * A hashable index provides a cryptographic hash which represents the complete state of this index.
+ *
+ * <p>Hashable indexes enable efficient verification of their contents. Two indexes contain
+ * the same values if their index hashes are equal. This property is used in the consensus
+ * algorithm to compare the database state on different nodes.
+ *
+ * <p>Index hashes are also used in verifiable index views. Such views contain a subset
+ * of index elements and a proof that jointly allow to restore the index hash. The computed
+ * index hash allows to verify that the elements come from an index with a certain state.
+ *
+ * <p>Hashable indexes may participate in
+ * <a href="https://docs.rs/exonum-merkledb/0.13.0-rc.2/exonum_merkledb/#state-aggregation">state hash aggregation</a>.
+ *
+ * @see <a href="https://docs.rs/exonum-merkledb/0.13.0-rc.2/exonum_merkledb/trait.ObjectHash.html">ObjectHash trait</a>
+ */
+public interface HashableIndex extends StorageIndex {
+
+  /**
+   * Returns the index hash which represents the complete state of this index.
+   * Any modifications to the stored entries affect the index hash.
+   *
+   * <p>How index hash is computed depends on the index data structure implementation.
+   */
+  HashCode getIndexHash();
+}

exonum-java-binding/core/src/main/java/com/exonum/binding/core/storage/indices/ProofEntryIndexProxy.java

@@ -50,7 +50,7 @@
  *
  * @see View
  */
-public final class ProofEntryIndexProxy<T> extends AbstractIndexProxy {
+public final class ProofEntryIndexProxy<T> extends AbstractIndexProxy implements HashableIndex {
 
   static {
     LibraryLoader.load();
@@ -178,8 +178,9 @@ public T get() {
    * <p>The entry index hash is computed as SHA-256 of the entry binary representation, or
    * a hash of zeroes if the entry is not set.
    *
-   * @throws IllegalStateException if this list is not valid
+   * @throws IllegalStateException if the proxy is invalid
    */
+  @Override
   public HashCode getIndexHash() {
     return HashCode.fromBytes(nativeGetIndexHash(getNativeHandle()));
   }

exonum-java-binding/core/src/main/java/com/exonum/binding/core/storage/indices/ProofListIndexProxy.java

@@ -54,7 +54,7 @@
  * @see View
  */
 public final class ProofListIndexProxy<E> extends AbstractListIndexProxy<E>
-    implements ListIndex<E> {
+    implements ListIndex<E>, HashableIndex {
 
   static {
     LibraryLoader.load();
@@ -212,12 +212,7 @@ private static ListProof parseProof(byte[] proofMessage) {
     }
   }
 
-  /**
-   * Returns the index hash which represents the complete state of this list.
-   * Any modifications to the stored entries affect the index hash.
-   *
-   * @throws IllegalStateException if this list is not valid
-   */
+  @Override
   public HashCode getIndexHash() {
     return HashCode.fromBytes(nativeGetIndexHash(getNativeHandle()));
   }

exonum-java-binding/core/src/main/java/com/exonum/binding/core/storage/indices/ProofMapIndexProxy.java

@@ -85,7 +85,8 @@
  * @param <V> the type of values in this map
  * @see View
  */
-public final class ProofMapIndexProxy<K, V> extends AbstractIndexProxy implements MapIndex<K, V> {
+public final class ProofMapIndexProxy<K, V> extends AbstractIndexProxy implements MapIndex<K, V>,
+    HashableIndex {
 
   private final Serializer<K> keySerializer;
   private final CheckingSerializerDecorator<V> valueSerializer;
@@ -381,12 +382,7 @@ private static MapProof decodeProofMessage(byte[] proofMessage) {
     }
   }
 
-  /**
-   * Returns the index hash which represents the complete state of this map.
-   * Any modifications to the stored entries affect the index hash.
-   *
-   * @throws IllegalStateException if this map is not valid
-   */
+  @Override
   public HashCode getIndexHash() {
     return HashCode.fromBytes(nativeGetIndexHash(getNativeHandle()));
   }