riakrest 0.0.4 → 0.1.0

data/lib/riakrest/core/jiak_data.rb

@@ -3,78 +3,45 @@ 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 instances of your user-defined data. Note JiakData does not create
+  # user-data instances, rather it facilitates creating the class used 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.
+  # The class methods <code>jattr_reader,jattr_writer</code>, and
+  # <code>jattr_accessor</code> are used to declare the Jiak readable and
+  # writable fields for a JiakData. The method <code>keygen</code> is used
+  # to specify a block for generating the key for a data instance. By default,
+  # JiakData generates an empty key which is interpreted by the Jiak server as
+  # a signal to generate a random key.
+  # ====Example
+  #  class FooBar
+  #    include JiakData
+  #    jattr_accessor :foo, :bar
+  #    keygen { foo.downcase }
+  #  end
   #
-  # 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.
+  # The four class methods <code>allow, require, readable, writable</code> are
+  # used for more specific data schema control. See JiakSchema for a
+  # discussion of the schema fields.
+  # ====Example
+  #  class FooBarBaz
+  #    include JiakData
   #
-  # 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.
+  #    allow    :foo, :bar, :baz
+  #    require  :foo
+  #    readable :foo, :bar
+  #    writable :foo, :baz
+  #  end
   #
-  # ===Example
-  # <code>
-  #   class FooBarBaz
-  #     include JiakData
+  # The methods used in the above examples can be used together as well.
   #
-  #     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
+  # The Core Client framework uses a JiakData class to marshall data to and
+  # from the Jiak server. Marshalling to the Jiak server uses JiakData#to_jiak
+  # and marshalling from the Jiak server uses
+  # JiakData#ClassMethods#jiak_create. Implementations of these methods are
+  # automatically generated to marshall writable fields to Jiak and initialize
+  # from readable fields.
   #
-  #     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
 
     # ----------------------------------------------------------------------
@@ -82,91 +49,126 @@ module RiakRest
     # ----------------------------------------------------------------------
     
     # 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.
+    # <code>allow, require, readable, writable</code> delegate to JiakSchema. 
+    # See JiakSchema for discussion on the use of schemas in Riak.
     module ClassMethods
 
       # :call-seq:
-      #   allowed :f1, ..., :fn   -> array
-      #   allowed [:f1, ..., :fn]   -> array
+      #   jattr_reader :f1,...,:fn
+      #
+      # Add read accessible fields.
+      def jattr_reader(*fields)
+        readable *fields
+        nil
+      end
+      alias :jattr :jattr_reader
+
+      # :call-seq:
+      #   jattr_writer :f1,...,:fn
+      #
+      # Add write accessible fields.
+      def jattr_writer(*fields)
+        writable *fields
+        nil
+      end
+
+      # :call-seq:
+      #   jattr_accessor :f1,...,:fn
+      #
+      # Add read/write accessible fields.
+      def jattr_accessor(*fields)
+        readable *fields
+        writable *fields
+      end
+
+      # :call-seq:
+      #   allow :f1, ..., :fn   -> array
+      #   allow [:f1, ..., :fn]   -> array
       #
-      # Fields allowed in Jiak interactions. Returns an array of the allowed
-      # fields.
+      # Adds to the fields allowed in Jiak interactions.
       #
-      # The field <code>jiak</code> is reserved for RiakRest.
+      # Returns an array of added fields.
       #
       # Raise JiakDataException if the fields include <code>jiak</code>.
-      def allowed(*fields)
-        if(fields.include?(:jiak) || fields.include?('jiak'))
-          raise JiakDataException, "jiak field name reserved for RiakRest"
-        end
-        arr_fields = transform_fields(*fields)
-        arr_fields.each {|field| attr_accessor field}
-        @schema = JiakSchema.new(arr_fields)
-        arr_fields
+      def allow(*fields)
+        delegate_schema("allow",*fields)
       end
 
       # :call-seq:
-      #   required :f1, ..., :fn  -> array
-      #   required [:f1, ..., :fn]   -> array
+      #   require :f1, ..., :fn  -> array
+      #   require [:f1, ..., :fn]   -> array
       #
-      # Fields required during in Jiak interactions. Returns an array of the
-      # required fields.
+      # Adds to the fields required during in Jiak interactions.
       #
-      def required(*fields)
-        set_fields('required_fields',*fields)
+      # Returns an array of added fields.
+      def require(*fields)
+        delegate_schema("require",*fields)
       end
 
       # :call-seq:
       #   readable :f1, ..., :fn  -> array
       #   readable [:f1, ..., :fn]  -> array
       #
-      # Fields returned by Jiak on retrieval. Returns an array of the fields in
-      # the read mask.
+      # Adds to the fields that can be read from Jiak.
       #
+      # Returns an array of added fields.
       def readable(*fields)
-        set_fields('read_mask',*fields)
+        delegate_schema("readable",*fields)
       end
 
       # :call-seq:
       #   writable :f1, ..., :fn  -> arry
       #   writable [:f1, ..., :fn]  -> arry
       #
-      # Fields that can be written during Jiak interaction. Returns an array of
-      # the fields in the write mask.
+      # Adds to the fields that can be written to Jiak.
       #
+      # Returns an array of added fields.
       def writable(*fields)
-        set_fields('write_mask',*fields)
+        delegate_schema("writable",*fields)
       end
 
       # :call-seq:
-      #   readwrite :f1, ..., :fn  -> array
-      #   readwrite [:f1, ..., :fn]  -> array
+      #   readwrite :f1, ..., :fn  -> nil
+      #   readwrite [:f1, ..., :fn]  -> nil
+      #
+      # Adds to the fields that can be read and written.
       #
-      # Set the read and write masks to the same fields. Returns an array of
-      # the fields in the masks.
+      # Returns nil
       def readwrite(*fields)
-        arr_fields = set_fields('readwrite',*fields)
-        arr_fields
+        readable(*fields)
+        writable(*fields)
+        nil
       end
 
-      def set_fields(which,*fields)
-        arr_fields = transform_fields(*fields)
-        check_allowed(arr_fields)
-        @schema.send("#{which}=",arr_fields)
-        arr_fields
+      # Delegates adding fields to the schema, then creates attr accessors for
+      # each field added.
+      def delegate_schema(method,*fields)
+        @schema ||= JiakSchema.new
+        prev_allowed = @schema.allowed_fields
+        added_fields = @schema.send(method,*fields)
+        added_allowed = @schema.allowed_fields - prev_allowed
+        added_allowed.each {|field| attr_accessor field}
+        added_fields
       end
-      private :set_fields
+      private :delegate_schema
       
       # :call-seq:
       #   JiakData.schema  -> JiakSchema
       #
-      # Get a JiakSchema representation determined by
-      # <code>allowed, required, readable, writable</code>.
-      #
+      # Get a JiakSchema representation this data.
       def schema
-        @schema
+        @schema ||= JiakSchema.new
+        @schema.dup
+      end
+
+      # :call-seq:
+      #   JiakData.keygen(&block)  -> nil
+      #
+      # Define the key generation for an instance of the created JiakData
+      # class. Key generation will call the specified block in the scope of the
+      # current instance.
+      def keygen(&block)
+        define_method(:keygen,&block)
       end
 
       # :call-seq:
@@ -176,46 +178,57 @@ module RiakRest
       # 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.
+      # User-defined data classes must either override this method explicitly
+      # or use the <code>jattr_*</code> methods which implicitly override this
+      # method. The method is automatically called to marshall data from
+      # Jiak. 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-data class.
-      def jiak_create(json)
-        raise JiakDataException, "#{self} must define jiak_create"
+      #  def initialize(f1,f2)
+      #    @f1 = f1
+      #    @f2 = f2
+      #  end
+      #  def jiak_create(jiak)
+      #    new(jiak['f1'], jiak['f2'])
+      #  end
+      def jiak_create(jiak)
+        new(jiak)
       end
 
-      def transform_fields(*fields)
-        fields = fields[0] if(fields[0].is_a?(Array))
-        fields.map {|f| f.to_sym}
+    end
+
+    def self.included(including_class)  # :nodoc:
+      including_class.extend(ClassMethods)
+
+      define_method(:initialize) do |hash={}|
+        hash.each {|k,v| instance_variable_set("@#{k}", v)}
       end
-      private :transform_fields
 
-      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
+      define_method(:to_jiak) do
+        self.class.schema.write_mask.inject({}) do |build,field|
+          build[field] = send("#{field}")
+          build
         end
       end
-      private :check_allowed
-    end
 
-    def self.included(including_class)  # :nodoc:
-      including_class.extend(ClassMethods)
+      define_method(:eql?) do |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
+
+      define_method(:==) do |other|
+        self.class.schema.allowed_fields.reduce(true) do |same,field|
+          same && (other.send("#{field}") == (send("#{field}")))
+        end
+      end
+
+      define_method(:hash) do
+        self.class.schema.allowed_fields.inject(0) do |hsh,field|
+          hsh += send("#{field}").hash
+        end
+      end
     end
     
     # ----------------------------------------------------------------------
@@ -223,29 +236,31 @@ module RiakRest
     # ----------------------------------------------------------------------
 
     # :call-seq:
-    #   for_jiak  -> hash
+    #   to_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.
+    # this structure should come from the JiakData write mask. See JiakSchema
+    # for shema 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.
+    # User-defined data classes must either override this method explicitly or
+    # use the <code>jattr_*</code> methods which implicitly provide an implicit
+    # override. The method is automatically called to marshall data to
+    # Jiak. You do not call this method explicitly.
+
+    # Data classes that do not used the jattr_* methods to specify attributes
+    # must override this method. 
     #
     # ====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"
