riakrest 0.0.1 → 0.0.2

data/lib/riakrest/resource/jiak_resource.rb

@@ -86,14 +86,12 @@ module RiakRest
 
         klass.schema.allowed_fields.each do |field|
           define_method("#{field}=") do |val|
-            @jiak.obj.data.send("#{field}=",val)
-            if(auto_update? ||
-               ((auto_update? != false) && self.class.auto_update?))
-              self.class.put(self)
-            end
+            @jiak.object.data.send("#{field}=",val)
+            self.class.do_auto_update(self)
+            val
           end
           define_method("#{field}") do
-            @jiak.obj.data.send("#{field}")
+            @jiak.object.data.send("#{field}")
           end
         end
       end
@@ -273,7 +271,8 @@ module RiakRest
       # general the values set on the Riak cluster should suffice.
       def put(resource,opts={})
         opts[:object] = true
-        resource.jiak.obj = jiak.server.store(resource.jiak.obj,opts)
+        resource.jiak.object = jiak.server.store(resource.jiak.object,opts)
+        resource.convenient_jiak
         resource
       end
 
@@ -284,7 +283,7 @@ module RiakRest
       # resource has not been previously stored. See JiakResource#put for
       # options.
       def post(resource,opts={})
-        unless(resource.jiak.obj.riak.nil?)
+        unless(resource.local?)
           raise JiakResourceException, "Resource already initially stored"
         end
         put(resource,opts)
@@ -296,7 +295,7 @@ module RiakRest
       # Updates a JiakResource on the Jiak server with a guard to ensure the
       # resource has been previously stored. See JiakResource#put for options.
       def update(resource,opts={})
-        if(resource.jiak.obj.riak.nil?)
+        if(resource.local?)
           raise JiakResourceException, "Resource not previously stored"
         end
         put(resource,opts)
@@ -311,6 +310,9 @@ module RiakRest
       # <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
       # JiakResource class, then to the value set on the Riak cluster.
+      #
+      # Raise JiakResourceNotFound if no resource exists on the Jiak server for
+      # the key.
       def get(key,opts={})
         new(jiak.server.get(jiak.bucket,key,opts))
       end
@@ -322,7 +324,7 @@ module RiakRest
       # data of the JiakResource is overwritten, so use with caution. See
       # JiakResource.get for options.
       def refresh(resource,opts={})
-        resource.jiak.obj = get(resource.jiak.obj.key,opts).jiak.obj
+        resource.jiak.object = get(resource.jiak.key,opts).jiak.object
       end
 
       # :call-seq:
@@ -336,21 +338,34 @@ module RiakRest
       # value set for the JiakResource, then to the value set on the Riak
       # cluster. In general the values set on the Riak cluster should suffice.
       def delete(resource,opts={})
-        jiak.server.delete(jiak.bucket,resource.jiak.obj.key,opts)
+        jiak.server.delete(jiak.bucket,resource.jiak.object.key,opts)
       end
 
       # :call-seq:
       #   JiakResource.link(from,to,tag)  -> JiakResource
       #
       # Link from a resource to another resource by tag.
+      #
+      # Note the resource being linked to cannot be a local object since the
+      # created link needs to include the Jiak server key. Even if a local
+      # object has a local key intended for use as the Jiak server key, there
+      # is no guarentee that key will not already be in use on the Jiak
+      # server. Only after a resource is stored on the Jiak server is the key
+      # assignment guarenteed.
+      #
+      # This restriction is not necessary for the resource being linked from,
+      # since it's Jiak server key is not in play. This does allow for
+      # establishing links to existing Jiak resources locally and storing with
+      # the initial store of the local Jiak resource.
       def link(from,to,tag)
-        link = JiakLink.new(to.jiak.obj.bucket, to.jiak.obj.key, tag)
-        unless from.jiak.obj.links.include?(link)
-          from.jiak.obj.links << link
-          if(from.auto_update? ||
-             ((from.auto_update? != false) && from.class.auto_update?))
-            put(from)
-          end
+        if(to.local?)
+          raise JiakResourceException, "Can't link to a local resource"
+        end
+
+        link = JiakLink.new(to.jiak.object.bucket, to.jiak.object.key, tag)
+        unless from.jiak.object.links.include?(link)
+          from.jiak.object.links << link
+          do_auto_update(from)
         end
         from
       end
@@ -370,10 +385,10 @@ module RiakRest
       # :call-seq:
       #   JiakResource.remove_link(from,to,tag) -> true or false
       def remove_link(from,to,tag)
-        link = JiakLink.new(to.jiak.obj.bucket, to.jiak.obj.key, tag)
-        has_link = from.jiak.obj.links.include?(link)
+        link = JiakLink.new(to.jiak.object.bucket, to.jiak.object.key, tag)
+        has_link = from.jiak.object.links.include?(link)
         if has_link
