ledger_interface.go 6.58 KB
Newer Older
manish's avatar
manish committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
/*
Copyright IBM Corp. 2016 All Rights Reserved.

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 ledger

import (
20
	commonledger "github.com/hyperledger/fabric/common/ledger"
21
	"github.com/hyperledger/fabric/protos/common"
manish's avatar
manish committed
22
23
)

24
25
// PeerLedgerProvider provides handle to ledger instances
type PeerLedgerProvider interface {
manish's avatar
manish committed
26
	// Create creates a new ledger with a given unique id
27
	Create(ledgerID string) (PeerLedger, error)
manish's avatar
manish committed
28
	// Open opens an already created ledger
29
	Open(ledgerID string) (PeerLedger, error)
30
31
32
33
	// Exists tells whether the ledger with given id exits
	Exists(ledgerID string) (bool, error)
	// List lists the ids of the existing ledgers
	List() ([]string, error)
34
	// Close closes the PeerLedgerProvider
35
36
37
	Close()
}

38
39
40
// PeerLedger differs from the OrdererLedger in that PeerLedger locally maintain a bitmask
// that tells apart valid transactions from invalid ones
type PeerLedger interface {
41
	commonledger.Ledger
manish's avatar
manish committed
42
	// GetTransactionByID retrieves a transaction by id
43
	GetTransactionByID(txID string) (*common.Envelope, error)
manish's avatar
manish committed
44
	// GetBlockByHash returns a block given it's hash
45
	GetBlockByHash(blockHash []byte) (*common.Block, error)
manish's avatar
manish committed
46
47
48
49
	// NewTxSimulator gives handle to a transaction simulator.
	// A client can obtain more than one 'TxSimulator's for parallel execution.
	// Any snapshoting/synchronization should be performed at the implementation level if required
	NewTxSimulator() (TxSimulator, error)
50
	// NewQueryExecutor gives handle to a query executor.
manish's avatar
manish committed
51
52
53
	// A client can obtain more than one 'QueryExecutor's for parallel execution.
	// Any synchronization should be performed at the implementation level if required
	NewQueryExecutor() (QueryExecutor, error)
54
55
56
57
	// NewHistoryQueryExecutor gives handle to a history query executor.
	// A client can obtain more than one 'HistoryQueryExecutor's for parallel execution.
	// Any synchronization should be performed at the implementation level if required
	NewHistoryQueryExecutor() (HistoryQueryExecutor, error)
58
	//Prune prunes the blocks/transactions that satisfy the given policy
59
	Prune(policy commonledger.PrunePolicy) error
60
61
62
63
64
}

// ValidatedLedger represents the 'final ledger' after filtering out invalid transactions from PeerLedger.
// Post-v1
type ValidatedLedger interface {
65
	commonledger.Ledger
manish's avatar
manish committed
66
67
68
69
70
71
72
73
74
75
76
77
}

// QueryExecutor executes the queries
// Get* methods are for supporting KV-based data model. ExecuteQuery method is for supporting a rich datamodel and query support
//
// ExecuteQuery method in the case of a rich data model is expected to support queries on
// latest state, historical state and on the intersection of state and transactions
type QueryExecutor interface {
	// GetState gets the value for given namespace and key. For a chaincode, the namespace corresponds to the chaincodeId
	GetState(namespace string, key string) ([]byte, error)
	// GetStateMultipleKeys gets the values for multiple keys in a single call
	GetStateMultipleKeys(namespace string, keys []string) ([][]byte, error)
manish's avatar
manish committed
78
	// GetStateRangeScanIterator returns an iterator that contains all the key-values between given key ranges.
79
80
81
	// 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 shuold be used judiciously for performance reasons.
manish's avatar
manish committed
82
	// The returned ResultsIterator contains results of type *KV
83
	GetStateRangeScanIterator(namespace string, startKey string, endKey string) (commonledger.ResultsIterator, error)
manish's avatar
manish committed
84
	// ExecuteQuery executes the given query and returns an iterator that contains results of type specific to the underlying data store.
85
	// Only used for state databases that support query
86
	ExecuteQuery(query string) (commonledger.ResultsIterator, error)
manish's avatar
manish committed
87
88
	// Done releases resources occupied by the QueryExecutor
	Done()
manish's avatar
manish committed
89
90
}

91
92
// HistoryQueryExecutor executes the history queries
type HistoryQueryExecutor interface {
93
	// GetHistoryForKey retrieves the history of values for a key.
94
	GetHistoryForKey(namespace string, key string) (commonledger.ResultsIterator, error)
95
96
}

manish's avatar
manish committed
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
// TxSimulator simulates a transaction on a consistent snapshot of the 'as recent state as possible'
// Set* methods are for supporting KV-based data model. ExecuteUpdate method is for supporting a rich datamodel and query support
type TxSimulator interface {
	QueryExecutor
	// SetState sets the given value for the given namespace and key. For a chaincode, the namespace corresponds to the chaincodeId
	SetState(namespace string, key string, value []byte) error
	// DeleteState deletes the given namespace and key
	DeleteState(namespace string, key string) error
	// SetMultipleKeys sets the values for multiple keys in a single call
	SetStateMultipleKeys(namespace string, kvs map[string][]byte) error
	// ExecuteUpdate for supporting rich data model (see comments on QueryExecutor above)
	ExecuteUpdate(query string) error
	// GetTxSimulationResults encapsulates the results of the transaction simulation.
	// This should contain enough detail for
	// - The update in the state that would be caused if the transaction is to be committed
	// - The environment in which the transaction is executed so as to be able to decide the validity of the enviroment
	//   (at a later time on a different peer) during committing the transactions
	// Different ledger implementation (or configurations of a single implementation) may want to represent the above two pieces
	// of information in different way in order to support different data-models or optimize the information representations.
	// TODO detailed illustration of a couple of representations.
	GetTxSimulationResults() ([]byte, error)
}

// KV - QueryResult for KV-based datamodel. Holds a key and corresponding value. A nil value indicates a non-existent key.
type KV struct {
	Key   string
	Value []byte
}

126
127
// KeyModification - QueryResult for History.
type KeyModification struct {
128
129
	TxID  string
	Value []byte
130
131
}

132
133
134
135
136
137
138
// QueryRecord - Result structure for query records. Holds a namespace, key and record.
// Only used for state databases that support query
type QueryRecord struct {
	Namespace string
	Key       string
	Record    []byte
}