aws-sdk-v1 1.52.0

data/lib/aws/core/collection.rb

@@ -0,0 +1,263 @@
+# Copyright 2011-2013 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 Core
+
+    # Provides useful methods for enumerating items in a collection.
+    module Collection
+
+      autoload :Simple, 'aws/core/collection/simple'
+      autoload :WithNextToken, 'aws/core/collection/with_next_token'
+      autoload :WithLimitAndNextToken, 'aws/core/collection/with_limit_and_next_token'
+
+      include Enumerable
+
+      # Yields once for every item in this collection.
+      #
+      #     collection.each {|item| ... }
+      #
+      # @note If you want fewer than all items, it is generally better
+      #   to call {#page} than {#each} with a `:limit`.
+      #
+      # @param [Hash] options
+      #
+      # @option options [Integer] :limit (nil) The maximum number of
+      #   items to enumerate from this collection.
+      #
+      # @option options [next_token] :next_token (nil)
+      #   Acts as an offset.  `:next_token` may be returned by {#each} and
+      #   {#each_batch} when a `:limit` is provided.
+      #
+      # @return [nil_or_next_token] Returns nil if all items were enumerated.
+      #   If some items were excluded because of a `:limit` option then
+      #   a `next_token` is returned.  Calling an enumerable method on
+      #   the same collection with the `next_token` acts like an offset.
+      #
+      def each options = {}, &block
+        each_batch(options) do |batch|
+          batch.each(&block)
+        end
+      end
+
+      # Yields items from this collection in batches.
+      #
+      #     collection.each_batch do |batch|
+      #       batch.each do |item|
+      #         # ...
+      #       end
+      #     end
+      #
+      # ## Variable Batch Sizes
+      #
+      # Each AWS service has its own rules on how it returns results.
+      # Because of this batch size may very based on:
+      #
+      # * Service limits (e.g. S3 limits keys to 1000 per response)
+      #
+      # * The size of response objects (SimpleDB limits responses to 1MB)
+      #
+      # * Time to process the request
+      #
+      # Because of these variables, batch sizes may not be consistent for
+      # a single collection.  Each batch represents all of the items returned
+      # in a single resopnse.
+      #
+      # @note If you require fixed batch sizes, see {#in_groups_of}.
+      # @param (see #each)
+      # @option (see #each)
+      # @return (see #each)
+      def each_batch options = {}, &block
+        _each_batch(options.dup, &block)
+      end
+
+      # Use this method when you want to call a method provided by
+      # Enumerable, but you need to pass options:
+      #
+      #     # raises an error because collect does not accept arguments
+      #     collection.collect(:limit => 10) {|i| i.name }
+      #
+      #     # not an issue with the enum method
+      #     collection.enum(:limit => 10).collect(&:name)
+      #
+      # @param (see #each)
+      # @option (see #each)
+      # @return [Enumerable::Enumerator] Returns an enumerator for this
+      #   collection.
+      #
+      def enum options = {}
+        to_enum(:each, options)
+      end
+      alias_method :enumerator, :enum
+
+      # Returns the first item from this collection.
+      #
+      # @return [item_or_nil] Returns the first item from this collection or
+      #   nil if the collection is empty.
+      #
+      def first options = {}
+        enum(options.merge(:limit => 1)).first
+      end
+
+      # Yields items from this collection in groups of an exact
+      # size (except for perhaps the last group).
+      #
+      #     collection.in_groups_of (10, :limit => 30) do |group|
+      #
+      #       # each group should be exactly 10 items unless
+      #       # fewer than 30 items are returned by the service
+      #       group.each do |item|
+      #         #...
+      #       end
+      #
+      #     end
+      #
+      # @param [Integer] size Size each each group of objects
+      #   should be yielded in.
+      # @param [Hash] options
+      # @option (see #each)
+      # @return (see #each)
+      def in_groups_of size, options = {}, &block
+
+        group = []
+
+        nil_or_next_token = each_batch(options) do |batch|
+          batch.each do |item|
+            group << item
+            if group.size == size
+              yield(group)
+              group = []
+            end
+          end
+        end
+
+        yield(group) unless group.empty?
+
+        nil_or_next_token
+
+      end
+
+      # Returns a single page of results in a kind-of array ({PageResult}).
+      #
+      #     items = collection.page(:per_page => 10) # defaults to 10 items
+      #     items.is_a?(Array) # => true
+      #     items.size         # => 8
+      #     items.per_page     # => 10
+      #     items.last_page?   # => true
+      #
+      # If you need to display a "next page" link in a web view you can
+      # use the #more? method.  Just make sure the generated link
+      # contains the `next_token`.
+      #
+      #     <% if items.more? %>
+      #       <%= link_to('Next Page', params.merge(:next_token => items.next_token) %>
+      #     <% end %>
+      #
+      # Then in your controller you can find the next page of results:
+      #
+      #     items = collection.page(:next_token => params[:next_token])
+      #
+      # Given a {PageResult} you can also get more results directly:
+      #
+      #     more_items = items.next_page
+      #
+      # @note This method does not accept a `:page` option, which means you
+      #   can only start at the begining of the collection and request
+      #   the next page of results.  You can not choose an offset
+      #   or know how many pages of results there will be.
+      #
+      # @param [Hash] options A hash of options that modifies the
+      #   items returned in the page of results.
+      #
+      # @option options [Integer] :per_page (10) The number of results
+      #   to return for each page.
+      #
+      # @option options [String] :next_token (nil) A token that indicates
+      #   an offset to use when paging items.  Next tokens are returned
+      #   by {PageResult#next_token}.
+      #
+      #   Next tokens should only be consumed by the same collection that
+      #   created them.
+      #
+      def page options = {}
+
+        each_opts = options.dup
+
+        per_page = each_opts.delete(:per_page)
+        per_page = [nil,''].include?(per_page) ? 10 : per_page.to_i
+
+        each_opts[:limit] = per_page
+
+        items = []
+        next_token = each(each_opts) do |item|
+          items << item
+        end
+
+        Core::PageResult.new(self, items, per_page, next_token)
+
+      end
+
+      protected
+
+      def _each_batch options, &block
+        # should be defined in the collection modules
+        raise NotImplementedError
+      end
+
+      def _each_item next_token, options = {}, &block
+        # should be defined in classes included the collection modules
+        raise NotImplementedError
+      end
+
+      def _extract_next_token options
+        next_token = options.delete(:next_token)
+        next_token = nil if next_token == ''
+        next_token
+      end
+
+      def _extract_batch_size options
+        batch_size = options.delete(:batch_size)
+        batch_size = nil if batch_size == ''
+        batch_size = batch_size.to_i if batch_size
+        batch_size
+      end
+
+      def _extract_limit options
+        limit = options.delete(:limit) || _limit
+        limit = nil if limit == ''
+        limit = limit.to_i if limit
+        limit
+      end
+
+      # Override this method in collection classes that provide
+      # an alternative way to provide the limit than passinging
+      # it to the enumerable method as :limit.
+      #
+      # An example of when this would be useful:
+      #
+      #     collection.limit(10).each {|item| ... }
+      #
+      # The collection class including this module should define _limit
+      # and return the cached limit value (of 10 from this example).
+      # This value may still be overridden by a locally passed
+      # `:limit` option:
+      #
+      #     # limit 5 wins out
+      #     collection.limit(10).each(:limit => 5) {|item| ... }
+      #
+      def _limit
+        nil
+      end
+
+    end
+  end
+end

