RubyGems - dynamoid - Versions diffs - 0.2.0 → 0.3.0 - Mend

dynamoid 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (97) hide show

data/Dynamoid.gemspec +65 -3
data/Gemfile +3 -0
data/Gemfile.lock +6 -0
data/README.markdown +117 -22
data/Rakefile +22 -9
data/VERSION +1 -1
data/doc/.nojekyll +0 -0
data/doc/Dynamoid.html +300 -0
data/doc/Dynamoid/Adapter.html +1387 -0
data/doc/Dynamoid/Adapter/AwsSdk.html +1561 -0
data/doc/Dynamoid/Adapter/Local.html +1487 -0
data/doc/Dynamoid/Associations.html +131 -0
data/doc/Dynamoid/Associations/Association.html +1706 -0
data/doc/Dynamoid/Associations/BelongsTo.html +339 -0
data/doc/Dynamoid/Associations/ClassMethods.html +723 -0
data/doc/Dynamoid/Associations/HasAndBelongsToMany.html +339 -0
data/doc/Dynamoid/Associations/HasMany.html +339 -0
data/doc/Dynamoid/Associations/HasOne.html +339 -0
data/doc/Dynamoid/Components.html +202 -0
data/doc/Dynamoid/Config.html +395 -0
data/doc/Dynamoid/Config/Options.html +609 -0
data/doc/Dynamoid/Criteria.html +131 -0
data/doc/Dynamoid/Criteria/Chain.html +759 -0
data/doc/Dynamoid/Criteria/ClassMethods.html +98 -0
data/doc/Dynamoid/Document.html +512 -0
data/doc/Dynamoid/Document/ClassMethods.html +581 -0
data/doc/Dynamoid/Errors.html +118 -0
data/doc/Dynamoid/Errors/DocumentNotValid.html +210 -0
data/doc/Dynamoid/Errors/Error.html +130 -0
data/doc/Dynamoid/Errors/InvalidField.html +133 -0
data/doc/Dynamoid/Errors/MissingRangeKey.html +133 -0
data/doc/Dynamoid/Fields.html +649 -0
data/doc/Dynamoid/Fields/ClassMethods.html +264 -0
data/doc/Dynamoid/Finders.html +128 -0
data/doc/Dynamoid/Finders/ClassMethods.html +502 -0
data/doc/Dynamoid/Indexes.html +308 -0
data/doc/Dynamoid/Indexes/ClassMethods.html +351 -0
data/doc/Dynamoid/Indexes/Index.html +1089 -0
data/doc/Dynamoid/Persistence.html +653 -0
data/doc/Dynamoid/Persistence/ClassMethods.html +568 -0
data/doc/Dynamoid/Validations.html +399 -0
data/doc/_index.html +439 -0
data/doc/class_list.html +47 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +55 -0
data/doc/css/style.css +322 -0
data/doc/file.LICENSE.html +66 -0
data/doc/file.README.html +279 -0
data/doc/file_list.html +52 -0
data/doc/frames.html +13 -0
data/doc/index.html +279 -0
data/doc/js/app.js +205 -0
data/doc/js/full_list.js +173 -0
data/doc/js/jquery.js +16 -0
data/doc/method_list.html +1054 -0
data/doc/top-level-namespace.html +105 -0
data/lib/dynamoid.rb +2 -1
data/lib/dynamoid/adapter.rb +77 -6
data/lib/dynamoid/adapter/aws_sdk.rb +96 -16
data/lib/dynamoid/adapter/local.rb +84 -15
data/lib/dynamoid/associations.rb +53 -4
data/lib/dynamoid/associations/association.rb +154 -26
data/lib/dynamoid/associations/belongs_to.rb +32 -6
data/lib/dynamoid/associations/has_and_belongs_to_many.rb +29 -3
data/lib/dynamoid/associations/has_many.rb +30 -4
data/lib/dynamoid/associations/has_one.rb +26 -3
data/lib/dynamoid/components.rb +7 -5
data/lib/dynamoid/config.rb +15 -2
data/lib/dynamoid/config/options.rb +8 -0
data/lib/dynamoid/criteria.rb +7 -2
data/lib/dynamoid/criteria/chain.rb +55 -8
data/lib/dynamoid/document.rb +68 -7
data/lib/dynamoid/errors.rb +17 -2
data/lib/dynamoid/fields.rb +44 -1
data/lib/dynamoid/finders.rb +32 -6
data/lib/dynamoid/indexes.rb +22 -2
data/lib/dynamoid/indexes/index.rb +48 -7
data/lib/dynamoid/persistence.rb +111 -51
data/lib/dynamoid/validations.rb +36 -0
data/spec/app/models/address.rb +2 -1
data/spec/app/models/camel_case.rb +11 -0
data/spec/app/models/magazine.rb +4 -1
data/spec/app/models/sponsor.rb +3 -1
data/spec/app/models/subscription.rb +5 -1
data/spec/app/models/user.rb +10 -1
data/spec/dynamoid/associations/association_spec.rb +67 -1
data/spec/dynamoid/associations/belongs_to_spec.rb +16 -1
data/spec/dynamoid/associations/has_and_belongs_to_many_spec.rb +7 -0
data/spec/dynamoid/associations/has_many_spec.rb +14 -0
data/spec/dynamoid/associations/has_one_spec.rb +10 -1
data/spec/dynamoid/criteria_spec.rb +5 -1
data/spec/dynamoid/document_spec.rb +23 -3
data/spec/dynamoid/fields_spec.rb +10 -1
data/spec/dynamoid/indexes/index_spec.rb +19 -0
data/spec/dynamoid/persistence_spec.rb +24 -0
data/spec/dynamoid/validations_spec.rb +36 -0
metadata +105 -4

