treequel 1.2.2 → 1.3.0pre384

data/lib/treequel/exceptions.rb

@@ -26,6 +26,24 @@ module Treequel
 	### other problem.
 	class ModelError < Treequel::Error; end
 
+	### Exception class raised when +raise_on_save_failure+ is set and validation fails
+	class ValidationFailed < Treequel::ModelError
+
+		### Create a new Treequel::ValidationFailed exception with the given +errors+.
+		### @param [Treequel::Model::Errors, String] errors  the validaton errors
+		def initialize( errors )
+			if errors.respond_to?( :full_messages )
+				@errors = errors
+				super( errors.full_messages.join(', ') )
+			else
+				super
+			end
+		end
+
+		# @return [Treequel::Model::Errors] the validation errors
+		attr_reader :errors
+	end
+
 end # module Treequel
 
 

data/lib/treequel/mixins.rb

@@ -153,14 +153,6 @@ module Treequel
 	### Add logging to a Treequel class. Including classes get #log and #log_debug methods.
 	module Loggable
 
-		LEVEL = {
-			:debug => Logger::DEBUG,
-			:info  => Logger::INFO,
-			:warn  => Logger::WARN,
-			:error => Logger::ERROR,
-			:fatal => Logger::FATAL,
-		  }
-
 		### A logging proxy class that wraps calls to the logger into calls that include
 		### the name of the calling class.
 		### @private
@@ -172,13 +164,34 @@ module Treequel
 				@force_debug = force_debug
 			end
 
-			### Delegate calls the global logger with the class name as the 'progname' 
-			### argument.
-			def method_missing( sym, msg=nil, &block )
-				return super unless LEVEL.key?( sym )
-				sym = :debug if @force_debug
-				Treequel.logger.add( LEVEL[sym], msg, @classname, &block )
+			### Delegate debug messages to the global logger with the appropriate class name.
+			def debug( msg=nil, &block )
+				Treequel.logger.add( Logger::DEBUG, msg, @classname, &block )
+			end
+
+			### Delegate info messages to the global logger with the appropriate class name.
+			def info( msg=nil, &block )
+				return self.debug( msg, &block ) if @force_debug
+				Treequel.logger.add( Logger::INFO, msg, @classname, &block )
+			end
+
+			### Delegate warn messages to the global logger with the appropriate class name.
+			def warn( msg=nil, &block )
+				return self.debug( msg, &block ) if @force_debug
+				Treequel.logger.add( Logger::WARN, msg, @classname, &block )
+			end
+
+			### Delegate error messages to the global logger with the appropriate class name.
+			def error( msg=nil, &block )
+				return self.debug( msg, &block ) if @force_debug
+				Treequel.logger.add( Logger::ERROR, msg, @classname, &block )
+			end
+
+			### Delegate fatal messages to the global logger with the appropriate class name.
+			def fatal( msg=nil, &block )
+				Treequel.logger.add( Logger::FATAL, msg, @classname, &block )
 			end
+
 		end # ClassNameProxy
 
 		#########
@@ -200,6 +213,7 @@ module Treequel
 		def log_debug
 			@log_debug_proxy ||= ClassNameProxy.new( self.class, true )
 		end
+
 	end # module Loggable
 
 
@@ -271,6 +285,22 @@ module Treequel
 			end
 		end
 
+		### Normalize the attributes in +hash+ to be of the form expected by the
+		### LDAP library (i.e., keys as Strings, values as Arrays of Strings)
+		def normalize_attributes( hash )
+			normhash = {}
+			hash.each do |key,val|
+				val = [ val ] unless val.is_a?( Array )
+				val.collect! {|obj| obj.to_s }
+
+				normhash[ key.to_s ] = val
+			end
+
+			normhash.delete( 'dn' )
+
+			return normhash
+		end
+
 	end # HashUtilities
 
 

data/lib/treequel/model.rb

