[FAB-15743] Align Context

- Node.js (JavaScript and TypeScript) pass the context on a per
  tx function basis.
- The context is effectively the 'Fabric Transaction Context'
  Contains the txid and channel id
- This is need for any interaction with the world state for example
  and is specific to the specific transaction that is executed
- Getting hold of the stub api that is applicable to this transaction
  is via the context (ctx.getStub())
- Future releases will adjust the API used to a more ledger focussed
  api
- Feedback on improvements to this api welcome (jira issues pls)

Change-Id: Ibb4237726a1401cc9f9d12e297acb1b9424be967
Signed-off-by: Matthew B. White <[email protected]>

Author: mbwhite

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/contract/Context.java

@@ -11,12 +11,41 @@
 /**
  *
  * This context is available to all 'transaction functions' and provides the
- * transaction context.
+ * transaction context. It also provides access to the APIs for the world state
+ * using {@link #getStub()}
+ * <p>
+ * Applications can implement their own versions if they wish to add
+ * functionality. All subclasses MUST implement a constructor, for example
+ * <pre>
+ * {@code
  *
- * It also provides access to the APIs for the world state. {@see ChaincodeStub}
+ * public MyContext extends Context {
+ *
+ *     public MyContext(ChaincodeStub stub) {
+ *        super(stub);
+ *     }
+ * }
+ *
+ *}
+ *</pre>
  *
- * Applications can implement their own versions if they wish to add
- * functionality.
  */
