class RSimperium::Bucket

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}

Public Class Methods

new(app_id, auth_token, bucket, opts={}) click to toggle source

A new Bucket object to interact with Simperium data.

@overload initialize(app_id, auth_token, bucket, opts={}) @param [String] app_id Your Simperium app id @param [String] auth_token A user’s Simperium auth token @param [String] bucket The name of the bucket to interact with @option opts [String] :userid The @option opts [String] :host (‘api.simperium.com’) The host to send requests to @option opts [String] :scheme (‘https’) The scheme to use for requests @option opts [String] :clientid (a new uuid) A specific clientid to use

# 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

Public Instance Methods

all(params={}) click to toggle source

@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.
# 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={}) click to toggle source

@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.
# 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) click to toggle source

@todo Document deletes the item from bucket

# 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={}) click to toggle source

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

@param item_id [String] The item to retrieve @option opts [String] :version The version of the item to retrieve @option opts [String] :default A hash to return if the item does not exist

# 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={}) click to toggle source

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

@option params [String] :mark mark the documents returned to be modified after the

given cv

@option params [String] :limit limit page size to this number. max 1000, default 100. @option params [String] :since limit page to documents changed since the given cv. @option params [String] :data include the current data state of each document in the

result. by default data is not included.

@return [Hash, string keys] See {simperium.com/docs/reference/http Simperium’s api page}

for the values inside the returned hash.
# 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) click to toggle source

@todo Document

# 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={}) click to toggle source

Posts the supplied data to item.

@param item_id [String] The item to retrieve @param data [Hash] A hash of data to be json-encoded @option opts [String] :version The version of the item to retrieve @option opts [String] :default A hash to return if the item does not exist @option opts [String] :ccid A unique id for this change. If you need to resubmit

this operation, you should send the same ccid to prevent duplicate operations.

@option opts [Boolean] :response If true, the item will be included in the response

@return [String] if a unique change id on success, or nil, if the post was not successful

# 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={}) click to toggle source

@todo Document

# File lib/r_simperium/bucket.rb, line 108
def set(item_id, data, options={})
  self.post(item_id, data, options)
end