amazon_sdb 0.6.0 → 0.6.5

data/History.txt

@@ -1,3 +1,9 @@
+== 0.6.5 / 2008-01-15
+* 3 major enhancements
+  * New usage tracking via the box_usage method
+  * Better docs
+  * Boolean coercion
+
 == 0.6.0 / 2007-12-28
 * 2 major enhancements
   * Correct error handling for API's HTTP responses (with tests)

data/README.txt

@@ -9,11 +9,11 @@ http://code.nytimes.com/svn/ruby/gems/amazon_sdb
 
 == DESCRIPTION:
   
-Amazon sdb is a Ruby wrapper to Amazon's new Simple Database Service. Amazon sdb is a different type of database:
+Amazon SDB is a Ruby wrapper to Amazon's new Simple Database Service. Amazon sdb is a different type of database:
 
 * Accessed over the network via RESTful calls
 * No schemas or types
-* Each sdb account can have up to 100 domains for data.
+* Each SimpleDB account can have up to 100 domains for data.
 * Domains can hold objects referenced by unique keys
 * Each object can hold up to 256 name/value attributes.
 * Only name/value pairs must be unique in an objects attributes, there can be multiple name/value attributes with the same name.
@@ -22,9 +22,9 @@ Amazon sdb is a Ruby wrapper to Amazon's new Simple Database Service. Amazon sdb
 
 == FEATURES:
   
