riakrest 0.1.0 → 0.1.2

data/lib/riakrest/core/jiak_schema.rb

@@ -16,6 +16,9 @@ module RiakRest
   # already stored by Jiak. Schema designations only affect structured Jiak
   # interaction, not the data itself.
   #
+  # At this time, Riak does not support concurrent bucket access with different
+  # schemas, so the bucket interactions is semi-static.
+  #
   # The fields are kept as symbols or strings in four attribute arrays:
   # <code>allowed_fields</code>:: Allowed in Jiak interaction.
   # <code>required_fields</code>:: Required during Jiak interaction.
@@ -26,6 +29,13 @@ module RiakRest
   # not meaningful, including a symbol that "equals" a string. Duplicates
   # fields are ignored.
   #
+  # Riak supports wild cards in schemas. The wild card is specified using the
+  # constant JiakSchema::WILDCARD. The constant JiakSchema::WIDE_OPEN specifies
+  # a wide open schema with allowed_fields, read_mask, and write_mask all set
+  # to JiakSchema::WILDCARD, and required_fields set to an empty array. The
+  # wide open schema allows the least restricted interaction with Jiak server
+  # data. An initially created Riak bucket has the wide open schema setting.
+  #
   # ===Usage
   # <pre>
   #   schema = JiakSchema.new([:foo,:bar])
@@ -42,6 +52,10 @@ module RiakRest
   # </pre>
   class JiakSchema
 
+    # Wild card constant.
+    WILDCARD = "*"
+    WILDCARD.freeze
+
     attr_accessor :allowed_fields, :required_fields, :read_mask, :write_mask
 
     # call-seq:
@@ -108,6 +122,16 @@ module RiakRest
           :read_mask       => arg,
           :write_mask      => arg
         }
+      when String
+        unless(arg.eql?(WILDCARD))
+          raise JiakSchemaException, "Initialize string can only be WILDCARD"
+        end
+        opts = {
+          :allowed_fields  => WILDCARD,
+          :required_fields => [],
+          :read_mask       => WILDCARD,
+          :write_mask      => WILDCARD
+        }
       when nil
         arr = []
         opts = {
@@ -117,15 +141,20 @@ module RiakRest
           :write_mask      => arr
         }
       else
-        raise JiakSchemaException, "Initialize arg must be either hash or array"
+        raise JiakSchemaException, "Illegal initialize arg"
       end
-
+      
+      # Dup to protect internal arrays from those passed into initialize
       @allowed_fields  = opts[:allowed_fields].dup
       @required_fields = opts[:required_fields].dup
       @read_mask       = opts[:read_mask].dup
       @write_mask      = opts[:write_mask].dup
     end
 
+    # Wide open schema constant.
+    WIDE_OPEN = JiakSchema.new(WILDCARD)
+    WIDE_OPEN.freeze
+
     # call-seq:
     #    JiakSchema.from_json(json)  -> JiakSchema
     #
@@ -200,18 +229,20 @@ module RiakRest
     #   allow(:f1,...,:fn) -> array
     #   allow([:f1,...,:fn]) -> array
     #
-    # Add to the allowed fields array.
+    # Add to the allowed fields array. Overwrites JiakSchema::WILDCARD array.
     #
     # Returns fields added to allowed fields.
     def allow(*fields)
-      add_fields(@allowed_fields,"allow",fields)
+      added_fields = add_fields(@allowed_fields,"allow",fields)
+      @allowed_fields = added_fields  if(@allowed_fields.eql?(WILDCARD))
+      added_fields
     end
 
     # :call-seq:
     #   require(:f1,...,:fn) -> array
     #   require([:f1,...,:fn]) -> array
     #
-    # Add fields to the required fields array.  Adds the fields to the allowed
+    # Add fields to the required fields array. Adds the fields to the allowed
     # fields as well.
     #
     # Returns fields added to required_fields.
@@ -226,12 +257,13 @@ module RiakRest
     #   readable([:f1,...,:fn]) -> array
     #
     # Add fields to the read mask array.  Adds the fields to the allowed
-    # fields as well.
+    # fields as well. Overwrites JiakSchema::WILDCARD arrays.
     #
     # Returns fields added to read_mask
     def readable(*fields)
       added_fields = add_fields(@read_mask,"readable",fields)
       allow(*fields)
+      @read_mask = added_fields if(@read_mask.eql?(WILDCARD))
       added_fields
     end
 
