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 }