@@ -10,12 +10,15 @@ require 'treequel/branchset'
 
 # An object interface to LDAP entries.
 class Treequel::Model < Treequel::Branch
+	require 'treequel/model/objectclass'
+	require 'treequel/model/errors'
+	require 'treequel/model/schemavalidations'
+
 	include Treequel::Loggable,
 	        Treequel::Constants,
 	        Treequel::Normalization,
-	        Treequel::Constants::Patterns
-
-	require 'treequel/model/objectclass'
+	        Treequel::Constants::Patterns,
+	        Treequel::Model::SchemaValidations
 
 
 	# A prototype Hash that autovivifies its members as Sets, for use in
@@ -23,6 +26,34 @@ class Treequel::Model < Treequel::Branch
 	SET_HASH = Hash.new {|h,k| h[k] = Set.new }
 
 
+	# The hooks that are called before an action
+	BEFORE_HOOKS = [
+		:before_create,
+		:before_update,
+		:before_save,
+		:before_destroy,
+		:before_validation,
+	  ]
+
+	# The hooks that are called after an action
+	AFTER_HOOKS = [
+		:after_initialize,
+		:after_create,
+		:after_update,
+		:after_save,
+		:after_destroy,
+		:after_validation,
+	  ]
+
+	# Hooks the user can override
+	HOOKS = BEFORE_HOOKS + AFTER_HOOKS
+
+	# Defaults for #validate options
+	DEFAULT_VALIDATION_OPTIONS = {
+		:with_schema => true,
+	}
+
+
 	#################################################################
 	###	C L A S S   M E T H O D S
 	#################################################################
@@ -131,6 +162,25 @@ class Treequel::Model < Treequel::Branch
 	end
 
 
+	### Never freeze converted values in Model objects.
+	def self::freeze_converted_values?; false; end
+
+
+	### Create a new Treequel::Model object with the given +entry+ hash from the 
+	### specified +directory+. Overrides Treequel::Branch.new_from_entry to pass the
+	### +from_directory+ flag to mark it as unmodified.
+	### 
+	### @see Treequel::Branch.new_from_entry
+	def self::new_from_entry( entry, directory )
+		entry = Treequel::HashUtilities.stringify_keys( entry )
+		dnvals = entry.delete( 'dn' ) or
+			raise ArgumentError, "no 'dn' attribute for entry"
+
+		Treequel.logger.debug "Creating %p from entry: %p in directory: %s" %
+			[ self, dnvals.first, directory ]
+		return self.new( directory, dnvals.first, entry, true )
+	end
+
 
 	#################################################################
 	###	I N S T A N C E   M E T H O D S
@@ -138,9 +188,25 @@ class Treequel::Model < Treequel::Branch
 
 	### Override the default to extend new instances with applicable mixins if their
 	### entry is set.
-	def initialize( *args )
+	def initialize( directory, dn, entry=nil, from_directory=false )
+		if from_directory
+			super( directory, dn, entry )
+		else
+			super( directory, dn )
+			@values = entry ? symbolify_keys( entry ) : {}
+			@dirty  = true
+		end
+
+		self.apply_applicable_mixins( @dn, @entry )
+		self.after_initialize
+	end
+
+
+	### Copy initializer -- re-apply mixins to duplicates, too.
+	def initialize_copy( other )
 		super
-		self.apply_applicable_mixins( @dn, @entry ) if @entry
+		self.apply_applicable_mixins( @dn, @entry )
+		self.after_initialize
 	end
 
 
@@ -148,6 +214,229 @@ class Treequel::Model < Treequel::Branch
 	public
 	######
 
