riakrest 0.0.1

data/lib/riakrest/core/jiak_data.rb

@@ -0,0 +1,265 @@
+module RiakRest
+
+  # All end-user data stored via RiakRest is contained in user-defined data
+  # objects. To make a user-defined data object, include module JiakData into
+  # your class definition. This allows creating a class that can be used to
+  # create instances of your user-defined data. Note JiakData does create
+  # user-data instances, rather it facilitates creating the class you use to
+  # create user-data instances.
+  #
+  # The four class methods <code>allowed, required, readable, writable</code>
+  # defined in JiakData#ClassMethods are used to declare the schema for
+  # structured Jiak interaction with user-defined data. The <code>allowed</code>
+  # method is mandatory; the other methods take the defaults as described in
+  # JiakSchema. See JiakSchema for discussion on structured data interaction.
+  #
+  # User-defined data classes must override JiakData#ClassMethods#jiak_create
+  # (creating your user-defined data from the information returned by Jiak) and
+  # JiakData#for_jiak (providing the information to be sent to Jiak). The
+  # default implementations of these methods throw JiakDataException to
+  # enforce this override.
+  #
+  # JiakData provides a default data key generator that returns nil, which
+  # instructs the Jiak server to generate a random key on first data
+  # storage. To explicitly set the key override JiakData#keygen to return
+  # whatever string you want to use for the key. Keys need to be unique within
+  # each bucket on the Jiak server but can be the same across distinct buckets.
+  #
+  # ===Example
+  # <code>
+  #   class FooBarBaz
+  #     include JiakData
+  #
+  #     allowed  :foo, :bar, :baz
+  #     required :foo
+  #     readable :foo, :bar
+  #     writable :foo, :baz
+  # 
+  #     def initialize(foo,bar,baz)
+  #       @foo = foo
+  #       @bar = bar
+  #       @baz = baz
+  #     end
+  # 
+  #     def self.jiak_create(jiak)
+  #       new(jiak['foo'],jiak['bar'])
+  #     end
+  # 
+  #     def for_jiak
+  #       { :foo => @foo,
+  #         :baz => @baz
+  #       }
+  #     end
+  #
+  #     def keygen
+  #       "#{foo}"
+  #     end
+  #   end
+  # </code>
+  #
+  # Note that FooBarBaz <code>bar</code> is readable but not writable and
+  # <code>baz</code> is writable but not readable. Also note
+  # <code>for_jiak</code> only provides the <code>writable</code> fields for
+  # writing to the Jiak server and <code>jiak_create</code> only initializes
+  # from the <code>readable</code> fields returned by the Jiak server. The
+  # above definition means a user of FooBarBaz could change <code>baz</code>
+  # but not see that change and could access <code>bar</code> but not change
+  # it. This could be useful if either another JiakData class (with a different
+  # schema) created access into the same data, allowing <code>bar</code> writes
+  # and <code>baz</code> reads, or if Riak server-side manipulation affected
+  # those fields. The constraints declared in FooBarBaz simply provide
+  # a particular structured interaction of data on a Jiak server.
+  #
+  # If only one JiakData will be used for a particular type of data on the Jiak
+  # server it is desirable to have the <code>readable</code> and
+  # <code>writable</code> fields be the same as <code>allowed</code>. Setting
+  # only <code>allowed</code> fields provide this reasonable default, hence only
+  # that call is mandatory.
+  module JiakData
+
+    # ----------------------------------------------------------------------
+    #   Class methods
+    # ----------------------------------------------------------------------
+    
+    # Class methods for use in creating a user-defined JiakData. The methods
+    # <code>allowed, required, readable, writable</code> define the JiakSchema
+    # for this JiakData. See JiakSchema for discussion on the use of schemas in
+    # Riak.
+    module ClassMethods
+
+      # :call-seq:
+      #   allowed :f1, ..., :fn   -> array
+      #
+      # Fields allowed in Jiak interactions. Returns an array of the allowed
+      # fields.
+      #
+      def allowed(*fields)
+        arr_fields = create_array(fields)
+        fields.each {|field| attr_accessor field}
+        @schema = JiakSchema.new(arr_fields)
+        arr_fields
+      end
+
+      # :call-seq:
+      #   required :f1, ..., :fn  -> array
+      #
+      # Fields required during in Jiak interactions. Returns an array of the
+      # required fields.
+      #
+      def required(*fields)
+        set_fields('required_fields',*fields)
+      end
+
+      # :call-seq:
+      #   readable :f1, ..., :fn  -> array
+      #
+      # Fields returned by Jiak on retrieval. Returns an array of the fields in
+      # the read mask.
+      #
+      def readable(*fields)
+        set_fields('read_mask',*fields)
+      end
+
+      # :call-seq:
+      #   writable :f1, ..., :fn  -> arry
+      #
+      # Fields that can be written during Jiak interaction. Returns an array of
+      # the fields in the write mask.
+      #
+      def writable(*fields)
+        set_fields('write_mask',*fields)
+      end
+
+      # :call-seq:
+      #   readwrite :f1, ..., :fn  -> array
+      #
+      # Set the read and write masks to the same fields. Returns an array of
+      # the fields in the masks.
+      def readwrite(*fields)
+        arr_fields = set_fields('readwrite',*fields)
+        arr_fields
+      end
+
+      def set_fields(which,*fields)
+        arr_fields = create_array(fields)
+        check_allowed(arr_fields)
+        @schema.send("#{which}=",arr_fields)
+        arr_fields
+      end
+      private :set_fields
+      
+      # :call-seq:
+      #   JiakData.schema  -> JiakSchema
+      #
+      # Get a JiakSchema representation determined by
+      # <code>allowed, required, readable, writable</code>.
+      #
+      def schema
+        @schema
+      end
+
+      # :call-seq:
+      #  JiakData.jiak_create(jiak)  -> JiakData
+      #
+      # Create an instance of user-defined data object from the fields read
+      # by Jiak. These fields are determined by the read mask of the
+      # structured Jiak interaction. See JiakSchema for read mask discussion.
+      #
+      # User-defined data classes must override this method. The method is
+      # called during the creation of a JiakObject from information returned by
+      # Jiak. The JiakObject contains the user-defined data itself. You do not
+      # call this method explicitly.
+      #
+      # ====Example
+      # <code>
+      #    def initialize(f1,f2)
+      #      @f1 = f1
+      #      @f2 = f2
+      #    end
+      #    def jiak_create(jiak)
+      #      new(jiak['f1'], jiak['f2'])
+      #    end
+      # </code>
+      #
+      # Raise JiakDataException if not explicitly defined by user-defined data class.
+      def jiak_create(json)
+        raise JiakDataException, "#{self} must define jiak_create"
+      end
+
+      def create_array(*fields)
+        if(fields.size == 1 && fields[0].is_a?(Array))
+          array = fields[0]
+        else
+          array = fields
+        end
+        array.map {|field| field}
+        array
+      end
+      private :create_array
+
+      def check_allowed(fields)
+        allowed_fields = @schema.allowed_fields
+        fields.each do |field|
+          unless allowed_fields.include?(field)
+            raise JiakDataException, "field '#{field}' not allowed"
+          end
+        end
+      end
+      private :check_allowed
+    end
+
+    def self.included(including_class)  # :nodoc:
+      including_class.extend(ClassMethods)
+    end
+    
+    # ----------------------------------------------------------------------
+    #   Instance methods
+    # ----------------------------------------------------------------------
+
+    # :call-seq:
+    #   for_jiak  -> hash
+    #
+    # Provide a hash structure of the data to write to Jiak. The fields for
+    # this structure should come from the write mask of the structured Jiak
+    # interaction.  See JiakSchema for write mask discussion.
+    #
+    # User-defined data classes must override this method. The method is called
+    # during the creation of a JiakObject to send information to Jiak. The
+    # JiakObject contains the user-defined data itself. You do not call this
+    # method explicitly.
+    #
+    # ====Example
+    # <code>
+    #    def for_jiak
+    #      { :writable_f1 => @writable_f1,
+    #        :writable_f2 => @writable_f2
+    #      }
+    #    end
+    # </code>
+    #
+    # Raise JiakDataException if not explicitly defined by user-defined data class.
+    def for_jiak
+      raise JiakDataException, "#{self} must define for_jiak"
+    end
+
+    # :call-seq:
+    #   keygen   -> string
+    #
+    # Generate Jiak key for data. Default implementation returns
+    # <code>nil</code> which instructs the Jiak server to generate a random
+    # key. Override for user-defined data behaviour.
+    #
+    # ====Example
+    # A simple implementation would look like:
+    # <code>
+    #   def keygen
+    #     f1.to_s
+    #   end
+    # </code>
+    def keygen
+      nil
+    end
+
+  end
+end
+

