aws-sdk 1.0.0

data/lib/aws/rails.rb

@@ -0,0 +1,209 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws'
+
+module AWS
+
+  if Object.const_defined?(:Rails) and Rails.const_defined?(:Railtie)
+
+    class Railtie < Rails::Railtie
+
+      # configure our plugin on boot. other extension points such
+      # as configuration, rake tasks, etc, are also available
+      initializer "aws-sdk.initialize" do |app|
+        AWS::Rails.setup
+      end
+    end
+
+  end
+
+  # A handful of useful Rails integration methods.
+  #
+  # If you require this gem inside a Rails application (via config.gem
+  # for rails 2 and bundler for rails 3) then AWS::Rails.setup
+  # is called automatically.
+  module Rails
+    
+    # Adds extra functionality to Rails.
+    #
+    # Normailly this method is invoked automatically when you require this
+    # gem in a Rails Application:
+    #
+    # Rails 3+ (RAILS_ROOT/Gemfile)
+    #
+    #   gem 'aws-sdk-rails'
+    #
+    # Rails 2.1 - 2.3 (RAILS_ROOT/config/environment.rb)
+    #
+    #   config.gem 'aws-sdk-rails'
+    #
+    # === Selective Rails Features
+    #
+    # If you would prefer to cherry pick a few of the features added by this
+    # gem you can change your gem requirement to load 'aws/rails' instead:
+    #
+    # Rails 3+ (RAILS_ROOT/Gemfile)
+    #
+    #   gem 'aws-sdk-rails', :require => 'aws/rails'
+    #
+    # Rails 2.1 - 2.3 (RAILS_ROOT/config/environment.rb)
+    #
+    #   config.gem 'aws-sdk-rails', :lib => 'aws/rails'
+    #
+    # In both of the examples above you can now configure AWS and call the setup
+    # methods of choice inside a config initializer (e.g. 
+    # RAILS_ROOT/config/initializers/aws.rb):
+    #
+    #   AWS.config(...)
+    #   AWS.log_to_rails_logger
+    #   AWS.add_action_mailer_delivery_method 
+    #   
+    # @return [nil]
+    def self.setup
+      load_yaml_config
+      add_action_mailer_delivery_method
+      log_to_rails_logger
+      nil
+    end
+  
+    # Loads AWS configuration options from +RAILS_ROOT/config/aws.yml+.
+    #
+    # This configuration file is optional.  You can omit this file and instead
+    # use ruby to configure AWS inside a configuration initialization script
+    # (e.g. RAILS_ROOT/config/intializers/aws.rb).
+    # 
+    # If you have a yaml configuration file it should be formatted like the
+    # standard +database.yml+ file in a Rails application.  This means there
+    # should be one section for Rails environment:
+    #
+    #   development:
+    #     access_key_id: YOUR_ACCESS_KEY_ID
+    #     secret_access_key: YOUR_SECRET_ACCESS_KEY
+    #     simple_db_consistent_reads: false
+    #
+    #   production:
+    #     access_key_id: YOUR_ACCESS_KEY_ID
+    #     secret_access_key: YOUR_SECRET_ACCESS_KEY
+    #     simple_db_consistent_reads: true
+    #     
+    # You should also consider DRYing up your configuration file using 
+    # YAML references:
+    #
+    #   development:
+    #     access_key_id: YOUR_ACCESS_KEY_ID
+    #     secret_access_key: YOUR_SECRET_ACCESS_KEY
+    #     simple_db_consistent_reads: false
+    #
+    #   production:
+    #     <<: *development
+    #     simple_db_consistent_reads: true
+    #
+    # The yaml file will also be ERB parsed so you can use ruby inside of it:
+    # 
+    #   development:
+    #     access_key_id: YOUR_ACCESS_KEY_ID
+    #     secret_access_key: <%= read_secret_from_a_secure_location %>
+    #     simple_db_consistent_reads: false
+    #
+    #   production:
+    #     <<: *development
+    #     simple_db_consistent_reads: true
+    #
+    def self.load_yaml_config
+  
+      path = Pathname.new("#{rails_root}/config/aws.yml")
+  
+      if File.exists?(path)
+        cfg = YAML::load(ERB.new(File.read(path)).result)[rails_env]
+        AWS.config(cfg)
+      end
+  
+    end
+  
+    # Adds a delivery method to ActionMailer that uses {AWS::SimplEmailService}.
+    #
+    # Once you have an SES delivery method you can configure Rails to use this
+    # for ActionMailer in your environment configuration (e.g. 
+    # RAILS_ROOT/config/environments/production.rb)
+    #
+    #   config.action_mailer.delivery_method = :amazon_ses
+    #
+    # === Defaults
+    #
+    # Normally you don't need to call this method.  By default a delivery method
+    # named +:amazon_ses+ is added to ActionMailer::Base.  This delivery method
+    # uses your default configuration (#{AWS.config}).
+    #
+    # === Custom SES Options
+    #
+    # If you need to supply configuration values for SES that are different than
+    # those in {AWS.config} then you can pass those options:
+    #
+    #   AWS.add_action_mailer_delivery_method(:ses, custom_options)
+    #
+    # @param [Hash] options
+    # @param [Symbol] name (:amazon_ses) The name of the delivery 
+    #   method.  The name used here should be the same as you set in your
+    #   environment config.  If you name the delivery method +:amazon_ses+ then
+    #   you could do something like this in your config/environments/ENV.rb file:
+    #   
+    #     config.action_mailer.delivery_method = :amazon_ses
+    #
+    # @param [Hash] options ({}) A hash of options that are passes to 
+    #   {AWS::SimpleEmailService#new} before delivering email.  
+    #
+    # @return [nil] 
+    def self.add_action_mailer_delivery_method name = :amazon_ses, options = {}
+  
+      amb = ::ActionMailer::Base
+  
+      if ::Rails.version.to_f >= 3
+        amb.add_delivery_method(name, AWS::SimpleEmailService, options)
+      else
+        amb.send(:define_method, "perform_delivery_#{name}") do |mail|
+          AWS::SimpleEmailService.new(options).send_raw_email(mail)
+        end
+      end
+  
+      nil
+  
+    end
+  
+    # Configures AWS to log to the Rails defualt logger.
+    # @return [nil]
+    def self.log_to_rails_logger
+      AWS.config(:logger => rails_logger)
+      nil
+    end
+
+    # @private
+    protected
+    def self.rails_env
+      ::Rails.respond_to?(:env) ? ::Rails.env : RAILS_ENV
+    end
+
+    # @private
+    protected
+    def self.rails_root
+      ::Rails.respond_to?(:root) ? ::Rails.root.to_s : RAILS_ROOT
+    end
+
+    # @private
+    protected
+    def self.rails_logger
+      ::Rails.respond_to?(:logger) ? ::Rails.logger : ::RAILS_DEFAULT_LOGGER
+    end
+
+  end
+end

