voltrb 0.0.2

data/CHANGELOG

@@ -0,0 +1,8 @@
+= Change log
+
+== 0.0.1
+* Initial release.
+
+== 0.0.2
+* Updated the README about the Unicode string issue. The trunk version now has this fixed.
+* More robust handling of different date & time types.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Junjun Olympia
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,160 @@
+= VoltRb: A gem client for VoltDB
+
+VoltRB is a gem client for VoltDB that uses the JSON interface.
+
+= Installing VoltRb
+
+Get from RubyForge.
+
+  % gem install voltrb
+
+= Example
+
+  This is the Ruby version of VoltDB's hello world example.
+
+  require 'voltrb'
+
+  # Create a client and connect to the VoltDB instance running in the same machine.
+  client = VoltRb::Client.new
+
+  # Insert "Hello, World" for different languages.
+  client.call_procedure("Insert", "Hello", "World", "English")
+  client.call_procedure("Insert", "Bonjour", "Monde", "French")
+  client.call_procedure("Insert", "Hola", "Mundo", "Spanish")
+  client.call_procedure("Insert", "Hej", "Verden", "Danish")
+  client.call_procedure("Insert", "Ciao", "Mondo", "Italian")
+
+  # Say it in Spanish!
+  response = client.call_procedure("Select", "Spanish")
+  puts "#{response.results[0].first[:HELLO]}, #{response.results[0].first[:WORLD]}!"
+
+= Usage
+
+== Initialization
+
+Initializing a client without passing any arguments will have it connect to the VoltDB instance running in localhost.
+
+  client = VoltRb::Client.new
+
+Or we can specify options as a hash.
+
+  client = VoltRb::Client.new({:host => "voltdbhost", :port => 8888})
+
+Right now, VoltRb only knows two:
+
+* host - should point to the name or IP address of the VoltDB instance.
+* port - in case the instance isn't listening on the default port (8080).
+
+There are no options yet for authentication since the JSON interface doesn't implement any. See Notes for more.
+
+== Stored Procedure Invocation
+
+We call VoltDB stored procedures using Client#call_procedure. The first argument is the name of the procedure followed by its parameters if any.
+
+  client.call_procedure(:Insert, "Hello", "World", "English")
+
+Ruby types are automatically mapped to VoltDB types as below:
+
+Ruby::    VoltDB 
+Fixnum, Bignum::  Tiny, Small, Integer, Long
+Float::   Float, Double
+BigDecimal:: Decimal
+Time, Date, DateTime::  Timestamp
+String::  String
+
+Nils become Nulls. 
+
+== Stored Procedure Response
+
+VoltDB stored procedures can return multiple rowsets (VoltTable objects). This array of rowsets is returned by ProcedureResponse#results. In the hello world example, the Select procedure returns only one so:
+
+  response = client.call_procedure("Select", "Spanish")
+  response.results[0]
+  => #<VoltRb::VoltTable:0x17952c4 @raw={"status"=>-128, "schema"=>[{"name"=>"HELLO", "type"=>9}, 
+  {"name"=>"WORLD", "type"=>9}], "data"=>[["Hola", "Mundo"]]}>
+
+Each VoltTable / rowset implements Enumerable so we can access the rows using the usual methods #each, #all, #first, #last.
+
+  response.results[0].each { |row| puts row }
+
+Each row is a hash with keys that are symbolized column names.
+
+  response.results[0].each { |row| puts "#{row[:HELLO]}, #{row[:WORLD]}" }
+  Hola, Mundo
+  => [["Hola", "Mundo"]]
+
+You can get the list of columns by looking at the array returned by VoltTable#schema.
+
+  response.results[0].schema
+  => [#<struct VoltRb::VoltColumn name=:HELLO, type=9>, #<struct VoltRb::VoltColumn name=:WORLD, type=9>]
+
+== Catching Errors
+
+Standard Ruby errors will be raised in case of network connection problems. VoltDB-specific errors like invalid procedure arguments and constraint violations will raise VoltRb::VoltError. We can find out more by inspecting #status_string or #app_status_string.
+
+  begin
+    client.call_procedure("Insert", "Hello", "World", "English")
+    # This second call will cause a unique constraint violation.
+    client.call_procedure("Insert", "Hello", "World", "English")
+  rescue VoltRb::VoltError => bang
+    puts "Error: #{bang.status_string}"
+  end    
+
+  Error: 
+  ========================================================
+  VOLTDB ERROR: CONSTRAINT VIOLATION
+    Attempted violation of constraint
+  Constraint Type UNIQUE, Table CatalogId HELLOWORLD
+   header size: 35
+   status code: -128 column count: 3
+   cols (HELLO:STRING), (WORLD:STRING), (DIALECT:STRING), 
+   rows -
+    Hello, World, English, 
+  
+      at Insert.run(Insert.java:19)
+  ========================================================
+ 
+= Notes
+
+== User Authentication
+
+As of VoltDB v1.1, the JSON interface does not implement any form of authentication. 
+
+The following text was taken from VoltDB's JSON documentation:
+
+<em>Note that there is currently no way to authenticate the client interface using JSON. In other words, the JSON interface operates as an "anonymous" client. If security is enabled for the database, use of the JSON interface is essentially disabled because any attempt to execute a stored procedure will result in a protection violation.</em>
+
+This forum thread says they expect to have the feature in v1.2
+
+http://community.voltdb.com/node/241
+
+== Unicode Strings
+
+As of v1.1 VoltDB's JSON interface does not properly return UTF-8 strings so non-Latin characters don't display correctly.
+
+http://community.voltdb.com/node/263
+
+The fix is now in their trunk version. It'll be included in the next official release of VoltDB (v1.2). Or you can build directly from trunk.
+
+  svn checkout http://svnmirror.voltdb.com/eng/trunk/
+
+= License
+
+This gem has been released under the MIT License[link:files/MIT-LICENSE.html].
+
+= Warranty
+
+This software is provided "as is" and without any express or
+implied warranties, including, without limitation, the implied
+warranties of merchantibility and fitness for a particular
+purpose.
+
+== Contributing
+
+The source code is hosted on http://github.com/beljun/voltrb.
+
+== Credits
+
+Author: Junjun Olympia (@beljun) / http://rubyredtomatoes.com
+
+

data/lib/voltrb/client.rb

@@ -0,0 +1,109 @@
+require 'json'
+require 'rest_client'
+require 'date'
+require 'time'
+require 'bigdecimal'
+
+module VoltRb
+  # This is the main class we use to interact with the VoltDB instance.
+  #
+  # == Initialization
+  # Create a client and connect to the instance in localhost:
+  #   client = VoltRb::Client.new
+  #
+  # Or pass it a hash of options like:
+  #   client = VoltRb::Client.new({:host => "voltdb_server", :port => 8888})
+  #
+  # See the new method for more details.
+  #
+  # == Calling stored procedures
+  # Call a stored procedure:
+  #   client.call_procedure(:MyStoredProc, "This is the first argument", 2, Date.today)
+  #
+  # The call above invokes the VoltDB stored procedure named "MyStoredProc". 
+  # The procedure expects 3 parameters (a String, a small integer, and a Date/Timestamp) so we pass these in order.
+  # See call_procedure method for more.
+  #
+  # == Getting the stored procedure response
+  # call_procedure returns a ProcedureResponse object which will contain the rows returned if any:
+  #   response = client.call_procedure(:AnotherProc, 1)
+  #   puts response.results[0].first[:TITLE]
+  #
+  # In the above example, we invoke the procedure "AnotherProc" and expect one rowset and 
+  # one row with a column named "TITLE".
+  # See ProcedureResponse for more.
+  #
+  # == Handling errors
+  # In case of typical errors like network connection problems, standard Ruby exceptions will be raised. 
+  # In case of VoltDB-specific errors like invalid stored procedure arguments or constraint violations, 
+  # a VoltDB::VoltError exception object will be raised.
+  #   begin
+  #     client.call_procedure(:MyStoredProc, 2)
+  #   rescue VoltDB::VoltError => bang
+  #     puts bang.status_string
+  #     raise
+  #   end
+  #
+  # The above call will raise an error because it expects 3 parameters but was only given one. 
+  # We can find the details of the error by inspecting status_string or app_status_string.
+  # See VoltError for more.
+  class Client
+    attr_reader :host, :port
+    attr_accessor :api_root
+
+    # Calling new without any arguments will create a client and have it connect to the VoltDB instance running 
+    # in localhost:8080.
+    # Pass an options hash to modify these defaults. 
+    #   client = VoltRb::Client.new({:host => "voltdb_server", :port => 8888})
+    #
+    # Right now, only two options are recognized:
+    # * host - the machine name or IP address
+    # * port - other than the default
+    #
+    # <em>Note on user authentication:</em>
+    # As of v1.1, the VoltDB JSON interface does not implement any form of authentication. 
+    # See the README[link:files/README.html] for more.
+    def initialize(options = {})
+      @host = options[:host] || "localhost"
+      @port = options[:port] || 8080
+      @api_root = "http://#{@host}:#{@port}/api/1.0/"
+    end
+
+    # Invoke a VoltDB stored procedure by calling this method with the first argument being the stored procedure name. 
+    # Follow that with any number of parameters needed by the stored procedure itself.
+    #   client.call_procedure(:MyStoredProc, "This is the first argument for :MyStoredProc", 2, Date.today)
+    #
+    # Ruby types map to the stored procedure data types as below:
+    # Ruby::    VoltDB 
+    # Fixnum, Bignum::  Tiny, Small, Integer, Long
+    # Float::   Float, Double
+    # BigDecimal:: Decimal
+    # Time, Date, DateTime::  Timestamp
+    # String::  String
+    # 
+    # Nils become Nulls. 
+    # If a stored procedure returns one or more rowsets that we're interested in, see the ProcedureResponse object
+    # that's returned by this method.
+    # In case of errors, handle the usual Ruby errors and the VoltDB-specfic VoltError (this inherits from StandardError).
+    def call_procedure(procedure_name, *args)
+      params = args.inject([]) { |o,e| o << prep_param(e); o }
+      response = RestClient.post(@api_root, :Procedure => procedure_name.to_s, :Parameters => params.to_json, :content_type => "text/plain; charset=UTF-8", :accept => :json)
+      proc_resp = ProcedureResponse.new(response)
+      raise(VoltError.new(proc_resp.status, proc_resp.status_string, proc_resp.app_status, proc_resp.app_status_string), "A VoltDB procedure error occurred. See the exception object for details.") if proc_resp.raw["status"] != 1 or proc_resp.raw["appstatus"] != -128
+      proc_resp
+    end
+
+  private
+    def prep_param(val)
+      case val
+        when BigDecimal then val.to_s('F')
+        when Time then val.to_i * 1000
+        # Note: case DateTime MUST come before Date because Ruby seems to think DateTime is a Date. But Date is not a DateTime. Ruby bug?
+        when DateTime then Time.parse(val.strftime("%a %b %d %H:%M:%S %z %Y")).to_i * 1000
+        when Date then Time.parse(val.strftime("%b %d %Y")).to_i * 1000
+        else val
+      end
+    end
+  end
+end
+

data/lib/voltrb/exceptions.rb

@@ -0,0 +1,11 @@
+module VoltRb
+  # Raised in case of VoltDB-specific errors such as stored procedure invalid arguments or constraint violations.
+  # Inspect status, status_string, app_status, and app_status_string for details on the error returned by VoltDB.
+  class VoltError < StandardError
+    attr_reader :status, :status_string, :app_status, :app_status_string
+
+    def initialize(status, status_string, app_status, app_status_string)
+      @status, @status_string, @app_status, @app_status_string = status, status_string, app_status, app_status_string
+    end
+  end
+end

data/lib/voltrb/procedure_response.rb

@@ -0,0 +1,45 @@
+module VoltRb
+  # An object of this class is returned by a call to Client#call_procedure.
+  #   response = client.call_procedure("Select", "Spanish")
+  # Some VoltDB stored procedures return multiple rowsets. (Think of one rowset as the rows returned by a SQL select.)
+  # You get access to these array of rowsets (VoltTable objects) thru results.
+  class ProcedureResponse
+    # This is a plain Ruby hash derived from the JSON response from VoltDB.
+    # We can use this hash to access the entire response entity as an alternative to the object methods below.
+    # May save us a few CPU cycles. (Benchmark to be sure.)
+    # No conversions are done for values of type Decimal and Timestamp so we'll have to handle those ourselves.
+    # We can also use the conversion functions in Utils
+    attr_reader :raw
+
+    def initialize(response)
+      @raw = JSON.parse(response)      
+    end
+
+    def status
+      @status ||= @raw["status"]
+    end
+
+    def status_string
+      @status_string ||= @raw["statusstring"]
+    end
+
+    def app_status
+      @app_status ||= @raw["appstatus"]
+    end
+
+    def app_status_string
+      @app_status_string ||= @raw["appstatusstring"]
+    end
+
+    # Returns an array of VoltTable.
+    def results
+      @results ||= hydrate_results
+    end
+
+  private
+    def hydrate_results
+      @raw["results"].inject([]) { |o,e| o << VoltTable.new(e); o }
+    end
+  end
+end
+

data/lib/voltrb/types.rb

@@ -0,0 +1,15 @@
+module VoltRb
+  # VoltDB constants to indicate data types.
+  module Types
+    ARRAY = -99
+    NULL = 1
+    TINYINT = 3
+    SMALLINT = 4
+    INTEGER = 5
+    BIGINT = 6
+    FLOAT = 8
+    STRING = 9
+    TIMESTAMP = 11
+    DECIMAL = 22
+  end
+end

data/lib/voltrb/utils.rb

@@ -0,0 +1,30 @@
+require 'bigdecimal'
+
+module VoltRb
+  # Set of utility functions.
+  module Utils
+    # Converts a string to a Big Decimal.
+    def dec_from_str(str)
+      BigDecimal.new(str)
+    end
+
+    # Converts an integer (millisecond value since epoch) to a Time object.
+    def time_from_milli_epoch(num)
+      Time.at(num/1000)
+    end
+
+    # Converts a val of type into its Ruby equivalent.
+    def ruby_from_volt(val, type)
+      return nil if val.nil?
+
+      case type
+        when Types::DECIMAL then dec_from_str(val)
+        when Types::TIMESTAMP then time_from_milli_epoch(val)
+        else val
+      end
+    end
+
+    module_function :dec_from_str, :time_from_milli_epoch, :ruby_from_volt
+  end
+end
+

data/lib/voltrb/version.rb

@@ -0,0 +1,5 @@
+module VoltRb
+  # This gem's version.
+  VERSION = "0.0.2"
+end
+

data/lib/voltrb/volt_table.rb

@@ -0,0 +1,62 @@
+module VoltRb
+  VoltColumn = Struct.new :name, :type
+
+  # This object contains one or more rows (a rowset).
+  # Enumerable is implemented so we can access the rows via the usual each, all, first, last.
+  #   first_row = response.results[0].first
+  # Each row is a hash with the symbolized column names for keys.
+  #   puts first_row[:MY_COLUMN]
+  # We can get a list of columns via schema.
+  class VoltTable
+    include Enumerable
+
+    def initialize(hash_data)
+      @raw = hash_data
+    end
+
+    def status
+      @status ||= @raw["status"]
+    end
+
+    def schema
+      @schema ||= hydrate_schema
+    end
+
+    def each
+      # ToDo: Benchmark, benchmark, benchmark.
+      @raw["data"].each { |r| yield hydrate_row(r) }
+    end
+
+    def all
+      self.inject([]) { |o,e| o << e; o }
+    end
+
+    def first
+      hydrate_row(@raw["data"].first)
+    end
+
+    def last
+      hydrate_row(@raw["data"].last)
+    end
+
+    def empty?
+      @raw["data"].empty?
+    end
+
+    def count
+      @raw["data"].size
+    end
+
+  private
+    def hydrate_schema
+      @raw["schema"].inject([]) { |o, e| o << VoltColumn.new(e["name"].to_sym, e["type"]); o }
+    end
+
+    def hydrate_row(data)
+      row = {}
+      self.schema.each_with_index { |col, i| row[col.name.to_sym] = Utils.ruby_from_volt(data[i], col.type) } 
+      row
+    end
+  end
+end
+

data/lib/voltrb.rb

@@ -0,0 +1,12 @@
+require 'json'
+require 'rest_client'
+require 'date'
+require 'time'
+require 'bigdecimal'
+require 'voltrb/types'
+require 'voltrb/utils'
+require 'voltrb/exceptions'
+require 'voltrb/volt_table'
+require 'voltrb/procedure_response'
+require 'voltrb/client'
+

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification 
+name: voltrb
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 2
+  version: 0.0.2
+platform: ruby
+authors: 
+- Junjun Olympia
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-07 00:00:00 +08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: VoltRb is a gem client for VoltDB. This early release uses the JSON interface and works with VoltDB v1.1 onwards.
+email: romeo.olympia@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/voltrb/client.rb
+- lib/voltrb/exceptions.rb
+- lib/voltrb/procedure_response.rb
+- lib/voltrb/types.rb
+- lib/voltrb/utils.rb
+- lib/voltrb/version.rb
+- lib/voltrb/volt_table.rb
+- lib/voltrb.rb
+- README.rdoc
+- MIT-LICENSE
+- CHANGELOG
+has_rdoc: true
+homepage: http://github.com/beljun/voltrb
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: voltrb
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: VoltRb is a gem client for VoltDB.
+test_files: []
+