riakrest 0.1.0 → 0.1.2

data/History.txt

@@ -1,3 +1,14 @@
+=== 0.1.2 2009-11-29
+  - Add wide open schemas.
+  - Add wild card schema arrays.
+
+=== 0.1.1 2009-11-28
+  - Fixed several 1.8.7 issues.
+  - Added helper for examples and put server URI setting in helpers.
+  - Removed POV terminology. Riak doesn't support per-request masks (yet?).
+  - Added some gem dependency declarations.
+  - Minor refactoring.
+
 === 0.1.0 2009-11-16
   - Renamed data/JiakDataHash to core/JiakDataFields and reworked.
   - Move JiakDataHash functionality into JiakData as default implementation

data/README.rdoc

@@ -62,6 +62,6 @@ sudo gem install riakrest
 
 == LICENSE:
 
-Copyright (c) 2009 Paul Rogers, DingoSky. See LICENCE for details.
+Copyright (c) 2009 Paul Rogers, DingoSky. See LICENSE for details.
 
 ===Go forth and Riak!

data/Rakefile

@@ -4,25 +4,29 @@ require 'rake'
 begin
   require 'jeweler'
 rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+  puts "Jeweler (or a dependency) not available."
+  puts "  Install with: sudo gem install jeweler"
 end
 
 Jeweler::Tasks.new do |gem|
   gem.name = "riakrest"
   gem.summary = %Q{RiakRest provides structured, RESTful interaction with a Riak document store.}
