orm

package module
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 28, 2021 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package orm is a convenient object to data store mapper.

Index

Constants

View Source 
const EncodedSeqLength = 8

EncodedSeqLength number of bytes used for the binary representation of a sequence value.

View Source 
const MaxBytesLen = 255

MaxBytesLen is the maximum allowed length for a key part of type []byte

Variables

View Source 
var (
	ErrNotFound          = errors.Register(ormCodespace, 100, "not found")
	ErrIteratorDone      = errors.Register(ormCodespace, 101, "iterator done")
	ErrIteratorInvalid   = errors.Register(ormCodespace, 102, "iterator invalid")
	ErrType              = errors.Register(ormCodespace, 110, "invalid type")
	ErrUniqueConstraint  = errors.Register(ormCodespace, 111, "unique constraint violation")
	ErrArgument          = errors.Register(ormCodespace, 112, "invalid argument")
	ErrIndexKeyMaxLength = errors.Register(ormCodespace, 113, "index key exceeds max length")
	ErrEmptyKey          = errors.Register(ormCodespace, 114, "cannot use empty key")
)

Functions

func AddLengthPrefix 

func AddLengthPrefix(bytes []byte) []byte

AddLengthPrefix prefixes the byte array with its length as 8 bytes. The function will panic if the bytes length is bigger than 255.

func DecodeSequence 

func DecodeSequence(bz []byte) uint64

DecodeSequence converts the binary representation into an Uint64 value.

func EncodeSequence 

func EncodeSequence(val uint64) []byte

EncodeSequence converts the sequence value into the binary representation.

func NullTerminatedBytes 

func NullTerminatedBytes(s string) []byte

NullTerminatedBytes converts string to byte array and null terminate it

func Paginate 

func Paginate(
	it Iterator,
	pageRequest *query.PageRequest,
	dest ModelSlicePtr,
) (*query.PageResponse, error)

Paginate does pagination with a given Iterator based on the provided PageRequest and unmarshals the results into the dest interface that must be an non-nil pointer to a slice.

If pageRequest is nil, then we will use these default values:

  • Offset: 0
  • Key: nil
  • Limit: 100
  • CountTotal: true

If pageRequest.Key was provided, it got used beforehand to instantiate the Iterator, using for instance UInt64Index.GetPaginated method. Only one of pageRequest.Offset or pageRequest.Key should be set. Using pageRequest.Key is more efficient for querying the next page.

If pageRequest.CountTotal is set, we'll visit all iterators elements. pageRequest.CountTotal is only respected when offset is used.

This function will call it.Close().

func PrefixRange 

func PrefixRange(prefix []byte) ([]byte, []byte)

PrefixRange turns a prefix into a (start, end) range. The start is the given prefix value and the end is calculated by adding 1 bit to the start value. Nil is not allowed as prefix. 

Example: []byte{1, 3, 4} becomes []byte{1, 3, 5}
		 []byte{15, 42, 255, 255} becomes []byte{15, 43, 0, 0}

In case of an overflow the end is set to nil. 

Example: []byte{255, 255, 255, 255} becomes nil

func PrimaryKey 

func PrimaryKey(obj PrimaryKeyed) []byte

PrimaryKey returns the immutable and serialized primary key of this object. The primary key has to be unique within it's domain so that not two with same value can exist in the same table. This means PrimaryKeyFields() has to return a unique value for each object.

func TestTableBuilder 

func TestTableBuilder(prefixData byte, storeKey sdk.StoreKey, model codec.ProtoMarshaler, cdc codec.Codec) (*tableBuilder, error)

TestTableBuilder exposes the private tableBuilder type for testing purposes. It is not safe to use this outside of test code.

Types

type AfterDeleteInterceptor 

type AfterDeleteInterceptor func(ctx HasKVStore, rowID RowID, value codec.ProtoMarshaler) error

AfterDeleteInterceptor defines a callback function to be called on Delete operations.

type AfterSetInterceptor 

type AfterSetInterceptor func(ctx HasKVStore, rowID RowID, newValue, oldValue codec.ProtoMarshaler) error

