Class RightAws::SdbInterface
In: lib/sdb/right_sdb_interface.rb
Parent: RightAwsBase
RuntimeError AwsError AwsNoChange RightAWSParser RightErrorResponseParser RightHttp2xxParser AcfInterface SqsInterface SqsGen2Interface S3Interface Ec2 SdbInterface RightAwsBase ActiveSdbConnect ActiveSdb SqsGen2 S3 S3Generator Sqs RightDummyParser AWSErrorHandler AwsBenchmarkingBlock AwsUtils RightSaxParserCallback lib/sqs/right_sqs_interface.rb lib/sqs/right_sqs_gen2.rb lib/s3/right_s3.rb lib/acf/right_acf_interface.rb lib/sqs/right_sqs_gen2_interface.rb lib/sqs/right_sqs.rb lib/sdb/right_sdb_interface.rb lib/sdb/active_sdb.rb lib/ec2/right_ec2.rb lib/s3/right_s3_interface.rb lib/awsbase/right_awsbase.rb RightAwsBaseInterface VERSION RightAws dot/m_13_0.png

Methods

Included Modules

RightAwsBaseInterface

Constants

DEFAULT_HOST = 'sdb.amazonaws.com'
DEFAULT_PORT = 443
DEFAULT_PROTOCOL = 'https'
API_VERSION = '2007-11-07'
DEFAULT_NIL_REPRESENTATION = 'nil'

Attributes

last_query_expression  [R] 

Public Class methods

[Source]

    # File lib/sdb/right_sdb_interface.rb, line 40
40:     def self.bench_sdb; @@bench.service; end

[Source]

    # File lib/sdb/right_sdb_interface.rb, line 39
39:     def self.bench_xml; @@bench.xml;     end

Creates new RightSdb instance.

Params:

   { :server       => 'sdb.amazonaws.com'  # Amazon service host: 'sdb.amazonaws.com'(default)
     :port         => 443                  # Amazon service port: 80 or 443(default)
     :protocol     => 'https'              # Amazon service protocol: 'http' or 'https'(default)
     :signature_version => '0'             # The signature version : '0' or '1'(default)
     :multi_thread => true|false           # Multi-threaded (connection per each thread): true or false(default)
     :logger       => Logger Object        # Logger instance: logs to STDOUT if omitted
     :nil_representation => 'mynil'}       # interpret Ruby nil as this string value; i.e. use this string in SDB to represent Ruby nils (default is the string 'nil')

Example:

 sdb = RightAws::SdbInterface.new('1E3GDYEOGFJPIT7XXXXXX','hgTHt68JY07JKUY08ftHYtERkjgtfERn57XXXXXX', {:multi_thread => true, :logger => Logger.new('/tmp/x.log')}) #=> #<RightSdb:0xa6b8c27c>

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/

[Source]

    # File lib/sdb/right_sdb_interface.rb, line 61
61:     def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={})
62:       @nil_rep = params[:nil_representation] ? params[:nil_representation] : DEFAULT_NIL_REPRESENTATION
63:       params.delete(:nil_representation)
64:       init({ :name             => 'SDB', 
65:              :default_host     => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).host   : DEFAULT_HOST, 
66:              :default_port     => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).port   : DEFAULT_PORT, 
67:              :default_protocol => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).scheme : DEFAULT_PROTOCOL }, 
68:            aws_access_key_id     || ENV['AWS_ACCESS_KEY_ID'], 
69:            aws_secret_access_key || ENV['AWS_SECRET_ACCESS_KEY'], 
70:            params)
71:     end

Public Instance methods

Create new SDB domain at Amazon.

Returns a hash: { :box_usage, :request_id } on success or an exception on error. (Amazon raises no errors if the domain already exists).

Example:

 sdb = RightAws::SdbInterface.new
 sdb.create_domain('toys') # => { :box_usage  => "0.0000071759",
                                  :request_id => "976709f9-0111-2345-92cb-9ce90acd0982" }

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_CreateDomain.html

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 258
258:     def create_domain(domain_name)
259:       link = generate_request("CreateDomain",
260:                               'DomainName' => domain_name)
261:       request_info(link, QSdbSimpleParser.new)
262:     rescue Exception
263:       on_exception
264:     end

Delete value, attribute or item.

