aws-record 2.8.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2aaa5337431b2b2f59b35245afd1fb9eb4cacb5226f9cc60a2fefeed5bde7619
-  data.tar.gz: 8e8a225d9abfb3ec8ca8ee30606df05016166bbb10e0affc4d81fbfbcaaa21f4
+  metadata.gz: e1d49110ed24d748680a2fe7c1d124e5faa40c1ee224b6f20059cc3252dc8b27
+  data.tar.gz: 4efe9261ad7642c172e267f4cec4b614f61f42e7c57970c7561b6eb51c6ac516
 SHA512:
-  metadata.gz: f3ca0395934b8b5f464e7208c8b9b55c104475a045e6e93c01d9a8dfbcbbcab5bed6e4d3563ff963d43a93cce79e2918bfba032e4dab83d42168603289aa2bee
-  data.tar.gz: 5ed32da4f64d414076c16265ae5200beeb2a02225fb03cc9626626df9bdc1e07a48918231576236e59a22edff0e940fb48be582f7a3fb7162353bbeb6cc9a4fc
+  metadata.gz: 9d2d80ea4671ab80debef324a8f80b40cb41034b2a426c69d95db48d436d86f1f7c4d1c8458da363595c28de3254c0755d9956f78f3e25dcacea83d695c8cede
+  data.tar.gz: ae7e17fb7b3fcd56a3e5f78c92da540bcceb5d4a3ec62ac70b95cf0eaefaedb89a5845b701d5b28eba0221294c6eb1f769800756017e04a812dd1a552dfd43ce

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

@@ -20,8 +20,19 @@ module Aws
         model_attributes = ModelAttributes.new(self)
         sub_class.instance_variable_set("@attributes", model_attributes)
         sub_class.instance_variable_set("@keys", KeyAttributes.new(model_attributes))
+        if Aws::Record.extends_record?(sub_class)
+          inherit_attributes(sub_class)
+        end
       end
 
+      # 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.
+      #
+      # === Inheritance Support
+      # Child models will inherit the attributes and keys defined in the parent
+      # model. Child models can override attribute keys if defined in their own model.
+      # See examples below to see the feature in action.
       # @example Usage Example
       #   class MyModel
       #     include Aws::Record
@@ -31,11 +42,34 @@ module Aws
       #   end
       #
       #   item = MyModel.new(id: 1, name: "Quick Create")
+      # @example Child model inheriting from Parent model
+      #   class Animal
+      #     include Aws::Record
+      #     string_attr :name,   hash_key: true
+      #     integer_attr :age,   default_value: 1
+      #   end
       #
-      # 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.
+      #   class Cat < Animal
+      #     include Aws::Record
+      #     integer_attr :num_of_wiskers
+      #   end
       #
+      #   cat = Cat.find(name: 'Foo')
+      #   cat.age    # => 1
+      #   cat.num_of_wiskers = 200
+      # @example Child model overrides the hash key
+      #   class Animal
+      #     include Aws::Record
+      #     string_attr :name,   hash_key: true
+      #     integer_attr :age,   range_key: true
+      #   end
+      #
+      #   class Dog < Animal
+      #     include Aws::Record
+      #     integer_attr :id, hash_key: true
+      #   end
+      #
+      #   Dog.keys # => {:hash=>:id, :range=>:age}
       # @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.
@@ -56,6 +90,27 @@ module Aws
         @data.hash_copy
       end
 
+      private
+      def self.inherit_attributes(klass)
+        superclass_attributes = klass.superclass.instance_variable_get("@attributes")
+
+        superclass_attributes.attributes.each do |name, attribute|
+          subclass_attributes = klass.instance_variable_get("@attributes")
+          subclass_attributes.register_superclass_attribute(name, attribute)
+        end
+
+        superclass_keys = klass.superclass.instance_variable_get("@keys")
+        subclass_keys = klass.instance_variable_get("@keys")
+
+        if superclass_keys.hash_key
+          subclass_keys.hash_key = superclass_keys.hash_key
+        end
+
+        if superclass_keys.range_key
+          subclass_keys.range_key = superclass_keys.range_key
+        end
+      end
+
       module ClassMethods
 
         # Define an attribute for your model, providing your own attribute type.

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

