Class: VoltRb::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/voltrb/client.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

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})

The following options are recognized:

  • host - the machine name or IP address

  • port - other than the default

  • username

  • password



66
67
68
69
70
71
72
 
# File 'lib/voltrb/client.rb', line 66

def initialize(options = {})
  @host = options[:host] || "localhost"
  @port = options[:port] || 8080
  @username= options[:username]
  @hashed_password = Digest::SHA1.hexdigest(options[:password]) if options[:password]
  @api_root = "http://#{@host}:#{@port}/api/1.0/"
end

Instance Attribute Details

#api_root ⇒ Object

Returns the value of attribute api_root.



53
54
55
 
# File 'lib/voltrb/client.rb', line 53

def api_root
  @api_root
end

#host ⇒ Object (readonly)

Returns the value of attribute host.



52
53
54
 
# File 'lib/voltrb/client.rb', line 52

def host
  @host
end

#port ⇒ Object (readonly)

Returns the value of attribute port.



52
53
54
 
# File 'lib/voltrb/client.rb', line 52

def port
  @port
end

#username ⇒ Object (readonly)

Returns the value of attribute username.



52
53
54
 
# File 'lib/voltrb/client.rb', line 52

def username
  @username
end

Instance Method Details

#call_procedure(procedure_name, *args) ⇒ Object Also known as: invoke

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).

Raises:

  • (VoltError.new(proc_resp.status, proc_resp.status_string, proc_resp.app_status, proc_resp.app_status_string)) 


90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/voltrb/client.rb', line 90

def call_procedure(procedure_name, *args)
  params = args.inject([]) { |o,e| o << prep_param(e); o }
  payload = {:Procedure => procedure_name.to_s, :Parameters => params.to_json}
  if @username
    payload[:User] = @username
    payload[:Hashedpassword] = @hashed_password
  end 
  response = RestClient.post(@api_root, payload, :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