AfterSetInterceptor defines a callback function to be called on Create + Update.

type AlwaysPanicKVStore 

type AlwaysPanicKVStore struct{}

func (AlwaysPanicKVStore) CacheWrap 

func (a AlwaysPanicKVStore) CacheWrap() types.CacheWrap

func (AlwaysPanicKVStore) CacheWrapWithTrace 

func (a AlwaysPanicKVStore) CacheWrapWithTrace(w io.Writer, tc types.TraceContext) types.CacheWrap

func (AlwaysPanicKVStore) Delete 

func (a AlwaysPanicKVStore) Delete(key []byte)

func (AlwaysPanicKVStore) Get 

func (a AlwaysPanicKVStore) Get(key []byte) []byte

func (AlwaysPanicKVStore) GetStoreType 

func (a AlwaysPanicKVStore) GetStoreType() types.StoreType

func (AlwaysPanicKVStore) Has 

func (a AlwaysPanicKVStore) Has(key []byte) bool

func (AlwaysPanicKVStore) Iterator 

func (a AlwaysPanicKVStore) Iterator(start, end []byte) types.Iterator

func (AlwaysPanicKVStore) ReverseIterator 

func (a AlwaysPanicKVStore) ReverseIterator(start, end []byte) types.Iterator

func (AlwaysPanicKVStore) Set 

func (a AlwaysPanicKVStore) Set(key, value []byte)

type AutoUInt64Table 

type AutoUInt64Table struct {
	// contains filtered or unexported fields
}

AutoUInt64Table is the table type which an auto incrementing ID.

func (AutoUInt64Table) Create 

func (a AutoUInt64Table) Create(ctx HasKVStore, obj codec.ProtoMarshaler) (uint64, error)

Create a new persistent object with an auto generated uint64 primary key. The key is returned.

Create iterates through the registered callbacks that may add secondary index keys.

func (AutoUInt64Table) Delete 

func (a AutoUInt64Table) Delete(ctx HasKVStore, rowID uint64) error

Delete removes the object under the rowID key. It expects the key to exists already and fails with a `ErrNotFound` otherwise. Any caller must therefore make sure that this contract is fulfilled.

Delete iterates through the registered callbacks that remove secondary index keys.

func (AutoUInt64Table) Export 

func (a AutoUInt64Table) Export(ctx HasKVStore, dest ModelSlicePtr) (uint64, error)

Export stores all the values in the table in the passed ModelSlicePtr and returns the current value of the associated sequence.

func (AutoUInt64Table) GetOne 

func (a AutoUInt64Table) GetOne(ctx HasKVStore, rowID uint64, dest codec.ProtoMarshaler) (RowID, error)

GetOne load the object persisted for the given RowID into the dest parameter. If none exists `ErrNotFound` is returned instead. Parameters must not be nil.

func (AutoUInt64Table) Has 

func (a AutoUInt64Table) Has(ctx HasKVStore, rowID uint64) bool

Has checks if a rowID exists.

func (AutoUInt64Table) Import 

func (a AutoUInt64Table) Import(ctx HasKVStore, data interface{}, seqValue uint64) error

Import clears the table and initializes it from the given data interface{}. data should be a slice of structs that implement PrimaryKeyed.

func (AutoUInt64Table) PrefixScan 

func (a AutoUInt64Table) PrefixScan(ctx HasKVStore, start, end uint64) (Iterator, error)

PrefixScan returns an Iterator over a domain of keys in ascending order. End is exclusive. Start is an MultiKeyIndex key or prefix. It must be less than end, or the Iterator is invalid and error is returned. Iterator must be closed by caller. To iterate over entire domain, use PrefixScan(nil, nil)

WARNING: The use of a PrefixScan can be very expensive in terms of Gas. Please make sure you do not expose this as an endpoint to the public without further limits. Example: 

it, err := idx.PrefixScan(ctx, start, end)
if err !=nil {
	return err
}
const defaultLimit = 20
it = LimitIterator(it, defaultLimit)

CONTRACT: No writes may happen within a domain while an iterator exists over it.

func (AutoUInt64Table) ReversePrefixScan 

