amazon_sdb 0.5.5

data/lib/amazon_sdb/exceptions.rb

@@ -0,0 +1,18 @@
+module Amazon
+  module SDB
+    class InvalidParameterError < ArgumentError
+    end
+    
+    class LimitError < Exception
+    end
+    
+    class DomainLimitError < LimitError
+    end
+    
+    class UnknownError < Exception
+    end
+    
+    class RecordNotFoundError < Exception
+    end
+  end
+end

data/lib/amazon_sdb/item.rb

@@ -0,0 +1,51 @@
+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
+    # call Item#new, instead it is returned by various methods in Domain and ResultSet
+    class Item
+      include Enumerable
+      attr_accessor :key, :attributes
+      
+      def initialize(domain, key, multimap=nil)
+        @domain = domain
+        @key = key
+        @attributes = multimap
+      end
+      
+      def reload!
+        item = @domain.get_attributes(@key)
+        @attributes = item.attributes
+      end
+      
+      def empty?
+        @attributes.size == 0
+      end
+      
+      def destroy!
+        @domain.delete_attributes(@key)
+      end
+      
+      def save
+        @domain.put_attributes(@key, @attributes)
+      end
+      
+      def get(key)
+        reload! if @attributes.nil?
+        @attributes.get(key)
+      end
+      
+      def [](key)
+        get(key)
+      end
+      
+      def each
+        @attributes.each
+      end
+      
+      def each_pair
+        @attributes.each_pair
+      end
+    end
+  end
+end

data/lib/amazon_sdb/multimap.rb

