OLD | NEW |
1 // Copyright 2015 The LUCI Authors. | 1 // Copyright 2015 The LUCI Authors. |
2 // | 2 // |
3 // Licensed under the Apache License, Version 2.0 (the "License"); | 3 // Licensed under the Apache License, Version 2.0 (the "License"); |
4 // you may not use this file except in compliance with the License. | 4 // you may not use this file except in compliance with the License. |
5 // You may obtain a copy of the License at | 5 // You may obtain a copy of the License at |
6 // | 6 // |
7 // http://www.apache.org/licenses/LICENSE-2.0 | 7 // http://www.apache.org/licenses/LICENSE-2.0 |
8 // | 8 // |
9 // Unless required by applicable law or agreed to in writing, software | 9 // Unless required by applicable law or agreed to in writing, software |
10 // distributed under the License is distributed on an "AS IS" BASIS, | 10 // distributed under the License is distributed on an "AS IS" BASIS, |
(...skipping 152 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
163 // KeyForObjErr extracts a key from src. | 163 // KeyForObjErr extracts a key from src. |
164 // | 164 // |
165 // src must be one of: | 165 // src must be one of: |
166 // - *S, where S is a struct | 166 // - *S, where S is a struct |
167 // - a PropertyLoadSaver | 167 // - a PropertyLoadSaver |
168 // | 168 // |
169 // It is expected that the struct exposes the following metadata (as retrieved | 169 // It is expected that the struct exposes the following metadata (as retrieved |
170 // by MetaGetter.GetMeta): | 170 // by MetaGetter.GetMeta): |
171 // - "key" (type: Key) - The full datastore key to use. Must not be nil. | 171 // - "key" (type: Key) - The full datastore key to use. Must not be nil. |
172 // OR | 172 // OR |
173 // - "id" (type: int64 or string) - The id of the Key to create | 173 // - "id" (type: int64 or string) - The id of the Key to create. |
174 // - "kind" (optional, type: string) - The kind of the Key to create. If | 174 // - "kind" (optional, type: string) - The kind of the Key to create. If |
175 // blank or not present, KeyForObjErr will extract the name of the src | 175 // blank or not present, KeyForObjErr will extract the name of the src |
176 // object's type. | 176 // object's type. |
177 // - "parent" (optional, type: Key) - The parent key to use. | 177 // - "parent" (optional, type: Key) - The parent key to use. |
178 // | 178 // |
179 // By default, the metadata will be extracted from the struct and its tagged | 179 // By default, the metadata will be extracted from the struct and its tagged |
180 // properties. However, if the struct implements MetaGetterSetter it is | 180 // properties. However, if the struct implements MetaGetterSetter it is |
181 // wholly responsible for exporting the required fields. A struct that | 181 // wholly responsible for exporting the required fields. A struct that |
182 // implements GetMeta to make some minor tweaks can evoke the defualt behavior | 182 // implements GetMeta to make some minor tweaks can evoke the defualt behavior |
183 // by using GetPLS(s).GetMeta. | 183 // by using GetPLS(s).GetMeta. |
(...skipping 380 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
564 // | 564 // |
565 // src must be one of: | 565 // src must be one of: |
566 // - *S, where S is a struct | 566 // - *S, where S is a struct |
567 // - *P, where *P is a concrete type implementing PropertyLoadSaver | 567 // - *P, where *P is a concrete type implementing PropertyLoadSaver |
568 // - []S or []*S, where S is a struct | 568 // - []S or []*S, where S is a struct |
569 // - []P or []*P, where *P is a concrete type implementing PropertyLoadSave
r | 569 // - []P or []*P, where *P is a concrete type implementing PropertyLoadSave
r |
570 // - []I, where I is some interface type. Each element of the slice must | 570 // - []I, where I is some interface type. Each element of the slice must |
571 // be non-nil, and its underlying type must be either *S or *P. | 571 // be non-nil, and its underlying type must be either *S or *P. |
572 // | 572 // |
573 // A *Key will be extracted from src via KeyForObj. If | 573 // A *Key will be extracted from src via KeyForObj. If |
574 // extractedKey.Incomplete() is true, then Put will write the resolved (i.e. | 574 // extractedKey.IsIncomplete() is true, then Put will write the resolved |
575 // automatic datastore-populated) *Key back to src. | 575 // (datastore-generated) *Key back to src. |
| 576 // |
| 577 // NOTE: The datastore only autogenerates *Keys with integer IDs. Only models |
| 578 // which use a raw `$key` or integer-typed `$id` field are elegible for this. |
| 579 // A model with a string-typed `$id` field will not accept an integer id'd *Key |
| 580 // and will cause the Put to fail. |
576 // | 581 // |
577 // If an error is encountered, the returned error value will depend on the | 582 // If an error is encountered, the returned error value will depend on the |
578 // input arguments. If one argument is supplied, the result will be the | 583 // input arguments. If one argument is supplied, the result will be the |
579 // encountered error type. If multiple arguments are supplied, the result will | 584 // encountered error type. If multiple arguments are supplied, the result will |
580 // be a MultiError whose error index corresponds to the argument in which the | 585 // be a MultiError whose error index corresponds to the argument in which the |
581 // error was encountered. | 586 // error was encountered. |
582 // | 587 // |
583 // If a src argument is a slice, its error type will be a MultiError. Note | 588 // If a src argument is a slice, its error type will be a MultiError. Note |
584 // that in the scenario where multiple slices are provided, this will return a | 589 // that in the scenario where multiple slices are provided, this will return a |
585 // MultiError containing a nested MultiError for each slice argument. | 590 // MultiError containing a nested MultiError for each slice argument. |
(...skipping 119 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
705 } | 710 } |
706 return err | 711 return err |
707 } | 712 } |
708 | 713 |
709 func filterStop(err error) error { | 714 func filterStop(err error) error { |
710 if err == Stop { | 715 if err == Stop { |
711 err = nil | 716 err = nil |
712 } | 717 } |
713 return err | 718 return err |
714 } | 719 } |
OLD | NEW |