gae/service/datastore/raw_interface.go - infra/luci/luci-go - Git at Google

 // Copyright 2015 The LUCI Authors.
 //
 // 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 datastore

 import (
 	"context"
 	"fmt"
 )

 // Cursor wraps datastore.Cursor.
 type Cursor interface {
 	fmt.Stringer
 }

 // CursorCB is used to obtain a Cursor while Run'ing a query on either
 // Interface or RawInterface.
 //
 // it can be invoked to obtain the current cursor.
 type CursorCB func() (Cursor, error)

 // RawRunCB is the callback signature provided to RawInterface.Run
 //
 //   - key is the Key of the entity
 //   - val is the data of the entity (or nil, if the query was keys-only)
 //
 // Return nil to continue iterating through the query results, or an error to
 // stop. If you return the error `Stop`, then Run will stop the query and
 // return nil.
 type RawRunCB func(key *Key, val PropertyMap, getCursor CursorCB) error

 // GetMultiCB is the callback signature provided to RawInterface.GetMulti
 //
 //   - idx is the index of the entity, ranging from 0 through len-1.
 //   - val is the data of the entity
 //     * It may be nil if some of the keys to the GetMulti were bad, since all
 //       keys are validated before the RPC occurs!
 //   - err is an error associated with this entity (e.g. ErrNoSuchEntity).
 //
 // The callback is called once per element. It may be called concurrently, and
 // may be called out of order. The "idx" variable describes which element is
 // being processed. If any callbacks are invoked, exactly one callback will be
 // invoked for each supplied element.
 type GetMultiCB func(idx int, val PropertyMap, err error)

 // NewKeyCB is the callback signature provided to RawInterface.PutMulti and
 // RawInterface.AllocateIDs. It is invoked once for each positional key that
 // was generated as the result of a call.
 //
 //   - idx is the index of the entity, ranging from 0 through len-1.
 //   - key is the new key for the entity (if the original was incomplete)
 //     * It may be nil if some of the keys/vals to the PutMulti were bad, since
 //       all keys are validated before the RPC occurs!
 //   - err is an error associated with putting this entity.
 //
 // The callback is called once per element. It may be called concurrently, and
 // may be called out of order. The "idx" variable describes which element is
 // being processed. If any callbacks are invoked, exactly one callback will be
 // invoked for each supplied element.
 type NewKeyCB func(idx int, key *Key, err error)

 // DeleteMultiCB is the callback signature provided to RawInterface.DeleteMulti
 //
 //   - idx is the index of the entity, ranging from 0 through len-1.
 //   - err is an error associated with deleting this entity.
 //
 // The callback is called once per element. It may be called concurrently, and
 // may be called out of order. The "idx" variable describes which element is
 // being processed. If any callbacks are invoked, exactly one callback will be
 // invoked for each supplied element.
 type DeleteMultiCB func(idx int, err error)

 // Constraints represent implementation constraints.
 //
 // A zero-value Constraints is valid, and indicates that no constraints are
 // present.
 type Constraints struct {
 	// MaxGetSize is the maximum number of entities that can be referenced in a
 	// single GetMulti call. If <= 0, no constraint is applied.
 	MaxGetSize int
 	// MaxPutSize is the maximum number of entities that can be referenced in a
 	// single PutMulti call. If <= 0, no constraint is applied.
 	MaxPutSize int
 	// MaxDeleteSize is the maximum number of entities that can be referenced in a
 	// single DeleteMulti call. If <= 0, no constraint is applied.
 	MaxDeleteSize int
 }

 type nullMetaGetterType struct{}

 func (nullMetaGetterType) GetMeta(string) (interface{}, bool) { return nil, false }

 var nullMetaGetter MetaGetter = nullMetaGetterType{}

 // MultiMetaGetter is a carrier for metadata, used with RawInterface.GetMulti
 //
 // It's OK to default-construct this. GetMeta will just return
 // (nil, ErrMetaFieldUnset) for every index.
 type MultiMetaGetter []MetaGetter

 // NewMultiMetaGetter returns a new MultiMetaGetter object. data may be nil.
 func NewMultiMetaGetter(data []PropertyMap) MultiMetaGetter {
 	if len(data) == 0 {
 		return nil
 	}
 	inner := make(MultiMetaGetter, len(data))
 	for i, pm := range data {
 		inner[i] = pm
 	}
 	return inner
 }

 // GetMeta is like PropertyLoadSaver.GetMeta, but it also takes an index
 // indicating which slot you want metadata for. If idx isn't there, this
 // returns (nil, ErrMetaFieldUnset).
 func (m MultiMetaGetter) GetMeta(idx int, key string) (interface{}, bool) {
 	return m.GetSingle(idx).GetMeta(key)
 }

 // GetSingle gets a single MetaGetter at the specified index.
 func (m MultiMetaGetter) GetSingle(idx int) MetaGetter {
 	if idx >= len(m) || m[idx] == nil {
 		return nullMetaGetter
 	}
 	return m[idx]
 }

 // RawInterface implements the datastore functionality without any of the fancy
 // reflection stuff. This is so that Filters can avoid doing lots of redundant
 // reflection work. See datastore.Interface for a more user-friendly interface.
 type RawInterface interface {
 	// AllocateIDs allows you to allocate IDs from the datastore without putting
 	// any data. The supplied keys must be PartialValid and share the same entity
 	// type.
 	//
 	// If there's no error, the keys in the slice will be replaced with keys
 	// containing integer IDs assigned to them.
 	AllocateIDs(keys []*Key, cb NewKeyCB) error

 	// RunInTransaction runs f in a transaction.
 	//
 	// opts may be nil.
 	//
 	// NOTE: Implementations and filters are guaranteed that:
 	//   - f is not nil
 	RunInTransaction(f func(c context.Context) error, opts *TransactionOptions) error

 	// DecodeCursor converts a string returned by a Cursor into a Cursor instance.
 	// It will return an error if the supplied string is not valid, or could not
 	// be decoded by the implementation.
 	DecodeCursor(s string) (Cursor, error)

 	// Run executes the given query, and calls `cb` for each successfully item.
 	//
 	// NOTE: Implementations and filters are guaranteed that:
 	//   - query is not nil
 	//   - cb is not nil
 	Run(q *FinalizedQuery, cb RawRunCB) error

 	// Count executes the given query and returns the number of entries which
 	// match it.
 	Count(q *FinalizedQuery) (int64, error)

 	// GetMulti retrieves items from the datastore.
 	//
 	// If there was a server error, it will be returned directly. Otherwise,
 	// callback will execute once per key/value pair, returning either the
 	// operation result or individual error for each position. If the callback
 	// receives an error, it will immediately forward that error and stop
 	// subsequent callbacks.
 	//
 	// meta is used to propagate metadata from higher levels.
 	//
 	// NOTE: Implementations and filters are guaranteed that:
 	//   - len(keys) > 0
 	//   - all keys are Valid, !Incomplete, and in the current namespace
 	//   - cb is not nil
 	GetMulti(keys []*Key, meta MultiMetaGetter, cb GetMultiCB) error

 	// PutMulti writes items to the datastore.
 	//
 	// If there was a server error, it will be returned directly. Otherwise,
 	// callback will execute once per key/value pair, returning either the
 	// operation result or individual error for each position. If the callback
 	// receives an error, it will immediately forward that error and stop
 	// subsequent callbacks.
 	//
 	// NOTE: Implementations and filters are guaranteed that:
 	//   - len(keys) > 0
 	//   - len(keys) == len(vals)
 	//   - all keys are Valid and in the current namespace
 	//   - cb is not nil
 	PutMulti(keys []*Key, vals []PropertyMap, cb NewKeyCB) error

 	// DeleteMulti removes items from the datastore.
 	//
 	// If there was a server error, it will be returned directly. Otherwise,
 	// callback will execute once per key/value pair, returning either the
 	// operation result or individual error for each position. If the callback
 	// receives an error, it will immediately forward that error and stop
 	// subsequent callbacks.
 	//
 	// NOTE: Implementations and filters are guaranteed that
 	//   - len(keys) > 0
 	//   - all keys are Valid, !Incomplete, and in the current namespace
 	//   - none keys of the keys are 'special' (use a kind prefixed with '__')
 	//   - cb is not nil
 	DeleteMulti(keys []*Key, cb DeleteMultiCB) error

 	// WithoutTransaction returns a derived Context without a transaction applied.
 	// This may be called even when outside of a transaction, in which case the
 	// input Context is a valid return value.
 	WithoutTransaction() context.Context

 	// CurrentTransaction returns a reference to the current Transaction, or nil
 	// if the Context does not have a current Transaction.
 	CurrentTransaction() Transaction

 	// Constraints returns this implementation's constraints.
 	Constraints() Constraints

 	// GetTestable returns the Testable interface for the implementation, or nil
 	// if there is none.
 	GetTestable() Testable
 }
	// Copyright 2015 The LUCI Authors.
	//
	// 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 datastore

	import (
	"context"
	"fmt"
	)

	// Cursor wraps datastore.Cursor.
	type Cursor interface {
	fmt.Stringer
	}

	// CursorCB is used to obtain a Cursor while Run'ing a query on either
	// Interface or RawInterface.
	//
	// it can be invoked to obtain the current cursor.
	type CursorCB func() (Cursor, error)

	// RawRunCB is the callback signature provided to RawInterface.Run
	//
	// - key is the Key of the entity
	// - val is the data of the entity (or nil, if the query was keys-only)
	//
	// Return nil to continue iterating through the query results, or an error to
	// stop. If you return the error `Stop`, then Run will stop the query and
	// return nil.
	type RawRunCB func(key *Key, val PropertyMap, getCursor CursorCB) error

	// GetMultiCB is the callback signature provided to RawInterface.GetMulti
	//
	// - idx is the index of the entity, ranging from 0 through len-1.
	// - val is the data of the entity
	// * It may be nil if some of the keys to the GetMulti were bad, since all
	// keys are validated before the RPC occurs!
	// - err is an error associated with this entity (e.g. ErrNoSuchEntity).
	//
	// The callback is called once per element. It may be called concurrently, and
	// may be called out of order. The "idx" variable describes which element is
	// being processed. If any callbacks are invoked, exactly one callback will be
	// invoked for each supplied element.
	type GetMultiCB func(idx int, val PropertyMap, err error)

	// NewKeyCB is the callback signature provided to RawInterface.PutMulti and
	// RawInterface.AllocateIDs. It is invoked once for each positional key that
	// was generated as the result of a call.
	//
	// - idx is the index of the entity, ranging from 0 through len-1.
	// - key is the new key for the entity (if the original was incomplete)
	// * It may be nil if some of the keys/vals to the PutMulti were bad, since
	// all keys are validated before the RPC occurs!
	// - err is an error associated with putting this entity.
	//
	// The callback is called once per element. It may be called concurrently, and
	// may be called out of order. The "idx" variable describes which element is
	// being processed. If any callbacks are invoked, exactly one callback will be
	// invoked for each supplied element.
	type NewKeyCB func(idx int, key *Key, err error)

	// DeleteMultiCB is the callback signature provided to RawInterface.DeleteMulti
	//
	// - idx is the index of the entity, ranging from 0 through len-1.
	// - err is an error associated with deleting this entity.
	//
	// The callback is called once per element. It may be called concurrently, and
	// may be called out of order. The "idx" variable describes which element is
	// being processed. If any callbacks are invoked, exactly one callback will be
	// invoked for each supplied element.
	type DeleteMultiCB func(idx int, err error)

	// Constraints represent implementation constraints.
	//
	// A zero-value Constraints is valid, and indicates that no constraints are
	// present.
	type Constraints struct {
	// MaxGetSize is the maximum number of entities that can be referenced in a
	// single GetMulti call. If <= 0, no constraint is applied.
	MaxGetSize int
	// MaxPutSize is the maximum number of entities that can be referenced in a
	// single PutMulti call. If <= 0, no constraint is applied.
	MaxPutSize int
	// MaxDeleteSize is the maximum number of entities that can be referenced in a
	// single DeleteMulti call. If <= 0, no constraint is applied.
	MaxDeleteSize int
	}

	type nullMetaGetterType struct{}

	func (nullMetaGetterType) GetMeta(string) (interface{}, bool) { return nil, false }

	var nullMetaGetter MetaGetter = nullMetaGetterType{}

	// MultiMetaGetter is a carrier for metadata, used with RawInterface.GetMulti
	//
	// It's OK to default-construct this. GetMeta will just return
	// (nil, ErrMetaFieldUnset) for every index.
	type MultiMetaGetter []MetaGetter

	// NewMultiMetaGetter returns a new MultiMetaGetter object. data may be nil.
	func NewMultiMetaGetter(data []PropertyMap) MultiMetaGetter {
	if len(data) == 0 {
	return nil
	}
	inner := make(MultiMetaGetter, len(data))
	for i, pm := range data {
	inner[i] = pm
	}
	return inner
	}

	// GetMeta is like PropertyLoadSaver.GetMeta, but it also takes an index
	// indicating which slot you want metadata for. If idx isn't there, this
	// returns (nil, ErrMetaFieldUnset).
	func (m MultiMetaGetter) GetMeta(idx int, key string) (interface{}, bool) {
	return m.GetSingle(idx).GetMeta(key)
	}

	// GetSingle gets a single MetaGetter at the specified index.
	func (m MultiMetaGetter) GetSingle(idx int) MetaGetter {
	if idx >= len(m) \|\| m[idx] == nil {
	return nullMetaGetter
	}
	return m[idx]
	}

	// RawInterface implements the datastore functionality without any of the fancy
	// reflection stuff. This is so that Filters can avoid doing lots of redundant
	// reflection work. See datastore.Interface for a more user-friendly interface.
	type RawInterface interface {
	// AllocateIDs allows you to allocate IDs from the datastore without putting
	// any data. The supplied keys must be PartialValid and share the same entity
	// type.
	//
	// If there's no error, the keys in the slice will be replaced with keys
	// containing integer IDs assigned to them.
	AllocateIDs(keys []*Key, cb NewKeyCB) error

	// RunInTransaction runs f in a transaction.
	//
	// opts may be nil.
	//
	// NOTE: Implementations and filters are guaranteed that:
	// - f is not nil
	RunInTransaction(f func(c context.Context) error, opts *TransactionOptions) error

	// DecodeCursor converts a string returned by a Cursor into a Cursor instance.
	// It will return an error if the supplied string is not valid, or could not
	// be decoded by the implementation.
	DecodeCursor(s string) (Cursor, error)

	// Run executes the given query, and calls `cb` for each successfully item.
	//
	// NOTE: Implementations and filters are guaranteed that:
	// - query is not nil
	// - cb is not nil
	Run(q *FinalizedQuery, cb RawRunCB) error

	// Count executes the given query and returns the number of entries which
	// match it.
	Count(q *FinalizedQuery) (int64, error)

	// GetMulti retrieves items from the datastore.
	//
	// If there was a server error, it will be returned directly. Otherwise,
	// callback will execute once per key/value pair, returning either the
	// operation result or individual error for each position. If the callback
	// receives an error, it will immediately forward that error and stop
	// subsequent callbacks.
	//
	// meta is used to propagate metadata from higher levels.
	//
	// NOTE: Implementations and filters are guaranteed that:
	// - len(keys) > 0
	// - all keys are Valid, !Incomplete, and in the current namespace
	// - cb is not nil
	GetMulti(keys []*Key, meta MultiMetaGetter, cb GetMultiCB) error

	// PutMulti writes items to the datastore.
	//
	// If there was a server error, it will be returned directly. Otherwise,
	// callback will execute once per key/value pair, returning either the
	// operation result or individual error for each position. If the callback
	// receives an error, it will immediately forward that error and stop
	// subsequent callbacks.
	//
	// NOTE: Implementations and filters are guaranteed that:
	// - len(keys) > 0
	// - len(keys) == len(vals)
	// - all keys are Valid and in the current namespace
	// - cb is not nil
	PutMulti(keys []*Key, vals []PropertyMap, cb NewKeyCB) error

	// DeleteMulti removes items from the datastore.
	//
	// If there was a server error, it will be returned directly. Otherwise,
	// callback will execute once per key/value pair, returning either the
	// operation result or individual error for each position. If the callback
	// receives an error, it will immediately forward that error and stop
	// subsequent callbacks.
	//
	// NOTE: Implementations and filters are guaranteed that
	// - len(keys) > 0
	// - all keys are Valid, !Incomplete, and in the current namespace
	// - none keys of the keys are 'special' (use a kind prefixed with '__')
	// - cb is not nil
	DeleteMulti(keys []*Key, cb DeleteMultiCB) error

	// WithoutTransaction returns a derived Context without a transaction applied.
	// This may be called even when outside of a transaction, in which case the
	// input Context is a valid return value.
	WithoutTransaction() context.Context

	// CurrentTransaction returns a reference to the current Transaction, or nil
	// if the Context does not have a current Transaction.
	CurrentTransaction() Transaction

	// Constraints returns this implementation's constraints.
	Constraints() Constraints

	// GetTestable returns the Testable interface for the implementation, or nil
	// if there is none.
	GetTestable() Testable
	}