OLD | NEW |
1 // Copyright 2015 The Chromium Authors. All rights reserved. | 1 // Copyright 2015 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 package datastore | 5 package datastore |
6 | 6 |
7 import ( | 7 import ( |
8 "fmt" | 8 "fmt" |
9 "reflect" | 9 "reflect" |
10 ) | 10 ) |
11 | 11 |
12 // GetPLS resolves obj into default struct PropertyLoadSaver and | 12 // GetPLS resolves obj into default struct PropertyLoadSaver and |
13 // MetaGetterSetter implementation. | 13 // MetaGetterSetter implementation. |
14 // | 14 // |
15 // obj must be a non-nil pointer to a struct of some sort. | 15 // obj must be a non-nil pointer to a struct of some sort. |
16 // | 16 // |
17 // By default, exported fields will be serialized to/from the datastore. If the | 17 // By default, exported fields will be serialized to/from the datastore. If the |
18 // field is not exported, it will be skipped by the serialization routines. | 18 // field is not exported, it will be skipped by the serialization routines. |
19 // | 19 // |
20 // If a field is of a non-supported type (see Property for the list of supported | 20 // If a field is of a non-supported type (see Property for the list of supported |
21 // property types), this function will panic. Other problems include duplicate | 21 // property types), this function will panic. Other problems include duplicate |
22 // field names (due to tagging), recursively defined structs, nested structures | 22 // field names (due to tagging), recursively defined structs, nested structures |
23 // with multiple slices (e.g. slices of slices, either directly `[][]type` or | 23 // with multiple slices (e.g. slices of slices, either directly `[][]type` or |
24 // indirectly `[]Embedded` where Embedded contains a slice.) | 24 // indirectly `[]Embedded` where Embedded contains a slice.) |
25 // | 25 // |
| 26 // The following field types are supported: |
| 27 // * int64, int32, int16, int8, int |
| 28 // * uint32, uint16, uint8, byte |
| 29 // * float64, float32 |
| 30 // * string |
| 31 // * []byte |
| 32 // * bool |
| 33 // * time.Time |
| 34 // * GeoPoint |
| 35 // * *Key |
| 36 // * any Type whose underlying type is one of the above types |
| 37 // * Types which implement PropertyConverter on (*Type) |
| 38 // * A struct composed of the above types (except for nested slices) |
| 39 // * A slice of any of the above types |
| 40 // |
26 // GetPLS supports the following struct tag syntax: | 41 // GetPLS supports the following struct tag syntax: |
27 // `gae:"fieldName[,noindex]"` -- an alternate fieldname for an exportable | 42 // `gae:"fieldName[,noindex]"` -- an alternate fieldname for an exportable |
28 // field. When the struct is serialized or deserialized, fieldName will be | 43 // field. When the struct is serialized or deserialized, fieldName will be |
29 // associated with the struct field instead of the field's Go name. This is | 44 // associated with the struct field instead of the field's Go name. This is |
30 // useful when writing Go code which interfaces with appengine code written | 45 // useful when writing Go code which interfaces with appengine code written |
31 // in other languages (like python) which use lowercase as their default | 46 // in other languages (like python) which use lowercase as their default |
32 // datastore field names. | 47 // datastore field names. |
33 // | 48 // |
34 // A fieldName of "-" means that gae will ignore the field for all | 49 // A fieldName of "-" means that gae will ignore the field for all |
35 // serialization/deserialization. | 50 // serialization/deserialization. |
36 // | 51 // |
37 // if noindex is specified, then this field will not be indexed in the | 52 // if noindex is specified, then this field will not be indexed in the |
38 // datastore, even if it was an otherwise indexable type. If fieldName is | 53 // datastore, even if it was an otherwise indexable type. If fieldName is |
39 // blank, and noindex is specifed, then fieldName will default to the | 54 // blank, and noindex is specifed, then fieldName will default to the |
40 // field's actual name. Note that by default, all fields (with indexable | 55 // field's actual name. Note that by default, all fields (with indexable |
41 // types) are indexed. | 56 // types) are indexed. |
42 // | 57 // |
43 // `gae:"$metaKey[,<value>]` -- indicates a field is metadata. Metadata | 58 // `gae:"$metaKey[,<value>]` -- indicates a field is metadata. Metadata |
44 // can be used to control filter behavior, or to store key data when using | 59 // can be used to control filter behavior, or to store key data when using |
45 // the Interface.KeyForObj* methods. The supported field types are: | 60 // the Interface.KeyForObj* methods. The supported field types are: |
46 // - Key | 61 // - *Key |
47 // - int64 | 62 // - int64, int32, int16, int8, uint32, uint16, uint8, byte |
48 // - string | 63 // - string |
49 // - Toggle (GetMeta and SetMeta treat the field as if it were bool) | 64 // - Toggle (GetMeta and SetMeta treat the field as if it were bool) |
50 // Additionally, int64, string and Toggle allow setting a default value | 65 // - Any type which implements PropertyConverter |
51 // in the struct field tag (the "<value>" portion). | 66 // Additionally, numeric, string and Toggle types allow setting a default |
| 67 // value in the struct field tag (the "<value>" portion). |
52 // | 68 // |
53 // Only exported fields allow SetMeta, but all fields of appropriate type | 69 // Only exported fields allow SetMeta, but all fields of appropriate type |
54 // allow tagged defaults. See Examples. | 70 // allow tagged defaults for use with GetMeta. See Examples. |
55 // | 71 // |
56 // `gae:"[-],extra"` -- indicates that any extra, unrecognized or mismatched | 72 // `gae:"[-],extra"` -- indicates that any extra, unrecognized or mismatched |
57 // property types (type in datastore doesn't match your struct's field | 73 // property types (type in datastore doesn't match your struct's field |
58 // type) should be loaded into and saved from this field. The precise type | 74 // type) should be loaded into and saved from this field. The precise type |
59 // of the field must be PropertyMap. This form allows you to control the | 75 // of the field must be PropertyMap. This form allows you to control the |
60 // behavior of reads and writes when your schema changes, or to implement | 76 // behavior of reads and writes when your schema changes, or to implement |
61 // something like ndb.Expando with a mix of structured and unstructured | 77 // something like ndb.Expando with a mix of structured and unstructured |
62 // fields. | 78 // fields. |
63 // | 79 // |
64 // If the `-` is present, then datastore write operations will not put | 80 // If the `-` is present, then datastore write operations will not put |
(...skipping 163 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
228 if !ok { | 244 if !ok { |
229 structCodecsMutex.Lock() | 245 structCodecsMutex.Lock() |
230 defer structCodecsMutex.Unlock() | 246 defer structCodecsMutex.Unlock() |
231 c = getStructCodecLocked(structType) | 247 c = getStructCodecLocked(structType) |
232 } | 248 } |
233 if c.problem != nil { | 249 if c.problem != nil { |
234 panic(c.problem) | 250 panic(c.problem) |
235 } | 251 } |
236 return c | 252 return c |
237 } | 253 } |
OLD | NEW |