func (a AutoUInt64Table) ReversePrefixScan(ctx HasKVStore, start uint64, end uint64) (Iterator, error)

ReversePrefixScan returns an Iterator over a domain of keys in descending order. End is exclusive. Start is an MultiKeyIndex key or prefix. It must be less than end, or the Iterator is invalid and error is returned. Iterator must be closed by caller. To iterate over entire domain, use PrefixScan(nil, nil)

WARNING: The use of a ReversePrefixScan can be very expensive in terms of Gas. Please make sure you do not expose this as an endpoint to the public without further limits. See `LimitIterator`

CONTRACT: No writes may happen within a domain while an iterator exists over it.

func (AutoUInt64Table) Sequence 

func (a AutoUInt64Table) Sequence() Sequence

Sequence returns the sequence used by this table

func (AutoUInt64Table) Set 

func (a AutoUInt64Table) Set(ctx HasKVStore, rowID uint64, newValue codec.ProtoMarshaler) error

Set persists the given object under the rowID key. It does not check if the key already exists and overwrites the value if it does.

Set iterates through the registered callbacks that may add secondary index keys.

func (AutoUInt64Table) Update 

func (a AutoUInt64Table) Update(ctx HasKVStore, rowID uint64, newValue codec.ProtoMarshaler) error

Update updates the given object under the rowID key. It expects the key to exists already and fails with an `ErrNotFound` otherwise. Any caller must therefore make sure that this contract is fulfilled. Parameters must not be nil.

Update iterates through the registered callbacks that may add or remove secondary index keys.

type AutoUInt64TableBuilder 

type AutoUInt64TableBuilder struct {
	// contains filtered or unexported fields
}

func NewAutoUInt64TableBuilder 

func NewAutoUInt64TableBuilder(prefixData byte, prefixSeq byte, storeKey sdk.StoreKey, model codec.ProtoMarshaler, cdc codec.Codec) (*AutoUInt64TableBuilder, error)

NewAutoUInt64TableBuilder creates a builder to setup a AutoUInt64Table object.

func (AutoUInt64TableBuilder) AddAfterDeleteInterceptor 

func (a AutoUInt64TableBuilder) AddAfterDeleteInterceptor(interceptor AfterDeleteInterceptor)

AddAfterDeleteInterceptor can be used to register a callback function that is executed after an object is deleted.

func (AutoUInt64TableBuilder) AddAfterSetInterceptor 

func (a AutoUInt64TableBuilder) AddAfterSetInterceptor(interceptor AfterSetInterceptor)

AddAfterSetInterceptor can be used to register a callback function that is executed after an object is created and/or updated.

func (AutoUInt64TableBuilder) Build 

func (a AutoUInt64TableBuilder) Build() AutoUInt64Table

Build create the AutoUInt64Table object.

func (AutoUInt64TableBuilder) RowGetter 

func (a AutoUInt64TableBuilder) RowGetter() RowGetter

RowGetter returns a type safe RowGetter.

func (AutoUInt64TableBuilder) StoreKey 

func (a AutoUInt64TableBuilder) StoreKey() sdk.StoreKey

type GasCountingMockContext 

type GasCountingMockContext struct {
	GasMeter sdk.GasMeter
	// contains filtered or unexported fields
}

func NewGasCountingMockContext 

func NewGasCountingMockContext(parent HasKVStore) *GasCountingMockContext

func (GasCountingMockContext) GasConsumed 

func (g GasCountingMockContext) GasConsumed() types.Gas

func (GasCountingMockContext) KVStore 

func (g GasCountingMockContext) KVStore(key sdk.StoreKey) sdk.KVStore

func (*GasCountingMockContext) ResetGasMeter 

func (g *GasCountingMockContext) ResetGasMeter()

type HasKVStore 

type HasKVStore interface {
	KVStore(key sdk.StoreKey) sdk.KVStore
}

HasKVStore is a subset of the cosmos-sdk context defined for loose coupling and simpler test setups.

type Index 

