Interface update, per-method Contexts.

doc.go

 // Copyright 2015 The LUCI Authors. All rights reserved.
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
 // Package gae provides a fakable wrapped interface for the appengine SDK's
 // APIs. This means that it's possible to mock all of the supported appengine
 // APIs for testing (or potentially implement a different backend for them).
 //
 // Features
 //
@@ skipping 45 matching lines @@
 //     innerHandler(c, w)
 //   }
 //
 //   type CoolStruct struct {
 //     ID `gae:"$id"`
 //
 //     Value string
 //   }
 //
 //   func innerHandler(c context.Context, w http.ResponseWriter) {
-//     rds := datastore.Get(c)
 //     obj := &CoolStruct{Value: "hello"}
-//     if err := rds.Put(obj); err != nil {
+//     if err := rds.Put(c, obj); err != nil {
 //       http.Error(w, err.String(), http.StatusInternalServerError)
 //     }
 //     fmt.Fprintf(w, "I wrote: %s", ds.KeyForObj(obj))
 //   }
 //
 // And in your test do:
 //
 //   import (
 //     "testing"
 //     "fmt"
@@ skipping 37 matching lines @@
 //
 //    service.RawFactory   - a function returning a RawInterface
 //
 //    service.RawFilter    - a function returning a new RawInterface based on
 //                           the previous filtered interface. Filters chain
 //                           together to allow behavioral service features
 //                           without needing to agument the underlying service
 //                           implementations directly.
 //
 // And common functions are:
-//    service.Get           - Retrieve the current, filtered Interface
-//                            implementation from the context. This is the most
-//                            frequently used service function by far.
-//
 //    service.GetRaw        - Retrieve the current, filtered RawInterface
 //                            implementation from the context. This is less
 //                            frequently used, but can be useful if you want to
 //                            avoid some of the overhead of the user-friendly
 //                            Interface, which can do sometimes-unnecessary amounts
 //                            of reflection or allocation. The RawInterface and
 //                            Interface for a service are fully interchangable and
 //                            usage of them can be freely mixed in an application.
 //
 //    service.AddRawFilters - adds one or more RawFilters to the context.
@@ skipping 31 matching lines @@
 //     CoolFunc(c)
 //   }
 //
 //   // This is the 'testing' code
 //   func TestCoolFunc(t *testing.T) {
 //     c := memory.Use(context.Background())
 //     CoolFunc(c)
 //   }
 //
 //   func CoolFunc(c context.Context, ...) {
-//     ds := datastore.Get(c)  // returns a datastore.Interface object
-//     mc := memcache.Get(c)   // returns a memcache.Interface object
-//     // use them here
-//
-//     // don't pass ds/mc/etc. directly, pass the context instead.
 //     SomeOtherFunction(c, ...)
 //
 //     // because you might need to:
-//     ds.RunInTransaction(func (c context.Context) error {
+//     ds.RunInTransaction(c, func (c context.Context) error {
 //       SomeOtherFunction(c, ...)  // c contains transactional versions of everything
 //     }, nil)
 //   }
 //
 // Filters
 //
 // Each service also supports "filters". Filters are proxy objects which have
 // the same interface as the service they're filtering, and pass data through to
 // the previous filter in the stack. Conceptually, a filtered version of, for
 // example, the Datastore, could look like:
 //    User code
 //    <count filter (counts how many times each API is called by the user)>
 //    <dscache filter (attempts to use memcache as a cache for datastore)>
 //    <count filter (counts how many times each API is actually hit)>
 //    memory datastore.RawInterface implementation
 //
-// So datastore.Get would return the full stack. In code, this would look
-// like:
-//   func HTTPHandler(r *http.Request) {
-//     c := prod.UseRequest(r)                                                    // production datastore
-//     c, rawCount := count.FilterRDS(c)      // add count filter
-//     c = dscache.FilterRDS(c)               // add dscache filter
-//     c, userCount := count.FilterRDS(c)     // add another count filter
-//   }
-//
 // Filters may or may not have state, it's up to the filter itself. In the case
 // of the count filter, it returns its state from the Filter<Service> method,
 // and the state can be observed to see how many times each API was invoked.
 // Since filters stack, we can compare counts from rawCount versus userCount to
 // see how many calls to the actual real datastore went through, vs. how many
 // went to memcache, for example.
 //
 // Note that Filters apply only to the service.RawInterface. All implementations
 // of service.Interface boil down to calls to service.RawInterface methods, but
 // it's possible that bad calls to the service.Interface methods could return
 // an error before ever reaching the filters or service implementation.
 package gae