+    #  def to_jiak
+    #    { :writable_f1 => @writable_f1,
+    #      :writable_f2 => @writable_f2
+    #    }
+    #  end
+    def to_jiak
+      self.class.schema.write_mask.inject({}) do |build,field|
+        build[field] = send("#{field}")
+        build
+      end
     end
 
     # :call-seq:
@@ -257,15 +272,15 @@ module RiakRest
     #
     # ====Example
     # A simple implementation would look like:
-    # <code>
-    #   def keygen
-    #     f1.to_s
-    #   end
-    # </code>
+    #  def keygen
+    #    f1.to_s
+    #  end
+    #
+    # The JiakData#ClassMethods#keygen class method can also be used to
+    # override this default implement method.
     def keygen
       nil
     end
 
   end
 end
-

data/lib/riakrest/core/jiak_data_fields.rb

@@ -0,0 +1,69 @@
+module RiakRest
+  # JiakDataFields provides a easy-to-create JiakData implementation.
+  #
+  # ===Usage
+  # <code>
+  #   Dog = JiakDataFields.create(:name,:weight)
+  #
+  #   addie = Dog.new(:name => "Adelaide", :weight => 45)
+  #   addie.name                                           # => "Adeliade"
+  #   addie.weight                                         # => 45
+  #
+  #   addie.weight = 47                                    # => 47
+  # </code>
+  #
+  class JiakDataFields
+
+    # :call-seq:
+    #   JiakDataFields.create(:f1,...,fn)    -> JiakDataFields
+    #   JiakDataFields.create([:f1,...,fn])  -> JiakDataFields
+    #   JiakDataFields.create(schema)        -> JiakDataFields
+    #
+    # Creates a JiakDataFields 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
+            jattr_accessor *args[0]
+          when JiakSchema
+            jattr_reader *args[0].read_mask
+            jattr_writer *args[0].write_mask
+            allow    *args[0].allowed_fields
+            require  *args[0].required_fields
+          end
+        else
+          jattr_accessor *args
+        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
+
+      end
+    end
+
+  end
+end

data/lib/riakrest/core/jiak_link.rb

@@ -5,12 +5,10 @@ module RiakRest
   # 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
+  #  link = JiakLink.new('people','callie','sister')
+  # If the above link were added to a JiakObject <code>remy</code> , then
+  # <code>remy</code> could retrieve the sister object <code>callie</code>
+  # using JiakClient#walk with a query link
   # <code>QueryLink.new('people','sister')</code>
   #   
   class JiakLink
@@ -70,10 +68,10 @@ module RiakRest
     end
 
     # :call-seq:
-    #   link.for_jiak  -> JSON
+    #   link.to_jiak  -> JSON
     #
     # Representation of this JiakLink for transport to Jiak.
-    def for_jiak
+    def to_jiak
       [@bucket, @key, @tag]
     end
 

data/lib/riakrest/core/jiak_object.rb

@@ -1,6 +1,10 @@
 module RiakRest
 
-  # Wrapper for JiakData.
+  # JiakObject wraps a JiakData and also maintains Jiak information, Riak
+  # context, and a set a links used in conjunction with the Jiak link
+  # map/reduce facility.
+  #
+  # See JiakClient for example usage.
   class JiakObject
 
     attr_accessor :bucket, :key, :data, :links, :riak
@@ -41,12 +45,11 @@ module RiakRest
     end
 
     # :call-seq:
-    #    JiakObject.from_jiak(jiak)  -> JiakObject
+    #    JiakObject.jiak_create(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)
+    # Called by the Core Client framework when marshalling from Jiak. This
+    # method does not need to be call explicitly.
+    def self.jiak_create(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)}
@@ -58,24 +61,23 @@ module RiakRest
     end
 
     # :call-seq:
-    #    jiak_object.to_jiak  -> JSON
+    #    to_jiak  -> hash
     #
-    # 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.
+    # Called by the Core Client framework when marshalling to Jiak. This method
+    # does not need to be call explicitly.
     def to_jiak
       jiak = {
         :bucket => @bucket.name,
         :key => @key,
-        :object => @data.for_jiak,
-        :links => @links.map {|link| link.for_jiak}
+        :object => @data.to_jiak,
+        :links => @links.map {|link| link.to_jiak}
       }
       if(@riak)
         jiak[:vclock] = @riak[:vclock]
         jiak[:vtag] = @riak[:vtag]
         jiak[:lastmod] = @riak[:lastmod]
       end
-      jiak.to_json
+      jiak
     end
 
     # :call-seq: