riakrest 0.1.2 → 0.1.5

data/lib/riakrest/resource/jiak_resource.rb

@@ -1,30 +1,45 @@
 module RiakRest
-  # JiakResource provides a resource-oriented wrapper for Jiak interaction.
+  # JiakResource provides an abstraction to the Jiak interaction provided by
+  # the Core Client classes of RiakRest. JiakResource is built on top of Core
+  # Client and does not provide any functionality not possible through Core
+  # Client. However, JiakResource does provide a much simplier Jiak interaction
+  # interface.
   #
   # ===Example
   #  require 'riakrest'
   #  include RiakRest
   #
-  #  class People
+  #  class Person
   #    include JiakResource
   #    server 'http://localhost:8002/jiak'
-  #    jattr_accessor :name, :age
+  #    attr_accessor :name, :age
   #    auto_manage
   #  end
   #
-  #  remy = People.new(:name => 'Remy',:age => 10)       # (auto-post)
+  #  remy = Person.new(:name => 'Remy',:age => 10)       # (auto-post)
   #  remy.age = 11                                       # (auto-update)
   #
-  #  callie = People.new(:name => 'Callie', :age => 13)
+  #  callie = Person.new(:name => 'Callie', :age => 13)
   #  remy.link(callie,'sister')
   #
-  #  sisters = remy.query(People,'sister')
+  #  sisters = remy.query([Person,'sister'])
   #  sisters[0].eql?(callie)                             # => true
   #
   #  remy.delete
   #  callie.delete
   
   module JiakResource
+
+    # :stopdoc:
+    PUT_PARAMS    = [:writes,:durable_writes,:reads,:copy,:read]
+    GET_PARAMS    = [:reads,:read]
+    DELETE_PARAMS = [:deletes]
+
+    PUT_PARAMS.freeze
+    GET_PARAMS.freeze
+    DELETE_PARAMS.freeze
+    # :startdoc:
+
     # ----------------------------------------------------------------------
     # Class methods
     # ----------------------------------------------------------------------
@@ -57,34 +72,34 @@ module RiakRest
       end
 
       # :call-seq:
-      #   jattr_reader :f1,...,:fn
+      #   attr_reader :f1,...,:fn
       #
       # Add read accessible fields.
-      def jattr_reader(*fields)
+      def attr_reader(*fields)
         check_fields(fields)
         added_fields = jiak.data.readable(*fields)
         added_fields.each do |field|
           class_eval <<-EOM
             def #{field}
-              @jiak.data.#{field}
+              @jiak.object.data.#{field}
             end
           EOM
         end
         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)
         check_fields(fields)
         added_fields = jiak.data.writable(*fields)
         added_fields.each do |field|
           class_eval <<-EOM
             def #{field}=(val)
-              @jiak.data.#{field} = val
+              @jiak.object.data.#{field} = val
               self.class.do_auto_update(self)
             end
           EOM
@@ -93,12 +108,12 @@ module RiakRest
       end
 
       # :call-seq:
-      #   jattr_accessor :f1,...,:fn
+      #   attr_accessor :f1,...,:fn
       #
       # Add read/write accessible fields.
-      def jattr_accessor(*fields)
-        jattr_reader *fields
-        jattr_writer *fields
+      def attr_accessor(*fields)
+        attr_reader *fields
+        attr_writer *fields
       end
 
       def check_fields(fields)
@@ -127,7 +142,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 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.
       #
       # The configuration of a Riak cluster includes server setting for
@@ -258,14 +273,11 @@ module RiakRest
       # <code>:durable_writes</code>
       # <code>:reads</code>
       # 
-      # If any of the request parameters <code>:writes, :durable_writes,
-      # :reads</code> are not set, each first defaults to the value set for the
-      # JiakResource class, then to the value set on the Riak cluster. In
-      # general the values set on the Riak cluster should suffice.
+      # See JiakResource#params for description of options.
       def put(resource,opts={})
+        check_opts(opts,PUT_PARAMS,JiakResourceException)
         opts[:return] = :object
         resource.jiak.object = jiak.client.store(resource.jiak.object,opts)
-        resource.jiak_convenience
         resource
       end
 
@@ -303,11 +315,12 @@ module RiakRest
       # Get a JiakResource on the Jiak server by the specified key.
       #
       # =====Valid options:
-      # <code>:reads</code> --- See JiakResource#new
+      # <code>:reads</code> --- See JiakResource#params
       #
       # Raise JiakResourceNotFound if no resource exists on the Jiak server for
       # the key.
       def get(key,opts={})
+        check_opts(opts,GET_PARAMS,JiakResourceException)
         new(jiak.client.get(jiak.bucket,key,opts))
       end
 
@@ -317,10 +330,10 @@ module RiakRest
       # Updates a JiakResource with the data on the Jiak server. The current
       # data of the JiakResource is overwritten, so use with caution.
       #
-      # See JiakResource#put for options.
+      # See JiakResource#get for options.
       def refresh(resource,opts={})
-        resource.jiak.object = get(resource.jiak.key,opts).jiak.object
-        resource.jiak_convenience
+        check_opts(opts,GET_PARAMS,JiakResourceException)
+        resource.jiak.object = get(resource.jiak.object.key,opts).jiak.object
       end
 
       # :call-seq:
@@ -330,8 +343,9 @@ module RiakRest
       # key.
       #
       # =====Valid options:
-      # <code>:deletes</code> --- See JiakResource#new
+      # <code>:deletes</code> --- See JiakResource#params
       def delete(resource,opts={})
+        check_opts(opts,DELETE_PARAMS,JiakResourceException)
         jiak.client.delete(jiak.bucket,resource.jiak.object.key,opts)
       end
 
@@ -392,38 +406,46 @@ module RiakRest
       end
       
       # :call-seq:
-      #   JiakResource.query(from,*steps)
+      #   JiakResource.query(from,steps,opts={})
       #
       # Retrieves an array of JiakResource objects by starting with the links
-      # in the <code>from</code> JiakResource and doing the query steps. The
-      # steps are a series of query links designated by a JiakResource and a
-      # string tag, or a JiakResource, a string tag and a string
-      # accumulator. The type of JiakResource returned in the array is
-      # determined by the JiakResource designated in the last step.
+      # in the <code>from</code> JiakResource and performing the query
+      # steps. Steps is an array holding a series of query links designated by
+      # JiakResource,tag pairs. The type of JiakResources returned by the query
+      # is determined by the JiakResource class designated in the last step.
+      #
+      # Note: Although Jiak supports accumulating intermediate link step
+      # results, since RiakRest auto-inflates returned data intermediate
+      # accumulation is not supported. The most common usage, however, is to
+      # only accumulate the last step as supported by RiakRest.
       #
       # ====Usage
       # <code>
-      #   JiakResource.query(resource,Child,'child')
-      #   JiakResource.query(resource,Parent,'odd',Child,'normal')
+      #   JiakResource.query(resource,[Child,'child'])
+      #   JiakResource.query(resource,[Parent,'odd',Child,'normal'])
       # </code>
-      def query(from,*steps)
-        links = []
-        until steps.empty?
-          begin
-            klass,tag = steps.shift(2)
-            last_klass = klass
-            acc = steps[0].is_a?(String) ? steps.shift : nil
-            links << QueryLink.new(klass.jiak.group,tag,acc)
-          rescue
-            raise(JiakResourceException, 
-                  "each step should be Klass,tag or Klass,tag,acc")
+      def query(from,steps,opts={})
+        check_opts(opts,GET_PARAMS,JiakResourceException)
+        begin
+          links = []
+          klass = nil
+          steps.each_slice(2) do |pair|
+            klass = pair[0]
+            links << QueryLink.new(klass.jiak.bucket.name,pair[1],nil)
           end
+          data_class = klass.jiak.bucket.data_class
+          if(klass.include?(JiakResourcePOV))
+            opts[:read] = klass.jiak.read_mask
+          end
+          jiak.client.walk(from.jiak.object.bucket,
+                           from.jiak.object.key,
+                           links,
+                           data_class,
+                           opts).map {|jobj| klass.new(jobj)}
+        # rescue
+        #   raise(JiakResourceException,
+        #         "each step should be JiakResource,tag pair")
         end
-        links = links[0]  if links.size == 1
-        jiak.client.walk(from.jiak.object.bucket, from.jiak.object.key, links,
-                         last_klass.jiak.bucket.data_class).map do |jobj|
-          last_klass.new(jobj)
-        end        
       end
       alias :walk :query
       
@@ -483,7 +505,7 @@ module RiakRest
     # with the JiakResource.
     def initialize(*args)
       # First form is used by JiakResource.get and JiakResource.query
-      @jiak = Struct.new(:object,:bucket,:key,:data,:links,:auto_update).new
+      @jiak = Struct.new(:object,:auto_update).new
       if(args.size == 1 && args[0].is_a?(JiakObject))
         @jiak.object = args[0]
       else
@@ -498,16 +520,6 @@ module RiakRest
           self.class.post(self)
         end
       end
-      jiak_convenience
-    end
-
-    # Public method as a by-product of implementation. No harm done in calling
-    # this method, as it will just repeat assignments already done.
-    def jiak_convenience     # :nodoc:
-      @jiak.bucket = @jiak.object.bucket
-      @jiak.key    = @jiak.object.key
-      @jiak.data   = @jiak.object.data
-      @jiak.links  = @jiak.object.links
     end
 
     # :call-seq:
@@ -545,7 +557,6 @@ module RiakRest
     # for options.
     def put(opts={})
       @jiak.object = (self.class.put(self,opts)).jiak.object
-      jiak_convenience
       self
     end
 
@@ -557,7 +568,6 @@ module RiakRest
     # options.
     def post(opts={})
       @jiak.object = (self.class.post(self,opts)).jiak.object
-      jiak_convenience
       self
     end
 
@@ -569,7 +579,6 @@ module RiakRest
     # options.
     def update(opts={})
       @jiak.object = (self.class.update(self,opts)).jiak.object
-      jiak_convenience
       self
     end
     alias :push :update
@@ -632,21 +641,26 @@ module RiakRest
     end
 
     # :call-seq:
-    #   query(*steps) -> array
+    #   query(steps) -> array
     #
     # Performs a Jiak query starting at this resource. See
     # JiakResource#ClassMethods#query for description.
     #
     # ====Usage
     # <code>
-    #   query(Child,'child')
-    #   query(Parent,'odd',Child,'normal')
+    #   query([Child,'child'])
+    #   query([Parent,'odd',Child,'normal'])
     # </code>
-    def query(*steps)
-      self.class.query(self,*steps)
+    def query(steps,opts={})
+      self.class.query(self,steps)
     end
     alias :walk :query
 
+    # CxINC
+    def pov(pov)
+      pov.get(@jiak.object.key)
+    end
+    
     # :call-seq:
     #   jiak_resource == other -> true or false
     #

data/lib/riakrest/resource/jiak_resource_pov.rb

@@ -0,0 +1,279 @@
+module RiakRest
+
+  # JiakResourcePOV provides a restricted interface to existing JiakResource
+  # data. This restriction offers two primary benefits: Only explicitly
+  # declared fields can be read or written via the POV, thereby protecting
+  # other JiakResource fields, and only the POV fields are transported to and
+  # from the Jiak server, thereby reducing the HTTP message sizes.
+  #
+  # ===Example
+  #  require 'riakrest'
+  #  include RiakRest
+  #
+  #  class AB
+  #    include JiakResource
+  #    server SERVER_URI
+  #    group  "test"
+  #    attr_accessor :a, :b
+  #    keygen { "k#{a}" }
+  #  end
+  #
+  #  class A
+  #    include JiakResourcePOV
+  #    resource AB
+  #    attr_accessor :a
+  #  end
+  #
+  #  ab = AB.new(:a => 1, :b => 2)
+  #  ab.post
+  #
+  #  a = ab.pov(A)
+  #  a.a = 11
+  #  a.update
+  #  
+  #  ab.refresh
+  #  ab.a                                     # => 11
+
+  module JiakResourcePOV
+
+    # ----------------------------------------------------------------------
+    # Class methods
+    # ----------------------------------------------------------------------
+    
+    # Class methods for creating a user-defined JiakResourcePOV.
+    #
+    # See JiakResourcePOV for example usage.
+    module ClassMethods
+
+      # :call-seq:
+      #   JiakResourcePOV.resource(resource)
+      #
+      # Set the JiakResource to which this JiakResourcePOV is a point-of-view.
+      def resource(resource)
+        @resource = resource
+        @jiak.bucket = JiakBucket.new(@resource.jiak.group,
+                                      JiakDataFields.create)
+      end
+
+      # :call-seq:
+      #   attr_reader :f1,...,:fn
+      #
+      # Add read accessible fields.
+      def attr_reader(*fields)
+        check_fields(fields,@resource.schema.read_mask)
+        added_fields = @jiak.bucket.data_class.readable(*fields)
+        added_fields.each do |field|
+          class_eval <<-EOM
+            def #{field}
+              @jiak.object.data.#{field}
+            end
+          EOM
+        end
+        @jiak.read_mask = @jiak.bucket.data_class.schema.read_mask.join(',')
+        nil
+      end
+
+      # :call-seq:
+      #   attr_writer :f1,...,:fn
+      #
+      # Add write accessible fields.
+      def attr_writer(*fields)
+        check_fields(fields,@resource.schema.write_mask)
+        added_fields = @jiak.bucket.data_class.writable(*fields)
+        added_fields.each do |field|
+          class_eval <<-EOM
+            def #{field}=(val)
+              @jiak.object.data.#{field} = val
+              self.class.do_auto_update(self)
+            end
+          EOM
+        end
+        nil
+      end
+
+      # :call-seq:
+      #   attr_accessor :f1,...,:fn
+      #
+      # Add read/write accessible fields.
+      def attr_accessor(*fields)
+        attr_reader(*fields)
+        attr_writer(*fields)
+      end
+
+      def check_fields(fields,valid)
+        invalid = fields.select {|f| !valid.include?(f)}
+        unless(invalid.empty?)
+          raise(JiakResourcePOVException,"invalid fields: #{invalid.inspect}")
+        end
+      end
+      private :check_fields
+
+      # :call-seq:
+      #   JiakResourcePOV.keys   -> array
+      #
+      # Get an array of the current keys for this resource. Since key lists are
+      # updated asynchronously on a Riak cluster the returned array can be out
+      # of synch immediately after new puts or deletes.
+      def keys
+        @resource.jiak.client.keys(jiak.bucket)
+      end
+
+      # :call-seq:
+      #   JiakResourcePOV.get(key,opts={})  -> JiakResourcePOV
+      #
+      # Get a JiakResourcePOV on the Jiak server by the specified key.
+      #
+      # =====Valid options:
+      # <code>:reads</code> --- See JiakResource#get
+      #
+      # Raise JiakResourceNotFound if no resource exists on the Jiak server for
+      # the key.
+      def get(key,opts={})
+        opts[:read] = @jiak.read_mask
+        new(@resource.jiak.client.get(@jiak.bucket,key,opts))
+      end
+
+      # :call-seq:
+      #   JiakResourcePOV.update(JiakResourcePOV,opts={})  -> JiakResourcePOV
+      #
+      # Updates a JiakResourcePOV on the Jiak server.
+      #
+      # See JiakResource#put for options.
+      def update(resource,opts={})
+        opts[:copy] = true
+        opts[:read] = @jiak.read_mask
+        @resource.put(resource,opts)
+      end
+
+      # :call-seq:
+      #   JiakResourcePOV.refresh(resource,opts={})  -> JiakResourcePOV
+      #
+      # Updates a JiakResource with the data on the Jiak server. The current
+      # data of the JiakResource is overwritten, so use with caution.
+      #
+      # See JiakResource#refresh for options.
+      def refresh(resource,opts={})
+        resource.jiak.object = get(resource.jiak.object.key,opts).jiak.object
+      end
+
+      # :call-seq:
+      #   JiakResourcePOV.exist?(key) -> true or false
+      #
+      # Determine if a resource exists on the Jiak server for a key.
+      def exist?(key)
+        @resource.jiak.client.exist?(@jiak.bucket,key)
+      end
+
+      # :call-seq:
+      #   JiakResourcePOV.do_auto_update(resource)  -> JiakResourcePOV or nil
+      #
+      # Determine if an auto update should be done on the resource and perform
+      # an update if so.
+      #
+      # Public method as a by-product of implementation.
+      def do_auto_update(rsrc)  # :no-doc:
+        if(rsrc.auto_update? ||
+            ((rsrc.auto_update? != false) && rsrc.class.auto_update?))
+          update(rsrc)
+        end
+      end
+
+    end
+    
+    def self.included(including_class)    # :nodoc:
+      including_class.instance_eval do
+        extend ClassMethods
+
+        def jiak  # :nodoc:
+          @jiak
+        end
+
+        @jiak = Struct.new(:bucket,:auto_update,:read_mask).new
+        @jiak.auto_update = false
+      end
+    end
+
+    # ----------------------------------------------------------------------
+    # Instance methods
+    # ----------------------------------------------------------------------
+
+    attr_reader :jiak   # :nodoc:
+
+    def initialize(jobj)    # :nodoc:
+      unless(jobj.is_a?(JiakObject))
+        # CxINC
+        raise JiakException
+      end
+      @jiak = Struct.new(:object,:auto_update).new
+      @jiak.object = jobj
+      @jiak.auto_update = false
+    end
+    # CxINC
+    # private_class_method :new
+
+    # :call-seq:
+    #   auto_update(true, false, or nil)
+    #
+    # See JiakResource#auto_update
+    def auto_update=(state)
+       unless (state.nil? || state.is_a?(TrueClass) || state.is_a?(FalseClass))
+         raise JiakResource, "auto_update must be true, false, or nil"
+       end
+     @jiak.auto_update = state
+    end
+    
+    # :call-seq:
+    #   auto_update?  -> true, false, or nil
+    #
+    # See JiakResource#auto_update?
+    def auto_update?
+      @jiak.auto_update
+    end
+
+    # :call-seq:
+    #   update(opts={})   -> nil
+    #
+    # Put this resource on the Jiak server. See JiakResource#ClassMethods#put
+    # for options.
+    def update(opts={})
+      @jiak.object = (self.class.update(self,opts)).jiak.object
+      self
+    end
+    alias :push :update
+
+    # :call-seq:
+    #   refresh(opts={})   -> nil
+    #
+    # Get this resource from the Jiak server. The current data of the resource
+    # is overwritten, so use with caution. See JiakResource#ClassMethods#get
+    # for options.
+    def refresh(opts={})
+      self.class.refresh(self,opts)
+    end
+    alias :pull :refresh
+
+    # :call-seq:
+    #   jiak_resource == other -> true or false
+    #
+    # Equality -- Two JiakResourcePOVs are equal if they wrap the same Jiak
+    # data.
+    def ==(other)
+      (@jiak.object == other.jiak.object)  rescue false
+    end
+
+    # :call-seq:
+    #    eql?(other) -> true or false
+    #
+    # Returns <code>true</code> if <code>other</code> is a JiakResourcePOV
+    # representing the same Jiak data.
+    def eql?(other)
+      other.is_a?(JiakResourcePOV) && @jiak.object.eql?(other.jiak.object)
+    end
+    
+    def hash  # :nodoc:
+      @jiak.object.hash
+    end
+
+
+  end
+end

data/lib/riakrest.rb

@@ -36,7 +36,7 @@ $:.unshift(dirname) unless
 #  class People
 #    include JiakResource
 #    server 'http://localhost:8002/jiak'
-#    jattr_accessor :name, :age
+#    attr_accessor :name, :age
 #    auto_manage
 #  end
 #
@@ -46,7 +46,7 @@ $:.unshift(dirname) unless
 #  callie = People.new(:name => 'Callie', :age => 13)
 #  remy.link(callie,'sister')
 #
-#  sisters = remy.query(People,'sister')
+#  sisters = remy.query([People,'sister'])
 #  sisters[0].eql?(callie)                             # => true
 #
 #  remy.delete
@@ -88,6 +88,7 @@ require 'riakrest/core/jiak_schema'
 require 'riakrest/core/query_link'
 
 require 'riakrest/resource/jiak_resource'
+require 'riakrest/resource/jiak_resource_pov'
 
 # Extend Array with convenience methods for comparing array contents.
 class Array   # :nodoc:

data/spec/core/jiak_client_spec.rb

@@ -3,7 +3,7 @@ require File.dirname(__FILE__) + '/../spec_helper.rb'
 class FooBarBaz  # :nodoc:
   include JiakData
 
-  jattr_accessor :foo, :bar
+  attr_accessor :foo, :bar
   require :foo
   allow   :baz
 end
@@ -44,12 +44,27 @@ describe "JiakClient" do
     no_no = lambda {JiakClient::DELETES << 'a'}
     no_no.should raise_error(StandardError,/frozen/)
 
-    no_no = lambda {JiakClient::VALID_PARAMS << 'a'}
+    no_no = lambda {JiakClient::COPY << 'a'}
     no_no.should raise_error(StandardError,/frozen/)
 
-    no_no = lambda {JiakClient::VALID_OPTS << 'a'}
+    no_no = lambda {JiakClient::READ << 'a'}
     no_no.should raise_error(StandardError,/frozen/)
-    
+
+    no_no = lambda {JiakClient::CLIENT_PARAMS << 'a'}
+    no_no.should raise_error(StandardError,/frozen/)
+
+    no_no = lambda {JiakClient::STORE_PARAMS << 'a'}
+    no_no.should raise_error(StandardError,/frozen/)
+
+    no_no = lambda {JiakClient::GET_PARAMS << 'a'}
+    no_no.should raise_error(StandardError,/frozen/)
+
+    no_no = lambda {JiakClient::DELETE_PARAMS << 'a'}
+    no_no.should raise_error(StandardError,/frozen/)
+
+    no_no = lambda {JiakClient::WALK_PARAMS << 'a'}
+    no_no.should raise_error(StandardError,/frozen/)
+
     no_no = lambda {JiakClient::KEYS << 'a'}
     no_no.should raise_error(StandardError,/frozen/)
     
@@ -340,7 +355,7 @@ end
 
 class PersonData
   include JiakData
-  jattr_accessor :name
+  attr_accessor :name
 end
 
 describe "JiakClient links" do