leanback 0.2.2 → 0.2.3

data/Changelog.rdoc

@@ -1,3 +1,18 @@
+=Leanback 0.2.3
+July 19, 2011:-
+* Added better error handling all database operations now raise a CouchdbException when something goes wrong. It's now easy to track exceptions.
+   begin 	
+   Couchdb.create 'contacts'
+  rescue => e
+   puts "Error message: " + e.to_s
+   puts "Error value: " + e.error
+  end 
+
+ # => Error message: CouchDB: Error - file_exists. Reason - The database could not be created, the file already exists.
+      Error value: file_exists
+
+See README for details
+
 =Leanback 0.2.2
 July 13, 2011:-
 * No need to call add_finder() method directly anymore. find_by() now adds a finder index to the database if one doesn't already exist.

data/README.rdoc

@@ -98,10 +98,9 @@ To find all female contacts
 ====How it works
 The method
  Couchdb.find_by(:database => 'contacts', :email => 'nancy@mail.com')  
-will query the 'contacts' database for a design_document called _design/email_finder and a view called find_by_email with key = "nancy@mail.com".
-It sends a  
+sends a
  GET http://127.0.0.1:5984/contacts/_design/email_finder/_view/find_by_email?key="nancy@mail.com"
-This returns all contacts with email = 'nancy@mail.com'. Leanback will parse the native JSON results to return only the data values. If the design_document and view doesn't exist Leanback will create it in the database. See the source below;
+This returns all contacts with email = 'nancy@mail.com'. Leanback will parse the native JSON results to return only the data values. If the design_document (_design/email_finder) and the view (find_by_email) doesn't exist, Leanback will create it in the database. See the source for the generated design_document;
  {
    "_id": "_design/email_finder",
    "_rev": "7-da7f3c0bf183f4a36a82013bd0ea6537",
@@ -183,20 +182,106 @@ To query the view
          {"Firstname"=>"john", "Lastname"=>"smith", "Email"=>"john@mail.com"}]
 
 
-===Error handling
-Attempting to create a database that already exists
- Couchdb.create 'contacts'
- # => {"error"=>"file_exists", "reason"=>"The database could not be created, the file already exists."} 
+===Create View on the fly if it doesn't already exist 
+Let's say we want to query a view and create it on the fly if it doesn't already exist, and still return the values. In this example we will query a view called get_emails view (which returns emails of all contacts), if this view doesn't already exist it will be added to the database.
+
+ def get_emails
+  begin  
+   docs = Couchdb.find(:database => "contacts", :design_doc => 'my_views', :view => 'get_emails') 
+  rescue CouchdbException => e
+    doc = { :database => 'contacts', :design_doc => 'my_views', :json_doc => '/path/to/my_views.json' }
+    Couchdb.create_design doc
+    docs = Couchdb.find(:database => "contacts", :design_doc => 'my_views', :view => 'get_emails')      
+  end
+  return docs
+ end
+
+ email_list = get_emails()
+ puts email_list.inspect
+ # => [{"Name"=>"Nancy", "Email"=>"nancy@mail.com"}, {"Name"=>"John", "Email"=>"john@mail.com"}]
+
+In get_emails(), 
+ docs = Couchdb.find(:database => "contacts", :design_doc => 'my_views', :view => 'get_emails') 
+sends a request to the design_document (my_views) and view (get_emails). If this view is found in the database, it returns an Array with the name and email of all contacts:
+  [{"Name"=>"Nancy", "Email"=>"nancy@mail.com"}, {"Name"=>"John", "Email"=>"john@mail.com"}]
+if the view doesn't exist it raises a CouchdbException. It catches this exception 
+  rescue CouchdbException => e
+and then it creates the design_document (my_views) and view (get_emails), since they don't already exist
+  doc = { :database => 'contacts', :design_doc => 'my_views', :json_doc => '/path/to/my_views.json' }
+  Couchdb.create_design doc
+next it sends a request for the view again. 
+   docs = Couchdb.find(:database => "contacts", :design_doc => 'my_views', :view => 'get_emails')
+Then it returns the email list
+   return docs
+So the first time the get_emails() method is called, the view will be created on the fly and added to the database.
+
+Source for the get_emails view:
+ #my_views.json
+ {
+  "language" : "javascript",
+  "views" :{
+    "get_emails" : {
+      "map" : "function(doc){
+         if(doc.firstname && doc.email)
+           emit(doc.id,{Name: doc.firstname, Email: doc.email});
+        }"
+    }
+  }
+ }
+
 
