riakrest 0.0.1

data/lib/riakrest/core/jiak_bucket.rb

@@ -0,0 +1,146 @@
+module RiakRest
+
+  # Data is stored on the Jiak server by key under a bucket. During Jiak
+  # interaction, the bucket on the server has an associated schema which
+  # determines permissible data interaction. See JiakSchema for a discussion of
+  # schemas in Jiak. Since the bucket schema can be changed dynamically,
+  # schemas can be viewed more as a loose type system rather than an onerous
+  # restriction.
+  #
+  # In RiakRest buckets have an associated JiakData class, and each JiakData
+  # class has an associated JiakSchema. These associations facility setting and
+  # maintaining the current schema in use for a Jiak bucket. Dynamically
+  # changing the bucket schema means you can have either homogeneous (simplest)
+  # or heterogenous data in a single Jiak server bucket. It also means you can
+  # define multiple JiakData classes that effectively present different "views"
+  # (via schemas) into the same data stored on the Jiak server. These classes
+  # act like types that can determine which fields are accessible for reading
+  # and writing data. The JiakData class associated with a bucket is also used
+  # to marshal user-defined data going to and from the Jiak server.
+  #
+  # JiakResource greatly eases the bookkeeping necessary for heterogenous, as
+  # well as homogenous, data interaction with the Jiak server.
+  class JiakBucket
+
+    attr_reader :schema
+    attr_accessor :name, :data_class, :params
+
+    # :call-seq:
+    #   JiakBucket.new(name,data_class,params={})  -> JiakBucket
+    #
+    # Create a bucket for use in Jiak interaction.
+    #
+    # Valid optional parameters are <code>params</code> hash are <code>:reads,
+    # :writes, :durable_writes, :waits</code>. See JiakClient#store,
+    # JiakClient#get, and JiakClient#delete for discriptions of these
+    # parameters.
+    #
+    # Raise JiakBucketException if the bucket name is not a non-empty string or
+    # the data class has not included JiakData.
+    def initialize(name,data_class,params={})
+      @name = transform_name(name)
+      @data_class = check_data_class(data_class)
+      @params = check_params(params)
+    end
+
+    # :call-seq:
+    #   name = gname
+    #
+    # Set the name of the Jiak bucket.
+    #
+    # Raise JiakBucketException if not a non-empty string.
+    def name=(gname)
+      @name = transform_name(gname)
+    end
+
+    # :call-seq:
+    #   data_class = klass
+    #
+    # Set the class for the data to be stored or retrieved from the bucket.
+    #
+    # Raise JiakBucketException if the data class has not included JiakData.
+    def data_class=(data_class)
+      @data_class = check_data_class(data_class)
+    end
+
+    # :call-seq:
+    #   bucket.params = params
+    #
+    # Set default params for Jiak client requests. See JiakBucket#new for
+    # valid parameters.
+    #
+    def params=(params)
+      @params = check_params(params)
+    end
+
+    # :call-seq:
+    #   bucket.schema  -> JiakSchema
+    #
+    # Gets the data schema for this bucket. This call does not access the
+    # server, but rather returns the schema of the current data class
+    # associated with the bucket. This association is required to establish the
+    # Jiak server schema in the first place, so as long as the Jiak server
+    # schema has not be altered by another call to JiakClient#set_schema the
+    # information returned via this call will be current.
+    def schema
+      data_class.schema
+    end
+
+    # :call-seq:
+    #    bucket == other -> true or false
+    #
+    # Equality -- JiakBuckets are equal if they contain the same attribute
+    # values.
+    def ==(other)
+      (@name == other.name &&
+       @data_class == other.data_class  &&
+       @params == other.params) rescue false
+    end
+
+    # :call-seq:
+    #    jiak_bucket.eql?(other) -> true or false
+    #
+    # Returns <code>true</code> if <i>jiak_bucket</i> and <i>other</i> contain
+    # the same attribute values.
+    def eql?(other)
+      (@name.eql?(other.name) &&
+       @data_class.eql?(other.data_class) &&
+       @params.eql?(other.params)) rescue false
+    end
+
+    def hash    # :nodoc:
+      @name.hash + @data_class.hash + @params.hash
+    end
+
+    def transform_name(name)
+      unless name.is_a?(String)
+        raise JiakBucketException, "Name must be a string"
+      end
+      b_name = name.dup
+      b_name.strip!
+      raise JiakBucketException, "Name cannot be empty" if b_name.empty?
+      b_name
+    end
+    private :transform_name
+
+    def check_data_class(data_class)
+      unless data_class.include?(JiakData)
+        raise JiakBucketException, "Data class must be type of JiakData."
+      end
+      data_class
+    end
+    private :check_data_class
+
+    def check_params(params)
+      valid = [:reads,:writes,:durable_writes,:waits]
+      err = params.select {|k,v| !valid.include?(k)}
+      unless err.empty?
+        raise JiakBucketException, "unrecognized request params: #{err.keys}"
+      end
+      params
+    end
+    private :check_params
+
+  end
+
+end

