riakrest 0.0.4 → 0.1.0

data/examples/ruby_json_data.rb

@@ -10,28 +10,10 @@ class DogData  # :nodoc:
   allowed   :name, :birthdate, :weight, :breed
   readwrite :name, :birthdate, :weight
 
-  def initialize(hsh)
-    hsh.each {|key,val| send("#{key}=",val)}
-  end
-
-  def self.create(hsh)
-    new(hsh)
-  end
+  keygen { name.downcase }
 
   def self.jiak_create(jiak)
     jiak['birthdate'] = Date.parse(jiak['birthdate']) if jiak['birthdate']    
     new(jiak)
   end
-
-  def for_jiak
-    self.class.write_mask.inject({}) do |build,field|
-      val = send("#{field}")
-      build[field] = val   unless val.nil?
-      build
-    end
-  end
-
-  def keygen
-    @name
-  end
 end

data/lib/riakrest/core/jiak_bucket.rb

@@ -1,46 +1,35 @@
 module RiakRest
 
-  # Data is stored on the Jiak server by key under a bucket. During Jiak
-  # interaction, the bucket on the server has an associated schema which
-  # determines permissible data interaction. See JiakSchema for a discussion of
-  # schemas in Jiak. Since the bucket schema can be changed dynamically,
-  # schemas can be viewed more as a loose type system rather than an onerous
-  # restriction.
+  # Data in stored in Riak by key in a bucket. Riak introduces structured
+  # interaction with the data in a bucket via a concept called a schema. The
+  # schema is not a constraint on bucket data, but rather on the interaction
+  # with bucket data. See JiakSchema.
   #
   # In RiakRest buckets have an associated JiakData class, and each JiakData
   # class has an associated JiakSchema. These associations facility setting and
   # maintaining the current schema in use for a Jiak bucket. Dynamically
   # changing the bucket schema means you can have either homogeneous (simplest)
-  # or heterogenous data in a single Jiak server bucket. It also means you can
-  # define multiple JiakData classes that effectively present different "views"
-  # (via schemas) into the same data stored on the Jiak server. These classes
-  # act like types that can determine which fields are accessible for reading
-  # and writing data. The JiakData class associated with a bucket is also used
-  # to marshal user-defined data going to and from the Jiak server.
-  #
-  # JiakResource greatly eases the bookkeeping necessary for heterogenous, as
-  # well as homogenous, data interaction with the Jiak server.
+  # or heterogenous data in a single Jiak bucket. It also means you can define
+  # multiple JiakData classes that effectively present different "views" (via
+  # schemas) into the same data stored on the Jiak server. These classes act
+  # like loose, dynamic types that can determine which fields are accessible
+  # for reading and writing data. The JiakData class associated with a bucket
+  # is also used to marshal user-defined data to and from the Jiak server.
   class JiakBucket
 
     attr_reader :schema
-    attr_accessor :name, :data_class, :params
+    attr_accessor :name, :data_class
 
     # :call-seq:
-    #   JiakBucket.new(name,data_class,params={})  -> JiakBucket
+    #   JiakBucket.new(name,data_class)  -> JiakBucket
     #
     # Create a bucket for use in Jiak interaction.
     #
-    # Valid optional parameters are <code>params</code> hash are <code>:reads,
-    # :writes, :durable_writes, :waits</code>. See JiakClient#store,
-    # JiakClient#get, and JiakClient#delete for discriptions of these
-    # parameters.
-    #
     # Raise JiakBucketException if the bucket name is not a non-empty string or
     # the data class has not included JiakData.
-    def initialize(name,data_class,params={})
+    def initialize(name,data_class)
       @name = transform_name(name)
       @data_class = check_data_class(data_class)
-      @params = check_params(params)
     end
 
     # :call-seq:
@@ -63,16 +52,6 @@ module RiakRest
       @data_class = check_data_class(data_class)
     end
 
-    # :call-seq:
-    #   bucket.params = params
-    #
-    # Set default params for Jiak client requests. See JiakBucket#new for
-    # valid parameters.
-    #
-    def params=(params)
-      @params = check_params(params)
-    end
-
     # :call-seq:
     #   bucket.schema  -> JiakSchema
     #
@@ -93,8 +72,7 @@ module RiakRest
     # values.
     def ==(other)
       (@name == other.name &&
-       @data_class == other.data_class  &&
-       @params == other.params) rescue false
+       @data_class == other.data_class) rescue false
     end
 
     # :call-seq:
@@ -103,13 +81,13 @@ module RiakRest
     # Returns <code>true</code> if <i>jiak_bucket</i> and <i>other</i> contain
     # the same attribute values.
     def eql?(other)
