Class: Google::Gax::PagedEnumerable

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/google/gax/api_callable.rb

Overview

A class to provide the Enumerable interface for page-streaming method. PagedEnumerable assumes that the API call returns a message for a page which holds a list of resources and the token to the next page.

PagedEnumerable provides the enumerations over the resource data, and also provides the enumerations over the pages themselves.

Examples:

normal iteration over resources.

paged_enumerable.each { |resource| puts resource }

per-page iteration.

paged_enumerable.each_page { |page| puts page }

Enumerable over pages.

pages = paged_enumerable.enum_for(:each_page).to_a

more exact operations over pages.

while some_condition()
  page = paged_enumerable.page
  do_something(page)
  break if paged_enumerable.next_page?
  paged_enumerable.next_page
end

Defined Under Namespace

Classes: Page

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(request_page_token_field, response_page_token_field, resource_field) ⇒ PagedEnumerable

Returns a new instance of PagedEnumerable.

Parameters:

  • request_page_token_field (String) —

    The name of the field in request which will have the page token.

  • response_page_token_field (String) —

    The name of the field in the response which holds the next page token.

  • resource_field (String) —

    The name of the field in the response which holds the resources.



127
128
129
130
131
 
# File 'lib/google/gax/api_callable.rb', line 127

def initialize(request_page_token_field,
               response_page_token_field, resource_field)
  @request_page_token_field = request_page_token_field
  @page = Page.new(nil, response_page_token_field, resource_field)
end

Instance Attribute Details

#page ⇒ Page (readonly)

Returns The current page object.

Returns:

  • (Page) —

    The current page object.



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/google/gax/api_callable.rb', line 69

class PagedEnumerable
  # A class to represent a page in a PagedEnumerable. This also implements
  # Enumerable, so it can iterate over the resource elements.
  #
  # @attribute [r] response
  #   @return [Object] the actual response object.
  # @attribute [r] next_page_token
  #   @return [Object] the page token to be used for the next API call.
  class Page
    include Enumerable
    attr_reader :response

    # @param response [Object]
    #   The response object for the page.
    # @param response_page_token_field [String]
    #   The name of the field in response which holds the next page token.
    # @param resource_field [String]
    #   The name of the field in response which holds the resources.
    def initialize(response, response_page_token_field, resource_field)
      @response = response
      @response_page_token_field = response_page_token_field
      @resource_field = resource_field
    end

    # Creates another instance of Page with replacing the new response.
    # @param response [Object] a new response object.
    def dup_with(response)
      self.class.new(response, @response_page_token_field, @resource_field)
    end

    # Iterate over the resources.
    # @yield [Object] Gives the resource objects in the page.
    def each
      @response[@resource_field].each do |obj|
        yield obj
      end
    end

    def next_page_token
      @response[@response_page_token_field]
    end

    # Truthiness of next_page_token.
    def next_page_token?
      !@response.nil? && !next_page_token.nil? && next_page_token != 0 &&
        (!next_page_token.respond_to?(:empty?) || !next_page_token.empty?)
    end
  end

  include Enumerable
  attr_reader :page

  # @param request_page_token_field [String]
  #   The name of the field in request which will have the page token.
  # @param response_page_token_field [String]
  #   The name of the field in the response which holds the next page token.
  # @param resource_field [String]
  #   The name of the field in the response which holds the resources.
  def initialize(request_page_token_field,
                 response_page_token_field, resource_field)
    @request_page_token_field = request_page_token_field
    @page = Page.new(nil, response_page_token_field, resource_field)
  end

  # Initiate the streaming with the requests and keywords.
  # @param api_call [Proc]
  #   A proc to update the response object.
  # @param request [Object]
  #   The initial request object.
  # @param settings [CallSettings]
  #   The call settings to enumerate pages
  # @return [PagedEnumerable]
  #   returning self for further uses.
  def start(api_call, request, settings, block)
    @func = api_call
    @request = request
    page_token = settings.page_token
    @request[@request_page_token_field] = page_token if page_token
    @page = @page.dup_with(@func.call(@request, block))
    self
  end

  # True if it's already started.
  def started?
    !@request.nil?
  end

  # Iterate over the resources.
  # @yield [Object] Gives the resource objects in the stream.
  # @raise [RuntimeError] if it's not started yet.
  def each
    each_page do |page|
      page.each do |obj|
        yield obj
      end
    end
  end

  # Iterate over the pages.
  # @yield [Page] Gives the pages in the stream.
  # @raise [GaxError] if it's not started yet.
  def each_page
    raise GaxError.new('not started!') unless started?
    yield @page
    loop do
      break unless next_page?
      yield next_page
    end
  end

  # True if it has the next page.
  def next_page?
    @page.next_page_token?
  end

  # Update the response in the current page.
  # @return [Page] the new page object.
  def next_page
    return unless next_page?
    @request[@request_page_token_field] = @page.next_page_token
    @page = @page.dup_with(@func.call(@request))
  end

  def response
    @page.response
  end

  def page_token
    @page.next_page_token
  end