data/lib/riakrest/core/jiak_client.rb

@@ -0,0 +1,316 @@
+module RiakRest
+
+  # Restful client interaction with a Riak document store via a JSON
+  # interface. See RiakRest for a basic example usage.
+  class JiakClient
+
+    # :stopdoc:
+    APP_JSON = 'application/json'
+    JSON_DATA = 'json'
+
+    RETURN_BODY = 'returnbody'
+    READS = 'r'
+    WRITES = 'w'
+    DURABLE_WRITES = 'dw'
+    RESPONSE_WAITS = 'rw'
+
+    KEYS='keys'
+    SCHEMA='schema'
+    # :startdoc:
+
+    # :call-seq:
+    #   JiakClient.new(uri)  -> uri
+    #
+    # Create a new client for Riak RESTful (Jiak) interaction with the server at
+    # the specified URI.
+    #
+    # Raise JiakClientException if the server URI is not a string.
+    #
+    def initialize(uri='http://127.0.0.1:8002/jiak/')
+      unless uri.is_a?(String)
+        raise JiakClientException, "Jiak server URI shoud be a String."
+      end
+      @uri = uri
+      @uri += '/' unless @uri.end_with?('/')
+      @uri
+    end
+
+    # :call-seq:
+    #   set_schema(bucket)  -> nil
+    #
+    # Set the Jiak server schema for a bucket. The schema is determined by the
+    # JiakData associated with the JiakBucket.
+    #
+    # Raise JiakClientException if the bucket is not a JiakBucket.
+    #
+    def set_schema(bucket)
+      unless bucket.is_a?(JiakBucket)
+        raise JiakClientException, "Bucket must be a JiakBucket."
+      end
+      resp = RestClient.put(jiak_uri(bucket),
+                            bucket.schema.to_jiak,
+                            :content_type => APP_JSON,
+                            :data_type => JSON_DATA,
+                            :accept => APP_JSON)
+    end
+
+    # :call-seq:
+    #   schema(bucket)  -> JiakSchema
+    #
+    # Get the data schema for a bucket on a Jiak server. This involves a call
+    # to the Jiak server. See JiakBucket#schema for a way to get this
+    # information without server access.
+    def schema(bucket)
+      JiakSchema.from_jiak(bucket_info(bucket,SCHEMA))
+    end
+
+    # :call-seq:
+    #   client.keys(bucket)  -> array
+    #
+    # Get an Array of all known keys for the specified bucket. Since key lists
+    # are updated asynchronously the returned array can be out of date
+    # immediately after a put or delete.
+    def keys(bucket)
+      bucket_info(bucket,KEYS)
+    end
+
+    # :call-seq:
+    #   store(object,opts={})  -> JiakObject or key
+    #
+    # Stores user-defined data (wrapped in a JiakObject) on the Jiak
+    # server. JiakData#to_jiak is used to prepare user-defined data for JSON
+    # transport to Jiak. That call is expected to return a Ruby hash
+    # representation of the writable JiakData fields that are JSONized for HTTP
+    # transport. Successful server writes return either the storage key or the
+    # stored JiakObject depending on the option <code>key</code>. The object
+    # for storage must be JiakObject. Valid options are:
+    #
+    # <code>:object</code> :: If <code>true</code>, on success return the stored JiakObject (which includes Jiak metadata); otherwise return just the key. Default is <code>false</code>, which returns the key.
+    # <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 if a JiakObject is being returned.
+    #
+    # If any of the request parameters <code>:writes, :durable_writes,
+    # :reads</code> are not set, each first defaults to the value set for the
+    # JiakBucket in the JiakObject, then to the value set on the Riak
+    # cluster. In general the values set on the Riak cluster should suffice.
+    #
+    # Raise JiakClientException if object not a JiakObject or illegal options
+    # are passed.<br/>
+    # Raise JiakResourceException on RESTful HTTP errors.
+    #
+    def store(jobj,opts={})
+      params = jobj.bucket.params
+      req_params = {
+        WRITES => opts[:writes] || params[:writes], 
+        DURABLE_WRITES => opts[:durable_writes] || params[:durable_writes],
+        READS => opts[:reads] || params[:reads]
+      }
+      req_params[RETURN_BODY] = opts[:object]  if opts[:object]
+
+      begin
+        uri = jiak_uri(jobj.bucket,jobj.key,req_params)
+        payload = jobj.to_jiak
+        headers = { 
+          :content_type => APP_JSON,
+          :data_type => JSON_DATA,
+          :accept => APP_JSON }
+        # Decision tree:
+        #   If key empty POST
+        #   Else PUT
+        #   If object true, return JiakObject
+        #   Else
+        #    POST - parse key from location header
+        #    PUT - return the given key
+        key_empty = jobj.key.empty?
+        if(key_empty)
+          resp = RestClient.post(uri,payload,headers)
+        else
+          resp = RestClient.put(uri,payload,headers)
+        end
+        
+        if(req_params[RETURN_BODY])
+          JiakObject.from_jiak(JSON.parse(resp),jobj.bucket.data_class)
+        elsif(key_empty)
+          resp.headers[:location].split('/').last
+        else
+          jobj.key
+        end
+      rescue RestClient::ExceptionWithResponse => err
+        fail_with_response("put", err)
+      rescue RestClient::Exception => err
+        fail_with_message("put", err)
+      end
+    end
+    
+    # :call-seq:
+    #   get(bucket,key,opts={})  -> JiakObject
+    #
+    # Get data stored on a Jiak server at a bucket/key. The user-defined data
+    # stored on the Jiak server is inflated inside a JiakObject that also
+    # includes Riak storage information. Data inflation is controlled by the
+    # data class associated with the bucket of this call.
+    #
+    # Since the data schema validation that occurs on the Jiak server validates
+    # to the last schema set for that Jiak server bucket, it is imperative that
+    # schema be the same (or at least consistent) with the schema associated
+    # with this bucket at retrieval time. If you only store homogeneous objects
+    # in a bucket this will not be an issue.
+    #
+    # The bucket must be a JiakBucket and the key must be a non-empty
+    # String. Valid options are:
+    #
+    # <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
+    # JiakBucket, then to the value set on the Riak cluster. In general the
+    # values set on the Riak cluster should suffice.
+    #
+    # Raise JiakClientException if bucket not a JiakBucket.<br/>
+    # Raise JiakResourceNotFound if resource not found on Jiak server.<br/>
+    # Raise JiakResourceException on other HTTP RESTful errors.
+    #
+    def get(bucket,key,opts={})
+      unless bucket.is_a?(JiakBucket)
+        raise JiakClientException, "Bucket must be a JiakBucket."
+      end
+      req_params = {READS => opts[:reads] || bucket.params[:reads]}
+
+      begin
+        uri = jiak_uri(bucket,key,req_params)
+        resp = RestClient.get(uri, :accept => APP_JSON)
+        JiakObject.from_jiak(JSON.parse(resp),bucket.data_class)
+      rescue RestClient::ResourceNotFound => err
+        raise JiakResourceNotFound, "failed get: #{err.message}"
+      rescue RestClient::ExceptionWithResponse => err
+        fail_with_response("get", err)
+      rescue RestClient::Exception => err
+        fail_with_message("get",err)
+      end
+    end
+
+    # :call-seq:
+    #   delete(bucket,key,opts={})  -> true or false
+    #
+    # Delete the JiakObject stored at the bucket/key. Valid options are:
+    #
+    # <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 JiakBucket, then to the value set on the Riak
+    # cluster. In general the values set on the Riak cluster should suffice.
+    #
+    # Raise JiakResourceException on RESTful HTTP errors.
+    #
+    def delete(bucket,key,opts={})
+      begin
+        req_params = {RESPONSE_WAITS => opts[:waits] || bucket.params[:waits]}
+        uri = jiak_uri(bucket,key,req_params)
+        RestClient.delete(uri, :accept => APP_JSON)
+        true
+      rescue RestClient::ExceptionWithResponse => err
+        fail_with_response("delete", err)
+      rescue RestClient::Exception => err
+        fail_with_message("delete", err)
+      end
+    end
+
+    # :call-seq:
+    #   walk(bucket,key,query,data_class)  -> array
+    #
+    # Return an array of JiakObjects retrieved by walking a query links
+    # array starting with the links for the object at bucket/key. The
+    # data_class is used to inflate the data objects returned in the
+    # JiakObject array.
+    #
+    # See QueryLink for a description of the <code>query</code> structure.
+    def walk(bucket,key,query,data_class)
+      begin
+        start = jiak_uri(bucket,key)
+        case query
+        when QueryLink
+          uri = start+'/'+query.for_uri
+        when Array
+          uri = query.inject(start) {|build,link| build+'/'+link.for_uri}
+        else
+          raise QueryLinkException, 'failed: query must be '+
+            'a QueryLink or an Array of QueryLink objects'
+        end
+        resp = RestClient.get(uri, :accept => APP_JSON)
+        # JSON.parse(resp)['results'][0]
+        JSON.parse(resp)['results'][0].map do |jiak|
+          JiakObject.from_jiak(jiak,data_class)
+        end
+      rescue RestClient::ExceptionWithResponse => err
+        fail_with_response("put", err)
+      rescue RestClient::Exception => err
+        fail_with_message("put", err)
+      end
+    end
+
+    # :call-seq:
+    #   client.uri  -> string
+    #
+    # String representation of the base URI of the Jiak server.
+    def uri
+      @uri
+    end
+
+    # :call-seq:
+    #    client == other -> true or false
+    #
+    # Equality -- JiakClients are equal if they have the same URI
+    def ==(other)
+      (@uri == other.uri) rescue false
+    end
+    
+    # :call-seq:
+    #    eql?(other) -> true or false
+    #
+    # Returns <code>true</code> if <code>other</code> is a JiakClint with the
+    # same URI.
+    def eql?(other)
+      other.is_a?(JiakClient) &&
+        @uri.eql?(other.uri)
+    end
+
+    def hash    # :nodoc:
+      @uri.hash
+    end
+
+    # Build the URI for accessing the Jiak server.
+    def jiak_uri(bucket,key="",params={})
+      uri = "#{@uri}#{URI.encode(bucket.name)}"
+      uri += "/#{URI.encode(key)}" unless key.empty?
+      qstring = params.reject {|k,v| v.nil?}.map{|k,v| "#{k}=#{v}"}.join('&')
+      uri += "?#{URI.encode(qstring)}"  unless qstring.empty?
+      uri
+    end
+    private :jiak_uri
+    
+    # Get either the schema or keys for the bucket.
+    def bucket_info(bucket,info)
+      ignore = (info == SCHEMA) ? KEYS : SCHEMA
+      begin
+        uri = jiak_uri(bucket,"",{ignore => false})
+        JSON.parse(RestClient.get(uri, :accept => APP_JSON))[info]
+      rescue RestClient::ExceptionWithResponse => err
+        fail_with_response("get", err)
+      rescue RestClient::Exception => err
+        fail_with_message("get", err)
+      end
+    end
+    private :bucket_info
+
+    def fail_with_response(action,err)
+      raise( JiakResourceException,
+             "failed #{action}: HTTP code #{err.http_code}: #{err.http_body}")
+    end
+    private :fail_with_response
+
+    def fail_with_message(action,err)
+      raise JiakResourceException, "failed #{action}: #{err.message}"
+    end
+    private :fail_with_message
+
+  end
+
+end