-      (@name.eql?(other.name) &&
-       @data_class.eql?(other.data_class) &&
-       @params.eql?(other.params)) rescue false
+      other.is_a?(JiakBucket) &&
+        @name.eql?(other.name) &&
+        @data_class.eql?(other.data_class)
     end
 
     def hash    # :nodoc:
-      @name.hash + @data_class.hash + @params.hash
+      @name.hash + @data_class.hash
     end
 
     def transform_name(name)
@@ -131,16 +109,6 @@ module RiakRest
     end
     private :check_data_class
 
-    def check_params(params)
-      valid = [:reads,:writes,:durable_writes,:waits]
-      err = params.select {|k,v| !valid.include?(k)}
-      unless err.empty?
-        raise JiakBucketException, "unrecognized request params: #{err.keys}"
-      end
-      params
-    end
-    private :check_params
-
   end
 
 end

data/lib/riakrest/core/jiak_client.rb

@@ -1,21 +1,60 @@
 module RiakRest
 
-  # Restful client interaction with a Riak document store via a JSON
-  # interface. See RiakRest for a basic example usage.
+  # Client for restful interaction with a Riak document store via the Jiak
+  # HTTP/JSON interface. RiakRest Core Client classes expose Jiak server
+  # constructs and concepts. JiakResource wraps Jiak interaction at a higher
+  # level of abstraction and takes care of much of the Core Client bookkeeping
+  # tasks. See JiakResource.
+  #
+  # ===Example
+  #  require 'riakrest'
+  #  include RiakRest
+  #
+  #  class PeopleData
+  #    include JiakData
+  #    jattr_accessor :name, :age
+  #  end
+  #
+  #  client = JiakClient.new("http://localhost:8002/jiak")
+  #  bucket = JiakBucket.new('people',PeopleData)
+  #  client.set_schema(bucket)
+  #
+  #  remy = client.store(JiakObject.new(:bucket => bucket,
+  #                                     :data => PeopleData.new(:name => "remy",
+  #                                                             :age => 10)),
+  #                      :return => :object)
+  #  callie = client.store(JiakObject.new(:bucket => bucket,
+  #                                       :data => PeopleData.new(:name => "Callie",
+  #                                                               :age => 12)),
+  #                        :return => :object)
+  #
+  #  remy.data.name = "Remy"
+  #  remy << JiakLink.new(bucket,callie.key,'sister')
+  #  client.store(remy)
+  #
+  #  sisters = client.walk(bucket,remy.key,
+  #                        QueryLink.new(bucket,'sister'),PeopleData)
+  #  sisters[0].eql?(callie)                                       #  => true
+  #
+  #  client.delete(bucket,remy.key)
+  #  client.delete(bucket,callie.key)
+  #
+  # See JiakResource for the same example using the RiakRest Resource layer.
   class JiakClient
 
-    # :stopdoc:
-    APP_JSON = 'application/json'
-    JSON_DATA = 'json'
+    attr_accessor :server, :proxy, :params
 
-    RETURN_BODY = 'returnbody'
-    READS = 'r'
-    WRITES = 'w'
+    # :stopdoc:
+    APP_JSON       = 'application/json'
+    RETURN_BODY    = 'returnbody'
+    READS          = 'r'
+    WRITES         = 'w'
     DURABLE_WRITES = 'dw'
     RESPONSE_WAITS = 'rw'
-
-    KEYS='keys'
-    SCHEMA='schema'
+    KEYS           = 'keys'
+    SCHEMA         = 'schema'
+    VALID_PARAMS   = [:reads,:writes,:durable_writes,:waits]
+    VALID_OPTS     = VALID_PARAMS << :proxy
     # :startdoc:
 
     # :call-seq:
@@ -24,44 +63,91 @@ module RiakRest
     # Create a new client for Riak RESTful (Jiak) interaction with the server at
     # the specified URI. Go through a proxy if proxy option specified.
     #
-    # Valid options:
-    #  <code>:proxy</code> Proxy server URI
-    #
-    # Raise JiakClientException if server or proxy (if exists) URI are not strings.
-    #
-    def initialize(uri='http://127.0.0.1:8002/jiak/', opts={})
-      check_opts(opts,[:proxy],JiakClientException)
-      server(uri)
-      proxy(opts[:proxy])   if(opts[:proxy])
+    # =====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>: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.
+    # 
+    def initialize(uri, opts={})
+      check_opts(opts,VALID_OPTS,JiakClientException)
+      self.server = uri
+      self.proxy = opts.delete(:proxy)
+      self.params = opts
     end
 
     # :call-seq:
-    #   server(uri)  -> string
+    #   server = uri
     #
     # Set the Jiak server URI for the client.
     #
     # Raise JiakClientException if server URI is not string.
-    def server(uri)
+    def server=(uri)
       unless uri.is_a?(String)
         raise JiakClientException, "Jiak server URI should be a string."
       end