type Index interface {
	// Has checks if a key exists. Panics on nil key.
	Has(ctx HasKVStore, key interface{}) (bool, error)

	// Get returns a result iterator for the searchKey.
	// searchKey must not be nil.
	Get(ctx HasKVStore, searchKey interface{}) (Iterator, error)

	// GetPaginated returns a result iterator for the searchKey and optional pageRequest.
	// searchKey must not be nil.
	GetPaginated(ctx HasKVStore, searchKey interface{}, pageRequest *query.PageRequest) (Iterator, error)

	// PrefixScan returns an Iterator over a domain of keys in ascending order. End is exclusive.
	// Start is an MultiKeyIndex key or prefix. It must be less than end, or the Iterator is invalid and error is returned.
	// Iterator must be closed by caller.
	// To iterate over entire domain, use PrefixScan(nil, nil)
	//
	// WARNING: The use of a PrefixScan can be very expensive in terms of Gas. Please make sure you do not expose
	// this as an endpoint to the public without further limits.
	// Example:
	//			it, err := idx.PrefixScan(ctx, start, end)
	//			if err !=nil {
	//				return err
	//			}
	//			const defaultLimit = 20
	//			it = LimitIterator(it, defaultLimit)
	//
	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
	PrefixScan(ctx HasKVStore, startI interface{}, endI interface{}) (Iterator, error)

	// ReversePrefixScan returns an Iterator over a domain of keys in descending order. End is exclusive.
	// Start is an MultiKeyIndex key or prefix. It must be less than end, or the Iterator is invalid  and error is returned.
	// Iterator must be closed by caller.
	// To iterate over entire domain, use PrefixScan(nil, nil)
	//
	// WARNING: The use of a ReversePrefixScan can be very expensive in terms of Gas. Please make sure you do not expose
	// this as an endpoint to the public without further limits. See `LimitIterator`
	//
	// CONTRACT: No writes may happen within a domain while an iterator exists over it.
	ReversePrefixScan(ctx HasKVStore, startI interface{}, endI interface{}) (Iterator, error)
}

Index allows efficient prefix scans is stored as key = concat(indexKeyBytes, rowIDUint64) with value empty so that the row PrimaryKey is allows a fixed with 8 byte integer. This allows the MultiKeyIndex key bytes to be variable length and scanned iteratively.

type Indexable 

type Indexable interface {
	StoreKey() sdk.StoreKey
	RowGetter() RowGetter
	AddAfterSetInterceptor(interceptor AfterSetInterceptor)
	AddAfterDeleteInterceptor(interceptor AfterDeleteInterceptor)
}

Indexable types are used to setup new tables. This interface provides a set of functions that can be called by indexes to register and interact with the tables.

type Indexer 

type Indexer struct {
	// contains filtered or unexported fields
}

Indexer manages the persistence for an Index based on searchable keys and operations.

func NewIndexer 

func NewIndexer(indexerFunc IndexerFunc) (*Indexer, error)

NewIndexer returns an indexer that supports multiple reference keys for an entity.

func NewUniqueIndexer 

func NewUniqueIndexer(f UniqueIndexerFunc) (*Indexer, error)

NewUniqueIndexer returns an indexer that requires exactly one reference keys for an entity.

func (Indexer) IndexerFunc 

func (i Indexer) IndexerFunc() IndexerFunc

IndexerFunc returns the indexer IndexerFunc, ensuring it has been prune from empty keys.

func (Indexer) OnCreate 

func (i Indexer) OnCreate(store sdk.KVStore, rowID RowID, value interface{}) error

OnCreate persists the secondary index entries for the new object.

func (Indexer) OnDelete 

func (i Indexer) OnDelete(store sdk.KVStore, rowID RowID, value interface{}) error

OnDelete removes the secondary index entries for the deleted object.

func (Indexer) OnUpdate 

func (i Indexer) OnUpdate(store sdk.KVStore, rowID RowID, newValue, oldValue interface{}) error

OnUpdate rebuilds the secondary index entries for the updated object.

type IndexerFunc 

type IndexerFunc func(value interface{}) ([]interface{}, error)

IndexerFunc creates one or multiple index keys for the source object.

type Iterator 