Example:

 # delete 'vodka' and 'girls' from 'Jon' and 'mice' from 'cat'.
 sdb.delete_attributes 'family', 'toys', { 'Jon' => ['vodka', 'girls'], 'cat' => ['mice'] }

 # delete the all the values from attributes (i.e. delete the attributes)
 sdb.delete_attributes 'family', 'toys', { 'Jon' => [], 'cat' => [] }
 # or
 sdb.delete_attributes 'family', 'toys', [ 'Jon', 'cat' ]

 # delete all the attributes from item 'toys' (i.e. delete the item)
 sdb.delete_attributes 'family', 'toys'

see docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_DeleteAttributes.html

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 390
390:     def delete_attributes(domain_name, item_name, attributes = nil)
391:       params = { 'DomainName' => domain_name,
392:                  'ItemName'   => item_name }.merge(pack_attributes(attributes))
393:       link = generate_request("DeleteAttributes", params)
394:       request_info( link, QSdbSimpleParser.new )
395:     rescue Exception
396:       on_exception
397:     end

Delete SDB domain at Amazon.

Returns a hash: { :box_usage, :request_id } on success or an exception on error. (Amazon raises no errors if the domain does not exist).

Example:

 sdb = RightAws::SdbInterface.new
 sdb.delete_domain('toys') # => { :box_usage  => "0.0000071759",
                                  :request_id => "976709f9-0111-2345-92cb-9ce90acd0982" }

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_DeleteDomain.html

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 279
279:     def delete_domain(domain_name)
280:       link = generate_request("DeleteDomain",
281:                               'DomainName' => domain_name)
282:       request_info(link, QSdbSimpleParser.new)
283:     rescue Exception
284:       on_exception
285:     end

Use this helper to manually escape the fields in the query expressions. To escape the single quotes and backslashes and to wrap the string into the single quotes.

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API.html

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 148
148:     def escape(value)
149:       %Q{'#{value.to_s.gsub(/(['\\])/){ "\\#{$1}" }}'} if value
150:     end

Retrieve SDB item‘s attribute(s).

Returns a hash:

 { :box_usage  => string,
   :request_id => string,
   :attributes => { 'nameA' => [valueA1,..., valueAN],
                    ... ,
                    'nameZ' => [valueZ1,..., valueZN] } }

Example:

 # request all attributes
 sdb.get_attributes('family', 'toys') # => { :attributes => {"cat"    => ["clew", "Jons_socks", "mouse"] },
                                                             "Silvia" => ["beetle", "rolling_pin", "kids"],
                                                             "Jon"    => ["vacuum_cleaner", "hammer", "spade"]},
                                             :box_usage  => "0.0000093222",
                                             :request_id => "81273d21-000-1111-b3f9-512d91d29ac8" }

 # request cat's attributes only
 sdb.get_attributes('family', 'toys', 'cat') # => { :attributes => {"cat" => ["clew", "Jons_socks", "mouse"] },
                                                    :box_usage  => "0.0000093222",
                                                    :request_id => "81273d21-001-1111-b3f9-512d91d29ac8" }

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_GetAttributes.html

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 361
361:     def get_attributes(domain_name, item_name, attribute_name=nil)
362:       link = generate_request("GetAttributes", 'DomainName'    => domain_name,
363:                                                'ItemName'      => item_name,
364:                                                'AttributeName' => attribute_name )
365:       res = request_info(link, QSdbGetAttributesParser.new)
366:       res[:attributes].each_value do |values|
367:         values.collect! { |e| sdb_to_ruby(e) }
368:       end
369:       res
370:     rescue Exception
371:       on_exception
372:     end

Retrieve a list of SDB domains from Amazon.

Returns a hash:

  { :domains     => [domain1, ..., domainN],
    :next_token => string || nil,
    :box_usage   => string,
    :request_id  => string }

Example:

 sdb = RightAws::SdbInterface.new
 sdb.list_domains  #=> { :box_usage  => "0.0000071759",
                         :request_id => "976709f9-0111-2345-92cb-9ce90acd0982",
                         :domains    => ["toys", "dolls"]}