@@ -1,15 +1,4 @@
-# Copyright 2015-2021 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.
+# frozen_string_literal: true
 
 module Aws
   module Record
@@ -17,6 +6,28 @@ module Aws
       extend ClientConfiguration
 
       class << self
+        # Provides a thin wrapper to the
+        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#batch_write_item-instance_method Aws::DynamoDB::Client#batch_write_item}
+        # method. Up to 25 +PutItem+ or +DeleteItem+ operations are supported.
+        # A single request may write up to 16 MB of data, with each item having a
+        # write limit of 400 KB.
+        #
+        # *Note*: this operation does not support dirty attribute handling,
+        # nor does it enforce safe write operations (i.e. update vs new record
+        # checks).
+        #
+        # This call may partially execute write operations. Failed operations
+        # are returned as {BatchWrite.unprocessed_items unprocessed_items} (i.e. the
+        # table fails to meet requested write capacity). Any unprocessed
+        # items may be retried by calling {BatchWrite.execute! .execute!}
+        # again. You can determine if the request needs to be retried by calling
+        # the {BatchWrite.complete? .complete?} method - which returns +true+
+        # when all operations have been completed.
+        #
+        # Please see
+        # {https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.Errors.html#Programming.Errors.BatchOperations Batch Operations and Error Handling}
+        # in the DynamoDB Developer Guide for more details.
+        #
         # @example Usage Example
         #   class Breakfast
         #     include Aws::Record
@@ -38,29 +49,7 @@ module Aws
         #   end
         #
         #   # unprocessed items can be retried by calling Aws::Record::BatchWrite#execute!
-        #   operation.execute! unless operation.complete?
-        #
-        # Provides a thin wrapper to the
-        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#batch_write_item-instance_method Aws::DynamoDB::Client#batch_write_item}
-        # method. Up to 25 +PutItem+ or +DeleteItem+ operations are supported.
-        # A single rquest may write up to 16 MB of data, with each item having a
-        # write limit of 400 KB.
-        #
-        # *Note*: this operation does not support dirty attribute handling,
-        # nor does it enforce safe write operations (i.e. update vs new record
-        # checks).
-        #
-        # This call may partially execute write operations. Failed operations
-        # are returned as +Aws::Record::BatchWrite#unprocessed_items+ (i.e. the
-        # table fails to meet requested write capacity). Any unprocessed
-        # items may be retried by calling +Aws::Record::BatchWrite#execute!+
-        # again. You can determine if the request needs to be retried by calling
-        # the +Aws::Record::BatchWrite#complete?+ method - which returns +true+
-        # when all operations have been completed.
-        #
-        # Please see
-        # {https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.Errors.html#Programming.Errors.BatchOperations Batch Operations and Error Handling}
-        # in the DynamoDB Developer Guide for more details.
+        #   operation.execute! until operation.complete?
         #
         # @param [Hash] opts the options you wish to use to create the client.
         #  Note that if you include the option +:client+, all other options
@@ -76,6 +65,81 @@ module Aws
           block.call(batch)
           batch.execute!
         end
