riakrest 0.0.1

data/lib/riakrest/core/jiak_schema.rb

@@ -0,0 +1,242 @@
+module RiakRest
+
+  # Schema for data objects placed in a Riak bucket. Riak performs basic checks
+  # for storing and retrieving data objects in a bucket by ensuring:
+  #
+  # * Only allowed fields are used.
+  # * Required fields are included.
+  # * Only writable fields are stored.
+  # * Only readable fields are retrieved.
+  #
+  # The schema for a bucket can be changed dynamically so this doesn't lock
+  # storage of data objects to a static structure. To store, say, an expanded
+  # data object in an existing bucket, add the new field to the schema and
+  # reset the bucket schema before storing objects of the new structure. Note
+  # that dynamic changes to a bucket schema do not affect the data objects
+  # already stored by Jiak. Schema designations only affect structured Jiak
+  # interaction, not the data itself.
+  #
+  # 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.
+  # <code>write_mask</code>:: Allowed to be written during a Jiak store.
+  # <code>read_mask</code>:: Returned by Jiak on a retrieval.
+  #
+  # Since Jiak interaction is JSON, duplicate fields names within an array are
+  # not meaningful, including a symbol that "equals" a string. Duplicates
+  # raise an exception.
+  #
+  # ===Usage
+  # <pre>
+  #   schema = JiakSchema.new({:allowed_fields => [:foo,:bar,:baz],
+  #                            :required_fields => [:foo,:bar],
+  #                            :read_mask => [:foo,:baz],
+  #                            :write_mask => [:foo,:bar] })
+  #
+  #   schema.required_fields                         # => [:foo,:bar]
+  #
+  #
+  #   schema = JiakSchema.new({:allowed_fields => [:foo,:bar,:baz],
+  #                            :required_fields => [:foo,:bar]})
+  #
+  #   schema.read_mask                               # => [:foo,:bar,:baz]
+  #   schema.required_fields                         # => [:foo,:bar]
+  #   schema.required_fields = [:foo,:bar,:baz]
+  #   schema.required_fields                         # => [:foo,:bar,:baz]
+  #
+  #
+  #   schema = JiakSchema.new([:foo,:bar,:baz])
+  #
+  #   schema.write_mask                              # => [:foo,:bar,:baz)
+  #
+  # </pre>
+  class JiakSchema
+
+    attr_accessor :allowed_fields, :required_fields, :read_mask, :write_mask
+
+    # call-seq:
+    #    JiakSchema.new(arg)  -> JiakSchema
+    #
+    # New schema from either a hash or an single-element array.
+    # 
+    # ====Hash structure
+    # <em>required</em>
+    # <code>allowed_fields</code>:: Fields that can be stored.
+    # <em>optional</em> 
+    # <code>required_fields</code>:: Fields that must be provided on storage.
+    # <code>read_mask</code>:: Fields returned on retrieval.
+    # <code>write_mask</code>:: Fields that can be changed and stored.
+    # The value for key must be an array.
+    #
+    # =====OR
+    # <code>schema</code>: A hash whose value is the above hash structure.
+    #
+    # Notes
+    # * Keys can either be symbols or strings.
+    # * Array fields must be symbols or strings.
+    # * Required fields defaults to an empty array.
+    # * Masks default to the <code>allowed_fields</code> array.
+    #   
+    # ====Array structure
+    # <code>[:f1,...,fn]</code>:: Allowed fields as symbols or strings.
+    #
+    # All other fields take the same value as the <code>allowed_fields</code>
+    # element. The array structure is provided for simplicity but does not
+    # provide the finer-grained control of the hash structure.
+    #
+    # Raise JiakSchemaException if:
+    # * the method argument is not either a hash or array
+    # * The fields are not either symbols or strings
+    # * The fields elements are not unique
+    def initialize(arg)
+      case arg
+      when Hash
+        # Jiak returns a JSON structure with a single key 'schema' whose value
+        # is a hash. If the arg hash has a schema key, set the opts hash to
+        # that; otherwise use the arg as the opts hash.
+        opts = arg[:schema] || arg['schema'] || arg
+
+        opts[:allowed_fields] ||= opts['allowed_fields']
+        check_arr("allowed_fields",opts[:allowed_fields])
+
+        # Use required if provided, otherwise set to empty array
+        opts[:required_fields] ||= opts['required_fields'] || []
+        check_arr("required_fields",opts[:required_fields])
+        
+        # Use masks if provided, otherwise set to allowed_fields
+        [:read_mask,:write_mask].each do |key|
+          opts[key] ||= opts[key.to_s] || opts[:allowed_fields]
+          check_arr(key.to_s,opts[key])
+        end
+      when Array
+        # An array arg must be a single-element array of the allowed
+        # fields. Required fields is set to an empty array and the masks are
+        # set to the allowed fields array.
+        check_arr("allowed_fields",arg)
+        opts = {
+          :allowed_fields  => arg,
+          :required_fields => [],
+          :read_mask       => arg,
+          :write_mask      => arg
+        }
+      else
+        raise JiakSchemaException, "Initialize arg must be either hash or array"
+      end
+
+      @allowed_fields =  opts[:allowed_fields]
+      @required_fields = opts[:required_fields]
+      @read_mask =       opts[:read_mask]
+      @write_mask =      opts[:write_mask]
+    end
+
+    # call-seq:
+    #    JiakSchema.from_json(json)  -> JiakSchema
+    #
+    # Create a JiakSchema from parsed JSON returned by the Jiak server.
+    def self.from_jiak(jiak)
+      new(jiak)
+    end
+
+    # call-seq:
+    #    schema.to_jiak  -> JSON
+    #
+    # Create a representation suitable for sending to a Jiak server. Called by
+    # JiakClient when transporting a schema to Jiak.
+    def to_jiak
+      { :schema =>
+        { :allowed_fields  => @allowed_fields,
+          :required_fields => @required_fields,
+          :read_mask       => @read_mask,
+          :write_mask      => @write_mask
+        }
+      }.to_json
+    end
+
+    def allowed_fields=(arr)  # :nodoc:
+      check_arr('allowed_fields',arr)
+      @allowed_fields = arr
+    end
+    def required_fields=(arr)  # :nodoc:
+      check_arr('required_fields',arr)
+      @required_fields = arr
+    end
+    def read_mask=(arr)  # :nodoc:
+      check_arr('read_mask',arr)
+      @read_mask = arr
+    end
+    def write_mask=(arr)  # :nodoc:
+      check_arr('write_mask',arr)
+      @write_mask = arr
+    end
+
+    # :call-seq:
+    #   schema.readwrite = [:f1,...,:fn]
+    #
+    # Set the read and write masks for a JiakSchema.
+    def readwrite=(arr)   # :nodoc:
+      check_arr('readwrite',arr)
+      @read_mask = arr
+      @write_mask = arr
+    end
+
+    # call-seq:
+    #    schema == other -> true or false
+    #
+    # Equality -- Two schemas are equal if they contain the same array elements
+    # for all attributes, irrespective 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
+    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.
+    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)
+    end
+
+    def hash    # :nodoc:
+      @allowed_fields.name.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+'"'
+    end
+
+    # Each option must be an array of symbol or string elements.
+    def check_arr(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"
+        end
+      end
+      unless arr.map{|f| f.to_s}.uniq.size == arr.size
+        raise JiakSchemaException, "#{desc} must have unique elements."
+      end
+    end
+    private :check_arr
+
+  end
+
+end

data/lib/riakrest/core/query_link.rb

@@ -0,0 +1,156 @@
+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.
+  #
+  # ===Usage
+  # <code>
+  #   link = QueryLink.new('people','parent')
+  #   link = QueryLink.new(['children','odd','_'])
+  #   link = QueryLink.new('blogs',nil,QueryLink::ANY)
+  # </code>
+  class QueryLink
+
+    attr_accessor :bucket, :tag, :acc
+
+    # Jiak (erlang) wildcard character (atom)
+    ANY = '_'
+
+    # :call-seq:
+    #   QueryLink.new(*args)  -> QueryLink
+    #
+    # Create a link from argument array. Missing, nil, or empty string values
+    # are set to QueryLink::ANY.
+    #
+    # ====Examples
+    # The following create QueryLinks with the shown equivalent array structure:
+    # <code>
+    #   QueryLink.new                       # => ['_','_','_']
+    #   QueryLink.new 'b'                   # => ['b','_','_']
+    #   QueryLink.new 'b','t'               # => ['b','t','_']
+    #   QueryLink.new 'b','t','a'           # => ['b','t','a']
+    #
+    #   QueryLink.new []                    # => ['_','_','_']
+    #   QueryLink.new ['b']                 # => ['b','_','_']
+    #   QueryLink.new ['b','t']             # => ['b','t','_']
+    #   QueryLink.new ['b','t','a']         # => ['b','t','a']
+    #
+    #   QueryLink.new ['',nil,' ']          # => ['_','_','_']
+    # </code>
+    #
+    # Passing another QueryLink as an argument makes a copy of that
+    # link. Passing a JiakBucket in the first (bucket) position uses the name
+    # field of that JiakBucket.
+    def initialize(*args)
+      case args.size
+      when 0
+        bucket = tag = acc = ANY
+      when 1
+        if args[0].is_a? String
+          bucket = args[0]
+          tag = acc = ANY
+        elsif args[0].is_a? QueryLink
+          bucket, tag, acc = args[0].bucket, args[0].tag, args[0].acc
+        elsif args[0].is_a? Array
+          bucket, tag, acc = args[0][0], args[0][1], args[0][2]
+        else
+          raise QueryLinkException, "argument error"
+        end
+      when 2
+        bucket, tag = args[0], args[1]
+        acc = ANY
+      when 3
+        bucket, tag, acc = args[0], args[1], args[2]
+      else
+        raise QueryLinkException, "too many arguments, (#{args.size} for 3)"
+      end
+      
+      @bucket, @tag, @acc  = transform_args(bucket,tag,acc)
+    end
+    
+    # :call-seq
+    #   link.bucket = bucket
+    #
+    # Set the bucket field.
+    def bucket=(bucket)
+      bucket = bucket.name  if bucket.is_a? JiakBucket
+      @bucket = transform_arg(bucket)
+    end
+
+    # :call-seq:
+    #   link.tag = tag
+    #
+    # Set the tag field.
+    def tag=(tag)
+      @tag = transform_arg(tag)
+    end
+
+    # :call-seq:
+    #   link.acc = acc
+    #
+    # Set the acc field.
+    def acc=(acc)
+      @acc = transform_arg(acc)
+    end
+
+    # :call-seq:
+    #    link.for_uri  -> URI encoded string
+    #
+    # URI represent this QueryLink, i.e, a string suitable for inclusion in an
+    # URI.
+    def for_uri
+      URI.encode([@bucket,@tag,@acc].join(','))
+    end
+
+    # :call-seq:
+    #    link == other -> true or false
+    #
+    # Equality -- QueryLinks are equal if they contain the same attribute
+    # values.
+    def ==(other)
+      (@bucket == other.bucket &&
+       @tag    == other.tag    &&
+       @acc    == other.acc) rescue false
+    end
+
+    # :call-seq:
+    #    link.eql?(other) -> true or false
+    #
+    # Returns <code>true</code> if <code>other</code> is a QueryLink with the
+    # same attribute values.
+    def eql?(other)
+      other.is_a?(QueryLink) &&
+        @bucket.eql?(other.bucket) &&
+        @tag.eql?(other.tag) &&
+        @acc.eql?(other.acc)
+    end
+
+    def hash    # :nodoc:
+      @bucket.name.hash + @tag.hash + @acc.hash
+    end
+
+    # String representation of this QueryLink.
+    def to_s
+      '["'+@bucket+'","'+@tag+'","'+@acc+'"]'
+    end
+
+    def transform_args(b,t,a)
+      b = b.name  if b.is_a? JiakBucket
+      [transform_arg(b),transform_arg(t),transform_arg(a)]
+    end
+    private :transform_args
+    
+    def transform_arg(arg)
+      arg = ANY  if arg.nil?
+      unless arg.is_a? String
+        raise QueryLinkException, "Link elements must be Strings."
+      end
+      value = arg.dup
+      value.strip!
+      value.empty? ? ANY : value
+    end
+    private :transform_arg
+  end
+end
+

data/lib/riakrest/data/jiak_data_hash.rb

@@ -0,0 +1,182 @@
+module RiakRest
+  # JiakDataHash provides a easy-to-use default JiakData implementation. See
+  # JiakData for a discussion on creating user-defined data classes.
+  #
+  # JiakDataHash creates a JiakData from a list of user-data fields. Note
+  # JiakDataHash, like JiakData, is not used to create instances of user data;
+  # rather it is used to create the class for the user data. That class is then
+  # used to create instances of the user data itself.
+  #
+  # The class created by JiakDataHash is anonymous and takes the name of the
+  # constant to which it is assigned. See the example below.
+  #
+  # Object instances of the class created by JiakDataHash have read and write
+  # accessors for each the fields used in creating the class. Instance values
+  # can also be accessed via [] and []=. Other hash sematics are not
+  # provided. The created class does have a <code>to_hash</code> method that
+  # returns a hash of the instance data fields and values.
+  #
+  # The class created by JiakDataHash includes an initialize method that takes
+  # as argument a hash of the field/value pairs for the instance. The instance
+  # still has all of the field attributes, this simply provides a easy way to
+  # initialize some or all of the values for the fields.
+  #
+  # The class created by JiakDataHash also provides a <code>keygen</code> class
+  # method that allows specifying a list of fields for use in generating the
+  # key for instance data. See JiakDataHash#keygen.
+  #
+  # Note the created class has methods provided by JiakData to inspect or
+  # manipulate the structure Jiak interaction for instances of the class. See
+  # JiakData#ClassMethods for those methods.
+  #
+  # ===Usage
+  # <code>
+  #   Dog = JiakDataHash.create(:name,:weight)
+  #   Dog.keygen :name
+  #
+  #   addie = Dog.new(:name => "Adelaide", :weight => 45)
+  #   addie.name                                           # => "Adeliade"
+  #   addie.weight                                         # => 45
+  #
+  #   addie.weight = 47                                    # => 47
+  # </code>
+  #
+  class JiakDataHash
+
+    # :call-seq:
+    #   JiakDataHash.create(:f1,...,fn)    -> JiakDataHash
+    #   JiakDataHash.create([:f1,...,fn])  -> JiakDataHash
+    #   JiakDataHash.create(schema)        -> JiakDataHash
+    #
+    # Creates a JiakDataHash class that can be used to create JiakData objects
+    # containing the specified fields.
+    def self.create(*args)
+      Class.new do
+        include JiakData
+
+        if(args.size == 1)
+          case args[0]
+          when Symbol, Array
+            allowed *args[0]
+          when JiakSchema
+            allowed  *args[0].allowed_fields
+            required *args[0].required_fields
+            readable *args[0].read_mask
+            writable *args[0].write_mask
+          end
+        else
+          allowed *args
+        end
+
+        # :call-seq:
+        #   DataClass.keygen(*fields)
+        #
+        # The key generation for the data class will be a concatenation of the
+        # to_s result of calling each of the listed data class fields.
+        def self.keygen(*fields)
+          define_method(:keygen) do
+            fields.inject("") {|key,field| key += send("#{field}").to_s}
+          end
+        end
+
+        # :call-seq:
+        #   data.new({})  -> JiakDataHash
+        #
+        # Create an instance of the user-defined JiakDataHash using the provide
+        # hash as initial values.
+        def initialize(hsh={})
+          hsh.each {|key,value| send("#{key}=",value)}
+        end
+        
+        # :call-seq:
+        #   data.jiak_create(jiak)  ->  JiakDataHash
+        #
+        # Used by RiakRest to create an instance of the user-defined data class
+        # from the values returned by the Jiak server.
+        def self.jiak_create(jiak)
+          new(jiak)
+        end
+
+        # :call-seq:
+        #   data[field] -> value
+        #
+        # Get the value of a field.
+        #
+        # Returns <code>nil</code> if <code>field</code> was not declared for
+        # this class. <code>field</code> can be in either string or symbol
+        # form.
+        def [](key)
+          send("#{key}") rescue nil
+        end
+
+        # :call-seq:
+        #   data[field] = value
+        #
+        # Set the value of a field.
+        #
+        # Returns the value set, or <code>nil</code> if <code>field</code> was
+        # not declared for this class.
+        def []=(key,value)
+          send("#{key}=",value)  rescue nil
+        end
+
+        # :call-seq:
+        #   data.for_jiak  -> hash
+        #
+        # Return a hash of the writable fields and their values. Used by
+        # RiakRest to prepare the data for transport to the Jiak server.
+        def for_jiak
+          self.class.schema.write_mask.inject({}) do |build,field|
+            val = send("#{field}")
+            build[field] = val  unless val.nil?
+            build
+          end
+        end
+        
+        # :call-seq:
+        #   data.to_hash
+        #
+        # Return a hash of the allowed fields and their values.
+        def to_hash
+          self.class.schema.allowed_fields.inject({}) do |build,field|
+            val = send("#{field}")
+            build[field] = val
+            build
+          end
+        end
+
+
+        # call-seq:
+        #    jiak_data == other -> true or false
+        #
+        # Equality -- Two JiakDataHash objects are equal if they contain the
+        # same values for all attributes.
+        def ==(other)
+          self.class.schema.allowed_fields.reduce(true) do |same,field|
+            same && (other.send("#{field}") == (send("#{field}")))
+          end
+        end
+
+        # call-seq:
+        #    data.eql?(other) -> true or false
+        #
+        # Returns <code>true</code> if <code>other</code> is a JiakObject with
+        # the same the same attribute values for all allowed fields.
+        def eql?(other)
+          other.is_a?(self.class) &&
+            self.class.schema.allowed_fields.reduce(true) do |same,field|
+            same && other.send("#{field}").eql?(send("#{field}"))
+          end
+        end
+
+        def hash   # :nodoc:
+          self.class.schema.allowed_fields.inject(0) do |hsh,field|
+            hsh += send("#{field}").hash
+          end
+        end
+
+      end
+    end
+
+  end
+end