[FAB-11989] Clarify error handling for plugins

Change-Id: I3d77a06158b78b0e2df3123ba68edcb4add3150c
Signed-off-by: Alessandro Sorniotti <ale.linux@sopit.net>
Signed-off-by: Matthias Neugschwandtner <eug@zurich.ibm.com>

Author: ale-linux

docs/source/pluggable_endorsement_and_validation.rst

@@ -255,18 +255,24 @@ Currently Fabric comes with the following dependencies for validation plugins:
 
     // State defines interaction with the world state
     type State interface {
-    	// GetStateMultipleKeys gets the values for multiple keys in a single call
-    	GetStateMultipleKeys(namespace string, keys []string) ([][]byte, error)
+        // GetStateMultipleKeys gets the values for multiple keys in a single call
+        GetStateMultipleKeys(namespace string, keys []string) ([][]byte, error)
 
-    	// GetStateRangeScanIterator returns an iterator that contains all the key-values between given key ranges.
-    	// startKey is included in the results and endKey is excluded. An empty startKey refers to the first available key
-    	// and an empty endKey refers to the last available key. For scanning all the keys, both the startKey and the endKey
-    	// can be supplied as empty strings. However, a full scan should be used judiciously for performance reasons.
-    	// The returned ResultsIterator contains results of type *KV which is defined in protos/ledger/queryresult.
-    	GetStateRangeScanIterator(namespace string, startKey string, endKey string) (ResultsIterator, error)
+        // GetStateRangeScanIterator returns an iterator that contains all the key-values between given key ranges.
+        // startKey is included in the results and endKey is excluded. An empty startKey refers to the first available key
+        // and an empty endKey refers to the last available key. For scanning all the keys, both the startKey and the endKey
+        // can be supplied as empty strings. However, a full scan should be used judiciously for performance reasons.
+        // The returned ResultsIterator contains results of type *KV which is defined in protos/ledger/queryresult.
+        GetStateRangeScanIterator(namespace string, startKey string, endKey string) (ResultsIterator, error)
 
-    	// Done releases resources occupied by the State
-    	Done()
+        // GetStateMetadata returns the metadata for given namespace and key
+        GetStateMetadata(namespace, key string) (map[string][]byte, error)
+
+        // GetPrivateDataMetadata gets the metadata of a private data item identified by a tuple <namespace, collection, key>
+        GetPrivateDataMetadata(namespace, collection, key string) (map[string][]byte, error)
+
+        // Done releases resources occupied by the State
+        Done()
     }
 
 Important notes
@@ -290,6 +296,13 @@ Important notes
   of marking the transaction as invalid. This is to prevent state divergence
   between different peers.
 
+- **Error handling for private metadata retrieval**: In case a plugin retrieves
+  metadata for private data by making use of the ``StateFetcher`` interface,
+  it is important that errors are handled as follows: ``CollConfigNotDefinedError''
+  and ``InvalidCollNameError'', signalling that the specified collection does
+  not exist, should be handled as deterministic errors and should not lead the
+  plugin to return an ``ExecutionFailureError``.
+
 - **Importing Fabric code into the plugin**: Importing code that belongs to Fabric
   other than protobufs as part of the plugin is highly discouraged, and can lead
   to issues when the Fabric code changes between releases, or can cause inoperability