-public interface Context extends ChaincodeStub {
+public class Context {
+    protected ChaincodeStub stub;
+
+    /**
+     * Constructor
+     * @param stub Instance of the {@link ChaincodeStub} to use
+     */
+    public Context(ChaincodeStub stub) {
+        this.stub = stub;
+    }
+
+    /**
+     *
+     * @return ChaincodeStub instance to use
+     */
+    public ChaincodeStub getStub() {
+        return this.stub;
+    }
 }

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/contract/ContextFactory.java

@@ -6,10 +6,6 @@
 
 package org.hyperledger.fabric.contract;
 
-import java.lang.reflect.InvocationHandler;
-import java.lang.reflect.Method;
-import java.lang.reflect.Proxy;
-
 import org.hyperledger.fabric.shim.ChaincodeStub;
 
 /**
@@ -26,25 +22,9 @@ static synchronized public ContextFactory getInstance() {
         return cf;
     }
 
-    public synchronized Context createContext(final ChaincodeStub stub) {
-        Context newContext = (Context) Proxy.newProxyInstance(this.getClass().getClassLoader(),
-                new Class[] { Context.class }, new ContextInvocationHandler(stub));
+    public Context createContext(final ChaincodeStub stub) {
+        Context newContext = new Context(stub);
         return newContext;
     }
 
-    static class ContextInvocationHandler implements InvocationHandler {
-
-        private ChaincodeStub stub;
-
-        ContextInvocationHandler(final ChaincodeStub stub) {
-            this.stub = stub;
-        }
-
-        @Override
-        public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
-            Method m = ChaincodeStub.class.getMethod(method.getName(), method.getParameterTypes());
-            return m.invoke(stub, args);
-        }
-    }
-
 }

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/contract/ContractInterface.java

@@ -6,39 +6,96 @@
 
 package org.hyperledger.fabric.contract;
 
+import org.hyperledger.fabric.contract.annotation.Contract;
+import org.hyperledger.fabric.contract.annotation.Transaction;
 import org.hyperledger.fabric.shim.ChaincodeStub;
 
 /**
- * Interface all contracts should implement
+ * All Contracts should implement this interface, in addition to the
+ * {@link Contract} annotation.
+ * <p>
+ * All the of the methods on this is inteface have default implementations; for
+ * many contracts it may not be needed to sub-class these.
+ * <p>
+ * Each method on the Contract that is marked with the {@link Transaction}
+ * annotation is considered a Transaction Function. This is eligible for
+ * calling. Each transaction function is supplied with it's first parameter
+ * being a {@link org.hyperledger.fabric.contract.Context} the other parameters
+ * are at the developer's discretion.
+ * <p>
+ * The sequence of calls is
+ *
+ * <pre>
+ * createContext()  -> beforeTransaction() -> the transaction function -> afterTransaction()
+ * </pre>
+ * <p>
+ * If any of these functions throws an exception it is considered an error case,
+ * and the whole transaction is failed. The {@link org.hyperledger.fabric.contract.Context} is
+ * a very important object as it provides transactional context for access to current transaction id,
+ * ledger state, etc.
+ * <p>
+ * <b>Note on Threading</b>
+ * <p>
+ * All code should be 'Thread Friendly'. Each method must not rely on instance
+ * fields or class side variables for storage. Nor should they use any
+ * ThreadLocal Storage. Ledger data is stored via the ledger api available via
+ * the {@link Context}.
+ * <p>
+ * If information needs to be passed from the {@link #beforeTransaction(Context)}
+ * {@link #afterTransaction(Context, Object)} or between separate transaction functions when
+ * called directory, then a subclass of the
+ * {@link Context} should be provided.
+ * <p>
+ *
  */
 public interface ContractInterface {
-    /**
-     * Returns instance of context associated with current invocation
-     * @return
-     */
-    default Context getContext() { throw new IllegalStateException("getContext default implementation can't be directly invoked"); }
 
     /**
-     * Create context from {@link ChaincodeStub}, default impl provided, but can be overwritten by contract
-     * @param stub
-     * @return
+     * Create context from {@link ChaincodeStub}, default impl provided, but can be
+     * overwritten by contract
+     *
+     * @param stub Instance of the ChaincodeStub to use for this transaction
+     * @return instance of the context to use for the current transaciton being
+     *         executed
      */
-    default Context createContext(ChaincodeStub stub) { return ContextFactory.getInstance().createContext(stub); }
+    default Context createContext(ChaincodeStub stub) {
+        return ContextFactory.getInstance().createContext(stub);
+    }
 
     /**
-     * Invoked once method for transaction not exist in contract
+     * Invoked for any transaction that does not exist.
+     *
+     * This will throw an exception. If you wish to alter the exception thrown or if
+     * you wish to consider requests for transactions that don't exist as not an
+     * error, subclass this method.
+     *
+     * @param ctx the context as created by {@link #createContext(ChaincodeStub)}.
      */
-    default void unknownTransaction() {
-    	throw new IllegalStateException("Undefined contract method called");
+    default void unknownTransaction(Context ctx) {
+        throw new IllegalStateException("Undefined contract method called");
     }
 
     /**
-     * Invoke before each transaction method
+     * Invoked once before each transaction.
+     *
+     * Any exceptions thrown will fail the transaction, and neither the required
+     * transaction or the {@link #afterTransaction(Context, Object)} will be called
+     *
+     * @param ctx the context as created by {@link #createContext(ChaincodeStub)}.
      */
-    default void beforeTransaction() {}
+    default void beforeTransaction(Context ctx) {
+    }
 
     /**
-     * Invoke after each transaction method
+     * Invoked once after each transaction.
+     *
+     * Any exceptions thrown will fail the transaction.
+     *
+     * @param ctx    the context as created by {@link #createContext(ChaincodeStub)}.
+     * @param result The object returned from the transaction function if any. As
+     *               this is a Java object and therefore pass-by-reference it is
+     *               possible to modify this object.
      */
-    default void afterTransaction() {}
+    default void afterTransaction(Context ctx, Object result) {
+    }
 }

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/contract/ContractRuntimeException.java

@@ -7,9 +7,9 @@
 
 /**
  * Specific RuntimeException for events that occur in the calling and handling
- * of the Contracts.
- *
- * At some future point we wish to add more diagnostic information into this,
+ * of the Contracts, NOT within the contract logic itself.
+ * <p>
+ * <B>FUTURE</b> At some future point we wish to add more diagnostic information into this,
  * for example current tx id
  *
  */

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/contract/annotation/Contract.java

@@ -18,16 +18,31 @@
  * Class level annotation that identifies this class as being a contract. Can
  * supply information and an alternative name for the contract rather than the
  * classname
- *
+ * <p>
  * The Info object can be supplied to provide additional information about the
  * contract; the format of this uses the OpenAPI v3 specification of info
- * {@see io.swagger.v3.oas.annotations.info.Info}
+ * {@link io.swagger.v3.oas.annotations.info.Info}
  *
  */
 @Retention(RUNTIME)
 @Target(ElementType.TYPE)
 public @interface Contract {
+
+    /**
+     * The Info object can be supplied to provide additional information about the
+     * contract; the format of this uses the  OpenAPI v3 Info format
+     *
+     *
+     * @return OpenAPI v3 specification of info
+     *         {@link io.swagger.v3.oas.annotations.info.Info}
+     */
     Info info();
 
+    /**
+     * Normally the name of the class is used to refer to the contract (name without package).
+     * This can be altered if wished.
+     *
+     * @return Name of the contract to be used instead of the Classname
+     */
     String name() default "";
 }

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/contract/annotation/DataType.java

@@ -14,8 +14,14 @@
 /**
  * Class level annotation indicating this class represents one of the complex
  * types that can be returned or passed to the transaction functions.
- *
- * This will appear within the metadata
+ * <p>
+ * These datatypes are used (within the current implementation) for determining the data flow protocol
+ * from the Contracts to the SDK and for permitting a fully formed Interface Definition to be created for the
+ * contract.
+ * <p>
+ * Complex types can appear within this definition, and these are identified using this annotation.
+ * <p>
+ * <b>FUTURE</b> To take these annotations are also utilize them for leverage storage
  */
 @Retention(RUNTIME)
 @Target(ElementType.TYPE)

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/contract/annotation/Property.java

@@ -12,12 +12,34 @@
 import java.lang.annotation.Target;
 
 /**
- * Property level annotation defining a property of the class (identified by
- * {@link @DataType}) Can also be used on the paratemers of transaction
- * functions
+ * Field and parameter level annotation defining a property of the class
+ * (identified by {@link DataType}) Can also be used on the paratemers of
+ * transaction functions
+ * <p>
+ * Example of using this annotation
+ *
+ * <pre>
+ *
+ * // max 15 character string, a-z with spaces
+ * &#64;Property(schema = { "pattern", "^[a-zA-Z\\s]{0,15}$" })
+ * private String text;
+ *
+ * // How friendly is this on a scale of 1-5, 1 being formal, 5 being familar
+ * &#64;Property(schema = { "minimum", "1", "maximum", "5" })
+ * private int friendlyness = 1;
+ *
+ * </pre>
  */
 @Retention(RUNTIME)
 @Target({ ElementType.FIELD, ElementType.PARAMETER })
 public @interface Property {
+
+    /**
+     * Allows each property to be defined a detail set of rules to determine the
+     * valid types of this data. The format follows the syntax of the OpenAPI Schema
+     * object.
+     *
+     * @return String array of the key-value pairs of the schema
+     */
     String[] schema() default {};
 }

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/contract/annotation/Transaction.java

@@ -13,8 +13,12 @@
 import java.lang.annotation.Target;
 
 /**
- * Method level annotation indicating the function to be a callable transaction
- * function
+ * Method level annotation indicating the method to be a callable transaction
+ * function.
+ * <p>
+ * These funcitons are called in client SDKs by the combination of <pre> [contractname]:[transactioname] </pre>
+ * Unless specified other wise, the contract name is the class name (without package) and the transactio
+ * name is the method name.
  */
 @Retention(RUNTIME)
 @Target(METHOD)
@@ -26,13 +30,13 @@
      * FALSE indicates that this is intended to be called with the evaluate
      * semantics
      *
-     * @return
+     * @return boolean, default is true
      */
     boolean submit() default true;
 
     /**
      * The name of the callable transaction if it should be different to the method
-     * name
+     * name.
      *
      * @return the transaction name
      */

fabric-chaincode-shim/src/main/java/org/hyperledger/fabric/contract/execution/JSONTransactionSerializer.java

@@ -45,7 +45,7 @@ public JSONTransactionSerializer(TypeRegistry typeRegistry) {
      *
      * @param value
      * @param ts
-     * @return
+     * @return  Byte buffer
      */
     public byte[] toBuffer(Object value, TypeSchema ts) {
         logger.debug(() -> "Schema to convert is " + ts);