@@ -240,12 +272,13 @@ module RiakRest
     #   writable([:f1,...,:fn]) -> array
     #
     # Add fields to the write mask array.  Adds the fields to the allowed
-    # fields as well.
+    # fields as well. Overwrites JiakSchema::WILDCARD arrays.
     #
     # Returns fields added to write_mask
     def writable(*fields)
       added_fields = add_fields(@write_mask,"writable",fields)
       allow(*fields)
+      @write_mask = added_fields if(@write_mask.eql?(WILDCARD))
       added_fields
     end
 
@@ -254,7 +287,7 @@ module RiakRest
     #   readwrite([:f1,...,:fn]) -> nil
     #
     # Add fields to the read and write mask arrays. Adds the fields to the
-    # allowed fields as well.
+    # allowed fields as well. Overwrites JiakSchema::WILDCARD arrays.
     #
     # Returns nil.
     def readwrite(*fields)
@@ -269,7 +302,11 @@ module RiakRest
     def add_fields(arr,descr,fields)
       fields = fields[0] if(fields.size == 1 && fields[0].is_a?(Array))
       scrubbed = transform_fields(descr,fields)
-      (scrubbed - arr).each {|f| arr << f}
+      if(arr.eql?(WILDCARD))
+        arr = scrubbed
+      else
+        (scrubbed - arr).each {|f| arr << f}
+      end
     end
     private :add_fields
 
@@ -317,58 +354,65 @@ module RiakRest
     #    schema == other -> true or false
     #
     # Equality -- Two schemas are equal if they contain the same array elements
-    # for all attributes, irrespective of order.
+    # for all attributes, regardless of order.
     def ==(other)
-      (@allowed_fields.same_fields?(other.allowed_fields) &&
-       @required_fields.same_fields?(other.required_fields) &&
-       @read_mask.same_fields?(other.read_mask) &&
-       @write_mask.same_fields?(other.write_mask)) rescue false
+      (compare_fields(@allowed_fields,other.allowed_fields)  &&
+       compare_fields(@required_fields,other.required_fields) &&
+       compare_fields(@read_mask,other.read_mask) &&
+       compare_fields(@write_mask,other.write_mask)) rescue false
     end
 
     # call-seq:
     #    schema.eql?(other) -> true or false
     #
     # Returns <code>true</code> if <code>other</code> is a JiakSchema with the
-    # same array elements, irrespective of order.
+    # same array elements, regardless of order.
     def eql?(other)
       other.is_a?(JiakSchema) &&
-        @allowed_fields.same_fields?(other.allowed_fields)  &&
-        @required_fields.same_fields?(other.required_fields) &&
-        @read_mask.same_fields?(other.read_mask) &&
-        @write_mask.same_fields?(other.write_mask)
+        compare_fields(@allowed_fields,other.allowed_fields)  &&
+        compare_fields(@required_fields,other.required_fields) &&
+        compare_fields(@read_mask,other.read_mask) &&
+        compare_fields(@write_mask,other.write_mask)
+    end
+
+    def compare_fields(arg1,arg2)
+      if(arg1.is_a?(Array) && arg2.is_a?(Array))
+        arg1.same_fields?(arg2)
+      elsif(arg1.is_a?(String) && arg2.is_a?(String))
+        arg1.eql?(arg2)
+      else
+        false
+      end
     end
 
     def hash    # :nodoc:
-      @allowed_fields.name.hash + @required_fields.hash + 
+      @allowed_fields.hash + @required_fields.hash + 
         @read_mask.hash + @write_mask.hash
     end
 
     # String representation of this schema.
     def to_s
-      'allowed_fields="'+@allowed_fields.inspect+
-        '",required_fields="'+@required_fields.inspect+
-        '",read_mask="'+@read_mask.inspect+
-        '",write_mask="'+@write_mask.inspect+'"'
+      af = "allowed_fields=#{@allowed_fields.inspect}"
+      rf = "required_fields=#{@required_fields.inspect}"
+      rm = "read_mask=#{@read_mask.inspect}"
+      wm = "write_mask=#{@write_mask.inspect}"
+      "#{af},#{rf},#{rm},#{wm}"
     end
 
     # Check for array of symbol or string elements.
     def transform_fields(desc,arr)
