og 0.16.0 → 0.17.0

data/README

@@ -1,4 +1,4 @@
-= Og 0.16.0 README
+= Og 0.17.0 README
 
 Og (ObjectGraph) is a powerfull object-relational mapping library. Og provides 
 transparent serialization of object graphs to a RDBMS 
@@ -27,21 +27,29 @@ The library provides the following features:
 
 + Object-Relational mapping.
 + Absolutely no configuration files.
-+ Multiple backend adapters (PostgreSQL, MySQL, SQLite3, Oracle, SqlServer).
++ Multiple stores (PostgreSQL, MySQL, SQLite, Oraclei, SqlServer, ..).
++ Supports non SQL stores.
 + ActiveRecord-style meta language and db aware methods.
-+ Automatially generates join-tables for many_to_many relations.
-+ Deserialize sql join queries to Ruby Objects (coming soon).
++ Deserialize to Ruby Objects.
++ Deserialize sql join queries to Ruby Objects.
++ Eager associations.
 + Serialize arbitrary ruby object graphs through YAML.
 + Connection pooling.
-+ Thread safety.
++ Thread safety (temporarily dissabled).
 + SQL transactions.
-+ Lifecycle event interception and Observers.
++ Aspect oriented constructs allow interception of lifecycle callbacks.
 + Transparent support for cascading deletes for all backends.
-+ Dynamic db related mixins (Orderable, etc).
-+ Hierarchical structures (nested sets, more coming soon).
-+ Works safely as part of a distributed application.
-+ Automatic Validation/Constraints.
-+ Simple and clean implementation.
++ Hierarchical structures (nested sets)
++ Works safely as part of distributed application.
++ Simple implementation.
+
+
+== What's new
+
+For information about the latest changes please consult the
+file
+
+doc/RELEASES
 
 
 == Download
@@ -51,7 +59,7 @@ The latest version of Og can be found at
 * http://nitro.rubyforge.org
 
 Documentation for Og can be found in the distribution. You can find
-a nice tutorial at www.rubygarden.com
+a nice tutorial at www.rubygarden.com.
 
 
 == Requirements
@@ -69,6 +77,8 @@ Og requires the following applications or libraries:
 * Ruby-mysql 
 	http://tmtm.org/ja/ruby/mysql/README_en.html
 	Ruby interface to the MySQL RDBMS.
+	Pure Ruby Mysql interface:
+	http://www.tmtm.org/ruby/mysql/
 	
 * PostgreSQL 
 	http://www.postgres.org
@@ -78,6 +88,9 @@ Og requires the following applications or libraries:
 	http://www.mysql.org
 	Used for the Database Backend.
 
+* SQLite
+	http://www.sqlite.org/download.html
+
 Please install the required applications and libraries before continuing
 with the installation of Og. Only install the libraries needed for
 the backend you plan to use.
@@ -98,6 +111,16 @@ Then try to run the examples in the examples directory.
 A tar.gz distribution is also available on http://www.rubyforge.com/projects/nitro.
 
 
+== Examples:
+
+Some examples can be found in the examples directory. You are also
+encouraged to check out the unit tests. Especially the test:
+
+test/og/tc_store.rb
+
+demonstrates some advanced features of Og.
+
+
 == Support
 
 For any questions regarding Og, feel free to ask on the ruby-talk 

data/Rakefile

@@ -1,7 +1,3 @@
-# * George Moschovitis  <gm@navel.gr>
-# (c) 2005 Navel, all rights reserved.
-# $Id$
-
 require 'rake/rdoctask'
 require 'rake/testtask'
 require 'rake/gempackagetask'
@@ -61,9 +57,10 @@ spec = Gem::Specification.new do |s|
 	s.description = 'An efficient and transparent Object-Relational mapping library'
 	
 	s.add_dependency 'glue', "= #{s.version}"
-	# s.add_dependency 'postgres-pr', '>= 0.3.0'
-	# s.add_dependency 'postgres', '>= 0.7.1'
-	# s.add_dependency 'sqlite3-ruby', '>= 1.0.0'
+	s.add_dependency 'facets', '>= 0.7.1'
+	#s.add_dependency 'postgres-pr', '>= 0.3.0'
+	#s.add_dependency 'postgres', '>= 0.7.1'
+	#s.add_dependency 'sqlite3-ruby', '>= 1.0.0'
 	#s.add_dependency 'mysql', '>= 2.5.1'
 
 	s.required_ruby_version = '>= 1.8.2'

data/benchmark/bench.rb

@@ -1,6 +1,6 @@
 # * George Moschovitis  <gm@navel.gr>
 # (c) 2004-2005 Navel, all rights reserved.
-# $Id: bench.rb 1 2005-04-11 11:04:30Z gmosx $
+# $Id: bench.rb 34 2005-04-26 09:07:39Z gmosx $
 
 require 'og'; include Og
 

data/doc/AUTHORS