+
+        # Provides support for the
+        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#batch_get_item-instance_method
+        # Aws::DynamoDB::Client#batch_get_item} for aws-record models.
+        #
+        # +Aws::Record::Batch+ is Enumerable and using Enumerable methods will handle
+        # paging through all requested keys automatically. Alternatively, a lower level
+        # interface is available. You can determine if there are any unprocessed keys by calling
+        # {BatchRead.complete? .complete?} and any unprocessed keys can be processed by
+        # calling {BatchRead.execute! .execute!}. You can access all processed items
+        # through {BatchRead.items .items}.
+        #
+        # The +batch_get_item+ supports up to 100 operations in a single call and a single
+        # operation can retrieve up to 16 MB of data.
+        #
+        # +Aws::Record::BatchRead+ can take more than 100 item keys. The first 100 requests
+        # will be processed and the remaining requests will be stored.
+        # When using Enumerable methods, any pending item keys will be automatically
+        # processed and the new items will be added to +items+.
+        # Alternately, use {BatchRead.execute! .execute!} to process any pending item keys.
+        #
+        # All processed operations can be accessed by {BatchRead.items items} - which is an
+        # array of modeled items from the response. The items will be unordered since
+        # DynamoDB does not return items in any particular order.
+        #
+        # If a requested item does not exist in the database, it is not returned in the response.
+        #
+        # If there is a returned item from the call and there's no reference model class
+        # to be found, the item will not show up under +items+.
+        #
+        # @example Usage Example
+        #   class Lunch
+        #     include Aws::Record
+        #     integer_attr :id,   hash_key: true
+        #     string_attr  :name, range_key: true
+        #   end
+        #
+        #   class Dessert
+        #     include Aws::Record
+        #     integer_attr :id,   hash_key: true
+        #     string_attr  :name, range_key: true
+        #   end
+        #
+        #   # batch operations
+        #   operation = Aws::Record::Batch.read do |db|
+        #     db.find(Lunch, id: 1, name: 'Papaya Salad')
+        #     db.find(Lunch, id: 2, name: 'BLT Sandwich')
+        #     db.find(Dessert, id: 1, name: 'Apple Pie')
+        #   end
+        #
+        #   # BatchRead is enumerable and handles pagination
+        #   operation.each { |item| item.id }
+        #
+        #   # Alternatively, BatchRead provides a lower level
+        #   # interface through: execute!, complete? and items.
+        #   # Unprocessed items can be processed by calling:
+        #   operation.execute! until operation.complete?
+        #
+        # @param [Hash] opts the options you wish to use to create the client.
+        #  Note that if you include the option +:client+, all other options
+        #  will be ignored. See the documentation for other options in the
+        #  {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#initialize-instance_method
+        #  AWS SDK for Ruby}.
+        # @option opts [Aws::DynamoDB::Client] :client allows you to pass in your
+        #  own pre-configured client.
+        # @return [Aws::Record::BatchRead] An instance that contains modeled items
+        #  from the +BatchGetItem+ result and stores unprocessed keys to be
+        #  manually processed later.
+        def read(opts = {}, &block)
+          batch = BatchRead.new(client: _build_client(opts))
+          block.call(batch)
+          batch.execute!
+          batch
+        end
+
       end
     end
   end

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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Aws
+  module Record
+    class BatchRead
+      include Enumerable
+
+      # @api private
+      BATCH_GET_ITEM_LIMIT = 100
+
+      # @param [Aws::DynamoDB::Client] client the DynamoDB SDK client.
+      def initialize(opts = {})
+        @client = opts[:client]
+      end
+
+      # Append the item keys to a batch read request.
+      #
+      # See {Batch.read} for example usage.
+      # @param [Aws::Record] klass a model class that includes {Aws::Record}
+      # @param [Hash] key attribute-value pairs for the key you wish to search for.
+      # @raise [Aws::Record::Errors::KeyMissing] if your option parameters
+      #  do not include all item keys defined in the model.
+      # @raise [ArgumentError] if the provided item keys is a duplicate request
+      #  in the same instance.
+      def find(klass, key = {})
+        unprocessed_key = format_unprocessed_key(klass, key)
+        store_unprocessed_key(klass, unprocessed_key)
+        store_item_class(klass, unprocessed_key)
+      end
+
+      # Perform a +batch_get_item+ request.
+      #
+      # This method processes the first 100 item keys and
+      # returns an array of new modeled items.
+      #
+      # See {Batch.read} for example usage.
+      # @return [Array] an array of unordered new items
+      def execute!
+        operation_keys = unprocessed_keys[0..BATCH_GET_ITEM_LIMIT - 1]
+        @unprocessed_keys = unprocessed_keys[BATCH_GET_ITEM_LIMIT..-1] || []
+
+        operations = build_operations(operation_keys)
+        result = @client.batch_get_item(request_items: operations)
+        new_items = build_items(result.responses)
+        items.concat(new_items)
+
+        unless result.unprocessed_keys.nil?
+          update_unprocessed_keys(result.unprocessed_keys)
+        end
+
+        new_items
+      end
+
+      # Provides an enumeration of the results from the +batch_get_item+ request
+      # and handles pagination.
+      #
+      # Any pending item keys will be automatically processed and be
+      # added to the {#items}.
+      #
+      # See {Batch.read} for example usage.
+      # @yieldparam [Aws::Record] item a modeled item
+      # @return [Enumerable<BatchRead>] an enumeration over the results of
+      #  +batch_get_item+ request.
+      def each
+        return enum_for(:each) unless block_given?
+
+        @items.each { |item| yield item }
+        until complete?
+          new_items = execute!
+          new_items.each { |new_item| yield new_item }
+        end
+      end
+
+      # Indicates if all item keys have been processed.
+      #
+      # See {Batch.read} for example usage.
+      # @return [Boolean] +true+ if all item keys has been processed, +false+ otherwise.
+      def complete?
+        unprocessed_keys.none?
+      end
+
+      # Returns an array of modeled items. The items are marshaled into classes used in {#find} method.
+      # These items will be unordered since DynamoDB does not return items in any particular order.
+      #
+      # See {Batch.read} for example usage.
+      # @return [Array] an array of modeled items from the +batch_get_item+ call.
+      def items
+        @items ||= []
+      end
+
+      private
+
+      def unprocessed_keys
+        @unprocessed_keys ||= []
+      end
+
+      def item_classes
+        @item_classes ||= Hash.new { |h, k| h[k] = [] }
+      end
+
+      def format_unprocessed_key(klass, key)
+        item_key = {}
+        attributes = klass.attributes
+        klass.keys.each_value do |attr_sym|
+          unless key[attr_sym]
+            raise Errors::KeyMissing, "Missing required key #{attr_sym} in #{key}"
+          end
+
+          attr_name = attributes.storage_name_for(attr_sym)
+          item_key[attr_name] = attributes.attribute_for(attr_sym)
+                                          .serialize(key[attr_sym])
+        end
+        item_key
+      end
+
+      def store_unprocessed_key(klass, unprocessed_key)
+        unprocessed_keys << { keys: unprocessed_key, table_name: klass.table_name }
+      end
+
+      def store_item_class(klass, key)
+        if item_classes.include?(klass.table_name)
+          item_classes[klass.table_name].each do |item|
+            if item[:keys] == key && item[:class] != klass
+              raise ArgumentError, 'Provided item keys is a duplicate request'
+            end
+          end
+        end
+        item_classes[klass.table_name] << { keys: key, class: klass }
+      end
+
+      def build_operations(keys)
+        operations = Hash.new { |h, k| h[k] = { keys: [] } }
+        keys.each do |key|
+          operations[key[:table_name]][:keys] << key[:keys]
+        end
+        operations
+      end
+
+      def build_items(item_responses)
+        new_items = []
+        item_responses.each do |table, unprocessed_items|
+          unprocessed_items.each do |item|
+            item_class = find_item_class(table, item)
+            if item_class.nil? && @client.config.logger
+              @client.config.logger.warn(
+                'Unexpected response from service.'\
+                "Received: #{item}. Skipping above item and continuing"
+              )
+            else
+              new_items << build_item(item, item_class)
+            end
+          end
+        end
+        new_items
+      end
+
+      def update_unprocessed_keys(keys)
+        keys.each do |table_name, table_values|
+          table_values.keys.each do |key|
+            unprocessed_keys << { keys: key, table_name: table_name }
+          end
+        end
+      end
+
+      def find_item_class(table, item)
+        selected_item = item_classes[table].find { |item_info| contains_keys?(item, item_info[:keys]) }
+        selected_item[:class] if selected_item
+      end
+
+      def contains_keys?(item, keys)
+        item.merge(keys) == item
+      end
+
+      def build_item(item, item_class)
+        new_item_opts = {}
+        item.each do |db_name, value|
+          name = item_class.attributes.db_to_attribute_name(db_name)
+          new_item_opts[name] = value
+        end
+        item = item_class.new(new_item_opts)
+        item.clean!
+        item
+      end
+    end
+  end
+end

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

