Class: Eloqua::Query

Inherits:
Object
  • Object
show all
Defined in:
lib/eloqua/query.rb

Constant Summary collapse

@@request_delay =

The amount of time in seconds to wait before sending another request to Eloqua

1

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(remote_object) ⇒ Query

Create a new query to attach conditions to.

class Contact < Eloqua::Entity
  remote_type = api.remote_type('Contact')
end

Eloqua::Query.new(Contact)

Parameters:



26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/eloqua/query.rb', line 26

def initialize(remote_object)
  unless(remote_object.is_a?(Class) && Eloqua::RemoteObject >= remote_object)
    raise(ArgumentError, 'must provide an Eloqua::RemoteObject or one of its descendants')
  end

  @page = 1
  @limit = 200
  @collection = []
  @remote_object = remote_object
  @conditions = []
  @fields = nil
  @has_requested = false
end

Instance Attribute Details

#collection ⇒ Object (readonly)

Returns the value of attribute collection.



9
10
11
 
# File 'lib/eloqua/query.rb', line 9

def collection
  @collection
end

#conditions ⇒ Object (readonly)

Returns the value of attribute conditions.



9
10
11
 
# File 'lib/eloqua/query.rb', line 9

def conditions
  @conditions
end

#remote_object ⇒ Object (readonly)

Returns the value of attribute remote_object.



9
10
11
 
# File 'lib/eloqua/query.rb', line 9

def remote_object
  @remote_object
end

#total_pages ⇒ Object (readonly)

Returns the value of attribute total_pages.



9
10
11
 
# File 'lib/eloqua/query.rb', line 9

def total_pages
  @total_pages
end

Instance Method Details

#all ⇒ Array

Sends request and returns collection

query.on(:email, '=', '*').all # => [Eloqua::RemoteObject.new(), ...]

Returns:

  • (Array) —

    collection of Eloqua::RemoteObject



234
235
236
237
 
# File 'lib/eloqua/query.rb', line 234

def all
  request!
  collection
end

#clear_conditions! ⇒ Object

Clears all conditions added by #on

                  query.on(:id, '>', '1')
                  query.clear_conditions!



96
97
98
99
 
# File 'lib/eloqua/query.rb', line 96

def clear_conditions!
  @has_requested = false
  conditions.clear
end

#each(&block) ⇒ Object

Sends request if not already set and iterates through result

                  query.each do |record|
                          record.class # query.remote_object
                  end

Currently this is a shortcut for

                  query.all.each do |record|
                          ...
                  end

Parameters:

  • a (Proc) —

    block iterator



225
226
227
 
# File 'lib/eloqua/query.rb', line 225

def each(&block)
  all.each(&block)
end

#each_page(max_pages = nil, &block) ⇒ Object

Iterates through each page up to max_pages when max_pages is nil (default) will iterate through each page yielding a block with a record.

with max_pages you could and then resume the loop through pages

                  query.each_page(2) |record|
                          query.total_pages # 10
                          query.page # 1 ... 2
                  end

                  ...

                  query.each_page(2) |record|
                          query.total_pages # 10
                          query.page # 3 ... 4
                  end

Parameters:

  • max (Integer) —

    pages to iterate through

See Also:



260
261
262
263
264
265
266
267
 
# File 'lib/eloqua/query.rb', line 260

def each_page(max_pages = nil, &block)
  each(&block)
  while(total_pages > page)
    break if max_pages && page >= max_pages
    page(page + 1)
    each(&block)
  end
end

#fields(value = nil) ⇒ self, Array

Sets or gets the array of fields to find. Can use a literal string or a symbol of a mapped attribute

query.fields([:email, 'Date'])
query.fields # returns [:email, 'Date']

Parameters:

  • (Array)

Returns:

  • (self, Array)

See Also:

  • RemoteObject::map


71
 
# File 'lib/eloqua/query.rb', line 71

def fields(value = nil); end

#has_requested? ⇒ Boolean

Has the request been made yet?

query.has_requested? # false
query.on(:email, '=', '*').request!
query.has_requested? # true

Returns:

  • (Boolean) 


208
209
210
 
# File 'lib/eloqua/query.rb', line 208

def has_requested?
  @has_requested
end

#limit(value = nil) ⇒ self, Integer

Sets or gets limit

query.limit(5) # sets limit returns self
query.limit # returns 5

Parameters:

  • (Integer)

Returns:

  • (self, Integer) 


50
 
# File 'lib/eloqua/query.rb', line 50

def limit(value = nil); end

#on(field, operator, value) ⇒ Object

Adds a condition to the query; may be chained.

query.on(:email, '=', 'value').on('created_at', '>', '2011-04-20')

Parameters:

  • field (String, Symbol) —

    name

  • operator (String) —

    can use: [ =, !=, <, >, >=, <=]

  • value (String) —

    to search for

Returns:

  • self



109
110
111
112
113
114
115
116
117
 
# File 'lib/eloqua/query.rb', line 109

def on(field, operator, value)
  @has_requested = false
  @conditions << {
    :field => field,
    :type => operator,
    :value => value
  }
  self
end

#page(value = nil) ⇒ self, Integer

Sets or gets page

query.page(5) # sets limit returns self
query.page # returns 5

Parameters:

  • (Integer)

Returns:

  • (self, Integer) 


60
 
# File 'lib/eloqua/query.rb', line 60

def page(value = nil); end

#request! ⇒ Object

Send the built request to eloqua

query.on(:email, '=', '*') # wildcard
query.request!
query.collection # Array of results
query.current_page # Current page
query.total_pages # Number of pages

Returns:

  • self



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
 
# File 'lib/eloqua/query.rb', line 129

def request!
  return if has_requested?
  sleep_for = wait_for_request_delay
  if(sleep_for)
    sleep(sleep_for)
  end
  xml_query = api.builder do |xml|
    xml.eloquaType do
      xml.template!(:object_type, remote_object.remote_type)
    end
    xml.searchQuery(build_query)

    # This won't harm anything but it is changing the
    # fields to its mapped elouqa name.
    if(!fields.blank? && fields.is_a?(Array))
      fields.map! do |field|
        field = remote_object.eloqua_attribute(field)
      end
      xml.fieldNames do
        xml.template!(:array, fields)
      end
    end

    xml.pageNumber(page)
    xml.pageSize(limit)
  end

  # Add timestamp of when we made request
  @_query_started = Time.now
  result = api.request(:query, xml_query)

  # Clear collection
  collection.clear

  # Mark as requested
  @has_requested = true


  if(result[:entities])
    @total_pages = result[:total_pages].to_i
    entities = Eloqua.format_results_for_array(result, :entities, :dynamic_entity)
    records = entities.inject([]) do |records, entity|
      record_attrs = {}
      entity_id = entity[:id]
      entity[:field_value_collection][:entity_fields].each do |entity_attr|
        record_attrs[entity_attr[:internal_name]] = entity_attr[:value]
      end
      record_attrs[remote_object.primary_key] = entity_id
      record_object = remote_object.new(record_attrs, :remote)

      collection << record_object
    end
    collection
  else
    @total_pages = 0
    false
  end
end

#wait_for_request_delay ⇒ Object 



188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/eloqua/query.rb', line 188

def wait_for_request_delay
  if(request_delay && query_started)
    now = Time.now
    wait_until = Time.at((request_delay + query_started.to_f))
    if(wait_until > now)
      wait_until - now
    end
  else
    false
  end
end