7 "github.com/aws/aws-sdk-go/aws"
8 "github.com/aws/aws-sdk-go/aws/awsutil"
11 // A Pagination provides paginating of SDK API operations which are paginatable.
12 // Generally you should not use this type directly, but use the "Pages" API
13 // operations method to automatically perform pagination for you. Such as,
14 // "S3.ListObjectsPages", and "S3.ListObjectsPagesWithContext" methods.
16 // Pagination differs from a Paginator type in that pagination is the type that
17 // does the pagination between API operations, and Paginator defines the
18 // configuration that will be used per page request.
21 // for p.Next() && cont {
22 // data := p.Page().(*s3.ListObjectsOutput)
23 // // process the page's data
27 // See service client API operation Pages methods for examples how the SDK will
28 // use the Pagination type.
29 type Pagination struct {
30 // Function to return a Request value for each pagination request.
31 // Any configuration or handlers that need to be applied to the request
32 // prior to getting the next page should be done here before the request
35 // NewRequest should always be built from the same API operations. It is
36 // undefined if different API operations are returned on subsequent calls.
37 NewRequest func() (*Request, error)
38 // EndPageOnSameToken, when enabled, will allow the paginator to stop on
39 // token that are the same as its previous tokens.
40 EndPageOnSameToken bool
43 prevTokens []interface{}
44 nextTokens []interface{}
50 // HasNextPage will return true if Pagination is able to determine that the API
51 // operation has additional pages. False will be returned if there are no more
54 // Will always return true if Next has not been called yet.
55 func (p *Pagination) HasNextPage() bool {
60 hasNextPage := len(p.nextTokens) != 0
61 if p.EndPageOnSameToken {
62 return hasNextPage && !awsutil.DeepEqual(p.nextTokens, p.prevTokens)
67 // Err returns the error Pagination encountered when retrieving the next page.
68 func (p *Pagination) Err() error {
72 // Page returns the current page. Page should only be called after a successful
73 // call to Next. It is undefined what Page will return if Page is called after
74 // Next returns false.
75 func (p *Pagination) Page() interface{} {
79 // Next will attempt to retrieve the next page for the API operation. When a page
80 // is retrieved true will be returned. If the page cannot be retrieved, or there
81 // are no more pages false will be returned.
83 // Use the Page method to retrieve the current page data. The data will need
84 // to be cast to the API operation's output type.
86 // Use the Err method to determine if an error occurred if Page returns false.
87 func (p *Pagination) Next() bool {
92 req, err := p.NewRequest()
99 for i, intok := range req.Operation.InputTokens {
100 awsutil.SetValueAtPath(req.Params, intok, p.nextTokens[i])
111 p.prevTokens = p.nextTokens
112 p.nextTokens = req.nextPageTokens()
118 // A Paginator is the configuration data that defines how an API operation
119 // should be paginated. This type is used by the API service models to define
120 // the generated pagination config for service APIs.
122 // The Pagination type is what provides iterating between pages of an API. It
123 // is only used to store the token metadata the SDK should use for performing
125 type Paginator struct {
127 OutputTokens []string
129 TruncationToken string
132 // nextPageTokens returns the tokens to use when asking for the next page of data.
133 func (r *Request) nextPageTokens() []interface{} {
134 if r.Operation.Paginator == nil {
137 if r.Operation.TruncationToken != "" {
138 tr, _ := awsutil.ValuesAtPath(r.Data, r.Operation.TruncationToken)
143 switch v := tr[0].(type) {
145 if !aws.BoolValue(v) {
155 tokens := []interface{}{}
157 for _, outToken := range r.Operation.OutputTokens {
158 vs, _ := awsutil.ValuesAtPath(r.Data, outToken)
160 tokens = append(tokens, nil)
165 switch tv := v.(type) {
167 if len(aws.StringValue(tv)) == 0 {
168 tokens = append(tokens, nil)
173 tokens = append(tokens, nil)
179 tokens = append(tokens, v)
188 // Ensure a deprecated item is only logged once instead of each time its used.
189 func logDeprecatedf(logger aws.Logger, flag *int32, msg string) {
193 if atomic.CompareAndSwapInt32(flag, 0, 1) {
199 logDeprecatedHasNextPage int32
200 logDeprecatedNextPage int32
201 logDeprecatedEachPage int32
204 // HasNextPage returns true if this request has more pages of data available.
206 // Deprecated Use Pagination type for configurable pagination of API operations
207 func (r *Request) HasNextPage() bool {
208 logDeprecatedf(r.Config.Logger, &logDeprecatedHasNextPage,
209 "Request.HasNextPage deprecated. Use Pagination type for configurable pagination of API operations")
211 return len(r.nextPageTokens()) > 0
214 // NextPage returns a new Request that can be executed to return the next
215 // page of result data. Call .Send() on this request to execute it.
217 // Deprecated Use Pagination type for configurable pagination of API operations
218 func (r *Request) NextPage() *Request {
219 logDeprecatedf(r.Config.Logger, &logDeprecatedNextPage,
220 "Request.NextPage deprecated. Use Pagination type for configurable pagination of API operations")
222 tokens := r.nextPageTokens()
223 if len(tokens) == 0 {
227 data := reflect.New(reflect.TypeOf(r.Data).Elem()).Interface()
228 nr := New(r.Config, r.ClientInfo, r.Handlers, r.Retryer, r.Operation, awsutil.CopyOf(r.Params), data)
229 for i, intok := range nr.Operation.InputTokens {
230 awsutil.SetValueAtPath(nr.Params, intok, tokens[i])
235 // EachPage iterates over each page of a paginated request object. The fn
236 // parameter should be a function with the following sample signature:
238 // func(page *T, lastPage bool) bool {
239 // return true // return false to stop iterating
242 // Where "T" is the structure type matching the output structure of the given
243 // operation. For example, a request object generated by
244 // DynamoDB.ListTablesRequest() would expect to see dynamodb.ListTablesOutput
245 // as the structure "T". The lastPage value represents whether the page is
246 // the last page of data or not. The return value of this function should
247 // return true to keep iterating or false to stop.
249 // Deprecated Use Pagination type for configurable pagination of API operations
250 func (r *Request) EachPage(fn func(data interface{}, isLastPage bool) (shouldContinue bool)) error {
251 logDeprecatedf(r.Config.Logger, &logDeprecatedEachPage,
252 "Request.EachPage deprecated. Use Pagination type for configurable pagination of API operations")
254 for page := r; page != nil; page = page.NextPage() {
255 if err := page.Send(); err != nil {
258 if getNextPage := fn(page.Data, !page.HasNextPage()); !getNextPage {