aws-record 1.0.0.pre.7 → 1.0.0.pre.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 808122fbcc8d09789f250b6ab5f7bfa4af8a511f
-  data.tar.gz: 006ed1f3c955fe8370cd4d2ae81adb17195cc77e
+  metadata.gz: 529b219269ff7db06904ac8069cd9d03c5a39b2f
+  data.tar.gz: de636bcd9279040598617f1cad6b9601f583a4fc
 SHA512:
-  metadata.gz: 6586ed1a3add7fbe31dcd37b59f3798a0671b1ec25c0886f68c8c7545f5798fb4d6639c7c0ea14206ccba1d29b75d505ab34c211540026963a4c675542a37b4c
-  data.tar.gz: ab2ecaf0359165f4c179af7df4d96bd142ca29f630a65bc9c9985fd7be8987f44fec050b41342ee6eec8ff1d0f5592b93d36f460b170f6943eab6c68d8b410fd
+  metadata.gz: 0466dcde49ea6a9f0a026b806fba07f3e4152d7d115c8c6f89bcf1955903cd92ada636e51b72c161a8cb3f14178948514bf1e5bc11aa72995541f69559b81255
+  data.tar.gz: be394920aba460d6f28d1087077a13f17e25c4f07eb93f24e4ccdf1a7abb222f8d946db3766e6817966659c524d0e550a9273b95be657434bee5e82ba088697b

data/lib/aws-record/record/attribute.rb

@@ -13,6 +13,12 @@
 
 module Aws
   module Record
+
+    # This class provides helper methods for +Aws::Record+ attributes. These
+    # include marshalers for type casting of item attributes, the Amazon
+    # DynamoDB type for use in certain table and item operation calls, and the
+    # ability to define a database name that is separate from the name used
+    # within the model class and item instances.
     class Attribute
 
       attr_reader :name, :database_name, :dynamodb_type
@@ -66,6 +72,8 @@ module Aws
 
     end
 
+    # This is an identity marshaler, which performs no changes for type casting
+    # or serialization. It is generally not recommended for use.
     module DefaultMarshaler
       def self.type_cast(raw_value, options = {})
         raw_value

data/lib/aws-record/record/attributes.rb

@@ -22,8 +22,28 @@ module Aws
         sub_class.instance_variable_set("@storage_attributes", {})
       end
 
-      def initialize
+      # @example Usage Example
+      #   class MyModel
+      #     include Aws::Record
+      #     integer_attr :id,   hash_key: true
+      #     string_attr  :name, range_key: true
+      #     string_attr  :body
+      #   end
+      #
+      #   item = MyModel.new(id: 1, name: "Quick Create")
+      #
+      # Base initialization method for a new item. Optionally, allows you to
+      # provide initial attribute values for the model. You do not need to
+      # provide all, or even any, attributes at item creation time.
+      #
+      # @param [Hash] attr_values Attribute symbol/value pairs for any initial
+      #  attribute values you wish to set.
+      # @return [Aws::Record] An item instance for your model.
+      def initialize(attr_values = {})
         @data = {}
+        attr_values.each do |attr_name, attr_value|
+          send("#{attr_name}=", attr_value)
+        end
       end
 
       # Returns a hash representation of the attribute data.

data/lib/aws-record/record/dirty_tracking.rb

@@ -23,7 +23,8 @@ module Aws
       #
       # @override initialize(*)
       def initialize(*)
-        super.tap { @dirty_data = {} }
+        @dirty_data = {}
+        super
       end
 
       # Returns +true+ if the specified attribute has any dirty changes, +false+ otherwise.

data/lib/aws-record/record/errors.rb

@@ -15,16 +15,42 @@ module Aws
   module Record
     module Errors
 
+      # RecordErrors relate to the persistence of items. They include both
+      # client errors and certain validation errors.
       class RecordError < RuntimeError; end
 
+      # Raised when a required key attribute is missing from an item when
+      # persistence is attempted.
       class KeyMissing < RecordError; end
+
+      # Raised when you attempt to load a record from the database, but it does
+      # not exist there.
       class NotFound < RecordError; end
