riakrest 0.0.4 → 0.1.0

data/lib/riakrest/resource/jiak_resource.rb

@@ -1,27 +1,37 @@
 module RiakRest
-  # JiakResource provides a resource-oriented wrapper for Jiak interaction. See
-  # RiakRest for a basic usage example.
+  # JiakResource provides a resource-oriented wrapper for Jiak interaction.
+  #
+  # ===Example
+  #  require 'riakrest'
+  #  include RiakRest
+  #
+  #  class People
+  #    include JiakResource
+  #    server 'http://localhost:8002/jiak'
+  #    jattr_accessor :name, :age
+  #    auto_manage
+  #  end
+  #
+  #  remy = People.new(:name => 'Remy',:age => 10)       # (auto-post)
+  #  remy.age = 11                                       # (auto-update)
+  #
+  #  callie = People.new(:name => 'Callie', :age => 13)
+  #  remy.link(callie,'sister')
+  #
+  #  sisters = remy.query(People,'sister')
+  #  sisters[0].eql?(callie)                             # => true
+  #
+  #  remy.delete
+  #  callie.delete
   
   module JiakResource
     # ----------------------------------------------------------------------
     # Class methods
     # ----------------------------------------------------------------------
     
-    # Class methods for creating a user-defined JiakResource. The methods
-    # <code>server</code>, <code>group</code> and <code>data_class</code> are
-    # mandatory to create a fully usable JiakResource.
+    # Class methods for creating a user-defined JiakResource.
     #
-    # ===Usage
-    # <code>
-    #   class Dog
-    #     include JiakResource
-    #
-    #     server      'http://localhost:8002/jiak'
-    #     group       'dogs'
-    #     data_class  DogData
-    #   end
-    # </code>
-    # 
+    # See JiakResource for example usage.
     module ClassMethods
 
       # :call-seq:
@@ -33,9 +43,8 @@ module RiakRest
       # Valid options:
       #  <code>:proxy</code> Proxy server URI.
       def server(uri,opts={})
-        jiak.uri = uri
         jiak.server = JiakClient.new(uri,opts)
-        uri
+        jiak.uri = uri
       end
 
       # :call-seq:
@@ -43,63 +52,64 @@ module RiakRest
       #
       # Set the Jiak group name for the storage area of a resource.
       def group(gname)
-        if(jiak.bucket.nil?)
-          unless(jiak.data.nil?)
-            create_jiak_bucket(gname,jiak.data)
-          else
-            jiak.group = gname
-          end
-        else
-          jiak.bucket.name = gname
-        end
+        jiak.group = gname
+        jiak.bucket.name = gname
       end
 
       # :call-seq:
-      #   JiakResource.data_class(klass)
-      #
-      # Set the resource Jiak data class.
-      def data_class(klass)
-        if(jiak.bucket.nil?)
-          unless(jiak.group.nil?)
-            create_jiak_bucket(jiak.group,klass)
-          else
-            jiak.data = klass
+      #   jattr_reader :f1,...,:fn
+      #
+      # Add read accessible fields.
+      def jattr_reader(*fields)
+        check_fields(fields)
+        added_fields = jiak.data.readable(*fields)
+        added_fields.each do |field|
+          define_method("#{field}") do
+            @jiak.data.send("#{field}")
           end
-        else
-          old_klass = jiak.bucket.data_class
-          jiak.bucket.data_class = klass
-          create_field_accessors(klass,old_klass)
         end
+        nil
       end
-        
-      def create_jiak_bucket(gname,klass)   # :nodoc:
-        jiak.bucket = JiakBucket.new(gname,klass)
-        jiak.group = jiak.bucket.name
-        jiak.data = klass
-        create_field_accessors(klass)
-      end
-      private :create_jiak_bucket
-        
-      def create_field_accessors(klass,old_klass=nil)
-        if(old_klass)
-          klass.schema.allowed_fields.each do |field|
-            remove_method(field)
-            remove_method("#{field}=")
-          end
-        end
+      alias :jattr :jattr_reader
 
