riakrest 0.0.1

data/lib/riakrest.rb

@@ -0,0 +1,164 @@
+# See README.rdoc for the RiakRest license.
+
+begin
+  require 'json'
+rescue LoadError
+  raise "RiakRest requires json for REST JSON messaging."
+end
+begin
+  require 'restclient'
+rescue LoadError
+  raise <<EOM
+RiakRest requires the restclient gem for making REST calls.
+  gem install rest-client
+
+EOM
+end
+
+require 'uri'
+
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || 
+  $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+# RiakRest provides structured, RESTful interaction with a Riak document
+# store. In Riak parlance, this JSON data exchange is called Jiak. RiakRest
+# provides two levels of interaction: Core Client and Resource. Core Client
+# interaction works down at the Jiak level and so exposes Jiak
+# internals. Resource interaction abstracts above that and is much easier to
+# use. But we'll show the Core Client first since Resource is built on top of
+# it.
+#
+# ===Core Client Interaction
+# Primary Jiak constructs are represented by core Jiak classes:
+# JiakClient :: Client used to make Jiak store, get, delete, and other calls.
+# JiakBucket :: Bucket name and the data class stored in the bucket.
+# JiakSchema :: Schema used by a Jiak server bucket.
+# JiakData :: Class to define user data to be stored on a Jiak server.
+# JiakObject :: Jiak object wrapper that includes the user-defined data.
+# JiakLink :: Jiak link objects for associations between Jiak server data.
+# QueryLink :: Link objects to query Jiak link associations.
+#
+# ====Example Usage
+# This example works at the Jiak core layer. See the Resource example below for
+# an abstraction layered on top of this core.
+# <code>
+#   require 'riakrest'
+#   include RiakRest
+# </code>
+# Create a simple class to hold Person data.
+# <code>
+#   Person = JiakDataHash.create(:name,:age)
+# </code>
+# Create a client, a bucket to hold the data, and set the bucket schema for
+# structured interaction.
+# <code>
+#   client = JiakClient.new("http://localhost:8002/jiak")
+#   bucket = JiakBucket.new('person',Person)
+#   client.set_schema(bucket)
+# </code>
+# Wrap a Person data object in a JiakObject and store it. Check the data on the
+# server to see it's really there.
+# <code>
+#   remy = client.store(JiakObject.new(:bucket => bucket,
+#                                      :data => Person.new(:name => "remy",
+#                                                           :age => 10)),
+#                       :object => true)
+#   puts client.get(bucket,remy.key).data.name         # => "remy"
+# </code>
+# Change the data via accessors and update. Again, we print the server value.
+# <code>
+#   remy.data.name                                     # => "remy"
+#   remy.data.name = "Remy"
+#   client.store(remy)
+#   puts client.get(bucket,remy.key).data.name         # => "Remy"
+# </code>
+# Let's add another person and a link between them.
+# <code>
+#   callie = client.store(JiakObject.new(:bucket => bucket,
+#                                        :data => Person.new(:name => "Callie",
+#                                                            :age => 12)),
+#                         :object => true)
+#   remy << JiakLink.new(bucket,callie.key,'sister')
+#   client.store(remy)
+# </code>
+# Now we can get callie as the sister of remy:
+# <code>
+#   sisters = client.walk(bucket,remy.key,QueryLink.new(bucket,'sister'),Person)
+#   sisters[0].eql?(callie)                           # => true
+# </code>
+# Finally, we'll delete the objects on the way out the door.
+# <code>
+#   client.delete(bucket,remy.key)
+#   client.delete(bucket,callie.key)
+# </code>
+#
+# ===Resource Interaction
+# Much of the above code can be abstracted into resource-based
+# interaction. RiakRest provides a module JiakResource that allows you to
+# create resource objects that encapsulate a lot of the cruft of core client
+# interaction. We'll do the same steps as above using resources.
+# <code>
+#   require 'riakrest'
+#   include RiakRest
+#   
+#   PersonData = JiakDataHash.create(:name,:age)
+#   PersonData.keygen :name
+#   
+#   class Person
+#     include JiakResource
+#     server      'http://localhost:8002/jiak'
+#     group       'people'
+#     data_class  PersonData
+#   end
+#   
+#   remy = Person.new(:name => 'remy', :age => 10)
+#   remy.post
+#   puts Person.get('remy').name                # => "remy"
+#   
+#   remy.name = "Remy"
+#   remy.update
+#   puts Person.get('remy').name                # => "Remy"
+#   
+#   callie = Person.new(:name => 'Callie', :age => 12).post
+#   remy.link(callie,'sister').update
+#   
+#   sisters = remy.walk(Person,'sister')
+#   sisters[0].eql?(callie)                     # => true
+#   
+#   remy.delete
+#   callie.delete
+# </code>
+# Ah, that feels better. Go forth and Riak!
+module RiakRest
+end
+
+require 'riakrest/version'
+
+require 'riakrest/core/exceptions'
+require 'riakrest/core/jiak_bucket'
+require 'riakrest/core/jiak_client'
+require 'riakrest/core/jiak_data'
+require 'riakrest/core/jiak_link'
+require 'riakrest/core/jiak_object'
+require 'riakrest/core/jiak_schema'
+require 'riakrest/core/query_link'
+
+require 'riakrest/data/jiak_data_hash'
+
+require 'riakrest/resource/jiak_resource'
+
+# Extend Array with convenience methods for comparing array contents.
+class Array
+  # Compare arrays for same elements regardless of order.
+  def same_elements?(arr)
+    raise ArgumentError unless arr.is_a?(Array)
+    (size == arr.size) && arr.reduce(true){|same,elem| same && include?(elem)}
+  end
+
+  # Compare arrays for same element.to_s values regardless of order.
+  def same_fields?(arr)
+    raise ArgumentError unless arr.is_a?(Array)
+    (size == arr.size) && map{|f| f.to_s}.same_elements?(arr.map{|f| f.to_s})
+  end
+end