If a block is given, this method yields to it. If the block returns true, list_domains will continue looping the request. If the block returns false, list_domains will end.

  sdb.list_domains(10) do |result|   # list by 10 domains per iteration
    puts result.inspect
    true
  end

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_ListDomains.html

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 226
226:     def list_domains(max_number_of_domains = nil, next_token = nil )
227:       request_params = { 'MaxNumberOfDomains' => max_number_of_domains,
228:                          'NextToken'          => next_token }
229:       link   = generate_request("ListDomains", request_params)
230:       result = request_info(link, QSdbListDomainParser.new)
231:       # return result if no block given
232:       return result unless block_given?
233:       # loop if block if given
234:       begin
235:         # the block must return true if it wanna continue 
236:         break unless yield(result) && result[:next_token]
237:         # make new request
238:         request_params['NextToken'] = result[:next_token]
239:         link   = generate_request("ListDomains", request_params)
240:         result = request_info(link, QSdbListDomainParser.new)
241:       end while true
242:     rescue Exception
243:       on_exception
244:     end

Add/Replace item attributes.

Params:

 domain_name = DomainName
 item_name   = ItemName
 attributes  = {
   'nameA' => [valueA1,..., valueAN],
   ...
   'nameZ' => [valueZ1,..., valueZN]
 }
 replace = :replace | any other value to skip replacement

Returns a hash: { :box_usage, :request_id } on success or an exception on error. (Amazon raises no errors if the attribute was not overridden, as when the :replace param is unset).

Example:

 sdb = RightAws::SdbInterface.new
 sdb.create_domain 'family'

 attributes = {}
 # create attributes for Jon and Silvia
 attributes['Jon']    = %w{ car beer }
 attributes['Silvia'] = %w{ beetle rolling_pin kids }
 sdb.put_attributes 'family', 'toys', attributes   #=> ok
 # now: Jon=>[car, beer], Silvia=>[beetle, rolling_pin, kids]

 # add attributes to Jon
 attributes.delete('Silvia')
 attributes['Jon'] = %w{ girls pub }
 sdb.put_attributes 'family', 'toys', attributes   #=> ok
 # now: Jon=>[car, beer, girls, pub], Silvia=>[beetle, rolling_pin, kids]

 # replace attributes for Jon and add to a cat (the cat had no attributes before)
 attributes['Jon'] = %w{ vacuum_cleaner hammer spade }
 attributes['cat'] = %w{ mouse clew Jons_socks }
 sdb.put_attributes 'family', 'toys', attributes, :replace #=> ok
 # now: Jon=>[vacuum_cleaner, hammer, spade], Silvia=>[beetle, rolling_pin, kids], cat=>[mouse, clew, Jons_socks]

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_PutAttributes.html

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 328
328:     def put_attributes(domain_name, item_name, attributes, replace = false)
329:       params = { 'DomainName' => domain_name,
330:                  'ItemName'   => item_name }.merge(pack_attributes(attributes, replace))
331:       link = generate_request("PutAttributes", params)
332:       request_info( link, QSdbSimpleParser.new )
333:     rescue Exception
334:       on_exception
335:     end

Perform a query on SDB.

Returns a hash:

  { :box_usage  => string,
    :request_id => string,
    :next_token => string,
    :items      => [ItemName1,..., ItemNameN] }

Example:

  query = "['cat' = 'clew']"
  sdb.query('family', query)     #=> hash of data
  sdb.query('family', query, 10) #=> hash of data with max of 10 items