data/lib/aws/core/collection/simple.rb

@@ -0,0 +1,82 @@
+# Copyright 2011-2013 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 Core
+    module Collection
+
+      # AWS::Core::Collection::Simple is used by collections that always
+      # recieve every matching items in a single response.
+      #
+      # This means:
+      #
+      # * Paging methods are simulated
+      #
+      # * Next tokens are artificial (guessable numeric offsets)
+      #
+      # AWS services generally return all items only for requests with a
+      # small maximum number of results.
+      #
+      # See {AWS::Core::Collection} for documentation on the available
+      # collection methods.
+      module Simple
+
+        include Model
+        include Enumerable
+        include Collection
+
+        protected
+
+        def _each_batch options = {}, &block
+
+          limit = _extract_limit(options)
+          next_token = _extract_next_token(options)
+          offset = next_token ? next_token.to_i - 1 : 0
+
+          total = 0
+          skipped = 0
+          simulated_next_token = nil
+
+          batch = []
+          _each_item(options.dup) do |item|
+
+            total += 1
+
+            # skip until we reach our offset (derived from the "next token")
+            if skipped < offset
+              skipped += 1
+              next
+            end
+
+            if limit
+              if batch.size < limit
+                batch << item
+              else
+                simulated_next_token = total
+                break
+              end
+            else
+              batch << item
+            end
+
+          end
+
+          yield(batch)
+
+          simulated_next_token
+
+        end
+      end
+    end
+  end
+end

