poro 0.1.0

data/LICENSE.txt

@@ -0,0 +1,24 @@
+Copyright (c) 2010, Jeffrey C. Reinecke
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the copyright holders nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL JEFFREY REINECKE BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.rdoc

@@ -0,0 +1,215 @@
+= Overview
+
+The name "Poro" is derived from "plain ol' Ruby object".  Poro is a simple and
+lightweight persistence engine.  Unlike most persistence engines, which require
+your persistent objects to be subclasses of a base model class, Poro aims to
+extend plain ol' Ruby objects to be stored in any persist way you choose
+(e.g. SQL, MongoDB, Memcache), and even mix and match different stores between
+objects.
+
+Additionally, Poro takes a hands-off philosophy by default, only minimally
+disturbing an object it persists.  Of course, there is a mixin available to add
+model functionality to your object if you like, but how and when you do this
+is up to you.
+
+While the packages available for managing individual kinds of repositories focus
+on a large breadth of functionality, Poro aims to give the simplest, lightest
+weight, common interface possible for these storage methods.  Given the disparity
+in functionality available between different persistence stores
+(e.g. SLQ, key/value, documents), additional needs of the store are accomplished
+by working with the individual adapter package APIs themselves rather than
+through whatever inferior homogenized API Poro may try to provide.
+
+= Installation
+
+Basic usage only requires the installation of the gem:
+    gem install poro
+However to utilize any meaningful persistence data store, the underlying gems
+for the desired persistence contexts are needed.  The documentation of the
+desired Context class' documentation should inform you of any necessary gems,
+though a useful error is thrown if you are missing a needed gem, so it is
+probably easier to just try.
+
+If you wish to run the gem's unit tests, you should also install <tt>rspec</tt>.
+
+It is also worthwhile checking rake for meaningful tasks, using:
+    rake -T
+
+= Supported Data Stores
+
+Currently, the following data stores are supported:
+
+[MongoDB] Install the gems mongo and bson_ext, and you should be good to go!
+          Good automatic support embedded documents, including conversion to
+          objects when it can figure out how to do so.
+[In-Memory Hash] This is really only for trial and testing purposes as it stores
+                 everything in RAM and is lost when the application dies.
+
+The following data stores are currently planned for version 1.0:
+
+[SQL] Install the sequel gem and it should be good to go.
+[Memcache] Install instructions forthcoming.  Will be useful for those working
+           with web apps.
+
+= Architecture
+
+Poro revolves around Contexts.  Each class that must persist gets its own
+Context, and that Context manages the persistence of that object.
+
+Contexts come in many flavors, depending on the data store that backs them.  To
+create the data stores, the application must have a ContextFactory instance.
+There are different ContextFactories, depending on the needs of your application,
+but the base ContextFactory can be customized via a block.
+
+In general, Poro is hands-off with the objects it persists, however there is
+one exception:  In order for the ContextFactory to create a Context for an object,
+the object must be tagged as persistent by including Poro::Persistify.
+
+If you wish to have model-like functionality to your objects, you may also
+include Poro::Modelify.  This is not necessary for a Context to be used, but
+the convenience and familiarity of this paradigm makes this desirable functionality.
+
+= Getting Started
+
+The following sample code sets up a basic context manager for the application,
+using an in-memory only testing store (which is just a hash):
+
+    require 'poro'
+    
+    Poro::Context.factory = Poro::ContextFactories::SingleStore.instantiate(:hash)
+    
+    class Foo
+      include Poro::Persistify
+      include Poro::Modelify
+    end
+    
+    f = Foo.new
+    puts "f doesn't have an ID yet: #{f.id.inspect}"
+    f.save
+    puts "f now has an ID: #{f.id.inspect}"
+    g = Foo.fetch(f.id)
+    puts "g is a fetch of f and has the same ID as f: #{g.id.inspect}"
+    f.remove
+    puts "f no longer has an ID: #{f.id.inspect}"
+    
+= Configuration
+
+Each Context has its own configuration parameters, based on how its data store
+works.  There are two ways in which to manage this configuration, depending on
+the needs of your application.
+
+== Inline
+
+Many users, thanks to some popular Ruby ORMs, are most comfortable with model
+class inline configuration.  Poro's philosophy is to be hands off with objects
+in your code, however there is a convenience method included into your object
+when you mark it for persistence that makes inline configuration of the context
+easy:
+
+    class Person
+      include Poro::Persistify
+      configure_context do |context|
+        context.primary_key = :some_attribute
+      end
+      include Poro::Modelify # if you want model methods.
+    end
+    
+The above configure method is really just a shortcut to the
+<tt>configure_for_class</tt> method on Context, which can be called instead.
+
+== External
+
+The problem with inline configuration is that it does not abstract the
+persistence engine from the plain ol' ruby objects.  Poro provides a solution
+to this layering violation via a configuration block that is supplied during
+ContextManager initialization.  This block may return the fully configured
+Context instance for each persistified class.
+
+For example, the following generic code has the same result as
+<code>Poro::Context.factory = Poro::ContextFactories::SingleStore.instantiate(:hash)</code>,
+which uses a specialized factory:
+
+    Poro::Context.factory = Poro::ContextManager.new do |klass|
+      Poro::Contexts::HashContext.new(klass)
+    end
+
+Of course, one normally would have a more complex block and/or utilize one of
+the specialized factories, but this example shows just how simple a factory
+nees to be.
+
+Note that all Contexts are cached after creation, so the context configuration
+can be mutated by other methods (such as <tt>configure_for_class</tt> on Context),
+but developers are encouraged to choose one paradigm for their application and
+stick with it.
+
+= Contact
+
+If you have any questions, comments, concerns, patches, or bugs, you can contact
+me via the github repository at:
+
+http://github.com/paploo/poro
+
+or directly via e-mail at:
+
+mailto:jeff@paploo.net
+
+= Version History
+
+[0.1.0 - 2010-Sep-18] Initial public release.
+                      * Major base functionality is complete, though is subject
+                        to big changes as it is used in the real world.
+                      * Only supports MongoDB and Hash Contexts.
+                      * No performance testing and optimization yet done.
+                      * The documentation is rough around the edges and may contain errors.
+                      * Spec tests are incomplete.
+
+= TODO List
+
+The following are the primary TODO items, roughly in priority order:
+
+* Modelify: Break into modules for each piece of functionality.
+* Specs: Add specs for Context Find methods.
+  * Check that private methods are private.  (Should do on subclasses too.)
+  * Check that the two main find methods pass through to the correct underlying
+    methods or throw an argument when necessary. 
+* Specs: Add spec tests for Mongo Context.
+* Mongo Context: Split into modules in separate files.
+* Context: Split out modules into files.
+* Contexts: Add SQL Context.
+
+= License
+
+The files contained in this repository are released under the commercially and
+GPL compatible "New BSD License", given below:
+
+== License Text
+
+    Copyright (c) 2010, Jeffrey C. Reinecke
+    All rights reserved.
+    
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+        * Redistributions of source code must retain the above copyright
+          notice, this list of conditions and the following disclaimer.
+        * Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+        * Neither the name of the copyright holders nor the
+          names of its contributors may be used to endorse or promote products
+          derived from this software without specific prior written permission.
+    
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL JEFFREY REINECKE BE LIABLE FOR ANY
+    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Poro::Util::Inflector and its submodules are adapted from ActiveSupport,
+and its source is redistributed under the MIT license it was originally
+distributed under.  Thetext of this copyright notice is supplied
+in <tt>poro/util/inflector.rb</tt>.