-      if(arr.eql?("*"))
-        raise(JiakSchemaException,
-              "RiakRest does not support wildcard schemas at this time.")
-      end
-      unless arr.is_a?(Array)
-        raise JiakSchemaException, "#{desc} must be an array"
-      end
-      arr.each do |field| 
-        unless(field.is_a?(String) || field.is_a?(Symbol)) 
-          raise JiakSchemaException, "#{desc} must be strings or symbols"
+      if(arr.is_a?(Array))
+        arr.each do |field| 
+          unless(field.is_a?(String) || field.is_a?(Symbol)) 
+            raise JiakSchemaException, "#{desc} must be strings or symbols"
+          end
         end
+        arr.map{|f| f.to_sym}.uniq
+      elsif(arr.eql?(WILDCARD))
+        arr
+      else
+        raise JiakSchemaException, "#{desc} must be an array or WILDCARD"
       end
-      # unless arr.map{|f| f.to_s}.uniq.size == arr.size
-      #   raise JiakSchemaException, "#{desc} must have unique elements."
-      # end
-      arr.map{|f| f.to_sym}.uniq
     end
     private :transform_fields
 

data/lib/riakrest/resource/jiak_resource.rb

@@ -35,15 +35,15 @@ module RiakRest
     module ClassMethods
 
       # :call-seq:
-      #   JiakServer.server(uri,opts={})
+      #   JiakResource.server(uri,opts={})
       #
       # Set the URI for Jiak server interaction. Go through a proxy if proxy
       # option specified.
       #
-      # Valid options:
-      #  <code>:proxy</code> Proxy server URI.
+      # =====Valid options:
+      #  <code>:proxy</code> -- Proxy server URI.
       def server(uri,opts={})
-        jiak.server = JiakClient.new(uri,opts)
+        jiak.client = JiakClient.new(uri,opts)
         jiak.uri = uri
       end
 
@@ -64,9 +64,11 @@ module RiakRest
         check_fields(fields)
         added_fields = jiak.data.readable(*fields)
         added_fields.each do |field|
-          define_method("#{field}") do
-            @jiak.data.send("#{field}")
-          end
+          class_eval <<-EOM
+            def #{field}
+              @jiak.data.#{field}
+            end
+          EOM
         end
         nil
       end
@@ -80,10 +82,12 @@ module RiakRest
         check_fields(fields)
         added_fields = jiak.data.writable(*fields)
         added_fields.each do |field|
-          define_method("#{field}=") do |val|
-            @jiak.data.send("#{field}=",val)
-            self.class.do_auto_update(self)
-          end
+          class_eval <<-EOM
+            def #{field}=(val)
+              @jiak.data.#{field} = val
+              self.class.do_auto_update(self)
+            end
+          EOM
         end
         nil
       end
@@ -105,6 +109,10 @@ module RiakRest
       end
       private :check_fields
 
+      # :call-seq:
+      #   keygen(&block)
+      #
+      # Specify the block for generating keys for a JiakResource instance.
       def keygen(&block)
         jiak.data.class_eval <<-EOS
           define_method(:keygen,&block)
@@ -114,22 +122,27 @@ module RiakRest
       # :call-seq:
       #   JiakResource.params(opts={})  -> hash
       #
-      # Default options for request parameters during Jiak interaction. Valid
-      # options are:
-      #
-      # <code>:reads</code> :: The number of Riak nodes that must successfully read data.
-      # <code>:writes</code> :: The number of Riak nodes that must successfully store data.
-      # <code>:durable_writes</code> :: The number of Riak nodes (<code>< writes</code>) that must successfully store data in a durable manner.
-      # <code>:waits</code> :: The number of Riak nodes that must reply the delete has occurred before success.
-      #
-      # Request parameters can be set at the JiakResource level using this
-      # method, or at the individual call level. The order of precedence for
-      # setting each parameter at the time of the Jiak interaction is
-      # individual call -> JiakResource -> Riak cluster. In general the values
-      # set on the Riak cluster should suffice and these parameters aren't
-      # necessary for Jiak interaction.
+      # Default options for request parameters during Jiak interaction.
+      #
+      # =====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>:deletes</code>:: Minimum number of responding nodes for successful delete.
+      #
+      # The configuration of a Riak cluster includes server setting for
+      # <code>writes, durable_writes, reads,</code> and <code>deletes</code>
+      # parameters. None of these parameter are required by RiakRest, and their
+      # use within RiakRest is to override the Riak cluster settings, either at
+      # the JiakResource level or the individual request level.
+      #
+      # Settings passed to individual <code>get, put, post, update,
+      # refresh,</code> and <code>delete</code> requests take precendence over
+      # the setting maintained by a JiakResource. Any parameter not set in
+      # JiakResource or on an individual request will default to the values
+      # set in the Riak cluster.
       def params(opts={})