-      @uri = uri
-      @uri += '/' unless @uri.end_with?('/')
-      @uri
+      @server = uri
+      @server += '/' unless @server.end_with?('/')
+      @server
     end
 
     # :call-seq:
-    #   proxy(uri)  -> string
+    #   server  -> string
+    #
+    # Return Jiak server URI
+    def server
+      @server
+    end
+
+    # :call-seq:
+    #   proxy = uri
     #
     # Set Jiak interaction to go through a proxy.
     #
     # Raise JiakClientException if proxy URI is not string.
-    def proxy(uri)
-      unless uri.is_a?(String)
-        raise JiakClientException, "Proxy URI should be a string."
+    def proxy=(uri)
+      unless(uri.nil?)
+        unless uri.is_a?(String)
+          raise JiakClientException, "Proxy URI should be a string."
+        end
+        RestClient.proxy = uri
       end
       @proxy = uri
-      RestClient.proxy = uri
+    end
+
+    # :call-seq:
+    #   set_params(req_params={})  ->  hash
+    #
+    # Set specified request parameters without changing unspecified ones. This
+    # method merges the passed parameters with the current settings.
+    def set_params(req_params={})
+      check_opts(req_params,VALID_PARAMS,JiakClientException)
+      @params.merge!(req_params)
+    end
+
+    # :call-seq:
+    #   params = req_params
+    #
+    # Set default params for Jiak client requests.
+    #
+    def params=(req_params)
+      check_opts(req_params,VALID_PARAMS,JiakClientException)
+      @params = req_params
+    end
+
+    # :call-seq:
+    #   params  ->  hash
+    #
+    # Copy of the current parameters hash.
+    def params
+      @params.dup
     end
 
     # :call-seq:
@@ -77,7 +163,7 @@ module RiakRest
         raise JiakClientException, "Bucket must be a JiakBucket."
       end
       resp = RestClient.put(jiak_uri(bucket),
-                            bucket.schema.to_jiak,
+                            bucket.schema.to_jiak.to_json,
                             :content_type => APP_JSON,
                             :accept => APP_JSON)
     end
@@ -89,7 +175,7 @@ module RiakRest
     # to the Jiak server. See JiakBucket#schema for a way to get this
     # information without server access.
     def schema(bucket)
-      JiakSchema.from_jiak(bucket_info(bucket,SCHEMA))
+      JiakSchema.jiak_create(bucket_info(bucket,SCHEMA))
     end
 
     # :call-seq:
@@ -105,23 +191,18 @@ module RiakRest
     # :call-seq:
     #   store(object,opts={})  -> JiakObject or key
     #
-    # Stores user-defined data (wrapped in a JiakObject) on the Jiak
-    # server. JiakData#to_jiak is used to prepare user-defined data for JSON
-    # transport to Jiak. That call is expected to return a Ruby hash
-    # representation of the writable JiakData fields that are JSONized for HTTP
-    # transport. Successful server writes return either the storage key or the
+    # Stores user-defined data (wrapped as a JiakObject) in Riak.
+    # Successful server writes return either the storage key or the
     # stored JiakObject depending on the option <code>key</code>. The object
-    # for storage must be JiakObject. Valid options are:
+    # for storage must be JiakObject.
     #
-    # <code>:return</code> :: If <code>:key</code>, return the key under which the data was stored. If <code>:object</code> return the stored JiakObject (which includes Riak context). Defaults to <code>:key</code>.
-    # <code>:writes</code> :: The number of Riak nodes that must successfully store the data.
-    # <code>:durable_writes</code> :: The number of Riak nodes (<code>< writes</code>) that must successfully store the data in a durable manner.
-    # <code>:reads</code> :: The number of Riak nodes that must successfully read data if a JiakObject is being returned.
-    #
-    # If any of the request parameters <code>:writes, :durable_writes,
-    # :reads</code> are not set, each first defaults to the value set for the
-    # JiakBucket in the JiakObject, then to the value set on the Riak
-    # cluster. In general the values set on the Riak cluster should suffice.
+    # =====Valid options
+    # <code>:return</code> -- <code>:key</code> (default), returns the key
+    # use to store the data, or <code>:object</code> returns the stored
+    # JiakObject with included Riak context.<br/>
+    # <code>:writes</code><br/>
+    # <code>:durable_writes</code><br/>
+    # <code>:reads</code><br/>
     #
     # Raise JiakClientException if object not a JiakObject or illegal options
     # are passed.<br/>
@@ -130,17 +211,16 @@ module RiakRest
     def store(jobj,opts={})
       check_opts(opts,[:return,:reads,:writes,:durable_writes],
                  JiakClientException)