data/riakrest.gemspec

@@ -0,0 +1,38 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{riakrest}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Paul Rogers"]
+  s.date = %q{2009-10-29}
+  s.description = %q{RiakRest provides structured, RESTful interaction with a Riak document
+store. In Riak parlance, this JSON data exchange is called Jiak. RiakRest
+provides two levels of interaction: Core Client and Resource. Core Client
+interaction works down at the Jiak level and exposes Jiak internals. Resource
+interaction is an abstraction built on top of the Core Client.}
+  s.email = ["paul@dingosky.com"]
+  s.extra_rdoc_files = ["History.txt", "Manifest.txt", "PostInstall.txt"]
+  s.files = ["History.txt", "Manifest.txt", "PostInstall.txt", "README.rdoc", "Rakefile", "examples/auto_update_data.rb", "examples/auto_update_links.rb", "examples/basic_client.rb", "examples/basic_resource.rb", "examples/json_data_resource.rb", "examples/linked_resource.rb", "examples/multiple_resources.rb", "lib/riakrest.rb", "lib/riakrest/core/exceptions.rb", "lib/riakrest/core/jiak_bucket.rb", "lib/riakrest/core/jiak_client.rb", "lib/riakrest/core/jiak_data.rb", "lib/riakrest/core/jiak_link.rb", "lib/riakrest/core/jiak_object.rb", "lib/riakrest/core/jiak_schema.rb", "lib/riakrest/core/query_link.rb", "lib/riakrest/data/jiak_data_hash.rb", "lib/riakrest/resource/jiak_resource.rb", "lib/riakrest/version.rb", "riakrest.gemspec", "script/console", "script/destroy", "script/generate", "spec/core/exceptions_spec.rb", "spec/core/jiak_bucket_spec.rb", "spec/core/jiak_client_spec.rb", "spec/core/jiak_link_spec.rb", "spec/core/jiak_object_spec.rb", "spec/core/jiak_schema_spec.rb", "spec/core/query_link_spec.rb", "spec/data/jiak_data_hash_spec.rb", "spec/resource/jiak_resource_spec.rb", "spec/riakrest_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "tasks/rspec.rake"]
+  s.homepage = %q{http://github.com/wcpr/riakrest}
+  s.post_install_message = %q{PostInstall.txt}
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{riakrest}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{RiakRest provides structured, RESTful interaction with a Riak document store}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<hoe>, [">= 2.3.3"])
+    else
+      s.add_dependency(%q<hoe>, [">= 2.3.3"])
+    end
+  else
+    s.add_dependency(%q<hoe>, [">= 2.3.3"])
+  end
+end

data/script/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# File: script/console
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+# Perhaps use a console_lib to store any extra methods I may want available in the cosole
+# libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/riakrest.rb'}"
+puts "Loading riakrest gem"
+exec "#{irb} #{libs} --simple-prompt"

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)

data/script/generate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/generate'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Generate.new.run(ARGV)

data/spec/core/exceptions_spec.rb