-        jiak.server.params = opts
+        jiak.client.params = opts
       end
 
       # :call-seq:
@@ -205,25 +218,25 @@ module RiakRest
         jiak.data.schema
       end
 
-      #   JiakResource.point_of_view  -> JiakSchema
+      # :call-seq:
+      #   JiakResource.push_schema  -> nil
       #
-      # Ready the Jiak server point-of-view to accept structured interaction
-      # with a JiakResource. Returns the schema set on the Jiak server.
-      def point_of_view
-        jiak.server.set_schema(jiak.bucket)
-        jiak.bucket.schema
+      # Push schema to the Jiak server. If no schema is provided, pushes the
+      # schema associated with the JiakResource.
+      def push_schema(schema=nil)
+        schema ||= jiak.bucket.schema
+        jiak.client.set_schema(jiak.bucket.name,schema)
       end
-      alias :pov :point_of_view
 
       # :call-seq:
-      #   JiakResource.point_of_view?  -> true or false
+      #   JiakResource.server_schema?  -> true or false
       #
-      # Determine if the point-of-view on the Jiak server is that of this
-      # JiakResource.
-      def point_of_view?
-        jiak.server.schema(jiak.bucket).eql? jiak.bucket.schema
+      # Determine if a schema is that set on the Jiak server. If no schema is
+      # provided, use the schema associated with the JiakResource.
+      def server_schema?(schema=nil)
+        schema ||= jiak.bucket.schema
+        jiak.client.schema(jiak.bucket).eql? schema
       end
-      alias :pov? :point_of_view?
 
       # :call-seq:
       #   JiakResource.keys   -> array
@@ -232,17 +245,18 @@ module RiakRest
       # 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)
+        jiak.client.keys(jiak.bucket)
       end
 
       # :call-seq:
       #   JiakResource.put(JiakResource,opts={})  -> JiakResource
       #
-      # Put a JiakResource on the Jiak server. Valid options are:
+      # Put a JiakResource on the Jiak server.
       #
-      # <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 being returned.
+      # =====Valid options:
+      # <code>:writes</code>
+      # <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
@@ -250,7 +264,7 @@ module RiakRest
       # general the values set on the Riak cluster should suffice.
       def put(resource,opts={})
         opts[:return] = :object
-        resource.jiak.object = jiak.server.store(resource.jiak.object,opts)
+        resource.jiak.object = jiak.client.store(resource.jiak.object,opts)
         resource.jiak_convenience
         resource
       end
@@ -259,8 +273,9 @@ module RiakRest
       #   JiakResource.post(JiakResource,opts={})  -> JiakResource
       #
       # Put a JiakResource on the Jiak server with a guard to ensure the
-      # resource has not been previously stored. See JiakResource#put for
-      # options.
+      # resource has not been previously stored.
+      #
+      # See JiakResource#put for options.
       def post(resource,opts={})
         unless(resource.local?)
           raise JiakResourceException, "Resource already initially stored"
@@ -272,7 +287,9 @@ module RiakRest
       #   JiakResource.update(JiakResource,opts={})  -> JiakResource
       #
       # Updates a JiakResource on the Jiak server with a guard to ensure the
-      # resource has been previously stored. See JiakResource#put for options.
+      # resource has been previously stored.
+      #
+      # See JiakResource#put for options.
       def update(resource,opts={})
         if(resource.local?)
           raise JiakResourceException, "Resource not previously stored"
@@ -283,41 +300,39 @@ module RiakRest
       # :call-seq:
       #   JiakResource.get(key,opts={})  -> JiakResource
       #
-      # Get a JiakResource on the Jiak server by the specified key. Valid
-      # options are:
+      # Get a JiakResource on the Jiak server by the specified key.
       #
-      # <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.
+      # =====Valid options:
+      # <code>:reads</code> --- See JiakResource#new
       #
       # 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))
+        new(jiak.client.get(jiak.bucket,key,opts))
       end
 
       # :call-seq:
       #   JiakResource.refresh(resource,opts={})  -> JiakResource
       #
       # Updates a JiakResource with the data on the Jiak server. The current
-      # data of the JiakResource is overwritten, so use with caution. See
-      # JiakResource.get for options.
+      # data of the JiakResource is overwritten, so use with caution.
+      #
+      # See JiakResource#put for options.
       def refresh(resource,opts={})
         resource.jiak.object = get(resource.jiak.key,opts).jiak.object