end

#page_token ⇒ Object (readonly)

Returns The page token to be used for the next API call.

Returns:

  • (Object) —

    The page token to be used for the next API call.



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/google/gax/api_callable.rb', line 69

class PagedEnumerable
  # A class to represent a page in a PagedEnumerable. This also implements
  # Enumerable, so it can iterate over the resource elements.
  #
  # @attribute [r] response
  #   @return [Object] the actual response object.
  # @attribute [r] next_page_token
  #   @return [Object] the page token to be used for the next API call.
  class Page
    include Enumerable
    attr_reader :response

    # @param response [Object]
    #   The response object for the page.
    # @param response_page_token_field [String]
    #   The name of the field in response which holds the next page token.
    # @param resource_field [String]
    #   The name of the field in response which holds the resources.
    def initialize(response, response_page_token_field, resource_field)
      @response = response
      @response_page_token_field = response_page_token_field
      @resource_field = resource_field
    end

    # Creates another instance of Page with replacing the new response.
    # @param response [Object] a new response object.
    def dup_with(response)
      self.class.new(response, @response_page_token_field, @resource_field)
    end

    # Iterate over the resources.
    # @yield [Object] Gives the resource objects in the page.
    def each
      @response[@resource_field].each do |obj|
        yield obj
      end
    end

    def next_page_token
      @response[@response_page_token_field]
    end

    # Truthiness of next_page_token.
    def next_page_token?
      !@response.nil? && !next_page_token.nil? && next_page_token != 0 &&
        (!next_page_token.respond_to?(:empty?) || !next_page_token.empty?)
    end
  end

  include Enumerable
  attr_reader :page

  # @param request_page_token_field [String]
  #   The name of the field in request which will have the page token.
  # @param response_page_token_field [String]
  #   The name of the field in the response which holds the next page token.
  # @param resource_field [String]
  #   The name of the field in the response which holds the resources.
  def initialize(request_page_token_field,
                 response_page_token_field, resource_field)
    @request_page_token_field = request_page_token_field
    @page = Page.new(nil, response_page_token_field, resource_field)
  end

  # Initiate the streaming with the requests and keywords.
  # @param api_call [Proc]
  #   A proc to update the response object.
  # @param request [Object]
  #   The initial request object.
  # @param settings [CallSettings]
  #   The call settings to enumerate pages
  # @return [PagedEnumerable]
  #   returning self for further uses.
  def start(api_call, request, settings, block)
    @func = api_call
    @request = request
    page_token = settings.page_token
    @request[@request_page_token_field] = page_token if page_token
    @page = @page.dup_with(@func.call(@request, block))
    self
  end

  # True if it's already started.
  def started?
    !@request.nil?
  end

  # Iterate over the resources.
  # @yield [Object] Gives the resource objects in the stream.
  # @raise [RuntimeError] if it's not started yet.
  def each
    each_page do |page|
      page.each do |obj|
        yield obj
      end
    end
  end

  # Iterate over the pages.
  # @yield [Page] Gives the pages in the stream.
  # @raise [GaxError] if it's not started yet.
  def each_page
    raise GaxError.new('not started!') unless started?
    yield @page
    loop do
      break unless next_page?
      yield next_page
    end
  end

  # True if it has the next page.
  def next_page?
    @page.next_page_token?
  end

  # Update the response in the current page.
  # @return [Page] the new page object.
  def next_page
    return unless next_page?
    @request[@request_page_token_field] = @page.next_page_token
    @page = @page.dup_with(@func.call(@request))
  end

  def response
    @page.response
  end

  def page_token
    @page.next_page_token
  end
end

#response ⇒ Object (readonly)

Returns The current response object.

Returns:

  • (Object) —

    The current response object.



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/google/gax/api_callable.rb', line 69