-Attempting to delete a database that no longer exists
- Couchdb.delete 'more_books'
- # => {"error"=>"not_found", "reason"=>"missing"} 
+===Error handling
+Every database operation raises a CouchdbException when things go wrong.
 
-Most methods return a hash value unless otherwise specified. When a database transaction goes through successfully most methods will return a hash {"ok" => true ...} and when something goes wrong it returns a hash {"error" => ...}
+Attempting to create a database that already exists
+  begin 	
+   Couchdb.create 'contacts'
+  rescue CouchdbException => e
+   puts "Error message: " + e.to_s
+   puts "Error value: " + e.error
+  end 
+
+ # => Error message: CouchDB: Error - file_exists. Reason - The database could not be created, the file already exists.
+      Error value: file_exists
+
+
+Attempting to delete a database that doesn't exist
+  begin
+   Couchdb.delete 'buildings'
+  rescue CouchdbException => e
+   puts "Error message: " + e.to_s
+   puts "Error value: " + e.error
+  end
+
+ # => Error message: CouchDB: Error - not_found. Reason - missing
+      Error value: not_found
+
+Attempting to query a permanent view that doesn't exist
+  begin
+   view = { :database => "contacts", :design_doc => 'more_views', :view => 'get_user_email'}
+   Couchdb.find view 
+  rescue CouchdbException => e
+   puts "Error message: " + e.to_s
+   puts "Error value: " + e.error
+  end 
+
+ # => Error message: CouchDB: Error - not_found. Reason - missing_named_view
+      Error value: not_found
+
+You can always check the information passed to the Exception. See example below:
+  begin
+   view = { :database => "contacts", :design_doc => 'more_views', :view => 'get_user_email'}
+   Couchdb.find view 
+  rescue CouchdbException => e
+    if e.error == "not_found"
+     doc = { :database => 'contacts', :design_doc => 'more_views', :json_doc => '/path/to/user_email.json' }
+     Couchdb.create_design doc
+     docs = Couchdb.find(:database => "contacts", :design_doc => 'more_views', :view => 'get_user_email')      
+    end
+  end 
 
-You can always check this value 
- hash = Couchdb.delete 'schools'
- puts hash.inspect
+In the code above, the rescue block will create and request the permanent view if it's not found by the initial request outside the block. e.error is the value of the error returned by CouchDB.
+  
 
 ===Bind Address
 Leanback uses the default Couchdb bind address http://127.0.0.1:5984. To use a different bind address;

data/VERSION

@@ -1 +1 @@
-0.2.2
+0.2.3