type Iterator interface {
	// LoadNext loads the next value in the sequence into the pointer passed as dest and returns the key. If there
	// are no more items the ErrIteratorDone error is returned
	// The key is the rowID and not any MultiKeyIndex key.
	LoadNext(dest codec.ProtoMarshaler) (RowID, error)
	// Close releases the iterator and should be called at the end of iteration
	io.Closer
}

Iterator allows iteration through a sequence of key value pairs

func NewInvalidIterator 

func NewInvalidIterator() Iterator

Iterator that return ErrIteratorInvalid only.

func NewSingleValueIterator 

func NewSingleValueIterator(rowID RowID, val []byte) Iterator

type IteratorFunc 

type IteratorFunc func(dest codec.ProtoMarshaler) (RowID, error)

IteratorFunc is a function type that satisfies the Iterator interface The passed function is called on LoadNext operations.

func (IteratorFunc) Close 

func (i IteratorFunc) Close() error

Close always returns nil

func (IteratorFunc) LoadNext 

func (i IteratorFunc) LoadNext(dest codec.ProtoMarshaler) (RowID, error)

LoadNext loads the next value in the sequence into the pointer passed as dest and returns the key. If there are no more items the ErrIteratorDone error is returned The key is the rowID and not any MultiKeyIndex key.

type LimitedIterator 

type LimitedIterator struct {
	// contains filtered or unexported fields
}

LimitedIterator returns up to defined maximum number of elements.

func LimitIterator 

func LimitIterator(parent Iterator, max int) (*LimitedIterator, error)

LimitIterator returns a new iterator that returns max number of elements. The parent iterator must not be nil max can be 0 or any positive number

func (LimitedIterator) Close 

func (i LimitedIterator) Close() error

Close releases the iterator and should be called at the end of iteration

func (*LimitedIterator) LoadNext 

func (i *LimitedIterator) LoadNext(dest codec.ProtoMarshaler) (RowID, error)

LoadNext loads the next value in the sequence into the pointer passed as dest and returns the key. If there are no more items or the defined max number of elements was returned the `ErrIteratorDone` error is returned The key is the rowID and not any MultiKeyIndex key.

type MockContext 

type MockContext struct {
	// contains filtered or unexported fields
}

func NewMockContext 

func NewMockContext() *MockContext

func (MockContext) KVStore 

func (m MockContext) KVStore(key sdk.StoreKey) sdk.KVStore

type ModelSlicePtr 

type ModelSlicePtr interface{}

ModelSlicePtr represents a pointer to a slice of models. Think of it as *[]Model Because of Go's type system, using []Model type would not work for us. Instead we use a placeholder type and the validation is done during the runtime.

type MultiKeyIndex 

type MultiKeyIndex struct {
	// contains filtered or unexported fields
}

MultiKeyIndex is an index where multiple entries can point to the same underlying object as opposite to a unique index where only one entry is allowed.

func NewIndex 

func NewIndex(builder Indexable, prefix byte, indexerF IndexerFunc, indexKey interface{}) (MultiKeyIndex, error)

NewIndex builds a MultiKeyIndex. Only single-field indexes are supported and `indexKey` represents such a field value, which can be []byte, string or uint64.

func (MultiKeyIndex) Get 

func (i MultiKeyIndex) Get(ctx HasKVStore, searchKey interface{}) (Iterator, error)

Get returns a result iterator for the searchKey. Parameters must not be nil.

func (MultiKeyIndex) GetPaginated 

func (i MultiKeyIndex) GetPaginated(ctx HasKVStore, searchKey interface{}, pageRequest *query.PageRequest) (Iterator, error)

GetPaginated creates an iterator for the searchKey starting from pageRequest.Key if provided. The pageRequest.Key is the rowID while searchKey is a MultiKeyIndex key.

func (MultiKeyIndex) Has 

func (i MultiKeyIndex) Has(ctx HasKVStore, key interface{}) (bool, error)

Has checks if a key exists. Returns an error on nil key.

func (MultiKeyIndex) PrefixScan 

func (i MultiKeyIndex) PrefixScan(ctx HasKVStore, startI interface{}, endI interface{}) (Iterator, error)