data/lib/aws/record.rb

@@ -0,0 +1,79 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'set'
+require 'aws/record/base'
+
+module AWS
+  module Record
+  
+    # @private
+    class RecordNotFound < Exception; end
+  
+    # Sets a prefix to be applied to all SimpleDB domains associated with
+    # AWS::Record::Base classes.
+    #
+    #   AWS::Record.domain_prefix = 'production_'
+    #
+    #   class Product < AWS::Record::Base
+    #     set_domain_name 'products'
+    #   end
+    #
+    #   Product.domain_name #=> 'production_products'
+    #
+    # @param [String] A prefix to append to all domains.  This is useful for
+    #   grouping domains used by one application with a single prefix.
+    def self.domain_prefix= prefix
+      @prefix = prefix
+    end
+  
+    # @return [String,nil] The string that is prepended to all domain names.
+    def self.domain_prefix
+      @prefix
+    end
+  
+    # A utility method for casting values into an array.  
+    #
+    # * nil is returned as an empty array, []
+    # * Arrays are returned unmodified
+    # * Everything else is returned as the sole element of an array
+    #
+    # @param [Object] value
+    # @return [Array] The value cast into an array
+    # @private
+    def self.as_array value
+      case value
+      when nil   then []
+      when Set   then value.to_a
+      when Array then value
+      else [value]
+      end
+    end
+  
+    # A utility method for casting values into 
+    #
+    # * Sets are returned unmodified
+    # * everything else is passed through #{as_array} and then into a new Set
+    #
+    # @param [Object] value
+    # @return [Set] The value cast into a Set.
+    # @private
+    def self.as_set value
+      case value
+      when Set then value
+      else Set.new(as_array(value))
+      end
+    end
+  
+  end
+end