-        klass.schema.allowed_fields.each do |field|
+      # :call-seq:
+      #   jattr_writer :f1,...,:fn
+      #
+      # Add write accessible fields.
+      def jattr_writer(*fields)
+        check_fields(fields)
+        added_fields = jiak.data.writable(*fields)
+        added_fields.each do |field|
           define_method("#{field}=") do |val|
-            @jiak.object.data.send("#{field}=",val)
+            @jiak.data.send("#{field}=",val)
             self.class.do_auto_update(self)
-            val
-          end
-          define_method("#{field}") do
-            @jiak.object.data.send("#{field}")
           end
         end
+        nil
+      end
+
+      # :call-seq:
+      #   jattr_accessor :f1,...,:fn
+      #
+      # Add read/write accessible fields.
+      def jattr_accessor(*fields)
+        jattr_reader *fields
+        jattr_writer *fields
+      end
+
+      def check_fields(fields)
+        if(fields.include?(:jiak) || fields.include?('jiak'))
+          raise(JiakResourceException,
+                "'jiak' reserved for RiakRest Resource usage")
+        end
+      end
+      private :check_fields
+
+      def keygen(&block)
+        jiak.data.class_eval <<-EOS
+          define_method(:keygen,&block)
+        EOS
       end
-      private :create_jiak_bucket, :create_field_accessors
 
       # :call-seq:
       #   JiakResource.params(opts={})  -> hash
@@ -119,16 +129,18 @@ module RiakRest
       # set on the Riak cluster should suffice and these parameters aren't
       # necessary for Jiak interaction.
       def params(opts={})
-        jiak.bucket.params = opts
+        jiak.server.params = opts
       end
 
       # :call-seq:
       #   JiakResource.auto_post(state)  -> true or false
       #
       # Set <code>true</code> to have new instances of the resource auto-posted
-      # to the Jiak server. Default is <code>false</code>.
-      def auto_post(state)
-        state = false  if state.nil?
+      # to the Jiak server.
+      #
+      # Default value for state is <code>true</code>. Note the default behavior
+      # for JiakResource is auto-post false.
+      def auto_post(state=true)
         unless (state.is_a?(TrueClass) || state.is_a?(FalseClass))
           raise JiakResource, "auto_post must be true or false"
         end
@@ -147,10 +159,12 @@ module RiakRest
       #   JiakResource.auto_update(state)  -> true or false
       #
       # Set <code>true</code> to have changes to resource fields or links
-      # trigger an auto-update to the Jiak server. Default is
-      # <code>false</code>. Interacts with the instance-level resource
-      # setting. See JiakResource#auto_update.
-      def auto_update(state)
+      # trigger an auto-update to the Jiak server. Interacts with the
+      # instance-level resource setting. See JiakResource#auto_update.
+      #
+      # Default value for state is <code>true</code>. Note the default behavior
+      # for JiakResource is auto-update false.
+      def auto_update(state=true)
         state = false  if state.nil?
         unless (state.is_a?(TrueClass) || state.is_a?(FalseClass))
           raise JiakResource, "auto_update must be true or false"
@@ -167,79 +181,30 @@ module RiakRest
       end
 
       # :call-seq:
-      #   JiakResource.schema  -> JiakSchema
-      #
-      # Get the schema for a resource.
-      def schema
-        jiak.bucket.schema
-      end
-
-      # :call-seq:
-      #   JiakResource.keys   -> array
+      #   JiakResource.auto_manage(state)  -> true or false
       #
-      # 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
-        jiak.server.keys(jiak.bucket)
+      # Set auto-post and auto-manage simultaneously.
+      def auto_manage(state=true)
+        auto_post state
+        auto_update state
       end
 
       # :call-seq:
-      #   JiakResource.allowed(:f1,...,:fn)  -> JiakSchema
-      #
-      # Set the allowed fields for the schema of a resource.
-      #
-      # Returns the altered JiakSchema.
-      def allowed(*fields)
-        jiak.bucket.schema.allowed_fields = *fields
-        jiak.bucket.schema
-      end
-
-      # :call-seq:
-      #   JiakResource.required(:f1,...,:fn)  -> JiakSchema
-      #
-      # Sets the required fields for the schema of a resource.
-      #
-      # Returns the altered JiakSchema.
-      def required(*fields)
-        jiak.bucket.schema.required_fields = *fields
-        jiak.bucket.schema
-      end
-
-      # :call-seq:
-      #   JiakResource.readable(:f1,...,:fn)  -> JiakSchema
-      #
-      # Sets the readable fields for the schema of a resource.
+      #   JiakResource.auto_update? -> true or false
       #
-      # Returns the altered JiakSchema.
-      def readable(*fields)
-        jiak.bucket.schema.read_mask = *fields
-        jiak.bucket.schema
+      # <code>true</code> if JiakResource is set to auto-update.
+      def auto_manage?
+        return auto_post? && auto_update?
       end
 
       # :call-seq:
-      #   JiakResource.writable(:f1,...,:fn)  -> JiakSchema
-      #
-      # Sets the writable fields for the schema of a resource.
+      #   JiakResource.schema  -> JiakSchema
       #
-      # Returns the altered JiakSchema.
-      def writable(*fields)
-        jiak.bucket.schema.write_mask = *fields
-        jiak.bucket.schema
+      # Get the schema for a resource.
+      def schema
+        jiak.data.schema
       end
 
-      # :call-seq:
-      #   JiakResource.readwrite(:f1,...,:fn)  -> JiakSchema
-      # 
-      # Set the readable and writable fields for the schema of a resource.
-      #
-      # Returns the altered JiakSchema
-      def readwrite(*fields)
-        jiak.bucket.schema.readwrite  = *fields
-        jiak.bucket.schema
-      end
-      
-      # :call-seq:
       #   JiakResource.point_of_view  -> JiakSchema
       #
       # Ready the Jiak server point-of-view to accept structured interaction
@@ -260,6 +225,16 @@ module RiakRest
       end
       alias :pov? :point_of_view?
 
+      # :call-seq:
+      #   JiakResource.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
+        jiak.server.keys(jiak.bucket)
+      end
+
       # :call-seq:
       #   JiakResource.put(JiakResource,opts={})  -> JiakResource
       #
@@ -276,7 +251,7 @@ module RiakRest
       def put(resource,opts={})
         opts[:return] = :object
         resource.jiak.object = jiak.server.store(resource.jiak.object,opts)
-        resource.convenient_jiak
+        resource.jiak_convenience
         resource
       end
 
@@ -450,37 +425,6 @@ module RiakRest
         end
       end
 
-      # :call-seq:
-      #   copy(opts={}) -> JiakResource
-      #
-      # Copies a JiakResource, resetting values passed as options. Valid
-      # options on copy are those mandatory to create a JiakResource:
-      # <code>:server</code>, <code>:group</code>, and
-      # <code>:data_class</code>, and optional auto flags
-      # <code>auto_post</code> and <code>auto_update</code>.
-      #   
-      def copy(opts={})
-        valid = [:server,:group,:data_class,:auto_post,:auto_update]
-        err = opts.select {|k,v| !valid.include?(k)}
-        unless err.empty?
-          raise JiakResourceException, "unrecognized options: #{err.keys}"
-        end
-
-        opts[:server] ||= jiak.server.uri
-        opts[:group] ||= jiak.bucket.name
-        opts[:data_class] ||= jiak.bucket.data_class
-        opts[:auto_post] ||= auto_post?
-        opts[:auto_update] ||= auto_update?
-        Class.new do
-          include JiakResource
-          server      opts[:server]
-          group       opts[:group]
-          data_class  opts[:data_class]
-          auto_post   opts[:auto_post]
-          auto_update opts[:auto_update]
-        end
-      end
-
       # :call-seq:
       #   JiakResource.do_auto_update(resource)  -> JiakResource or nil
       #
@@ -506,6 +450,10 @@ module RiakRest
         end
         @jiak = Struct.new(:server,:uri,:group,:data,:bucket,
                            :auto_post,:auto_update).new