@@ -6,14 +6,14 @@ MAIN DEVELOPER:
 	
 IDEAS, ADDITIONAL CODING, SUPPORT:
 
+* Michael Neumann  <mneumann@ntecs.de>
+	Design, additional coding and bug reports.
+
 *	Matt Bowen  <matt.bowen@farweststeel.com>
 	Additional code and documentation.
 
 * Anastasios Koutoumanos  <ak@navel.gr>
 	Design, additional coding.
 
-* Michael Neumann  <mneumann@ntecs.de>
-	Design, additional coding and bug reports.
-
 * Thomas Quas  <tquas@yahoo.com>
 	Ideas, bug reports, unit tests.

data/doc/RELEASES

@@ -1,9 +1,160 @@
-== Version 0.16.0
+== Version 0.17.0
+
+Og Reloaded!! A totally new, clean and elegant implementation 
+that supports tons of new advanced features. This version should
+be considered as a preview, but you really have to *try* this! 
+A new version, with the rest of the planned features and bug
+fixes is expected shortly. Many thanks to Michael Neumann and 
+the other hackers on the mailing list for ideas and suggestions 
+that made this version possible.
+
+Most notable additions:
+
+* Extremely clean source code. Better names are used thorougout.
+	Extra care was taken to make all features more orthogonal.
+	
+* Brand new relation mechanism. The 'enchanting' of entities 
+	(managed classes) happens in multiple passes to be more
+	flexible. Totaly separated graph/metadata creation and serialization
+	code generation. The Graph metadata can be used for advanced
+	scaffolding, testing and more.
+
+* Support for fully customizable primary keys. You are no longer
+	forced to use xxx_oid primary keys. Appart from the extra 
+	flexibility this feature provides this is an essential step
+	towards the planed 'reverse engineering' mode that will allow the
+	use of existing schemas with Og.
+	
+* More elegant inspection mechanism. Example:
+
+	Article.relation(:user) # => Og::BelongsTo(...)
+	Article.relations # => [...]
+	Article.properties # => [...]
+
+* Joins_many relation, as an alias for one way, join table relations.
+
+* Support for 'active' collections. Active collection are
+	synchronized with the backend Store and provide a more elegant
+	interface and the opportunity for 'session' caching:
+	
+	article.comments << Comment.new
+	
+	instead of 
+	
+	article.add_comment(Comment.new) # this is also allowed though.
+	
+	p article.comments
+	p article.comments.size # the results of the first query is cached
+
+* Eager relations.
+
+	comments = Article.comments(:include => User)
+
+	for comment in comments
+		p comment.user.name
+	end
+	
+	Elegantly solves the N+1 query problem by using one join
+	query.
+
+* No need for forward references when defining relations. Now,
+	the following code magically works:
+	
+	class User
+	  has_many Comment # works even though Comment is not defined!
+	end
+	
+	class Comment
+		belongs_to User
+	end
+	 
+* Use inflection where possible to infer missing configuration
+	options. For example
+	
+	class Article
+		belongs_to User # infects relation name :user
+		...
+		
+* New, lean and mean Store interface. The code needed to teach 
+	Og how to  serialize objects to backend store is dramatically
+	reduced. The new interface is SQL agnostic, so non SQL-RDBM's 
+	stores are possible.
+	
+* SQL agnostic querying interface, compatible with non-sql 
+	Stores. Here is an example:
+	
+	Article.find(
+		:condition => 'hits > 2 AND rate > 3', 
+		:order => 'title',
+		:offset => 30,
+		:limit => 10
+	)
+
+* More elegant (and non-sql store compatible) way for selective 
+	updates:
+
+	article.title = 'Changed'
+	article.hits += 1
+	article.update(:title, :hits)
+
+* New, in-memory store that support all features. This is a pure
+	ruby solution useful for experimentation. It will also serve
+	as the base for the forthcoming madeleine Store implementation.
+
+* Allow for multiple stores in one application. A great example,
+	mysql_to_psql is provided. This example uses Og's powerfull
+	features to automatically convert a Mysql database to a 
+	PostgreSQL database. Database migration was never easier.
+	
+* Uses the excellent Facets utility collection to further
+	clenup and minimize the code.
+
+* Managed classes or Entities should include the EntityMixin
+	or extend the Entity class. Example:
+	
+	class Article < Entity
+		..
+	end
+	
+	class Article 
+		include EntityMixin
+	end
+	
+	This is done to avoid the Module module like in earlier
+	versions of Og. However, Og is can infer the need to include
+	the Managed mixin in typical cases:
+	
+	class Article
+		property :title, String 
+		# when a property is defined Og automatically converts the
+		# class to an Entity
+	end
+	
+	class Article < AnExistingManagedEntity
+		# also includes the mixin
+		...
+		
+	class Article
+		include AModuleThatDefinesProperties
+		...
+
+* Improved support for og_delete interception.
+
+* Support for nested transactions.
+	
+* Many, many smaller features and changes.
+	
+Check out the file test/og/tc_store.rb for a demonstration of
+the new features. The stores for Oracle and SqlServer are not
+converted yet.
+
+
+== Version 0.16.0 was released on 15/04/2005.
 
 A snapshot of the latest developments. Many, many subtle improvements,
 new features and a major cleanup of the source code. 
 
