lafcadio 0.9.0 → 0.9.1

data/lib/lafcadio.rb

@@ -16,7 +16,7 @@
 # http://lafcadio.rubyforge.org/tutorial.html.
 
 module Lafcadio
-	Version = "0.9.0"
+	Version = "0.9.1"
 
 	require 'lafcadio/depend'
 	require 'lafcadio/domain'

data/lib/lafcadio.rb~

@@ -16,7 +16,7 @@
 # http://lafcadio.rubyforge.org/tutorial.html.
 
 module Lafcadio
-	Version = "0.8.0"
+	Version = "0.9.0"
 
 	require 'lafcadio/depend'
 	require 'lafcadio/domain'

data/lib/lafcadio/domain.rb

@@ -17,7 +17,7 @@ module Lafcadio
 			if className != ''
 				fieldClass = Class.by_name( 'Lafcadio::' + className )
 				register_name( name )
-				field = fieldClass.instantiate_from_xml( @domain_class, fieldElt )
+				field = fieldClass.create_from_xml( @domain_class, fieldElt )
 				set_field_attributes( field, fieldElt )
 			else
 				msg = "Couldn't find field class '#{ className }' for field " +
@@ -44,7 +44,7 @@ module Lafcadio
 			fieldAttr = []
 			fieldAttr << FieldAttribute.new( 'size', FieldAttribute::INTEGER )
 			fieldAttr << FieldAttribute.new( 'unique', FieldAttribute::BOOLEAN )
-			fieldAttr << FieldAttribute.new( 'not_null', FieldAttribute::BOOLEAN )
+			fieldAttr << FieldAttribute.new( 'not_nil', FieldAttribute::BOOLEAN )
 			fieldAttr << FieldAttribute.new( 'enum_type', FieldAttribute::ENUM,
 																			 BooleanField )
 			fieldAttr << FieldAttribute.new( 'enums', FieldAttribute::HASH )
@@ -120,6 +120,8 @@ module Lafcadio
 		class InvalidDataError < ArgumentError; end
 	end
 
+	# DomainComparable is used by DomainObject and DomainObjectProxy to define
+	# comparisons.
 	module DomainComparable
 		include Comparable
 
@@ -137,6 +139,8 @@ module Lafcadio
 			end
 		end
 		
+		# Two DomainObjects or DomainObjectProxies are eql? if they have the same
+		# +domain_class+ and the same +pk_id+.
 		def eql?( otherObj ); self == otherObj; end
 
 		def hash; "#{ self.class.name } #{ pk_id }".hash; end
@@ -146,24 +150,37 @@ module Lafcadio
 	# of DomainObject.
 	#
 	# = Defining fields
-	# There are two ways to define the fields of a DomainObject subclass.
-	# 1. Defining fields in an XML file. To do this,
-	#    1. Set one directory to contain all your XML files, by setting
-	#       +classDefinitionDir+ in your LafcadioConfig file.
-	#    2. Write one XML file per domain class. For example, a User.xml file
-	#       might look like:
-	#         <lafcadio_class_definition name="User">
-	#           <field name="lastName" class="StringField"/>
-	#           <field name="email" class="StringField"/>
-	#           <field name="password" class="StringField"/>
-	#           <field name="birthday" class="DateField"/>
-	#         </lafcadio_class_definition>
-	# 2. Overriding DomainObject.get_class_fields. The method should return an Array
-	#    of instances of ObjectField or its children. The order is unimportant.
+	# There are three ways to define the fields of a DomainObject subclass.
+	# 1. <b>One-line field definitions</b>: When defining the class, add fields
+	#    with class methods like so:
+	#      class User < Lafcadio::DomainObject
+	#        string 'lastName'
+	#        email  'email'
+	#        string 'password'
+	#        date   'birthday'
+	#      end
+	#    These can also be pluralized:
+	#      class User < Lafcadio::DomainObject
+	#        strings 'lastName', 'password'
+	#        email   'email'
+	#        date    'birthday'
+	#      end
+	#    The class methods you can use are +blob+, +boolean+, +date+,
+	#    +date_time+, +domain_object+, +email+, +enum+, +float+, +integer+,
+	#    +month+, +state+, +string+, +text_list+. These correspond to BlobField,
+	#    BooleanField, DateField, DateTimeField, DomainObjectField, EmailField,
+	#    EnumField, FloatField, IntegerField, MonthField, StateField,
+	#    StringField, and TextListField, respectively. Consult their individual
+	#    RDoc entries for more on how to parameterize them through the class
+	#    methods.
+	# 2. <b>Overriding DomainObject.get_class_fields</b>: The method should
+	#    return an Array of instances of ObjectField or its children. If you use
+	#    this method, make sure to call the superclass (this is needed to define
+	#    the primary key field). The order of fields in the Array is unimportant.
 	#    For example:
 	#      class User < DomainObject 
 	#        def User.get_class_fields 