+        @jiak.data = JiakDataFields.create
+        @jiak.group = self.name.split('::').last.downcase
+        @jiak.bucket = JiakBucket.new(@jiak.group,@jiak.data)
+        
         @jiak.auto_post = false
         @jiak.auto_update = false
       end
@@ -540,12 +488,12 @@ module RiakRest
           self.class.post(self)
         end
       end
-      convenient_jiak
+      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 convenient_jiak     # :nodoc:
+    def jiak_convenience     # :nodoc:
       @jiak.bucket = @jiak.object.bucket
       @jiak.key    = @jiak.object.key
       @jiak.data   = @jiak.object.data
@@ -586,7 +534,7 @@ module RiakRest
     # for options.
     def put(opts={})
       @jiak.object = (self.class.put(self,opts)).jiak.object
-      convenient_jiak
+      jiak_convenience
       self
     end
 
@@ -598,7 +546,7 @@ module RiakRest
     # options.
     def post(opts={})
       @jiak.object = (self.class.post(self,opts)).jiak.object
-      convenient_jiak
+      jiak_convenience
       self
     end
 
@@ -610,7 +558,7 @@ module RiakRest
     # options.
     def update(opts={})
       @jiak.object = (self.class.update(self,opts)).jiak.object
-      convenient_jiak
+      jiak_convenience
       self
     end
     alias :push :update

data/lib/riakrest.rb

@@ -21,118 +21,39 @@ $:.unshift(dirname) unless
   $:.include?(dirname) || 
   $:.include?(File.expand_path(dirname))
 
-# RiakRest provides structured, RESTful interaction with a Riak document
-# store. In Riak parlance, this JSON data exchange is called Jiak. RiakRest
-# provides two levels of interaction: Core Client and Resource. Core Client
-# interaction works down at the Jiak level and so exposes Jiak
-# internals. Resource interaction abstracts above that and is much easier to
-# use. But we'll show the Core Client first since Resource is built on top of
-# it.
+# RiakRest provides structured, RESTful interaction with a Riak document data
+# store. In Riak parlance, the HTTP/JSON interface to a Riak cluster is called
+# Jiak. RiakRest provides two levels of Jiak interaction: Core Client and
+# Resource. Core Client works directly with the Jiak level, whereas Resource is
+# a resource-oriented abstraction on top of Core Client.
 #
-# ===Core Client Interaction
-# Primary Jiak constructs are represented by core Jiak classes:
-# JiakClient :: Client used to make Jiak store, get, delete, and other calls.
-# JiakBucket :: Bucket name and the data class stored in the bucket.
-# JiakSchema :: Schema used by a Jiak server bucket.
-# JiakData :: Class to define user data to be stored on a Jiak server.
-# JiakObject :: Jiak object wrapper that includes the user-defined data.
-# JiakLink :: Jiak link objects for associations between Jiak server data.
-# QueryLink :: Link objects to query Jiak link associations.
-#
-# ====Example Usage
-# This example works at the Jiak core layer. See the Resource example below for
-# an abstraction layered on top of this core.
-# <code>
-#   require 'riakrest'
-#   include RiakRest
-# </code>
-# Create a simple class to hold Person data.
-# <code>
-#   Person = JiakDataHash.create(:name,:age)
-# </code>
-# Create a client, a bucket to hold the data, and set the bucket schema for
-# structured interaction.
-# <code>
-#   client = JiakClient.new("http://localhost:8002/jiak")
-#   bucket = JiakBucket.new('person',Person)
-#   client.set_schema(bucket)
-# </code>
-# Wrap a Person data object in a JiakObject and store it. Check the data on the
-# server to see it's really there.
-# <code>
-#   remy = client.store(JiakObject.new(:bucket => bucket,
-#                                      :data => Person.new(:name => "remy",
-#                                                           :age => 10)),
-#                       :object => true)
-#   puts client.get(bucket,remy.key).data.name         # => "remy"
-# </code>
-# Change the data via accessors and update. Again, we print the server value.
-# <code>
-#   remy.data.name                                     # => "remy"
-#   remy.data.name = "Remy"
-#   client.store(remy)
-#   puts client.get(bucket,remy.key).data.name         # => "Remy"
-# </code>
-# Let's add another person and a link between them.
-# <code>
-#   callie = client.store(JiakObject.new(:bucket => bucket,
-#                                        :data => Person.new(:name => "Callie",
-#                                                            :age => 12)),
-#                         :object => true)
-#   remy << JiakLink.new(bucket,callie.key,'sister')
-#   client.store(remy)
-# </code>
-# Now we can get callie as the sister of remy:
-# <code>
-#   sisters = client.query(bucket,remy.key,QueryLink.new(bucket,'sister'),Person)
-#   sisters[0].eql?(callie)                           # => true
-# </code>
-# Finally, we'll delete the objects on the way out the door.
-# <code>
-#   client.delete(bucket,remy.key)
-#   client.delete(bucket,callie.key)
-# </code>
-#
-# ===Resource Interaction
-# Much of the above code can be abstracted into resource-based
-# interaction. RiakRest provides a module JiakResource that allows you to
-# create resource objects that encapsulate a lot of the cruft of core client
-# interaction. We'll do the same steps as above using resources.
-# <code>
+# ===Example
 #  require 'riakrest'
 #  include RiakRest