-Most notable attitions:
+Most notable additions:
 
 * Aspect Oriented Programming support. This new system
 	is used to reimplement features such as Controller filters,

data/doc/config.txt

@@ -14,13 +14,6 @@ applications/sites on a single database.
 If true, use Ruby's advanced introspection capabilities to 
 automatically manage classes that define properties.
 	
-=== Og.enchant_managed_classes = true
-
-If true, the library automatically 'enchants' managed classes.
-In enchant mode, special db aware methods are added to 
-managed classes and instances. If false, Og enchants only classes 
-that define properties.
-	
 === Og.create_schema = true
 
 If set to true, Og attempts to recreate the database schema

data/doc/tutorial.txt

@@ -1,5 +1,12 @@
 = Og Tutorial
 
+=== WARNING
+
+This tutorial is not updated for the latest code. However it is
+a nice read to understand the spirit and feature of Og. Please
+consult the API for the latest more advanced features of Og.
+
+
 === Introduction
 
 Ruby is a wonderful object oriented language featuring a well

data/examples/README

@@ -9,3 +9,8 @@ automatically creates a 'test' database.
 
 Demonstrates how easily the Og infrastructure can be mocked,
 for easy test unit writing.
+
+== mysql_to_psql.rb
+
+Demonstrates how easy it is to migrate a mysql database
+to postgres using Og.

data/examples/mysql_to_psql.rb

@@ -1,4 +1,4 @@
-# = Og Mysql to PostgreSQL copy example 
+# = Mysql to PostgreSQL migration example.
 #
 # A simple example to demonstrate the flexibility of
 # Og. Two connections to different databases are 
@@ -6,71 +6,46 @@
 # to a PostgreSQL database.
 #
 # Og makes it easier to switch to a REAL database :)
-#
-# * George Moschovitis  <gm@navel.gr>
-# (c) 2004-2005 Navel, all rights reserved.
-# $Id: mysql_to_psql.rb 1 2005-04-11 11:04:30Z gmosx $
-
-raise 'WARNING, this example does not work yet, for the moment ' + 
-			'just have a look at the source code.'
 
 require 'og'
 
-# An example managed object.
-# Looks like an ordinary Ruby object.
-
-class Article
-	prop_accessor :name, :body, String
-
-	def initialize(name = nil, body = nil)
-		@name, @body = name, body
-	end
-end
-
 # Configure databases.
 
 psql_config = {
-	:address => 'localhost',
-	:database => 'test',
-	:backend => 'psql',
+	:destroy => true,
+	:name => 'test',
+	:store => 'psql',
 	:user => 'postgres',
-	:password => 'navelrulez',
-	:connection_count => 1
+	:password => 'navelrulez'
 }
 
 mysql_config = {
-	:address => 'localhost',
-	:database => 'mysql',
-	:backend => 'psql',
-	:user => 'postgres',
-	:password => 'navelrulez',
-	:connection_count => 1
-}
-=begin
-mysql_config = {
-	:address => 'localhost',
-	:database => 'test',
-	:backend => 'mysql',
+	:destroy => true,
+	:name => 'test',
+	:store => 'mysql',
 	:user => 'root',
-	:password => 'navelrulez',
-	:connection_count => 1
+	:password => 'navelrulez'
 }
-=end
 
-# Cleanup the databases, remove data from
-# earlier executions.
+# Initialize Og.
 
-Og::Database.drop!(psql_config)
-Og::Database.drop!(mysql_config)
+psql = Og.connect(psql_config)
+mysql = Og.connect(mysql_config)
 
-# Initialize Og.
+# An example managed object.
+# Looks like an ordinary Ruby object.
 
-psql = Og::Database.new(psql_config)
-mysql = Og::Database.new(mysql_config)
+class Article
+	property :name, :body, String
+
+	def initialize(name = nil, body = nil)
+		@name, @body = name, body
+	end
+end
 
 # First populate the mysql database.
 
-Og.use(mysql)
+mysql.manage(Article)
 
 a1 = Article.create('name1', 'body1')
 a1 = Article.create('name1', 'body1')
@@ -82,15 +57,15 @@ articles = Article.all
 
 # Switch to PostgreSQL.
 
-Og.use(psql)
+psql.manage(Article)
 
 # Store all articles.
 
 for article in articles
-	article.save!
+	article.insert
 end
 
 # Fetch an article from PostgreSQL
 # as an example. Lookup by name.
 
-article = Article['name1']
+article = Article.find_by_name('name1')