hbase-stargate 1.5.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Dingding Ye
+
+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.textile

@@ -0,0 +1,79 @@
+h1. hbase-stargate
+
+A Ruby client for HBase (http://hadoop.apache.org/hbase) that works with the Stargate interface.
+Stargate is the RESTful web service front end for HBase that can serve up a number of formats including XML, JSON, and protobufs.
+
+This project is based off the work of Dingding Ye <yedingding@gmail.com> at http://github.com/sishen/hbase-ruby
+
+
+h2. Installation
+
+<pre>
+<code>$ gem install hbase-stargate -s http://gemcutter.org</code>
+</pre>
+
+To work with this gem in your Rails application, add this to the environment.rb file:
+<pre><code>config.gem 'hbase-stargate', :lib => "stargate", :source => "http://gemcutter.org"</code></pre>
+
+To build the gem yourself:
+<pre><code>$ rake gem</code></pre>
+
+
+h2. Getting Started
+
+ # Download and unpack the most recent release of HBase from http://hadoop.apache.org/hbase/releases.html#Download
+ # Edit <hbase-dir>/conf/hbase-env.sh and uncomment/modify the following line to correspond to your Java home path:
+export JAVA_HOME=/usr/lib/jvm/java-6-sun
+ # Copy <hbase-dir>/contrib/stargate/hbase-<version>-stargate.jar into <hbase-dir>/lib
+ # Copy all the files in the <hbase-dir>/contrib/stargate/lib folder into <hbase-dir>/lib
+ # Start up HBase:
+$ <hbase-dir>/bin/start-hbase.sh
+ # Start up Stargate (append "-p 1234" at the end if you want to change the port):
+$ <hbase-dir>/bin/hbase org.apache.hadoop.hbase.stargate.Main
+
+
+h2. Usage
+
+Here are some examples:
+
+<pre><code>
+require 'stargate'
+
+# Direct connection
+# client = Stargate::Client.new("http://localhost:8080") # this url is the default for stargate.
+# Connection through a proxy
+client = Stargate::Client.new("http://localhost:8080", { :proxy => "10.2.3.4:8080" }) 
+
+# Table Operation
+tables = client.list_tables                              # list available tables
+table = client.create_table('users', 'habbit')           # create a table whose column_family is habbit
+table = client.show_table('users')                       # show the meta info of table users 
+client.delete_table('users')                             # delete 'users' table
+
+# Row Operation
+row = client.show_row('users', 'sishen')                 # show the data of row 'sishen' in table 'users'
+row2 = client.create_row('users', 'sishen', Time.now.to_i, {:name => 'habbit:football', :value => 'i like football'}) # create the row 'sishen' with the data in the table 'users'
+client.delete_row('users', 'sishen', nil, 'habbit:football')  # delete the row 'sishen' of table 'users' with the optional column 'habbit:football'
+
+# Scanner Operation (see spec/stargate-client/operation/scanner_operation_spec.rb for more examples)
+scanner = client.open_scanner('users', {:start_row => "row2", :batch => 5, :columns => ["habbit:"]}) # See more options from Stargate::Model::Scanner.AVAILABLE_OPTS
+rows = client.get_rows(scanner)
+client.close_scanner(scanner)
+</code></pre>
+
+
+h2. Testing
+
+Run the specs with the following rake task:
+
+$ rake spec
+
+or pass it the URL to the HBase Stargate server as an argument:
+
+$ rake spec STARGATE_URL=http://localhost:8080
+
+
+h2. Copyright
+
+Copyright (c) 2008 Dingding Ye <yedingding@gmail.com>
+Distributed under MIT License

data/Rakefile

@@ -0,0 +1,27 @@
+require 'spec/rake/spectask'
+
+begin
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "hbase-stargate"
+    gemspec.authors = ['Openplaces']
+    gemspec.email = 'greg.lu@gmail.com'
+    gemspec.homepage = "http://github.com/greglu/hbase-stargate"
+    gemspec.summary = "Ruby client for HBase's Stargate web service"
+    gemspec.description = "A Ruby client used to interact with HBase through its Stargate web service front-end"
+    gemspec.files = FileList["{lib,spec}/**/*","Rakefile","VERSION","LICENSE","README.textile"].to_a
+    gemspec.extra_rdoc_files = FileList["LICENSE","README.textile"].to_a
+
+    gemspec.add_development_dependency "rspec"
+    gemspec.add_dependency "json"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler"
+end
+
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = File.open("spec/spec.opts").readlines.map{|x| x.chomp}
+end

data/VERSION

@@ -0,0 +1 @@
+1.5.0

data/lib/stargate.rb

@@ -0,0 +1,7 @@
+module Stargate end
+
+require File.join(File.dirname(__FILE__), "stargate", "client")
+require File.join(File.dirname(__FILE__), "stargate", "exception")
+require File.join(File.dirname(__FILE__), "stargate", "model")
+require File.join(File.dirname(__FILE__), "stargate", "request")
+require File.join(File.dirname(__FILE__), "stargate", "response")

data/lib/stargate/client.rb

@@ -0,0 +1,93 @@
+require 'net/http'
+require File.dirname(__FILE__) + '/operation/meta_operation'
+require File.dirname(__FILE__) + '/operation/table_operation'
+require File.dirname(__FILE__) + '/operation/row_operation'
+require File.dirname(__FILE__) + '/operation/scanner_operation'
+
+module Stargate
+  class Client
+    VERSION = File.read(File.join(File.dirname(__FILE__), "..", "..", "VERSION")).chomp.freeze
+
+    include Operation::MetaOperation
+    include Operation::TableOperation
+    include Operation::RowOperation
+    include Operation::ScannerOperation
+
+    attr_reader :url, :connection
+
+    def initialize(url = "http://localhost:8080", opts = {})
+      @url = URI.parse(url)
+      unless @url.kind_of? URI::HTTP
+        raise "invalid http url: #{url}"
+      end
+
+      # Not actually opening the connection yet, just setting up the persistent connection.
+      if opts[:proxy]
+        proxy_address, proxy_port = opts[:proxy].split(':')
+        @connection = Net::HTTP.Proxy(proxy_address, proxy_port).new(@url.host, @url.port)
+      else
+        @connection = Net::HTTP.new(@url.host, @url.port)
+      end
+      @connection.read_timeout = opts[:timeout] if opts[:timeout]
+    end
+
+    def get(path, options = {})
+      safe_request { @connection.get(@url.path + path, {"Accept" => "application/json"}.merge(options)) }
+    end
+
+    def get_response(path, options = {})
+      safe_response { @connection.get(@url.path + path, {"Accept" => "application/json"}.merge(options)) }
+    end
+
+    def post(path, data = nil, options = {})
+      safe_request { @connection.post(@url.path + path, data, {'Content-Type' => 'text/xml'}.merge(options)) }
+    end
+
+    def post_response(path, data = nil, options = {})
+      safe_response { @connection.post(@url.path + path, data, {'Content-Type' => 'text/xml'}.merge(options)) }
+    end
+
+    def delete(path, options = {})
+      safe_request { @connection.delete(@url.path + path, options) }
+    end
+
+    def delete_response(path, options = {})
+      safe_response { @connection.delete(@url.path + path, options) }
+    end
+
+    def put(path, data = nil, options = {})
+      safe_request { @connection.put(@url.path + path, data, {'Content-Type' => 'text/xml'}.merge(options)) }
+    end
+
+    def put_response(path, data = nil, options = {})
+      safe_response { @connection.put(@url.path + path, data, {'Content-Type' => 'text/xml'}.merge(options)) }
+    end
+
+    private
+
+      # Part of safe_request was broken up into safe_response because when working with scanners
+      # in Stargate, you need to have access to the response itself, and not just the body.
+      def safe_response(&block)
+        begin
+          yield
+        rescue Errno::ECONNREFUSED
+          raise ConnectionNotEstablishedError, "can't connect to #{@url}"
+        rescue Timeout::Error => e
+          puts e.backtrace.join("\n")
+          raise ConnectionTimeoutError, "execution expired. Maybe query disabled tables"
+        end
+      end
+
+      def safe_request(&block)
+        response = safe_response{ yield block }
+
+        case response
+        when Net::HTTPSuccess
+          response.body
+        else
+          response.error!
+        end
+      end
+
+  end
+end

data/lib/stargate/exception.rb

@@ -0,0 +1,21 @@
+class Stargate::Exception < StandardError; end
+
+class Stargate::ConnectionNotEstablishedError < Stargate::Exception; end
+
+class Stargate::ConnectionTimeoutError < Stargate::Exception; end
+
+class Stargate::TableNotFoundError < Stargate::Exception; end
+
+class Stargate::TableExistsError < Stargate::Exception; end
+
+class Stargate::TableFailCreateError < Stargate::Exception; end
+
+class Stargate::TableNotDisabledError < Stargate::Exception; end
+
+class Stargate::TableFailDisableError < Stargate::Exception; end
+
+class Stargate::TableFailEnableError < Stargate::Exception; end
+
+class Stargate::RowNotFoundError < Stargate::Exception; end
+
+class Stargate::ScannerError < Stargate::Exception; end

data/lib/stargate/model.rb

@@ -0,0 +1,19 @@
+module Stargate
+  module Model
+    class Record
+      def initialize (params)
+        params.each do |key, value|
+          name = key.to_s
+          instance_variable_set("@#{name}", value) if respond_to?(name)
+        end
+      end
+    end
+  end
+end
+
+require File.dirname(__FILE__) + '/model/column'
+require File.dirname(__FILE__) + '/model/column_descriptor'
+require File.dirname(__FILE__) + '/model/region_descriptor'
+require File.dirname(__FILE__) + '/model/row'
+require File.dirname(__FILE__) + '/model/table_descriptor'
+require File.dirname(__FILE__) + '/model/scanner'

data/lib/stargate/model/column.rb

@@ -0,0 +1,9 @@
+module Stargate
+  module Model
+    class Column < Record
+      attr_accessor :name
+      attr_accessor :value
+      attr_accessor :timestamp
+    end
+  end
+end

data/lib/stargate/model/column_descriptor.rb

@@ -0,0 +1,32 @@
+module Stargate
+  module Model
+    module CompressionType
+      NONE = "NONE"
+      RECORD = "RECORD"
+      BLOCK = "BLOCK"
+
+      CTYPES = [NONE, RECORD, BLOCK]
+
+      def to_compression_type(type_string)
+        CTYPES.include?(type_string) ? type_string : NONE
+      end
+
+      module_function :to_compression_type
+    end
+
+    class ColumnDescriptor < Record
+      AVAILABLE_OPTS = {  :name => "name", :max_versions => "VERSIONS", :versions => "VERSIONS",
+                          :compression => "COMPRESSION", :in_memory => "IN_MEMORY",
+                          :block_cache => "BLOCKCACHE", :blockcache => "BLOCKCACHE",
+                          :blocksize => "BLOCKSIZE", :length => "LENGTH", :ttl => "TTL",
+                          :bloomfilter => "BLOOMFILTER"}
+      attr_accessor :name
+      attr_accessor :compression
+      attr_accessor :bloomfilter
+      attr_accessor :maximum_cell_size
+      attr_accessor :max_versions
+
+      attr_accessor :versions
+    end
+  end
+end

data/lib/stargate/model/region_descriptor.rb

@@ -0,0 +1,9 @@
+module Stargate
+  module Model
+    class Region < Record
+    end
+
+    class RegionDescriptor < Record
+    end
+  end
+end

data/lib/stargate/model/row.rb

@@ -0,0 +1,18 @@
+module Stargate
+  module Model
+    class Row < Record
+      attr_accessor :table_name
+      attr_accessor :name
+      attr_accessor :total_count
+      attr_accessor :columns
+
+      def timestamp
+        warn "[DEPRECATION] timestamp attribute will be removed from the Row model. "
+      end
+
+      def timestamp=
+        timestamp
+      end
+    end
+  end
+end

data/lib/stargate/model/scanner.rb

@@ -0,0 +1,16 @@
+module Stargate
+  module Model
+    class Scanner < Record
+      AVAILABLE_OPTS = {  :start_row => "startRow", :end_row => "endRow",
+                          :start_time => "startTime", :end_time => "endTime",
+                          :batch => "batch" }
+
+      attr_accessor :table_name
+      attr_accessor :scanner_url
+      attr_accessor :batch_size
+
+      # Deprecation: scanner_url is used instead of just the ID
+      attr_accessor :scanner_id
+    end
+  end
+end

data/lib/stargate/model/table_descriptor.rb

@@ -0,0 +1,8 @@
+module Stargate
+  module Model
+    class TableDescriptor < Record
+      attr_accessor :name
+      attr_accessor :column_families
+    end
+  end
+end

data/lib/stargate/operation/meta_operation.rb

@@ -0,0 +1,20 @@
+module Stargate
+  module Operation
+    module MetaOperation
+      def list_tables
+        request = Request::MetaRequest.new
+        Response::MetaResponse.new(get(request.list_tables), :list_tables).parse
+      end
+
+      def version
+        request = Request::MetaRequest.new
+        get(request.version, {"Accept" => "text/plain"}).strip
+      end
+
+      def cluster_version
+        request = Request::MetaRequest.new
+        get(request.cluster_version, {"Accept" => "text/plain"}).strip
+      end
+    end
+  end
+end

data/lib/stargate/operation/row_operation.rb

@@ -0,0 +1,86 @@
+module Stargate
+  module Operation
+    module RowOperation
+      Converter = {
+        '&' => '&',
+        '<' => '&lt;',
+        '>' => '&gt;',
+        "'" => '&apos;',
+        '"' => '&quot;'
+      }
+
+      def row_timestamps(table_name, name)
+        raise NotImplementedError, "Currently not supported in Stargate client"
+      end
+
+      def show_row(table_name, name, timestamp = nil, columns = nil, options = { })
+        begin
+          options[:version] ||= 1
+
+          request = Request::RowRequest.new(table_name, name, timestamp)
+          row = Response::RowResponse.new(get(request.show(columns, options)), :show_row).parse.first
+          row.table_name = table_name
+          row
+        rescue Net::ProtocolError => e
+          # TODO: Use better handling instead of this.
+          if e.to_s.include?("Table")
+            raise TableNotFoundError, "Table '#{table_name}' Not Found"
+          elsif e.to_s.include?("404")
+            raise RowNotFoundError, "Row '#{name}' Not Found"
+          end
+        end
+      end
+
+      def create_row(table_name, name, timestamp = nil, columns = nil)
+        begin
+          request = Request::RowRequest.new(table_name, name, timestamp)
+          data = []
+          if columns
+            if columns.instance_of? Array
+              data = columns
+            elsif columns.instance_of? Hash
+              data = [columns]
+            else
+              raise StandardError, "Only Array or Hash data accepted"
+            end
+          end
+
+          xml_data = "<?xml version='1.0' encoding='UTF-8' standalone='yes'?><CellSet>"
+          xml_data << "<Row key='#{[name].pack('m') rescue ''}'>"
+          data.each do |d|
+            escape_name = d[:name].gsub(/[&<>'"]/) { |match| Converter[match] }
+            xml_data << "<Cell "
+            xml_data << "timestamp='#{timestamp}' " if timestamp
+            xml_data << "column='#{[escape_name].pack('m') rescue ''}'>"
+            xml_data << "#{[d[:value]].pack("m") rescue ''}"
+            xml_data << "</Cell>"
+          end
+          xml_data << "</Row></CellSet>"
+
+          Response::RowResponse.new(post_response(request.create(data.map{|col| col[:name]}), xml_data), :create_row).parse
+        rescue Net::ProtocolError => e
+          if e.to_s.include?("Table")
+            raise TableNotFoundError, "Table '#{table_name}' Not Found"
+          elsif e.to_s.include?("Row")
+            raise RowNotFoundError, "Row '#{name}' Not Found"
+          else
+            raise StandardError, "Error encountered while trying to create row: #{e.message}"
+          end
+        end
+      end
+
+      def delete_row(table_name, name, timestamp = nil, columns = nil)
+        begin
+          request = Request::RowRequest.new(table_name, name, timestamp)
+          Response::RowResponse.new(delete_response(request.delete(columns)), :delete_row).parse
+        rescue Net::ProtocolError => e
+          if e.to_s.include?("Table")
+            raise TableNotFoundError, "Table '#{table_name}' Not Found"
+          elsif e.to_s.include?("Row")
+            raise RowNotFoundError, "Row '#{name}' Not Found"
+          end
+        end
+      end
+    end
+  end
+end