PrefixScan returns an Iterator over a domain of keys in ascending order. End is exclusive. Start is an MultiKeyIndex key or prefix. It must be less than end, or the Iterator is invalid and error is returned. Iterator must be closed by caller. To iterate over entire domain, use PrefixScan(nil, nil)

WARNING: The use of a PrefixScan can be very expensive in terms of Gas. Please make sure you do not expose this as an endpoint to the public without further limits. Example: 

it, err := idx.PrefixScan(ctx, start, end)
if err !=nil {
	return err
}
const defaultLimit = 20
it = LimitIterator(it, defaultLimit)

CONTRACT: No writes may happen within a domain while an iterator exists over it.

func (MultiKeyIndex) ReversePrefixScan 

func (i MultiKeyIndex) ReversePrefixScan(ctx HasKVStore, startI interface{}, endI interface{}) (Iterator, error)

ReversePrefixScan returns an Iterator over a domain of keys in descending order. End is exclusive. Start is an MultiKeyIndex key or prefix. It must be less than end, or the Iterator is invalid and error is returned. Iterator must be closed by caller. To iterate over entire domain, use PrefixScan(nil, nil)

WARNING: The use of a ReversePrefixScan can be very expensive in terms of Gas. Please make sure you do not expose this as an endpoint to the public without further limits. See `LimitIterator`

CONTRACT: No writes may happen within a domain while an iterator exists over it.

type Persistent 

type Persistent interface {
	// Marshal serializes object into binary representation
	Marshal() ([]byte, error)
	// Unmarshal deserializes the object from the binary representation
	Unmarshal([]byte) error
}

Persistent supports Marshal and Unmarshal

This is separated from Marshal, as this almost always requires a pointer, and functions that only need to marshal bytes can use the Marshaller interface to access non-pointers.

As with Marshaller, this may do internal validation on the data and errors should be expected.

type PrimaryKeyTable 

type PrimaryKeyTable struct {
	// contains filtered or unexported fields
}

PrimaryKeyTable provides simpler object style orm methods without passing database RowIDs. Entries are persisted and loaded with a reference to their unique primary key.

func (PrimaryKeyTable) Contains 

func (a PrimaryKeyTable) Contains(ctx HasKVStore, obj PrimaryKeyed) bool

Contains returns true when an object with same type and primary key is persisted in this table.

func (PrimaryKeyTable) Create 

func (a PrimaryKeyTable) Create(ctx HasKVStore, obj PrimaryKeyed) error

Create persists the given object under their primary key. It checks if the key already exists and may return an `ErrUniqueConstraint`.

Create iterates through the registered callbacks that may add secondary index keys.

func (PrimaryKeyTable) Delete 

func (a PrimaryKeyTable) Delete(ctx HasKVStore, obj PrimaryKeyed) error

Delete removes the object. It expects the primary key to exists already and fails with a `ErrNotFound` otherwise. Any caller must therefore make sure that this contract is fulfilled.

Delete iterates through the registered callbacks that remove secondary index keys.

func (PrimaryKeyTable) Export 

func (a PrimaryKeyTable) Export(ctx HasKVStore, dest ModelSlicePtr) (uint64, error)

Export stores all the values in the table in the passed ModelSlicePtr.

func (PrimaryKeyTable) GetOne 

func (a PrimaryKeyTable) GetOne(ctx HasKVStore, primKey RowID, dest codec.ProtoMarshaler) error

GetOne load the object persisted for the given primary Key into the dest parameter. If none exists `ErrNotFound` is returned instead. Parameters must not be nil.

func (PrimaryKeyTable) Has 

func (a PrimaryKeyTable) Has(ctx HasKVStore, primaryKey RowID) bool

Has checks if a key exists. Panics on nil key.

func (PrimaryKeyTable) Import 

func (a PrimaryKeyTable) Import(ctx HasKVStore, data interface{}, seqValue uint64) error

Import clears the table and initializes it from the given data interface{}. data should be a slice of structs that implement PrimaryKeyed.

func (PrimaryKeyTable) PrefixScan 