data/lib/riakrest/core/jiak_link.rb

@@ -0,0 +1,131 @@
+module RiakRest
+
+  # Represents a link between object in Jiak. JiakLinks are used to link a
+  # JiakObject to another JiakObject at a bucket/key. The tag allows the link
+  # to be traversed later using a QueryLink.
+  #
+  # ===Usage
+  # <code>
+  #   link = JiakLink.new('people','callie','sister')
+  # </code>
+  # If the above link were added to a JiakObject in the same bucket and keyed
+  # by the string 'remy', the link from remy to the sister callie would be
+  # retrieve using JiakClient#walk and the query link
+  # <code>QueryLink.new('people','sister')</code>
+  #   
+  class JiakLink
+
+    attr_accessor :bucket, :key, :tag
+
+    # :call-seq:
+    #   JiakLink.new(bucket,key,tag)  -> JiakLink
+    #   JiakLink.new([bucket,key,tag])  -> JiakLink
+    #
+    # Create a link (designated by tag) to an object at bucket/key. Bucket can
+    # be either a JiakBucket or a string bucket name; key and tag must both be
+    # strings.
+    #
+    def initialize(*args)
+      case args.size
+      when 1
+        if args[0].is_a? Array
+          bucket, key, tag = args[0][0], args[0][1], args[0][2]
+        elsif args[0].is_a? JiakLink
+          bucket, key, tag = args[0].bucket, args[0].key, args[0].tag
+        else
+          raise JiakLinkException, "argument error"
+        end
+      when 3
+        bucket, key, tag = args[0], args[1], args[2]
+      else
+        raise JiakLinkException, "argument error"
+      end
+
+      @bucket, @key, @tag  = transform_args(bucket,key,tag)
+    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.key = key
+    #
+    # Set the key field.
+    def key=(key)
+      @key = transform_arg(key)
+    end
+
+    # :call-seq:
+    #   link.tag = tag
+    #
+    # Set the tag field.
+    def tag=(tag)
+      @tag = transform_arg(tag)
+    end
+
+    # :call-seq:
+    #   link.for_jiak  -> JSON
+    #
+    # Representation of this JiakLink for transport to Jiak.
+    def for_jiak
+      [@bucket, @key, @tag]
+    end
+
+    # :call-seq:
+    #    link == other -> true or false
+    #
+    # Equality -- JiakLinks are equal if they contain the same attribute values.
+    def ==(other)
+      (@bucket == other.bucket &&
+       @key    == other.key    &&
+       @tag    == other.tag) rescue false
+    end
+
+    # :call-seq:
+    #    eql?(other) -> true or false
+    #
+    # Returns <code>true</code> if <code>other</code> is a JiakLink with the
+    # same attribute values.
+    def eql?(other)
+      other.is_a?(JiakLink) &&
+        @bucket.eql?(other.bucket) &&
+        @key.eql?(other.key) &&
+        @tag.eql?(other.tag)
+    end
+
+    def hash    # :nodoc:
+      @bucket.hash + @key.hash + @tag.hash
+    end
+
+    # String representation of this JiakLink.
+    def to_s
+      "[#{bucket},#{key},#{tag}]"
+    end
+
+    def transform_args(b,k,t)
+      b = b.name  if b.is_a? JiakBucket
+      [transform_arg(b),transform_arg(k),transform_arg(t)]
+    end
+    private :transform_args
+    
+    def transform_arg(arg)
+      unless arg.is_a? String
+        raise JiakLinkException, "Link elements must be Strings."
+      end
+      value = arg.dup
+      value.strip!
+      if value.empty?
+        raise JiakLinkException, "Link elements can't be empty."
+      end
+      value
+    end
+    private :transform_arg
+
+  end
+end