-      params = jobj.bucket.params
       req_params = {
-        WRITES => opts[:writes] || params[:writes], 
-        DURABLE_WRITES => opts[:durable_writes] || params[:durable_writes],
-        READS => opts[:reads] || params[:reads]
+        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)
 
       begin
         uri = jiak_uri(jobj.bucket,jobj.key,req_params)
-        payload = jobj.to_jiak
+        payload = jobj.to_jiak.to_json
         headers = { 
           :content_type => APP_JSON,
           :accept => APP_JSON }
@@ -159,7 +239,7 @@ module RiakRest
         end
         
         if(req_params[RETURN_BODY])
-          JiakObject.from_jiak(JSON.parse(resp),jobj.bucket.data_class)
+          JiakObject.jiak_create(JSON.parse(resp),jobj.bucket.data_class)
         elsif(key_empty)
           resp.headers[:location].split('/').last
         else
@@ -187,12 +267,10 @@ module RiakRest
     # in a bucket this will not be an issue.
     #
     # The bucket must be a JiakBucket and the key must be a non-empty
-    # String. Valid options are:
+    # String.
     #
-    # <code>:reads</code> --- The number of Riak nodes that must successfully
-    # reply with the data. If not set, defaults first to the value set for the
-    # JiakBucket, then to the value set on the Riak cluster. In general the
-    # values set on the Riak cluster should suffice.
+    # =====Valid options
+    # <code>:reads</code>
     #
     # Raise JiakClientException if bucket not a JiakBucket.<br/>
     # Raise JiakResourceNotFound if resource not found on Jiak server.<br/>
@@ -203,12 +281,12 @@ module RiakRest
         raise JiakClientException, "Bucket must be a JiakBucket."
       end
       check_opts(opts,[:reads],JiakClientException)
-      req_params = {READS => opts[:reads] || bucket.params[:reads]}
+      req_params = {READS => opts[:reads] || @params[:reads]}
 
       begin
         uri = jiak_uri(bucket,key,req_params)
         resp = RestClient.get(uri, :accept => APP_JSON)
-        JiakObject.from_jiak(JSON.parse(resp),bucket.data_class)
+        JiakObject.jiak_create(JSON.parse(resp),bucket.data_class)
       rescue RestClient::ResourceNotFound => err
         raise JiakResourceNotFound, "failed get: #{err.message}"
       rescue RestClient::ExceptionWithResponse => err
@@ -221,19 +299,17 @@ module RiakRest
     # :call-seq:
     #   delete(bucket,key,opts={})  -> true or false
     #
-    # Delete the JiakObject stored at the bucket/key. Valid options are:
+    # Delete the JiakObject stored at the bucket/key.
     #
-    # <code>:waits</code> --- The number of Riak nodes that must reply the
-    # delete has occurred before success. If not set, defaults first to the
-    # value set for the JiakBucket, then to the value set on the Riak
-    # cluster. In general the values set on the Riak cluster should suffice.
+    # =====Valid options
+    # <code>:waits</code>
     #
     # Raise JiakResourceException on RESTful HTTP errors.
     #
     def delete(bucket,key,opts={})
       check_opts(opts,[:waits],JiakClientException)
       begin
-        req_params = {RESPONSE_WAITS => opts[:waits] || bucket.params[:waits]}
+        req_params = {RESPONSE_WAITS => opts[:waits] || @params[:waits]}
         uri = jiak_uri(bucket,key,req_params)
         RestClient.delete(uri, :accept => APP_JSON)
         true
@@ -268,7 +344,7 @@ module RiakRest
         resp = RestClient.get(uri, :accept => APP_JSON)
         # JSON.parse(resp)['results'][0]
         JSON.parse(resp)['results'][0].map do |jiak|
-          JiakObject.from_jiak(jiak,data_class)
+          JiakObject.jiak_create(jiak,data_class)
         end
       rescue RestClient::ExceptionWithResponse => err
         fail_with_response("put", err)
@@ -277,20 +353,12 @@ module RiakRest
       end
     end
 
-    # :call-seq:
-    #   client.uri  -> string
-    #
-    # String representation of the base URI of the Jiak server.
-    def uri
-      @uri
-    end
-
     # :call-seq:
     #    client == other -> true or false
     #
     # Equality -- JiakClients are equal if they have the same URI
     def ==(other)
-      (@uri == other.uri) rescue false
+      (@server == other.server) rescue false
     end
     
     # :call-seq:
@@ -300,16 +368,16 @@ module RiakRest
     # same URI.
     def eql?(other)
       other.is_a?(JiakClient) &&
-        @uri.eql?(other.uri)
+        @server.eql?(other.server)
     end
 
     def hash    # :nodoc:
-      @uri.hash
+      @server.hash
     end
 
     # Build the URI for accessing the Jiak server.
     def jiak_uri(bucket,key="",params={})
-      uri = "#{@uri}#{URI.encode(bucket.name)}"
+      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?