data/lib/aws/core/collection/with_limit_and_next_token.rb

@@ -0,0 +1,71 @@
+# Copyright 2011-2013 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 Core
+    module Collection
+
+      # # Collection::WithLimitAndNextToken
+      #
+      # This module is used by collections where the service may truncate
+      # responses but that also accept a upper limit of results to
+      # return in a single request.
+      #
+      # See {AWS::Core::Collection} for documentation on the available
+      # methods.
+      #
+      module WithLimitAndNextToken
+
+        include Model
+        include Collection
+        include Enumerable
+
+        protected
+
+        def _each_batch options = {}, &block
+
+          limit = _extract_limit(options)
+          batch_size = _extract_batch_size(options)
+          next_token = _extract_next_token(options)
+
+          total = 0  # count of items yeilded across all batches
+
+          begin
+
+            max = nil
+            if limit or batch_size
+              max = []
+              max << (limit - total) if limit
+              max << batch_size if batch_size
+              max = max.min
+            end
+
+            batch = []
+            next_token = _each_item(next_token, max, options.dup) do |item|
+
+              total += 1
+              batch << item
+
+            end
+
+            yield(batch)
+
+          end until next_token.nil? or (limit and limit == total)
+
+          next_token
+
+        end
+      end
+    end
+  end
+end

data/lib/aws/core/collection/with_next_token.rb

@@ -0,0 +1,97 @@
+# Copyright 2011-2013 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 Core
+    module Collection
+
+      # # Collection::WithNextToken
+      #
+      # When making a request to list elements from one of these
+      # collections, the response may return a next token.  This indicates
+      # there are more results than were returned.  You can not control
+      # the number of elements returned with each response.
+      #
+      # See {AWS::Core::Collection} for documentation on the available
+      # collection methods.
+      #
+      module WithNextToken
+
+        include Model
+        include Enumerable
+        include Collection
+
+        protected
+
+        def _each_batch options = {}, &block
+
+          limit = _extract_limit(options)
+
+          next_token, skip_count = _extract_next_token(options)
+
+          skipped = 0
+          collected = 0
+
+          begin
+
+            offset = 0
+            batch = []
+
+            next_token = _each_item(next_token, options.dup) do |item|
+
+              if skipped < skip_count
+                skipped += 1
+                next
+              end
+
+              if limit
+                if collected < limit
+                  batch << item
+                  collected += 1
+                else
+                  yield(batch)
+                  simulated_next_token = {}
+                  simulated_next_token[:token] = next_token if next_token
+                  simulated_next_token[:offset] = offset + skipped
+                  return simulated_next_token
+                end
+              else
+                batch << item
+                collected += 1
+              end
+
+              offset += 1
+
+            end # _each_item
+
+            yield(batch)
+
+          end until next_token.nil? or (limit and limit == collected)
+
+          next_token.nil? ? nil : { :token => next_token }
+
+        end
+
+        def _extract_next_token options
+          next_token = super
+          case next_token
+          when nil   then [nil, 0]
+          when Hash  then [next_token[:token], next_token[:offset] || 0]
+          else [next_token, 0]
+          end
+        end
+
+      end
+    end
+  end
+end