-      class ItemAlreadyExists < RecordError; end
+
+      # Raised when a conditional write fails.
+      class ConditionalWriteFailed < RecordError; end
+
+      # Raised when a validation hook call to +:valid?+ fails.
       class ValidationError < RecordError; end
 
+      # Raised when an attribute is defined that has a name collision with an
+      # existing attribute.
       class NameCollision < RuntimeError; end
+
+      # Raised when you attempt to create an attribute which has a name that
+      # conflicts with reserved names (generally, defined method names). If you
+      # see this error, you should change the attribute name in the model. If
+      # the database uses this name, you can take advantage of the
+      # +:database_attribute_name+ option in
+      # {Aws::Record::Attributes::ClassMethods#attr #attr}
       class ReservedName < RuntimeError; end
+
+      # Raised when you attempt a table migration and your model class is
+      # invalid.
       class InvalidModel < RuntimeError; end
+
+      # Raised when you attempt update/delete operations on a table that does
+      # not exist.
       class TableDoesNotExist < RuntimeError; end
 
     end

data/lib/aws-record/record/item_collection.rb

@@ -1,3 +1,16 @@
+# Copyright 2015-2016 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
     class ItemCollection

data/lib/aws-record/record/item_operations.rb

@@ -39,8 +39,8 @@ module Aws
       #  default, will either perform a conditional put or an update call.
       # @raise [Aws::Record::Errors::KeyMissing] if a required key attribute
       #  does not have a value within this item instance.
-      # @raise [Aws::Record::Errors::ItemAlreadyExists] if a conditional put
-      #  fails because the item exists on the remote end.
+      # @raise [Aws::Record::Errors::ConditionalWriteFailed] if a conditional
+      #  put fails because the item exists on the remote end.
       # @raise [Aws::Record::Errors::ValidationError] if the item responds to
       #  +:valid?+ and that call returned false. In such a case, checking root
       #  cause is dependent on the validation library you are using.
@@ -122,11 +122,10 @@ module Aws
           begin
             dynamodb_client.put_item(put_opts)
           rescue Aws::DynamoDB::Errors::ConditionalCheckFailedException => e
-            raise Errors::ItemAlreadyExists.new(
-              "Conditional #put_item call failed, an item with the same key"\
-                " already exists in the table. Either load and update this"\
-                " item, or include the :force option to clobber the remote"\
-                " item."
+            raise Errors::ConditionalWriteFailed.new(
+              "Conditional #put_item call failed! Check that conditional write"\
+                " conditions are met, or include the :force option to clobber"\
+                " the remote item."
             )
           end
         else
@@ -237,7 +236,7 @@ module Aws
                 "Missing required key #{attr_sym} in #{opts}"
               )
             end