-* A basic interface to Amazon sdb
-* Includes a class for representing attribute sets in sdb
-* Automatic conversion to/from sdb representations for integers and dates (for floats, it's suggested you use the Multimap#numeric function)
+* A basic interface to Amazon SimpleDB
+* Includes a class for representing attribute sets in SimpleDB
+* Automatic conversion to/from SimpleDB representations for integers and dates (for floats, it's suggested you use the Multimap#numeric function)
 * The beginnings of mock-based tests for methods derived from Amazon's docs
 
 == CAVEATS
@@ -41,7 +41,7 @@ Amazon sdb is a Ruby wrapper to Amazon's new Simple Database Service. Amazon sdb
 
 == SYNOPSIS:
 
-  b = Amazon::sdb::Base.new(aws_public_key, aws_secret_key)
+  b = Amazon::SDB::Base.new(aws_public_key, aws_secret_key)
 	b.domains #=> list of domain
 	domain = b.create_domain 'my domain'
 	

data/lib/amazon_sdb.rb

@@ -30,10 +30,11 @@ require 'amazon_sdb/domain'
 require 'amazon_sdb/item'
 require 'amazon_sdb/resultset'
 require 'amazon_sdb/exceptions'
+require 'amazon_sdb/usage'
 
 module Amazon
   module SDB
-    VERSION = '0.6.0'    
+    VERSION = '0.6.5'    
   end
 end
 

data/lib/amazon_sdb/base.rb

@@ -15,6 +15,8 @@ module Amazon
       def initialize(aws_access_key, aws_secret_key)
         @access_key = aws_access_key
         @secret_key = aws_secret_key
+        @usage = Usage.new
+        raise @usage
       end
 
       ##
@@ -32,16 +34,42 @@ module Amazon
         @@number_padding = num
       end
       
+      ##
+      # The number of digits after the decimal points to use by default
       def self.float_precision
         return @@float_precision
       end
       
+      ##
+      # Set the #float_precision
       def self.float_precision=(num)
         return @@float_precision
       end
 
       ##
-      # Retrieves a list of domains in your SDS database. Each entry is a Domain object.
+      # Returns the Box Usage accumulated since the beginning of the session. Box Usage represents computation time and is one of
+      # the parameters in your monthly SimpleDB bill. As an alternative, when passed a block (no parameters yielded), it returns 
+      # the box usage only for the operations within the block.
+      def box_usage
+        unless block_given?
+          @usage.box_usage
+        else
+          # return the usage of the actions in the block
+          usage1 = @usage.box_usage
+          yield
+          usage2 = @usage.box_usage
+          return usage2 - usage1
+        end
+      end
+      
+      ##
+      # Resets the box usage accumulated within the current session. Not sure why you'd need to do this, but it's provided.
+      def reset_usage!
+        @usage.reset!
+      end
+
+      ##
+      # Retrieves a list of domains in your SDS database. Each entry is a Domain object. 
       def domains
         domains = []
         nextToken = nil
@@ -67,10 +95,35 @@ module Amazon
       end
 
       ##
-      # Returns a domain object for SDS. Assumes the domain already exists, so errors might occur if you didn't create it.
+      # Returns a domain object for SimpleDB. Assumes the domain already exists, so a ParameterError (NoSuchDomain) might occur if it's not there. This
+      # method is useful for getting a domain object without having to incur the operational costs of querying all domains.
       def domain(name)
         Domain.new(@access_key, @secret_key, name)
       end
+      
+      ##
+      # Creates a domain. This operation is idempotent, but it is slow and if you are sure the domain already exists, you might
+      # want to use the #domain method instead. Each SimpleDB account is allowed up to 100 domains; a LimitError will be raised
+      # if you attempt to create more.
+      def create_domain(name)
+        sdb_query({:Action => 'CreateDomain', 'DomainName' => name}) do |h|
+          domain(name)
+        end
+      end
+
+      ##
+      # Deletes a domain. Running this command multiple times or on a domain that does not exist will NOT return an error.
+      def delete_domain!(name)
+        sdb_query({:Action => 'DeleteDomain', 'DomainName' => name})
+      end
+
+    private
+      def parse_usage(hpricot)
+        usagenode = hpricot.at('//BoxUsage')
+        return unless usagenode
+        
+        @usage.add_usage usagenode.innerText.to_f
+      end
 
       def raise_errors(hpricot)
         errnode = hpricot.at('//Errors/Error')
@@ -102,18 +155,6 @@ module Amazon
         end
       end
       
-      def create_domain(name)
-        sdb_query({:Action => 'CreateDomain', 'DomainName' => name}) do |h|
-          domain(name)
-        end
-      end
-
-      ##
-      # Deletes a domain. This operation is currently not supported by SDS.
-      def delete_domain!(name)
-        sdb_query({:Action => 'DeleteDomain', 'DomainName' => name})
-      end
-
       def timestamp
         Time.now.iso8601
       end
@@ -148,11 +189,13 @@ module Amazon
           open(url) do |f|
             h = Hpricot.XML(f)
 
+            parse_usage h
             raise_errors h
             yield h if block_given?
           end
         rescue OpenURI::HTTPError => e
           h = Hpricot.XML(e.io.read)
+          parse_usage h
           raise_errors h
         end
       end
@@ -166,7 +209,6 @@ module Amazon
         return hmac(key, option_array.map {|pair| pair[0]+pair[1]}.join('')).chop
       end
 
-    private
       @@number_padding                 = 32
       @@float_precision                = 8
 

data/lib/amazon_sdb/domain.rb

@@ -22,9 +22,9 @@ module Amazon
       ##
       # Sets attributes for a given key in the domain. If there are no attributes supplied, it creates an empty set.
       # Takes the following arguments:
-      # - key - a string key for the attribute set
-      # - multimap - an collection of attributes for the set in a Multimap object. If nothing, creates an empty set.
-      # - options - for put options
+      # - <tt>key</tt> - a string key for the attribute set
+      # - <tt>multimap</tt> - an collection of attributes for the set in a Multimap object (can convert a Hash and Array too). If nothing, creates an empty set.
+      # - <tt>options</tt> - for put options. Currently the only option is :replace, which either takes an array of attribute names to replace or :all for all of them
       def put_attributes(key, multimap=nil, options = {})
         req_options = {'Action' => 'PutAttributes', 'DomainName' => name, 'ItemName' => key}
         
@@ -52,6 +52,7 @@ module Amazon
       ##
       # Gets the attribute list for a key. Arguments:
       # - <tt>key</tt> - the key for the attribute set
+      # - <tt>attr_list</tt> - by default, this function returns all the attributes of an item. If you wanted to limit the response to only a few named attributes, you can pass them here.
       def get_attributes(key, *attr_list)
         options = {'Action' => 'GetAttributes', 'DomainName' => name, 'ItemName' => key}
         
@@ -75,7 +76,9 @@ module Amazon
       end
 
       ##
-      # Not implemented yet.
+      # Deletes the attributes associated with a particular item. If the optional <tt>multimap</tt> argument is nil, deletes the entire
+      # object. Otherwise, the optional multimap argument can be used to delete specific key/value pairs in the object (also accepts
+      # a String or Symbol for a single name, an Array for multiple keys or a Hash for key/value pairs)
       def delete_attributes(key, multimap=nil)
         options = {'Action' => 'DeleteAttributes', 'DomainName' => name, 'ItemName' => key}
         
@@ -106,9 +109,10 @@ module Amazon
       ##
       # Returns a list of matching items that match a filter
       # Options include:
-      # - <tt>max_results</tt> = the max items to return for a listing (top/default is 100)
-      # - <tt>:more_token</tt> = to retrieve a second or more page of results, the more token should be provided
-      # - <tt>:load_attrs</tt> = this query normally returns just a list of names, the attributes have to be retrieved separately. To load the attributes for matching results automatically, set to true (normally false)
+      # - <tt>:expr</tt> - a query expression to evaluate (see the Amazon SimpleDB documentation for details)
+      # - <tt>:max_results</tt> - the max items to return for a listing (top/default is 100)
+      # - <tt>:next_token</tt> - to retrieve a second or more page of results, the more token should be provided
+      # - <tt>:load_attrs</tt> - this query normally returns just a list of names, the attributes have to be retrieved separately. To load the attributes for matching results automatically, set to true (normally false). Be aware this will lead to N additional requests to SimpleDB.
       def query(query_options = {})
         req_options = {'Action' => 'Query', 'DomainName' => name}
         

data/lib/amazon_sdb/exceptions.rb

@@ -4,46 +4,80 @@ module Amazon
     end
     
     ACCESS_ERROR_CODES = %w{AccessFailure}
+
+    ##
+    # The AccessError represents access problems connecting to SimpleDB
     class AccessError < Error
     end
     
     AUTH_ERROR_CODES = %w{AuthFailure AuthMissingFailure InvalidHTTPAuthHeader OptInRequired}
+
+    ##
+    # AuthError represents several different authentication problems that may occur when connecting to Amazon SimpleDB. See the
+    # message for details.
     class AuthError < Error
     end
     
     PARAMETER_ERROR_CODES = %w(InvalidAction InvalidNextToken InvalidParameterError 
     InvalidParameterCombination InvalidParameterValue MissingAction MissingParameter NoSuchDomain
     )
+
+    ## 
+    # ParameterError is returned when a parameter to SimpleDB is invalid or missing. See the error for details.
     class ParameterError < Error
     end
     
     QUERY_ERROR_CODES = %w{InvalidNumberPredicates InvalidNumberValueTests InvalidQueryExpression}
+    
+    ##
+    # The QuerySyntaxError covers several errors that may result from an invalid <tt>:expr</tt> passed into the Domain#Query method.
     class QuerySyntaxError < Error
     end
     
     LIMIT_ERROR_CODES = %w{NumberDomainsExceeded NumberDomainAttributesExceeded NumberDomainBytesExceeded NumberDomainBytesExceeeded URITooLong}
+  
+    ##
+    # A LimitError is returned when you hit one of the fundamental limits for SimpleDB accounts. See the message content for details.
     class LimitError < Error
     end
     
     SERVER_ERROR_CODES = %w{InternalError ServiceOverload ServiceUnavailable}
+    
+    ##
+    # ServerErrors represent server problems on SimpleDB.
     class ServerError < Error
     end
     
+    ##
+    # Huh? What? For when SimpleDB sends me an error code I've never seen before (and isn't in the docs)
     class UnknownError < Error
     end
     
     REQUEST_ERROR_CODES = %w{InvalidHttpRequest InvalidSOAPRequest InvalidURI InvalidService UnsupportedHttpVerb}
+    
+    ##
+    # For incorrectly constructed HTTP queries against the SimpleDB server. If you see this error, it's my fault, and let me know
+    # the command that caused it.
     class RequestError < Error
     end
     
     TIMEOUT_ERROR_CODES = %w{RequestExpired RequestTimeout RequestThrottled}
+    
+    ##
+    # Amazon SimpleDB times out any operation that lasts more than 5 seconds. This error will be returned.
     class TimeoutError < Error
     end
     
     VERSION_ERROR_CODES = %w{FeatureDeprecated NoSuchVersion NotYetImplemented}
+    
+    ##
+    # For when there is a mismatch between this gem and the API being called.
     class VersionError < Error
     end
     
+    ##
+    # When GetAttributes doesn't match, Amazon returns an empty record. I prefer to raise an exception instead, so there will be no
+    # confusion.
     class RecordNotFoundError < Error
     end
   end

data/lib/amazon_sdb/item.rb

@@ -1,7 +1,7 @@
 module Amazon
   module SDB
     ##
-    # An item from sdb. This basically is a key for the item in the domain and a Multimap of the attributes. You should never
+    # An item from SimpleDB. This basically is a key for the item in the domain and a Multimap of the attributes. You should never
     # call Item#new, instead it is returned by various methods in Domain and ResultSet
     class Item
       include Enumerable
@@ -13,23 +13,34 @@ module Amazon
         @attributes = multimap
       end
       
+      ##
+      # Reloads from the domain
       def reload!
         item = @domain.get_attributes(@key)
         @attributes = item.attributes
       end
       
+      ##
+      # Returns true if the attributes are empty
       def empty?
+        return true if @attributes.nil?
         @attributes.size == 0
       end
       
+      ##
+      # Deletes the item in SimpleDB
       def destroy!
         @domain.delete_attributes(@key)
       end
       
+      ##
+      # Saves the item back (like a put_attributes with :replace => :all
       def save
-        @domain.put_attributes(@key, @attributes)
+        @domain.put_attributes(@key, @attributes, :replace => :all)
       end
       
+      ##
+      # Reloads the item if necessary
       def get(key)
         reload! if @attributes.nil?
         @attributes.get(key)

data/lib/amazon_sdb/multimap.rb

@@ -172,6 +172,10 @@ module Amazon
 
       def sdb_value_escape(value)
         case value
+        when TrueClass
+          "true"
+        when FalseClass
+          "false"
         when Fixnum
           sprintf("%0#{Base.number_padding}d", value)
         when Float
@@ -204,6 +208,10 @@ module Amazon
 
       def coerce(value)
         case value
+        when 'true'
+          true
+        when 'false'
+          false
         when /^0+\d+$/
           value.to_i
         when /^0+\d*.\d+$/

data/test/test_item.rb

@@ -0,0 +1,56 @@
+require "test_sdb_harness"
+
+class TestItem < Test::Unit::TestCase
+  def setup
+    @domain = Amazon::SDB::Domain.new 'API_KEY', 'SECRET_KEY', 'testdb'
+    @key = 'TEST_ITEM'
+    @multimap = Amazon::SDB::Multimap.new({"foo" => "bar", "baz" => "quux"})
+    
+    @empty_item = Amazon::SDB::Item.new(@domain, @key)
+    @item = Amazon::SDB::Item.new(@domain, @key, @multimap)
+  end
+
+  def test_save
+    @domain.responses << generic_response('PutAttributes')
+    @item.save
+    
+    assert_in_url_query({'Action' => 'PutAttributes', 'DomainName' => 'testdb', 'ItemName' => 'TEST_ITEM', 
+                         'Attribute.0.Replace' => 'true', 'Attribute.1.Replace' => 'true'}, @domain.uris.first)
+  end
+  
+  def test_reload!
+    # tests sends a get attributes
+    @domain.responses << <<-EOF
+    <GetAttributesResponse xmlns="http://sdb.amazonaws.com/doc/2007-11-07"> 
+    <GetAttributesResult> 
+    <Attribute><Name>Color</Name><Value>Blue</Value></Attribute> 
+    <Attribute><Name>Size</Name><Value>Med</Value></Attribute> 
+    <Attribute><Name>Price</Name><Value>14</Value></Attribute> 
+    </GetAttributesResult> 
+    <ResponseMetadata> 
+    <RequestId>b1e8f1f7-42e9-494c-ad09-2674e557526d</RequestId> 
+    <BoxUsage>0.0000219907/<BoxUsage> 
+    </ResponseMetadata> 
+    </GetAttributesResponse> 
+    EOF
+    
+    @item.reload!
+    
+    assert_in_url_query({'Action' => 'GetAttributes', 'DomainName' => 'testdb', 'ItemName' => 'TEST_ITEM'}, @domain.uris.first)
+  end
+  
+  def test_empty?
+    assert @empty_item.empty?
+    assert !@item.empty?
+  end
+  
+  def test_destroy!
+    # tests sends a delete attributes with 0 attrs
+    @domain.responses << generic_response('DeleteAttributes')
+    
+    @item.destroy!
+    assert_in_url_query({'Action' => 'DeleteAttributes', 'DomainName' => 'testdb', 'ItemName' => 'TEST_ITEM'}, @domain.uris.first)
+  end
+end
+  
+  

data/test/test_multimap.rb

@@ -105,6 +105,12 @@ class TestMultimap < Test::Unit::TestCase
     @m['Num'] = Amazon::SDB::Multimap.numeric(12.34, 10, 4)
     assert_equal '00012.3400', @m['Num']
   end
+  
+  def test_boolean_to_sdb
+    @m['a'] = true
+   
+    assert_equal 'true', @m.to_sdb['Attribute.0.Value']
+  end
     
   def test_to_sdb_replace_all
     @m[:a] = "foo"
@@ -166,6 +172,14 @@ class TestMultimap < Test::Unit::TestCase
     assert_equal "0000000000034.3400000000", m.get("a", :before_cast => true)
   end
   
+  def test_coerce_boolean
+    m = Multimap.new
+    m.from_sdb([["a", "true"], ["b", "false"]])
+  
+    assert_equal true, m["a"]
+    assert_equal false, m["b"]
+  end
+  
   def test_coerce_datetime
     now = Time.now
     

data/test/test_sdb_harness.rb

@@ -9,6 +9,7 @@ class Amazon::SDB::Base
   def initialize(aws_access_key, aws_secret_key)
     @access_key = aws_access_key
     @secret_key = aws_secret_key
+    @usage = Amazon::SDB::Usage.new
     @responses = []
     @uris = []  
   end

data/test/test_usage.rb

@@ -0,0 +1,113 @@
+require "test_sdb_harness"
+
+class TestUsage < Test::Unit::TestCase
+  include Amazon::SDB
+  
+  def setup
+    @sdb = Amazon::SDB::Base.new 'API_KEY', 'SECRET_KEY' 
+  end
+  
+  def test_accumulate
+    u = Amazon::SDB::Usage.new
+    
+    u << 0.50
+    u << 0.25
+    
+    assert_in_delta(0.75, u.box_usage, 2 ** -20)
+  end
+  
+  def test_reset
+    u = Amazon::SDB::Usage.new
+    
+    u << 0.50
+    u << 0.25
+    
+    u.reset!
+    
+    assert_in_delta(0.0, u.box_usage, 2 ** -20)
+  end
+  
+  def test_request_usage
+    @sdb.responses << <<-EOF
+    <?xml version="1.0" encoding="utf-8" ?>
+    <ListDomainsResponse xmlns="http://sdb.amazonaws.com/doc/2007-11-07"> 
+    <ListDomainsResult> 
+    <DomainName>foo</DomainName> 
+    <DomainName>bar</DomainName>
+    <DomainName>baz</DomainName> 
+    </ListDomainsResult> 
+    <ResponseMetadata> 
+    <RequestId>eb13162f-1b95-4511-8b12-489b86acfd28</RequestId> 
+    <BoxUsage>0.00777</BoxUsage> 
+    </ResponseMetadata> 
+    </ListDomainsResponse> 
+    EOF
+     
+    @sdb.domains
+    
+    assert_in_delta(0.00777, @sdb.box_usage, 2 ** -20)
+  end
+  
+  def test_error_usage
+    @sdb.responses << error_response('RequestTimeout')
+
+    assert_raise(Amazon::SDB::TimeoutError) { @sdb.domains }
+    assert_in_delta(0.0000219907, @sdb.box_usage, 2 ** -20)
+  end
+  
+  def test_block_usage
+    @sdb.responses << <<-EOF
+    <?xml version="1.0" encoding="utf-8" ?>
+    <ListDomainsResponse xmlns="http://sdb.amazonaws.com/doc/2007-11-07"> 
+    <ListDomainsResult> 
+    <DomainName>foo</DomainName> 
+    <DomainName>bar</DomainName>
+    <DomainName>baz</DomainName> 
+    </ListDomainsResult> 
+    <ResponseMetadata> 
+    <RequestId>eb13162f-1b95-4511-8b12-489b86acfd28</RequestId> 
+    <BoxUsage>0.50</BoxUsage> 
+    </ResponseMetadata> 
+    </ListDomainsResponse> 
+    EOF
+    
+    @sdb.responses << <<-EOF
+    <?xml version="1.0" encoding="utf-8" ?>
+    <ListDomainsResponse xmlns="http://sdb.amazonaws.com/doc/2007-11-07"> 
+    <ListDomainsResult> 
+    <DomainName>foo</DomainName> 
+    <DomainName>bar</DomainName>
+    <DomainName>baz</DomainName> 
+    </ListDomainsResult> 
+    <ResponseMetadata> 
+    <RequestId>eb13162f-1b95-4511-8b12-489b86acfd28</RequestId> 
+    <BoxUsage>0.25</BoxUsage> 
+    </ResponseMetadata> 
+    </ListDomainsResponse> 
+    EOF
+    
+    @sdb.responses << <<-EOF
+    <?xml version="1.0" encoding="utf-8" ?>
+    <ListDomainsResponse xmlns="http://sdb.amazonaws.com/doc/2007-11-07"> 
+    <ListDomainsResult> 
+    <DomainName>foo</DomainName> 
+    <DomainName>bar</DomainName>
+    <DomainName>baz</DomainName> 
+    </ListDomainsResult> 
+    <ResponseMetadata> 
+    <RequestId>eb13162f-1b95-4511-8b12-489b86acfd28</RequestId> 
+    <BoxUsage>0.01</BoxUsage> 
+    </ResponseMetadata> 
+    </ListDomainsResponse> 
+    EOF
+    
+    @sdb.domains
+    
+    usage = @sdb.box_usage do
+      @sdb.domains
+      @sdb.domains
+    end
+    
+    assert_in_delta(0.26, usage, 2 ** -20)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: amazon_sdb
 version: !ruby/object:Gem::Version 
-  version: 0.6.0
+  version: 0.6.5
 platform: ruby
 authors: 
 - Jacob Harris
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2007-12-28 00:00:00 -05:00
+date: 2008-01-14 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -79,7 +79,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: nytimes
-rubygems_version: 1.0.0
+rubygems_version: 1.0.1
 signing_key: 
 specification_version: 2
 summary: A ruby wrapper to Amazon's sdb service
@@ -87,5 +87,7 @@ test_files:
 - test/test_amazon_base.rb
 - test/test_amazon_domain.rb
 - test/test_exceptions.rb
+- test/test_item.rb
 - test/test_multimap.rb
 - test/test_sdb_harness.rb
+- test/test_usage.rb