func (a PrimaryKeyTable) PrefixScan(ctx HasKVStore, start, end []byte) (Iterator, error)

PrefixScan returns an Iterator over a domain of keys in ascending order. End is exclusive. Start is an MultiKeyIndex key or prefix. It must be less than end, or the Iterator is invalid and error is returned. Iterator must be closed by caller. To iterate over entire domain, use PrefixScan(nil, nil)

WARNING: The use of a PrefixScan can be very expensive in terms of Gas. Please make sure you do not expose this as an endpoint to the public without further limits. Example: 

it, err := idx.PrefixScan(ctx, start, end)
if err !=nil {
	return err
}
const defaultLimit = 20
it = LimitIterator(it, defaultLimit)

CONTRACT: No writes may happen within a domain while an iterator exists over it.

func (PrimaryKeyTable) ReversePrefixScan 

func (a PrimaryKeyTable) ReversePrefixScan(ctx HasKVStore, start, end []byte) (Iterator, error)

ReversePrefixScan returns an Iterator over a domain of keys in descending order. End is exclusive. Start is an MultiKeyIndex key or prefix. It must be less than end, or the Iterator is invalid and error is returned. Iterator must be closed by caller. To iterate over entire domain, use PrefixScan(nil, nil)

WARNING: The use of a ReversePrefixScan can be very expensive in terms of Gas. Please make sure you do not expose this as an endpoint to the public without further limits. See `LimitIterator`

CONTRACT: No writes may happen within a domain while an iterator exists over it.

func (PrimaryKeyTable) Set 

func (a PrimaryKeyTable) Set(ctx HasKVStore, newValue PrimaryKeyed) error

Set persists the given object under the rowID key. It does not check if the key already exists and overwrites the value if it does.

Set iterates through the registered callbacks that may add secondary index keys.

func (PrimaryKeyTable) Update 

func (a PrimaryKeyTable) Update(ctx HasKVStore, newValue PrimaryKeyed) error

Update updates the given object under the primary key. It expects the key to exists already and fails with an `ErrNotFound` otherwise. Any caller must therefore make sure that this contract is fulfilled. Parameters must not be nil.

Update iterates through the registered callbacks that may add or remove secondary index keys.

type PrimaryKeyTableBuilder 

type PrimaryKeyTableBuilder struct {
	// contains filtered or unexported fields
}

func NewPrimaryKeyTableBuilder 

func NewPrimaryKeyTableBuilder(prefixData byte, storeKey sdk.StoreKey, model PrimaryKeyed, cdc codec.Codec) (*PrimaryKeyTableBuilder, error)

NewPrimaryKeyTableBuilder creates a builder to setup a PrimaryKeyTable object.

func (PrimaryKeyTableBuilder) AddAfterDeleteInterceptor 

func (a PrimaryKeyTableBuilder) AddAfterDeleteInterceptor(interceptor AfterDeleteInterceptor)

AddAfterDeleteInterceptor can be used to register a callback function that is executed after an object is deleted.

func (PrimaryKeyTableBuilder) AddAfterSetInterceptor 

func (a PrimaryKeyTableBuilder) AddAfterSetInterceptor(interceptor AfterSetInterceptor)

AddAfterSetInterceptor can be used to register a callback function that is executed after an object is created and/or updated.

func (PrimaryKeyTableBuilder) Build 

func (a PrimaryKeyTableBuilder) Build() PrimaryKeyTable

func (PrimaryKeyTableBuilder) RowGetter 

func (a PrimaryKeyTableBuilder) RowGetter() RowGetter

RowGetter returns a type safe RowGetter.

func (PrimaryKeyTableBuilder) StoreKey 

func (a PrimaryKeyTableBuilder) StoreKey() sdk.StoreKey

type PrimaryKeyed 

type PrimaryKeyed interface {
	// PrimaryKeyFields returns the fields of the object that will make up
	// the primary key. The PrimaryKey function will encode and concatenate
	// the fields to build the primary key.
	//
	// PrimaryKey parts can be []byte, string, and integer types. []byte is
	// encoded with a length prefix, strings are null-terminated, and
	// integers are encoded using 8 byte big endian.
	//
	// IMPORTANT: []byte parts are encoded with a single byte length prefix,
	// so cannot be longer than 255 bytes.
	PrimaryKeyFields() []interface{}
	codec.ProtoMarshaler
}