data/lib/aws/record/attribute.rb

@@ -0,0 +1,94 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+module AWS
+  module Record
+
+    # Base class for all of the AWS::Record attributes.
+    # @private
+    class Attribute
+
+      # @param [Symbol] Name of this attribute.  It should be a name that
+      #   is safe to use as a method.
+      # @param [Hash] options
+      # @option options [Boolean] :set (false) When true this attribute can
+      #   accept multiple unique values.  
+      def initialize name, options = {}
+        @name = name.to_s
+        @options = options.dup
+        if options[:set] and !self.class.allow_set?
+          raise ArgumentError, "invalid option :set for #{self.class}"
+        end
+      end
+
+      # @return [String] The name of this attribute
+      attr_reader :name
+
+      # @return [Hash] The hash of options this attribute was constructed with
+      attr_reader :options
+
+      # @return [Boolean] Returns true if this attribute can have 
+      #   multiple values.
+      def set?
+        options[:set] ? true : false
+      end
+
+      # @return Returns the default value for this attribute.  Defaults to nil.
+      def default_value
+        options[:default_value]
+      end
+
+      # @param [Mixed] A single value to type cast.
+      # @return [Mixed] Returns the type casted value.
+      def type_cast raw_value
+        self.class.type_cast(raw_value, options)
+      end
+
+      # @param [String] The serialized string value.
+      # @return [Mixed] Returns a deserialized type-casted value.
+      def deserialize serialized_value
+        self.class.deserialize(serialized_value, options)
+      end
+
+      # Takes the type casted value and serializes it
+      # @param [Mixed] A single value to serialize.
+      # @return [Mixed] Returns the serialized value.
+      def serialize type_casted_value
+        self.class.serialize(type_casted_value, options)
+      end
+      
+      # @param [String] serialized_value The string value as returned from AWS.
+      # @return [Mixed] Returns the type-casted deserialized value.
+      def self.deserialize serialized_value, options = {}
+        self.type_cast(serialized_value, options)
+      end
+
+      # @return [Boolean] Returns true if this attribute type can be used
+      #   with the +:set => true+ option.  Certain attirbutes can not 
+      #   be represented with multiple values (like BooleanAttribute).
+      def self.allow_set?
+        raise 'allow_set? must be defined in subclasses'
+      end
+
+      # @private
+      protected
+      def self.expect klass, value, &block
+        unless value.is_a?(klass)
+          raise ArgumentError, "expected a #{klass} value, got #{value.class}"
+        end
+        yield
+      end
+
+    end
+  end
+end

data/lib/aws/record/attribute_macros.rb