-	#          fields = [] 
+	#          fields = super
 	#          fields << StringField.new(self, 'firstName') 
 	#          fields << StringField.new(self, 'lastName') 
 	#          fields << StringField.new(self, 'email') 
@@ -172,63 +189,89 @@ module Lafcadio
 	#          fields 
 	#        end 
 	#      end
+	#    This method is probably not worth the trouble unless you end up defining
+	#    your own field classes for some reason.
+	# 3. <b>Defining fields in an XML file</b>: Note that this method may be
+	#    removed in the future. To do this:
+	#    1. Set one directory to contain all your XML files, by setting
+	#       +classDefinitionDir+ in your LafcadioConfig file.
+	#    2. Write one XML file per domain class. For example, a User.xml file
+	#       might look like:
+	#         <lafcadio_class_definition name="User">
+	#           <field name="lastName" class="StringField"/>
+	#           <field name="email" class="StringField"/>
+	#           <field name="password" class="StringField"/>
+	#           <field name="birthday" class="DateField"/>
+	#         </lafcadio_class_definition>
 	#
 	# = Setting and retrieving fields
 	# Once your fields are defined, you can create an instance by passing in a
 	# hash of field names and values.
-	#   john = User.new( 'firstName' => 'John', 'lastName' => 'Doe',
-	#                    'email' => 'john.doe@email.com',
-	#                    'password' => 'my_password',
-	#                    'birthday' => tenYearsAgo )
+	#
+	#   john = User.new(
+	#     :firstName => 'John', :lastName => 'Doe',
+	#     :email => 'john.doe@email.com', :password => 'my_password',
+	#     :birthday => Date.new( 1979, 1, 15 )
+	#   )
 	#
 	# You can read and write these fields like normal instance attributes.
-	#   john.email => 'john.doe@email.com'
+	#   john.email # => 'john.doe@email.com'
 	#   john.email = 'john.doe@mail.email.com'
 	#
 	# If your domain class has fields that refer to other domain classes, or even
-	# to another row in the same table, you can use a DomainObjectField to express the
-	# relation.
-	#   <lafcadio_class_definition name="Message">
-	#     <field name="subject" class="StringField" />
-	#     <field name="body" class="StringField" />
-	#     <field name="author" class="DomainObjectField" linked_type="User" />
-	#     <field name="recipient" class="DomainObjectField" linked_type="User" />
-	#     <field name="dateSent" class="DateField" />
-	#   </lafcadio_class_definition>
- 	#
- 	#   msg = Message.new( 'subject' => 'hi there',
- 	#                      'body' => 'You wanna go to the movies on Saturday?',
- 	#                      'author' => john, 'recipient' => jane,
- 	#                      'dateSent' => Date.today )
+	# to another row in the same table, you can use a DomainObjectField to 
+	# express the relation.
+	#
+	#   class Message < Lafcadio::DomainObject
+	#     strings       'subject', 'body'
+	#     domain_object User, 'author'
+	#     domain_object User, 'recipient'
+	#     date          'date_sent'
+	#   end
+	#
+ 	#   msg = Message.new(
+	#     :subject => 'hi there',
+	#     :body => 'You wanna go to the movies on Saturday?',
+ 	#     :author => john, :recipient => jane, :dateSent => Date.today
+	#   )
 	#
 	# = pk_id and committing
-	# Lafcadio requires that each table has a numeric primary key. It assumes that
-	# this key is named +pk_id+ in the database, though that can be overridden.
+	# Lafcadio requires that each table has a numeric primary key. It assumes
+	# that this key is named +pk_id+ in the database, though that can be
+	# overridden.
 	#
-	# When you create a domain object by calling new, you should not assign a
-	# +pk_id+ to the new instance. The pk_id will automatically be set when you
-	# commit the object by calling DomainObject#commit.
+	# When you create a domain object by calling DomainObject.new, you should not
+	# assign a +pk_id+ to the new instance. The pk_id will automatically be set
+	# when you commit the object by calling DomainObject#commit.
 	#
-	# However, you may want to manually set +pk_id+ when setting up a test case, so
-	# you can ensure that a domain object has a given primary key.
+	# However, you may want to manually set +pk_id+ when setting up a test case, 
+	# so you can ensure that a domain object has a given primary key.
 	#
 	# = Naming assumptions, and how to override them
 	# By default, Lafcadio assumes that every domain object is indexed by the
 	# field +pk_id+ in the database schema. If you're dealing with a table that 
-	# uses a different field name, override DomainObject.sql_primary_key_name.
+	# uses a different field name, call DomainObject.sql_primary_key_name.
 	# However, you will always use +pk_id+ in your Ruby code.
 	#
-	# Lafcadio assumes that a domain class corresponds to a table whose name is 
-	# the plural of the class name, and whose first letter is lowercase. A User 
-	# class is assumed to be stored in a "users" table, while a ProductCategory 
-	# class is assumed to be stored in a "productCategories" table. Override
+	# Lafcadio assumes that a domain class corresponds to a table whose name is
+	# the pluralized, lower-case, underscored version of the class name. A User
+	# class is assumed to be stored in a "users" table, while a ProductCategory
+	# class is assumed to be stored in a "product_categories" table. Call
 	# DomainObject.table_name to override this behavior.
 	#
+	#   class LegacyThing < Lafcadio::DomainObject
+	#     string 'some_field'
+	#     sql_primary_key_name 'some_legacy_id'
+	#     table_name 'some_legacy_table'
+	#   end
+	#   thing = LegacyThing[9909]
+	#   thing.pk_id # => 9909
+	#
 	# = Inheritance
 	# Domain classes can inherit from other domain classes; they have all the 
 	# fields of any concrete superclasses plus any new fields defined for 
 	# themselves. You can use normal inheritance to define this:
-	#   class User < DomainObject
+	#   class User < Lafcadio::DomainObject
 	#     ...
 	#   end
 	#
@@ -248,28 +291,32 @@ module Lafcadio
 
 		include DomainComparable
 		
+		# Shortcut method for retrieving one domain object.
+		#
+		#   User[7356] # => user with the pk_id 7536
 		def self.[]( pk_id ); get( pk_id ); end
 		
+		def self.abstract_subclass?( a_class ) #:nodoc:
+			abstract_subclasses.include? a_class
+		end
+		
 		def self.abstract_subclasses #:nodoc:
 			[ MapObject ]
 		end
 		
-		def self.all; ObjectStore.get_object_store.get_all( self ); end
+		# Returns every committed instance of the domain class.
+		#
+		#   User.all # => all users
+		def self.all; ObjectStore.get_object_store.all( self ); end
 		
-		# Returns an array of all fields defined for this class and all concrete
-		# superclasses.
-		def self.all_fields
+		def self.all_fields # :nodoc:
 			self_and_concrete_superclasses.map { |a_class|
 				a_class.class_fields
 			}.flatten
 		end
 
 		def self.class_field(fieldName) #:nodoc:
-			field = nil
-			self.class_fields.each { |aField|
-				field = aField if aField.name == fieldName
-			}
-			field
+			self.class_fields.find { |field| field.name == fieldName }
 		end
 		
 		def self.class_fields #:nodoc:
@@ -286,11 +333,11 @@ module Lafcadio
 			subclass_record.fields
 		end
 
-		def self.create_field( field_class, *args )
+		def self.create_field( field_class, *args ) #:nodoc:
 			subclass_record.maybe_init_fields
 			att_hash = create_field_att_hash( field_class, *args )
 			field = field_class.create_with_args( self, att_hash )
