riakrest 0.1.2 → 0.1.5

data/examples/linked_resources.rb

@@ -1,14 +1,6 @@
 require File.dirname(__FILE__) + '/example_helper.rb'
 
-class Parents
-  include JiakResource
-  server         SERVER_URI
-  jattr_accessor :name
-  keygen { name }
-end
-(Child = Parents.dup).group 'children'
-
-# relationships
+# The parent-child relationships
 parent_children = {
   'p0' => ['c0'],
   'p1' => ['c0','c1','c2'],
@@ -16,17 +8,20 @@ parent_children = {
   'p3' => ['c3']
 }
 
-# invert relationships
-child_parents = parent_children.inject({}) do |build, (p,cs)|
-  cs.each do |c|
-    build[c] ? build[c] << p : build[c] = [p]
-  end
-  build
+# Simple resource classes. Parent group (Jiak bucket name) defaults to
+# lowercase of class name, so Child class just like Parent, but grouped by
+# 'child' rather than 'parent'.
+class Parent
+  include JiakResource
+  server         SERVER_URI
+  attr_accessor :name
+  keygen { name }
 end
+(Child = Parent.dup).group 'child'
 
-# store data and relationships
+# Store data and relationships
 parent_children.each do |pname,cnames|
-  p = Parents.new(:name => pname).post
+  p = Parent.new(:name => pname).post
   cnames.each do |cname|
     begin
       c = Child.get(cname)
@@ -40,70 +35,43 @@ parent_children.each do |pname,cnames|
   p.update
 end
 
-# retrieve parents
-parents = parent_children.keys.map {|p| Parents.get(p)}
-p0,p1,p2,p3 = parents
-puts p1.name                                      # => 'p1'
-
-# retrieve children
-children = child_parents.keys.map {|c| Child.get(c)}
-c0,c1,c2,c3 = children
-puts c1.name                                      # => 'c1'
+# Retrieve parents and children objects for future reference
+parents  = parent_children.keys.map {|p| Parent.get(p)}
+children = parent_children.values.flatten.uniq.map {|c| Child.get(c)}
 
-# retrieve parent children
-p0c,p1c,p2c,p3c = parents.map {|p| p.query(Child,'child')}
-puts p2c[0].name                                  # => 'c2' (could be 'c3')
+# Retrieve parent-1 children by query
+p1c = parents[1].query([Child,'child'])
+puts "   3 children? #{p1c.size == 3}"                           # => true
+puts " Including c2? #{p1c.include?(children[2])}"               # => true
 
-# retrieve children parents
-c0p,c1p,c2p,c3p = children.map {|c| c.query(Parents,'parent')}
-puts c3p[0].name                                  # => 'p2'
-puts c3p[1].name                                  # => 'p3'
+# Retrieve child-3 parents by query
+c3p = children[3].query([Parent,'parent'])
+puts "    2 parents? #{c3p.size == 2}"                           # => true
+puts " Including p2? #{c3p.include?(parents[2])}"                # => true
 
-# retrieve children siblings
-c0s,c1s,c2s,c3s = children.map do |c|
-  c.query(Parents,'parent',Child,'child').delete_if{|s| s.eql?(c)}
-end
-puts c3s[0].name                                  # => 'c2'
+# Retrieve child-2 siblings by multi-step query
+c2s = children[2].query([Parent,'parent',Child,'child'])
+c2s.delete_if{|s| s.eql?(children[2])}
+puts "   3 siblings? #{c2s.size == 3}"                           # => true
+puts " Including c0? #{c2s.include?(children[0])}"               # => true
 
-# who is c3's step-sibling's other parent?
-c3sp = c3.query(Parents,'parent',Child,'child',Parents,'parent')
+# Who is c3's step-sibling's other parent?
+c3sp = children[3].query([Parent,'parent',Child,'child',Parent,'parent'])
 c3p.each {|p| c3sp.delete_if{|sp| p.eql?(sp)}}
-puts c3sp[0].name                                 # => "p1"
-
-# turn on auto-update at class level
-Parents.auto_update true
-Child.auto_update  true
+puts "    Parent p1? #{c3sp.include?(parents[1])}"               # => true
 
-# add sibling links
+# Add sibling links using existing links (say, for convenience)
 children.each do |c|
-  siblings = c.query(Parents,'parent',Child,'child').delete_if{|s| s.eql?(c)}
+  siblings = c.query([Parent,'parent',Child,'child']).delete_if{|s| s.eql?(c)}
   siblings.each {|s| c.link(s,'sibling')}
   c.update
 end
-puts c1.query(Child,'sibling').size               # => 2  
-  
-# some folks are odd, and others are normal
-parent_children.keys.each do |p|
-  parent = Parents.get(p)
-  p_children = parent.query(Child,'child')
-  p_children.each do |child| 
-    child.link(parent, p[1].to_i.odd? ? 'odd' : 'normal')
-    child.update
-    parent.link(child, child.name[1].to_i.odd? ? 'odd' : 'normal')
-  end
-  parent.update
-end
-# refresh parents and children variables
-parents.each {|p| p.refresh}
-children.each {|c| c.refresh}
 
-# do any odd parents have normal children?
-op = parents.inject([]) do |build,parent|
-  build << parent.query(Child,'normal',Parents,'odd')
-  build.flatten.uniq
-end
-puts op[0].name                                   # => 'p1'
+# Retrieve child-2 siblings using new links
+c2s = children[2].query([Child,'sibling'])
+puts "   3 siblings? #{c2s.size == 3}"                           # => true
+puts " Including c0? #{c2s.include?(children[0])}"               # => true
 
-# clean-up by deleting everybody
+# Clean-up by deleting all parents and children
 parents.each  {|p| p.delete}
 children.each {|c| c.delete}

data/lib/riakrest/core/jiak_client.rb

@@ -12,7 +12,7 @@ module RiakRest
   #
   #  class PeopleData
   #    include JiakData
-  #    jattr_accessor :name, :age
+  #    attr_accessor :name, :age
   #  end
   #
   #  client = JiakClient.new("http://localhost:8002/jiak")
@@ -45,29 +45,41 @@ module RiakRest
     attr_accessor :server, :proxy, :params
 
     # :stopdoc:
-    APP_JSON       = 'application/json'
+    APP_JSON               = 'application/json'
     APP_JSON.freeze
 
-    RETURN_BODY    = 'returnbody'
+    KEYS                   = 'keys'
+    SCHEMA                 = 'schema'
+    KEYS.freeze
+    SCHEMA.freeze
+
+    RETURN_BODY            = 'returnbody'
+    READS                  = 'r'
+    WRITES                 = 'w'
+    DURABLE_WRITES         = 'dw'
+    DELETES                = 'rw'
+    COPY                   = 'copy'
+    READ                   = 'read'
+
     RETURN_BODY.freeze
-    READS          = 'r'
     READS.freeze
-    WRITES         = 'w'
     WRITES.freeze
-    DURABLE_WRITES = 'dw'
     DURABLE_WRITES.freeze
-    DELETES        = 'rw'
     DELETES.freeze
+    COPY.freeze
+    READ.freeze
 
-    VALID_PARAMS   = [:reads,:writes,:durable_writes,:deletes]
-    VALID_PARAMS.freeze
-    VALID_OPTS     = Array.new(VALID_PARAMS) << :proxy
-    VALID_OPTS.freeze
+    CLIENT_PARAMS = [:reads,:writes,:durable_writes,:deletes,:proxy]
+    STORE_PARAMS  = [:writes,:durable_writes,:return,:reads,:copy,:read]
+    GET_PARAMS    = [:reads,:read]
+    DELETE_PARAMS = [:delete]
+    WALK_PARAMS   = [:read]
 
-    KEYS           = 'keys'
-    KEYS.freeze
-    SCHEMA         = 'schema'
-    SCHEMA.freeze
+    CLIENT_PARAMS.freeze
+    STORE_PARAMS.freeze
+    GET_PARAMS.freeze
+    DELETE_PARAMS.freeze
+    WALK_PARAMS.freeze
     # :startdoc:
 
     # :call-seq:
@@ -79,7 +91,7 @@ module RiakRest
     # =====Valid options
     # <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>:durable_writes</code>:: Minimum number of responding nodes that must perform a durable write to a persistence layer.
     # <code>:deletes</code>:: Minimum number of responding nodes for successful delete.
     # <code>:proxy</code>:: Proxy server URI
     #
@@ -95,7 +107,7 @@ module RiakRest
     # individual request will default to the values set in the Riak cluster.
     # 
     def initialize(uri, opts={})
-      check_opts(opts,VALID_OPTS,JiakClientException)
+      check_opts(opts,CLIENT_PARAMS,JiakClientException)
       self.server = uri
       self.proxy = opts.delete(:proxy)
       self.params = opts
@@ -143,10 +155,10 @@ module RiakRest
     # :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.
+    # Set specified client 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)
+      check_opts(req_params,CLIENT_PARAMS,JiakClientException)
       @params.merge!(req_params)
     end
 
@@ -156,7 +168,7 @@ module RiakRest
     # Set default params for Jiak client requests.
     #
     def params=(req_params)
-      check_opts(req_params,VALID_PARAMS,JiakClientException)
+      check_opts(req_params,CLIENT_PARAMS,JiakClientException)
       @params = req_params
     end
 
@@ -232,32 +244,39 @@ module RiakRest
     # <code>:writes</code><br/>
     # <code>:durable_writes</code><br/>
     # <code>:reads</code><br/>
+    # <code>:copy</code> -- <code>true</code> to indicate the any data
+    # fields already stored on the server and not explicitly altered by this
+    # write should be copied and left unchanged. Default is
+    # <code>false</code><br/>.
+    # <code>:read</code> -- Comma separated list of fields to be returned on
+    # read.
     #
     # 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).
+    # durable_writes,</code> and <code>reads</code> parameters. The
+    # <code>reads</code> and <code>read</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.
     #
     def store(jobj,opts={})
-      check_opts(opts,[:return,:reads,:writes,:durable_writes],
-                 JiakClientException)
+      check_opts(opts,STORE_PARAMS,JiakClientException)
       req_params = {
         WRITES => opts[:writes] || @params[:writes], 
         DURABLE_WRITES => opts[:durable_writes] || @params[:durable_writes],
+        COPY => opts[:copy]
       }
       if(opts[:return] == :object)
         req_params[RETURN_BODY] = true
         req_params[READS] = opts[:reads] || @params[:reads]
+        req_params[READ] = opts[:read]
       end
 
       begin
         uri = jiak_uri(jobj.bucket,jobj.key) << jiak_qstring(req_params)
         payload = jobj.to_jiak.to_json
-        headers = { 
+        headers = {
           :content_type => APP_JSON,
           :accept => APP_JSON }
         # Decision tree:
@@ -316,9 +335,10 @@ module RiakRest
       unless bucket.is_a?(JiakBucket)
         raise JiakClientException, "Bucket must be a JiakBucket."
       end
-      check_opts(opts,[:reads],JiakClientException)
+      check_opts(opts,GET_PARAMS,JiakClientException)
       req_params = {
-        READS => opts[:reads] || @params[:reads]
+        READS => opts[:reads] || @params[:reads],
+        READ  => opts[:read]
       }
 
       begin
@@ -345,7 +365,7 @@ module RiakRest
     # Raise JiakResourceException on RESTful HTTP errors.
     #
     def delete(bucket,key,opts={})
-      check_opts(opts,[:deletes],JiakClientException)
+      check_opts(opts,DELETE_PARAMS,JiakClientException)
       begin
         req_params = {DELETES => opts[:deletes] || @params[:deletes]}
         uri = jiak_uri(bucket,key) << jiak_qstring(req_params)
@@ -383,7 +403,11 @@ module RiakRest
     # JiakObject array.
     #
     # See QueryLink for a description of the <code>query</code> structure.
-    def walk(bucket,key,query,data_class)
+    def walk(bucket,key,query,data_class,opts={})
+      check_opts(opts,WALK_PARAMS,JiakClientException)
+      req_params = {
+        READ => opts[:read]
+      }
       begin
         start = jiak_uri(bucket,key)
         case query
@@ -395,6 +419,7 @@ module RiakRest
           raise QueryLinkException, 'failed: query must be '+
             'a QueryLink or an Array of QueryLink objects'
         end
+        uri << jiak_qstring(req_params)
         resp = RestClient.get(uri, :accept => APP_JSON)
         JSON.parse(resp)['results'][0].map do |jiak|
           JiakObject.jiak_create(jiak,data_class)

data/lib/riakrest/core/jiak_data.rb

@@ -7,8 +7,8 @@ module RiakRest
   # user-data instances, rather it facilitates creating the class used to
   # create user-data instances.
   #
-  # The class methods <code>jattr_reader,jattr_writer</code>, and
-  # <code>jattr_accessor</code> are used to declare the Jiak readable and
+  # The class methods <code>attr_reader,attr_writer</code>, and
+  # <code>attr_accessor</code> are used to declare the Jiak readable and
   # writable fields for a JiakData. The method <code>keygen</code> is used
   # to specify a block for generating the key for a data instance. By default,
   # JiakData generates an empty key which is interpreted by the Jiak server as
@@ -16,7 +16,7 @@ module RiakRest
   # ====Example
   #  class FooBar
   #    include JiakData
-  #    jattr_accessor :foo, :bar
+  #    attr_accessor :foo, :bar
   #    keygen { foo.downcase }
   #  end
   #
@@ -54,29 +54,29 @@ module RiakRest
     module ClassMethods
 
       # :call-seq:
-      #   jattr_reader :f1,...,:fn
+      #   attr_reader :f1,...,:fn
       #
       # Add read accessible fields.
-      def jattr_reader(*fields)
+      def attr_reader(*fields)
         readable *fields
         nil
       end
-      alias :jattr :jattr_reader
+      alias :attr :attr_reader
 
       # :call-seq:
-      #   jattr_writer :f1,...,:fn
+      #   attr_writer :f1,...,:fn
       #
       # Add write accessible fields.
-      def jattr_writer(*fields)
+      def attr_writer(*fields)
         writable *fields
         nil
       end
 
       # :call-seq:
-      #   jattr_accessor :f1,...,:fn
+      #   attr_accessor :f1,...,:fn
       #
       # Add read/write accessible fields.
-      def jattr_accessor(*fields)
+      def attr_accessor(*fields)
         readable *fields
         writable *fields
       end
@@ -147,7 +147,17 @@ module RiakRest
         prev_allowed = @schema.allowed_fields
         added_fields = @schema.send(method,*fields)
         added_allowed = @schema.allowed_fields - prev_allowed
-        added_allowed.each {|field| attr_accessor field}
+        # added_allowed.each {|field| attr_accessor field}
+        added_allowed.each do |field| 
+          class_eval <<-EOH
+            def #{field}
+              @#{field}
+            end
+            def #{field}=(val)
+              @#{field} = val
+            end
+          EOH
+        end
         added_fields
       end
       private :expand_schema
@@ -178,7 +188,7 @@ module RiakRest
       # structured Jiak interaction. See JiakSchema for read mask discussion.
       #
       # User-defined data classes must either override this method explicitly
-      # or use the <code>jattr_*</code> methods which implicitly override this
+      # or use the <code>attr_*</code> methods which implicitly override this
       # method. The method is automatically called to marshall data from
       # Jiak. You do not call this method explicitly.
       #
@@ -242,11 +252,11 @@ module RiakRest
     # for shema discussion.
     #
     # User-defined data classes must either override this method explicitly or
-    # use the <code>jattr_*</code> methods which implicitly provide an implicit
+    # use the <code>attr_*</code> methods which implicitly provide an implicit
     # override. The method is automatically called to marshall data to
     # Jiak. You do not call this method explicitly.
 
-    # Data classes that do not used the jattr_* methods to specify attributes
+    # Data classes that do not used the attr_* methods to specify attributes
     # must override this method. 
     #
     # ====Example

data/lib/riakrest/core/jiak_data_fields.rb

@@ -28,15 +28,15 @@ module RiakRest
         if(args.size == 1)
           case args[0]
           when Symbol, Array
-            jattr_accessor *args[0]
+            attr_accessor *args[0]
           when JiakSchema
-            jattr_reader *args[0].read_mask
-            jattr_writer *args[0].write_mask
+            attr_reader *args[0].read_mask
+            attr_writer *args[0].write_mask
             allow    *args[0].allowed_fields
             require  *args[0].required_fields
           end
         else
-          jattr_accessor *args
+          attr_accessor *args
         end
 
         # :call-seq:

data/lib/riakrest/core/query_link.rb

@@ -1,21 +1,28 @@
 module RiakRest
 
-  # Represents a link used to query linked objects in Jiak. Links are
-  # established using a JiakLink and queried using a QueryLink. The structures
-  # are very similar but significantly different.
+  # Represents a link used to query linked objects using Jiak's link/step
+  # map-reduce facility. Links are established using a JiakLink and queried
+  # using a QueryLink. The structures are very similar but significantly
+  # different. A JiakLink is [bucket,key,tag] and a QueryLink is
+  # [bucket,tag,acc]. The accumulator field of a QueryLink allows for
+  # accumulating intermediate link/step results. Since RiakRest auto-inflates
+  # data returned via Jiak link/step processing, the accumulation of
+  # intermediate results is not supported by RiakRest. The setting of the
+  # <code>acc</code> is implemented for future consideration but should not be
+  # used.
   #
   # ===Usage
   # <code>
   #   link = QueryLink.new('people','parent')
-  #   link = QueryLink.new(['children','odd','_'])
-  #   link = QueryLink.new('blogs',nil,QueryLink::ANY)
+  #   link = QueryLink.new('blogs',nil)
   # </code>
   class QueryLink
 
     attr_accessor :bucket, :tag, :acc
 
-    # Jiak (erlang) wildcard character (atom)
+    # Jiak wildcard character (erlang atom)
     ANY = '_'
+    ANY.freeze
 
     # :call-seq:
     #   QueryLink.new(*args)  -> QueryLink