@@ -0,0 +1,18 @@
+require File.dirname(__FILE__) + '/../spec_helper.rb'
+
+describe "Jiak exceptions" do
+  it "should all be a kind of RiakRest::Exception" do
+    JiakResourceException.new.should be_a_kind_of RiakRest::Exception
+    JiakResourceNotFound.new.should be_a_kind_of RiakRest::Exception
+    JiakClientException.new.should be_a_kind_of RiakRest::Exception
+    JiakObjectException.new.should be_a_kind_of RiakRest::Exception
+    JiakSchemaException.new.should be_a_kind_of RiakRest::Exception
+    JiakLinkException.new.should be_a_kind_of RiakRest::Exception
+  end
+end
+
+describe "JiakResource hierarchy" do
+  it "should have resource not found" do
+    JiakResourceNotFound.new.should be_a_kind_of JiakResourceException
+  end
+end

data/spec/core/jiak_bucket_spec.rb

@@ -0,0 +1,103 @@
+require File.dirname(__FILE__) + '/../spec_helper.rb'
+
+describe "JiakBucket" do
+  before do
+    @name = 'bucket_name'
+    @data_class = JiakDataHash.create(:f1,:f2)
+    @params = {:reads => 1, :writes => 2, :durable_writes => 3, :waits => 4}
+    @bucket = JiakBucket.new(@name,@data_class)
+  end
+
+  it "should respond to" do
+    @bucket.should respond_to(:name,:data_class,:params,:schema)
+    @bucket.should respond_to(:name=,:data_class=,:params=)
+    @bucket.should respond_to(:eql?)
+  end
+
+  it "should initialize with name and data class" do
+    @bucket.name.should eql @name
+    @bucket.data_class.should eql @data_class
+    @bucket.params.should be_empty
+  end
+
+  it "should initialize with name, data class, and params" do
+    bucket = JiakBucket.new(@name,@data_class,@params)
+    bucket.name.should eql @name
+    bucket.data_class.should eql @data_class
+    bucket.params.should have_exactly(4).items
+    @params.each {|k,v| bucket.params[k].should == @params[k]}
+
+    @params.delete(:writes)
+    bucket = JiakBucket.new(@name,@data_class,@params)
+    bucket.params.should have_exactly(3).items
+    bucket.params[:waits].should == @params[:waits]
+  end
+
+  it "should update the name,data class, and params" do
+    # name = 'new_bucket_name'
+    # @bucket.name = name
+    # @bucket.name.should eql name
+
+    data_class = JiakDataHash.create(:g1)
+    @bucket.data_class = data_class
+    @bucket.data_class.should eql data_class
+
+    @bucket.params.should be_empty
+    @bucket.params = @params
+    @bucket.params.should eql @params
+  end
+
+  it "should validate name, data class, and params" do
+    empty_name = lambda {JiakBucket.new("",@data_class)}
+    empty_name.should raise_error(JiakBucketException,/Name.*empty/)
+
+    empty_name = lambda {JiakBucket.new("  ",@data_class)}
+    empty_name.should raise_error(JiakBucketException,/Name.*empty/)
+
+    nil_name = lambda {JiakBucket.new(nil,@data_class)}
+    nil_name.should raise_error(JiakBucketException,/Name.*string/)
+
+    bad_data_class = lambda {JiakBucket.new(@name,Hash)}
+    bad_data_class.should raise_error(JiakBucketException,/JiakData/)
+
+    bad_data_class = lambda {@bucket.data_class = Hash}
+    bad_data_class.should raise_error(JiakBucketException,/JiakData/)
+
+    params = @params
+    params.delete(:writes)
+    params[:write] = 2
+    bad_params = lambda {JiakBucket.new(@name,@data_class,params)}
+    bad_params.should raise_error(JiakBucketException,/params/)
+
+    bad_params = lambda {@bucket.params = params}
+    bad_params.should raise_error(JiakBucketException,/params/)
+  end
+
+  it "should provide the schema for the data class" do
+    @bucket.schema.should eql @data_class.schema
+  end
+
+  it "should eql by state" do
+    bucket = JiakBucket.new(@name,@data_class)
+    bucket.should eql @bucket
+
+    bucket = JiakBucket.new(@name.upcase,@data_class)
+    bucket.should_not eql @bucket
+
+    data_class = JiakDataHash.create(:g1)
+    bucket = JiakBucket.new(@name,data_class)
+    bucket.should_not eql @bucket
+
+    bucket = JiakBucket.new(@name,@data_class,@params)
+    bucket.should_not eql @bucket
+
+    @bucket.params = @params
+    bucket.should eql @bucket
+
+    params = {:reads => @params[:reads]+1}
+    bucket_1 = JiakBucket.new(@name,@data_class,@params)
+    bucket_2 = JiakBucket.new(@name,@data_class,params)
+    bucket_1.should_not eql bucket_2
+  end
+
+end