Skip to content
Browse files

Started documentation with Yard

  • Loading branch information...
1 parent ac9050f commit 97c9b239088dc3ceca2959bcb06ee1e5cf052b83 @greglu committed
View
2 .gitignore
@@ -5,3 +5,5 @@ nbproject*
.loadpath
.rspec
pkg/
+.yardoc/
+doc/
View
11 lib/stargate/operation/meta_operation.rb
@@ -1,20 +1,31 @@
module Stargate
module Operation
module MetaOperation
+
+ # Get a list of tables
+ #
+ # @return [Array<Model::TableDescriptor>] array of TableDescriptor
def list_tables
request = Request::MetaRequest.new
Response::MetaResponse.new(rest_get(request.list_tables), :list_tables).parse
end
+ # Get the version string of the REST server
+ #
+ # @return [String] version number
def version
request = Request::MetaRequest.new
rest_get(request.version, {"Accept" => "text/plain"}).strip
end
+ # Get the version of the HBase cluster
+ #
+ # @return [String] cluster version number
def cluster_version
request = Request::MetaRequest.new
rest_get(request.cluster_version, {"Accept" => "text/plain"}).strip
end
+
end
end
end
View
56 lib/stargate/operation/row_operation.rb
@@ -4,6 +4,17 @@ module RowOperation
CONVERTER = { '&' => '&amp;', '<' => '&lt;', '>' => '&gt;', "'" => '&apos;', '"' => '&quot;' }.freeze
+ # Add a row to HBase
+ #
+ # Example:
+ # client = Stargate::Client.new("http://localhost:8080")
+ # client.set("test-hbase-stargate", "row1", {"col1:cell1" => "value for column 1, cell 1", "col1:cell2" => "value 2"})
+ #
+ # @param [String] table_name The HBase table name
+ # @param [String] row The row id
+ # @param [Hash] columns hash consisting of the keys as column names and their corresponding values
+ # @param [Integer] timestamp optional timestamp argument. Can be any custom value (in seconds), but HBase uses the time since epoch.
+ # @return [true,false] true or false depending on whether the row was added successfully
def set(table_name, row, columns, timestamp = nil)
# Changing from Ruby epoch time (seconds) to Java epoch time (milliseconds)
timestamp = timestamp*1000 unless timestamp.nil?
@@ -45,10 +56,37 @@ def multi_get(table_name, rows, options = {})
end
end
+ # Get a row from HBase
+ #
+ # Example:
+ # client = Stargate::Client.new("http://localhost:8080")
+ # client.get("test-hbase-stargate", "row1", :timestamp => 1321846232, :columns => ["col1:cell1"], :version => 3)
+ #
+ # @param [String] table_name The HBase table name
+ # @param [String] row The row id
+ # @param [Hash] options the options to retrieve the row with
+ # @option options [Integer] :timestamp A specific timestamp the rows should have
+ # @option options [Array<String>] :columns List of columns to get
+ # @option options [Integer] :versions The number of versions to get back
+ # @return [Model::Row] object corresponding to the requested row, or nil if it could not be found
def get(table_name, row, options = {})
multi_get(table_name, row, options)[row]
end
+ # Get a row from HBase
+ #
+ # Example:
+ # client = Stargate::Client.new("http://localhost:8080")
+ # row = client.show_row("test-hbase-stargate", "row1", nil, nil, :version => 2)
+ #
+ # @deprecated Use the {#get} method instead
+ # @param [String] table_name The HBase table name
+ # @param [String] name The row id
+ # @param [Integer] timestamp optional timestamp
+ # @param [Array<String>] columns name of the columns to retrieve. Use nil to get them all.
+ # @param [Hash] options the options to retrieve the row with
+ # @option options [Integer] :versions The number of versions to get back
+ # @return [Model::Row] object corresponding to the requested row, or nil if it could not be found
def show_row(table_name, name, timestamp = nil, columns = nil, options = {})
handle_exception(table_name, name) do
options[:version] ||= 1
@@ -68,6 +106,18 @@ def show_row(table_name, name, timestamp = nil, columns = nil, options = {})
end
end
+ # Add a row to HBase
+ #
+ # Example:
+ # client = Stargate::Client.new("http://localhost:8080")
+ # client.create_row("test-hbase-stargate", "row1", nil, [{ :name => "col1:cell1", :value => "row2-col1-cell1" }, { :name => "col1:cell2", :value => "row2-col1-cell2" }])
+ #
+ # @deprecated Use the {#set} method instead
+ # @param [String] table_name The HBase table name
+ # @param [String] name The row id
+ # @param [Integer] timestamp optional timestamp argument. Can be any custom value (in seconds), but HBase uses the time since epoch.
+ # @param [Hash, Array<Hash>] columns
+ # @return [true,false] true or false depending on whether the row was added successfully
def create_row(table_name, name, timestamp = nil, columns = nil)
# Changing from Ruby epoch time (seconds) to Java epoch time (milliseconds)
timestamp = timestamp*1000 unless timestamp.nil?
@@ -101,6 +151,12 @@ def create_row(table_name, name, timestamp = nil, columns = nil)
end
end
+ # Delete a row in HBase
+ #
+ # @param [String] table_name The HBase table name
+ # @param [String] name The row id
+ # @param [Integer] timestamp optional timestamp value (deletes all timestamp if not specified)
+ # @param [Array<String>] optional list of specific columns to delete (deletes all columns if not specified)
def delete_row(table_name, name, timestamp = nil, columns = nil)
handle_exception(table_name, name) do
request = Request::RowRequest.new(table_name, name, timestamp)
View
59 lib/stargate/operation/scanner_operation.rb
@@ -1,13 +1,17 @@
module Stargate
module Operation
module ScannerOperation
- # Trying to maintain some API stability for now
- def open_scanner(table_name, columns, start_row, stop_row = nil, timestamp = nil)
- warn "[DEPRECATION] This method is deprecated. Use #open_scanner(table_name, options = {}) instead."
-
- open_scanner(table_name, {:columns => columns, :start_row => start_row, :stop_row => stop_row, :timestamp => timestamp})
- end
+ # Create a scanner for the given table along with options defined in the {Model::Scanner::AVAILABLE_OPTS} hash.
+ #
+ # Example:
+ # client = Stargate::Client.new("http://localhost:8080")
+ # scanner = client.open_scanner("test-hbase-stargate", :batch_size => 1000, :start_row => "row1", :end_row => "row2")
+ #
+ # @see Model::Scanner::AVAILABLE_OPTS
+ # @param [String] table_name the table name
+ # @param [Hash] options options for the scanner
+ # @return [Model::Scanner] object representing the scanner
def open_scanner(table_name, options = {})
raise ArgumentError, "options should be given as a Hash" unless options.instance_of? Hash
columns = options.delete(:columns)
@@ -50,6 +54,22 @@ def open_scanner(table_name, options = {})
end
end
+ # Execute a given block on each row returned by the {Model::Scanner}. This will only store
+ # a batch size (defined during scanner creation) number of records and keep requesting more
+ # until a break or limit is reached. This means that it's safe to run this method against
+ # the whole dataset (assuming that each row encountered isn't being stored elsewhere).
+ #
+ # Example:
+ # client = Stargate::Client.new("http://localhost:8080")
+ # scanner = client.open_scanner("test-hbase-stargate")
+ # client.each_row(scanner) do |row|
+ # puts row.name
+ # end
+ #
+ # @see #open_scanner
+ # @see Model::Scanner
+ # @param [Model::Scanner] scanner Scanner object that was previously open
+ # @yield [Model::Row] code to run against each row
def each_row(scanner, &block)
begin
request = Request::ScannerRequest.new(scanner.table_name)
@@ -77,6 +97,20 @@ def each_row(scanner, &block)
end
end
+ # Get a list of rows from a given {Model::Scanner} that was previously created by the {#open_scanner} method.
+ # If a limit is given, then this method will only retrieve that amount, otherwise it will keep getting
+ # rows until the scanner is exhausted (i.e. there no more records).
+ #
+ # Example:
+ # client = Stargate::Client.new("http://localhost:8080")
+ # scanner = client.open_scanner("test-hbase-stargate")
+ # rows = client.get_rows(scanner, 10)
+ #
+ # @see #open_scanner
+ # @see Model::Scanner
+ # @param [Model::Scanner] scanner Scanner object that was previously open
+ # @param [Integer] limit return this maximum number of records, or return all if nil
+ # @return [Array<Model::Row>] list of row records
def get_rows(scanner, limit = nil)
rows = []
each_row(scanner) do |row|
@@ -86,6 +120,19 @@ def get_rows(scanner, limit = nil)
return rows
end
+ # Close a {Model::Scanner} object
+ #
+ # Example:
+ # client = Stargate::Client.new("http://localhost:8080")
+ # scanner = client.open_scanner("test-hbase-stargate")
+ # client.each_row(scanner) do |row|
+ # puts row.name
+ # end
+ # client.close_scanner(scanner)
+ #
+ # @see #open_scanner
+ # @see Model::Scanner
+ # @param [Model::Scanner] scanner Scanner object that was previously open
def close_scanner(scanner)
begin
request = Request::ScannerRequest.new(scanner.table_name)
View
49 lib/stargate/operation/table_operation.rb
@@ -1,6 +1,11 @@
module Stargate
module Operation
module TableOperation
+
+ # Get the TableDescriptor object for the table of the given name
+ #
+ # @param [String] name the table name
+ # @return [Model::TableDescriptor] TableDescriptor object corresponding to the table
def show_table(name)
begin
request = Request::TableRequest.new(name)
@@ -10,8 +15,29 @@ def show_table(name)
end
end
+ # Create a table in HBase. Pass in one or more arguments after the table name to configure the column families
+ # that should be created. The arguments can be a mix of String (no options) or a Hash with options specified
+ # from the key names of the {Model::ColumnDescriptor::AVAILABLE_OPTS} hash.
+ #
+ # Example:
+ # client = Stargate::Client.new("http://localhost:8080")
+ # table_options = { :name => 'columnfamily1',
+ # :max_version => 3,
+ # :compression => Stargate::Model::CompressionType::NONE,
+ # :in_memory => false,
+ # :block_cache => false,
+ # :ttl => -1,
+ # :max_cell_size => 2147483647,
+ # :bloomfilter => false
+ # }
+ # client.create_table('test-hbase-stargate', table_options)
+ #
+ # @see Model::ColumnDescriptor::AVAILABLE_OPTS
+ # @param [String] name the table name
+ # @param [String, Hash] args initial column family
+ # @return [true,false] whether or not the table was created
def create_table(name, *args)
- raise StandardError, "Table name must be of type String" unless name.instance_of? String
+ raise ArgumentError, "Table name must be of type String" unless name.instance_of? String
request = Request::TableRequest.new(name)
begin
@@ -30,7 +56,7 @@ def create_table(name, *args)
xml_data << "/>"
else
- raise StandardError, "#{arg.class.to_s} of #{arg.to_s} is not of Hash Type"
+ raise ArgumentError, "#{arg.class.to_s} of #{arg.to_s} is not of Hash Type"
end
end
xml_data << "</TableSchema>"
@@ -41,6 +67,9 @@ def create_table(name, *args)
end
end
+ # Will alter the table of the given name. Not currently implemented.
+ #
+ # @param [String] name the table name
def alter_table(name, *args)
raise NotImplementedError, "Altering the table is not supported yet"
@@ -60,6 +89,10 @@ def alter_table(name, *args)
end
end
+ # Delete the table with the given name and optionally choose certain columns to delete
+ #
+ # @param [String] name the table name
+ # @param [Array<String>] [Deprecated] list of column names
def delete_table(name, columns = nil)
begin
request = Request::TableRequest.new(name)
@@ -73,19 +106,15 @@ def delete_table(name, columns = nil)
end
end
+ # (see #delete_table)
def destroy_table(name, columns = nil)
delete_table(name, columns)
end
- def enable_table(name)
- warn "[DEPRECATION] Explicitly enabling tables isn't required anymore. HBase Stargate will enable/disable as needed."
- end
-
- def disable_table(name)
- warn "[DEPRECATION] Explicitly disabling tables isn't required anymore. HBase Stargate will enable/disable as needed."
- end
-
+ # List of table regions
+ #
def table_regions(name, start_row = nil, end_row = nil)
+ raise NotImplementedError, "Getting the table regions is not supported yet"
end
end

0 comments on commit 97c9b23

Please sign in to comment.
Something went wrong with that request. Please try again.