@@ -15,12 +15,14 @@ module Aws
   module Record
     class BatchWrite
       # @param [Aws::DynamoDB::Client] client the DynamoDB SDK client.
-      def initialize(client:)
-        @client = client
+      def initialize(opts = {})
+        @client = opts[:client]
       end
 
       # Append a +PutItem+ operation to a batch write request.
       #
+      # See {Batch.write} for example usage.
+      #
       # @param [Aws::Record] record a model class that includes {Aws::Record}.
       def put(record)
         table_name, params = record_put_params(record)
@@ -30,6 +32,7 @@ module Aws
 
       # Append a +DeleteItem+ operation to a batch write request.
       #
+      # See {Batch.write} for example usage.
       # @param [Aws::Record] record a model class that includes {Aws::Record}.
       def delete(record)
         table_name, params = record_delete_params(record)
@@ -39,6 +42,7 @@ module Aws
 
       # Perform a +batch_write_item+ request.
       #
+      # See {Batch.write} for example usage.
       # @return [Aws::Record::BatchWrite] an instance that provides access to
       #   unprocessed items and allows for retries.
       def execute!
@@ -49,6 +53,7 @@ module Aws
 
       # Indicates if all items have been processed.
       #
+      # See {Batch.write} for example usage.
       # @return [Boolean] +true+ if +unprocessed_items+ is empty, +false+
       #   otherwise
       def complete?
