Module AWS::Core::Collection
In: lib/aws/core/collection/simple.rb
lib/aws/core/collection/limitable.rb
lib/aws/core/collection.rb

Different Collection Types in AWS

The Collection module acts as a namespace and base implementation for the primary collection types in AWS:

Each AWS service allows provides a method to enumerate resources.

Methods

each   each_batch   enum   enumerator   first   in_groups_of   page  

Included Modules

Enumerable

Classes and Modules

Module AWS::Core::Collection::Limitable
Module AWS::Core::Collection::Simple

Public Instance methods

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.

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 size batches, see {in_groups_of}.

@param (see each)

@option (see each)

@return (see each)

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.
enumerator(options = {})

Alias for 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.

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)

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.

[Validate]