data/doc/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,105 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.7.5
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
+<script type="text/javascript" charset="utf-8">
+  relpath = '';
+  if (relpath != '') relpath += '/';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <script type="text/javascript" charset="utf-8">
+      if (window.top.frames.main) document.body.className = 'frames';
+    </script>
+    <div id="header">
+      <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
+</div>
+      <div id="search">
+    <a id="class_list_link" href="#">Class List</a>
+    <a id="method_list_link" href="#">Method List</a>
+    <a id="file_list_link" href="#">File List</a>
+</div>
+      <div class="clear"></div>
+    </div>
+    <iframe id="search_frame"></iframe>
+    <div id="content"><h1>Top Level Namespace
+</h1>
+<dl class="box">
+</dl>
+<div class="clear"></div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Dynamoid.html" title="Dynamoid (module)">Dynamoid</a></span>
+</p>
+</div>
+    <div id="footer">
+  Generated on Tue Mar 27 17:53:07 2012 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.7.5 (ruby-1.9.3).
+</div>
+  </body>
+</html>

data/lib/dynamoid.rb CHANGED Viewed

@@ -13,6 +13,7 @@ require 'dynamoid/fields'
 require 'dynamoid/indexes'
 require 'dynamoid/associations'
 require 'dynamoid/persistence'
+require 'dynamoid/validations'
 require 'dynamoid/criteria'
 require 'dynamoid/finders'
 require 'dynamoid/config'
@@ -37,4 +38,4 @@ module Dynamoid
     @included_models ||= []
   end
-end
+end

data/lib/dynamoid/adapter.rb CHANGED Viewed

@@ -1,15 +1,23 @@
 # encoding: utf-8
-module Dynamoid #:nodoc:
+module Dynamoid
+  # Adapter provides a generic, write-through class that abstracts variations in the underlying connections to provide a uniform response
+  # to Dynamoid.
   module Adapter
     extend self
     attr_accessor :tables
+    # The actual adapter currently in use: presently, either AwsSdk or Local.
+    #
+    # @since 0.2.0
     def adapter
       reconnect! unless @adapter
       @adapter
     end
+    # Establishes a connection to the underyling adapter and caches all its tables for speedier future lookups. Issued when the adapter is first called.
+    #
+    # @since 0.2.0
     def reconnect!
       require "dynamoid/adapter/#{Dynamoid::Config.adapter}" unless Dynamoid::Adapter.const_defined?(Dynamoid::Config.adapter.camelcase)
       @adapter = Dynamoid::Adapter.const_get(Dynamoid::Config.adapter.camelcase)
