massive_record 0.1.0

data/.autotest

@@ -0,0 +1,15 @@
+require 'autotest/restart'
+require 'autotest/growl'
+require 'autotest/fsevent'
+
+Autotest.add_hook(:initialize) {|at|
+  %w{.git .svn .hg .DS_Store ._* vendor tmp log doc}.each do |exception|
+    at.add_exception(exception)
+  end
+  at.clear_mappings         
+  # take out the default (test/test*rb)
+  at.add_mapping(%r{^lib/.*\.rb$}) {|f, _|
+    Dir['spec/**/*.rb']
+  }
+  nil
+}

data/.gitignore

@@ -0,0 +1,6 @@
+pkg/*
+*.gem
+.bundle
+.DS_Store
+spec/config.yml
+rdoc/

data/.rspec

@@ -0,0 +1,2 @@
+--format p
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in testgem.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,38 @@
+PATH
+  remote: .
+  specs:
+    massive_record (0.1.0)
+      activemodel
+      activesupport
+      thrift (>= 0.5.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activesupport (3.0.3)
+    builder (2.1.2)
+    diff-lcs (1.1.2)
+    i18n (0.5.0)
+    rspec (2.2.0)
+      rspec-core (~> 2.2)
+      rspec-expectations (~> 2.2)
+      rspec-mocks (~> 2.2)
+    rspec-core (2.2.1)
+    rspec-expectations (2.2.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.2.0)
+    thrift (0.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activemodel
+  activesupport
+  massive_record!
+  rspec (>= 2.1.0)
+  thrift (>= 0.5.0)

data/Manifest

@@ -0,0 +1,24 @@
+Manifest
+README.md
+Rakefile
+autotest/discover.rb
+lib/massive_record.rb
+lib/massive_record/base.rb
+lib/massive_record/cell.rb
+lib/massive_record/column_families_collection.rb
+lib/massive_record/column_family.rb
+lib/massive_record/connection.rb
+lib/massive_record/migration.rb
+lib/massive_record/row.rb
+lib/massive_record/scanner.rb
+lib/massive_record/table.rb
+lib/massive_record/tables_collection.rb
+lib/massive_record/thrift/hbase.rb
+lib/massive_record/thrift/hbase_constants.rb
+lib/massive_record/thrift/hbase_types.rb
+massive_record.gemspec
+spec/README.md
+spec/config.yml.example
+spec/connection_spec.rb
+spec/spec_helper.rb
+spec/table_spec.rb

data/README.md

@@ -0,0 +1,225 @@
+# Massive Record
+
+Massive Record is an ORM for HBase. It currently uses
+Thrift to communicate with HBase and will in time support
+other forms for communicating with Hbase.
+
+
+See introduction to HBase model architecture:  
+http://wiki.apache.org/hadoop/Hbase/HbaseArchitecture  
+Understanding terminology of Table / Row / Column family / Column / Cell:  
+http://jimbojw.com/wiki/index.php?title=Understanding_Hbase_and_BigTable
+
+
+## Installation
+
+  gem install massive_record
+
+### Ruby on Rails
+    
+Add the following Gems in your Gemfile:
+    
+    gem 'massive_record'
+
+Create an config/hbase.yml file with the following content:
+  
+    defaults: &defaults
+      host: somewhere.compute.amazonaws.com # No 'http', it's a Thrift connection
+      port: 9090
+
+    development:
+      <<: *defaults
+
+    test:
+      <<: *defaults
+
+    production:
+      <<: *defaults
+
+
+## Usage
+
+There are two ways for using the Massive Record library. At the highest level we have ORM. This is Active Model compliant and makes
+it easy to use. The second way of doing things is working directly against the wrapper (soon to be called adapter).
+
+
+### ORM
+    
+Both MassiveRecord::ORM::Table and MassiveRecord::ORM::Column do now have some functionality which you can expect from an ORM. This includes:
+    - An initializer which takes attribute hash and assigns them to your object.
+    - Write and read methods for the attributes
+    - Validations, as you expect from an ActiveRecord.
+    - Callbacks, as you expect from an ActiveRecord.
+    - Information about changes on attributes.
+    - Casting of attributes
+    - Serialization of array / hashes
+
+Tables also have:
+    - Persistencey method calls like create, save and destroy (but they do not actually save things to hbase)
+    - Easy access to adapter's connection via Person.connection
+    - Easy access to adapter's hbase table via Person.table
+    - Finder method, like Person.find("an_id"), Person.find("id1", "id2"), Person.all etc
+    - Save / update methods
+    - Auto-creation of table and column families on save if table does not exists.
+    - Destroy records
+
+
+Here is an example of usage, both for Table and Column:
+
+    class Person < MassiveRecord::ORM::Table
+      column_family :info do
+        field :name
+        field :email
+        field :phone_number
+        field :points, :integer, :default => 0
+        field :date_of_birth, :date
+        field :newsletter, :boolean, :default => false
+      end
+
+      validates_presence_of :name, :email
+      validates_format_of :email, :with => /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i
+    end
+
+    
+    
+    class Address < MassiveRecord::ORM::Column
+      field :street
+      field :number, :integer
+      field :nice_place, :boolean, :default => true
+    end
+
+
+## Wrapper (adapter) API
+
+You can, if you'd like, work directly against the adapter.
+  
+    # Init a new connection with HBase
+    conn = MassiveRecord::Wrapper::Connection.new(:host => 'localhost', :port => 9090)
+    conn.open
+    
+    # OR init a connection using the config/hbase.yml file with Rails
+    conn = MassiveRecord::Wrapper::Base.connection
+  
+    # Fetch tables name
+    conn.tables # => ["companies", "news", "webpages"]
+  
+    # Init a table
+    table = MassiveRecord::Wrapper::Table.new(conn, :people)
+  
+    # Add a column family
+    column = MassiveRecord::Wrapper::ColumnFamily.new(:info)
+    table.column_families.push(column)
+  
+    # Or bulk add column families
+    table.create_column_families([:friends, :misc])
+    
+    # Create the table
+    table.save # will raise an exception if the table already exists
+  
+    # Fetch column families from the database
+    table.fetch_column_families # => [ColumnFamily#RTY4424, ColumnFamily#R475424, ColumnFamily#GHJ9424]
+    table.column_families.collect(&:name) # => ["info", "friends", "misc"]
+  
+    # Add a new row
+    row = MassiveRecord::Wrapper::Row.new
+    row.id = "my_unique_id"
+    row.values = { :info => { :first_name => "H", :last_name => "Base", :email => "h@base.com" } }
+    row.table = table
+    row.save
+  
+    # Fetch rows
+    table.first # => MassiveRecord#ID1
+    table.all(:limit => 10) # => [MassiveRecord#ID1, MassiveRecord#ID2, ...]
+    table.find("ID2") # => MassiveRecord#ID2
+    table.find(["ID1", "ID2"]) # => [MassiveRecord#ID1, MassiveRecord#ID2]
+    table.all(:limit => 3, :start => "ID2") # => [MassiveRecord#ID2, MassiveRecord#ID3, MassiveRecord#ID4]
+    
+    # Manipulate rows
+    table.first.destroy # => true
+    
+    # Remove the table
+    table.destroy
+
+
+
+## Planned work
+
+- Rename Wrapper to Adapter, and make it easy to switch from Thrift to another way of communicating with Hbase.
+- Automatically handling time stamps like created_at and updated_at.
+- Associations and embedded objects.
+- Implement other Adapters, for instance using jruby and the Java API.
+
+
+
+## Contribute
+
+If you want to contribute feel free to fork this project :-)
+Make a feature branch, write test, implement and make a pull request.
+
+### Getting started
+
+    git clone git://github.com/CompanyBook/massive_record.git (or the address to your fork)
+    cd massive_record
+    bundle install
+
+Next up you need to add a config.yml file inside of spec/ which contains something like:
+    host: url.to-a.thrift.server
+    port: 9090
+    table: massive_record_test_table
+
+You should now be able to run `rspec spec/`
+
+### Play with it in the console
+
+Checkout the massive_record project and install it as a Gem :
+
+    cd massive_record/
+    bundle console
+    ruby-1.9.2-p0 > Bundler.require
+     => [
+          <Bundler::Dependency type=:runtime name="massive_record" requirements=">= 0">,
+          <Bundler::Dependency type=:runtime name="thrift" requirements=">= 0.5.0">,
+          <Bundler::Dependency type=:runtime name="activesupport" requirements=">= 0">,
+          <Bundler::Dependency type=:runtime name="activemodel" requirements=">= 0">,
+          <Bundler::Dependency type=:runtime name="rspec" requirements=">= 2.1.0">
+        ]
+    ruby-1.9.2-p0 > MassiveRecord::VERSION
+     => "0.0.1" 
+    
+### Clean HBase database between each test
+
+We have created a helper module MassiveRecord::Rspec::SimpleDatabaseCleaner which, when included into rspec tests, will clean
+the database for ORM records between each test case. You can also take a look into spec/support/mock_massive_record_connection.rb
+for some functionality which will mock a hbase connection making it easier (faster) to test code where no real database is needed.
+
+    
+
+
+## More Information and Resources
+
+### Thrift API
+
+Ruby Library using the HBase Thrift API.
+http://wiki.apache.org/hadoop/Hbase/ThriftApi
+
+The generated Ruby files can be found under lib/massive_record/thrift/  
+The whole API (CRUD and more) is present in the Client object (Apache::Hadoop::Hbase::Thrift::Hbase::Client).  
+The client can be easily initialized using the MassiveRecord connection :
+
+    conn = MassiveRecord::Wrapper::Connection.new(:host => 'localhost', :port => 9090)
+    conn.open
+    
+    client = conn.client
+    # Do whatever you want with the client object
+    
+### Q&A
+
+How to add a new column family to an existing table?
+    
+    # Connect to the HBase console on the server itself and enter the following code :
+    disable 'companies'
+    alter 'companies', { NAME => 'new_collumn_familiy' }
+    enable 'companies'
+
+
+Copyright (c) 2011 Companybook, released under the MIT license

data/Rakefile

@@ -0,0 +1,16 @@
+$:.push File.expand_path("../lib", __FILE__)
+require 'bundler'
+require "massive_record/version"
+
+Bundler::GemHelper.install_tasks
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "MassiveRecord #{MassiveRecord::VERSION}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/TODO.md

@@ -0,0 +1,8 @@
+# TODO
+
+  * code documentation
+  * Rails ORM (ActiveModel etc.)
+  * write tests
+  * add generators for hbase.yml etc.
+  * add migration tools
+  * ...

data/autotest/discover.rb

@@ -0,0 +1 @@
+Autotest.add_discovery { "rspec2" }

data/lib/massive_record.rb

@@ -0,0 +1,18 @@
+# Thrift Gems
+require 'thrift'
+require 'thrift/transport/socket'
+require 'thrift/protocol/binary_protocol'
+
+# Exceptions
+require 'massive_record/exceptions'
+
+# Generated Ruby classes from Thrift for HBase
+require 'massive_record/thrift/hbase_constants'
+require 'massive_record/thrift/hbase_types'
+require 'massive_record/thrift/hbase'
+
+# Wrapper
+require 'massive_record/wrapper/base'
+
+# ORM
+require 'massive_record/orm/base'

data/lib/massive_record/exceptions.rb

@@ -0,0 +1,11 @@
+module MassiveRecord
+  
+  class ConnectionException < Exception
+    
+    def initialize
+      
+    end
+    
+  end
+  
+end

data/lib/massive_record/orm/attribute_methods.rb

@@ -0,0 +1,61 @@
+module MassiveRecord
+  module ORM
+    module AttributeMethods
+      extend ActiveSupport::Concern
+      include ActiveModel::AttributeMethods      
+
+      module ClassMethods
+        def define_attribute_methods
+          super(known_attribute_names)
+        end
+      end
+
+
+      def attributes
+        @attributes ||= {}
+      end
+      
+      def attributes=(new_attributes)
+        return unless new_attributes.is_a?(Hash)
+
+        new_attributes.each do |attr, value|
+          writer_method = "#{attr}="
+          if respond_to? writer_method
+            send(writer_method, value)
+          else
+            raise UnkownAttributeError.new("Unkown attribute: #{attr}")
+          end
+        end
+      end
+
+      
+      def method_missing(method, *args, &block)
+        unless self.class.attribute_methods_generated?
+          self.class.define_attribute_methods
+          send(method, *args, &block)
+        else
+          super
+        end
+      end
+
+      def respond_to?(*args)
+        self.class.define_attribute_methods unless self.class.attribute_methods_generated?
+        super
+      end
+
+      private
+
+      def attributes_raw=(new_attributes)
+        return unless new_attributes.is_a?(Hash)
+        attributes = new_attributes.stringify_keys
+        @attributes = {'id' => nil}.merge(attributes)
+      end
+
+      def attributes_from_field_definition
+        attributes = {'id' => nil}
+        attributes.merge! self.class.default_attributes_from_schema if self.class.respond_to? :default_attributes_from_schema
+        attributes
+      end
+    end
+  end
+end