PrimaryKeyed defines an object type that is aware of its immutable primary key.

type RowGetter 

type RowGetter func(ctx HasKVStore, rowID RowID, dest codec.ProtoMarshaler) error

RowGetter loads a persistent object by row ID into the destination object. The dest parameter must therefore be a pointer. Any implementation must return `ErrNotFound` when no object for the rowID exists

func NewTypeSafeRowGetter 

func NewTypeSafeRowGetter(storeKey sdk.StoreKey, prefixKey byte, model reflect.Type, cdc codec.Codec) RowGetter

NewTypeSafeRowGetter returns a `RowGetter` with type check on the dest parameter.

type RowID 

type RowID []byte

Unique identifier of a persistent table.

func First 

func First(it Iterator, dest codec.ProtoMarshaler) (RowID, error)

First loads the first element into the given destination type and closes the iterator. When the iterator is closed or has no elements the according error is passed as return value.

func ReadAll 

func ReadAll(it Iterator, dest ModelSlicePtr) ([]RowID, error)

ReadAll consumes all values for the iterator and stores them in a new slice at the passed ModelSlicePtr. The slice can be empty when the iterator does not return any values but not nil. The iterator is closed afterwards. Example: 

var loaded []testdata.GroupInfo
rowIDs, err := ReadAll(it, &loaded)
require.NoError(t, err)

func (RowID) Bytes 

func (r RowID) Bytes() []byte

Bytes returns raw bytes.

type Sequence 

type Sequence struct {
	// contains filtered or unexported fields
}

sequence is a persistent unique key generator based on a counter.

func NewSequence 

func NewSequence(storeKey sdk.StoreKey, prefix byte) Sequence

func (Sequence) CurVal 

func (s Sequence) CurVal(ctx HasKVStore) uint64

CurVal returns the last value used. 0 if none.

func (Sequence) InitVal 

func (s Sequence) InitVal(ctx HasKVStore, seq uint64) error

InitVal sets the start value for the sequence. It must be called only once on an empty DB. Otherwise an error is returned when the key exists. The given start value is stored as current value.

It is recommended to call this method only for a sequence start value other than `1` as the method consumes unnecessary gas otherwise. A scenario would be an import from genesis.

func (Sequence) NextVal 

func (s Sequence) NextVal(ctx HasKVStore) uint64

NextVal increments and persists the counter by one and returns the value.

func (Sequence) PeekNextVal 

func (s Sequence) PeekNextVal(ctx HasKVStore) uint64

PeekNextVal returns the CurVal + increment step. Not persistent.

type TableExportable 

type TableExportable interface {
	// Export stores all the values in the table in the passed
	// ModelSlicePtr. If the table has an associated sequence, then its
	// current value is returned, otherwise 0 is returned by default.
	Export(HasKVStore, ModelSlicePtr) (uint64, error)

	// Import clears the table and initializes it from the given data
	// interface{}. data should be a slice of structs that implement
	// PrimaryKeyed (eg []*GroupInfo). The seqValue is optional and only
	// used with tables that have an associated sequence.
	Import(HasKVStore, interface{}, uint64) error
}

TableExportable

type UniqueIndex 

type UniqueIndex struct {
	MultiKeyIndex
}

func NewUniqueIndex 

func NewUniqueIndex(builder Indexable, prefix byte, uniqueIndexerFunc UniqueIndexerFunc, indexKey interface{}) (UniqueIndex, error)

NewUniqueIndex create a new Index object where duplicate keys are prohibited.

type UniqueIndexerFunc 

type UniqueIndexerFunc func(value interface{}) (interface{}, error)

IndexerFunc creates exactly one index key for the source object.

type Validateable 

type Validateable interface {
	// ValidateBasic is a sanity check on the data. Any error returned prevents create or updates.
	ValidateBasic() error
}

Validateable is an interface that Persistent types can implement and is called on any orm set operation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.