data/Rakefile

@@ -0,0 +1,37 @@
+require 'rake'
+require "rake/rdoctask"
+
+# ===== RDOC BUILDING =====
+# This isn't necessary if installing from a gem.
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.rdoc_files.add "lib/**/*.rb", "README.rdoc"
+end
+
+# ===== SPEC TESTING =====
+
+begin
+  require "spec/rake/spectask"
+  
+  Spec::Rake::SpecTask.new(:spec) do |spec|
+    spec.spec_opts = ['-c' '-f specdoc']
+    spec.spec_files = ['spec']
+  end
+  
+  Spec::Rake::SpecTask.new(:spec_with_backtrace) do |spec|
+    spec.spec_opts = ['-c' '-f specdoc', '-b']
+    spec.spec_files = ['spec']
+  end
+rescue LoadError
+  task :spec do
+    puts "You must have rspec installed to run this task."
+  end
+end
+
+# ===== GEM BUILDING =====
+
+desc "Build the gem file for this package"
+task :build_gem do
+  STDOUT.puts `gem build poro.gemspec`
+end

data/lib/poro.rb

@@ -0,0 +1,14 @@
+# Require foundation.
+require 'poro/util'
+
+# Require core classes and modules.
+require 'poro/context_factory'
+require 'poro/context'
+require 'poro/persistify'
+
+# Require core expansions.
+require 'poro/context_factories'
+require 'poro/contexts'
+
+# Require modelfication modules.
+require 'poro/modelify'