-            attr_name = attr_sym.to_s
+            attr_name = attributes[attr_sym].database_name
             key[attr_name] = attributes[attr_sym].serialize(opts[attr_sym])
           end
           request_opts = {
@@ -252,6 +251,69 @@ module Aws
           end
         end
 
+        # @example Usage Example
+        #   class MyModel
+        #     include Aws::Record
+        #     integer_attr :id,   hash_key: true
+        #     string_attr  :name, range_key: true
+        #     string_attr  :body
+        #     boolean_attr :sir_not_appearing_in_this_example
+        #   end
+        #
+        #   MyModel.update(id: 1, name: "First", body: "Hello!")
+        #
+        # Performs an
+        # {http://docs.aws.amazon.com/sdkforruby/api/Aws/DynamoDB/Client.html#update_item-instance_method Aws::DynamoDB::Client#update_item}
+        # call immediately on the table, using the attribute key/value pairs
+        # provided.
+        #
+        # @param [Hash] opts attribute-value pairs for the update operation you
+        #  wish to perform. You must include all key attributes for a valid
+        #  call, then you may optionally include any other attributes that you
+        #  wish to update.
+        # @raise [Aws::Record::Errors::KeyMissing] if your option parameters do
+        #  not include all table keys.
+        def update(opts)
+          key = {}
+          updates = {}
+          @keys.each_value do |attr_sym|
+            unless value = opts.delete(attr_sym)
+              raise Errors::KeyMissing.new(
+                "Missing required key #{attr_sym} in #{opts}"
+              )
+            end
+            attr_name = attributes[attr_sym].database_name
+            key[attr_name] = attributes[attr_sym].serialize(value)
+          end
+          request_opts = {
+            table_name: table_name,
+            key: key
+          }
+          update_expressions = []
+          exp_attr_names = {}
+          exp_attr_values = {}
+          name_sub_token = "A"
+          value_sub_token = "a"
+          opts.each do |attr_sym, value|
+            name_sub = "#" + name_sub_token
+            value_sub = ":" + value_sub_token
+            name_sub_token = name_sub_token.succ
+            value_sub_token = value_sub_token.succ
+
+            attr_name = attributes[attr_sym].database_name
+            update_expressions << "#{name_sub} = #{value_sub}"
+            exp_attr_names[name_sub] = attr_name
+            exp_attr_values[value_sub] = attributes[attr_sym].serialize(value)
+          end
+          unless update_expressions.empty?
+            uex = "SET " + update_expressions.join(", ")
+            request_opts[:update_expression] = uex
+            request_opts[:expression_attribute_names] = exp_attr_names
+            request_opts[:expression_attribute_values] = exp_attr_values
+          end
+          dynamodb_client.update_item(request_opts)
+        end
+
         private
         def build_item_from_resp(resp)
           record = new

data/lib/aws-record/record/query.rb

@@ -27,6 +27,35 @@ module Aws
         # populating the +:table_name+ parameter from the model class, and
         # combining this with the other parameters you provide.
         #
+        # @example A query with key and filter expressions:
+        #   # Example model class
+        #   class ExampleTable
+        #     include Aws::Record
+        #     string_attr  :uuid, hash_key: true
+        #     integer_attr :id,   range_key: true
+        #     string_attr  :body
+        #   end
+        #
+        #   query = ExampleTable.query(
+        #     key_condition_expression: "#H = :h AND #R > :r",
+        #     filter_expression: "contains(#B, :b)",
+        #     expression_attribute_names: {
+        #       "#H" => "uuid",
+        #       "#R" => "id",
+        #       "#B" => "body"
+        #     },
+        #     expression_attribute_values: {
+        #       ":h" => "123456789uuid987654321",
+        #       ":r" => 100,
+        #       ":b" => "some substring"
+        #     }
+        #   )
+        #
+        #   # You can enumerate over your results.
+        #   query.each do |r|
+        #     puts "UUID: #{r.uuid}\nID: #{r.id}\nBODY: #{r.body}\n"
+        #   end
+        #
         # @param [Hash] opts options to pass on to the client call to +#query+.
         #   See the documentation above in the AWS SDK for Ruby V2.
         # @return [Aws::Record::ItemCollection] an enumerable collection of the
@@ -41,6 +70,30 @@ module Aws
         # populating the +:table_name+ parameter from the model class, and
         # combining this with the other parameters you provide.
         #
+        # @example A scan with a filter expression:
+        #   # Example model class
+        #   class ExampleTable
+        #     include Aws::Record
+        #     string_attr  :uuid, hash_key: true
+        #     integer_attr :id,   range_key: true
+        #     string_attr  :body
+        #   end
+        #
+        #   scan = ExampleTable.scan(
+        #     filter_expression: "contains(#B, :b)",
+        #     expression_attribute_names: {
+        #       "#B" => "body"
+        #     },
+        #     expression_attribute_values: {
+        #       ":b" => "some substring"
+        #     }
+        #   )
+        #
+        #   # You can enumerate over your results.
+        #   scan.each do |r|
+        #     puts "UUID: #{r.uuid}\nID: #{r.id}\nBODY: #{r.body}\n"
+        #   end
+        #
         # @param [Hash] opts options to pass on to the client call to +#scan+.
         #   See the documentation above in the AWS SDK for Ruby V2.
         # @return [Aws::Record::ItemCollection] an enumerable collection of the

data/lib/aws-record/record/table_migration.rb

@@ -29,7 +29,7 @@ module Aws
       #  class. If this option is not included, a client will be constructed for
       #  you with default parameters.
       def initialize(model, opts = {})
-        assert_model_valid(model)
+        _assert_model_valid(model)
         @model = model
         @client = opts[:client] || Aws::DynamoDB::Client.new
       end
@@ -39,6 +39,20 @@ module Aws
       # populating the attribute definitions and key schema based on your model
       # class, as well as passing through other parameters as provided by you.
       #
+      # @example Creating a table with a global secondary index named +:gsi+
+      #   migration.create!(
+      #     provisioned_throughput: {
+      #       read_capacity_units: 5,
+      #       write_capacity_units: 2
+      #     },
+      #     global_secondary_index_throughput: {
+      #       gsi: {
+      #         read_capacity_units: 3,
+      #         write_capacity_units: 1
+      #       }
+      #     }
+      #   )
+      #
       # @param [Hash] opts options to pass on to the client call to
       #  +#create_table+. See the documentation above in the AWS SDK for Ruby
       #  V2.
@@ -53,8 +67,8 @@ module Aws
         gsit = opts.delete(:global_secondary_index_throughput)
         create_opts = opts.merge({
           table_name: @model.table_name,
-          attribute_definitions: attribute_definitions,
-          key_schema: key_schema
+          attribute_definitions: _attribute_definitions,
+          key_schema: _key_schema
         })
         if lsis = @model.local_secondary_indexes_for_migration
           create_opts[:local_secondary_indexes] = lsis
@@ -117,25 +131,25 @@ module Aws
       end
 
       private
-      def assert_model_valid(model)
-        assert_required_include(model)
-        assert_keys(model)
+      def _assert_model_valid(model)
+        _assert_required_include(model)
+        _assert_keys(model)
       end
 
-      def assert_required_include(model)
+      def _assert_required_include(model)
         unless model.include?(::Aws::Record)
           raise Errors::InvalidModel.new("Table models must include Aws::Record")
         end
       end
 
-      def assert_keys(model)
+      def _assert_keys(model)
         if model.hash_key.nil?
           raise Errors::InvalidModel.new("Table models must include a hash key")
         end
       end
 
-      def attribute_definitions
-        keys.map do |type, attr|
+      def _attribute_definitions
+        _keys.map do |type, attr|
           {
             attribute_name: attr.database_name,
             attribute_type: attr.dynamodb_type
@@ -183,8 +197,8 @@ module Aws
         ret
       end
 
-      def key_schema
-        keys.map do |type, attr|
+      def _key_schema
+        _keys.map do |type, attr|
           {
             attribute_name: attr.database_name,
             key_type: type == :hash ? "HASH" : "RANGE"
@@ -192,7 +206,7 @@ module Aws
         end
       end
 
-      def keys
+      def _keys
         @model.keys.inject({}) do |acc, (type, name)|
           acc[type] = @model.attributes[name]
           acc

data/lib/aws-record/record/version.rb

@@ -13,6 +13,6 @@
 
 module Aws
   module Record
-    VERSION = '1.0.0.pre.7'
+    VERSION = '1.0.0.pre.8'
   end
 end

data/lib/aws-record/record.rb

@@ -12,6 +12,22 @@
 # and limitations under the License.
 
 module Aws
+
+  # +Aws::Record+ is the module you include in your model classes in order to
+  # decorate them with the Amazon DynamoDB integration methods provided by this
+  # library. Methods you can use are shown below, in sub-modules organized by
+  # functionality.
+  #
+  # @example A class definition using +Aws::Record+
+  #   class MyModel
+  #     include Aws::Record
+  #     string_attr     :uuid,    hash_key: true
+  #     integer_attr    :post_id, range_key: true
+  #     boolean_attr    :is_active
+  #     datetime_attr   :created_at
+  #     string_set_attr :tags
+  #     map_attr        :metadata
+  #   end
   module Record
     # @!parse extend RecordClassMethods
     # @!parse include Attributes

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-record
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.7
+  version: 1.0.0.pre.8
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-21 00:00:00.000000000 Z
+date: 2016-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-resources