activerecord_authorails 1.0.0

data/README

@@ -0,0 +1,360 @@
+= Active Record -- Object-relation mapping put on rails
+
+Active Record connects business objects and database tables to create a persistable
+domain model where logic and data are presented in one wrapping. It's an implementation 
+of the object-relational mapping (ORM) pattern[http://www.martinfowler.com/eaaCatalog/activeRecord.html] 
+by the same name as described by Martin Fowler:
+
+  "An object that wraps a row in a database table or view, encapsulates 
+       the database access, and adds domain logic on that data."
+
+Active Record's main contribution to the pattern is to relieve the original of two stunting problems:
+lack of associations and inheritance. By adding a simple domain language-like set of macros to describe
+the former and integrating the Single Table Inheritance pattern for the latter, Active Record narrows the
+gap of functionality between the data mapper and active record approach.
+
+A short rundown of the major features:
+
+* Automated mapping between classes and tables, attributes and columns.
+
+   class Product < ActiveRecord::Base; end
+   
+   ...is automatically mapped to the table named "products", such as:
+   
+   CREATE TABLE products (
+     id int(11) NOT NULL auto_increment,
+     name varchar(255),
+     PRIMARY KEY  (id)
+   );
+
+   ...which again gives Product#name and Product#name=(new_name) 
+   
+  {Learn more}[link:classes/ActiveRecord/Base.html]
+
+
+* Associations between objects controlled by simple meta-programming macros. 
+
+   class Firm < ActiveRecord::Base
+     has_many   :clients
+     has_one    :account
+     belongs_to :conglomorate
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Associations/ClassMethods.html]
+
+
+* Aggregations of value objects controlled by simple meta-programming macros. 
+
+   class Account < ActiveRecord::Base
+     composed_of :balance, :class_name => "Money",
+                 :mapping => %w(balance amount)
+     composed_of :address, 
+                 :mapping => [%w(address_street street), %w(address_city city)]
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Aggregations/ClassMethods.html]
+
+
+* Validation rules that can differ for new or existing objects.
+
+    class Account < ActiveRecord::Base
+      validates_presence_of     :subdomain, :name, :email_address, :password
+      validates_uniqueness_of   :subdomain
+      validates_acceptance_of   :terms_of_service, :on => :create
+      validates_confirmation_of :password, :email_address, :on => :create
+    end
+
+  {Learn more}[link:classes/ActiveRecord/Validations.html]
+
+
+* Acts that can make records work as lists or trees:
+
+    class Item < ActiveRecord::Base
+      belongs_to   :list
+      acts_as_list :scope => :list
+    end
+    
+    item.move_higher
+    item.move_to_bottom
+
+  Learn about {acts_as_list}[link:classes/ActiveRecord/Acts/List/ClassMethods.html], {the instance methods acts_as_list provides}[link:classes/ActiveRecord/Acts/List/InstanceMethods.html], and
+  {acts_as_tree}[link:classes/ActiveRecord/Acts/Tree/ClassMethods.html]
+ 
+* Callbacks as methods or queues on the entire lifecycle (instantiation, saving, destroying, validating, etc).
+
+   class Person < ActiveRecord::Base
+     def before_destroy # is called just before Person#destroy
+       CreditCard.find(credit_card_id).destroy
+     end
+   end
+
+   class Account < ActiveRecord::Base
+     after_find :eager_load, 'self.class.announce(#{id})'
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Callbacks.html]
+
+
+* Observers for the entire lifecycle
+
+   class CommentObserver < ActiveRecord::Observer
+     def after_create(comment) # is called just after Comment#save
+       Notifications.deliver_new_comment("david@loudthinking.com", comment)
+     end
+   end
+
+  {Learn more}[link:classes/ActiveRecord/Observer.html]
+
+
+* Inheritance hierarchies 
+
+   class Company < ActiveRecord::Base; end
+   class Firm < Company; end
+   class Client < Company; end
+   class PriorityClient < Client; end
+
+  {Learn more}[link:classes/ActiveRecord/Base.html]
+
+
+* Transaction support on both a database and object level. The latter is implemented 
+  by using Transaction::Simple[http://railsmanual.com/module/Transaction::Simple]
+
+    # Just database transaction
+    Account.transaction do
+      david.withdrawal(100)
+      mary.deposit(100)
+    end
+
+    # Database and object transaction
+    Account.transaction(david, mary) do
+      david.withdrawal(100)
+      mary.deposit(100)
+    end
+
+  {Learn more}[link:classes/ActiveRecord/Transactions/ClassMethods.html]
+
+
+* Reflections on columns, associations, and aggregations
+
+    reflection = Firm.reflect_on_association(:clients)
+    reflection.klass # => Client (class)
+    Firm.columns # Returns an array of column descriptors for the firms table
+
+  {Learn more}[link:classes/ActiveRecord/Reflection/ClassMethods.html]
+
+
+* Direct manipulation (instead of service invocation)
+
+  So instead of (Hibernate[http://www.hibernate.org/] example):
+
+     long pkId = 1234;
+     DomesticCat pk = (DomesticCat) sess.load( Cat.class, new Long(pkId) );
+     // something interesting involving a cat...
+     sess.save(cat);
+     sess.flush(); // force the SQL INSERT
+
+  Active Record lets you:
+
+     pkId = 1234
+     cat = Cat.find(pkId)
+     # something even more interesting involving the same cat...
+     cat.save
+
+  {Learn more}[link:classes/ActiveRecord/Base.html]
+
+
+* Database abstraction through simple adapters (~100 lines) with a shared connector
+
+   ActiveRecord::Base.establish_connection(:adapter => "sqlite", :database => "dbfile")
+
+   ActiveRecord::Base.establish_connection(
+     :adapter  => "mysql", 
+     :host     => "localhost", 
+     :username => "me", 
+     :password => "secret", 
+     :database => "activerecord"
+   )
+
+  {Learn more}[link:classes/ActiveRecord/Base.html#M000081] and read about the built-in support for
+  MySQL[link:classes/ActiveRecord/ConnectionAdapters/MysqlAdapter.html], PostgreSQL[link:classes/ActiveRecord/ConnectionAdapters/PostgreSQLAdapter.html], SQLite[link:classes/ActiveRecord/ConnectionAdapters/SQLiteAdapter.html], Oracle[link:classes/ActiveRecord/ConnectionAdapters/OCIAdapter.html], SQLServer[link:classes/ActiveRecord/ConnectionAdapters/SQLServerAdapter.html], and DB2[link:classes/ActiveRecord/ConnectionAdapters/DB2Adapter.html].
+
+
+* Logging support for Log4r[http://log4r.sourceforge.net] and Logger[http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc]
+
+    ActiveRecord::Base.logger = Logger.new(STDOUT)
+    ActiveRecord::Base.logger = Log4r::Logger.new("Application Log")
+
+
+== Simple example (1/2): Defining tables and classes (using MySQL)
+
+Data definitions are specified only in the database. Active Record queries the database for 
+the column names (that then serves to determine which attributes are valid) on regular
+object instantiation through the new constructor and relies on the column names in the rows
+with the finders.
+ 
+   # CREATE TABLE companies (
+   #   id int(11) unsigned NOT NULL auto_increment,
+   #   client_of int(11),
+   #   name varchar(255),
+   #   type varchar(100),
+   #   PRIMARY KEY  (id)
+   # )
+
+Active Record automatically links the "Company" object to the "companies" table
+
+   class Company < ActiveRecord::Base
+     has_many :people, :class_name => "Person"
+   end
+
+   class Firm < Company
+     has_many :clients
+  
+     def people_with_all_clients
+      clients.inject([]) { |people, client| people + client.people }
+     end
+   end
+
+The foreign_key is only necessary because we didn't use "firm_id" in the data definition
+ 
+   class Client < Company
+     belongs_to :firm, :foreign_key => "client_of"
+   end
+
+   # CREATE TABLE people (
+   #   id int(11) unsigned NOT NULL auto_increment,
+   #   name text,
+   #   company_id text,
+   #   PRIMARY KEY  (id)
+   # )
+
+Active Record will also automatically link the "Person" object to the "people" table
+
+   class Person < ActiveRecord::Base
+     belongs_to :company
+   end
+
+== Simple example (2/2): Using the domain
+
+Picking a database connection for all the Active Records
+
+   ActiveRecord::Base.establish_connection(
+     :adapter  => "mysql", 
+     :host     => "localhost", 
+     :username => "me", 
+     :password => "secret", 
+     :database => "activerecord"
+   )
+
+Create some fixtures
+
+   firm = Firm.new("name" => "Next Angle")
+   # SQL: INSERT INTO companies (name, type) VALUES("Next Angle", "Firm")
+   firm.save
+
+   client = Client.new("name" => "37signals", "client_of" => firm.id)
+   # SQL: INSERT INTO companies (name, client_of, type) VALUES("37signals", 1, "Firm")
+   client.save
+
+Lots of different finders
+
+   # SQL: SELECT * FROM companies WHERE id = 1
+   next_angle = Company.find(1)
+
+   # SQL: SELECT * FROM companies WHERE id = 1 AND type = 'Firm'
+   next_angle = Firm.find(1)    
+
+   # SQL: SELECT * FROM companies WHERE id = 1 AND name = 'Next Angle'
+   next_angle = Company.find(:first, :conditions => "name = 'Next Angle'")
+
+   next_angle = Firm.find_by_sql("SELECT * FROM companies WHERE id = 1").first
+
+The supertype, Company, will return subtype instances
+
+   Firm === next_angle
+
+All the dynamic methods added by the has_many macro
+
+  next_angle.clients.empty?  # true
+  next_angle.clients.size    # total number of clients
+  all_clients = next_angle.clients
+
+Constrained finds makes access security easier when ID comes from a web-app
+
+   # SQL: SELECT * FROM companies WHERE client_of = 1 AND type = 'Client' AND id = 2
+   thirty_seven_signals = next_angle.clients.find(2)
+
+Bi-directional associations thanks to the "belongs_to" macro
+
+   thirty_seven_signals.firm.nil? # true
+
+
+== Examples
+
+Active Record ships with a couple of examples that should give you a good feel for
+operating usage. Be sure to edit the <tt>examples/shared_setup.rb</tt> file for your
+own database before running the examples. Possibly also the table definition SQL in 
+the examples themselves.
+
+It's also highly recommended to have a look at the unit tests. Read more in link:files/RUNNING_UNIT_TESTS.html
+
+
+== Philosophy 
+
+Active Record attempts to provide a coherent wrapper as a solution for the inconvenience that is 
+object-relational mapping. The prime directive for this mapping has been to minimize
+the amount of code needed to build a real-world domain model. This is made possible
+by relying on a number of conventions that make it easy for Active Record to infer
+complex relations and structures from a minimal amount of explicit direction.
+
+Convention over Configuration:
+* No XML-files!
+* Lots of reflection and run-time extension
+* Magic is not inherently a bad word 
+
+Admit the Database:
+* Lets you drop down to SQL for odd cases and performance
+* Doesn't attempt to duplicate or replace data definitions
+
+
+== Download
+
+The latest version of Active Record can be found at
+
+* http://rubyforge.org/project/showfiles.php?group_id=182
+
+Documentation can be found at 
+
+* http://ar.rubyonrails.com
+
+
+== Installation
+
+The prefered method of installing Active Record is through its GEM file. You'll need to have
+RubyGems[http://rubygems.rubyforge.org/wiki/wiki.pl] installed for that, though. If you have,
+then use:
+
+  % [sudo] gem install activerecord-1.10.0.gem
+
+You can also install Active Record the old-fashion way with the following command:
+
+  % [sudo] ruby install.rb
+
+from its distribution directory.
+
+
+== License
+
+Active Record is released under the MIT license.
+
+
+== Support
+
+The Active Record homepage is http://www.rubyonrails.com. You can find the Active Record
+RubyForge page at http://rubyforge.org/projects/activerecord. And as Jim from Rake says:
+
+   Feel free to submit commits or feature requests.  If you send a patch,
+   remember to update the corresponding unit tests.  If fact, I prefer
+   new feature to be submitted in the form of new unit tests.
+
+For other information, feel free to ask on the ruby-talk mailing list
+(which is mirrored to comp.lang.ruby) or contact mailto:david@loudthinking.com.

data/RUNNING_UNIT_TESTS

@@ -0,0 +1,64 @@
+== Creating the test database
+
+The default names for the test databases are "activerecord_unittest" and 
+"activerecord_unittest2". If you want to use another database name then be sure 
+to update the connection adapter setups you want to test with in 
+test/connections/<your database>/connection.rb. 
+When you have the database online, you can import the fixture tables with 
+the test/fixtures/db_definitions/*.sql files.
+
+Make sure that you create database objects with the same user that you specified in 
+connection.rb otherwise (on Postgres, at least) tests for default values will fail.
+
+== Running with Rake
+
+The easiest way to run the unit tests is through Rake. The default task runs
+the entire test suite for all the adapters. You can also run the suite on just
+one adapter by using the tasks test_mysql, test_sqlite, test_postgresql or any
+of the other test_ tasks. For more information, checkout the full array of rake
+tasks with "rake -T"
+
+Rake can be found at http://rake.rubyforge.org
+
+== Running by hand
+
+Unit tests are located in test directory. If you only want to run a single test suite, 
+or don't want to bother with Rake, you can do so with something like:
+
+   cd test; ruby -I "connections/native_mysql" base_test.rb
+   
+That'll run the base suite using the MySQL-Ruby adapter. Change the adapter
+and test suite name as needed.
+
+You can also run all the suites on a specific adapter with:
+
+   cd test; all.sh "connections/native_mysql"
+
+== Faster tests
+
+If you are using a database that supports transactions, you can set the
+"AR_TX_FIXTURES" environment variable to "yes" to use transactional fixtures.
+This gives a very large speed boost. With rake:
+
+  rake AR_TX_FIXTURES=yes
+
+Or, by hand:
+
+  AR_TX_FIXTURES=yes ruby -I connections/native_sqlite3 base_test.rb
+
+== Testing with Oracle
+
+In order to allow for testing against Oracle using an "arunit" schema within an existing
+Oracle database, the database name and tns connection string must be set in environment
+variables prior to running the unit tests.
+
+  $ export ARUNIT_DB_NAME=MYDB
+  $ export ARUNIT_DB=MYDB
+
+The ARUNIT_DB_NAME variable should be set to the name by which the database knows
+itself, ie., what will be returned by the query:
+
+  select sys_context('userenv','db_name') db from dual
+
+And the ARUNIT_DB variable should be set to the tns connection string.
+

data/Rakefile

@@ -0,0 +1,226 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require File.join(File.dirname(__FILE__), 'lib', 'active_record', 'version')
+
+PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
+PKG_NAME      = 'activerecord'
+PKG_VERSION   = ActiveRecord::VERSION::STRING + PKG_BUILD
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+
+RELEASE_NAME  = "REL #{PKG_VERSION}"
+
+RUBY_FORGE_PROJECT = "activerecord"
+RUBY_FORGE_USER    = "webster132"
+
+PKG_FILES = FileList[
+    "lib/**/*", "test/**/*", "examples/**/*", "doc/**/*", "[A-Z]*", "install.rb", "Rakefile"
+].exclude(/\bCVS\b|~$/)
+
+
+desc "Default Task"
+task :default => [ :test_mysql, :test_sqlite, :test_postgresql ]
+
+# Run the unit tests
+
+for adapter in %w( mysql postgresql sqlite sqlite3 firebird sqlserver sqlserver_odbc db2 oracle sybase openbase frontbase )
+  Rake::TestTask.new("test_#{adapter}") { |t|
+    t.libs << "test" << "test/connections/native_#{adapter}"
+    if adapter =~ /^sqlserver/
+      t.pattern = "test/**/*_test{,_sqlserver}.rb"
+    else
+      t.pattern = "test/**/*_test{,_#{adapter}}.rb"
+    end
+    t.verbose = true
+  }
+end
+
+SCHEMA_PATH = File.join(File.dirname(__FILE__), *%w(test fixtures db_definitions))
+
+desc 'Build the MySQL test databases'
+task :build_mysql_databases do 
+  %x( mysqladmin  create activerecord_unittest )
+  %x( mysqladmin  create activerecord_unittest2 )
+  %x( mysql -e "grant all on activerecord_unittest.* to rails@localhost" )
+  %x( mysql -e "grant all on activerecord_unittest2.* to rails@localhost" )
+  %x( mysql  activerecord_unittest < #{File.join(SCHEMA_PATH, 'mysql.sql')} )
+  %x( mysql  activerecord_unittest < #{File.join(SCHEMA_PATH, 'mysql2.sql')} )
+end
+
+desc 'Drop the MySQL test databases'
+task :drop_mysql_databases do 
+  %x( mysqladmin -f drop activerecord_unittest )
+  %x( mysqladmin -f drop activerecord_unittest2 )
+end
+
+desc 'Rebuild the MySQL test databases'
+task :rebuild_mysql_databases => [:drop_mysql_databases, :build_mysql_databases]
+
+desc 'Build the PostgreSQL test databases'
+task :build_postgresql_databases do 
+  %x( createdb -U postgres activerecord_unittest )
+  %x( createdb -U postgres activerecord_unittest2 )
+  %x( psql activerecord_unittest -f #{File.join(SCHEMA_PATH, 'postgresql.sql')} postgres )
+  %x( psql activerecord_unittest2 -f #{File.join(SCHEMA_PATH, 'postgresql2.sql')}  postgres )
+end
+
+desc 'Drop the PostgreSQL test databases'
+task :drop_postgresql_databases do 
+  %x( dropdb -U postgres activerecord_unittest )
+  %x( dropdb -U postgres activerecord_unittest2 )
+end
+
+desc 'Rebuild the PostgreSQL test databases'
+task :rebuild_postgresql_databases => [:drop_postgresql_databases, :build_postgresql_databases]
+
+desc 'Build the FrontBase test databases'
+task :build_frontbase_databases => :rebuild_frontbase_databases 
+
+desc 'Rebuild the FrontBase test databases'
+task :rebuild_frontbase_databases do
+  build_frontbase_database = Proc.new do |db_name, sql_definition_file|
+    %(
+      STOP DATABASE #{db_name};
+      DELETE DATABASE #{db_name};
+      CREATE DATABASE #{db_name};
+
+      CONNECT TO #{db_name} AS SESSION_NAME USER _SYSTEM;
+      SET COMMIT FALSE;
+
+      CREATE USER RAILS;
+      CREATE SCHEMA RAILS AUTHORIZATION RAILS;
+      COMMIT;
+
+      SET SESSION AUTHORIZATION RAILS;
+      SCRIPT '#{sql_definition_file}';
+
+      COMMIT;
+
+      DISCONNECT ALL; 
+    )
+  end
+  create_activerecord_unittest  = build_frontbase_database['activerecord_unittest',  File.join(SCHEMA_PATH, 'frontbase.sql')]
+  create_activerecord_unittest2 = build_frontbase_database['activerecord_unittest2', File.join(SCHEMA_PATH, 'frontbase2.sql')]
+  execute_frontbase_sql = Proc.new do |sql| 
+    system(<<-SHELL)
+    /Library/FrontBase/bin/sql92 <<-SQL
+    #{sql}
+    SQL
+    SHELL
+  end
+  execute_frontbase_sql[create_activerecord_unittest]
+  execute_frontbase_sql[create_activerecord_unittest2]
+end
+
+# Generate the RDoc documentation
+
+Rake::RDocTask.new { |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "Active Record -- Object-relation mapping put on rails"
+  rdoc.options << '--line-numbers' << '--inline-source' << '-A cattr_accessor=object'
+  rdoc.template = "#{ENV['template']}.rb" if ENV['template']
+  rdoc.rdoc_files.include('README', 'RUNNING_UNIT_TESTS', 'CHANGELOG')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.exclude('lib/active_record/vendor/*')
+  rdoc.rdoc_files.include('dev-utils/*.rb')
+}
+
+# Enhance rdoc task to copy referenced images also
+task :rdoc do
+  FileUtils.mkdir_p "doc/files/examples/"
+  FileUtils.copy "examples/associations.png", "doc/files/examples/associations.png"
+end
+
+
+# Create compressed packages
+
+dist_dirs = [ "lib", "test", "examples", "dev-utils" ]
+
+spec = Gem::Specification.new do |s|
+  s.name = PKG_NAME
+  s.version = PKG_VERSION
+  s.summary = "Implements the ActiveRecord pattern for ORM."
+  s.description = %q{Implements the ActiveRecord pattern (Fowler, PoEAA) for ORM. It ties database tables and classes together for business objects, like Customer or Subscription, that can find, save, and destroy themselves without resorting to manual SQL.}
+
+  s.files = [ "Rakefile", "install.rb", "README", "RUNNING_UNIT_TESTS", "CHANGELOG" ]
+  dist_dirs.each do |dir|
+    s.files = s.files + Dir.glob( "#{dir}/**/*" ).delete_if { |item| item.include?( "\.svn" ) }
+  end
+  
+  s.add_dependency('activesupport', '= 1.4.2' + PKG_BUILD)
+
+  s.files.delete "test/fixtures/fixture_database.sqlite"
+  s.files.delete "test/fixtures/fixture_database_2.sqlite"
+  s.files.delete "test/fixtures/fixture_database.sqlite3"
+  s.files.delete "test/fixtures/fixture_database_2.sqlite3"
+  s.require_path = 'lib'
+  s.autorequire = 'active_record'
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = %w( README )
+  s.rdoc_options.concat ['--main',  'README']
+  
+  s.author = "David Heinemeier Hansson"
+  s.email = "david@loudthinking.com"
+  s.homepage = "http://www.rubyonrails.org"
+  s.rubyforge_project = "activerecord"
+end
+  
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+task :lines do
+  lines, codelines, total_lines, total_codelines = 0, 0, 0, 0
+
+  for file_name in FileList["lib/active_record/**/*.rb"]
+    next if file_name =~ /vendor/
+    f = File.open(file_name)
+
+    while line = f.gets
+      lines += 1
+      next if line =~ /^\s*$/
+      next if line =~ /^\s*#/
+      codelines += 1
+    end
+    puts "L: #{sprintf("%4d", lines)}, LOC #{sprintf("%4d", codelines)} | #{file_name}"
+    
+    total_lines     += lines
+    total_codelines += codelines
+    
+    lines, codelines = 0, 0
+  end
+
+  puts "Total: Lines #{total_lines}, LOC #{total_codelines}"
+end
+
+
+# Publishing ------------------------------------------------------
+
+desc "Publish the beta gem"
+task :pgem => [:package] do 
+  Rake::SshFilePublisher.new("davidhh@wrath.rubyonrails.org", "public_html/gems/gems", "pkg", "#{PKG_FILE_NAME}.gem").upload
+  `ssh davidhh@wrath.rubyonrails.org './gemupdate.sh'`
+end
+
+desc "Publish the API documentation"
+task :pdoc => [:rdoc] do 
+  Rake::SshDirPublisher.new("davidhh@wrath.rubyonrails.org", "public_html/ar", "doc").upload
+end
+
+desc "Publish the release files to RubyForge."
+task :release => [ :package ] do
+  require 'rubyforge'
+
+  packages = %w( gem tgz zip ).collect{ |ext| "pkg/#{PKG_NAME}-#{PKG_VERSION}.#{ext}" }
+
+  rubyforge = RubyForge.new
+  rubyforge.login
+  rubyforge.add_release(PKG_NAME, PKG_NAME, "REL #{PKG_VERSION}", *packages)
+end