class PagedEnumerable
  # A class to represent a page in a PagedEnumerable. This also implements
  # Enumerable, so it can iterate over the resource elements.
  #
  # @attribute [r] response
  #   @return [Object] the actual response object.
  # @attribute [r] next_page_token
  #   @return [Object] the page token to be used for the next API call.
  class Page
    include Enumerable
    attr_reader :response

    # @param response [Object]
    #   The response object for the page.
    # @param response_page_token_field [String]
    #   The name of the field in response which holds the next page token.
    # @param resource_field [String]
    #   The name of the field in response which holds the resources.
    def initialize(response, response_page_token_field, resource_field)
      @response = response
      @response_page_token_field = response_page_token_field
      @resource_field = resource_field
    end

    # Creates another instance of Page with replacing the new response.
    # @param response [Object] a new response object.
    def dup_with(response)
      self.class.new(response, @response_page_token_field, @resource_field)
    end

    # Iterate over the resources.
    # @yield [Object] Gives the resource objects in the page.
    def each
      @response[@resource_field].each do |obj|
        yield obj
      end
    end

    def next_page_token
      @response[@response_page_token_field]
    end

    # Truthiness of next_page_token.
    def next_page_token?
      !@response.nil? && !next_page_token.nil? && next_page_token != 0 &&
        (!next_page_token.respond_to?(:empty?) || !next_page_token.empty?)
    end
  end

  include Enumerable
  attr_reader :page

  # @param request_page_token_field [String]
  #   The name of the field in request which will have the page token.
  # @param response_page_token_field [String]
  #   The name of the field in the response which holds the next page token.
  # @param resource_field [String]
  #   The name of the field in the response which holds the resources.
  def initialize(request_page_token_field,
                 response_page_token_field, resource_field)
    @request_page_token_field = request_page_token_field
    @page = Page.new(nil, response_page_token_field, resource_field)
  end

  # Initiate the streaming with the requests and keywords.
  # @param api_call [Proc]
  #   A proc to update the response object.
  # @param request [Object]
  #   The initial request object.
  # @param settings [CallSettings]
  #   The call settings to enumerate pages
  # @return [PagedEnumerable]
  #   returning self for further uses.
  def start(api_call, request, settings, block)
    @func = api_call
    @request = request
    page_token = settings.page_token
    @request[@request_page_token_field] = page_token if page_token
    @page = @page.dup_with(@func.call(@request, block))
    self
  end

  # True if it's already started.
  def started?
    !@request.nil?
  end

  # Iterate over the resources.
  # @yield [Object] Gives the resource objects in the stream.
  # @raise [RuntimeError] if it's not started yet.
  def each
    each_page do |page|
      page.each do |obj|
        yield obj
      end
    end
  end

  # Iterate over the pages.
  # @yield [Page] Gives the pages in the stream.
  # @raise [GaxError] if it's not started yet.
  def each_page
    raise GaxError.new('not started!') unless started?
    yield @page
    loop do
      break unless next_page?
      yield next_page
    end
  end

  # True if it has the next page.
  def next_page?
    @page.next_page_token?
  end

  # Update the response in the current page.
  # @return [Page] the new page object.
  def next_page
    return unless next_page?
    @request[@request_page_token_field] = @page.next_page_token
    @page = @page.dup_with(@func.call(@request))
  end

  def response
    @page.response
  end

  def page_token
    @page.next_page_token
  end
end

Instance Method Details

#each {|Object| ... } ⇒ Object

Iterate over the resources.

Yields:

  • (Object) —

    Gives the resource objects in the stream.

Raises:

  • (RuntimeError) —

    if it’s not started yet.



159
160
161
162
163
164
165
 
# File 'lib/google/gax/api_callable.rb', line 159

def each
  each_page do |page|
    page.each do |obj|
      yield obj
    end
  end
end

#each_page {|Page| ... } ⇒ Object

Iterate over the pages.

Yields:

  • (Page) —

    Gives the pages in the stream.

Raises:

  • (GaxError) —

    if it’s not started yet.



170
171
172
173
174
175
176
177
 
# File 'lib/google/gax/api_callable.rb', line 170

def each_page
  raise GaxError.new('not started!') unless started?
  yield @page
  loop do
    break unless next_page?
    yield next_page
  end
end

#next_page ⇒ Page

Update the response in the current page.

Returns:

  • (Page) —

    the new page object.



186
187
188
189
190
 
# File 'lib/google/gax/api_callable.rb', line 186

def next_page
  return unless next_page?
  @request[@request_page_token_field] = @page.next_page_token
  @page = @page.dup_with(@func.call(@request))
end

#next_page? ⇒ Boolean

True if it has the next page.

Returns:

  • (Boolean) 


180
181
182
 
# File 'lib/google/gax/api_callable.rb', line 180

def next_page?
  @page.next_page_token?
end

#start(api_call, request, settings, block) ⇒ PagedEnumerable

Initiate the streaming with the requests and keywords.

Parameters:

  • api_call (Proc) —

    A proc to update the response object.

  • request (Object) —

    The initial request object.

  • settings (CallSettings) —

    The call settings to enumerate pages

Returns:



142
143
144
145
146
147
148
149
 
# File 'lib/google/gax/api_callable.rb', line 142

def start(api_call, request, settings, block)
  @func = api_call
  @request = request
  page_token = settings.page_token
  @request[@request_page_token_field] = page_token if page_token
  @page = @page.dup_with(@func.call(@request, block))
  self
end

#started? ⇒ Boolean

True if it’s already started.

Returns:

  • (Boolean) 


152
153
154
 
# File 'lib/google/gax/api_callable.rb', line 152

def started?
  !@request.nil?
end