diff options
Diffstat (limited to 'vendor/google.golang.org/appengine/datastore/doc.go')
| -rw-r--r-- | vendor/google.golang.org/appengine/datastore/doc.go | 361 |
1 files changed, 0 insertions, 361 deletions
diff --git a/vendor/google.golang.org/appengine/datastore/doc.go b/vendor/google.golang.org/appengine/datastore/doc.go deleted file mode 100644 index 85616cf..0000000 --- a/vendor/google.golang.org/appengine/datastore/doc.go +++ /dev/null @@ -1,361 +0,0 @@ -// Copyright 2011 Google Inc. All rights reserved. -// Use of this source code is governed by the Apache 2.0 -// license that can be found in the LICENSE file. - -/* -Package datastore provides a client for App Engine's datastore service. - - -Basic Operations - -Entities are the unit of storage and are associated with a key. A key -consists of an optional parent key, a string application ID, a string kind -(also known as an entity type), and either a StringID or an IntID. A -StringID is also known as an entity name or key name. - -It is valid to create a key with a zero StringID and a zero IntID; this is -called an incomplete key, and does not refer to any saved entity. Putting an -entity into the datastore under an incomplete key will cause a unique key -to be generated for that entity, with a non-zero IntID. - -An entity's contents are a mapping from case-sensitive field names to values. -Valid value types are: - - signed integers (int, int8, int16, int32 and int64), - - bool, - - string, - - float32 and float64, - - []byte (up to 1 megabyte in length), - - any type whose underlying type is one of the above predeclared types, - - ByteString, - - *Key, - - time.Time (stored with microsecond precision), - - appengine.BlobKey, - - appengine.GeoPoint, - - structs whose fields are all valid value types, - - slices of any of the above. - -Slices of structs are valid, as are structs that contain slices. However, if -one struct contains another, then at most one of those can be repeated. This -disqualifies recursively defined struct types: any struct T that (directly or -indirectly) contains a []T. - -The Get and Put functions load and save an entity's contents. An entity's -contents are typically represented by a struct pointer. - -Example code: - - type Entity struct { - Value string - } - - func handle(w http.ResponseWriter, r *http.Request) { - ctx := appengine.NewContext(r) - - k := datastore.NewKey(ctx, "Entity", "stringID", 0, nil) - e := new(Entity) - if err := datastore.Get(ctx, k, e); err != nil { - http.Error(w, err.Error(), 500) - return - } - - old := e.Value - e.Value = r.URL.Path - - if _, err := datastore.Put(ctx, k, e); err != nil { - http.Error(w, err.Error(), 500) - return - } - - w.Header().Set("Content-Type", "text/plain; charset=utf-8") - fmt.Fprintf(w, "old=%q\nnew=%q\n", old, e.Value) - } - -GetMulti, PutMulti and DeleteMulti are batch versions of the Get, Put and -Delete functions. They take a []*Key instead of a *Key, and may return an -appengine.MultiError when encountering partial failure. - - -Properties - -An entity's contents can be represented by a variety of types. These are -typically struct pointers, but can also be any type that implements the -PropertyLoadSaver interface. If using a struct pointer, you do not have to -explicitly implement the PropertyLoadSaver interface; the datastore will -automatically convert via reflection. If a struct pointer does implement that -interface then those methods will be used in preference to the default -behavior for struct pointers. Struct pointers are more strongly typed and are -easier to use; PropertyLoadSavers are more flexible. - -The actual types passed do not have to match between Get and Put calls or even -across different calls to datastore. It is valid to put a *PropertyList and -get that same entity as a *myStruct, or put a *myStruct0 and get a *myStruct1. -Conceptually, any entity is saved as a sequence of properties, and is loaded -into the destination value on a property-by-property basis. When loading into -a struct pointer, an entity that cannot be completely represented (such as a -missing field) will result in an ErrFieldMismatch error but it is up to the -caller whether this error is fatal, recoverable or ignorable. - -By default, for struct pointers, all properties are potentially indexed, and -the property name is the same as the field name (and hence must start with an -upper case letter). - -Fields may have a `datastore:"name,options"` tag. The tag name is the -property name, which must be one or more valid Go identifiers joined by ".", -but may start with a lower case letter. An empty tag name means to just use the -field name. A "-" tag name means that the datastore will ignore that field. - -The only valid options are "omitempty" and "noindex". - -If the options include "omitempty" and the value of the field is empty, then the field will be omitted on Save. -The empty values are false, 0, any nil interface value, and any array, slice, map, or string of length zero. -Struct field values will never be empty. - -If options include "noindex" then the field will not be indexed. All fields are indexed -by default. Strings or byte slices longer than 1500 bytes cannot be indexed; -fields used to store long strings and byte slices must be tagged with "noindex" -or they will cause Put operations to fail. - -To use multiple options together, separate them by a comma. -The order does not matter. - -If the options is "" then the comma may be omitted. - -Example code: - - // A and B are renamed to a and b. - // A, C and J are not indexed. - // D's tag is equivalent to having no tag at all (E). - // I is ignored entirely by the datastore. - // J has tag information for both the datastore and json packages. - type TaggedStruct struct { - A int `datastore:"a,noindex"` - B int `datastore:"b"` - C int `datastore:",noindex"` - D int `datastore:""` - E int - I int `datastore:"-"` - J int `datastore:",noindex" json:"j"` - } - - -Structured Properties - -If the struct pointed to contains other structs, then the nested or embedded -structs are flattened. For example, given these definitions: - - type Inner1 struct { - W int32 - X string - } - - type Inner2 struct { - Y float64 - } - - type Inner3 struct { - Z bool - } - - type Outer struct { - A int16 - I []Inner1 - J Inner2 - Inner3 - } - -then an Outer's properties would be equivalent to those of: - - type OuterEquivalent struct { - A int16 - IDotW []int32 `datastore:"I.W"` - IDotX []string `datastore:"I.X"` - JDotY float64 `datastore:"J.Y"` - Z bool - } - -If Outer's embedded Inner3 field was tagged as `datastore:"Foo"` then the -equivalent field would instead be: FooDotZ bool `datastore:"Foo.Z"`. - -If an outer struct is tagged "noindex" then all of its implicit flattened -fields are effectively "noindex". - - -The PropertyLoadSaver Interface - -An entity's contents can also be represented by any type that implements the -PropertyLoadSaver interface. This type may be a struct pointer, but it does -not have to be. The datastore package will call Load when getting the entity's -contents, and Save when putting the entity's contents. -Possible uses include deriving non-stored fields, verifying fields, or indexing -a field only if its value is positive. - -Example code: - - type CustomPropsExample struct { - I, J int - // Sum is not stored, but should always be equal to I + J. - Sum int `datastore:"-"` - } - - func (x *CustomPropsExample) Load(ps []datastore.Property) error { - // Load I and J as usual. - if err := datastore.LoadStruct(x, ps); err != nil { - return err - } - // Derive the Sum field. - x.Sum = x.I + x.J - return nil - } - - func (x *CustomPropsExample) Save() ([]datastore.Property, error) { - // Validate the Sum field. - if x.Sum != x.I + x.J { - return nil, errors.New("CustomPropsExample has inconsistent sum") - } - // Save I and J as usual. The code below is equivalent to calling - // "return datastore.SaveStruct(x)", but is done manually for - // demonstration purposes. - return []datastore.Property{ - { - Name: "I", - Value: int64(x.I), - }, - { - Name: "J", - Value: int64(x.J), - }, - }, nil - } - -The *PropertyList type implements PropertyLoadSaver, and can therefore hold an -arbitrary entity's contents. - - -Queries - -Queries retrieve entities based on their properties or key's ancestry. Running -a query yields an iterator of results: either keys or (key, entity) pairs. -Queries are re-usable and it is safe to call Query.Run from concurrent -goroutines. Iterators are not safe for concurrent use. - -Queries are immutable, and are either created by calling NewQuery, or derived -from an existing query by calling a method like Filter or Order that returns a -new query value. A query is typically constructed by calling NewQuery followed -by a chain of zero or more such methods. These methods are: - - Ancestor and Filter constrain the entities returned by running a query. - - Order affects the order in which they are returned. - - Project constrains the fields returned. - - Distinct de-duplicates projected entities. - - KeysOnly makes the iterator return only keys, not (key, entity) pairs. - - Start, End, Offset and Limit define which sub-sequence of matching entities - to return. Start and End take cursors, Offset and Limit take integers. Start - and Offset affect the first result, End and Limit affect the last result. - If both Start and Offset are set, then the offset is relative to Start. - If both End and Limit are set, then the earliest constraint wins. Limit is - relative to Start+Offset, not relative to End. As a special case, a - negative limit means unlimited. - -Example code: - - type Widget struct { - Description string - Price int - } - - func handle(w http.ResponseWriter, r *http.Request) { - ctx := appengine.NewContext(r) - q := datastore.NewQuery("Widget"). - Filter("Price <", 1000). - Order("-Price") - b := new(bytes.Buffer) - for t := q.Run(ctx); ; { - var x Widget - key, err := t.Next(&x) - if err == datastore.Done { - break - } - if err != nil { - serveError(ctx, w, err) - return - } - fmt.Fprintf(b, "Key=%v\nWidget=%#v\n\n", key, x) - } - w.Header().Set("Content-Type", "text/plain; charset=utf-8") - io.Copy(w, b) - } - - -Transactions - -RunInTransaction runs a function in a transaction. - -Example code: - - type Counter struct { - Count int - } - - func inc(ctx context.Context, key *datastore.Key) (int, error) { - var x Counter - if err := datastore.Get(ctx, key, &x); err != nil && err != datastore.ErrNoSuchEntity { - return 0, err - } - x.Count++ - if _, err := datastore.Put(ctx, key, &x); err != nil { - return 0, err - } - return x.Count, nil - } - - func handle(w http.ResponseWriter, r *http.Request) { - ctx := appengine.NewContext(r) - var count int - err := datastore.RunInTransaction(ctx, func(ctx context.Context) error { - var err1 error - count, err1 = inc(ctx, datastore.NewKey(ctx, "Counter", "singleton", 0, nil)) - return err1 - }, nil) - if err != nil { - serveError(ctx, w, err) - return - } - w.Header().Set("Content-Type", "text/plain; charset=utf-8") - fmt.Fprintf(w, "Count=%d", count) - } - - -Metadata - -The datastore package provides access to some of App Engine's datastore -metadata. This metadata includes information about the entity groups, -namespaces, entity kinds, and properties in the datastore, as well as the -property representations for each property. - -Example code: - - func handle(w http.ResponseWriter, r *http.Request) { - // Print all the kinds in the datastore, with all the indexed - // properties (and their representations) for each. - ctx := appengine.NewContext(r) - - kinds, err := datastore.Kinds(ctx) - if err != nil { - serveError(ctx, w, err) - return - } - - w.Header().Set("Content-Type", "text/plain; charset=utf-8") - for _, kind := range kinds { - fmt.Fprintf(w, "%s:\n", kind) - props, err := datastore.KindProperties(ctx, kind) - if err != nil { - fmt.Fprintln(w, "\t(unable to retrieve properties)") - continue - } - for p, rep := range props { - fmt.Fprintf(w, "\t-%s (%s)\n", p, strings.Join(rep, ", ")) - } - } - } -*/ -package datastore // import "google.golang.org/appengine/datastore" |