-			unless class_fields.any? { |cf| cf.name == field.name }
+			unless class_field( field.name )
 				att_hash.each { |field_name, value|
 					setter = field_name + '='
 					field.send( setter, value ) if field.respond_to?( setter )
@@ -302,20 +349,46 @@ module Lafcadio
 		def self.create_field_att_hash( field_class, *args ) #:nodoc:
 			att_hash = args.last
 			unless att_hash.is_a? Hash
-				att_hash = subclass_record.default_field_setup_hash[
-					field_class
-				].clone
+				att_hash = subclass_record.default_field_setup_hash[field_class].clone
 			end
 			if field_class == DomainObjectField
 				att_hash['linked_type'] = args.first
 				att_hash['name'] = args[1] if args[1] and !args[1].is_a? Hash
 			else
-				name = args.first
-				att_hash['name'] = name.is_a?( String ) ? name : name.to_s
+				att_hash['name'] = args.first.to_s
 			end
 			att_hash
 		end
+
+		def self.create_fields( field_class, *args ) #:nodoc:
+			arg = args.shift
+			until args.empty?
+				next_arg = args.shift
+				if next_arg.is_a? String or next_arg.is_a? Symbol
+					create_field( field_class, arg )
+					arg = next_arg
+				else
+					create_field( field_class, arg, next_arg )
+					arg = args.shift
+				end
+			end
+			create_field( field_class, arg ) unless arg.nil?
+		end
 		
+		# Sets a default setup hash for a field of a certain class. Useful for
+		# mapping domain classes with lots of fields and unusual field 
+		# configurations.
+		#
+		#   class LotsOfBooleans < Lafcadio::DomainObject
+		#     default_field_setup_hash(
+		#       Lafcadio::BooleanField,
+		#       {
+		#         'enum_type' => Lafcadio::BooleanField::ENUMS_CAPITAL_YES_NO
+		#       }
+		#     )
+		#     booleans 'this', 'that', 'the_other', 'and_another_one',
+		#              'this_one_too'
+		#   end
 		def self.default_field_setup_hash( field_class, hash )
 			subclass_record.default_field_setup_hash[field_class] = hash
 		end
@@ -323,47 +396,101 @@ module Lafcadio
 		def self.dependent_classes #:nodoc:
 			dependent_classes = {}
 			DomainObject.subclasses.each { |aClass|
-				unless DomainObject.abstract_subclasses.include?( aClass )
-					if ( field = aClass.get_link_field( self ) )
-						dependent_classes[aClass] = field
-					end
+				if (
+					!abstract_subclass?( aClass ) and
+					( field = aClass.link_field( self ) )
+				)
+					dependent_classes[aClass] = field
 				end
 			}
 			dependent_classes
 		end
 		
+		def self.domain_class #:nodoc:
+			self
+		end
+
+		def self.domain_dirs #:nodoc:
+			if ( domainDirStr = LafcadioConfig.new['domainDirs'] )
+				domainDirStr.split(',')
+			else
+				[]
+			end
+		end
+		
+		# Tests whether a given domain object exists.
+		#
+		#   User.exist?( 8280 ) # => returns true iff there's a User 8280
+		#   User.exist?( 'Hwang', :lastName ) # => returns true iff there's a User
+		#                                     #    with the last name 'Hwang'
 		def self.exist?( search_term, field_name = :pk_id )
 			query = Query.infer( self ) { |dobj|
 				dobj.send( field_name ).equals( search_term )
 			}
-			!ObjectStore.get_object_store.get_subset( query ).empty?
+			!ObjectStore.get_object_store.query( query ).empty?
 		end
 		
+		def self.field( fieldName ) #:nodoc:
+			aDomainClass = self
+			field = nil
+			while aDomainClass < DomainObject && !field
+				field = aDomainClass.class_field( fieldName )
+				aDomainClass = aDomainClass.superclass
+			end
+			field
+		end
+
+		# Returns the first domain object it can find.
+		#
+		#   very_first_user = User.first
 		def self.first; all.first; end
-			
+		
+		# This class method has a few uses, depending on how you use it.
+		# 1. Pass DomainObject.get a block in order to run a complex query:
+		#      adult_hwangs = User.get { |user|
+		#        user.lastName.equals( 'Hwang' ) &
+		#          user.birthday.lte( Date.today - ( 365 * 18 ) )
+		#      }
+		#    See query.rb for more information about how to form these
+		#    queries.
+		# 2. Pass it a simple search term and a field name to retrieve every domain
+		#    object matching the term. The field name will default to +pk_id+.
+		#      hwangs = User.get( 'Hwang', :lastName )
+		#      user123 = User.get( 123 ).first
+		# 3. Pass it a { :group => :count } hash to retrieve a count result hash.
+		#    This interface is fairly new and may be refined (that is, changed) in
+		#    the future.
+		#      num_users = User.get( :group => :count ).first[:count]
 		def self.get( *args )
 			if block_given?
 				query = Query.infer( self ) { |dobj| yield( dobj ) }
-				ObjectStore.get_object_store.get_subset( query )
+				ObjectStore.get_object_store.query( query )
 			elsif args.size == 1
 				arg = args.first
 				if arg.is_a? Fixnum
 					ObjectStore.get_object_store.get( self, *args )
 				else
 					qry = Query.new( self, nil, { :group_functions => [ :count ] } )
-					ObjectStore.get_object_store.query qry
+					ObjectStore.get_object_store.group_query qry
 				end
 			else
-				ObjectStore.get_object_store.get_filtered( self.name, *args )
+				search_term = args.shift
+				field_name = (
+					args.shift or link_field( search_term.domain_class ).name
+				)
+				qry = Query::Equals.new( field_name, search_term, self )
+				ObjectStore.get_object_store.query qry
 			end
 		end
 
 		# Returns an Array of ObjectField instances for this domain class, parsing
-		# them from XML if necessary.
+		# them from XML if necessary. You can override this to define a domain
+		# class' fields, though it will probably just be simpler to use one-line 
+		# class methods instead. 
 		def self.get_class_fields
 			if self.methods( false ).include?( 'get_class_fields' )
 				[ subclass_record.pk_field ]
-			elsif abstract_subclasses.include?( self )
+			elsif abstract_subclass?( self )
 				[]
 			else
 				xmlParser = try_load_xml_parser
@@ -377,107 +504,64 @@ module Lafcadio
 			end
 		end
 
-		def self.get_domain_dirs #:nodoc:
-			if ( domainDirStr = LafcadioConfig.new['domainDirs'] )
-				domainDirStr.split(',')
-			else
-				[]
-			end
-		end
-		
-		def self.get_field( fieldName ) #:nodoc:
-			aDomainClass = self
-			field = nil
-			while aDomainClass < DomainObject && !field
-				field = aDomainClass.class_field( fieldName )
-				aDomainClass = aDomainClass.superclass
-			end
-			if field
-				field
-			else
-				errStr = "Couldn't find field \"#{ fieldName }\" in " +
-								 "#{ self } domain class"
-				raise( MissingError, errStr, caller )
-			end
+		def self.is_child_domain_class? #:nodoc:
+			superclass != DomainObject and !abstract_subclass?( superclass )
 		end
 
-		def self.get_domain_class_from_string(typeString) #:nodoc:
-			domain_class = nil
-			require_domain_file( typeString )
-			subclasses.each { |subclass|
-				domain_class = subclass if subclass.to_s == typeString
-			}
-			if domain_class
-				domain_class
-			else
-				raise CouldntMatchDomainClassError,
-						"couldn't match domain_class #{typeString}", caller
-			end
-		end
+		# Returns the last domain object.
+		#
+		#   last_msg = Message.last
+		def self.last; all.last; end
 		
-		def self.get_link_field( linked_domain_class ) # :nodoc:
+		def self.link_field( linked_domain_class ) # :nodoc:
 			class_fields.find { |field|
-				field.is_a? DomainObjectField and field.linked_type == linked_domain_class
+				field.is_a? DomainObjectField and
+				field.linked_type == linked_domain_class
 			}
 		end
 		
-		def self.inherited(subclass) #:nodoc:
-			@@subclass_records[subclass]
-		end
-		
-		def self.is_based_on? #:nodoc:
-		  self.superclass.is_concrete?
-		end
-
-		def self.is_concrete? #:nodoc:
-		  (self != DomainObject && abstract_subclasses.index(self).nil?)
-		end
-		
-		def self.last; all.last; end
-		
 		def self.method_missing( methodId, *args ) #:nodoc:
+			dispatched = false
 			method_name = methodId.id2name
-			maybe_field_class_name = method_name.underscore_to_camel_case + 'Field'
 			begin
-				field_class = Lafcadio.const_get( maybe_field_class_name )
-				create_field( field_class, *args )
+				method_missing_try_create_field( method_name, *args )
+				dispatched = true
 			rescue NameError
-				singular = method_name.singular
-				if singular
-					maybe_field_class_name = singular.underscore_to_camel_case + 'Field'
-					begin
-						field_class = Lafcadio.const_get( maybe_field_class_name )
-						arg = args.shift
-						until args.empty?
-							next_arg = args.shift
-							if next_arg.is_a? String or next_arg.is_a? Symbol
-								create_field( field_class, arg )
-								arg = next_arg
-							else
-								create_field( field_class, arg, next_arg )
-								arg = args.shift
-							end
-						end
-						create_field( field_class, arg ) unless arg.nil?
-					rescue NameError
-						super
-					end
-				else
-					super
-				end
+				begin
+					method_missing_try_create_fields( method_name, *args )
+					dispatched = true
+				rescue NameError; end
 			end
+			super unless dispatched
 		end
 		
-		def self.only; all.only; end
-
-		def self.domain_class #:nodoc:
-			self
+		def self.method_missing_try_create_field( method_name, *args ) # :nodoc:
+			maybe_field_class_name = method_name.underscore_to_camel_case + 'Field'
+			field_class = Lafcadio.const_get( maybe_field_class_name )
+			create_field( field_class, *args )
+		end
+		
+		def self.method_missing_try_create_fields( method_name, *args ) # :nodoc:
+			singular = method_name.singular
+			if singular
+				maybe_field_class_name = singular.underscore_to_camel_case + 'Field'
+				field_class = Lafcadio.const_get( maybe_field_class_name )
+				create_fields( field_class, *args )
+			else
+				raise NameError
+			end
 		end
 
-		def self.require_domain_file( typeString )
+		# Returns the only committed instance of the domain class. Will raise an
+		# IndexError if there are 0, or more than 1, domain objects.
+		#
+		#   the_one_user = User.only
+		def self.only; all.only; end
+
+		def self.require_domain_file( typeString ) # :nodoc:
 			typeString =~ /([^\:]*)$/
 			fileName = $1
-			get_domain_dirs.each { |domainDir|
+			domain_dirs.each { |domainDir|
 				if Dir.entries(domainDir).index("#{fileName}.rb")
 					require "#{ domainDir }#{ fileName }"
 				end
@@ -491,43 +575,66 @@ module Lafcadio
 		def self.self_and_concrete_superclasses # :nodoc:
 			classes = [ ]
 			a_domain_class = self
-			until( a_domain_class == DomainObject ||
-					   abstract_subclasses.index( a_domain_class ) != nil )
+			until(
+				a_domain_class == DomainObject || abstract_subclass?( a_domain_class )
+			)
 				classes << a_domain_class
 				a_domain_class = a_domain_class.superclass
 			end
 			classes
 		end
 
-		def self.singleton_method_added( symbol )
+		def self.singleton_method_added( symbol ) # :nodoc:
 			if symbol.id2name == 'sql_primary_key_name' && self < DomainObject
 				begin
-					get_field( 'pk_id' ).db_field_name = self.send( symbol )
+					field( 'pk_id' ).db_field_name = self.send( symbol )
 				rescue NameError
 					subclass_record.sql_primary_key = self.send( symbol )
 				end
 			end
 		end
 		
-		# Returns the name of the primary key in the database, retrieving it from
-		# the class definition XML if necessary.
-		def self.sql_primary_key_name( set_sql_primary_key_name = nil )
-			if set_sql_primary_key_name
-				get_field( 'pk_id' ).db_field_name = set_sql_primary_key_name
-			end
-			get_field( 'pk_id' ).db_field_name
+		# If +set_db_field_name+ is nil, this will return the sql name of the
+		# primary key. If +set_db_field_name+ isn't nil, it will set the sql name.
+		#
+		#   class User < Lafcadio::DomainObject
+		#     string 'firstNames'
+		#   end
+		#   User.sql_primary_key_name # => 'pk_id'
+		#   class User < Lafcadio::DomainObject
+		#     sql_primary_key_name 'some_other_id'
+		#   end
+		#   User.sql_primary_key_name # => 'some_other_id'
+		def self.sql_primary_key_name( set_db_field_name = nil )
+			field( 'pk_id' ).db_field_name = set_db_field_name if set_db_field_name
+			field( 'pk_id' ).db_field_name
 		end
 		
-		def self.subclass_record; @@subclass_records[self]; end
+		def self.subclass_record # :nodoc:
+			@@subclass_records[self]
+		end
 
 		def self.subclasses #:nodoc:
 			@@subclass_records.keys
 		end
 
-		# Returns the table name, which is assumed to be the domain class name 
-		# pluralized, and with the first letter lowercase. A User class is
-		# assumed to be stored in a "users" table, while a ProductCategory class is
-		# assumed to be stored in a "productCategories" table.
+		# If +set_table_name+ is nil, DomainObject.table_name will return the table
+		# name. Lafcadio assumes that a domain class corresponds to a table whose
+		# name is the pluralized, lower-case, underscored version of the class
+		# name. A User class is assumed to be stored in a "users" table, while a
+		# ProductCategory class is assumed to be stored in a "product_categories"
+		# table.
+		#
+		# If +set_table_name+ is not nil, this will set the table name.
+		#
+		#   class User < Lafcadio::DomainObject
+		#     string 'firstNames'
+		#   end
+		#   User.table_name # => 'users'
+		#   class User < Lafcadio::DomainObject
+		#     table_name 'some_table'
+		#   end
+		#   User.table_name # => 'some_table'
 		def self.table_name( set_table_name = nil )
 			if set_table_name
 				@table_name = set_table_name
@@ -543,30 +650,31 @@ module Lafcadio
 			end
 		end
 
-		def self.try_load_xml_parser
+		def self.try_load_xml_parser # :nodoc:
 			require 'lafcadio/domain'
 			dirName = LafcadioConfig.new['classDefinitionDir']
 			xmlFileName = self.basename + '.xml'
 			xmlPath = File.join( dirName, xmlFileName )
-			xml = ''
 			begin
-				File.open( xmlPath ) { |file| xml = file.readlines.join }
+				xml = File.open( xmlPath ) do |f| f.gets( nil ); end
 				ClassDefinitionXmlParser.new( self, xml )
 			rescue Errno::ENOENT
 				# no xml file, so no @xmlParser
 			end
 		end
 		
-		attr_accessor :error_messages, :last_commit, :fields, :fields_set
+		attr_accessor :fields_set, :field_values, :last_commit_type
 		attr_reader :delete
-		protected :fields, :fields_set
+		protected :fields_set, :field_values
 
-		# fieldHash should contain key-value associations for the different
+		# +field_hash+ should contain key-value associations for the different
 		# fields of this domain class. For example, instantiating a User class 
 		# might look like:
 		#
-		#   User.new( 'firstNames' => 'John', 'lastName' => 'Doe',
-		#             'email' => 'john.doe@email.com', 'password' => 'l33t' )
+		#   User.new(
+		#     'firstNames' => 'John', 'lastName' => 'Doe',
+		#     'email' => 'john.doe@email.com', 'password' => 'l33t'
+		#   )
 		#
 		# In normal usage any code you write that creates a domain object will not
 		# define the +pk_id+ field. The system assumes that a domain object with an
@@ -575,27 +683,11 @@ module Lafcadio
 		#
 		# If you're creating mock objects for unit tests, you can explicitly set 
 		# the +pk_id+ to represent objects that already exist in the database.
-		def initialize(fieldHash)
-			if fieldHash.respond_to? :keys
-				fieldHash.keys.each { |key|
-					key = key.to_s
-					begin
-						self.class.get_field( key )
-					rescue MissingError
-						raise ArgumentError, "Invalid field name #{ key }"
-					end
-				}
-			end
-			if fieldHash.is_a? Hash
-				@fieldHash = {}
-				fieldHash.each do |k, v| @fieldHash[k.to_s] = v; end
-			else
-				@fieldHash = fieldHash
-			end
-			@error_messages = []
-			@fields = {}
+		def initialize( field_hash )
+			field_hash = preprocess_field_hash field_hash
+			@field_values = {}
 			@fields_set = []
-			@original_values = OriginalValuesHash.new( @fieldHash )
+			reset_original_values_hash @fieldHash
 			check_fields = LafcadioConfig.new()['checkFields']
 			verify if %w( onInstantiate onAllStates ).include?( check_fields )
 		end
@@ -603,7 +695,7 @@ module Lafcadio
 		# Returns a clone, with all of the fields copied.
 		def clone
 			copy = super
-			copy.fields = @fields.clone
+			copy.field_values = @field_values.clone
 			copy.fields_set = @fields_set.clone
 			copy
 		end
@@ -622,106 +714,125 @@ module Lafcadio
 			@delete = value
 		end
 		
+		# Deletes a domain object, committing the delete to the database
+		# immediately.
 		def delete!
 			self.delete = true
 			commit
 		end
 
-		def get_field( field ) #:nodoc:
+		# Returns the subclass of DomainObject that this instance represents.
+		# Because of the way that proxying works, clients should call this method
+		# instead of Object.class.
+		def domain_class
+			self.class.domain_class
+		end
+
+		def field_value( field ) #:nodoc:
 			unless @fields_set.include?( field )
-				set_field( field, @fieldHash[field.name] )
+				set_field_value( field, @fieldHash[field.name] )
 			end
-			@fields[field.name]
+			@field_values[field.name]
 		end
 		
-		def get_getter_field( methId ) #:nodoc:
-			begin
-				self.class.get_field( methId.id2name )
-			rescue MissingError
-				nil
-			end
+		def getter_field( methId ) #:nodoc:
+			self.class.field methId.id2name
 		end
 
-		def get_setter_field( methId ) #:nodoc:
-			if methId.id2name =~ /(.*)=$/
-				begin
-					self.class.get_field( $1 )
-				rescue MissingError
-					nil
-				end
-			else
-				nil
-			end
-		end
-		
 		def method_missing( methId, *args ) #:nodoc:
-			if ( field = get_setter_field( methId ) )
-				set_field( field, args.first )
-			elsif ( field = get_getter_field( methId ) )
-				get_field( field )
+			if ( field = setter_field( methId ) )
+				set_field_value( field, args.first )
+			elsif ( field = getter_field( methId ) )
+				field_value( field )
 			else
-				new_symbol = ( 'get_' + methId.id2name ).to_sym
 				object_store = ObjectStore.get_object_store
-				if object_store.respond_to? new_symbol
+				if object_store.respond_to? methId
 					args = [ self ].concat args
-					object_store.send( 'get_' + methId.id2name, *args )
+					object_store.send( methId, *args )
 				else
 					super( methId, *args )
 				end
 			end
 		end
 
-		# Returns the subclass of DomainObject that this instance represents.
-		# Because of the way that proxying works, clients should call this method
-		# instead of Object.class.
-		def domain_class
-			self.class.domain_class
-		end
-
 		# This template method is called before every commit. Subclasses can 
 		# override it to ensure code is executed before a commit.
 		def pre_commit_trigger
 			nil
 		end
 
+		def preprocess_field_hash( fieldHash ) # :nodoc:
+			if fieldHash.is_a? Hash
+				fieldHash.keys.each { |key|
+					if self.class.field( key.to_s ).nil?
+						raise ArgumentError, "Invalid field name #{ key.to_s }"
+					end
+				}
+				@fieldHash = {}
+				fieldHash.each do |k, v| @fieldHash[k.to_s] = v; end
+			else
+				@fieldHash = fieldHash
+			end
+		end
+		
 		# This template method is called after every commit. Subclasses can 
 		# override it to ensure code is executed after a commit.
 		def post_commit_trigger
 			nil
 		end
 
-		def set_field( field, value ) #:nodoc:
-			if field.class <= DomainObjectField
-				if value.class != DomainObjectProxy && value
-					value = DomainObjectProxy.new(value)
-				end
+		def reset_original_values_hash( f = @field_values ) #:nodoc:
+			@original_values = ReadOnlyHash.new( f.clone )
+		end
+
+		def set_field_value( field, value ) #:nodoc:
+			if (
+				field.is_a?( DomainObjectField ) and
+				!value.is_a?( DomainObjectProxy ) and value
+			)
+				value = DomainObjectProxy.new(value)
 			end
 			if ( LafcadioConfig.new()['checkFields'] == 'onAllStates' &&
 			     !field.instance_of?( PrimaryKeyField ) )
 				field.verify( value, pk_id )
 			end
-			@fields[field.name] = value
+			@field_values[field.name] = value
 			@fields_set << field
 		end
 		
+		def setter_field( methId ) #:nodoc:
+			if methId.id2name =~ /(.*)=$/
+				self.class.field $1
+			else
+				nil
+			end
+		end
+		
+		# Updates a domain object and commits the changes to the database 
+		# immediately.
+		#
+		#   user99 = User[99]
+		#   user99.update!( :firstNames => 'Bill', :password => 'n3wp4ssw0rd' )
 		def update!( changes )
 			changes.each do |sym, value| self.send( sym.to_s + '=', value ); end
 			commit
 		end
 		
+		# If you're running against a MockObjectStore, this will verify each field
+		# and raise an error if there's any invalid fields.
 		def verify
-			if ObjectStore.get_object_store.mock?
+			if ObjectStore.mock?
 				self.class.get_class_fields.each { |field|
 					field.verify( self.send( field.name ), self.pk_id )
 				}
 			end
 		end
 		
-		class OriginalValuesHash < DelegateClass( Hash )
+		class ReadOnlyHash < DelegateClass( Hash ) # :nodoc:
 			def []=( key, val ); raise NoMethodError; end
 		end
 		
-		class SubclassRecord
+		class SubclassRecord # :nodoc:
 			attr_accessor :default_field_setup_hash, :fields, :sql_primary_key
 			
 			def initialize( subclass )
@@ -746,16 +857,13 @@ module Lafcadio
 
 	# Any domain class that is used mostly to map between two other domain 
 	# classes should be a subclass of MapObject. Subclasses of MapObject should 
-	# override MapObject.mappedTypes, returning a two-element array containing 
+	# override MapObject.mapped_classes, returning a two-element array containing 
 	# the domain classes that the map object maps between.
 	class MapObject < DomainObject
 		def self.other_mapped_type(firstType) #:nodoc:
-			types = mappedTypes
-			if types.index(firstType) == 0
-				types[1]
-			else
-				types[0]
-			end
+			mt = mapped_classes.clone
+			mt.delete firstType
+			mt.only
 		end
 
 		def self.subsidiary_map #:nodoc: