lib/amazon_sdb/usage.rb test/test_item.rb test/test_usage.rb @@ -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) History.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' README.txt @@ -30,6 +30,7 @@ require 'amazon_sdb/domain' require 'amazon_sdb/item' require 'amazon_sdb/resultset' require 'amazon_sdb/exceptions' +require 'amazon_sdb/usage' module Amazon module SDB lib/amazon_sdb.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 lib/amazon_sdb/base.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} lib/amazon_sdb/domain.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 lib/amazon_sdb/exceptions.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) lib/amazon_sdb/item.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+$/ lib/amazon_sdb/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 test/test_multimap.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 test/test_sdb_harness.rb 48f5498f8b23e0b7145f2c07eb4e173edd375dc8 harrisj harrisj@f6ba467f-1a71-446b-a959-e5960c5d402f http://github.com/harrisj/amazon-sdb/commit/ca9957146205f702f610080c521a202879a83203 ca9957146205f702f610080c521a202879a83203 2008-01-14T19:56:07-08:00 2008-01-14T19:56:07-08:00 amazon_sdb: new usage class, testing for item methods, rdoc improvements git-svn-id: svn+ssh://code.nytimes.com/var/open/repos/ruby/gems/amazon_sdb@12 f6ba467f-1a71-446b-a959-e5960c5d402f 4cebca15b94af91bac6e85578cf5286fbd00f39d harrisj harrisj@f6ba467f-1a71-446b-a959-e5960c5d402f