github.com/adnan-c/fabric_e2e_couchdb@v0.6.1-preview.0.20170228180935-21ce6b23cf91/core/ledger/ledger_interface.go (about)

     1  /*
     2  Copyright IBM Corp. 2016 All Rights Reserved.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8  		 http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  package ledger
    18  
    19  import (
    20  	commonledger "github.com/hyperledger/fabric/common/ledger"
    21  	"github.com/hyperledger/fabric/protos/common"
    22  	"github.com/hyperledger/fabric/protos/peer"
    23  )
    24  
    25  // PeerLedgerProvider provides handle to ledger instances
    26  type PeerLedgerProvider interface {
    27  	// Create creates a new ledger with a given unique id
    28  	Create(ledgerID string) (PeerLedger, error)
    29  	// Open opens an already created ledger
    30  	Open(ledgerID string) (PeerLedger, error)
    31  	// Exists tells whether the ledger with given id exists
    32  	Exists(ledgerID string) (bool, error)
    33  	// List lists the ids of the existing ledgers
    34  	List() ([]string, error)
    35  	// Close closes the PeerLedgerProvider
    36  	Close()
    37  }
    38  
    39  // PeerLedger differs from the OrdererLedger in that PeerLedger locally maintain a bitmask
    40  // that tells apart valid transactions from invalid ones
    41  type PeerLedger interface {
    42  	commonledger.Ledger
    43  	// GetTransactionByID retrieves a transaction by id
    44  	GetTransactionByID(txID string) (*peer.ProcessedTransaction, error)
    45  	// GetBlockByHash returns a block given it's hash
    46  	GetBlockByHash(blockHash []byte) (*common.Block, error)
    47  	// GetBlockByTxID returns a block which contains a transaction
    48  	GetBlockByTxID(txID string) (*common.Block, error)
    49  	// NewTxSimulator gives handle to a transaction simulator.
    50  	// A client can obtain more than one 'TxSimulator's for parallel execution.
    51  	// Any snapshoting/synchronization should be performed at the implementation level if required
    52  
    53  	// GetTxValidationCodeByTxID returns reason code of transaction validation
    54  	GetTxValidationCodeByTxID(txID string) (peer.TxValidationCode, error)
    55  	NewTxSimulator() (TxSimulator, error)
    56  	// NewQueryExecutor gives handle to a query executor.
    57  	// A client can obtain more than one 'QueryExecutor's for parallel execution.
    58  	// Any synchronization should be performed at the implementation level if required
    59  	NewQueryExecutor() (QueryExecutor, error)
    60  	// NewHistoryQueryExecutor gives handle to a history query executor.
    61  	// A client can obtain more than one 'HistoryQueryExecutor's for parallel execution.
    62  	// Any synchronization should be performed at the implementation level if required
    63  	NewHistoryQueryExecutor() (HistoryQueryExecutor, error)
    64  	//Prune prunes the blocks/transactions that satisfy the given policy
    65  	Prune(policy commonledger.PrunePolicy) error
    66  }
    67  
    68  // ValidatedLedger represents the 'final ledger' after filtering out invalid transactions from PeerLedger.
    69  // Post-v1
    70  type ValidatedLedger interface {
    71  	commonledger.Ledger
    72  }
    73  
    74  // QueryExecutor executes the queries
    75  // Get* methods are for supporting KV-based data model. ExecuteQuery method is for supporting a rich datamodel and query support
    76  //
    77  // ExecuteQuery method in the case of a rich data model is expected to support queries on
    78  // latest state, historical state and on the intersection of state and transactions
    79  type QueryExecutor interface {
    80  	// GetState gets the value for given namespace and key. For a chaincode, the namespace corresponds to the chaincodeId
    81  	GetState(namespace string, key string) ([]byte, error)
    82  	// GetStateMultipleKeys gets the values for multiple keys in a single call
    83  	GetStateMultipleKeys(namespace string, keys []string) ([][]byte, error)
    84  	// GetStateRangeScanIterator returns an iterator that contains all the key-values between given key ranges.
    85  	// startKey is included in the results and endKey is excluded. An empty startKey refers to the first available key
    86  	// and an empty endKey refers to the last available key. For scanning all the keys, both the startKey and the endKey
    87  	// can be supplied as empty strings. However, a full scan shuold be used judiciously for performance reasons.
    88  	// The returned ResultsIterator contains results of type *KV
    89  	GetStateRangeScanIterator(namespace string, startKey string, endKey string) (commonledger.ResultsIterator, error)
    90  	// ExecuteQuery executes the given query and returns an iterator that contains results of type specific to the underlying data store.
    91  	// Only used for state databases that support query
    92  	// For a chaincode, the namespace corresponds to the chaincodeId
    93  	ExecuteQuery(namespace, query string) (commonledger.ResultsIterator, error)
    94  	// Done releases resources occupied by the QueryExecutor
    95  	Done()
    96  }
    97  
    98  // HistoryQueryExecutor executes the history queries
    99  type HistoryQueryExecutor interface {
   100  	// GetHistoryForKey retrieves the history of values for a key.
   101  	GetHistoryForKey(namespace string, key string) (commonledger.ResultsIterator, error)
   102  }
   103  
   104  // TxSimulator simulates a transaction on a consistent snapshot of the 'as recent state as possible'
   105  // Set* methods are for supporting KV-based data model. ExecuteUpdate method is for supporting a rich datamodel and query support
   106  type TxSimulator interface {
   107  	QueryExecutor
   108  	// SetState sets the given value for the given namespace and key. For a chaincode, the namespace corresponds to the chaincodeId
   109  	SetState(namespace string, key string, value []byte) error
   110  	// DeleteState deletes the given namespace and key
   111  	DeleteState(namespace string, key string) error
   112  	// SetMultipleKeys sets the values for multiple keys in a single call
   113  	SetStateMultipleKeys(namespace string, kvs map[string][]byte) error
   114  	// ExecuteUpdate for supporting rich data model (see comments on QueryExecutor above)
   115  	ExecuteUpdate(query string) error
   116  	// GetTxSimulationResults encapsulates the results of the transaction simulation.
   117  	// This should contain enough detail for
   118  	// - The update in the state that would be caused if the transaction is to be committed
   119  	// - The environment in which the transaction is executed so as to be able to decide the validity of the enviroment
   120  	//   (at a later time on a different peer) during committing the transactions
   121  	// Different ledger implementation (or configurations of a single implementation) may want to represent the above two pieces
   122  	// of information in different way in order to support different data-models or optimize the information representations.
   123  	// TODO detailed illustration of a couple of representations.
   124  	GetTxSimulationResults() ([]byte, error)
   125  }
   126  
   127  // KV - QueryResult for KV-based datamodel. Holds a key and corresponding value. A nil value indicates a non-existent key.
   128  type KV struct {
   129  	Key   string
   130  	Value []byte
   131  }
   132  
   133  // KeyModification - QueryResult for History.
   134  type KeyModification struct {
   135  	TxID  string
   136  	Value []byte
   137  }
   138  
   139  // QueryRecord - Result structure for query records. Holds a namespace, key and record.
   140  // Only used for state databases that support query
   141  type QueryRecord struct {
   142  	Namespace string
   143  	Key       string
   144  	Record    []byte
   145  }