+        resource.jiak_convenience
       end
 
       # :call-seq:
       #   JiakResource.delete(resource,opts={})  -> true or false
       #
       # Delete the JiakResource store on the Jiak server by the specified
-      # key. Valid options are:
+      # 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 JiakResource, then to the value set on the Riak
-      # cluster. In general the values set on the Riak cluster should suffice.
+      # =====Valid options:
+      # <code>:deletes</code> --- See JiakResource#new
       def delete(resource,opts={})
-        jiak.server.delete(jiak.bucket,resource.jiak.object.key,opts)
+        jiak.client.delete(jiak.bucket,resource.jiak.object.key,opts)
       end
 
       # :call-seq:
@@ -405,7 +420,7 @@ module RiakRest
           end
         end
         links = links[0]  if links.size == 1
-        jiak.server.walk(from.jiak.object.bucket, from.jiak.object.key, links,
+        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        
@@ -417,12 +432,7 @@ module RiakRest
       #
       # Determine if a resource exists on the Jiak server for a key.
       def exist?(key)
-        begin
-          get(key)
-          true
-        rescue JiakResourceNotFound
-          false
-        end
+        jiak.client.exist?(jiak.bucket,key)
       end
 
       # :call-seq:
@@ -448,7 +458,7 @@ module RiakRest
         def jiak  # :nodoc:
           @jiak
         end
-        @jiak = Struct.new(:server,:uri,:group,:data,:bucket,
+        @jiak = Struct.new(:client,:uri,:group,:data,:bucket,
                            :auto_post,:auto_update).new
         @jiak.data = JiakDataFields.create
         @jiak.group = self.name.split('::').last.downcase
@@ -463,7 +473,7 @@ module RiakRest
     # Instance methods
     # ----------------------------------------------------------------------
 
-    attr_accessor :jiak   # :nodoc:
+    attr_reader :jiak   # :nodoc:
 
     # :call-seq:
     #   JiakResource.new(*args)   -> JiakResource
@@ -522,7 +532,8 @@ module RiakRest
     # :call-seq:
     #   auto_update?  -> true, false, or nil
     #
-    # Get current auto_update setting. See JiakResource#auto_update for settings.
+    # Get current auto_update setting. See JiakResource#auto_update for
+    # settings.
     def auto_update?
       @jiak.auto_update
     end
@@ -639,7 +650,7 @@ module RiakRest
     # :call-seq:
     #   jiak_resource == other -> true or false
     #
-    # Equality -- Two JiakResources are equal if they wrap the same data.
+    # Equality -- Two JiakResources are equal if they wrap the same Jiak data.
     def ==(other)
       (@jiak.object == other.jiak.object)  rescue false
     end

data/lib/riakrest.rb

@@ -2,16 +2,18 @@
 begin
   require 'json'
 rescue LoadError
-  raise "RiakRest requires json for REST JSON messaging."
+  puts "\nRiakRest requires json for REST JSON messaging."
+  puts "  Install with:  gem install json"
+  puts
+  exit
 end
 
 begin
   require 'restclient'
 rescue LoadError
-  raise <<EOM
-RiakRest requires the restclient gem for making REST calls.
-  gem install rest-client
-EOM
+  puts "\nRiakRest requires the restclient gem for making REST calls."
+  puts "  Install with:  gem install rest-client"
+  exit
 end
 
 require 'uri'
@@ -59,12 +61,17 @@ module RiakRest
   VERSION = IO.read(version_file).chomp
 
   # 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 opt are not in valid, raise the exception listing the invalid
   # options in the message.
   def check_opts(opts,valid,exception)              # :nodoc:
-    err = opts.select {|k,v| !valid.include?(k)}
-    unless err.empty?
-      raise exception, "unrecognized options: #{err.keys}"
+    unless(opts.empty?)
+      err = opts.inject({}) do |h,(k,v)|
+        h[k] = v  unless(valid.include?(k))
+        h
+      end
+      unless err.empty?
+        raise exception, "unrecognized options: #{err.keys}"
+      end
     end
     opts
   end

data/spec/core/jiak_bucket_spec.rb

@@ -52,6 +52,9 @@ describe "JiakBucket" do
 
     bad_data_class = lambda {@bucket.data_class = Hash}
     bad_data_class.should raise_error(JiakBucketException,/JiakData/)
+
+    nil_data_class = lambda {JiakBucket.new(@name,nil)}
+    nil_data_class.should raise_error(JiakBucketException,/JiakData/)
   end
 
   it "should provide the schema for the data class" do