+	### Set up the empty hook methods
+	HOOKS.each do |hook|
+		define_method( hook ) do |*args|
+			self.log.debug "#{hook} default hook called."
+		end
+	end
+
+
+	### Tests whether the object has been modified since it was loaded from
+	### the directory.
+	def modified?
+		return @dirty ? true : false
+	end
+
+
+	### Mark the object as unmodified.
+	def reset_dirty_flag
+		@dirty = false
+	end
+
+
+	### Index set operator -- set attribute +attrname+ to a new +value+.
+	### Overridden to make Model objects defer writing changes until 
+	### {Treequel::Model#save} is called.
+	### 
+	### @param [Symbol, String] attrname  attribute name
+	### @param [Object] value  the attribute value
+	def []=( attrname, value )
+		attrtype = self.find_attribute_type( attrname.to_sym ) or
+			raise ArgumentError, "unknown attribute %p" % [ attrname ]
+		value = Array( value ) unless attrtype.single?
+
+		self.mark_dirty
+		@values[ attrtype.name.to_sym ] = value
+
+		# If the objectClasses change, we (may) need to re-apply mixins
+		if attrname.to_s.downcase == 'objectclass'
+			self.log.debug "  objectClass change -- reapplying mixins"
+			self.apply_applicable_mixins( self.dn )
+		else
+			self.log.debug "  no objectClass changes -- no need to reapply mixins"
+		end
+
+		return value
+	end
+
+
+	### Make the changes to the object specified by the given +attributes+.
+	### Overridden to make Model objects defer writing changes until 
+	### {Treequel::Model#save} is called.
+	### 
+	### @param attributes (see Treequel::Directory#modify)
+	### @return [TrueClass] if the merge succeeded
+	def merge( attributes )
+		attributes.each do |attrname, value|
+			self[ attrname ] = value
+		end
+	end
+
+
+	### Delete the specified attributes.
+	### Overridden to make Model objects defer writing changes until 
+	### {Treequel::Model#save} is called.
+	### 
+	### @see Treequel::Branch#delete
+	def delete( *attributes )
+		return super if attributes.empty?
+
+		self.log.debug "Deleting attributes: %p" % [ attributes ]
+		self.mark_dirty
+
+		attributes.flatten.each do |attribute|
+
+			# With a hash, delete each value for each key
+			if attribute.is_a?( Hash )
+				self.delete_specific_values( attribute )
+
+			# With an array of attributes to delete, replace 
+			# MULTIPLE attribute types with an empty array, and SINGLE 
+			# attribute types with nil
+			elsif attribute.respond_to?( :to_sym )
+				attrtype = self.find_attribute_type( attribute.to_sym )
+				if attrtype.single?
+					@values[ attribute.to_sym ] = nil
+				else
+					@values[ attribute.to_sym ] = []
+				end
+			else
+				raise ArgumentError,
+					"can't convert a %p to a Symbol or a Hash" % [ attribute.class ]
+			end
+		end
+
+		return true
+	end
+
+
+	### Returns the validation errors associated with this object.
+	### @see Treequel::Model::Errors.
+	def errors
+		return @errors ||= Treequel::Model::Errors.new
+	end
+
+
+	### Return +true+ if the model object passes all of its validations.
+	def valid?( opts={} )
+		self.errors.clear
+
+		return false if self.before_validation == false
+		self.validate
+		self.after_validation
+
+		return self.errors.empty? ? true : false
+	end
+
+
+	### Validate the object with the specified +options+.
+	### @param [Hash] options  options for validation.
+	### @option options [Boolean] :with_schema  whether or not to run the schema validations
+	def validate( options={} )
+		options = DEFAULT_VALIDATION_OPTIONS.merge( options )
+
+		self.errors.add( :objectClass, 'must have at least one' ) if self.object_classes.empty?
+
+		super( options )
+	end
+
+
+	### Write any pending changes in the model object to the directory.
+	def save
+		self.log.debug "Saving %s..." % [ self.dn ]
+		raise Treequel::ValidationFailed, self.errors unless self.valid?
+		self.log.debug "  validation succeeded."
+
+		unless mods = self.modifications
+			self.log.debug "  no modifications... no save necessary."
+			return false
+		end
+
+		self.log.debug "  got %d modifications." % [ mods.length ]
+		self.before_save( mods ) or return nil
+
+		if self.exists?
+			self.log.debug "    entry already exists: updating..."
+			self.before_update( mods ) or return nil
+			self.modify( mods )
+			self.after_update( mods )
+
+		else
+			self.log.debug "    entry doesn't exist: creating..."
+			self.before_create( mods ) or return nil
+			self.create( mods )
+			self.after_create( mods )
+		end
+
+		self.after_save( mods )
+
+		return true
+	end
+
+
+	### Return any pending changes in the model object.
+	### @return [Array<LDAP::Mod>]  the changes as LDAP modifications
+	def modifications
+		return unless self.modified?
+		self.log.debug "Gathering modifications..."
+
+		mods = []
+		entry = self.entry || {}
+		self.log.debug "  directory entry is: %p" % [ entry ]
+
+		@values.sort_by {|k, _| k.to_s }.each do |attribute, vals|
+			vals = [ vals ] unless vals.is_a?( Array )
+			vals = vals.compact
+			vals.collect! {|val| self.get_converted_attribute(attribute, val) }
+			self.log.debug "  comparing %s values to entry: %p vs. %p" %
+				[ attribute, vals, entry[attribute.to_s] ]
+
+			entryvals = (entry[attribute.to_s] || [])
+			attrmods = { :add => [], :delete => [] }
+
+			Diff::LCS.sdiff( entryvals.sort, vals.sort ) do |change|
+				self.log.debug "    found a change: %p" % [ change ]
+				if change.adding?
+					attrmods[:add] << change.new_element
+				elsif change.changed?
+					attrmods[:add] << change.new_element
+					attrmods[:delete] << change.old_element
+				elsif change.deleting?
+					attrmods[:delete] << change.old_element
+				# else
+				# 	self.log.debug "      no mod necessary for %p" % [ change.action ]
+				end
+			end
+
+			mods << LDAP::Mod.new( LDAP::LDAP_MOD_DELETE, attribute.to_s, attrmods[:delete] ) unless
+				attrmods[:delete].empty?
+			mods << LDAP::Mod.new( LDAP::LDAP_MOD_ADD, attribute.to_s, attrmods[:add] ) unless
+				attrmods[:add].empty?
+		end
+
+		self.log.debug "  mods are: %p" % [ mods ]
+
+		return mods
+	end
+
+
+	### Return the pending modifications for the object as an LDIF string.
+	def modification_ldif
+		mods = self.modifications
+		return LDAP::LDIF.mods_to_ldif( self.dn, mods )
+	end
+
+
+	### Revert to the attributes in the directory, discarding any pending changes.
+	def revert
+		self.clear_caches
+		@dirty = false
+
+		return true
+	end
+
+
 	### Override Branch#search to inject the 'objectClass' attribute to the
 	### selected attribute list if there is one.
 	def search( scope=:subtree, filter='(objectClass=*)', parameters={}, &block )
@@ -197,6 +486,29 @@ class Treequel::Model < Treequel::Branch
 	protected
 	#########
 
+
+	### Mark the object as having been modified.
+	def mark_dirty
+		@dirty = true
+	end
+
+
+	### Delete specific key/value +pairs+ from the entry.
+	### @param [Hash] pairs  key/value pairs to delete from the entry.
+	def delete_specific_values( pairs )
+		self.log.debug "  hash-delete..."
+
+		# Ensure the value exists, and its values converted and cached, as
+		# the delete needs Ruby object instead of string comparison
+		pairs.each do |key, vals|
+			next unless self[ key ]
+			self.log.debug "    deleting %p: %p" % [ key, vals ]
+
+			@values[ key ].delete_if {|val| vals.include?(val) }
+		end
+	end
+
+
 	### Search for the Treequel::Schema::AttributeType associated with +sym+.
 	### 
 	### @param [Symbol,String] name  the name of the attribute to find
@@ -205,7 +517,7 @@ class Treequel::Model < Treequel::Branch
 	def find_attribute_type( name )
 		attrtype = nil
 
-		# If the attribute doesn't match as-is, try the camelCased version of it
+		# Try both the name as-is, and the camelCased version of it
 		camelcased_sym = name.to_s.gsub( /_(\w)/ ) { $1.upcase }.to_sym
 		attrtype = self.valid_attribute_type( name ) ||
 		           self.valid_attribute_type( camelcased_sym )
