yssk22-couch_resource 0.1.0 → 0.1.1

data/README.rdoc

@@ -1,7 +1,219 @@
-= couch_resource
+= What is CouchResource ?
 
-Description goes here.
+CouchResource is an ActiveRecord-style data mapper for CouchDB.
+You can develop model classes baed on the ActiveRecord way.
+
+== Install
+
+You can install from github,
+
+  gem source -a http://github.com
+  sudo gem install yssk22-couch_resource
+
+And official gem packages is also available in {WebJourney Project @RubyForge}[http://rubyforge.org/projects/webjourney/]
+
+== Supported CouchDB
+
+version 0.9.0-incubating (currently installed from svn trunk).
+
+
+== Examples of ActiveRecord-like Features
+- Automapping CouchDB database
+
+CouchReSource model classes are automatically mapped to databases.
+
+  class MyDocument < CouchResource::Base
+  end
+  #=> mapped to http://localhost:5984/my_documents
+
+You can set the specific database uri with <tt>set_database</tt> method.
+
+  class MyDocument < CouhcResource::Base
+    set_database http://user:password@host:port/database1
+  end
+  #=> mapped to http://user:password@host:port/database1
+
+- Typed attributes
+
+CouchDB is schemaless so that you can set data attributes directly in your model code.
+
+  class MyDocument < CouhcResource::Base
+    string :title
+    string :content
+    array  :tags, :is_a => String
+  end
+  doc = MyDocument.new
+  doc.title   = "My document"
+  doc.content = "My content..."
+
+And you can use nested data structure using CouchResource::SubResource.
+
+  class Comment < CouchResource::SubResource
+    string :content
+  end
+
+  class MyDocument < CouhcResource::Base
+    string :title
+    string :content
+    array  :tags,     :is_a => String
+    array  :comments, :is_a => Comment
+  end
+  doc = MyDocument.new
+  doc.comments = []
+  doc.comments << Comment.new(:content => "comment ... ")
+
+- Validation with typed attributes
+
+ActiveRecord-like validations are supported.
+
+  class MyDocument < CouhcResource::Base
+    string :title, :validates => [[:length_of, {:in => 1..64, :allow_nil => false}]]
+  end
+
+You can use validations indivisually out of attributes.
+
+  class MyDocument < CouhcResource::Base
+    string :title
+    validates_length_of :title, :in => 1..64, :allow_nil => false
+  end
+
+- Callbacks
+
+This feature is also the same as ActiveRecord.
+
+  class Person < CouchResource::Base
+    string :credit_card_id
+    def before_destroy # is called just before Person#destroy
+      CreditCard.find(credit_card_id).destroy
+    end
+  end
+
+- Direct manipulation
+
+  docId = "abcdefg"
+  MyDocument.find(docId)
+
+- Logging Support
+
+  CouchResource::Base.logger = Logger.new(STDOUT)
+  CouchResource::Base.logger = Log4r::Logger.new("Application Log")
+
+
+- Observers
+
+TBD, not implemented yet.
+
+- Inheritance hierarchies
+
+TBD, not implemented yet.
+
+- Transactions
+
+Not applicable for CouchDB.
+
+- Reflections on columns, associations, and aggregations
+
+Not applicable for CouchResource.
+
+== Examples of CouchDB Features
+
+- MapReduce finders
+
+  class MyDocument < CouchResource::Base
+    string :title
+    string :content
+    array  :tags, :is_a => String
+
+    # define finder method (find_by_{design_name}_{view_name}) using map/reduce scripts
+    view :tags, :count => {
+       :map    => include_js("path/to/map.js"),
+       :reduce => include_js("path/to/reduce.js")
+    }
+  end
+
+  MyDocument.find_tags_count("web")
+
+- Pagination in finders
+
+  class MyDocument < CouchResource::Base
+    string :title
+    string :content
+    array  :tags, :is_a => String
+  end
+
+  docs = MyDocument.find(:all, :count => 3)
+  # => first 3 documents in docs[:rows]
+  docs = MyDocument.find(docs[:next])
+  # => next 3 documents in docs[:rows] (*1)
+  docs = MyDocument.find(docs[:next])
+  # => next more 3 documents in docs[:rows]
+  docs = MyDocument.find(docs[:previous])
+  # => backward 3 documents in docs[:rows] (the same as *1)
+
+== Rails Support
+
+To enable rails utilities in CouchResource, you may need to add the following sentences in your config/environment.rb.
+
+  require 'couch_resource'
+  require 'couch_resource/rails'
+
+- CouchConfig
+
+You can define multipe CouchDB sites in config/couchdb.yml and use the configurations in your CouchResource models.
+
+  development:
+    user_profiles:
+      host: localhost
+      port: 5984
+      database: user_profiles_development
+    pages:
+      host: localhost
+      port: 5984
+      database: pages_development
+    feeds:
+      host: localhost
+      port: 5984
+      database: feeds_development
+
+  class Page < CouchResource::Base
+    set_database CouchConfig.database_uri_for(:db => :wj_pages)
+  end
+
+- CouchFixture
+
+Add followings in your test/test_helper.rb.
+
+  class Test::Unit::TestCase
+    #  ... (snip) ...
+
+    # Add more helper methods to be used by all tests here...
+    setup :setup_couch_fixture
+    def setup_couch_fixture
+      CouchFixture.load
+    end
+  end
+
+Then You can define fixtures in test/fixtures/couchdb/{model_name}.yml
+
+
+== Other information
+
+=== Application Practical Example
+
+WebJourney and it's blog component. Both of them are developed on http://github.com/yssk22/webjourney/tree/master
+
+=== Bugs/Requests/Quesions and ...
+
+Let's collabolate {our project site}[http://www.webjourney.org/project/projects/show/couch-resource]
+or please fork the github repo at http://github.com/yssk22/couch_resource.
+
+=== Altenertives
+
+There are some useful alternatves for CouchDB mapper in Ruby environment.
+
+CouchPotato : http://github.com/langalex/couch_potato/tree/master
+CouchRest   : http://github.com/jchris/couchrest/tree/master
 
 == Copyright
 
-Copyright (c) 2009 Yohei Sasaki. See LICENSE for details.
+Copyright (c) 2009 Yohei Sasaki. See MIT_LICENSE for details.

data/lib/couch_resource/base.rb

@@ -3,76 +3,53 @@ require 'json'
 require File.join(File.dirname(__FILE__), 'error')
 require File.join(File.dirname(__FILE__), 'connection')
 
+#
+# CouchResource is an ActiveRecord-style data mapper for CouchDB.
+#
 module CouchResource
   class Base
     cattr_accessor :logger, :instance_writer => false
+    @@logger = Logger.new("/dev/null")
     cattr_accessor :check_design_revision_every_time, :instance_writer => false
+    @@check_design_revision_every_time = true
 
     class << self
       # Get the URI of the CouchDB database to map for this class
       def database
-        if defined?(@database)
-          @database
-        elsif superclass != Object && superclass.database
-          superclass.database.dup.freeze
+        db = read_inheritable_attribute(:database)
+        if db
+          db
+        elsif superclass != CouchResource::Base && superclass.database
+          superclass.database
+        else
+          # convension
+          db = self.name.to_s.underscore.pluralize.gsub("/", "_")
+          URI.parse("http://localhost:5984/#{URI.decode(db)}")
         end
       end
 
       # Set the URI of the CouchDB database to map for this class
       def database=(uri)
-        @connection = nil
         if uri.nil?
-          @database = nil
+          write_inheritable_attribute(:database, nil)
         else
-          @database = uri.is_a?(URI) ? uri.dup : URI.parse(uri)
-          @user     = URI.decode(@database.user) if @database.user
-          @password = URI.decode(@database.password) if @database.password
+          db = uri.is_a?(URI) ? uri.dup : URI.parse(uri)
+          write_inheritable_attribute(:database, db)
+          db
         end
       end
       alias :set_database :database=
 
-      # Gets the user for REST HTTP authentication.
-      def user
-        # Not using superclass_delegating_reader. See +site+ for explanation
-        if defined?(@user)
-          @user
-        elsif superclass != Object && superclass.user
-          superclass.user.dup.freeze
-        end
-      end
-
-      # Sets the user for REST HTTP authentication.
-      def user=(user)
-        @connection = nil
-        @user = user
-      end
-
-      # Gets the password for REST HTTP authentication.
-      def password
-        # Not using superclass_delegating_reader. See +site+ for explanation
-        if defined?(@password)
-          @password
-        elsif superclass != Object && superclass.password
-          superclass.password.dup.freeze
-        end
-      end
-
-      # Sets the password for REST HTTP authentication.
-      def password=(password)
-        @connection = nil
-        @password = password
-      end
-
       # Sets the number of seconds after which requests to the REST API should time out.
       def timeout=(timeout)
-        @connection = nil
-        @timeout = timeout
+        write_inheritable_attribute(:timeout, timeout)
       end
 
       # Gets tthe number of seconds after which requests to the REST API should time out.
       def timeout
-        if defined?(@timeout)
-          @timeout
+        tm = read_inheritable_attribute(:timeout)
+        if tm
+          tm
         elsif superclass != Object && superclass.timeout
           superclass.timeout
         end
@@ -82,15 +59,16 @@ module CouchResource
       # The +refresh+ parameter toggles whether or not the connection is refreshed at every request
       # or not (defaults to <tt>false</tt>).
       def connection(reflesh = false)
-        if defined?(@connection) || superclass == Object
-          @connection = Connection.new(database) if reflesh || @connection.nil?
-          @connection.user = user if user
-          @connection.password = password if password
-          @connection.timeout = timeout if timeout
-          @connection
-        else
-          superclass.connection
+        conn = read_inheritable_attribute(:connection)
+        if reflesh || conn.nil?
+          db = database
+          conn          = Connection.new(db)
+          conn.user     = user     if db.user
+          conn.password = password if db.password
+          conn.timeout  = timeout  if timeout
+          write_inheritable_attribute(:connection, conn)
         end
+        conn
       end
 
       # Get the document path specified by the document id

data/lib/couch_resource/rails/couch_config.rb

@@ -0,0 +1,123 @@
+#
+# CouchDB Configuration Loader class
+#
+# = Configuration CouchDB Data Source in YAML
+#
+# Database configurations can be defined in Yaml format. WebJourney can support multiple CouchDB databases.
+# There are two types of configuration YAML files in WebJourney.
+#
+# - site level configuration, located in RAILS_ROOT/config/couchdb.yml
+# - component level configuration, located in RAILS_ROOT/components/{component_dir}/_config/couchdb.yml
+#
+# = YAML format
+#
+# The configuration format is almost the same as database.yml except that couchdb.yml requires <tt>db identifier</tt> for the multiple database support.
+# The format is as follows::
+#
+#   {environement}:
+#      {db_identifier}:
+#         host : {couchdb hostname}
+#         port : {couchdb port}
+#         database : {couchdb database name}
+#
+# For example, WjPage objects are persisted in one CouchDB database and WjUserProfile objects in another. In this case,
+# two databases are required so that the couchdb.yml (for <tt>development</tt> and <tt>production</tt>) is as follows::
+#
+#   development:
+#     wj_user_profiles:
+#         host: localhost
+#         port: 5984
+#         database: webjourney_dev_wj_profile
+#     wj_pages:
+#         host: localhost
+#         port: 5984
+#         database: webjourney_dev_wj_pages
+#
+#   production:
+#     wj_user_profiles:
+#         host: couch_site1
+#         port: 5984
+#         database: webjourney_dev_wj_profile
+#     wj_pages:
+#         host: couch_site2
+#         port: 5984
+#         database: webjourney_dev_wj_pages
+#
+# = Specify the database in CouchResource models
+#
+# CouchConfig class does only resolve a name to the couchdb database url by the <tt>database_uri_for</tt> method.
+# On the other hand, it is required to specify a database in a CouchResource model class (by <tt>set_database</tt> method).
+# So configruations loaded by CouchConfig and CouchResource classes are related as follows.
+#
+# At first, there are two couchdb.yml files. one is the site level configuration file.
+#
+#   # RAILS_ROOT/config/couchdb.yml
+#   development:
+#     abc:
+#         host: localhost
+#         port: 5984
+#         database: system_abc
+#
+# The other is the component level configuraiton.
+#
+#   # RAILS_ROOT/comopnents/my_component/config/couchdb.yml
+#   development:
+#     abc:
+#         host: 192.168.1.10
+#         port: 5984
+#         database: my_component_abc
+#
+# == Using site level database (often used by the WebJounrney framework)
+#
+#   class MyDocumentModel < CouchResource::Base
+#      # specify without the '/' separator.
+#      set_database CouchConfig.database_uri_for(:db => "abc")
+#
+#   end
+#
+# In this case, CouchConfig loads the configuration from RAILS_ROOT/config/couchdb.yml so that
+# MyDocumentModel objects are stored at <tt>#http://localhost:5984/system_abc</tt>.
+#
+# == Using component level database (often used by components)
+#
+#   class MyComponent::MyDocumentModel < CouchResource::Base
+#      # specify with the '/' separator.
+#      set_database CouchConfig.database_uri_for(:db => "my_component/abc")
+#
+#   end
+#
+# In this case, CouchConfig loads the configuration from RAILS_ROOT/component/my_component/_config/couchdb.yml so that
+# MyComponent::MyDocumentModel objects are stored at <tt>#http://192.168.1.10:5984/my_component_abc</tt>.
+#
+#
+class CouchConfig
+  # Get the all configuration hash
+  def self.get(component = nil)
+    if component.blank?
+      @@config ||= YAML.load(File.open(File.join(RAILS_ROOT, "config/couchdb.yml")))
+    else
+      @@component_config ||= {}
+      @@component_config[component] ||= YAML.load(File.open(File.join(RAILS_ROOT, "components", component, "_config/couchdb.yml")))
+    end
+  end
+
+  # Get the current configuration (specified to the database) by URI string
+  def self.database_uri_for(option = {})
+    env = (option[:env] || RAILS_ENV).to_s
+    db  = (option[:db]  || :system).to_s
+
+    component, dbname = db.split("/")
+
+    # swap if db does not have any '/' separators.
+    component, dbname = dbname, component    if dbname.blank?
+
+    config = self.get(component)[env.to_s][dbname]
+
+    # check each attributes
+    scheme   = config["scheme"]   || "http"
+    host     = config["host"]     || "localhost"
+    port     = config["port"]     || 5984
+    database = config["database"] || ("webjourney_#{RAILS_ENV}_#{dbname}")
+    "#{scheme}://#{host}:#{port}/#{database}"
+  end
+end

data/lib/couch_resource/rails/couch_fixture.rb

@@ -0,0 +1,52 @@
+#
+# = Experimental loader for CouchDB fixture data
+#
+# CouchDB fixture is an experimental module for Testing. Fixture data is stored in test/fixtures/couchdb/*.yml in YAML format.
+# Some useful features in ActiveRecord fixture such as transactional data cannot not supported in CouchDB.
+#
+class CouchFixture
+  #
+  # Load all fixtures in the <tt>basedir</tt>. If the fixture data is already stored in database, it'll be destroyed and newly created.
+  #
+  def self.load(basedir = File.join(RAILS_ROOT, "test/fixtures/couchdb/"))
+    # collecting database and yaml dataset pairs
+    datasets = {}
+    Dir.glob("#{basedir}/**/*.yml") do |f|
+      # resolve class
+      file = f.gsub(/^#{basedir}\//, '').gsub(/\.yml$/, '')
+      klass = file.singularize.camelize.constantize
+      # reset a database
+      uri = klass.database
+      datasets[uri] ||= []
+      content = YAML.load(ERB.new(File.read(f)).result)
+      datasets[uri] << [klass, content]
+    end
+
+    datasets.each do |uri, classes|
+      RAILS_DEFAULT_LOGGER.debug "CouchFixture : reset database (#{uri})."
+      Net::HTTP.start(uri.host, uri.port) { |http|
+        http.delete(uri.path)
+        http.put(uri.path, nil)
+      }
+      RAILS_DEFAULT_LOGGER.debug "CouchFixture : push the datasets (#{uri})."
+      classes.each do |klass, content|
+        klass.write_inheritable_attribute(:design_revision_checked, false)
+        # load yaml file
+        if content
+          content.each do |key, value|
+            value.symbolize_keys!
+            value[:_id] = key unless value[:_id]
+            # obj = klass.find(value[:_id]) rescue nil
+            # obj.destroy if obj
+            obj = klass.new(value)
+            begin
+              obj.save!
+            rescue CouchResource::PreconditionFailed
+              raise "Cannot load fixture with #{key} on #{uri} (duplicated key?)"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/couch_resource/rails.rb

@@ -0,0 +1,2 @@
+require File.join(File.dirname(__FILE__), 'rails/couch_config')
+require File.join(File.dirname(__FILE__), 'rails/couch_fixture')

data/lib/couch_resource/view.rb

@@ -3,13 +3,6 @@ require 'rubygems'
 require 'active_support'
 require 'json'
 
-#
-# == Synchronization of design documents
-#
-# Synchronization mechanism of design documents is controlled by <tt>check_design_revision_every_time</tt>.
-# The value is true, the finder methods of views always check the revision of the design document.
-# When false, the finder methods only check at first time.
-#
 module CouchResource
   module View
     def self.included(base)

data/test/test_base.rb

@@ -39,6 +39,14 @@ class MagicAttributesTest < CouchResource::Base
   datetime :updated_on
 end
 
+class DatabaseNameTest < CouchResource::Base
+end
+
+module Nested
+  class DatabaseNameTest < CouchResource::Base
+  end
+end
+
 class TestBase < Test::Unit::TestCase
   def setup
     res = SimpleDocument.connection.put(SimpleDocument.database.path)
@@ -365,20 +373,25 @@ class TestBase < Test::Unit::TestCase
     assert_equal 0, docs[:rows].length
   end
 
-  private
-  def register_simple_documents
-    0.upto(9) do |i|
-      doc = SimpleDocument.new(:title => "title_#{i}", :content => "content_#{i}")
-      doc.save
-    end
+  def test_database_name
+    assert_equal "http://localhost:5984/database_name_tests",        DatabaseNameTest.database.to_s
+    assert_equal "http://localhost:5984/nested_database_name_tests", Nested::DatabaseNameTest.database.to_s
   end
 
   def test_magic_attributes
-    obj = MagicAttributesTest
+    obj = MagicAttributesTest.new
     obj.save
     assert_not_nil obj.created_at
     assert_not_nil obj.created_on
     assert_not_nil obj.updated_at
     assert_not_nil obj.updated_on
   end
+
+  private
+  def register_simple_documents
+    0.upto(9) do |i|
+      doc = SimpleDocument.new(:title => "title_#{i}", :content => "content_#{i}")
+      doc.save
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: yssk22-couch_resource
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Yohei Sasaki
@@ -9,10 +9,29 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-10 00:00:00 -07:00
+date: 2009-03-22 00:00:00 -07:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 1.1.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: active_support
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 2.2.2
+    version: 
 description: 
 email: yssk22@gmail.com
 executables: []
@@ -28,6 +47,9 @@ files:
 - lib/couch_resource/callbacks.rb
 - lib/couch_resource/connection.rb
 - lib/couch_resource/error.rb
+- lib/couch_resource/rails/couch_config.rb
+- lib/couch_resource/rails/couch_fixture.rb
+- lib/couch_resource/rails.rb
 - lib/couch_resource/struct.rb
 - lib/couch_resource/validations.rb
 - lib/couch_resource/view.rb