-# 
-#  PersonData = JiakDataHash.create(:name,:age)
-#  PersonData.keygen :name
-# 
-#  class Person
+#
+#  class People
 #    include JiakResource
-#    server      'http://localhost:8002/jiak'
-#    group       'people'
-#    data_class  PersonData
-#    auto_post   true
-#    auto_update true
+#    server 'http://localhost:8002/jiak'
+#    jattr_accessor :name, :age
+#    auto_manage
 #  end
-# 
-#  remy = Person.new(:name => 'remy',:age => 10) #            (auto-post)
-#  puts remy.name                                # => "remy"  (auto-update)
-# 
-#  puts Person.get('remy').name                  # => "remy"  (from Jiak server)
-#  puts Person.get('remy').age                   # => 10      (from Jiak server)
 #
-#  remy.age = 11                                 #            (auto-update)
-#  puts Person.get('remy').age                   # => 11      (from Jiak server)
+#  remy = People.new(:name => 'Remy',:age => 10)       # (auto-post)
+#  remy.age = 11                                       # (auto-update)
 #
-#  callie = Person.new(:name => 'Callie', :age => 13)
+#  callie = People.new(:name => 'Callie', :age => 13)
 #  remy.link(callie,'sister')
 #
-#  sisters = remy.query(Person,'sister')
-#  puts sisters[0].eql?(callie)                  # => true
+#  sisters = remy.query(People,'sister')
+#  sisters[0].eql?(callie)                             # => true
 #
 #  remy.delete
 #  callie.delete
-# </code>
-# Ah, that feels better. Go forth and Riak!
+#
+# ===Core Client
+# See JiakClient for Core Client example.
+#
+# Go forth and Riak!
 module RiakRest
   version_file = File.join(File.dirname(__FILE__),"..","VERSION")
   VERSION = IO.read(version_file).chomp
@@ -140,7 +61,7 @@ module RiakRest
   # Convenience method for checking validity of method options. If any of the
   # options in opt are not in valid, raise the exception with the invalid
   # options in the message.
-  def check_opts(opts,valid,exception)
+  def check_opts(opts,valid,exception)              # :nodoc:
     err = opts.select {|k,v| !valid.include?(k)}
     unless err.empty?
       raise exception, "unrecognized options: #{err.keys}"
@@ -153,16 +74,16 @@ require 'riakrest/core/exceptions'
 require 'riakrest/core/jiak_bucket'
 require 'riakrest/core/jiak_client'
 require 'riakrest/core/jiak_data'
+require 'riakrest/core/jiak_data_fields'
 require 'riakrest/core/jiak_link'
 require 'riakrest/core/jiak_object'
 require 'riakrest/core/jiak_schema'
 require 'riakrest/core/query_link'
 
-require 'riakrest/data/jiak_data_hash'
 require 'riakrest/resource/jiak_resource'
 
 # Extend Array with convenience methods for comparing array contents.