@@ -0,0 +1,267 @@
+module Amazon
+  module SDB
+    ##
+    # A multimap is like a hash or set, but it only requires that key/value pair is unique (the same key may have multiple values).
+    # Multimaps may be created by the user to send into Amazon sdb or they may be read back from sdb as the attributes for an object.
+    #
+    # For your convenience, multimap's initializer can take several types of input parameters:
+    # - A hash of key/value pairs (for when you want keys to be unique)
+    # - An array of key/value pairs represented as 2-member arrays
+    # - Another multimap
+    # - Or nothing at all (an empty set)
+    class Multimap
+      include Enumerable
+      
+      ##
+      # To be honest, floats are difficult for sdb. In order to work with lexical comparisons, you need to save floats as strings padded to the same size.
+      # The problem is, automatic conversion can run afoul of rounding errors if it has a larger precision than the original float, 
+      # so for the short term I've provided the numeric helper method for saving floats as strings into the multimap (when read back from
+      # sdb they will still be converted from floats). To use, specify the precision you want to represent as well as the total size (pick something large like 32 to be safe)
+      def self.numeric(float, size, precision)
+        sprintf "%0#{size}.#{precision}f", float
+      end
+      
+      def initialize(init=nil)
+        @mset = {}
+
+        clear_size!
+
+        if init.nil?
+          # do nothing
+        elsif init.is_a? Hash
+          init.each {|k, v| put(k, v) }
+        elsif init.is_a? Array
+          # load from array
+          if init.any? {|v| ! v.is_a? Array || v.size != 2 }
+            raise ArgumentError, "Array must be of key/value pairs only"
+          end
+
+          init.each {|v| self.put(v[0], v[1])}
+        elsif init.is_a? Multimap
+          @mset = init.mset.dup
+        else
+          raise ArgumentError, "Wrong type passed as initializer"
+        end
+      end
+
+      def clear_size!
+        @size = nil
+      end
+      
+      ##
+      # Returns the size of the multimap. This is the total number of key/value pairs in it.
+      def size
+        if @size.nil?
+          @size = @mset.inject(0) do |total, pair|
+            value = pair[1]
+            if value.is_a? Array
+              total + value.size
+            else
+              total + 1
+            end
+          end
+        end
+
+        @size
+      end
+
+      ##
+      # Save a key/value attribute into the multimap. Takes additional options
+      # - <tt>:replace => true</tt> remove any attributes with the same key before insert (otherwise, appends)
+      def put(key_arg, value, options = {})
+        key = key_arg.to_s
+
+        if options[:before_cast]
+          key = "#{key}_before_cast"
+        end
+
+        k = @mset[key]
+        clear_size!
+
+        if k.nil? || options[:replace]
+          @mset[key] = value
+        else
+          if @mset[key].is_a? Array
+            @mset[key] << value
+          else
+            @mset[key] = [@mset[key], value]
+          end
+        end
+      end
+      
+      ##
+      # Returns all the values that match a key. Normally, if there is only a single value entry 
+      # returns just the value, with an array for multiple values, and nil for no match. If you want
+      # to always return an array, pass in <tt>:force_array => true</tt> in the options
+      def get(key_arg, options = {})
+        key = key_arg.to_s
+
+        if options[:before_cast]
+          key = "#{key}_before_cast"
+        end
+
+        k = @mset[key]
+
+        if options[:force_array]
+          return [] if k.nil?
+          k.to_a
+        else
+          k
+        end
+      end
+
+      ##
+      # Shortcut for #get
+      def [](key)
+        get(key)
+      end
+      
+      ##
+      # Shortcut for put(key, value, :replace => true)
+      def []=(key, value)
+        put(key, value, :replace => true)
+      end
+
+      ##
+      # Support for Enumerable. Yields each key/value pair as an array of 2 members.
+      def each
+        @mset.each_pair do |key, group| 
+          group.to_a.each do |value|
+            yield [key, value]
+          end
+        end    
+      end
+
+      ##
+      # Yields each key/value pair as separate parameters to the block.
+      def each_pair
+        @mset.each_pair do |key, group|
+          case group
+          when Array 
+            group.each do |value|
+              yield key, value
+            end
+          else
+            yield key, group
+          end
+        end
+      end
+
+      ##
+      # Yields each pair as separate key/value plus an index.
+      def each_pair_with_index
+        index = 0
+        self.each_pair do |key, value|
+          yield key, value, index
+          index += 1
+        end
+      end
+
+      def string_escape(str)
+        str.gsub('\\') {|c| "#{c}#{c}"}.gsub('\'') {|c| "\\#{c}"}
+      end
+      
+      def sdb_key_escape(key)
+        case key
+        when String
+          string_escape(key)
+        else
+          key.to_s
+        end
+      end
+
+      def sdb_value_escape(value)
+        case value
+        when Fixnum
+          sprintf("%0#{Base.number_padding}d", value)
+        when Float
+          numeric(value, Base.number_padding, Base.float_precision)
+        when String
+          string_escape(value)
+        when Time
+          value.iso8601
+        else
+          string_escape(value.to_s)
+        end
+      end
+
+      ##
+      # Outputs a multimap to sdb using Amazon's query-string notation (and doing auto-conversions of int and date values)
+      def to_sdb(options={})
+        out = {}
+        
+        self.each_pair_with_index do |key, value, index|
+          out["Attribute.#{index}.Name"] = sdb_key_escape(key)
+          out["Attribute.#{index}.Value"] = sdb_value_escape(value)
+          
+          if options.key?(:replace) && (options[:replace] == :all || [*options[:replace]].find {|x| x.to_s == key })
+            out["Attribute.#{index}.Replace"] = "true"
+          end
+        end
+
+        out
+      end
+
+      def coerce(value)
+        case value
+        when /^0+\d+$/
+          value.to_i
+        when /^0+\d*.\d+$/
+          value.to_f
+        when /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}([+\-]\d{2}:\d{2})?)?$/
+          Time.parse(value)
+        else
+          value
+        end
+      end
+      
+      def from_sdb(values)
+        @mset = {}
+        clear_size!
+
+        if values.nil?
+          # do nothing
+        elsif values.is_a? Array
+          # load from array
+          if values.any? {|v| ! v.is_a? Array || v.size != 2 }
+            raise ArgumentError, "Array must be of key/value pairs only"
+          end
+
+          values.each do |v|
+            self.put(v[0], v[1], :before_cast => true)
+            self.put(v[0], coerce(v[1]))
+          end
+        else
+          raise ArgumentError, "Wrong type passed as initializer"
+        end
+      end
+      
+      ##
+      # Returns the multimap as an array of 2-item arrays, one for each key-value pair
+      def to_a
+        out = []
+        each_pair {|k, v| out << [k, v] }
+        out
+      end
+      
+      ##
+      # Returns the multimap as a hash. In cases where there are multiple values for a key, it puts all the values into an array. 
+      def to_h
+        @mset.dup
+      end
+      
+      def method_missing(method_symbol, *args)
+        name = method_symbol.to_s
+        if name =~ /^\w+$/
+          if @mset.key? name
+            get(name)
+          else
+            super
+          end
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/amazon_sdb/resultset.rb

@@ -0,0 +1,45 @@
+module Amazon
+  module SDB
+    
+    ##
+    # Represents a ResultSet returned from Domain#query. Currently, this is just
+    # a set of Items plus an operation to see if there is another set to be retrieved
+    # and to load it on demand. When Amazon sees fit to add total results or other metadata
+    # for queries that will also be included here.
+    class ResultSet
+      include Enumerable
+      attr_reader :items
+      
+      def initialize(domain, items, more_token = nil)
+        @domain = domain
+        @items = items
+        @more_token = more_token
+      end
+      
+      ##
+      # Returns true if there is another result set to be loaded
+      def more_items?
+        not @more_token.nil?
+      end
+      
+      ##
+      # Not implemented yet
+      def load_next!
+      end
+      
+      ##
+      # Iterator through all the keys in this resultset
+      def keys
+        @items.map {|i| i.key }
+      end
+      
+      ##
+      # Support method for Enumerable. Iterates through the items in this set (NOT all the matching results for a query)
+      def each
+        @items.each do |i|
+          yield i
+        end
+      end
+    end
+  end
+end