@@ -268,13 +580,13 @@ class Treequel::Model < Treequel::Branch
 	def make_reader( attrtype )
 		self.log.debug "Generating an attribute reader for %p" % [ attrtype ]
 		attrname = attrtype.name
-		return lambda {|*args|
+		return lambda do |*args|
 			if args.empty?
 				self[ attrname ]
 			else
 				self.traverse_branch( attrname, *args )
 			end
-		}
+		end
 	end
 
 
@@ -329,30 +641,35 @@ class Treequel::Model < Treequel::Branch
 
 
 	### Apply mixins that are applicable considering the receiver's DN and the 
-	### objectClasses from its entry.
-	def apply_applicable_mixins( dn, entry )
-		self.log.debug "Applying mixins applicable to %s" % [ dn ]
+	### objectClasses from the given entry merged with any unsaved values.
+	def apply_applicable_mixins( dn, entry=nil )
+		entry ||= {}
+		entry.merge!( stringify_keys(@values) )
+		return unless entry['objectClass']
+
+		# self.log.debug "Applying mixins applicable to %s" % [ dn ]
 		schema = self.directory.schema
 
+		# self.log.debug "  entry is: %p" % [ entry ]
 		ocs = entry['objectClass'].collect do |oc_oid|
 			explicit_oc = schema.object_classes[ oc_oid ]
 			explicit_oc.ancestors.collect {|oc| oc.name }
 		end.flatten.uniq
-		self.log.debug "  got %d candidate objectClasses: %p" % [ ocs.length, ocs ]
+		# self.log.debug "  got %d candidate objectClasses: %p" % [ ocs.length, ocs ]
 
 		oc_mixins = self.class.mixins_for_objectclasses( *ocs )
 		dn_mixins = self.class.mixins_for_dn( dn )
-		self.log.debug "  found %d mixins by objectclass (%s), and %d by base (%s)" % [
-			oc_mixins.length,
-			oc_mixins.map(&:name).join(', '),
-			dn_mixins.length,
-			dn_mixins.map(&:name).join(', ')
-		]
+		# self.log.debug "  found %d mixins by objectclass (%s), and %d by base (%s)" % [
+		# 	oc_mixins.length,
+		# 	oc_mixins.map(&:name).join(', '),
+		# 	dn_mixins.length,
+		# 	dn_mixins.map(&:name).join(', ')
+		# ]
 
 		# The applicable mixins are those in the intersection of the ones
 		# inferred by its objectclasses and those that apply to its DN
 		mixins = ( oc_mixins & dn_mixins )
-		self.log.debug "  %d mixins remain after intersection: %p" % [ mixins.length, mixins ]
+		# self.log.debug "  %d mixins remain after intersection: %p" % [ mixins.length, mixins ]
 
 		mixins.each {|mod| self.extend(mod) }
 	end
@@ -369,9 +686,9 @@ class Treequel::Model < Treequel::Branch
 	def attribute_from_method( methodname )
 
 		case methodname.to_s
-		when /^(?:has_)?([a-z]\w+)\?$/i
+		when /^(?:has_)?([a-z]\w*)\?$/i
 			return $1.to_sym, :predicate
-		when /^([a-z]\w+)(=)?$/i
+		when /^([a-z]\w*)(=)?$/i
 			return $1.to_sym, ($2 ? :writer : :reader )
 		end
 	end