Class: Telerivet::APICursor

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/telerivet/apicursor.rb

Overview

An easy-to-use interface for interacting with API methods that return collections of objects that may be split into multiple pages of results.

Using the APICursor, you can easily iterate over query results without having to manually fetch each page of results.

Instance Method Summary collapse

Constructor Details

#initialize(api, item_cls, path, params = nil) ⇒ APICursor

Returns a new instance of APICursor.



14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/telerivet/apicursor.rb', line 14

def initialize(api, item_cls, path, params = nil)
    params ||= {}

    if params.has_key?('count')
        raise Exception, "Cannot construct APICursor with 'count' parameter. Call the count() method instead."
    end

    @api = api
    @item_cls = item_cls
    @path = path
    @params = params

    @count = -1
    @pos = nil
    @data = nil
    @truncated = nil
    @next_marker = nil
    @limit = nil
    @offset = 0
end

Instance Method Details

#all ⇒ Object 



86
87
88
 
# File 'lib/telerivet/apicursor.rb', line 86

def all()
    to_a
end

#count ⇒ Object

Returns the total count of entities matching the current query, without actually fetching the entities themselves.

This is much more efficient than all() if you only need the count, as it only results in one API call, regardless of the number of entities matched by the query.

Returns:

int



75
76
77
78
79
80
81
82
83
84
 
# File 'lib/telerivet/apicursor.rb', line 75

def count()
    if @count == -1
        params = @params.clone
        params['count'] = 1

        res = @api.do_request("GET", @path, params)
        @count = res['count'].to_i
    end
    @count
end

#each ⇒ Object 



35
36
37
38
39
40
41
 
# File 'lib/telerivet/apicursor.rb', line 35

def each()
    loop do
        item = self.next()
        return if item == nil
        yield item
    end
end

#has_next? ⇒ Boolean

Returns true if there are any more entities in the result set, false otherwise

Returns:

bool

Returns:

  • (Boolean) 


96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/telerivet/apicursor.rb', line 96

def has_next?()
    return false if @limit != nil && @offset >= @limit

    load_next_page() if @data == nil

    return true if @pos < @data.length

    return false if !@truncated

    load_next_page()

    @pos < @data.length
end

#limit(_limit) ⇒ Object

Limits the maximum number of entities fetched by this query.

By default, iterating over the cursor will automatically fetch additional result pages as necessary. To prevent fetching more objects than you need, call this method to set the maximum number of objects retrieved from the API.

Arguments:

- limit (int)
    * The maximum number of entities to fetch from the server (may require multiple API
        calls if greater than 200)
    * Required

Returns:

the current APICursor object



59
60
61
62
 
# File 'lib/telerivet/apicursor.rb', line 59

def limit(_limit)
    @limit = _limit
    self
end

#load_next_page ⇒ Object 



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/telerivet/apicursor.rb', line 140

def load_next_page()
    request_params = @params.clone

    if @next_marker != nil
        request_params['marker'] = @next_marker
    end

    if @limit != nil && !request_params.has_key?("page_size")
        request_params['page_size'] = [@limit, 200].min
    end

    response = @api.do_request("GET", @path, request_params)

    @data = response['data']
    @truncated = response['truncated']
    @next_marker = response['next_marker']
    @pos = 0
end

#next ⇒ Object

Returns the next entity in the result set.

Returns:

Telerivet::Entity



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/telerivet/apicursor.rb', line 116

def next()
    if @limit != nil && @offset >= @limit
        return nil
    end

    if @data == nil || (@pos >= @data.length && @truncated)
        load_next_page()
    end

    if @pos < @data.length
        item_data = @data[@pos]
        @pos += 1
        @offset += 1
        cls = @item_cls
        if cls
            return cls.new(@api, item_data, true)
        else
            return item_data
        end
    else
        return nil
    end
end