@@ -17,6 +25,15 @@ module Dynamoid #:nodoc:
       self.tables = benchmark('Cache Tables') {list_tables}
     end
+    # Shows how long it takes a method to run on the adapter. Useful for generating logged output.
+    #
+    # @param [Symbol] method the name of the method to appear in the log
+    # @param [Array] args the arguments to the method to appear in the log
+    # @yield the actual code to benchmark
+    #
+    # @return the result of the yield
+    #
+    # @since 0.2.0
     def benchmark(method, *args)
       start = Time.now
       result = yield
@@ -24,6 +41,14 @@ module Dynamoid #:nodoc:
       return result
     end
+    # Write an object to the adapter. Partition it to a randomly selected key first if necessary.
+    #
+    # @param [String] table the name of the table to write the object to
+    # @param [Object] object the object itself
+    #
+    # @return [Object] the persisted object
+    #
+    # @since 0.2.0
     def write(table, object)
       if Dynamoid::Config.partitioning? && object[:id]
         object[:id] = "#{object[:id]}.#{Random.rand(Dynamoid::Config.partition_size)}"
@@ -32,6 +57,16 @@ module Dynamoid #:nodoc:
       benchmark('Put Item', object) {put_item(table, object)}
     end
+    # Read one or many keys from the selected table. This method intelligently calls batch_get or get on the underlying adapter depending on
+    # whether ids is a range or a single key: additionally, if partitioning is enabled, it batch_gets all keys in the partition space
+    # automatically. Finally, if a range key is present, it will also interpolate that into the ids so that the batch get will acquire the
+    # correct record.
+    #
+    # @param [String] table the name of the table to write the object to
+    # @param [Array] ids to fetch, can also be a string of just one id
+    # @param [Number] range_key the range key of the record
+    #
+    # @since 0.2.0
     def read(table, ids, range_key = nil)
       if ids.respond_to?(:each)
         ids = ids.collect{|id| range_key ? [id, range_key] : id}
@@ -52,16 +87,29 @@ module Dynamoid #:nodoc:
       end
     end
-    def delete(table, id)
+    # Delete an item from a table. If partitioning is turned on, deletes all partitioned keys as well.
+    #
+    # @param [String] table the name of the table to write the object to
+    # @param [String] id the id of the record
+    # @param [Number] range_key the range key of the record
+    #
+    # @since 0.2.0
+    def delete(table, id, range_key = nil)
       if Dynamoid::Config.partitioning?
         benchmark('Delete Item', id) do
-          id_with_partitions(id).each {|i| delete_item(table, i)}
+          id_with_partitions(id).each {|i| delete_item(table, i, range_key)}
         end
       else
-        benchmark('Delete Item', id) {delete_item(table, id)}
+        benchmark('Delete Item', id) {delete_item(table, id, range_key)}
       end
     end
+    # Scans a table. Generally quite slow; try to avoid using scan if at all possible.
+    #
+    # @param [String] table the name of the table to write the object to
+    # @param [Hash] scan_hash a hash of attributes: matching records will be returned by the scan
+    #
+    # @since 0.2.0
     def scan(table, query)
       if Dynamoid::Config.partitioning?
         results = benchmark('Scan', table, query) {adapter.scan(table, query)}
@@ -72,17 +120,37 @@ module Dynamoid #:nodoc:
     end
     [:batch_get_item, :create_table, :delete_item, :delete_table, :get_item, :list_tables, :put_item].each do |m|
+      # Method delegation with benchmark to the underlying adapter. Faster than relying on method_missing.
+      #
+      # @since 0.2.0
       define_method(m) do |*args|
         benchmark("#{m.to_s}", args) {adapter.send(m, *args)}
       end
     end