@@ -58,6 +63,7 @@ module Aws
       # Returns all +DeleteItem+ and +PutItem+ operations that have not yet been
       # processed successfully.
       #
+      # See {Batch.write} for example usage.
       # @return [Hash] All operations that have not yet successfully completed.
       def unprocessed_items
         operations

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

@@ -26,6 +26,8 @@ module Aws
       # in doubt, call this method to ensure your client is configured the way
       # you want it to be configured.
       #
+      # *Note*: {#dynamodb_client} is inherited from a parent model when
+      # +configure_client+ is explicitly specified in the parent.
       # @param [Hash] opts the options you wish to use to create the client.
       #  Note that if you include the option +:client+, all other options
       #  will be ignored. See the documentation for other options in the
@@ -33,15 +35,23 @@ module Aws
       # @option opts [Aws::DynamoDB::Client] :client allows you to pass in your
       #  own pre-configured client.
       def configure_client(opts = {})
-        @dynamodb_client = _build_client(opts)
+        if self.class != Module && Aws::Record.extends_record?(self) && opts.empty? &&
+          self.superclass.instance_variable_get('@dynamodb_client')
+            @dynamodb_client = self.superclass.instance_variable_get('@dynamodb_client')
+        else
+          @dynamodb_client = _build_client(opts)
+        end
       end
 
       # Gets the
-      # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html}
+      # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html Client}
       # instance that Transactions use. When called for the first time, if
       # {#configure_client} has not yet been called, will configure a new
       # client for you with default parameters.
       #
+      # *Note*: +dynamodb_client+ is inherited from a parent model when
+      # {configure_client} is explicitly specified in the parent.
+      #
       # @return [Aws::DynamoDB::Client] the Amazon DynamoDB client instance.
       def dynamodb_client
         @dynamodb_client ||= configure_client

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

@@ -54,7 +54,7 @@ module Aws
       # match your search.
       #
       # @return [Array<Aws::Record>] an array of the record items found in the
-      #   first page of reponses from the query or scan call.
+      #   first page of responses from the query or scan call.
       def page
         search_response = items
         @last_evaluated_key = search_response.last_evaluated_key

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

@@ -1,15 +1,4 @@
-# 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.
+# frozen_string_literal: true
 
 module Aws
   module Record
@@ -514,6 +503,43 @@ module Aws
           end
         end
 