data/leanback.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{leanback}
-  s.version = "0.2.2"
+  s.version = "0.2.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Obi Akubue"]
-  s.date = %q{2011-07-13}
+  s.date = %q{2011-07-19}
   s.description = %q{lightweight Ruby interface to CouchDB}
   s.email = %q{obioraakubue@yahoo.com}
   s.extra_rdoc_files = [

data/lib/leanback.rb

@@ -2,6 +2,14 @@ require 'rest_client'
 require 'yajl'
 require 'erb'
 
+class CouchdbException < RuntimeError
+   attr :error
+   def initialize(error)
+    @error = error.values[0]
+  end
+end
+
+
 module Document
   
   #create a document 
@@ -16,6 +24,7 @@ module Document
          hash = Yajl::Parser.parse(response.to_str)
        rescue => e
          hash = Yajl::Parser.parse(e.response.to_s)
+         raise CouchdbException.new(hash), "CouchDB: Error - " + hash.values[0] + ". Reason - "  + hash.values[1]
        end
   end
 
@@ -31,6 +40,7 @@ module Document
          hash = Yajl::Parser.parse(response.to_str)
        rescue => e
          hash = Yajl::Parser.parse(e.response.to_s)
+         raise CouchdbException.new(hash), "CouchDB: Error - " + hash.values[0] + ". Reason - "  + hash.values[1]
       end
   end
 
@@ -45,6 +55,7 @@ module Document
       hash = Yajl::Parser.parse(response.to_str)
     rescue => e
      hash = Yajl::Parser.parse(e.response.to_s)
+     raise CouchdbException.new(hash), "CouchDB: Error - " + hash.values[0] + ". Reason - "  + hash.values[1]
     end
  end
 
@@ -69,6 +80,7 @@ module Couchdb
          hash = Yajl::Parser.parse(response.to_str)
        rescue => e
          hash = Yajl::Parser.parse(e.response.to_s)
+         raise CouchdbException.new(hash), "CouchDB: Error - " + hash.values[0] + ". Reason - "  + hash.values[1]
        end
   end
 
@@ -80,6 +92,7 @@ module Couchdb
          hash = Yajl::Parser.parse(response.to_str)
        rescue => e
          hash = Yajl::Parser.parse(e.response.to_s)
+         raise CouchdbException.new(hash), "CouchDB: Error - " + hash.values[0] + ". Reason - "  + hash.values[1]
        end 
  end
 
@@ -104,6 +117,7 @@ def self.view(doc)
    hash = Yajl::Parser.parse(response.to_str)
   rescue => e
    hash = Yajl::Parser.parse(e.response.to_s)
+   raise CouchdbException.new(hash), "CouchDB: Error - " + hash.values[0] + ". Reason - "  + hash.values[1]
  end 
 end
 
@@ -130,6 +144,7 @@ def self.find(doc,key=nil)
    rescue => e
     #puts e.inspect
     hash = Yajl::Parser.parse(e.response.to_s)
+    raise CouchdbException.new(hash), "CouchDB: Error - " + hash.values[0] + ". Reason - "  + hash.values[1]
    end
 end
 
@@ -154,6 +169,7 @@ def self.create_design(doc)
     hash = Yajl::Parser.parse(response.to_str)
   rescue => e
     hash = Yajl::Parser.parse(e.response.to_s)
+    raise CouchdbException.new(hash), "CouchDB: Error - " + hash.values[0] + ". Reason - "  + hash.values[1]
   end
 end
 
@@ -181,6 +197,7 @@ def self.add_finder(options)
   response = RestClient.put 'http://' + @address + ':' + @port + '/' + db_name + '/_design/' + design_doc_name, view, {:content_type => :json, :accept => :json}
  rescue => e
     hash = Yajl::Parser.parse(e.response.to_s)
+    raise CouchdbException.new(hash), "CouchDB: Error - " + hash.values[0] + ". Reason - "  + hash.values[1]
  end
 end
 
@@ -222,6 +239,7 @@ def self.docs_from(database_name)
         return rows
   rescue => e
      hash = Yajl::Parser.parse(e.response.to_s)
+     raise CouchdbException.new(hash), "CouchDB: Error - " + hash.values[0] + ". Reason - "  + hash.values[1]
   end  
 end
 

data/test/test_leanback.rb

@@ -13,47 +13,90 @@ class TestLeanback < Test::Unit::TestCase
 	#puts hash.inspect
   end
 
- should "create a database if it doesn't already exist" do
-	hash = Couchdb.create 'contacts'
-	#puts hash.inspect
+ should "create a database if it doesn't already exist, and handle exception if it exists" do
+       begin 	
+        hash = Couchdb.create 'contacts'
+        #puts hash.inspect
+       rescue => e
+          #puts "Error message: " + e.to_s
+          #puts "Error value: " + e.error
+       end 
   end
 
-  should "add a finder method to the database" do
+  should "delete a database that doesn't exist and handle the exception" do 
+      begin
+       hash = Couchdb.delete 'buildings'
+       #puts hash.inspect
+      rescue CouchdbException => e
+       #puts "Error message: " + e.to_s
+       #puts "Error value: " + e.error
+      end
+   end
+
+  should "add a finder method to the database or handle exception if a finder already exists" do
+      begin
        hash = Couchdb.add_finder(:database => 'contacts', :key => 'email') 
        #puts hash.inspect
+       rescue CouchdbException => e
+        #puts e.to_s
+        #puts e.error
+      end
   end
 
  should "find items by key" do
      docs = Couchdb.find_by( :database => 'contacts', :email => 'nancy@mail.com')
      #docs = Couchdb.find_by( :database => 'contacts', :lastname => 'Smith') 
      #docs = Couchdb.find_by( :database => 'contacts', :gender => 'female') 
-     puts docs.inspect
+     #puts docs.inspect
  end
 
-  should "view document doc" do
-        
+  should "view document doc or handle exception" do
+     
         doc = {:database => 'monitors', :doc_id => '3-d71c8ee21d6753896f2d08f57a985e94'}
+       begin 
         hash = Couchdb.view doc
         #puts hash.inspect
+       rescue CouchdbException => e
+        #puts e.inspect
+        #puts e.error
+       end
   end
 
+  should "Query a permanent view that doesn't exist and handle exception" do
+    begin
+     #puts 'viewing design doc...'
+     view = { :database => "contacts", :design_doc => 'more_views', :view => 'get_user_email'}
+     hash = Couchdb.find view 
+     #puts hash.inspect
+    rescue CouchdbException => e
+      puts "Error message: " + e.to_s
+      puts "Error value: " + e.error
+    end  
+  end
+
+
   should "Query a permanent view" do
     view = { :database => "contacts", :design_doc => 'more_views', :view => 'get_email'}
-    puts 'viewing design doc...'
+    #puts 'viewing design doc...'
     hash = Couchdb.find view 
     #puts hash.inspect
   end
 
-  should "Create a design doc/permanent view" do
+  should "Create a design doc/permanent view or handle exception" do
     doc = { :database => 'contacts', :design_doc => 'more_views', :json_doc => '/home/obi/bin/leanback/test/my_views.json' }
+    begin 
      hash = Couchdb.create_design doc
      #puts hash.inspect
+     rescue CouchdbException => e
+        #puts e.to_s
+        #puts e.error
+    end  
   end
 
   should "return a display a list of all databases" do
       databases = Couchdb.all
        databases.each do |db_name| 
-           #puts db_name
+          # puts db_name
         end
    end
 
@@ -62,29 +105,55 @@ class TestLeanback < Test::Unit::TestCase
        #puts hash.inspect
    end
 
-  should "create a document" do 
+  should "create a document and handle exception if one occurs" do 
+       begin
         data = {:firstname => 'Nancy', :lastname =>'Lee', :phone => '347-808-3734',:email =>'nancy@mail.com',:gender => 'female'}
          doc = {:database => 'contacts', :doc_id => 'Nancy', :data => data}
          hash = Document.create doc
          #puts hash.inspect    
+       rescue CouchdbException => e
+        #puts e.to_s
+        #puts e.error
+      end  
   end
 
- should "edit a document" do 
+ should "edit a document - handle exceptions" do 
+        begin
          data = {:firstname => 'john', :lastname =>'smith', :email => 'john@mail.com',:gender=>'male', :_rev=>'2-e813a0e902e3ac114400ff3959a2adde'}
          doc = {:database => 'contacts', :doc_id => 'john', :data => data}
          hash = Document.edit doc
-         #puts hash.inspect    
+         #puts hash.inspect 
+        rescue CouchdbException => e   
+          #puts e.to_s
+          #puts e.error
+        end
   end
 
-   should "delete a document" do 
+   should "delete a document - handle exceptions" do 
+       begin
          doc = {:database => 'contacts', :doc_id => 'john', :rev => '3-be02e80490f8e9e610d9a9e33d752316'}
          hash = Document.delete doc
          #puts hash.inspect
+      rescue CouchdbException => e   
+         #puts e.to_s
+         #puts e.error
+      end
    end
 
+   should "display all documents in the database that doesn't exist and handle exception" do 
+    begin
+      docs = Couchdb.docs_from 'buildings'
+    rescue CouchdbException => e
+        #puts e.to_s
+        #puts e.error
+    end  
+   end
+  
+
+
    should "display all documents in the database" do 
       docs = Couchdb.docs_from 'monitors'
-       puts 'docs = Couchdb.docs_from monitors'
+       #puts 'docs = Couchdb.docs_from monitors'
       docs.each do |d| 
          # puts "_rev: " + d["_rev"]
           #puts "_id: " + d["_id"]    
@@ -98,10 +167,24 @@ class TestLeanback < Test::Unit::TestCase
        end
    end
 
+   should "create view on the fly if it doesn't already exist" do
+     begin  
+      docs = Couchdb.find(:database => "contacts", :design_doc => 'x_my_views', :view => 'get_emails') 
+     rescue CouchdbException => e
+       #puts e.to_s
+       doc = { :database => 'contacts', :design_doc => 'x_my_views', :json_doc => '/home/obi/bin/my_views.json' }
+       #doc = { :database => 'contacts', :design_doc => 'my_views', :json_doc => '/path/to/my_views.json' }
+       Couchdb.create_design doc
+       docs = Couchdb.find(:database => "contacts", :design_doc => 'my_views', :view => 'get_emails')      
+     end
+        #puts docs.inspect
+   end
+
+
   should " switch to default bind address" do
      Couchdb.address = nil
      Couchdb.port = nil
-     Couchdb.all
+     #Couchdb.all
   end
   
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 2
-  version: 0.2.2
+  - 3
+  version: 0.2.3
 platform: ruby
 authors: 
 - Obi Akubue
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-13 00:00:00 -04:00
+date: 2011-07-19 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -136,7 +136,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -928313619
+      hash: 143649905
       segments: 
       - 0
       version: "0"