-  gem.description = <<-EOH
+  gem.description = <<-EOS
     RiakRest provides structured, RESTful interaction with
     the HTTP/JSON interface of a Riak[http://riak.basho.com] document data
     store. RiakRest provides two levels of interaction: Core Client and
     Resource. Core Client works at the Jiak level and exposes Jiak
     internals. JiakResource is an abstraction built on top of the Core Client
     that gives a true RESTful feel.
-  EOH
+  EOS
   gem.authors = ["Paul Rogers"]
-  gem.email = "paul@dingosky.com"
+  gem.email = "riak@dingosky.com"
   gem.homepage = "http://github.com/wcpr/riakrest"
   gem.add_dependency('rest-client', '>= 1.0.0')
+  gem.add_dependency('json', '>= 1.1.9')
   gem.add_development_dependency "rest-client", ">= 1.0.0"
+  gem.add_development_dependency "json", ">= 1.1.9"
+  gem.add_development_dependency "jeweler", ">= 1.4.0"
   gem.add_development_dependency "rspec", ">= 1.2.9"
 end
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.2

data/examples/auto_update_data.rb

@@ -1,9 +1,8 @@
-require 'riakrest'
-include RiakRest
+require File.dirname(__FILE__) + '/example_helper.rb'
 
 class People
   include JiakResource
-  server         'http://localhost:8002/jiak'
+  server         SERVER_URI
   jattr_accessor :name, :age
   keygen { name }
   auto_manage

data/examples/auto_update_links.rb

@@ -1,9 +1,8 @@
-require 'riakrest'
-include RiakRest
+require File.dirname(__FILE__) + '/example_helper.rb'
 
 class People
   include JiakResource
-  server         'http://localhost:8002/jiak'
+  server         SERVER_URI
   jattr_accessor :name, :age
   keygen { name.downcase }
   auto_post

data/examples/basic_client.rb

@@ -1,12 +1,11 @@
-require 'riakrest'
-include RiakRest
+require File.dirname(__FILE__) + '/example_helper.rb'
 
 class PeopleData
   include JiakData
   jattr_accessor :name, :age
 end
 
-client = JiakClient.new("http://localhost:8002/jiak")
+client = JiakClient.new(SERVER_URI)
 bucket = JiakBucket.new('people',PeopleData)
 client.set_schema(bucket)
 

data/examples/basic_resource.rb

@@ -1,9 +1,8 @@
-require 'riakrest'
-include RiakRest
+require File.dirname(__FILE__) + '/example_helper.rb'
 
 class People
   include JiakResource
-  server 'http://localhost:8002/jiak'
+  server SERVER_URI
   jattr_accessor :name, :age
   keygen {name.downcase}
   auto_manage

data/examples/example_helper.rb

@@ -0,0 +1,7 @@
+require 'rubygems' unless ENV['NO_RUBYGEMS']
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'riakrest'
+include RiakRest
+
+SERVER_URI = 'http://localhost:8002/jiak'

data/examples/linked_resources.rb

@@ -1,9 +1,8 @@
-require 'riakrest'
-include RiakRest
+require File.dirname(__FILE__) + '/example_helper.rb'
 
 class Parents
   include JiakResource
-  server         'http://localhost:8002/jiak'
+  server         SERVER_URI
   jattr_accessor :name
   keygen { name }
 end

data/lib/riakrest/core/jiak_bucket.rb

@@ -102,8 +102,8 @@ module RiakRest
     private :transform_name
 
     def check_data_class(data_class)
-      unless data_class.include?(JiakData)
-        raise JiakBucketException, "Data class must be type of JiakData."
+      unless !data_class.nil? && data_class.include?(JiakData)
+        raise JiakBucketException, "Data class must include JiakData."
       end
       data_class
     end

data/lib/riakrest/core/jiak_client.rb

@@ -46,15 +46,28 @@ module RiakRest
 
     # :stopdoc:
     APP_JSON       = 'application/json'
+    APP_JSON.freeze
+
     RETURN_BODY    = 'returnbody'
+    RETURN_BODY.freeze
     READS          = 'r'
+    READS.freeze
     WRITES         = 'w'
+    WRITES.freeze
     DURABLE_WRITES = 'dw'
-    RESPONSE_WAITS = 'rw'
+    DURABLE_WRITES.freeze
+    DELETES        = 'rw'
+    DELETES.freeze
+
+    VALID_PARAMS   = [:reads,:writes,:durable_writes,:deletes]
+    VALID_PARAMS.freeze
+    VALID_OPTS     = Array.new(VALID_PARAMS) << :proxy
+    VALID_OPTS.freeze
+
     KEYS           = 'keys'
+    KEYS.freeze
     SCHEMA         = 'schema'
-    VALID_PARAMS   = [:reads,:writes,:durable_writes,:waits]
-    VALID_OPTS     = VALID_PARAMS << :proxy
+    SCHEMA.freeze
     # :startdoc:
 
     # :call-seq:
@@ -64,17 +77,22 @@ module RiakRest
     # the specified URI. Go through a proxy if proxy option specified.
     #
     # =====Valid options
-    # <code>:reads</code>:: Respond after this many Riak nodes reply to a read request.
-    # <code>:writes</code>:: Respond after this many Riak nodes reply to a write request.
-    # <code>:durable_writes</code>:: Ensure this many Riak nodes perform a durable write.
-    # <code>:waits</code>:: Respond after this many Riak nodes reply to a delete request.
+    # <code>:reads</code>:: Minimum number of responding nodes for successful reads.
+    # <code>:writes</code>:: Minimum number of responding nodes for successful writes. Writes can be buffered on the server nodes for performance.
+    # <code>:durable_writes</code>:: Minimum number of resonding nodes that must perform a durable write to the persistence layer.
+    # <code>:deletes</code>:: Minimum number of responding nodes for successful delete.
     # <code>:proxy</code>:: Proxy server URI
     #
-    # Any of the request parameters <code>writes, durable_writes, reads,</code>
-    # and <code>waits</code> can be set on a per request basis. If the
-    # parameters are not specified, the value set for JiakClient is used. If
-    # neither of those scopes include the parameter, the value set on the Riak
-    # cluster is used.
+    # The configuration of a Riak cluster includes server setting for the
+    # <code>writes, durable_writes, reads,</code> and <code>deletes</code>
+    # parameters. None of these request parameter are required by RiakRest, and
+    # their use within RiakRest is to override the Riak cluster settings,
+    # either at the JiakClient level or the individual request level.
+    #
+    # Settings passed to individual <code>get, store,</code> and
+    # <code>delete</code> requests take precendence over the setting maintained
+    # by a JiakClient. Any request parameter not set in JiakClient or on an
+    # individual request will default to the values set in the Riak cluster.
     # 
     def initialize(uri, opts={})
       check_opts(opts,VALID_OPTS,JiakClientException)
@@ -145,25 +163,38 @@ module RiakRest
     # :call-seq:
     #   params  ->  hash
     #
-    # Copy of the current parameters hash.
+    # Copy of the current request parameters hash.
     def params
       @params.dup
     end
 
     # :call-seq:
-    #   set_schema(bucket)  -> nil
+    #   set_schema(bucket,schema=nil)  -> nil
     #
-    # Set the Jiak server schema for a bucket. The schema is determined by the
-    # JiakData associated with the JiakBucket.
+    # Set the Jiak server schema for a bucket. If a JaikSchema is given, bucket
+    # must be a string; otherwise, if the schema is not given bucket must be a
+    # JiakBucket and the associated JiakData schema is used.
     #
     # Raise JiakClientException if the bucket is not a JiakBucket.
-    #
-    def set_schema(bucket)
-      unless bucket.is_a?(JiakBucket)
-        raise JiakClientException, "Bucket must be a JiakBucket."
+    # Raise JiakClientException if the schema is not a JiakSchema.
+    def set_schema(bucket,schema=nil)
+      if(schema.nil?)
+        unless bucket.is_a?(JiakBucket)
+          raise JiakClientException, "Bucket must be a JiakBucket."
+        end
+        bucket_name = bucket.name
+        schema = bucket.schema
+      else
+        unless(bucket.is_a?(String))
+          raise JiakClientException, "Bucket must be a string name."
+        end
+        unless(schema.is_a?(JiakSchema))
+          raise JiakClientException, "Schema must be a JiakSchema."
+        end
+        bucket_name = bucket
       end
-      resp = RestClient.put(jiak_uri(bucket),
-                            bucket.schema.to_jiak.to_json,
+      resp = RestClient.put(jiak_uri(bucket_name),
+                            schema.to_jiak.to_json,
                             :content_type => APP_JSON,
                             :accept => APP_JSON)
     end
@@ -171,9 +202,7 @@ module RiakRest
     # :call-seq:
     #   schema(bucket)  -> JiakSchema
     #
-    # Get the data schema for a bucket on a Jiak server. This involves a call
-    # to the Jiak server. See JiakBucket#schema for a way to get this
-    # information without server access.
+    # Get the data schema for a bucket on a Jiak server.
     def schema(bucket)
       JiakSchema.jiak_create(bucket_info(bucket,SCHEMA))
     end
@@ -204,6 +233,11 @@ module RiakRest
     # <code>:durable_writes</code><br/>
     # <code>:reads</code><br/>
     #
+    # See JiakClient#new for description of <code>writes,
+    # durable_writes,</code> and <code>reades</code> parameters. The
+    # <code>reads</code> parameter only takes effect if the JiakObject is being
+    # returned (which involves reading the writes).
+    #
     # Raise JiakClientException if object not a JiakObject or illegal options
     # are passed.<br/>
     # Raise JiakResourceException on RESTful HTTP errors.
@@ -214,12 +248,14 @@ module RiakRest
       req_params = {
         WRITES => opts[:writes] || @params[:writes], 
         DURABLE_WRITES => opts[:durable_writes] || @params[:durable_writes],
-        READS => opts[:reads] || @params[:reads]
       }
-      req_params[RETURN_BODY] = (opts[:return] == :object)
+      if(opts[:return] == :object)
+        req_params[RETURN_BODY] = true
+        req_params[READS] = opts[:reads] || @params[:reads]
+      end
 
       begin
-        uri = jiak_uri(jobj.bucket,jobj.key,req_params)
+        uri = jiak_uri(jobj.bucket,jobj.key) << jiak_qstring(req_params)
         payload = jobj.to_jiak.to_json
         headers = { 
           :content_type => APP_JSON,
@@ -270,7 +306,7 @@ module RiakRest
     # String.
     #
     # =====Valid options
-    # <code>:reads</code>
+    # <code>:reads</code> --- See JiakClient#new
     #
     # Raise JiakClientException if bucket not a JiakBucket.<br/>
     # Raise JiakResourceNotFound if resource not found on Jiak server.<br/>
@@ -281,10 +317,12 @@ module RiakRest
         raise JiakClientException, "Bucket must be a JiakBucket."
       end
       check_opts(opts,[:reads],JiakClientException)
-      req_params = {READS => opts[:reads] || @params[:reads]}
+      req_params = {
+        READS => opts[:reads] || @params[:reads]
+      }
 
       begin
-        uri = jiak_uri(bucket,key,req_params)
+        uri = jiak_uri(bucket,key) << jiak_qstring(req_params)
         resp = RestClient.get(uri, :accept => APP_JSON)
         JiakObject.jiak_create(JSON.parse(resp),bucket.data_class)
       rescue RestClient::ResourceNotFound => err
@@ -302,16 +340,16 @@ module RiakRest
     # Delete the JiakObject stored at the bucket/key.
     #
     # =====Valid options
-    # <code>:waits</code>
+    # <code>:deletes</code> --- See JiakClient#new
     #
     # Raise JiakResourceException on RESTful HTTP errors.
     #
     def delete(bucket,key,opts={})
-      check_opts(opts,[:waits],JiakClientException)
+      check_opts(opts,[:deletes],JiakClientException)
       begin
-        req_params = {RESPONSE_WAITS => opts[:waits] || @params[:waits]}
-        uri = jiak_uri(bucket,key,req_params)
-        RestClient.delete(uri, :accept => APP_JSON)
+        req_params = {DELETES => opts[:deletes] || @params[:deletes]}
+        uri = jiak_uri(bucket,key) << jiak_qstring(req_params)
+        RestClient.delete(uri,:accept => APP_JSON)
         true
       rescue RestClient::ExceptionWithResponse => err
         fail_with_response("delete", err)
@@ -320,6 +358,22 @@ module RiakRest
       end
     end
 
+    # :call-seq:
+    #   exist?(bucket,key)  -> true or false
+    #
+    # Return true if a resource exists at bucket/key
+    def exist?(bucket,key)
+      begin
+        uri = jiak_uri(bucket,key)
+        RestClient.head(uri,:accept => APP_JSON)
+        true
+      rescue RestClient::ResourceNotFound
+        false
+      rescue RestClient::Exception => err
+        fail_with_message("delete", err)
+      end
+    end
+
     # :call-seq:
     #   walk(bucket,key,query,data_class)  -> array
     #
@@ -334,7 +388,7 @@ module RiakRest
         start = jiak_uri(bucket,key)
         case query
         when QueryLink
-          uri = start+'/'+query.for_uri
+          uri = "#{start}/#{query.for_uri}"
         when Array
           uri = query.inject(start) {|build,link| build+'/'+link.for_uri}
         else
@@ -342,7 +396,6 @@ module RiakRest
             'a QueryLink or an Array of QueryLink objects'
         end
         resp = RestClient.get(uri, :accept => APP_JSON)
-        # JSON.parse(resp)['results'][0]
         JSON.parse(resp)['results'][0].map do |jiak|
           JiakObject.jiak_create(jiak,data_class)
         end
@@ -356,7 +409,7 @@ module RiakRest
     # :call-seq:
     #    client == other -> true or false
     #
-    # Equality -- JiakClients are equal if they have the same URI
+    # Equality --- JiakClients are equal if they have the same URI
     def ==(other)
       (@server == other.server) rescue false
     end
@@ -376,20 +429,30 @@ module RiakRest
     end
 
     # Build the URI for accessing the Jiak server.
-    def jiak_uri(bucket,key="",params={})
-      uri = "#{@server}#{URI.encode(bucket.name)}"
-      uri += "/#{URI.encode(key)}" unless key.empty?
-      qstring = params.reject {|k,v| v.nil?}.map{|k,v| "#{k}=#{v}"}.join('&')
-      uri += "?#{URI.encode(qstring)}"  unless qstring.empty?
+    def jiak_uri(bucket,key="")
+      bucket_name = bucket.is_a?(JiakBucket) ? bucket.name : bucket
+      uri = "#{@server}#{URI.encode(bucket_name)}"
+      uri << "/#{URI.encode(key)}" unless key.empty?
       uri
     end
     private :jiak_uri
+
+    # Build query string. Strip keys with nil values.
+    def jiak_qstring(params={})
+      qstring = ""
+      params.delete_if {|k,v| v.nil?}
+      unless(params.empty?)
+        qstring << "?" << params.map{|k,v| "#{k}=#{v}"}.join('&')
+      end
+      qstring
+    end
+    private :jiak_qstring
     
     # Get either the schema or keys for the bucket.
     def bucket_info(bucket,info)
       ignore = (info == SCHEMA) ? KEYS : SCHEMA
       begin
-        uri = jiak_uri(bucket,"",{ignore => false})
+        uri = jiak_uri(bucket,"") << jiak_qstring({ignore => false})
         JSON.parse(RestClient.get(uri, :accept => APP_JSON))[info]
       rescue RestClient::ExceptionWithResponse => err
         fail_with_response("get", err)

data/lib/riakrest/core/jiak_data.rb

@@ -91,7 +91,7 @@ module RiakRest
       #
       # Raise JiakDataException if the fields include <code>jiak</code>.
       def allow(*fields)
-        delegate_schema("allow",*fields)
+        expand_schema("allow",*fields)
       end
 
       # :call-seq:
@@ -102,7 +102,7 @@ module RiakRest
       #
       # Returns an array of added fields.
       def require(*fields)
-        delegate_schema("require",*fields)
+        expand_schema("require",*fields)
       end
 
       # :call-seq:
@@ -113,7 +113,7 @@ module RiakRest
       #
       # Returns an array of added fields.
       def readable(*fields)
-        delegate_schema("readable",*fields)
+        expand_schema("readable",*fields)
       end
 
       # :call-seq:
@@ -124,7 +124,7 @@ module RiakRest
       #
       # Returns an array of added fields.
       def writable(*fields)
-        delegate_schema("writable",*fields)
+        expand_schema("writable",*fields)
       end
 
       # :call-seq:
@@ -142,7 +142,7 @@ module RiakRest
 
       # Delegates adding fields to the schema, then creates attr accessors for
       # each field added.
-      def delegate_schema(method,*fields)
+      def expand_schema(method,*fields)
         @schema ||= JiakSchema.new
         prev_allowed = @schema.allowed_fields
         added_fields = @schema.send(method,*fields)
@@ -150,7 +150,7 @@ module RiakRest
         added_allowed.each {|field| attr_accessor field}
         added_fields
       end
-      private :delegate_schema
+      private :expand_schema
       
       # :call-seq:
       #   JiakData.schema  -> JiakSchema
@@ -158,7 +158,6 @@ module RiakRest
       # Get a JiakSchema representation this data.
       def schema
         @schema ||= JiakSchema.new
-        @schema.dup
       end
 
       # :call-seq:
@@ -200,10 +199,6 @@ module RiakRest
     def self.included(including_class)  # :nodoc:
       including_class.extend(ClassMethods)
 
-      define_method(:initialize) do |hash={}|
-        hash.each {|k,v| instance_variable_set("@#{k}", v)}
-      end
-
       define_method(:to_jiak) do
         self.class.schema.write_mask.inject({}) do |build,field|
           build[field] = send("#{field}")
@@ -235,6 +230,10 @@ module RiakRest
     #   Instance methods
     # ----------------------------------------------------------------------
 
+    def initialize(hash={})
+      hash.each {|k,v| instance_variable_set("@#{k}", v)}
+    end
+
     # :call-seq:
     #   to_jiak  -> hash
     #

data/lib/riakrest/core/jiak_object.rb

@@ -40,7 +40,8 @@ module RiakRest
 
       # The Riak context for the object if provided.
       if opts[:vclock]
-        @riak = {}.merge(opts)
+        @riak = {}
+        [:vclock,:vtag,:lastmod].each {|k| @riak[k] = opts[k]}
       end
     end