+    # Takes a list of ids and returns them with partitioning added. If an array of arrays is passed, we assume the second key is the range key
+    # and pass it in unchanged.
+    #
+    # @example Partition id 1
+    #   Dynamoid::Adapter.id_with_partitions(['1']) # ['1.0', '1.1', '1.2', ..., '1.199']
+    # @example Partition id 1 and range_key 1.0
+    #   Dynamoid::Adapter.id_with_partitions([['1', 1.0]]) # [['1.0', 1.0], ['1.1', 1.0], ['1.2', 1.0], ..., ['1.199', 1.0]]
+    #
+    # @param [Array] ids array of ids to partition
+    #
+    # @since 0.2.0
     def id_with_partitions(ids)
       Array(ids).collect {|id| (0...Dynamoid::Config.partition_size).collect{|n| id.is_a?(Array) ? ["#{id.first}.#{n}", id.last] : "#{id}.#{n}"}}.flatten(1)
     end
+    # Takes an array of results that are partitioned, find the most recently updated one, and return only it. Compares each result by
+    # their id and updated_at attributes; if the updated_at is the greatest, then it must be the correct result.
+    #
+    # @param [Array] returned partitioned results from a query
+    #
+    # @since 0.2.0
     def result_for_partition(results)
-      Hash.new.tap do |hash|
+      {}.tap do |hash|
         Array(results).each do |result|
           next if result.nil?
           id = result[:id].split('.').first
@@ -94,6 +162,9 @@ module Dynamoid #:nodoc:
       end.values
     end
+    # Delegate all methods that aren't defind here to the underlying adapter.
+    #
+    # @since 0.2.0
     def method_missing(method, *args)
       return benchmark(method, *args) {adapter.send(method, *args)} if @adapter.respond_to?(method)
       super
@@ -101,4 +172,4 @@ module Dynamoid #:nodoc:
   end
-end
+end

data/lib/dynamoid/adapter/aws_sdk.rb CHANGED Viewed

@@ -1,20 +1,45 @@
+# encoding: utf-8
 require 'aws'
 module Dynamoid
   module Adapter
+    # The AwsSdk adapter provides support for the AWS-SDK for Ruby gem.
+    # More information is available at that Gem's Github page:
+    # https://github.com/amazonwebservices/aws-sdk-for-ruby
+    #
     module AwsSdk
       extend self
       @@connection = nil
+      # Establish the connection to DynamoDB.
+      #
+      # @return [AWS::DynamoDB::Connection] the raw DynamoDB connection
+      #
+      # @since 0.2.0
       def connect!
         @@connection = AWS::DynamoDB.new(:access_key_id => Dynamoid::Config.access_key, :secret_access_key => Dynamoid::Config.secret_key)
       end
+      # Return the established connection.
+      #
+      # @return [AWS::DynamoDB::Connection] the raw DynamoDB connection
+      #
+      # @since 0.2.0
       def connection
         @@connection
       end
-      # BatchGetItem
+      # Get many items at once from DynamoDB. More efficient than getting each item individually.
+      #
+      # @example Retrieve IDs 1 and 2 from the table testtable
+      #   Dynamoid::Adapter::AwsSdk.batch_get_item('table1' => ['1', '2'])
+      #
+      # @param [Hash] options the hash of tables and IDs to retrieve
+      #
+      # @return [Hash] a hash where keys are the table names and the values are the retrieved items
+      #
+      # @since 0.2.0
       def batch_get_item(options)
         hash = Hash.new{|h, k| h[k] = []}
         return hash if options.all?{|k, v| v.empty?}
@@ -30,16 +55,30 @@ module Dynamoid
         hash
       end
-      # CreateTable
+      # Create a table on DynamoDB. This usually takes a long time to complete.
+      #
+      # @param [String] table_name the name of the table to create
+      # @param [Symbol] key the table's primary key (defaults to :id)
+      # @param [Hash] options provide a range_key here if you want one for the table
+      #
+      # @since 0.2.0
       def create_table(table_name, key = :id, options = {})
         options[:hash_key] ||= {key.to_sym => :string}
         options[:range_key] = {options[:range_key].to_sym => :number} if options[:range_key]
-        table = @@connection.tables.create(table_name, 100, 20, options)
+        read_capacity = options[:read_capacity] || Dynamoid::Config.read_capacity
+        write_capacity = options[:write_capacity] || Dynamoid::Config.write_capacity
+        table = @@connection.tables.create(table_name, read_capacity, write_capacity, options)
         sleep 0.5 while table.status == :creating
         return table
       end
-      # DeleteItem
+      # Removes an item from DynamoDB.
+      #
+      # @param [String] table_name the name of the table
+      # @param [String] key the hash key of the item to delete
+      # @param [Number] range_key the range key of the item to delete, required if the table has a composite key
+      #
+      # @since 0.2.0
       def delete_item(table_name, key, range_key = nil)
         table = @@connection.tables[table_name]
         table.load_schema
@@ -52,14 +91,27 @@ module Dynamoid
         true
       end
-      # DeleteTable
+      # Deletes an entire table from DynamoDB. Only 10 tables can be in the deleting state at once,
+      # so if you have more this method may raise an exception.
+      #
+      # @param [String] table_name the name of the table to destroy
+      #
+      # @since 0.2.0
       def delete_table(table_name)
         @@connection.tables[table_name].delete
       end
-      # DescribeTable
+      # @todo Add a DescribeTable method.
-      # GetItem
+      # Fetches an item from DynamoDB.
+      #
+      # @param [String] table_name the name of the table
+      # @param [String] key the hash key of the item to find
+      # @param [Number] range_key the range key of the item to find, required if the table has a composite key
+      #
+      # @return [Hash] a hash representing the raw item in DynamoDB
+      #
+      # @since 0.2.0
       def get_item(table_name, key, range_key = nil)
         table = @@connection.tables[table_name]
         table.load_schema
@@ -73,23 +125,43 @@ module Dynamoid
         else
           result.symbolize_keys!
         end
-      rescue
-        raise [table_name, key, range_key].inspect
       end
-      # ListTables
+      # List all tables on DynamoDB.
+      #
+      # @since 0.2.0
       def list_tables
         @@connection.tables.collect(&:name)
       end
-      # PutItem
+      # Persists an item on DynamoDB.
+      #
+      # @param [String] table_name the name of the table
+      # @param [Object] object a hash or Dynamoid object to persist
+      #
+      # @since 0.2.0
       def put_item(table_name, object)
         table = @@connection.tables[table_name]
         table.load_schema
         table.items.create(object.delete_if{|k, v| v.nil? || (v.respond_to?(:empty?) && v.empty?)})
       end
-      # Query
+      # Query the DynamoDB table. This employs DynamoDB's indexes so is generally faster than scanning, but is
+      # only really useful for range queries, since it can only find by one hash key at once. Only provide
+      # one range key to the hash.
+      #
+      # @param [String] table_name the name of the table
+      # @param [Hash] opts the options to query the table with
+      # @option opts [String] :hash_value the value of the hash key to find
+      # @option opts [Range] :range_value find the range key within this range
+      # @option opts [Number] :range_greater_than find range keys greater than this
+      # @option opts [Number] :range_less_than find range keys less than this
+      # @option opts [Number] :range_gte find range keys greater than or equal to this
+      # @option opts [Number] :range_lte find range keys less than or equal to this
+      #
+      # @return [Array] an array of all matching items
+      #
+      # @since 0.2.0
       def query(table_name, opts = {})
         table = @@connection.tables[table_name]
         table.load_schema
@@ -103,7 +175,15 @@ module Dynamoid
         end
       end
-      # Scan
+      # Scan the DynamoDB table. This is usually a very slow operation as it naively filters all data on
+      # the DynamoDB servers.
+      #
+      # @param [String] table_name the name of the table
+      # @param [Hash] scan_hash a hash of attributes: matching records will be returned by the scan
+      #
+      # @return [Array] an array of all matching items
+      #
+      # @since 0.2.0
       def scan(table_name, scan_hash)
         table = @@connection.tables[table_name]
         table.load_schema
@@ -114,9 +194,9 @@ module Dynamoid
         results
       end
-      # UpdateItem
+      # @todo Add an UpdateItem method.
-      # UpdateTable
+      # @todo Add an UpdateTable method.
     end
   end
-end
+end