Add transaction methods extraction and invocation [ECR-3923] (#1274)

MakarovS · dmitry-timofeev · commit 1e322c621623 · 2019-12-17T13:25:44.000+02:00
Add transaction methods extraction and invocation classes.
They will be used by ServiceWrapper to invoke transaction 
methods by an id.

Transaction methods are Service methods annotated
with @TransactionMethod, and will replace Transaction-interface,
TransactionConverter and explicit deserialization of arguments.
diff --git a/exonum-java-binding/core/src/main/java/com/exonum/binding/core/runtime/TransactionInvoker.java b/exonum-java-binding/core/src/main/java/com/exonum/binding/core/runtime/TransactionInvoker.java
@@ -0,0 +1,68 @@
+/*
+ * Copyright 2019 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
+ *
+ *     http://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.runtime;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import com.exonum.binding.core.service.Service;
+import com.exonum.binding.core.transaction.TransactionContext;
+import com.exonum.binding.core.transaction.TransactionExecutionException;
+import java.lang.invoke.MethodHandle;
+import java.util.Map;
+
+/**
+ * Stores ids of transaction methods and their method handles of a corresponding service.
+ */
+final class TransactionInvoker {
+  private final Service service;
+  private final Map<Integer, MethodHandle> transactionMethods;
+
+  TransactionInvoker(Service service) {
+    this.service = service;
+    this.transactionMethods =
+        TransactionMethodExtractor.extractTransactionMethods(service.getClass());
+  }
+
+  /**
+   * Invoke the transaction method with a given transaction identifier.
+   *
+   * @param transactionId a transaction method identifier
+   * @param context a transaction execution context
+   * @param arguments the serialized transaction arguments
+   *
+   * @throws IllegalArgumentException if there is no transaction method with given id in a
+   *     corresponding service
+   * @throws TransactionExecutionException if {@link TransactionExecutionException} was thrown by
+   *     the transaction method, it is propagated
+   * @throws RuntimeException any other error is wrapped into a {@link RuntimeException}
+   */
+  void invokeTransaction(int transactionId, byte[] arguments, TransactionContext context)
+      throws TransactionExecutionException {
+    checkArgument(transactionMethods.containsKey(transactionId),
+        "No method with transaction id (%s)", transactionId);
+    try {
+      MethodHandle methodHandle = transactionMethods.get(transactionId);
+      methodHandle.invoke(service, arguments, context);
+    } catch (Throwable throwable) {
+      if (throwable instanceof TransactionExecutionException) {
+        throw (TransactionExecutionException) throwable;
+      } else {
+        throw new RuntimeException(throwable);
+      }
+    }
+  }
+}
diff --git a/exonum-java-binding/core/src/main/java/com/exonum/binding/core/runtime/TransactionMethodExtractor.java b/exonum-java-binding/core/src/main/java/com/exonum/binding/core/runtime/TransactionMethodExtractor.java
@@ -0,0 +1,111 @@
+/*
+ * Copyright 2019 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
+ *
+ *     http://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.runtime;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static java.util.stream.Collectors.toMap;
+
+import com.exonum.binding.core.transaction.TransactionContext;
+import com.exonum.binding.core.transaction.TransactionMethod;
+import com.google.common.annotations.VisibleForTesting;
+
+import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodHandles;
+import java.lang.invoke.MethodHandles.Lookup;
+import java.lang.reflect.Method;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Finds and validates transaction methods in a service.
+ */
+final class TransactionMethodExtractor {
+
+  /**
+   * Returns a map of transaction ids to transaction methods found in a service class.
+   *
+   * @see TransactionMethod
+   */
+  static Map<Integer, MethodHandle> extractTransactionMethods(Class<?> serviceClass) {
+    Map<Integer, Method> transactionMethods = findTransactionMethods(serviceClass);
+    Lookup lookup = MethodHandles.publicLookup()
+        .in(serviceClass);
+    return transactionMethods.entrySet().stream()
+        .peek(tx -> validateTransactionMethod(tx.getValue(), serviceClass))
+        .collect(toMap(Map.Entry::getKey,
+            (e) -> toMethodHandle(e.getValue(), lookup)));
+  }
+
+  @VisibleForTesting
+  static Map<Integer, Method> findTransactionMethods(Class<?> serviceClass) {
+    Map<Integer, Method> transactionMethods = new HashMap<>();
+    while (serviceClass != Object.class) {
+      Method[] classMethods = serviceClass.getDeclaredMethods();
+      for (Method method : classMethods) {
+        if (method.isAnnotationPresent(TransactionMethod.class)) {
+          TransactionMethod annotation = method.getAnnotation(TransactionMethod.class);
+          int transactionId = annotation.value();
+          checkDuplicates(transactionMethods, transactionId, serviceClass, method);
+          transactionMethods.put(transactionId, method);
+        }
+      }
+      serviceClass = serviceClass.getSuperclass();
+    }
+    return transactionMethods;
+  }
+
+  private static void checkDuplicates(Map<Integer, Method> transactionMethods, int transactionId,
+      Class<?> serviceClass, Method method) {
+    if (transactionMethods.containsKey(transactionId)) {
+      String firstMethodName = transactionMethods.get(transactionId).getName();
+      String errorMessage = String.format("Service %s has more than one transaction with the same"
+              + " id (%s): first: %s; second: %s",
+          serviceClass.getName(), transactionId, firstMethodName, method.getName());
+      throw new IllegalArgumentException(errorMessage);
+    }
+  }
+
+  /**
+   * Checks that the given transaction method signature is correct.
+   */
+  private static void validateTransactionMethod(Method transaction, Class<?> serviceClass) {
+    String errorMessage = String.format("Method %s in a service class %s annotated with"
+        + " @TransactionMethod should have precisely two parameters of the following types:"
+        + " 'byte[]' and 'com.exonum.binding.core.transaction.TransactionContext'",
+        transaction.getName(), serviceClass.getName());
+    checkArgument(transaction.getParameterCount() == 2, errorMessage);
+    Class<?> firstParameter = transaction.getParameterTypes()[0];
+    Class<?> secondParameter = transaction.getParameterTypes()[1];
+    checkArgument(firstParameter == byte[].class,
+        String.format(errorMessage
+            + ". But first parameter type was: %s", firstParameter.getName()));
+    checkArgument(TransactionContext.class.isAssignableFrom(secondParameter),
+        String.format(errorMessage
+            + ". But second parameter type was: %s", secondParameter.getName()));
+  }
+
+  private static MethodHandle toMethodHandle(Method method, Lookup lookup) {
+    try {
+      return lookup.unreflect(method);
+    } catch (IllegalAccessException e) {
+      throw new IllegalArgumentException(
+          String.format("Couldn't access method %s", method.getName()), e);
+    }
+  }
+
+  private TransactionMethodExtractor() {}
+}
diff --git a/exonum-java-binding/core/src/main/java/com/exonum/binding/core/transaction/TransactionMethod.java b/exonum-java-binding/core/src/main/java/com/exonum/binding/core/transaction/TransactionMethod.java
@@ -0,0 +1,61 @@
+/*
+ * Copyright 2019 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
+ *
+ *     http://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.transaction;
+
+import com.exonum.binding.common.message.TransactionMessage;
+import com.exonum.core.messages.Runtime.ErrorKind;
+import com.exonum.core.messages.Runtime.ExecutionError;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates that a method is a transaction method. The annotated method should execute the
+ * transaction, possibly modifying the blockchain state. The method should:
+ * <ul>
+ *   <li>be public
+ *   <li>have exactly two parameters - the
+ *       {@linkplain TransactionMessage#getPayload() serialized transaction arguments} of type
+ *       'byte[]' and a transaction execution context, which allows to access the information about
+ *       this transaction and modify the blockchain state through the included database fork of
+ *       type '{@link TransactionContext}' in this particular order
+ * </ul>
+ *
+ * <p>The annotated method might throw {@linkplain TransactionExecutionException} if the
+ * transaction cannot be executed normally and has to be rolled back. The transaction will be
+ * committed as failed (error kind {@linkplain ErrorKind#SERVICE SERVICE}), the
+ * {@linkplain ExecutionError#getCode() error code} with the optional description will be saved
+ * into the storage. The client can request the error code to know the reason of the failure.
+ *
+ * <p>The annotated method might also throw {@linkplain RuntimeException} if an unexpected error
+ * occurs. A correct transaction implementation must not throw such exceptions. The transaction
+ * will be committed as failed (status "panic").
+ *
+ * @see <a href="https://exonum.com/doc/version/0.13-rc.2/architecture/transactions">Exonum Transactions</a>
+ * @see <a href="https://exonum.com/doc/version/0.13-rc.2/architecture/services">Exonum Services</a>
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+// TODO: rename to Transaction after migration
+public @interface TransactionMethod {
+
+  /**
+   * Returns the transaction type identifier which is unique within the service.
+   */
+  int value();
+}
diff --git a/exonum-java-binding/core/src/test/java/com/exonum/binding/core/runtime/TransactionInvokerTest.java b/exonum-java-binding/core/src/test/java/com/exonum/binding/core/runtime/TransactionInvokerTest.java
@@ -0,0 +1,126 @@
+/*
+ * Copyright 2019 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
+ *
+ *     http://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.runtime;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.Mockito.spy;
+import static org.mockito.Mockito.verify;
+
+import com.exonum.binding.common.hash.HashCode;
+import com.exonum.binding.core.service.Node;
+import com.exonum.binding.core.service.Service;
+import com.exonum.binding.core.storage.database.Snapshot;
+import com.exonum.binding.core.transaction.TransactionContext;
+import com.exonum.binding.core.transaction.TransactionExecutionException;
+import com.exonum.binding.core.transaction.TransactionMethod;
+import io.vertx.ext.web.Router;
+import java.util.Collections;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mock;
+
+class TransactionInvokerTest {
+
+  private static final byte[] ARGUMENTS = new byte[0];
+  @Mock
+  private TransactionContext context;
+
+  @Test
+  void invokeValidServiceTransaction() throws Exception {
+    ValidService service = spy(new ValidService());
+    TransactionInvoker invoker = new TransactionInvoker(service);
+    invoker.invokeTransaction(ValidService.TRANSACTION_ID, ARGUMENTS, context);
+    invoker.invokeTransaction(ValidService.TRANSACTION_ID_2, ARGUMENTS, context);
+
+    verify(service).transactionMethod(ARGUMENTS, context);
+    verify(service).transactionMethod2(ARGUMENTS, context);
+  }
+
+  @Test
+  void invokeInvalidTransactionId() {
+    TransactionInvoker invoker = new TransactionInvoker(new ValidService());
+    int invalidTransactionId = Integer.MAX_VALUE;
+    IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+        () -> invoker.invokeTransaction(invalidTransactionId, ARGUMENTS, context));
+    assertThat(e.getMessage())
+        .contains(String.format("No method with transaction id (%s)", invalidTransactionId));
+  }
+
+  @Test
+  void invokeThrowingTransactionExecutionException() {
+    TransactionInvoker invoker = new TransactionInvoker(new ThrowingService());
+    TransactionExecutionException e = assertThrows(TransactionExecutionException.class,
+        () -> invoker.invokeTransaction(ThrowingService.TRANSACTION_ID, ARGUMENTS, context));
+    assertThat(e.getErrorCode()).isEqualTo(ThrowingService.ERROR_CODE);
+  }
+
+  @Test
+  void invokeThrowingServiceException() {
+    TransactionInvoker invoker = new TransactionInvoker(new ThrowingService());
+    RuntimeException e = assertThrows(RuntimeException.class,
+        () -> invoker.invokeTransaction(ThrowingService.TRANSACTION_ID_2, ARGUMENTS, context));
+    assertThat(e.getCause().getClass()).isEqualTo(IllegalArgumentException.class);
+  }
+
+  static class BasicService implements Service {
+
+    static final int TRANSACTION_ID = 1;
+    static final int TRANSACTION_ID_2 = 2;
+
+    @Override
+    public List<HashCode> getStateHashes(Snapshot snapshot) {
+      return Collections.emptyList();
+    }
+
+    @Override
+    public void createPublicApiHandlers(Node node, Router router) {
+      // no-op
+    }
+  }
+
+  public static class ValidService extends BasicService {
+
+    @TransactionMethod(TRANSACTION_ID)
+    @SuppressWarnings("WeakerAccess") // Should be accessible
+    public void transactionMethod(byte[] arguments, TransactionContext context) {
+    }
+
+    @TransactionMethod(TRANSACTION_ID_2)
+    @SuppressWarnings("WeakerAccess") // Should be accessible
+    public void transactionMethod2(byte[] arguments, TransactionContext context) {
+    }
+  }
+
+  public static class ThrowingService extends BasicService {
+
+    static final byte ERROR_CODE = 18;
+    static final String ERROR_MESSAGE = "Service originated exception";
+
+    @TransactionMethod(TRANSACTION_ID)
+    public void transactionMethod(byte[] arguments, TransactionContext context)
+        throws TransactionExecutionException {
+      throw new TransactionExecutionException(ERROR_CODE);
+    }
+
+    @TransactionMethod(TRANSACTION_ID_2)
+    public void transactionMethod2(byte[] arguments, TransactionContext context)
+        throws TransactionExecutionException {
+      throw new IllegalArgumentException(ERROR_MESSAGE);
+    }
+  }
+}
diff --git a/exonum-java-binding/core/src/test/java/com/exonum/binding/core/runtime/TransactionMethodExtractorTest.java b/exonum-java-binding/core/src/test/java/com/exonum/binding/core/runtime/TransactionMethodExtractorTest.java