-          from.jiak.obj.links.delete(link)
+          from.jiak.object.links.delete(link)
           if(from.auto_update? ||
              ((from.auto_update? != false) && from.class.auto_update?))
             put(from)
@@ -383,7 +398,7 @@ module RiakRest
       end
       
       # :call-seq:
-      #   JiakResource.walk(from,*steps)
+      #   JiakResource.query(from,*steps)
       #
       # Retrieves an array of JiakResource objects by starting with the links
       # in the <code>from</code> JiakResource and doing the query steps. The
@@ -394,10 +409,10 @@ module RiakRest
       #
       # ====Usage
       # <code>
-      #   JiakResource.walk(resource,Child,'child')
-      #   JiakResource.walk(resource,Parent,'odd',Child,'normal')
+      #   JiakResource.query(resource,Child,'child')
+      #   JiakResource.query(resource,Parent,'odd',Child,'normal')
       # </code>
-      def walk(from,*steps)
+      def query(from,*steps)
         links = []
         until steps.empty?
           begin
@@ -411,22 +426,37 @@ module RiakRest
           end
         end
         links = links[0]  if links.size == 1
-        jiak.server.walk(from.jiak.obj.bucket, from.jiak.obj.key, links,
+        jiak.server.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
       
+      # :call-seq:
+      #   JiakResource.exist?(key) -> true or false
+      #
+      # Determine if a resource exists on the Jiak server for a key.
+      def exist?(key)
+        begin
+          get(key)
+          true
+        rescue JiakResourceNotFound
+          false
+        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>.
+      # <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]
+        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}"
@@ -435,11 +465,30 @@ module RiakRest
         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]
+          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
+      #
+      # 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.local? &&
+           (rsrc.auto_update? ||
+            ((rsrc.auto_update? != false) && rsrc.class.auto_update?)))
+          update(rsrc)
         end
       end
 
@@ -471,18 +520,32 @@ module RiakRest
     # is passed to the <code>new</code> method of the JiakData associated
     # with the JiakResource.
     def initialize(*args)
-      # First form is used by JiakResource.get and JiakResource.walk
-      @jiak = Struct.new(:obj,:auto_update).new
+      # First form is used by JiakResource.get and JiakResource.query
+      @jiak = Struct.new(:object,:bucket,:key,:data,:links,:auto_update).new
       if(args.size == 1 && args[0].is_a?(JiakObject))
-        @jiak.obj = args[0]
+        @jiak.object = args[0]
       else
         bucket = self.class.jiak.bucket
-        @jiak.obj = JiakObject.new(:bucket => bucket,
-                                   :data => bucket.data_class.new(*args))
+        @jiak.object = JiakObject.new(:bucket => bucket,
+                                      :data => bucket.data_class.new(*args))
         if(self.class.auto_post?)
+          if(!@jiak.object.key.empty? && self.class.exist?(@jiak.object.key))
+            raise(JiakResourceException,
+                  "auto-post failed: key='#{@jiak.object.key}' already exists.")
+          end
           self.class.post(self)
         end
       end
+      convenient_jiak
+    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:
+      @jiak.bucket = @jiak.object.bucket
+      @jiak.key    = @jiak.object.key
+      @jiak.data   = @jiak.object.data
+      @jiak.links  = @jiak.object.links
     end
 
     # :call-seq:
@@ -518,7 +581,8 @@ module RiakRest
     # Put this resource on the Jiak server. See JiakResource#ClassMethods#put
     # for options.
     def put(opts={})
-      @jiak.obj = (self.class.put(self,opts)).jiak.obj
+      @jiak.object = (self.class.put(self,opts)).jiak.object
+      convenient_jiak
       self
     end
 
@@ -529,7 +593,8 @@ module RiakRest
     # has not been previously stored. See JiakResource#ClassMethods#put for
     # options.
     def post(opts={})
-      @jiak.obj = (self.class.post(self,opts)).jiak.obj
+      @jiak.object = (self.class.post(self,opts)).jiak.object
+      convenient_jiak
       self
     end
 
@@ -540,9 +605,11 @@ module RiakRest
     # has been previously stored. See JiakResource#ClassMethods#put for
     # options.
     def update(opts={})
-      @jiak.obj = (self.class.update(self,opts)).jiak.obj
+      @jiak.object = (self.class.update(self,opts)).jiak.object
+      convenient_jiak
       self
     end
+    alias :push :update
 
     # :call-seq:
     #   refresh(opts={})   -> nil
@@ -551,7 +618,18 @@ module RiakRest
     # is overwritten, so use with caution. See JiakResource#ClassMethods#get
     # for options.
     def refresh(opts={})
-      self.class.refresh!(self,opts)
+      self.class.refresh(self,opts)
+    end
+    alias :pull :refresh
+
+    # :call-seq:
+    #   local? -> true or false
+    #
+    # <code>true</code> if a resource is local only, i.e., has not been
+    # post/put to the Jiak server. This test is used in the guards for class
+    # and instance level post/update methods.
+    def local?
+      jiak.object.riak.nil?
     end
 
     # :call-seq:
@@ -566,7 +644,9 @@ module RiakRest
     # :call-seq:
     #   link(resource,tag) -> JiakResource
     #
-    # Link to the resource by tag.
+    # Link to the resource by tag. Note the resource being linked to cannot be
+    # local. The object creating this link can be local. See JiakResource#link
+    # for a discussion.
     def link(resource,tag)
       self.class.link(self,resource,tag)
     end
@@ -589,39 +669,40 @@ module RiakRest
     end
 
     # :call-seq:
-    #   walk(*steps) -> array
+    #   query(*steps) -> array
     #
-    # Performs a Jiak walk starting at this resource. See
-    # JiakResource#ClassMethods#walk for description.
+    # Performs a Jiak query starting at this resource. See
+    # JiakResource#ClassMethods#query for description.
     #
     # ====Usage
     # <code>
-    #   walk(Child,'child')
-    #   walk(Parent,'odd',Child,'normal')
+    #   query(Child,'child')
+    #   query(Parent,'odd',Child,'normal')
     # </code>
-    def walk(*steps)
-      self.class.walk(self,*steps)
+    def query(*steps)
+      self.class.query(self,*steps)
     end
+    alias :walk :query
 
-    # call-seq:
-    #    jiak_resource == other -> true or false
+    # :call-seq:
+    #   jiak_resource == other -> true or false
     #
     # Equality -- Two JiakResources are equal if they wrap the same data.
     def ==(other)
-      (@jiak.obj == other.jiak.obj)  rescue false
+      (@jiak.object == other.jiak.object)  rescue false
     end
 
-    # call-seq:
+    # :call-seq:
     #    eql?(other) -> true or false
     #
     # Returns <code>true</code> if <code>other</code> is a JiakResource
     # representing the same Jiak data.
     def eql?(other)
-      other.is_a?(JiakResource) && @jiak.obj.eql?(other.jiak.obj)
+      other.is_a?(JiakResource) && @jiak.object.eql?(other.jiak.object)
     end
     
     def hash  # :nodoc:
-      @jiak.obj.hash
+      @jiak.object.hash
     end
 
   end

data/lib/riakrest/version.rb

@@ -1,5 +1,5 @@
 module RiakRest
-  VERSION         = '0.0.1'
+  VERSION         = '0.0.2'
   VERSION_ARRAY   = VERSION.split(/\./).map { |x| x.to_i } # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/riakrest.rb

@@ -84,7 +84,7 @@ $:.unshift(File.dirname(__FILE__)) unless
 # </code>
 # Now we can get callie as the sister of remy:
 # <code>
-#   sisters = client.walk(bucket,remy.key,QueryLink.new(bucket,'sister'),Person)
+#   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.
@@ -99,35 +99,38 @@ $:.unshift(File.dirname(__FILE__)) unless
 # 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>
-#   require 'riakrest'
-#   include RiakRest
-#   
-#   PersonData = JiakDataHash.create(:name,:age)
-#   PersonData.keygen :name
-#   
-#   class Person
-#     include JiakResource
-#     server      'http://localhost:8002/jiak'
-#     group       'people'
-#     data_class  PersonData
-#   end
-#   
-#   remy = Person.new(:name => 'remy', :age => 10)
-#   remy.post
-#   puts Person.get('remy').name                # => "remy"
-#   
-#   remy.name = "Remy"
-#   remy.update
-#   puts Person.get('remy').name                # => "Remy"
-#   
-#   callie = Person.new(:name => 'Callie', :age => 12).post
-#   remy.link(callie,'sister').update
-#   
-#   sisters = remy.walk(Person,'sister')
-#   sisters[0].eql?(callie)                     # => true
-#   
-#   remy.delete
-#   callie.delete
+#  require 'riakrest'
+#  include RiakRest
+# 
+#  PersonData = JiakDataHash.create(:name,:age)
+#  PersonData.keygen :name
+# 
+#  class Person
+#    include JiakResource
+#    server      'http://localhost:8002/jiak'
+#    group       'people'
+#    data_class  PersonData
+#    auto_post   true
+#    auto_update true
+#  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)
+#
+#  callie = Person.new(:name => 'Callie', :age => 13)
+#  remy.link(callie,'sister')
+#
+#  sisters = remy.query(Person,'sister')
+#  puts sisters[0].eql?(callie)                  # => true
+#
+#  remy.delete
+#  callie.delete
 # </code>
 # Ah, that feels better. Go forth and Riak!
 module RiakRest