If a block is given, query will iteratively yield results to it as long as the block continues to return true.

  # List 10 items per iteration. Don't
  # forget to escape single quotes and backslashes and wrap all the items in single quotes.
  query = "['cat'='clew'] union ['dog'='Jon\\'s boot']"
  sdb.query('family', query, 10) do |result|
    puts result.inspect
    true
  end

  # Same query using automatic escaping...to use the auto escape, pass the query and its params as an array:
  query = [ "['cat'=?] union ['dog'=?]", "clew", "Jon's boot" ]
  sdb.query('family', query)

  query = [ "['cat'=?] union ['dog'=?] sort 'cat' desc", "clew", "Jon's boot" ]
  sdb.query('family', query)

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/SDB_API_Query.html

     http://docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?SortingData.html

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 436
436:     def query(domain_name, query_expression = nil, max_number_of_items = nil, next_token = nil)
437:       query_expression = query_expression_from_array(query_expression) if query_expression.is_a?(Array)
438:       @last_query_expression = query_expression
439:       #
440:       request_params = { 'DomainName'       => domain_name,
441:                          'QueryExpression'  => query_expression,
442:                          'MaxNumberOfItems' => max_number_of_items,
443:                          'NextToken'        => next_token }
444:       link   = generate_request("Query", request_params)
445:       result = request_info( link, QSdbQueryParser.new )
446:       # return result if no block given
447:       return result unless block_given?
448:       # loop if block if given
449:       begin
450:         # the block must return true if it wanna continue 
451:         break unless yield(result) && result[:next_token]
452:         # make new request
453:         request_params['NextToken'] = result[:next_token]
454:         link   = generate_request("Query", request_params)
455:         result = request_info( link, QSdbQueryParser.new )
456:       end while true
457:     rescue Exception
458:       on_exception
459:     end

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 192
192:     def query_expression_from_hash(hash)
193:       return '' if hash.blank?
194:       expression = []
195:       hash.each do |key, value|
196:         expression << "#{key}=#{escape(value)}"
197:       end
198:       expression.join(' AND ')
199:     end

Perform a query and fetch specified attributes. If attributes are not specified then fetches the whole list of attributes.