@@ -0,0 +1,288 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/record/attributes/string'
+require 'aws/record/attributes/integer'
+require 'aws/record/attributes/sortable_integer'
+require 'aws/record/attributes/float'
+require 'aws/record/attributes/sortable_float'
+require 'aws/record/attributes/boolean'
+require 'aws/record/attributes/datetime'
+
+module AWS
+  module Record
+    module AttributeMacros
+  
+      # Adds a string attribute to this class.
+      #
+      # @example A standard string attribute
+      #
+      #   class Recipe < AWS::Record::Base
+      #     string_attr :name
+      #   end
+      #
+      #   recipe = Recipe.new(:name => "Buttermilk Pancakes")
+      #   recipe.name #=> 'Buttermilk Pancakes'
+      #
+      # @example A string attribute with +:set+ set to true
+      #
+      #   class Recipe < AWS::Record::Base
+      #     string_attr :tags, :set => true
+      #   end
+      #
+      #   recipe = Recipe.new(:tags => %w(popular dessert))
+      #   recipe.tags #=> #<Set: {"popular", "desert"}> 
+      #
+      # @param [Symbol] name The name of the attribute.
+      # @param [Hash] options
+      # @option options [Boolean] :set (false) When true this attribute
+      #   can have multiple values.
+      def string_attr name, options = {}
+        add_attribute(StringAttribute.new(name, options))
+      end
+
+      # Adds an integer attribute to this class.
+      #
+      #   class Recipe < AWS::Record::Base
+      #     integer_attr :servings
+      #   end
+      #
+      #   recipe = Recipe.new(:servings => '10')
+      #   recipe.servings #=> 10
+      #
+      # @param [Symbol] name The name of the attribute.
+      # @param [Hash] options
+      # @option options [Boolean] :set (false) When true this attribute
+      #   can have multiple values.
+      def integer_attr name, options = {}
+        add_attribute(IntegerAttribute.new(name, options))
+      end
+
+      # Adds a sortable integer attribute to this class.
+      #
+      #   class Person < AWS::Record::Base
+      #     sortable_integer_attr :age, :range => 0..150
+      #   end
+      #
+      #   person = Person.new(:age => 10)
+      #   person.age #=> 10
+      #
+      # === Validations
+      # 
+      # It is recomended to apply a validates_numericality_of with
+      # minimum and maximum value constraints.  If a value is assigned
+      # to a sortable integer that falls outside of the +:range: it will
+      # raise a runtime error when the record is saved.
+      #
+      # === Difference Between Sortable an Regular Integer Attributes
+      #
+      # Because SimpleDB does not support numeric types, all values must
+      # be converted to strings.  This complicates sorting by numeric values.
+      # To accomplish sorting numeric attributes the values must be
+      # zero padded and have an offset applied to eliminate negative values.
+      #
+      # @param [Symbol] name The name of the attribute.
+      # @param [Hash] options
+      # @option options [Range] :range A numeric range the represents the
+      #   minimum and  maximum values this attribute should accept.
+      # @option options [Boolean] :set (false) When true this attribute
+      #   can have multiple values.
+      def sortable_integer_attr name, options = {}
+        add_attribute(SortableIntegerAttribute.new(name, options))
+      end
+
+      # Adds a float attribute to this class.
+      #
+      #   class Listing < AWS::Record::Base
+      #     float_attr :score
+      #   end
+      #
+      #   listing = Listing.new(:score => '123.456')
+      #   listing.score # => 123.456
+      #
+      # @param [Symbol] name The name of the attribute.
+      # @param [Hash] options
+      # @option options [Boolean] :set (false) When true this attribute
+      #   can have multiple values.
+      def float_attr name, options = {}
+        add_attribute(FloatAttribute.new(name, options))
+      end
+
+      # Adds sortable float attribute to this class.
+      #
+      # Persisted values are stored (and sorted) as strings.  This makes it
+      # more difficult to sort numbers because they don't sort 
+      # lexicographically unless they have been offset to be positive and
+      # then zero padded.
+      #
+      # === Postive Floats
+      #
+      # To store floats in a sort-friendly manor:
+      #
+      #   sortable_float_attr :score, :range => (0..10)
+      #
+      # This will cause values like 5.5 to persist as a string like '05.5' so 
+      # that they can be sorted lexicographically.
+      #
+      # === Negative Floats
+      #
+      # If you need to store negative sortable floats, increase your +:range+
+      # to include a negative value.
+      #
+      #   sortable_float_attr :position, :range => (-10..10)
+      #
+      # AWS::Record will add 10 to all values and zero pad them 
+      # (e.g. -10.0 will be represented as '00.0' and 10 will be represented as 
+      # '20.0').  This will allow the values to be compared lexicographically.
+      #
+      # @note If you change the +:range+ after some values have been persisted
+      #   you must also manually migrate all of the old values to have the
+      #   correct padding & offset or they will be interpreted differently.
+      #
+      # @param [Symbol] name The name of the attribute.
+      # @param [Hash] options
+      # @option options [Range] :range The range of numbers this attribute
+      #   should represent.  The min and max values of this range will determine
+      #   how many digits of precision are required and how much of an offset
+      #   is required to make the numbers sort lexicographically.
+      # @option options [Boolean] :set (false) When true this attribute
+      #   can have multiple values.
+      def sortable_float_attr name, options = {}
+        add_attribute(SortableFloatAttribute.new(name, options))
+      end
+
+      # Adds a boolean attribute to this class.
+      #
+      # @example
+      #
+      #   class Book < AWS::Record::Base
+      #     boolean_attr :read
+      #   end
+      #
+      #   b = Book.new
+      #   b.read? # => false
+      #   b.read = true
+      #   b.read? # => true
+      #
+      #   listing = Listing.new(:score => '123.456'
+      #   listing.score # => 123.456
+      #
+      # @param [Symbol] name The name of the attribute.
+      def boolean_attr name, options = {}
+
+        attr = add_attribute(BooleanAttribute.new(name, options))
+
+        # add the boolean question mark method
+        define_method("#{attr.name}?") do
+          !!__send__(attr.name)
+        end
+
+      end
+
+      # Adds a datetime attribute to this class.
+      #
+      # @example A standard datetime attribute
+      #
+      #   class Recipe < AWS::Record::Base
+      #     datetime_attr :invented
+      #   end
+      #
+      #   recipe = Recipe.new(:invented => Time.now)
+      #   recipe.invented #=> <DateTime ...>
+      #
+      # If you add a datetime_attr for +:created_at+ and/or +:updated_at+ those
+      # will be automanaged.
+      #
+      # @param [Symbol] name The name of the attribute.
+      # @param [Hash] options
+      # @option options [Integer] :precision When set, the integer will be
+      #   serialized with the correct number of digits to SimpleDB, left 
+      #   padded by zeros to allow sorting.
+      # @option options [Boolean] :set (false) When true this attribute
+      #   can have multiple values.
+      def datetime_attr name, options = {}
+        add_attribute(DateTimeAttribute.new(name, options))
+      end
+
+      # A convenience method for adding the standard two datetime attributes
+      # +:created_at+ and +:updated_at+.
+      #
+      # @example
+      #
+      #   class Recipe < AWS::Record::Base
+      #     timestamps
+      #   end
+      #
+      #   recipe = Recipe.new
+      #   recipe.save
+      #   recipe.created_at #=> <DateTime ...>
+      #   recipe.updated_at #=> <DateTime ...>
+      # 
+      def timestamps
+        c = datetime_attr :created_at
+        u = datetime_attr :updated_at
+        [c, u]
+      end
+  
+      # @private
+      private
+      def add_attribute attribute
+
+        attr_name = attribute.name
+
+        attributes[attr_name] = attribute
+
+        # setter
+        define_method("#{attr_name}=") do |value|
+          self[attr_name] = value
+        end
+
+        # getter
+        define_method(attr_name) do
+          self[attr_name]
+        end
+
+        # before type-cast getter
+        define_method("#{attr_name}_before_type_cast") do
+          @_data[attr_name]
+        end
+
+        ## dirty tracking methods
+
+        define_method("#{attr_name}_changed?") do
+          attribute_changed?(attr_name)
+        end
+
+        define_method("#{attr_name}_change") do
+          attribute_change(attr_name)
+        end
+
+        define_method("#{attr_name}_was") do
+          attribute_was(attr_name)
+        end
+
+        define_method("#{attr_name}_will_change!") do
+          attribute_will_change!(attr_name)
+        end
+
+        define_method("reset_#{attr_name}!") do
+          reset_attribute!(attr_name)
+        end
+
+        attribute
+
+      end
+
+    end
+  end
+end