data/lib/poro/context.rb

@@ -0,0 +1,459 @@
+module Poro
+  # This is the abstract superclass of all Contexts.
+  #
+  # For find methods, see FindMethods.
+  #
+  # The Context is the responsible delegate for directly interfacing with the
+  # persistence layer.  Each program class that needs persistence must have its
+  # own context instance that knows how to store/retrive only instances of that
+  # class.
+  #
+  # All instances respond to the methods declared here, and must conform to
+  # the rules described with each method.
+  #
+  # One normally uses a subclass of Context, and that subclass may have extra
+  # methods for setting options and configuring behavior.
+  class Context
+    
+    # Fetches the context for the given object or class from
+    # <tt>ContextFactory.instance</tt>.
+    # Returns nil if no context is found.
+    def self.fetch(obj)
+      if( obj.kind_of?(Class) )
+        return self.factory.fetch(obj)
+      else
+        return self.factory.fetch(obj.class)
+      end
+    end
+    
+    # Returns true if the given class is configured to be represented by a
+    # context.  This is done by including Poro::Persistify into the module.
+    def self.managed_class?(klass)
+      return self.factory.context_managed_class?(klass)
+    end
+    
+    # A convenience method for further configuration of a context over what the
+    # factory does, via the passed block.
+    #
+    # This really just fetches (and creates, if necessary) the
+    # Context for the class, and then yields it to the block.  Returns the context.
+    def self.configure_for_klass(klass)
+      context = self.fetch(klass)
+      yield(context) if block_given?
+      return context
+    end
+    
+    # Returns the application's ContextFactory instance.
+    def self.factory
+      return ContextFactory.instance
+    end
+    
+    # Sets the application's ContextFactory instance.
+    def self.factory=(context_factory)
+      ContextFactory.instance = context_factory
+    end
+    
+    # Initizialize this context for the given class.  Yields self if a block
+    # is given, so that instances can be easily configured at instantiation.
+    #
+    # Subclasses are expected to use this method (through calls to super).
+    def initialize(klass)
+      @klass = klass
+      self.data_store = nil unless defined?(@data_store)
+      self.primary_key = :id
+      yield(self) if block_given?
+    end
+    
+    # The class that this context instance services.
+    attr_reader :klass
+    
+    # The raw data store backing this context.  This is useful for advanced
+    # usage, such as special queries.  Be aware that whenever you use this,
+    # there is tight coupling with the underlying persistence store!
+    attr_reader :data_store
+    
+    # Sets the raw data store backing this context.  Useful during initial
+    # configuration and advanced usage, but can be dangerous.
+    attr_writer :data_store
+    
+    # Returns the a symbol for the method that returns the Context assigned
+    # primary key for the managed object.  This defaults to <tt>:id</tt>
+    attr_reader :primary_key
+    
+    # Set the method that returns the Context assigned primary key for the
+    # managed object.
+    #
+    # Note that if you want the primary key's instance variable value to be
+    # purged from saved data, you must name the accessor the same as the instance
+    # method (like if using attr_reader and attr_writer).
+    def primary_key=(pk)
+      @primary_key = pk.to_sym
+    end
+    
+    # Returns the primary key value from the given object, using the primary
+    # key set for this context.
+    def primary_key_value(obj)
+      return obj.send( primary_key() )
+    end
+    
+    # Sets the primary key value on the managed object, using the primary
+    # key set for this context.
+    def set_primary_key_value(obj, id)
+      method = (primary_key().to_s + '=').to_sym
+      obj.send(method, id)
+    end
+    
+    # Fetches the object from the store with the given id, or returns nil
+    # if there are none matching.
+    def fetch(id)
+      return convert_to_plain_object( clean_id(nil) )
+    end
+    
+    # Saves the given object to the persistent store using this context.
+    #
+    # Subclasses do not need to call super, but should follow the given rules:
+    #
+    # Returns self so that calls may be daisy chained.
+    #
+    # If the object has never been saved, it should be inserted and given
+    # an id.  If the object has been added before, the id is used to update
+    # the existing record.
+    #
+    # Raises an Error if save fails.
+    def save(obj)
+      obj.id = obj.object_id if obj.respond_to?(:id) && obj.id.nil? && obj.respond_to?(:id=)
+      return obj
+    end
+    
+    # Remove the given object from the persisten store using this context.
+    #
+    # Subclasses do not need to call super, but should follow the given rules:
+    #
+    # Returns self so that calls may be daisy chained.
+    #
+    # If the object is successfully removed, the id is set to nil.
+    #
+    # Raises an Error is the remove fails.
+    def remove(obj)
+      obj.id = nil if obj.respond_to?(:id=)
+      return obj
+    end
+    
+    # Convert the data from the data store into the correct plain ol' ruby
+    # object for the class this context represents.
+    #
+    # For non-embedded persistent stores, only records of the type for this
+    # context must be handled.  However, for embedded stores--or more
+    # complex embedded handling on non-embedded stores--more compex
+    # rules may be necessary, handling all sorts of data types.
+    #
+    # The second argument is reserved for state information that the method
+    # may need to pass around, say if it is recursively converting elements.
+    # Any root object returned from a "find" in the data store needs to be
+    # able to be converted
+    def convert_to_plain_object(data, state_info={})
+      return data
+    end
+    
+    # Convert a plain ol' ruby object into the data store data format this
+    # context represents.
+    #
+    # For non-embedded persistent stores, only records of the type for this
+    # context must be handled.  However, for embedded stores--or more
+    # complex embedded handling on non-embedded stores--more compex
+    # rules may be necessary, handling all sorts of data types.
+    #
+    # The second argument is reserved for state information that the method
+    # may need to pass around, say if it is recursively converting elements.
+    # Any root object returned from a "find" in the data store needs to be
+    # able to be converted
+    def convert_to_data(obj, state_info={})
+      return obj
+    end
+    
+    private 
+    
+    # Given a value that represents an ID, scrub it to produce a clean ID as
+    # is needed by the data store for the context.
+    #
+    # This is used by methods like <tt>fetch</tt> and <tt>find_for_ids</tt> to
+    # convert the IDs from whatever types the user passed, into the correct
+    # values.
+    def clean_id(id)
+      return id
+    end
+    
+  end
+end
+
+
+
+
+module Poro
+  class Context
+    # A mixin that contains all the context find methods.
+    #
+    # The methods are split into three groups:
+    # [FindMethods] Contains the methods that a developer should use but that
+    #               a Context author should never need to override.
+    # [FindMethods::RootMethods] Contains the methods that a developer should
+    #                            never need to use, but that a Context author
+    #                            needs to override.
+    # [FindMethods::HelperMethods] Some private helper methods that rarely need
+    #                              to be used or overriden.
+    #
+    # Note that <tt>fetch</tt> is considered basic functionality and not a 
+    # find method, even though it technically finds by id.
+    #
+    # Subclasses are expected to override the methods in RootMethods.
+    module FindMethods
+      
+      def self.included(mod) # :nodoc:
+        mod.send(:include, RootMethods)
+        mod.send(:private, *RootMethods.instance_methods)
+        mod.send(:include, HelperMethods)
+        mod.send(:private, *HelperMethods.instance_methods)
+      end
+      
+      # Provides the delegate methods for the find routines.
+      #
+      # These methods are made private so that developers use the main find
+      # methods.  This makes it easier to change behavior in the future due to
+      # the bottlenecking.
+      #
+      # Subclasses of Context should override all of these.
+      # See the inline subclassing documentation sections for each method for details.
+      module RootMethods
+        
+        # Returns an array of all the records that match the following options.
+        #
+        # One ususally calls this through <tt>find</tt> via the :all or :many argument.
+        #
+        # See <tt>find</tt> for more help.
+        #
+        # === Subclassing
+        #
+        # Subclasses MUST override this method.
+        #
+        # Subclases usually convert the options into a call to <tt>data_store_find_all</tt>.
+        def find_all(opts)
+          return data_store_find_all(opts)
+        end
+        
+        # Returns the first record that matches the following options.
+        # Use of <tt>fetch</tt> is more convenient if finding by ID.
+        #
+        # One usually calls this through <tt>find</tt> via the :first or :one argument.
+        #
+        # See <tt>find</tt> for more help.
+        #
+        # === Subclassing
+        #
+        # Subclasses MUST override this method!
+        #
+        # They usually take one of several tacts:
+        # 1. Convert tothe options and call <tt>data_store_find_first</tt>.
+        # 2. Set the limit to 1 and call <tt>find_all</tt>.
+        def find_first(opts)
+          hashize_limit(opts[:limit])[:limit] = 1
+          return find_all(opts)
+        end
+        
+        # Calls the relevant finder method on the underlying data store, and
+        # converts all the results to plain objects.
+        #
+        # One usually calls thrigh through the <tt>data_store_find</tt> method
+        # with the :all or :many arument.
+        #
+        # Use of this method is discouraged as being non-portable, but sometimes
+        # there is no alternative but to get right down to the underlying data
+        # store.
+        #
+        # Note that if this method still isn't enough, you'll have to use the
+        # data store and convert the objects yourself, like so:
+        #   SomeContext.data_store.find_method(arguments).map {{|data| SomeContext.convert_to_plain_object(data)}
+        #
+        # === Subclassing
+        #
+        # Subclasses MUST override this method.
+        #
+        # Subclasses are expected to return the results converted to plain objects using
+        #   self.convert_to_plain_object(data)
+        def data_store_find_all(*args, &block)
+          return [].map {|data| convert_to_plain_object(data)}
+        end
+        
+        # Calls the relevant finder method on the underlying data store, and
+        # converts the result to a plain object.
+        #
+        # One usually calls thrigh through the <tt>data_store_find</tt> method
+        # with the :first or :one arument.
+        #
+        # Use of this method is discouraged as being non-portable, but sometimes
+        # there is no alternative but to get right down to the underlying data
+        # store.
+        #
+        # Note that if this method still isn't enough, you'll have to use the
+        # data store and convert the object yourself, like so:
+        #   SomeContext.convert_to_plain_object( SomeContext.data_store.find_method(arguments) )
+        #
+        #
+        # === Subclassing
+        # 
+        # Subclasses MUST override this method.
+        #
+        # Subclasses are expected to return the result converted to a plain object using
+        #   self.convert_to_plain_object(data)
+        def data_store_find_first(*args, &block)
+          return convert_to_plain_object(nil)
+        end
+        
+        # Returns the records that correspond to the passed ids (or array of ids).
+        #
+        # One usually calls this by giving an array of IDs to the <tt>find</tt> method.
+        #
+        # === Subclassing
+        #
+        # Subclasses SHOULD override this method.
+        #
+        # By default, this method aggregates separate calls to find_by_id.  For
+        # most data stores this makes N calls to the server, decreasing performance.
+        #
+        # When possible, this method should be overriden by subclasses to be more
+        # efficient, probably calling a <tt>find_all</tt> with the IDs, as
+        # filtered by the <tt>clean_id</tt> private method.
+        def find_with_ids(*ids)
+          ids = ids.flatten
+          return ids.map {|id| find_by_id(id)}
+        end
+        
+      end
+      
+      # Contains some private helper methods to help process finds.  These
+      # rarely need to be used or overriden by Context subclasses.
+      module HelperMethods
+      
+        # Cleans the find opts.  This makes it so that no matter which (legal)
+        # style that they give their options to find, they are made into a single
+        # standard format that the subclasses can depend on.
+        def clean_find_opts(opts)
+          cleaned_opts = opts.dup
+          cleaned_opts[:limit] = hashize_limit(opts[:limit]) if opts.has_key?(:limit)
+          cleaned_opts[:order] = hashize_order(opts[:order]) if opts.has_key?(:order)
+          return cleaned_opts
+        end
+      
+        # Takes the limit option to find and returns a uniform hash version of it.
+        #
+        # The hash has the form:
+        #  {:limit => (integer || nil), :offset => (integer)}
+        #
+        # Note that a limit of nil means that all records shoudl be returned.
+        def hashize_limit(limit_opt)
+          if( limit_opt.kind_of?(Hash) )
+            return {:limit => nil, :offset => 0}.merge(limit_opt)
+          elsif( limit_opt.kind_of?(Array) )
+            return {:limit => limit_opt[0], :offset => limit_opt[1]||0}
+          else
+            return {:limit => (limit_opt&&limit_opt.to_i), :offset => 0}
+          end
+        end
+      
+        # Takes the order option to find and returns a uniform hash version of it.
+        #
+        # Returns a hash of each sort key followed by either :asc or :desc.  If
+        # there are no sort keys, this returns an empty hash.
+        def hashize_order(order_opt)
+          if( order_opt.kind_of?(Hash) )
+            return order_opt
+          elsif( order_opt.kind_of?(Array) )
+            return order_opt.inject({}) {|hash,(key,direction)| hash[key] = direction || :asc; hash}
+          elsif( order_opt.nil? )
+            return {}
+          else
+            return {order_opt => :asc}
+          end
+        end
+        
+      end
+      
+      # Fetches records according to the parameters given in opts.
+      #
+      # Contexts attempt to implement this method as uniformily as possible,
+      # however some features only exist in some backings and may or may not be
+      # portable.
+      #
+      # WARNING: For performance, some Contexts may not check that the passed
+      # options are syntactically correct before passing off to their data store.
+      # This could result in the inadvertent support of some underlying functionality
+      # that may go away in a refactor.  Please make sure you only use this method
+      # in the way it is documented for maximal future compatibility.
+      #
+      # Note that if you wish to work more directly with the data store's find
+      # methods, one should see <ttdata_store_find_all</tt> and
+      # <tt>data_store_find_first</tt>.
+      #
+      # The first argument must be one of the following:
+      # * An ID
+      # * An array of IDs
+      # * :all or :many
+      # * :first or :one
+      #
+      # The options are as follows:
+      # [:conditions] A hash of key-value pairs that will be matched against.  They
+      #               are joined by an "and".  Note that in contexts that support embedded
+      #               contexts, the keys may be dot separated keypaths.
+      # [:order]      The name of the key to order by in ascending order, an array of
+      #               keys to order by in ascending order, an array of arrays, or a hash, where
+      #               the first value is the key, and the second value is either :asc or :desc.
+      # [:limit]      Either the limit of the number of records to get, an array of the
+      #               limit and offset, or a hash with keys :limit and/or :offset.
+      #
+      # === Subclassing
+      #
+      # Subclasses MUST NOT override this method.
+      #
+      # This method delegates out its calls to other methods that should be
+      # overridden by subclasses.
+      def find(arg, opts={})
+        if(arg == :all || arg == :many)
+          return find_all(opts)
+        elsif( arg == :first || arg == :one)
+          return find_first(opts)
+        elsif( arg.respond_to?(:map) )
+          return find_with_ids(arg)
+        else
+          return find_by_id(arg)
+        end
+      end
+      
+      # Forwards the arguments and any block to the data store's find methods,
+      # and returns plain ol' objects as the result.
+      # 
+      # WARNING: This normally should not be used as its behavior is dependent
+      # upon the underlying data store, however sometimes there is no equivalent
+      # to the functionality offered by the data store given by the normal find
+      # method.
+      #
+      # The first argument must be one of:
+      # * :all or :many
+      # * :first or :one
+      def data_store_find(first_or_all, *args, &block)
+        if(first_or_all == :all || first_or_all == :many)
+          return data_store_find_all(*first_or_all, &block)
+        elsif( first_or_all == :first || first_or_all == :one)
+          return data_store_find_first(*first_or_all, &block)
+        else
+          raise ArgumentError, "#{__method__} expects the first argument to be one of :all, :many, :first, or :one."
+        end
+      end
+      
+    end
+  end
+end
+
+module Poro
+  class Context
+    include FindMethods
+  end
+end