Returns a hash:

  { :box_usage  => string,
    :request_id => string,
    :next_token => string,
    :items      => [ { ItemName1 => { attribute1 => value1, ...  attributeM => valueM } },
                     { ItemName2 => {...}}, ... ]

Example:

  sdb.query_with_attributes(domain, ['hobby', 'country'], "['gender'='female'] intersection ['name' starts-with ''] sort 'name'") #=>
    { :request_id => "06057228-70d0-4487-89fb-fd9c028580d3",
      :items =>
        [ { "035f1ba8-dbd8-11dd-80bd-001bfc466dd7"=>
            { "hobby"   => ["cooking", "flowers", "cats"],
              "country" => ["Russia"]}},
          { "0327614a-dbd8-11dd-80bd-001bfc466dd7"=>
            { "hobby"   => ["patchwork", "bundle jumping"],
              "country" => ["USA"]}}, ... ],
       :box_usage=>"0.0000504786"}

  sdb.query_with_attributes(domain, [], "['gender'='female'] intersection ['name' starts-with ''] sort 'name'") #=>
    { :request_id => "75bb19db-a529-4f69-b86f-5e3800f79a45",
      :items =>
      [ { "035f1ba8-dbd8-11dd-80bd-001bfc466dd7"=>
          { "hobby"   => ["cooking", "flowers", "cats"],
            "name"    => ["Mary"],
            "country" => ["Russia"],
            "gender"  => ["female"],
            "id"      => ["035f1ba8-dbd8-11dd-80bd-001bfc466dd7"]}},
        { "0327614a-dbd8-11dd-80bd-001bfc466dd7"=>
          { "hobby"   => ["patchwork", "bundle jumping"],
            "name"    => ["Mary"],
            "country" => ["USA"],
            "gender"  => ["female"],
            "id"      => ["0327614a-dbd8-11dd-80bd-001bfc466dd7"]}}, ... ],
     :box_usage=>"0.0000506668"}

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?SDB_API_QueryWithAttributes.html

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 504
504:     def query_with_attributes(domain_name, attributes=[], query_expression = nil, max_number_of_items = nil, next_token = nil)
505:       attributes = attributes.to_a
506:       query_expression = query_expression_from_array(query_expression) if query_expression.is_a?(Array)
507:       @last_query_expression = query_expression
508:       #
509:       request_params = { 'DomainName'       => domain_name,
510:                          'QueryExpression'  => query_expression,
511:                          'MaxNumberOfItems' => max_number_of_items,
512:                          'NextToken'        => next_token }
513:       attributes.each_with_index do |attribute, idx|
514:         request_params["AttributeName.#{idx+1}"] = attribute
515:       end
516:       link   = generate_request("QueryWithAttributes", request_params)
517:       result = select_response_to_ruby(request_info( link, QSdbQueryWithAttributesParser.new ))
518:       # return result if no block given
519:       return result unless block_given?
520:       # loop if block if given
521:       begin
522:         # the block must return true if it wanna continue
523:         break unless yield(result) && result[:next_token]
524:         # make new request
525:         request_params['NextToken'] = result[:next_token]
526:         link   = generate_request("QueryWithAttributes", request_params)
527:         result = select_response_to_ruby(request_info( link, QSdbQueryWithAttributesParser.new ))
528:       end while true
529:     rescue Exception
530:       on_exception
531:     end

Convert a Ruby language value to a SDB value by replacing Ruby nil with the user‘s chosen string representation of nil. Non-nil values are unaffected by this filter.

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 154
154:     def ruby_to_sdb(value)
155:       value.nil? ? @nil_rep : value
156:     end

Convert a SDB value to a Ruby language value by replacing the user‘s chosen string representation of nil with Ruby nil. Values are unaffected by this filter unless they match the nil representation exactly.

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 160
160:     def sdb_to_ruby(value)
161:       value.eql?(@nil_rep) ? nil : value
162:     end

Perform SQL-like select and fetch attributes. Attribute values must be quoted with a single or double quote. If a quote appears within the attribute value, it must be escaped with the same quote symbol as shown in the following example. (Use array to pass select_expression params to avoid manual escaping).

 sdb.select(["select * from my_domain where gender=?", 'female']) #=>
   {:request_id =>"8241b843-0fb9-4d66-9100-effae12249ec",
    :items =>
     [ { "035f1ba8-dbd8-11dd-80bd-001bfc466dd7"=>
         {"hobby"   => ["cooking", "flowers", "cats"],
          "name"    => ["Mary"],
          "country" => ["Russia"],
          "gender"  => ["female"],
          "id"      => ["035f1ba8-dbd8-11dd-80bd-001bfc466dd7"]}},
       { "0327614a-dbd8-11dd-80bd-001bfc466dd7"=>
         {"hobby"   => ["patchwork", "bundle jumping"],
          "name"    => ["Mary"],
          "country" => ["USA"],
          "gender"  => ["female"],
          "id"      => ["0327614a-dbd8-11dd-80bd-001bfc466dd7"]}}, ... ]
    :box_usage =>"0.0000506197"}

  sdb.select('select country, name from my_domain') #=>
   {:request_id=>"b1600198-c317-413f-a8dc-4e7f864a940a",
    :items=>
     [ { "035f1ba8-dbd8-11dd-80bd-001bfc466dd7"=> {"name"=>["Mary"],     "country"=>["Russia"]} },
       { "376d2e00-75b0-11dd-9557-001bfc466dd7"=> {"name"=>["Putin"],    "country"=>["Russia"]} },
       { "0327614a-dbd8-11dd-80bd-001bfc466dd7"=> {"name"=>["Mary"],     "country"=>["USA"]}    },
       { "372ebbd4-75b0-11dd-9557-001bfc466dd7"=> {"name"=>["Bush"],     "country"=>["USA"]}    },
       { "37a4e552-75b0-11dd-9557-001bfc466dd7"=> {"name"=>["Medvedev"], "country"=>["Russia"]} },
       { "38278dfe-75b0-11dd-9557-001bfc466dd7"=> {"name"=>["Mary"],     "country"=>["Russia"]} },
       { "37df6c36-75b0-11dd-9557-001bfc466dd7"=> {"name"=>["Mary"],     "country"=>["USA"]}    } ],
    :box_usage=>"0.0000777663"}

see: docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?SDB_API_Select.html

     http://docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?UsingSelect.html
     http://docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?SDBLimits.html

[Source]

     # File lib/sdb/right_sdb_interface.rb, line 570
570:     def select(select_expression, next_token = nil)
571:       select_expression      = query_expression_from_array(select_expression) if select_expression.is_a?(Array)
572:       @last_query_expression = select_expression
573:       #
574:       request_params = { 'SelectExpression' => select_expression,
575:                          'NextToken'        => next_token }
576:       link   = generate_request("Select", request_params)
577:       result = select_response_to_ruby(request_info( link, QSdbSelectParser.new ))
578:       return result unless block_given?
579:       # loop if block if given
580:       begin
581:         # the block must return true if it wanna continue
582:         break unless yield(result) && result[:next_token]
583:         # make new request
584:         request_params['NextToken'] = result[:next_token]
585:         link   = generate_request("Select", request_params)
586:         result = select_response_to_ruby(request_info( link, QSdbSelectParser.new ))
587:       end while true
588:     rescue Exception
589:       on_exception
590:     end

[Validate]