Permalink
Find file Copy path
7e6fd79 May 30, 2018
1 contributor

Users who have contributed to this file

267 lines (229 sloc) 11.5 KB
package datastore
import (
"context"
)
// FromContext provides default ClientGenerator.
// this variable will be injected by go.mercari.io/datastore/aedatastore or go.mercari.io/datastore/clouddatastore package's init function.
//
// Deprecated: use aedatastore.FromContext or clouddatastore.FromContext instead.
var FromContext ClientGenerator
// ClientGenerator represents the type of function for generating Client.
//
// Deprecated:
type ClientGenerator func(ctx context.Context, opts ...ClientOption) (Client, error)
// Client is a client for reading and writing data in a datastore dataset.
type Client interface {
// Get loads the entity stored for key into dst, which must be a struct pointer or implement PropertyLoadSaver.
//
// If there is no such entity for the key, Get returns ErrNoSuchEntity.
// The values of dst's unmatched struct fields are not modified, and matching slice-typed fields are not reset before appending to them.
// In particular, it is recommended to pass a pointer to a zero valued struct on each Get call.
//
// If you set false to SuppressErrFieldMismatch variable, act like the original Datastore.
// ErrFieldMismatch is returned when a field is to be loaded into a different type than the one it was stored from, or when a field is missing or unexported in the destination struct.
Get(ctx context.Context, key Key, dst interface{}) error
// GetMulti is a batch version of Get.
//
// dst must be a []S, []*S, []I or []P, for some struct type S, some interface type I, or some non-interface non-pointer type P such that P or *P implements PropertyLoadSaver.
// If an []I, each element must be a valid dst for Get: it must be a struct pointer or implement PropertyLoadSaver.
//
// As a special case, PropertyList is an invalid type for dst, even though a PropertyList is a slice of structs.
// It is treated as invalid to avoid being mistakenly passed when []PropertyList was intended.
GetMulti(ctx context.Context, keys []Key, dst interface{}) error
// Put saves the entity src into the datastore with key k.
// src must be a struct pointer or implement PropertyLoadSaver; if a struct pointer then any unexported fields of that struct will be skipped.
// If k is an incomplete key, the returned key will be a unique key generated by the datastore.
Put(ctx context.Context, key Key, src interface{}) (Key, error)
// PutMulti is a batch version of Put.
//
// src must satisfy the same conditions as the dst argument to GetMulti.
PutMulti(ctx context.Context, keys []Key, src interface{}) ([]Key, error)
// Delete deletes the entity for the given key.
Delete(ctx context.Context, key Key) error
// DeleteMulti is a batch version of Delete.
DeleteMulti(ctx context.Context, keys []Key) error
// NewTransaction starts a new transaction.
NewTransaction(ctx context.Context) (Transaction, error)
// RunInTransaction runs f in a transaction. f is invoked with a Transaction that f should use for all the transaction's datastore operations.
//
// f must not call Commit or Rollback on the provided Transaction.
//
// If f returns nil, RunInTransaction commits the transaction, returning the Commit and a nil error if it succeeds.
// If the commit fails due to a conflicting transaction, RunInTransaction gives up and returns ErrConcurrentTransaction immediately.
// If you want to retry operation, You have to retry by yourself.
//
// If f returns non-nil, then the transaction will be rolled back and RunInTransaction will return the same error.
//
// Note that when f returns, the transaction is not committed. Calling code must not assume that any of f's changes have been committed until RunInTransaction returns nil.
RunInTransaction(ctx context.Context, f func(tx Transaction) error) (Commit, error)
// Run runs the given query in the given context.
Run(ctx context.Context, q Query) Iterator
// AllocateIDs accepts a slice of incomplete keys and returns a slice of complete keys that are guaranteed to be valid in the datastore.
AllocateIDs(ctx context.Context, keys []Key) ([]Key, error)
// Count returns the number of results for the given query.
//
// The running time and number of API calls made by Count scale linearly with with the sum of the query's offset and limit.
// Unless the result count is expected to be small, it is best to specify a limit; otherwise Count will continue until it finishes counting or the provided context expires.
Count(ctx context.Context, q Query) (int, error)
// GetAll runs the provided query in the given context and returns all keys that match that query, as well as appending the values to dst.
//
// dst must have type *[]S or *[]*S or *[]P, for some struct type S or some non-interface, non-pointer type P such that P or *P implements PropertyLoadSaver.
//
// As a special case, *PropertyList is an invalid type for dst, even though a PropertyList is a slice of structs.
// It is treated as invalid to avoid being mistakenly passed when *[]PropertyList was intended.
//
// The keys returned by GetAll will be in a 1-1 correspondence with the entities added to dst.
//
// If q is a “keys-only” query, GetAll ignores dst and only returns the keys.
//
// The running time and number of API calls made by GetAll scale linearly with with the sum of the query's offset and limit.
// Unless the result count is expected to be small, it is best to specify a limit; otherwise GetAll will continue until it finishes collecting results or the provided context expires.
GetAll(ctx context.Context, q Query, dst interface{}) ([]Key, error)
// IncompleteKey creates a new incomplete key.
// The supplied kind cannot be empty.
// The namespace of the new key is empty.
IncompleteKey(kind string, parent Key) Key
// NameKey creates a new key with a name.
// The supplied kind cannot be empty.
// The supplied parent must either be a complete key or nil.
// The namespace of the new key is empty.
NameKey(kind, name string, parent Key) Key
// IDKey creates a new key with an ID.
// The supplied kind cannot be empty.
// The supplied parent must either be a complete key or nil.
// The namespace of the new key is empty.
IDKey(kind string, id int64, parent Key) Key
// NewQuery creates a new Query for a specific entity kind.
//
// An empty kind means to return all entities, including entities created and managed by other App Engine features, and is called a kindless query.
// Kindless queries cannot include filters or sort orders on property values.
NewQuery(kind string) Query
// Close closes the Client.
Close() error
// DecodeKey decodes a key from the opaque representation returned by Encode.
DecodeKey(encoded string) (Key, error)
// DecodeCursor from its base-64 string representation.
DecodeCursor(s string) (Cursor, error)
// Batch creates batch mode objects.
Batch() *Batch
// AppendMiddleware to client.
// Middleware will apply First-In First-Apply
AppendMiddleware(middleware Middleware)
// RemoveMiddleware from client.
RemoveMiddleware(middleware Middleware) bool
// Context returns this client's context.
Context() context.Context
// SetContext to this client.
SetContext(ctx context.Context)
}
// Key represents the datastore key for a stored entity.
type Key interface {
Kind() string
ID() int64
Name() string
ParentKey() Key
Namespace() string
SetNamespace(namespace string)
String() string
GobEncode() ([]byte, error)
GobDecode(buf []byte) error
MarshalJSON() ([]byte, error)
UnmarshalJSON(buf []byte) error
Encode() string
Equal(o Key) bool
Incomplete() bool
}
// PendingKey represents the key for newly-inserted entity. It can be
// resolved into a Key by calling the Key method of Commit.
type PendingKey interface {
StoredContext() context.Context
}
// Transaction represents a set of datastore operations to be committed atomically.
//
// Operations are enqueued by calling the Put and Delete methods on Transaction
// (or their Multi-equivalents). These operations are only committed when the
// Commit method is invoked. To ensure consistency, reads must be performed by
// using Transaction's Get method or by using the Transaction method when
// building a query.
//
// A Transaction must be committed or rolled back exactly once.
type Transaction interface {
// Get is the transaction-specific version of the package function Get.
// All reads performed during the transaction will come from a single consistent snapshot.
// Furthermore, if the transaction is set to a serializable isolation level,
// another transaction cannot concurrently modify the data that is read or modified by this transaction.
Get(key Key, dst interface{}) error
// GetMulti is a batch version of Get.
GetMulti(keys []Key, dst interface{}) error
// Put is the transaction-specific version of the package function Put.
//
// Put returns a PendingKey which can be resolved into a Key using the return value from a successful Commit.
// If key is an incomplete key, the returned pending key will resolve to a unique key generated by the datastore.
Put(key Key, src interface{}) (PendingKey, error)
// PutMulti is a batch version of Put. One PendingKey is returned for each element of src in the same order.
PutMulti(keys []Key, src interface{}) ([]PendingKey, error)
// Delete is the transaction-specific version of the package function Delete.
// Delete enqueues the deletion of the entity for the given key,
// to be committed atomically upon calling Commit.
Delete(key Key) error
// DeleteMulti is a batch version of Delete.
DeleteMulti(keys []Key) error
// Commit applies the enqueued operations atomically.
Commit() (Commit, error)
// Rollback abandons a pending transaction.
Rollback() error
Batch() *TransactionBatch
}
// Commit represents the result of a committed transaction.
type Commit interface {
Key(p PendingKey) Key
}
// GeoPoint represents a location as latitude/longitude in degrees.
type GeoPoint struct {
Lat, Lng float64
}
// Query represents a datastore query.
type Query interface {
Ancestor(ancestor Key) Query
EventualConsistency() Query
Namespace(ns string) Query
Transaction(t Transaction) Query
Filter(filterStr string, value interface{}) Query
Order(fieldName string) Query
Project(fieldNames ...string) Query
Distinct() Query
// NOT IMPLEMENTED ON APPENGINE DistinctOn(fieldNames ...string) *Query
KeysOnly() Query
Limit(limit int) Query
Offset(offset int) Query
Start(c Cursor) Query
End(c Cursor) Query
Dump() *QueryDump
}
// Iterator is the result of running a query.
type Iterator interface {
// Next returns the key of the next result. When there are no more results,
// iterator.Done is returned as the error.
//
// If the query is not keys only and dst is non-nil, it also loads the entity
// stored for that key into the struct pointer or PropertyLoadSaver dst, with
// the same semantics and possible errors as for the Get function.
Next(dst interface{}) (Key, error)
// Cursor returns a cursor for the iterator's current location.
Cursor() (Cursor, error)
}
// Cursor is an iterator's position. It can be converted to and from an opaque
// string. A cursor can be used from different HTTP requests, but only with a
// query with the same kind, ancestor, filter and order constraints.
//
// The zero Cursor can be used to indicate that there is no start and/or end
// constraint for a query.
type Cursor interface {
String() string
}
// PropertyTranslator is for converting the value of Property when saving and loading.
type PropertyTranslator interface {
ToPropertyValue(ctx context.Context) (interface{}, error)
FromPropertyValue(ctx context.Context, p Property) (dst interface{}, err error)
}
// TODO ComplexPropertyTranslator e.g. ToProperties(ctx context.Context) ([]Property, error)