Class: Orchestrate::Collection

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/orchestrate/collection.rb

Overview

Collections are groupings of KeyValue items. They are analagous to tables in SQL databases.

Defined Under Namespace

Classes: KeyValueList

Instance Attribute Summary collapse

Collection api collapse

KeyValue getters, setters collapse

KeyValue enumerators collapse

Geo Queries collapse

Instance Method Summary collapse

Constructor Details

#initialize(app, collection_name) ⇒ Object

Instantiate the Collection

Parameters:



15
16
17
18
19
20
21
22
 
# File 'lib/orchestrate/collection.rb', line 15

def initialize(app, collection_name)
  if app.kind_of? Orchestrate::Client
    @app = Application.new(app)
  else
    @app = app
  end
  @name = collection_name.to_s
end

Instance Attribute Details

#app ⇒ Orchestrate::Application (readonly)

Returns The application this collection belongs to.

Returns:



6
7
8
 
# File 'lib/orchestrate/collection.rb', line 6

def app
  @app
end

#name ⇒ String (readonly)

Returns The name of this collection.

Returns:

  • (String) —

    The name of this collection.



9
10
11
 
# File 'lib/orchestrate/collection.rb', line 9

def name
  @name
end

Instance Method Details

#<<(value) ⇒ Orchestrate::KeyValue

Note:

If the create is considered a success but the client is unable to parse the key from the location header, an API::ServiceError is raised.

Creates a KeyValue item with an auto-generated key

Parameters:

  • value (#to_json) —

    The value to store

Returns:

Raises:



103
104
105
106
107
108
 
# File 'lib/orchestrate/collection.rb', line 103

def <<(value)
  response = perform(:post, value)
  match_data = response.location.match(%r{#{name}/([^/]+)})
  raise API::ServiceError.new(response) unless match_data
  KeyValue.from_bodyless_response(self, match_data[1], value, response)
end

#<=>(other) ⇒ nil, ...

Equivalent to String#<=>. Compares by name and app's api_key.

Parameters:

Returns:

  • (nil, -1, 0, 1) 


43
44
45
46
47
 
# File 'lib/orchestrate/collection.rb', line 43

def <=>(other)
  return nil unless other.kind_of?(Orchestrate::Collection)
  return nil unless other.app.api_key == app.api_key
  other.name <=> name
end

#==(other) ⇒ true, false Also known as: eql?

Equivalent to String#==. Compares by name and app's api_key.

Parameters:

Returns:

  • (true, false) 


33
34
35
36
37
 
# File 'lib/orchestrate/collection.rb', line 33

def ==(other)
  other.kind_of?(Orchestrate::Collection) && \
    other.app.api_key == app.api_key && \
    other.name == name
end

#[](key_name) ⇒ Orchestrate::KeyValue?

Retrieves a KeyValue item by key.

Parameters:

  • key_name (#to_s) —

    The key of the item

Returns:



64
65
66
67
68
69
70
 
# File 'lib/orchestrate/collection.rb', line 64

def [](key_name)
  begin
    KeyValue.load(self, key_name)
  rescue API::NotFound
    nil
  end
end

#[]=(key_name, value) ⇒ value

Note:

Ruby will return the value provided to something= methods. If you want the KeyValue returned, use #set.

Sets a KeyValue item by key.

Parameters:

  • key_name (#to_s) —

    The key of the item.

  • value (#to_json) —

    The value to store at the key.

Returns:

  • (value) —

    The item provided for 'value'.

Raises:

  • Orchestrate::API::BadRequest the body is not valid JSON.

See Also:



79
80
81
 
# File 'lib/orchestrate/collection.rb', line 79

def []=(key_name, value)
  set(key_name, value)
end

#after(start_key) ⇒ KeyValueList

Sets the exclusive start key for enumeration over the KeyValue items in the collection.

Returns:

See Also:



212
213
214
 
# File 'lib/orchestrate/collection.rb', line 212

def after(start_key)
  KeyValueList.new(self).after(start_key)
end

#before(end_key) ⇒ KeyValueList

Sets the exclusive end key for enumeration over the KeyValue items in the collection.

Returns:

See Also:



219
220
221
 
# File 'lib/orchestrate/collection.rb', line 219

def before(end_key)
  KeyValueList.new(self).before(end_key)
end

#build(key_name, value = {}) ⇒ KeyValue

Builds a new, unsaved KeyValue with the given key_name and value.

Parameters:

  • key_name (#to_s) —

    The key of the item

  • value (#to_json) (defaults to: {}) —

    The value to store at the key.

Returns:



141
142
143
144
145
 
# File 'lib/orchestrate/collection.rb', line 141

def build(key_name, value={})
  kv = KeyValue.new(self, key_name)
  kv.value = value
  kv
end

#create(value) ⇒ Orchestrate::KeyValue #create(key_name, value) ⇒ Orchestrate::KeyValue?

Creates a KeyValue item in the collection.

Overloads:



125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/orchestrate/collection.rb', line 125

def create(key_name_or_value, value=nil)
  if value.nil? and key_name_or_value.respond_to?(:to_json)
    self << key_name_or_value
  else
    begin
      set(key_name_or_value, value, false)
    rescue Orchestrate::API::AlreadyPresent
      false
    end
  end
end

#delete(key_name) ⇒ true

Deletes the value for a KeyValue item.

Parameters:

  • key_name (#to_s) —

    The name of the key

Returns:

  • (true) —

    If the request suceeds.



161
162
163
164
 
# File 'lib/orchestrate/collection.rb', line 161

def delete(key_name)
  perform(:delete, key_name)
  true
end

#destroy! ⇒ Object

Deletes the collection.

Returns:

  • Orchestrate::API::Response



53
54
55
 
# File 'lib/orchestrate/collection.rb', line 53

def destroy!
  perform :delete_collection
end

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

Iterates over each KeyValue item in the collection. Used as the basis for Enumerable methods. Items are provided in lexicographically sorted order by key name.

Examples:

keys = collection.take(20).map(&:key)
# returns the first 20 keys in the collection.

Overloads:

  • #each ⇒ Enumerator

    Returns:

    • (Enumerator)
  • #each {|key_value| ... } ⇒ Object

    Yield Parameters:

See Also:



191
192
193
 
# File 'lib/orchestrate/collection.rb', line 191

def each(&block)
  KeyValueList.new(self).each(&block)
end

#end(end_key) ⇒ KeyValueList

Sets the inclusive end key for enumeration over the KeyValue items in the collection.

Returns:

See Also:



226
227
228
 
# File 'lib/orchestrate/collection.rb', line 226

def end(end_key)
  KeyValueList.new(self).end(end_key)
end

#in(field, box = {}) ⇒ Orchestrate::Search::QueryBuilder

Performs a search for items within a particular area, using a specified bounding box Search for items in a geographic bounding box

Examples:

collection.in(:field, {north: 12.5, south: 15, east: 14, west: 3})

Parameters:

  • field (#to_s) —

    The field containing location data (latitude & longitude)

  • box (#to_json) (defaults to: {}) —

    The values to create the bounding box,

Returns:



380
381
382
383
384
 
# File 'lib/orchestrate/collection.rb', line 380

def in(field, box={})
  box = box.flatten.each_slice(2).map {|dir, val| "#{dir}:#{val}" }.join(" ")
  query = "#{field}:IN:{#{box}}"
  Search::QueryBuilder.new(self, query)
end

#lazy ⇒ Enumerator::Lazy

Creates a Lazy Enumerator for the Collection's KeyValue List. If called inside the app's #in_parallel block, pre-fetches the first page of results.

Returns:

  • (Enumerator::Lazy) 


198
199
200
 
# File 'lib/orchestrate/collection.rb', line 198

def lazy
  KeyValueList.new(self).lazy
end

#near(field, latitude, longitude, distance, units = nil) ⇒ Orchestrate::Search::QueryBuilder

Performs a search for items near a specified geographic point in a collection. Search for items near a geographic point supported units: km, m, cm, mm, mi, yd, ft, in, nmi

Parameters:

  • field (#to_s) —

    The field containing location data (latitude & longitude)

  • latitude (Float) —

    The number representing latitude of a geographic point

  • longitude (Float) —

    The number representing longitude of a geographic point

  • distance (Integer) —

    The number of distance units.

  • units (#to_s) (defaults to: nil) —

    Unit of measurement for distance, default to kilometers (km),

Returns:



366
367
368
369
370
 
# File 'lib/orchestrate/collection.rb', line 366

def near(field, latitude, longitude, distance, units=nil)
  units ||= 'km'
  query = "#{field}:NEAR:{lat:#{latitude} lon:#{longitude} dist:#{distance}#{units}}"
  Search::QueryBuilder.new(self, query)
end

#perform(api_method, *args) ⇒ Object

Tells the Applicaiton to perform a request on its client, automatically providing the collection name.

Parameters:

  • api_method (Symbol) —

    The method on the client to call.

  • args (#to_s, #to_json, Hash) —

    The arguments for the method.

Returns:

  • API::Response



392
393
394
 
# File 'lib/orchestrate/collection.rb', line 392

def perform(api_method, *args)
  app.perform(api_method, name, *args)
end

#purge(key_name) ⇒ true

Purges a KeyValue item and its Ref history.

Parameters:

  • key_name (#to_s) —

    The name of the key

Returns:

  • (true) —

    If the request suceeds.



170
171
172
173
 
# File 'lib/orchestrate/collection.rb', line 170

def purge(key_name)
  perform(:purge, key_name)
  true
end

#search(query) ⇒ Orchestrate::Search::QueryBuilder

Returns A builder object to construct the query.

Parameters:

Returns:



352
353
354
 
# File 'lib/orchestrate/collection.rb', line 352

def search(query)
  Search::QueryBuilder.new(self, query)
end

#set(key_name, value, condition = nil) ⇒ Orchestrate::KeyValue

Sets a KeyValue item by key.

Parameters:

  • key_name (#to_s) —

    The key of the item.

  • value (#to_json) —

    The value to store at the key.

  • condition (nil, false, #to_s) (defaults to: nil) —

    (see Orchestraate::Client#put)

Returns:

Raises:

  • Orchestrate::API::BadRequest the body is not valid JSON.

  • Orchestrate::API::VersionMismatch a String condition was provided, but does not match the ref for the current value.

  • Orchestrate::API::AlreadyPresent a false condition was provided, but a value already exists for this key

See Also:



92
93
94
95
 
# File 'lib/orchestrate/collection.rb', line 92

def set(key_name, value, condition=nil)
  response = perform(:put, key_name, value, condition)
  KeyValue.from_bodyless_response(self, key_name, value, response)
end

#start(start_key) ⇒ KeyValueList

Sets the inclusive start key for enumeration over the KeyValue items in the collection.

Returns:

See Also:



205
206
207
 
# File 'lib/orchestrate/collection.rb', line 205

def start(start_key)
  KeyValueList.new(self).start(start_key)
end

#stub(key_name) ⇒ KeyValue

Returns an unloaded KeyValue object with the given key_name, if you need to access Refs, Relations or Events without loading the KeyValue's value.

Parameters:

  • key_name (#to_s) —

    The key of the item.

Returns:



151
152
153
154
155
 
# File 'lib/orchestrate/collection.rb', line 151

def stub(key_name)
  kv = KeyValue.new(self, key_name)
  kv.value = nil
  kv
end

#take(count) ⇒ Array<KeyValue>

Returns the first n items. Equivalent to Enumerable#take. Sets the limit parameter on the query to Orchestrate, so we don't ask for more than is needed.

Parameters:

  • count (Integer) —

    The number of items to limit to.

Returns:



234
235
236
 
# File 'lib/orchestrate/collection.rb', line 234

def take(count)
  KeyValueList.new(self).take(count)
end

#to_s ⇒ Object Also known as: inspect

Returns a pretty-printed representation of the collection.

Returns:

  • a pretty-printed representation of the collection.



25
26
27
 
# File 'lib/orchestrate/collection.rb', line 25

def to_s
  "#<Orchestrate::Collection name=#{name} api_key=#{app.api_key[0..7]}...>"
end