-class Array
+class Array   # :nodoc:
   # Compare arrays for same elements regardless of order.
   def same_elements?(arr)
     raise ArgumentError unless arr.is_a?(Array)

data/spec/core/jiak_bucket_spec.rb

@@ -1,53 +1,43 @@
 require File.dirname(__FILE__) + '/../spec_helper.rb'
 
+F1F2 = JiakDataFields.create :f1, :f2
+G1   = JiakDataFields.create :g1
+
 describe "JiakBucket" do
   before do
     @name = 'bucket_name'
-    @data_class = JiakDataHash.create(:f1,:f2)
-    @params = {:reads => 1, :writes => 2, :durable_writes => 3, :waits => 4}
+    @data_class = F1F2
     @bucket = JiakBucket.new(@name,@data_class)
   end
 
   it "should respond to" do
-    @bucket.should respond_to(:name,:data_class,:params,:schema)
-    @bucket.should respond_to(:name=,:data_class=,:params=)
+    @bucket.should respond_to(:name,:data_class,:schema)
+    @bucket.should respond_to(:name=,:data_class=)
     @bucket.should respond_to(:eql?)
   end
 
   it "should initialize with name and data class" do
     @bucket.name.should eql @name
     @bucket.data_class.should eql @data_class
-    @bucket.params.should be_empty
   end
 
-  it "should initialize with name, data class, and params" do
-    bucket = JiakBucket.new(@name,@data_class,@params)
+  it "should initialize with name and data class" do
+    bucket = JiakBucket.new(@name,@data_class)
     bucket.name.should eql @name
     bucket.data_class.should eql @data_class
-    bucket.params.should have_exactly(4).items
-    @params.each {|k,v| bucket.params[k].should == @params[k]}
-
-    @params.delete(:writes)
-    bucket = JiakBucket.new(@name,@data_class,@params)
-    bucket.params.should have_exactly(3).items
-    bucket.params[:waits].should == @params[:waits]
   end
 
-  it "should update the name,data class, and params" do
-    # name = 'new_bucket_name'
-    # @bucket.name = name
-    # @bucket.name.should eql name
+  it "should update the name and data class" do
+    name = 'new_bucket_name'
+    @bucket.name = name
+    @bucket.name.should eql name
 
-    data_class = JiakDataHash.create(:g1)
+    data_class = G1
     @bucket.data_class = data_class
     @bucket.data_class.should eql data_class
-
-    @bucket.params.should be_empty
-    @bucket.params = @params
-    @bucket.params.should eql @params
   end
 
-  it "should validate name, data class, and params" do
+  it "should validate name and data class" do
     empty_name = lambda {JiakBucket.new("",@data_class)}
     empty_name.should raise_error(JiakBucketException,/Name.*empty/)
 
@@ -62,15 +52,6 @@ describe "JiakBucket" do
 
     bad_data_class = lambda {@bucket.data_class = Hash}
     bad_data_class.should raise_error(JiakBucketException,/JiakData/)
-
-    params = @params
-    params.delete(:writes)
-    params[:write] = 2
-    bad_params = lambda {JiakBucket.new(@name,@data_class,params)}
-    bad_params.should raise_error(JiakBucketException,/params/)
-
-    bad_params = lambda {@bucket.params = params}
-    bad_params.should raise_error(JiakBucketException,/params/)
   end
 
   it "should provide the schema for the data class" do
@@ -84,20 +65,9 @@ describe "JiakBucket" do
     bucket = JiakBucket.new(@name.upcase,@data_class)
     bucket.should_not eql @bucket
 
-    data_class = JiakDataHash.create(:g1)
+    data_class = G1
     bucket = JiakBucket.new(@name,data_class)
     bucket.should_not eql @bucket
-
-    bucket = JiakBucket.new(@name,@data_class,@params)
-    bucket.should_not eql @bucket
-
-    @bucket.params = @params
-    bucket.should eql @bucket
-
-    params = {:reads => @params[:reads]+1}
-    bucket_1 = JiakBucket.new(@name,@data_class,@params)
-    bucket_2 = JiakBucket.new(@name,@data_class,params)
-    bucket_1.should_not eql bucket_2
   end
 
 end