data/lib/riakrest/core/jiak_object.rb

@@ -0,0 +1,233 @@
+module RiakRest
+
+  # Wrapper for JiakData.
+  class JiakObject
+
+    attr_accessor :bucket, :key, :data, :links, :riak
+
+    # :call-seq:
+    #   JiakObject.new(opts)  -> JiakObject
+    #
+    # Create a object for Jiak storage. Valid options:
+    # <code>:bucket</code> :: JiakBucket for storage.
+    # <code>:data</code> :: Object JiakData to be stored.
+    # <code>:key</code> :: Object key.
+    # <code>:links</code> :: Object JiakLink array.
+    #
+    # The bucket and data options are required.
+    #
+    # The key and links options are optional. If no key is provided, the
+    # <code>keygen</code> method of <code>data</code> is used to provide the
+    # key. The default implementation of JiakData#keygen is an empty string,
+    # which instructs the Jiak server to generate a random key. If no links are
+    # provided, the default uses an empty array.
+    #
+    # There are other options used by the system to maintain the context of the
+    # JiakObject on the Riak cluster. These options should not be manually
+    # altered and are purposely not described here.
+    def initialize(opts)
+      opts[:links] ||= []
+      check_opts(opts)
+
+      @bucket = check_bucket(opts[:bucket])
+      @data = check_data(opts[:data])
+      @key = transform_key(opts[:key] || @data.keygen)
+      @links = check_links(opts[:links])
+
+      # The Riak context for the object if provided.
+      if opts[:vclock]
+        @riak = opts.select {|k,v| [:vclock,:vtag,:lastmod].include?(k)}
+      end
+    end
+
+    # :call-seq:
+    #    JiakObject.from_jiak(jiak)  -> JiakObject
+    #
+    # Create a JiakObject from parsed JSON returned by the Jiak server. Calls
+    # the <code>jiak_create</code> of the JiakData class passed as the second
+    # argument to inflate the data into the user-defined data class.
+    def self.from_jiak(jiak,klass)
+      jiak[:bucket] = JiakBucket.new(jiak.delete('bucket'),klass)
+      jiak[:data] = klass.jiak_create(jiak.delete('object'))
+      jiak[:links] = jiak.delete('links').map {|link| JiakLink.new(link)}
+
+      new(jiak.inject({}) do |build, (key, value)|
+            build[key.to_sym] = value
+            build
+          end)
+    end
+
+    # :call-seq:
+    #    jiak_object.to_jiak  -> JSON
+    #
+    # Create a representation suitable for sending to a Jiak server. Calls the
+    # <code>for_jiak</code> method of the wrapped JiakData. Called by
+    # JiakClient when transporting an object to Jiak.
+    def to_jiak
+      jiak = {
+        :bucket => @bucket.name,
+        :key => @key,
+        :object => @data.for_jiak,
+        :links => @links.map {|link| link.for_jiak}
+      }
+      if(@riak)
+        jiak[:vclock] = @riak[:vclock]
+        jiak[:vtag] = @riak[:vtag]
+        jiak[:lastmod] = @riak[:lastmod]
+      end
+      jiak.to_json
+    end
+
+    # :call-seq:
+    #   jiak_object.bucket = bucket
+    #
+    # Set the bucket for a JiakObject. Bucket must be a JiakBucket.
+    def bucket=(bucket)
+      @bucket = check_bucket(bucket)
+    end
+
+    # :call-seq:
+    #   jiak_object.key = string or nil
+    #
+    # Set the key for a JiakObject. Key string is stripped of leading and
+    # trailing blanks. A nil key is interpreted as an empty string.
+    def key=(key)
+      @key = transform_key(key)
+    end
+
+    # :call-seq:
+    #   jiak_object.data = {}
+    #
+    # Set the data wrapped by a JiakObject. The data must be a JiakData object.
+    def data=(data)
+      @data = check_data(data)
+    end
+
+    # :call-seq:
+    #   jiak_object.links = []
+    #
+    # Set the links array for JiakObject. Each array element must be a
+    # JiakLink.
+    def links=(links)
+      @links = check_links(links)
+    end
+
+    # :call-seq:
+    #   jiak_object << JiakLink  -> JiakObject
+    #
+    # Convenience method for adding a JiakLink to the links for a
+    # JiakObject. Duplicate links are ignored. Returns the JiakObject for
+    # chaining.
+    def <<(link)
+      link = check_link(link)
+      @links << link unless @links.include?(link)
+      self
+    end
+
+    # :call-seq:
+    #   jiak_object.riak = riak
+    #
+    # Set the Riak context for a JiakObject.
+    def riak=(riak)
+      @riak = check_riak(riak)
+    end
+
+    # :call-seq:
+    #    jiak_object == other -> true or false
+    #
+    # Equality -- Two JiakObjects are equal if they contain the same values
+    # for all attributes.
+    def ==(other)
+      (@bucket == other.bucket &&
+       @key == other.key &&
+       @data == other.data &&
+       @links == other.links
+       ) rescue false
+    end
+
+    # :call-seq:
+    #    jiak_object.eql?(other) -> true or false
+    #
+    # Returns <code>true</code> if <code>other</code> is a JiakObject with the
+    # same the same attribute values.
+    def eql?(other)
+      other.is_a?(JiakObject) &&
+        @bucket.eql?(other.bucket) &&
+        @key.eql?(other.key) &&
+        @data.eql?(other.data) &&
+        @links.eql?(other.links)
+    end
+
+    def hash    # :nodoc:
+      @bucket.name.hash + @key.hash + @data.hash + @links.hash + @riak.hash
+    end
+
+    def check_opts(opts)
+      err = opts.select {|k,v| !VALID_OPTS.include?(k)}
+      unless err.empty?
+        raise JiakObjectException, "unrecognized options: #{err.keys}"
+      end
+      opts
+    end
+    private :check_opts
+
+    def check_bucket(bucket)
+      unless bucket.is_a?(JiakBucket)
+        raise JiakObjectException, "Bucket must be a JiakBucket."
+      end
+      bucket
+    end
+    private :check_bucket
+
+    def transform_key(key)
+      # Change nil key to empty
+      o_key = key.nil? ? '' : key.dup
+      unless o_key.is_a?(String)
+        raise JiakObjectException, "Key must be a String" 
+      end
+      o_key.strip!
+      o_key
+    end
+    private :transform_key
+
+    def check_data(data)
+      unless data.is_a?(JiakData)
+        raise JiakObjectException, "Data must be a JiakData."
+      end
+      data
+    end
+    private :check_data
+
+    def check_links(links)
+      unless links.is_a? Array
+        raise JiakObjectException, "Links must be an array"
+      end
+      links.each do |link|
+        check_link(link)
+      end
+      links
+    end
+    private :check_links
+
+    def check_link(link)
+      unless link.is_a? JiakLink
+        raise JiakObjectException, "Each link must be a JiakLink"
+      end
+      link
+    end
+    private :check_link
+
+    def check_riak(riak)
+      err = riak.select {|k,v| !VALID_RIAK.include?(k)}
+      unless err.empty?
+        raise JiakObjectException, "unrecognized options: #{err.keys}"
+      end
+      riak
+    end
+
+    private
+    VALID_RIAK = [:vclock,:vtag,:lastmod]
+    VALID_OPTS = [:bucket,:key,:data,:links] + VALID_RIAK
+  end
+
+end