+
+        # @example Usage Example
+        #   class MyModel
+        #     include Aws::Record
+        #     integer_attr :id,   hash_key: true
+        #     string_attr  :name, range_key: true
+        #   end
+        #
+        #   # returns a homogenous list of items
+        #   foo_items = MyModel.find_all(
+        #     [
+        #       {id: 1, name: 'n1'},
+        #       {id: 2, name: 'n2'}
+        #     ])
+        #
+        # Provides support for the
+        # {https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/DynamoDB/Client.html#batch_get_item-instance_method
+        # Aws::DynamoDB::Client#batch_get_item} for your model.
+        #
+        # This method will take a list of keys and return an instance of +Aws::Record::BatchRead+
+        #
+        # See {Batch.read} for more details.
+        # @param [Array] keys an array of item key hashes you wish to search for.
+        # @return [Aws::Record::BatchRead] An instance that contains modeled items
+        #  from the +BatchGetItem+ result and stores unprocessed keys to be
+        #  manually processed later.
+        # @raise [Aws::Record::Errors::KeyMissing] if your param hashes do not
+        #  include all the keys defined in model.
+        # @raise [ArgumentError] if the provided keys are a duplicate.
+        def find_all(keys)
+          Aws::Record::Batch.read do |db|
+            keys.each do |key|
+              db.find(self, key)
+            end
+          end
+        end
+
         # @example Usage Example
         #   class MyModel
         #     include Aws::Record

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

@@ -32,6 +32,13 @@ module Aws
         attribute
       end
 
+      def register_superclass_attribute (name, attribute)
+        _new_attr_validation(name, attribute)
+        @attributes[name] = attribute.dup
+        @storage_attributes[attribute.database_name] = name
+        attribute
+      end
+
       def attribute_for(name)
         @attributes[name]
       end

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

@@ -20,6 +20,17 @@ module Aws
         sub_class.instance_variable_set("@local_secondary_indexes", {})
         sub_class.instance_variable_set("@global_secondary_indexes", {})
         sub_class.extend(SecondaryIndexesClassMethods)
+        if Aws::Record.extends_record?(sub_class)
+          inherit_indexes(sub_class)
+        end
+      end
+
+      private
+      def self.inherit_indexes(klass)
+        superclass_lsi = klass.superclass.instance_variable_get("@local_secondary_indexes").dup
+        superclass_gsi = klass.superclass.instance_variable_get("@global_secondary_indexes").dup
+        klass.instance_variable_set("@local_secondary_indexes", superclass_lsi)
+        klass.instance_variable_set("@global_secondary_indexes", superclass_gsi)
       end
 
       module SecondaryIndexesClassMethods
@@ -28,6 +39,8 @@ module Aws
         # Secondary Indexes in the
         # {http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html Amazon DynamoDB Developer Guide}.
         #
+        # *Note*: {#local_secondary_indexes} is inherited from a parent model
+        # when +local_secondary_index+ is explicitly specified in the parent.
         # @param [Symbol] name index name for this local secondary index
         # @param [Hash] opts
         # @option opts [Symbol] :range_key the range key used by this local
@@ -46,6 +59,8 @@ module Aws
         # Global Secondary Indexes in the
         # {http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html Amazon DynamoDB Developer Guide}.
         #
+        # *Note*: {#global_secondary_indexes} is inherited from a parent model
+        # when +global_secondary_index+ is explicitly specified in the parent.
         # @param [Symbol] name index name for this global secondary index
         # @param [Hash] opts
         # @option opts [Symbol] :hash_key the hash key used by this global
@@ -60,12 +75,20 @@ module Aws
           global_secondary_indexes[name] = opts
         end
 
+        # Returns hash of local secondary index names to the index’s attributes.
+        #
+        # *Note*: +local_secondary_indexes+ is inherited from a parent model when {#local_secondary_index}
+        # is explicitly specified in the parent.
         # @return [Hash] hash of local secondary index names to the index's
         #   attributes.
         def local_secondary_indexes
           @local_secondary_indexes
         end
 
