Class: RSimperium::Bucket

Inherits:
Object
  • Object
show all
Includes:
ApiHelpers
Defined in:
lib/r_simperium/bucket.rb

Overview

Example use:

require 'r_simperium'
bucket = RSimperium::Bucket.new('myapp', 'db3d2a64abf711e0b63012313d001a3b', 'mybucket')
bucket.set 'item2', :age => 23
  # => True
bucket.set 'item2', :age => 25
  # => True
bucket.get 'item2'
  # => {'age' => 25}
bucket.get 'item2', :version => 1
  # => {'age' => 23}

Instance Method Summary collapse

Methods included from ApiHelpers

#api_auth_header, #api_meta, #api_request, #api_request_with_auth, #api_url

Constructor Details

#initialize(app_id, auth_token, bucket, opts = {}) ⇒ Bucket

A new Bucket object to interact with Simperium data.

Parameters:

  • app_id (String) —

    Your Simperium app id

  • auth_token (String) —

    A user’s Simperium auth token

  • bucket (String) —

    The name of the bucket to interact with

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • :userid (String) —

    The

  • :host (String) — default: 'api.simperium.com' —

    The host to send requests to

  • :scheme (String) — default: 'https' —

    The scheme to use for requests

  • :clientid (String) — default: a new uuid —

    A specific clientid to use



30
31
32
33
34
35
36
37
38
39
 
# File 'lib/r_simperium/bucket.rb', line 30

def initialize(app_id, auth_token, bucket, opts={})
  @app_id = app_id
  @bucket = bucket
  @auth_token = auth_token

  @userid = opts[:userid]
  @host = opts[:host] || ENV['SIMPERIUM_APIHOST'] || 'api.simperium.com'
  @scheme = opts[:scheme] || 'https'
  @clientid = opts[:clientid] || "py-#{RSimperium.gen_uuid @app_id}"
end

Instance Method Details

#all(params = {}) ⇒ Object

TODO:

Document

retrieves all updates for this bucket, regardless of the user

which made the update.

@cv: if supplied only updates that occurred after this
    change version are retrieved.

@data: if True, also include the lastest version of the data for
    changed entity

@username: if True, also include the username that created the
    change

@most_recent: if True, then only the most recent change for each
    document in the current page will be returned. e.g. if a
    document has been recently changed 3 times, only the latest of
    those 3 changes will be returned.

@timeout: the call will wait for updates if not are immediately
    available.  by default it will wait indefinately.  if a timeout
    is supplied an empty list will be return if no updates are made
    before the timeout is reached.



174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/r_simperium/bucket.rb', line 174

def all(params={})
  # cv=nil, data=false, username=false, most_recent=false, timeout=nil
  path = "/#{@bucket}/all"
  params[:clientid] = @clientid

  begin
    api_request_with_auth :get, api_url(path), :params => params
  rescue RestClient::Exception => e
    return [] if e.http_code == 504 || e.message =~ /(timed out|Connection refused)/
    raise
  end
end

#changes(params = {}) ⇒ Object

TODO:

Document

retrieves updates for this bucket for this user

@cv: if supplied only updates that occurred after this
    change version are retrieved.

@timeout: the call will wait for updates if not are immediately
    available.  by default it will wait indefinately.  if a timeout
    is supplied an empty list will be return if no updates are made
    before the timeout is reached.



138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/r_simperium/bucket.rb', line 138

def changes(params={})
  # cv=nil, timeout=nil
  path = "/#{@bucket}/changes?clientid=#{@clientid}"
  params[:clientid] = @clientid

  begin
    api_request_with_auth :get, api_url(path), :params => params
  rescue RestClient::Exception => e
    return [] if e.http_code == 504 || e.message =~ /(timed out|Connection refused)/
    raise
  end
end

#delete(item_id, version = nil) ⇒ Object

TODO:

Document

deletes the item from bucket



114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/r_simperium/bucket.rb', line 114

def delete(item_id, version=nil)
  path = "/#{@bucket}/i/#{item_id}"

  ccid = RSimperium.gen_uuid(@app_id)
  params = {
    :version => version,
    :clientid => @clientid,
    :ccid => ccid
  }

  api_request_with_auth :delete, api_url(path), :params => params
end

#get(item_id, opts = {}) ⇒ Object

Retrieves either the latest version of item from this bucket, or the specific version requested

Parameters:

  • item_id (String) —

    The item to retrieve

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • :version (String) —

    The version of the item to retrieve

  • :default (String) —

    A hash to return if the item does not exist



63
64
65
66
67
68
69
70
71
 
# File 'lib/r_simperium/bucket.rb', line 63

def get(item_id, opts={})
  path = "/#{@bucket}/i/#{item_id}"
  path += "/v/#{opts[:version]}" if opts[:version]
  begin
    api_request_with_auth :get, api_url(path)
  rescue RestClient::ResourceNotFound
    opts[:default]
  end
end

#index(params = {}) ⇒ Hash, string keys

Retrieve a page of the latest versions of a buckets documents ordered by most the most recently modified.

Parameters:

  • params (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (params):

  • :mark (String) —

    mark the documents returned to be modified after the given cv

  • :limit (String) —

    limit page size to this number. max 1000, default 100.

  • :since (String) —

    limit page to documents changed since the given cv.

  • :data (String) —

    include the current data state of each document in the result. by default data is not included.

Returns:



53
54
55
 
# File 'lib/r_simperium/bucket.rb', line 53

def index(params={})
  api_request_with_auth :get, api_url("/#{@bucket}/index"), :params => params
end

#new(data, ccid = nil) ⇒ Object

TODO:

Document



103
104
105
 
# File 'lib/r_simperium/bucket.rb', line 103

def new(data, ccid=nil)
  self.post RSimperium.gen_uuid(@app_id), data, :ccid => ccid
end

#post(item_id, data, opts = {}) ⇒ String

Posts the supplied data to item.

successful

Parameters:

  • item_id (String) —

    The item to retrieve

  • data (Hash) —

    A hash of data to be json-encoded

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • :version (String) —

    The version of the item to retrieve

  • :default (String) —

    A hash to return if the item does not exist

  • :ccid (String) —

    A unique id for this change. If you need to resubmit this operation, you should send the same ccid to prevent duplicate operations.

  • :response (Boolean) —

    If true, the item will be included in the response

Returns:

  • (String) —

    if a unique change id on success, or nil, if the post was not



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/r_simperium/bucket.rb', line 86

def post(item_id, data, opts={})
  path = "/#{@bucket}/i/#{item_id}"
  path += "/v/#{opts[:version]}" if opts[:version]

  opts[:ccid] || RSimperium.gen_uuid(@app_id)
  opts[:clientid] = @clientid
  data = MultiJson.encode(data)

  begin
    response = api_request_with_auth :post, api_url(path), :payload => data,
                                     :params => opts
  rescue RestClient::Exception => e
    return nil
  end
end

#set(item_id, data, options = {}) ⇒ Object

TODO:

Document



108
109
110
 
# File 'lib/r_simperium/bucket.rb', line 108

def set(item_id, data, options={})
  self.post(item_id, data, options)
end