data/test/test_amazon_base.rb

@@ -0,0 +1,135 @@
+require 'test_sdb_harness'
+
+class TestAmazonBase < Test::Unit::TestCase
+  def setup
+    @sdb = Amazon::SDB::Base.new 'API_KEY', 'SECRET_KEY' 
+  end
+    
+  def test_sign
+    # this example is given by Amazon
+    options = {
+      "Timestamp" => '2004-02-12T15:19:21+00:00',
+      'adc' => 1,
+      'aab' => 2,
+      'AWSAccessKeyId' => 'my_access_id',
+      'SignatureVersion' => 1,
+      'Action' => 'Get',
+      'Version' => '2006-08-11'
+    }
+
+    signature = Amazon::SDB::Base.sign('secret_key', options)
+    assert_equal 'xlrD17jnkGk6E3nVVOV3Qon3Nwg=', signature
+  end
+  
+  def test_cgi_encode
+    options = {'foo' => 'bar'}
+  
+    assert_equal 'foo=bar', @sdb.cgi_encode(options)
+  end
+  
+  def test_cgi_encode_array
+    options = {"foo" => ["bar", "baz"]}
+    assert_equal 'foo=bar&foo=baz', @sdb.cgi_encode(options)
+  end
+  
+  def test_domains
+    @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.0000219907</BoxUsage> 
+    </ResponseMetadata> 
+    </ListDomainsResponse> 
+    EOF
+    
+    domains = @sdb.domains
+
+    assert_equal 1, @sdb.uris.length
+    assert_in_url_query({'Action' => 'ListDomains'}, @sdb.uris.first)
+
+    assert_equal 3, domains.size
+    %w(foo bar baz).each_with_index do |name, index|
+      assert_equal name, domains[index].name
+    end
+  end
+  
+  def test_domains_more
+    @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>
+    <NextToken>FOOBAR</NextToken> 
+    </ListDomainsResult> 
+    <ResponseMetadata> 
+    <RequestId>eb13162f-1b95-4511-8b12-489b86acfd28</RequestId> 
+    <BoxUsage>0.0000219907</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>baz</DomainName> 
+    </ListDomainsResult> 
+    <ResponseMetadata> 
+    <RequestId>eb13162f-1b95-4511-8b12-489b86acfd28</RequestId> 
+    <BoxUsage>0.0000219907</BoxUsage> 
+    </ResponseMetadata> 
+    </ListDomainsResponse> 
+    EOF
+    
+    domains = @sdb.domains
+    
+    assert_equal 2, @sdb.uris.length, "Should make 2 requests to sdb"
+    assert_in_url_query({'NextToken' => 'FOOBAR'}, @sdb.uris.last)
+    
+    assert_equal 3, domains.size, "Should return 3 domains"
+    %w(foo bar baz).each_with_index do |name, index|
+      assert_equal name, domains[index].name
+    end    
+  end
+  
+  def test_domains_fail
+  end
+  
+  def test_create_domain
+    @sdb.responses << generic_response('CreateDomain')
+
+    domain = @sdb.create_domain('foobar')
+    assert_equal 1, @sdb.uris.length
+    assert_in_url_query({'Action' => 'CreateDomain', 'DomainName' => 'foobar'}, @sdb.uris.first)
+    
+    assert_equal 'foobar', domain.name
+  end
+  
+  def test_create_domain_invalid_param
+    @sdb.responses << error_response('InvalidParameterValue', 'Value (X) for parameter DomainName is invalid.')
+
+    assert_raise(Amazon::SDB::InvalidParameterError) { @sdb.create_domain('(X)') }
+    assert_equal 1, @sdb.uris.length
+  end
+  
+  def test_create_domain_limit_error
+    @sdb.responses << error_response('NumberDomainsExceeded', 'Domain Limit reached')
+    
+    assert_raise(Amazon::SDB::DomainLimitError) { @sdb.create_domain('foo') }
+  end
+  
+  def test_delete_domain
+    @sdb.responses << generic_response('DeleteDomain')
+    
+    @sdb.delete_domain!('foo')
+    assert_equal 1, @sdb.uris.length
+    assert_in_url_query({'Action' => 'DeleteDomain', 'DomainName' => 'foo'}, @sdb.uris.first)
+  end
+end