+        # Returns hash of global secondary index names to the index’s attributes.
+        #
+        # *Note*: +global_secondary_indexes+ is inherited from a parent model when {#global_secondary_index}
+        # is explicitly specified in the parent.
         # @return [Hash] hash of global secondary index names to the index's
         #   attributes.
         def global_secondary_indexes

data/lib/aws-record/record.rb

@@ -17,7 +17,19 @@ module Aws
   # 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.
-  #
+  # === Inheritance Support
+  # Aws Record models can be extended using standard ruby inheritance. The child
+  # model must include +Aws::Record+ in their model and the following will
+  # be inherited:
+  # * {#set_table_name set_table_name}
+  # * {#initialize Attributes and keys}
+  # * Mutation Tracking:
+  #   * {#enable_mutation_tracking enable_mutation_tracking}
+  #   * {#disable_mutation_tracking disable_mutation_tracking}
+  # * {#local_secondary_indexes local_secondary_indexes}
+  # * {#global_secondary_indexes global_secondary_indexes}
+  # * {ClientConfiguration#configure_client configure_client}
+  # See example below to see the feature in action.
   # @example A class definition using +Aws::Record+
   #   class MyModel
   #     include Aws::Record
@@ -28,6 +40,21 @@ module Aws
   #     string_set_attr :tags
   #     map_attr        :metadata
   #   end
+  # @example Inheritance between models
+  #   class Animal
+  #     include Aws::Record
+  #     string_attr :name, hash_key: true
+  #     integer_attr :age
+  #   end
+  #
+  #   class Dog < Animal
+  #     include Aws::Record
+  #     boolean_attr :family_friendly
+  #   end
+  #
+  #   dog = Dog.find(name: 'Sunflower')
+  #   dog.age = 3
+  #   dog.family_friendly = true
   module Record
     # @!parse extend RecordClassMethods
     # @!parse include Attributes
@@ -57,6 +84,14 @@ module Aws
       sub_class.send(:include, DirtyTracking)
       sub_class.send(:include, Query)
       sub_class.send(:include, SecondaryIndexes)
+      if Aws::Record.extends_record?(sub_class)
+        inherit_track_mutations(sub_class)
+      end
+    end
+
+    # @api private
+    def self.extends_record?(klass)
+      klass.superclass.include?(Aws::Record)
     end
 
     private
@@ -64,6 +99,11 @@ module Aws
       self.class.dynamodb_client
     end
 
+    def self.inherit_track_mutations(klass)
+      superclass_track_mutations = klass.superclass.instance_variable_get("@track_mutations")
+      klass.instance_variable_set("@track_mutations", superclass_track_mutations)
+    end
+
     module RecordClassMethods
 
       # Returns the Amazon DynamoDB table name for this model class.
@@ -72,12 +112,14 @@ module Aws
       # also define a custom table name at the class level to be anything that
       # you want.
       #
+      # *Note*: +table_name+ is inherited from a parent model when {set_table_name}
+      # is explicitly specified in the parent.
       # @example
       #   class MyTable
       #     include Aws::Record
       #   end
       #
-      #   class MyTableTest
+      #   class MyOtherTable
       #     include Aws::Record
       #     set_table_name "test_MyTable"
       #   end
@@ -85,29 +127,65 @@ module Aws
       #   MyTable.table_name      # => "MyTable"
       #   MyOtherTable.table_name # => "test_MyTable"
       def table_name
-        if @table_name
-          @table_name
-        else
-          @table_name = self.name.split("::").join("_")
+        @table_name ||= begin
+          if Aws::Record.extends_record?(self) &&
+              default_table_name(self.superclass) != self.superclass.table_name
+            self.superclass.instance_variable_get('@table_name')
+          else
+            default_table_name(self)
+          end
         end
       end
 
       # Allows you to set a custom Amazon DynamoDB table name for this model
       # class.
+      # === Inheritance Support
+      # +table_name+ is inherited from a parent model when it is explicitly specified
+      # in the parent.
       #
-      # @example
+      # The parent model will need to have +set_table_name+ defined in their model
+      # for the child model to inherit the +table_name+.
+      # If no +set_table_name+ is defined, the parent and child models will have separate
+      # table names based on their class name.
+      #
+      # If both parent and child models have defined +set_table_name+ in their model,
+      # the child model will override the +table_name+ with theirs.
+      # @example Setting custom table name for model class
       #   class MyTable
       #     include Aws::Record
       #     set_table_name "prod_MyTable"
       #   end
       #
-      #   class MyTableTest
+      #   class MyOtherTable
       #     include Aws::Record
       #     set_table_name "test_MyTable"
       #   end
       #
       #   MyTable.table_name      # => "prod_MyTable"
       #   MyOtherTable.table_name # => "test_MyTable"
+      # @example Child model inherits table name from Parent model
+      #   class Animal
+      #     include Aws::Record
+      #     set_table_name "AnimalTable"
+      #   end
+      #
+      #   class Dog < Animal
+      #     include Aws::Record
+      #   end
+      #
+      #   Dog.table_name      # => "AnimalTable"
+      # @example Child model overrides table name from Parent model
+      #   class Animal
+      #     include Aws::Record
+      #     set_table_name "AnimalTable"
+      #   end
+      #
+      #   class Dog < Animal
+      #     include Aws::Record
+      #     set_table_name "DogTable"
+      #   end
+      #
+      #   Dog.table_name      # => "DogTable"
       def set_table_name(name)
         @table_name = name
       end
@@ -149,6 +227,9 @@ module Aws
       end
 
       # Turns off mutation tracking for all attributes in the model.
+      #
+      # *Note*: +disable_mutation_tracking+ is inherited from a parent model
+      # when it is explicitly specified in the parent.
       def disable_mutation_tracking
         @track_mutations = false
       end
@@ -158,6 +239,9 @@ module Aws
       # call this. It is provided in case there is a need to dynamically turn
       # this feature on and off, though that would be generally discouraged and
       # could cause inaccurate mutation tracking at runtime.
+      #
+      # *Note*: +enable_mutation_tracking+ is inherited from a parent model
+      # when it is explicitly specified in the parent.
       def enable_mutation_tracking
         @track_mutations = true
       end
@@ -177,6 +261,13 @@ module Aws
           raise Errors::InvalidModel.new("Table models must include a hash key")
         end
       end
+
+      private
+      def default_table_name(klass)
+        return unless klass.name
+        klass.name.split("::").join("_")
+      end
+
     end
   end
 end

data/lib/aws-record.rb

@@ -1,15 +1,4 @@
-# Copyright 2015-2017 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.
+# frozen_string_literal: true
 
 require 'aws-sdk-dynamodb'
 require_relative 'aws-record/record/client_configuration'
@@ -30,6 +19,7 @@ require_relative 'aws-record/record/table_migration'
 require_relative 'aws-record/record/version'
 require_relative 'aws-record/record/transactions'
 require_relative 'aws-record/record/buildable_search'
+require_relative 'aws-record/record/batch_read'
 require_relative 'aws-record/record/batch_write'
 require_relative 'aws-record/record/batch'
 require_relative 'aws-record/record/marshalers/string_marshaler'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-record
 version: !ruby/object:Gem::Version
-  version: 2.8.0
+  version: 2.10.0
 platform: ruby
 authors:
 - Amazon Web Services
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-12 00:00:00.000000000 Z
+date: 2023-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-dynamodb
@@ -37,6 +37,7 @@ files:
 - lib/aws-record/record/attribute.rb
 - lib/aws-record/record/attributes.rb
 - lib/aws-record/record/batch.rb
+- lib/aws-record/record/batch_read.rb
 - lib/aws-record/record/batch_write.rb
 - lib/aws-record/record/buildable_search.rb
 - lib/aws-record/record/client_configuration.rb
@@ -65,7 +66,7 @@ files:
 - lib/aws-record/record/table_migration.rb
 - lib/aws-record/record/transactions.rb
 - lib/aws-record/record/version.rb
-homepage: http://github.com/aws/aws-sdk-ruby-record
+homepage: https://github.com/aws/aws-sdk-ruby-record
 licenses:
 - Apache 2.0
 metadata: {}