riakrest 0.1.2 → 0.1.5

data/History.txt

@@ -1,3 +1,9 @@
+=== 0.1.5 2009-12-11
+  - Added POV processing.
+  - Refactored jattr_* to attr_*.
+  - Added opts to query, which forced steps arg to be an explicit array.
+  - Changes to examples for web site.
+
 === 0.1.2 2009-11-29
   - Add wide open schemas.
   - Add wild card schema arrays.

data/README.rdoc

@@ -1,43 +1,43 @@
-= RiakRest
+= RiakREST
 
-http://github.com/wcpr/riakrest
+More information available at RiakREST[http://riakrest.com/].
 
-== DESCRIPTION:
+== Description:
 
-RiakRest provides structured, RESTful interaction with a Riak document
-store.
+RiakREST is a Ruby library providing structured, RESTful interaction with
+Riak[http://riak.basho.com], an open-source document datastore.
 
-== RIAK:
+== Riak:
 
 Riak[http://riak.basho.com] is an open-source project developed and maintained
 by the fine folks at Basho[http://www.basho.com] Technologies. Riak combines a
 decentralized key-value store, a flexible map/reduce engine, and a friendly
 HTTP/JSON query interface to provide a database ideally suited for Web
-applications. RiakRest interacts with the HTTP/JSON query interface, which is
-called Jiak.
+applications.
 
-== SYNOPSIS:
+== RiakREST
 
-RiakRest provides structured, RESTful interaction with the HTTP/JSON interface
-of a Riak[http://riak.basho.com] document data store. RiakRest provides two
-levels of interaction: Core Client and Resource. Core Client works at the Jiak
-level and exposes Jiak internals. JiakResource is an abstraction built on top
-of the Core Client that gives a true RESTful feel.
+RiakREST provides Ruby interaction with Jiak, the HTTP/JSON interface to a Riak
+cluster, through two different levels of Jiak interaction: Core Client and
+Resource. Core Client works at the Jiak level and mirrors Jiak internals,
+whereas, Resource is an abstraction built on top of the Core Client that
+gives a simplier, RESTful feel.
 
-== REQUIREMENTS:
+== Requirements:
 
-RestClient is used for REST server interaction.
+RestClient (Ruby gem rest-client) is used for RESTful server interaction.
 
 JSON is used for data exchange.
 
-Riak[http://riak.basho.com] provides the HTTP/JSON Jiak interface and data
+Riak[http://riak.basho.com] provides the runs the server cluser and provides
+the Jiak HTTP/JSON interface.
 store.
 
-== INSTALL:
+== Install:
 
 sudo gem install riakrest
 
-== EXAMPLE
+== Example
   require 'riakrest'
   include RiakRest
 
@@ -45,22 +45,32 @@ sudo gem install riakrest
     include JiakResource
     server 'http://localhost:8002/jiak'
     jattr_accessor :name, :age
-    auto_manage
   end
 
-  remy = People.new(:name => 'Remy',:age => 10)    # (auto-post)
-  remy.age = 11                                    # (auto-update)
+  # Created and store a resource.
+  remy = Person.new(:name => 'Remy',:age => 10)
+  remy.post
+
+  # Change and store
+  remy.age = 11
+  remy.put
 
-  callie = People.new(:name => 'Callie', :age => 13)
+  # Create another resource
+  callie = Person.new(:name => 'Callie', :age => 13)
+  callie.post
+  
+  # Add a link from remy to callie tagged as 'sister'
   remy.link(callie,'sister')
+  remy.put
 
-  sisters = remy.query(People,'sister')
+  # Retrieve sister via link
+  sisters = remy.query([Person,'sister'])
   puts sisters[0].eql?(callie)                     # => true
 
   remy.delete
   callie.delete
 
-== LICENSE:
+== License:
 
 Copyright (c) 2009 Paul Rogers, DingoSky. See LICENSE for details.
 

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.5

data/examples/auto_manage_data.rb

@@ -0,0 +1,51 @@
+require File.dirname(__FILE__) + '/example_helper.rb'
+
+# Simple resource set to auto-manage instances. Auto-manage does both auto-post
+# and auto-update.
+class Person
+  include JiakResource
+  server         SERVER_URI
+  attr_accessor :name, :age
+  keygen { name }
+  auto_manage
+end
+
+# Convenience method for showing results
+def show_jiak_values
+  rsrc = Person.get('remy')
+  puts "name:#{rsrc.name}, age:#{rsrc.age}"
+end
+
+# Create resource. Auto-manage auto-posts the create.
+remy = Person.new(:name => 'remy', :age => 10)
+show_jiak_values                                       # => remy, 10
+
+# Changes are auto-updated
+remy.name = "Remy"
+show_jiak_values                                       # => Remy, 10
+remy.age = 12
+show_jiak_values                                       # => Remy, 12
+
+# Auto-update can be set at class and instance level
+Person.auto_update false
+remy.auto_update = true
+remy.age = 10
+show_jiak_values                                       # => Remy, 10
+
+# Instance level setting overrides class level setting
+Person.auto_update true
+remy.auto_update = false
+remy.age = 12
+show_jiak_values                                       # => Remy, 10
+remy.update
+show_jiak_values                                       # => Remy, 12
+
+# Due to class level interaction, set instance level to nil to get class level
+remy.auto_update = nil
+remy.age = 10
+show_jiak_values                                       # => Remy, 10
+
+# Clean-up
+remy.delete
+
+

data/examples/auto_update_links.rb

@@ -1,43 +1,60 @@
 require File.dirname(__FILE__) + '/example_helper.rb'
 
-class People
+# Simple resource used to show auto-updating of links.
+class Person
   include JiakResource
   server         SERVER_URI
-  jattr_accessor :name, :age
+  attr_accessor :name, :age
   keygen { name.downcase }
   auto_post
 end
 
-remy = People.new(:name => 'remy', :age => 10)
-callie = People.new(:name => 'Callie', :age => 12)
+# Convenience method for checking number of links
+def check_num_links(rsrc,tag,expect)
+  num = rsrc.query([Person,tag]).size
+  puts " #{expect}? #{num == expect}"
+end
+
+# Create resources. (Auto-posted)
+remy = Person.new(:name => 'remy', :age => 10)
+callie = Person.new(:name => 'Callie', :age => 12)
 
+# Add links. Class-level auto-post does not trigger auto-update.
 remy.link(callie,'sister')
-puts remy.query(People,'sister').size              # => 0
+check_num_links(remy,'sister',0)                           # => true
 remy.update
-puts remy.query(People,'sister').size              # => 1
+check_num_links(remy,'sister',1)                           # => true
 remy.remove_link(callie,'sister')
+remy.update
+check_num_links(remy,'sister',0)                           # => true
 
-People.auto_update true
+# Turn on class level auto-update.
+Person.auto_update true
 remy.link(callie,'sibling')
-puts remy.query(People,'sibling').size             # => 1
+check_num_links(remy,'sibling',1)                          # => true
 remy.remove_link(callie,'sibling')
 
+# Instance level auto-update settings.
 callie.auto_update = false
 callie.link(remy,'sibling')
-puts callie.query(People,'sibling').size           # => 0
+check_num_links(callie,'sibling',0)                        # => true
 callie.update
-puts callie.query(People,'sibling').size           # => 1
+check_num_links(callie,'sibling',1)                        # => true
 callie.remove_link(remy,'sibling')
 
-People.auto_update false
+# Another permutation of class and instance level auto-update settings.
+Person.auto_update false
 remy.auto_update = true
 callie.auto_update = nil
+
+# bi_link create links in both directions.
 remy.bi_link(callie,'sisters')
-puts remy.query(People,'sisters').size             # => 1
-puts callie.query(People,'sisters').size           # => 0
+check_num_links(remy,'sisters',1)                          # => true
+check_num_links(callie,'sisters',0)                        # => true
 callie.update
-puts callie.query(People,'sisters').size           # => 1
+check_num_links(callie,'sisters',1)                        # => true
 
+# Clean-up
 remy.delete
 callie.delete
 

data/examples/basic_client.rb

@@ -1,34 +1,57 @@
 require File.dirname(__FILE__) + '/example_helper.rb'
 
-class PeopleData
+# Simple JiakData class with a couple of attributes
+class PersonData
   include JiakData
-  jattr_accessor :name, :age
+  attr_accessor :name, :age
 end
 
 client = JiakClient.new(SERVER_URI)
-bucket = JiakBucket.new('people',PeopleData)
+bucket = JiakBucket.new('people',PersonData)
+
+puts bucket.name                              # => 'people'
+puts bucket.data_class                        # => PeopleData
+puts bucket.data_class.schema                 # => JiakSchema of data
+puts bucket.schema                            # => Same as above
+
+# The default schema for a Riak bucket is the WIDE_OPEN schema.
+puts client.schema(bucket)                    # => JiakSchema of server bucket.
 client.set_schema(bucket)
+puts client.schema(bucket)                    # => Server schema now data schema
 
+# Create and store Jiak objects. Keys are server generated. JiakObjects with
+# Riak context are returned.
 remy = client.store(JiakObject.new(:bucket => bucket,
-                                    :data => PeopleData.new(:name => "remy",
+                                   :data => PersonData.new(:name => "remy",
                                                             :age => 10)),
                     :return => :object)
 callie = client.store(JiakObject.new(:bucket => bucket,
-                                     :data => PeopleData.new(:name => "Callie",
+                                     :data => PersonData.new(:name => "Callie",
                                                              :age => 12)),
                       :return => :object)
 
-puts client.get(bucket,remy.key).data.name                         # => "remy"
+puts remy.key                                 # => server generated key
+puts remy.data                                # => PersonData
+puts remy.data.name                           # => remy
+puts remy.data.age                            # => 10
 
+# Change data and show server value
 remy.data.name = "Remy"
-remy << JiakLink.new(bucket,callie.key,'sister')
 client.store(remy)
+puts client.get(bucket,remy.key).data.name    # => Remy
 
-puts client.get(bucket,remy.key).data.name                         # => "Remy"
+# Add a link from remy to callie tagged as sister, and show links
+remy << JiakLink.new(bucket,callie.key,'sister')
+client.store(remy)
+puts remy.links                               # => JiakLink
 
+# Follow the sister link and test that callie is in the returned array
 sisters = client.walk(bucket,remy.key,
-                      QueryLink.new(bucket,'sister'),PeopleData)
-puts sisters[0].eql?(callie)                                       # => true
+                      QueryLink.new(bucket,'sister'),PersonData)
+puts sisters.include?(callie)                 # => true
+puts sisters.size                             # => 1
+puts sisters[0].data.name                     # => "Callie"
 
+# Clean-up
 client.delete(bucket,remy.key)
 client.delete(bucket,callie.key)

data/examples/basic_resource.rb

@@ -1,27 +1,44 @@
 require File.dirname(__FILE__) + '/example_helper.rb'
 
-class People
+# Simple JiakResource with a couple of attributes
+class Person
   include JiakResource
   server SERVER_URI
-  jattr_accessor :name, :age
+  attr_accessor :name, :age
   keygen {name.downcase}
-  auto_manage
 end
 
-remy = People.new(:name => 'Remy',:age => 10)    #            (auto-post)
-puts remy.name                                   # => "Remy"
+# Convenience method for showing results
+def show_jiak_values
+  rsrc = Person.get('remy')
+  puts "name:#{rsrc.name}, age:#{rsrc.age}"
+end
+
+# Created and store a resource.
+remy = Person.new(:name => 'Remy',:age => 10)
+puts "name:#{remy.name}, age:#{remy.age}"     # => Remy, 10
+remy.post
+show_jiak_values                              # => Remy, 10
 
-puts People.get('remy').name                     # => "Remy"  (from Jiak server)
-puts People.get('remy').age                      # => 10      (from Jiak server)
+# Change and store
+remy.age = 11
+remy.put
+show_jiak_values                              # => Remy, 11
 
-remy.age = 11                                    #            (auto-update)
-puts People.get('remy').age                      # => 11      (from Jiak server)
+# Create another resource
+callie = Person.new(:name => 'Callie', :age => 13)
+callie.post
 
-callie = People.new(:name => 'Callie', :age => 13)
+# Add a link from remy to callie tagged as 'sister'
 remy.link(callie,'sister')
+remy.put
 
-sisters = remy.query(People,'sister')
-puts sisters[0].eql?(callie)                     # => true
+# Retrieve sister via link
+sisters = remy.query([Person,'sister'])
+puts sisters.include?(callie)                 # => true
+puts sisters.size                             # => 1
+puts sisters[0].name                          # => "Callie"
 
+# Clean-up
 remy.delete
 callie.delete

data/examples/basic_resource_pov.rb

@@ -0,0 +1,65 @@
+require File.dirname(__FILE__) + '/example_helper.rb'
+
+class AB
+  include JiakResource
+  server SERVER_URI
+  group  "test"
+  attr_accessor :a, :b
+  keygen { "k#{a}" }
+end
+
+class A
+  include JiakResourcePOV
+  resource AB
+  attr_accessor :a
+end
+
+class B
+  include JiakResourcePOV
+  resource AB
+  attr_accessor :b
+end
+
+# Store data using AB
+puts "POST ab.a=1, ab.b=2"
+ab = AB.new(:a => 1, :b => 2)
+ab.post
+
+# Get POVs using two different mechanisms.
+a = ab.pov(A)
+b = B.get('k1')
+puts "a=#{ab.a}, b=#{ab.b}"                                   # => a=1, b=2
+puts "ab.a and a.a equal   1? #{ab.a == 1 && ab.a == a.a}"    # =>   1? true
+puts "ab.b and b.b equal   2? #{ab.b == 2 && ab.b == b.b}"    # =>   2? true
+
+# Update data using AB
+puts "\nPUT ab.a=11"
+ab.a = 11
+ab.update
+a.refresh
+b.refresh
+puts "a = #{ab.a}, b = #{ab.b}"                               # => a=11, b=2
+puts "ab.a and a.a equal  11? #{ab.a == 11 && ab.a == a.a}"   # =>  11? true
+puts "ab.b and b.b equal   2? #{ab.b == 2  && ab.b == b.b}"   # =>   2? true
+
+# Update data using A
+puts "\nPUT a.a=111"
+a.a = 111
+a.update
+ab.refresh
+b.refresh
+puts "a = #{ab.a}, b = #{ab.b}"                               # => a=111, b=2
+puts "ab.a and a.a equal 111? #{ab.a == 111 && ab.a == a.a}"  # => 111? true
+puts "ab.b and b.b equal   2? #{ab.b == 2   && ab.b == b.b}"  # =>   2? true
+
+# Update data using B
+puts "\nPUT b.b=22"
+b.b = 22
+b.update
+ab.refresh
+a.refresh
+puts "a = #{ab.a}, b = #{ab.b}"                               # => a=111, b=22
+puts "ab.a and a.a equal 111? #{ab.a == 111 && ab.a == a.a}"  # => 111? true
+puts "ab.b and b.b equal  22? #{ab.b == 22  && ab.b == b.b}"  # =>  22? true
+
+ab.delete

data/examples/buoy.rb

@@ -0,0 +1,102 @@
+require File.join(File.dirname(__FILE__), 'example_helper.rb')
+
+# Primary resource declares server URI, and optional group and keygen, along
+# with full complement of attributes.
+class Buoy
+  include JiakResource
+
+  server SERVER_URI
+  group "buoy"
+  keygen { name }
+
+  attr_accessor :name
+  attr_accessor :lat, :lon
+  attr_accessor :wind_u, :wind_v, :temp_air
+  attr_accessor :temp_0,  :salt_0
+  attr_accessor :temp_10, :salt_10
+  attr_accessor :temp_20, :salt_20
+end
+
+# POVs declares an existing JiakResource and a subset of attributes, which can
+# be read, write, or both.
+class BuoySurface
+  include JiakResourcePOV
+  resource Buoy
+
+  attr_reader   :name
+  attr_reader   :lat, :lon
+  attr_accessor :wind_u, :wind_v, :temp_air
+  attr_accessor :temp_0, :salt_0
+end
+
+class BuoyChain
+  include JiakResourcePOV
+  resource Buoy
+
+  attr_accessor :temp_0,  :salt_0
+  attr_accessor :temp_10, :salt_10
+  attr_accessor :temp_20, :salt_20
+end
+
+class BuoyWind
+  include JiakResourcePOV
+  resource Buoy
+
+  attr_reader   :name
+  attr_accessor :wind_u, :wind_v
+end
+
+class BuoySST
+  include JiakResourcePOV
+  resource Buoy
+
+  attr_reader :name, :temp_0
+end
+
+# A simple resource for a region of buoys
+class Region
+  include JiakResource
+  server  SERVER_URI
+  group 'region'
+  
+  attr_accessor :name
+end
+
+
+# Some data and a loading mechanism
+M0 = ["M0",[36.83, -121.90], [2.51, 3.12],
+      [15.04, 14.98, 14.85, 13.22], [33.34, 33.38, 33.84]]
+M1 = ["M1",[36.75, -122.03], [3.35, 2.42],
+      [15.54, 14.43, 14.41, 14.01], [33.37, 33.43, 33.41]]
+M2 = ["M2",[36.70, -122.39], [0.51, 0.44],
+      [14.24, 14.03, 13.80, 13.82], [33.20, 33.11, 33.03]]
+
+BUOYS = [M0,M1,M2]
+
+class BuoyData
+  def self.load(m)
+    b = {}
+    b[:name] = m[0]
+    b[:lat],b[:lon] = m[1][0],m[1][1]
+    b[:wind_u],b[:wind_v] = m[2][0],m[2][1]
+    b[:temp_air],b[:temp_0],b[:temp_10],b[:temp_20] = 
+      m[3][0],m[3][1],m[3][2],m[3][3]
+    b[:salt_0],b[:salt_10],b[:salt_20] = m[4][0],m[4][1],m[4][2]
+    b
+  end
+
+end
+
+def show_data(rsrc)
+  if(rsrc.class.include?(JiakResourcePOV))
+    read_mask = rsrc.class.jiak.read_mask.split(',')
+  else
+    read_mask = rsrc.class.jiak.bucket.schema.read_mask
+  end
+  arr = read_mask.map do |field|
+    val = rsrc.send(field)
+    "#{field.to_s}= #{val}"
+  end
+  puts " #{rsrc.class}: #{arr.join(',')}"
+end
+

data/examples/buoy_pov.rb

@@ -0,0 +1,46 @@
+# buoy.rb contains resource and POV class declarations
+require File.join(File.dirname(__FILE__), 'buoy')
+
+# Load buoy data
+buoy0,buoy1,buoy2 = 
+  BUOYS.map {|m| BuoyData.load(m)}.map {|b| Buoy.new(b)}.each {|m| m.post}
+
+# Loaded data for Buoy, BuoySurface, and BuoySST
+buoy0_srf = buoy0.pov(BuoySurface)
+buoy0_sst = buoy0.pov(BuoySST)
+puts "Loaded data"
+show_data(buoy0)
+show_data(buoy0_srf)
+show_data(buoy0_sst)
+
+# Change SST via BuoySurface POV
+buoy0_srf.temp_0 = 14.99
+buoy0_srf.update
+buoy0.refresh
+buoy0_sst.refresh
+puts
+puts "SST set to 14.99 via BuoySurface POV"
+show_data(buoy0)
+show_data(buoy0_srf)
+show_data(buoy0_sst)
+
+# Create a region and link the 3 buoys
+mbay = Region.new(:name => 'Monterey Bay')
+mbay.post
+[buoy0,buoy1,buoy2].each {|buoy| mbay.link(buoy,'buoy')}
+mbay.update
+
+# Get all MBay buoys via query as both Buoy and BuoySST
+buoys = mbay.query([Buoy,'buoy'])
+sst = mbay.query([BuoySST,'buoy'])
+puts
+puts "Check SST of M0 buoy as both Buoy and BuoySST POV"
+m0_buoy = buoys.find {|buoy| buoy.name.eql?('M0')}
+m0_sst  =   sst.find {|buoy| buoy.name.eql?('M0')}
+show_data(m0_buoy)
+show_data(m0_sst)
+puts " #{m0_buoy.temp_0 == m0_sst.temp_0}"                   # => true
+
+# Clean-up
+[buoy0,buoy1,buoy2,mbay].each {|rsrc| rsrc.delete}
+

data/examples/example_helper.rb

@@ -5,3 +5,4 @@ require 'riakrest'
 include RiakRest
 
 SERVER_URI = 'http://localhost:8002/jiak'
+