module Couchbase::Operations::Get

Public Instance Methods

[](key, options = {}) click to toggle source
# File lib/couchbase/operations/get.rb, line 164
def [](key, options = {})
  get(key, options)
end
async_get(key) click to toggle source
# File lib/couchbase/operations/get.rb, line 184
def async_get(key)
  case key
  when String, Symbol
    meta = { op: :get, key: key }
    future = client.asyncGet(key)
  when Array
    meta = { op: :get }
    future = client.asyncGetBulk(key)
  when Hash
    # async_get_and_touch(key, options, &block)
  end
  register_future(future, meta, &Proc.new) if block_given?
end
get(*args, &block) click to toggle source

Obtain an object stored in Couchbase by given key.

@since 1.0.0

@see couchbase.com/docs/couchbase-manual-2.0/couchbase-architecture-apis-memcached-protocol-additions.html#couchbase-architecture-apis-memcached-protocol-additions-getl

@overload get(*keys, options = {})

@param keys [String, Symbol, Array] One or several keys to fetch
@param options [Hash] Options for operation.
@option options [true, false] :extended (false) If set to +true+, the
  operation will return a tuple +[value, flags, cas]+, otherwise (by
  default) it returns just the value.
@option options [Fixnum] :ttl (self.default_ttl) Expiry time for key.
  Values larger than 30*24*60*60 seconds (30 days) are interpreted as
  absolute times (from the epoch).
@option options [true, false] :quiet (self.quiet) If set to +true+, the
  operation won't raise error for missing key, it will return +nil+.
  Otherwise it will raise error in synchronous mode. In asynchronous
  mode this option ignored.
@option options [Symbol] :format (nil) Explicitly choose the decoder
  for this key (+:plain+, +:document+, +:marshal+). See
  {Bucket#default_format}.
@option options [Fixnum, Boolean] :lock Lock the keys for time span.
  If this parameter is +true+ the key(s) will be locked for default
  timeout. Also you can use number to setup your own timeout in
  seconds. If it will be lower that zero or exceed the maximum, the
  server will use default value. You can determine actual default and
  maximum values calling {Bucket#stats} without arguments and
  inspecting keys  "ep_getl_default_timeout" and "ep_getl_max_timeout"
  correspondingly. See overloaded hash syntax to specify custom timeout
  per each key.
@option options [true, false] :assemble_hash (false) Assemble Hash for
  results. Hash assembled automatically if +:extended+ option is true
  or in case of "get and touch" multimple keys.
@option options [true, false] :replica (false) Read key from replica
  node. Options +:ttl+ and +:lock+ are not compatible with +:replica+.

@yieldparam ret [Result] the result of operation in asynchronous mode
  (valid attributes: +error+, +operation+, +key+, +value+, +flags+,
  +cas+).

@return [Object, Array, Hash] the value(s) (or tuples in extended mode)
  associated with the key.

@raise [Couchbase::Error::NotFound] if the key is missing in the
  bucket.

@raise [Couchbase::Error::Connect] if connection closed (see {Bucket#reconnect})

@raise [ArgumentError] when passing the block in synchronous mode

@example Get single value in quiet mode (the default)
  c.get("foo")     #=> the associated value or nil

@example Use alternative hash-like syntax
  c["foo"]         #=> the associated value or nil

@example Get single value in verbose mode
  c.get("missing-foo", :quiet => false)  #=> raises Couchbase::NotFound
  c.get("missing-foo", :quiet => true)   #=> returns nil

@example Get and touch single value. The key won't be accessible after 10 seconds
  c.get("foo", :ttl => 10)

@example Extended get
  val, flags, cas = c.get("foo", :extended => true)

@example Get multiple keys
  c.get("foo", "bar", "baz")   #=> [val1, val2, val3]

@example Get multiple keys with assembing result into the Hash
  c.get("foo", "bar", "baz", :assemble_hash => true)
  #=> {"foo" => val1, "bar" => val2, "baz" => val3}

@example Extended get multiple keys
  c.get("foo", "bar", :extended => true)
  #=> {"foo" => [val1, flags1, cas1], "bar" => [val2, flags2, cas2]}

@example Asynchronous get
  c.run do
    c.get("foo", "bar", "baz") do |res|
      ret.operation   #=> :get
      ret.success?    #=> true
      ret.key         #=> "foo", "bar" or "baz" in separate calls
      ret.value
      ret.flags
      ret.cas
    end
  end

@example Get and lock key using default timeout
  c.get("foo", :lock => true)

@example Determine lock timeout parameters
  c.stats.values_at("ep_getl_default_timeout", "ep_getl_max_timeout")
  #=> [{"127.0.0.1:11210"=>"15"}, {"127.0.0.1:11210"=>"30"}]

@example Get and lock key using custom timeout
  c.get("foo", :lock => 3)

@example Get and lock multiple keys using custom timeout
  c.get("foo", "bar", :lock => 3)

@overload get(keys, options = {})

When the method receive hash map, it will behave like it receive list
of keys (+keys.keys+), but also touch each key setting expiry time to
the corresponding value. But unlike usual get this command always
return hash map +{key => value}+ or +{key => [value, flags, cas]}+.

@param keys [Hash] Map key-ttl
@param options [Hash] Options for operation. (see options definition
  above)

@return [Hash] the values (or tuples in extended mode) associated with
  the keys.

@example Get and touch multiple keys
  c.get("foo" => 10, "bar" => 20)   #=> {"foo" => val1, "bar" => val2}

@example Extended get and touch multiple keys
  c.get({"foo" => 10, "bar" => 20}, :extended => true)
  #=> {"foo" => [val1, flags1, cas1], "bar" => [val2, flags2, cas2]}

@example Get and lock multiple keys for chosen period in seconds
  c.get("foo" => 10, "bar" => 20, :lock => true)
  #=> {"foo" => val1, "bar" => val2}
# File lib/couchbase/operations/get.rb, line 148
def get(*args, &block)
  key, options = expand_get_args(args)

  if async?
    async_get(key, &block)
    # if block_given?
    #   async_get(key, &Proc.new)
    # else
    #   async_get(key)
    # end
  else
    sync_block_error if block_given?
    get_key(key, options)
  end
end
get_bulk(keys, options) click to toggle source
# File lib/couchbase/operations/get.rb, line 168
def get_bulk(keys, options)
  results = if options[:extended]
              get_bulk_extended(keys)
            else
              client_get_bulk(keys)
            end

  not_found_error(results.size != keys.size, options)

  if options[:assemble_hash] || options[:extended]
    results
  else
    ordered_multi_values(keys, results)
  end
end

Private Instance Methods

client_get_and_lock(key, options) click to toggle source
# File lib/couchbase/operations/get.rb, line 278
def client_get_and_lock(key, options)
  lock = options[:lock] == true ? 30 : options[:lock]
  cas = client.getAndLock(key, lock)
  if options[:extended]
    [cas.getValue, nil, cas.getCas]
  else
    cas.getValue
  end
end
client_get_and_touch(key, ttl) click to toggle source
# File lib/couchbase/operations/get.rb, line 274
def client_get_and_touch(key, ttl)
  client.getAndTouch(key, ttl).getValue
end
client_get_bulk(keys) click to toggle source
# File lib/couchbase/operations/get.rb, line 298
def client_get_bulk(keys)
  client.getBulk(keys)
rescue java.lang.ClassCastException
  raise TypeError.new
end
client_get_extended(key) click to toggle source
# File lib/couchbase/operations/get.rb, line 288
def client_get_extended(key)
  cas_value = client.gets(key)

  if cas_value.nil?
    nil
  else
    [cas_value.getValue, nil, cas_value.getCas]
  end
end
expand_get_args(args) click to toggle source
# File lib/couchbase/operations/get.rb, line 211
def expand_get_args(args)
  options = extract_options_hash(args)
  key = args.size == 1 ? args.first : args

  [key, options]
end
get_and_touch(key, options = {}) click to toggle source
# File lib/couchbase/operations/get.rb, line 244
def get_and_touch(key, options = {})
  if key.size > 1
    get_bulk_and_touch(key, options)
  else
    key, ttl = key.first
    value = client_get_and_touch(key, ttl)
    not_found_error(value.nil?)
    { key => value }
  end
end
get_bulk_and_touch(keys, options = {}) click to toggle source
# File lib/couchbase/operations/get.rb, line 255
def get_bulk_and_touch(keys, options = {})
  options.merge!(assemble_hash: true)
  results = get_bulk(keys.keys, options)
  touch(keys)
  results.to_hash
end
get_bulk_extended(keys, options = {}) click to toggle source
# File lib/couchbase/operations/get.rb, line 262
def get_bulk_extended(keys, options = {})
  {}.tap do |results|
    keys.each do |key|
      results[key] = get_extended(key, options)
    end
  end
end
get_extended(key, options = {}) click to toggle source
# File lib/couchbase/operations/get.rb, line 235
def get_extended(key, options = {})
  if options.key?(:lock)
    client_get_and_lock(key, options[:lock])
  end
  extended = client_get_extended(key)
  not_found_error(extended.nil?, options)
  extended
end
get_key(key, options) click to toggle source
# File lib/couchbase/operations/get.rb, line 200
def get_key(key, options)
  case key
  when String, Symbol
    get_single(key, options)
  when Array
    get_bulk(key, options)
  when Hash
    get_and_touch(key, options)
  end
end
get_single(key, options) click to toggle source
# File lib/couchbase/operations/get.rb, line 218
def get_single(key, options)
  if options[:lock]
    client_get_and_lock(key, options)
  elsif options[:extended]
    get_extended(key, options)
  else
    value = if options.key?(:ttl)
              client_get_and_touch(key, options[:ttl])
            else
              client.get(key)
            end

    not_found_error(value.nil?, options)
    value.nil? ? nil : value
  end
end
ordered_multi_values(keys, results) click to toggle source
# File lib/couchbase/operations/get.rb, line 270
def ordered_multi_values(keys, results)
  keys.map { |key| results[key] }
end