treequel 1.3.0pre384 → 1.3.0

data/ChangeLog

@@ -1,8 +1,53 @@
+2011-01-12  Michael Granger  <ged@FaerieMUD.org>
+
+	* lib/treequel/model.rb:
+	Always initialize the dirty flag for Treequel::Model objects.
+	[4a75d892a89d] [github/master, master, tip]
+
+	* lib/treequel/branch.rb, spec/treequel/branch_spec.rb:
+	Fixed a bug in Treequel::Branch that caused non-schema attribute
+	fetches through the index operator to pollute the values cache,
+	which in turn caused Treequel::Model schema validations to fail.
+	[8cee4f66c05d]
+
+	* manual/src/models.page:
+	More work on the manual
+	[1652fd0874ab]
+
+	* lib/treequel/model.rb, spec/treequel/model_spec.rb:
+	Made Treequel::Model#validate run the
+	before_validation/after_validation hooks
+	[55d6b5f34c2b]
+
+2011-01-11  Michael Granger  <ged@FaerieMUD.org>
+
+	* lib/treequel/exceptions.rb, lib/treequel/model.rb,
+	manual/src/models.page, spec/treequel/model_spec.rb:
+	Worked on model hooks and validations; added specs, raise exceptions
+	by default, started adding info to the manual.
+	[2454e05f1302]
+
+	* lib/treequel/model/errors.rb,
+	lib/treequel/model/schemavalidations.rb,
+	spec/treequel/model/errors_spec.rb,
+	spec/treequel/model/schemavalidations_spec.rb:
+	Adding structural-objectClass validation
+	[1b9bd6587cf0]
+
+	* Rakefile:
+	Add sysexits to the list of dev dependencies
+	[54e20f994ef4]
+
+	* Manifest.txt:
+	Rearranged the release manifest a bit to make it easier to check
+	against the source in TextMate
+	[fd358623589a]
+
 2011-01-10  Michael Granger  <ged@FaerieMUD.org>
 
 	* Rakefile:
 	Cleaning up dependencies, adding a note to the post-install
-	[633dfb8ea77a] [github/master, master, tip]
+	[633dfb8ea77a]
 
 	* Manifest.txt:
 	Adding the ChangeLog to the release manifest

data/History.md

@@ -1,4 +1,4 @@
-## 1.3.0 [2011-01-07] Michael Granger <ged@FaerieMUD.org>
+## 1.3.0 [2011-01-13] Michael Granger <ged@FaerieMUD.org>
 
 Enhancements:
 
@@ -12,6 +12,17 @@ Enhancements:
   - Treequel::Model#errors
   - Treequel::Model#revert
   - Treequel::Model#modified?
+  - Treequel::Model#after_initialize
+  - Treequel::Model#before_validation
+  - Treequel::Model#after_validation
+  - Treequel::Model#before_save
+  - Treequel::Model#before_create
+  - Treequel::Model#before_update
+  - Treequel::Model#after_create
+  - Treequel::Model#after_update
+  - Treequel::Model#after_save
+  - Treequel::Model#before_destroy
+  - Treequel::Model#after_destroy
   New classes:
   - Treequel::Model::Errors
   - Treequel::ValidationFailed
@@ -36,6 +47,7 @@ Bugfixes:
   - Check for explicit nil DN in .new
   - Check for nil parent_dn in #parent
   - Use 'top' instead of :top as objectClass default
+  - Don't cache attempts to fetch invalid attributes
 
 
 ## 1.2.2 [2010-12-14] Michael Granger <ged@FaerieMUD.org>

data/Rakefile

@@ -24,6 +24,7 @@ hoespec = Hoe.spec 'treequel' do
 		'ruby-termios'  => '~> 0.9.6',
 		'ruby-terminfo' => '~> 0.1.1',
 		'columnize'     => '~> 0.3.1',
+		'sysexits'      => '~> 1.0.2',
 	}
 
 	self.spec_extras[:licenses] = ["BSD"]

data/lib/treequel/branch.rb

@@ -320,7 +320,7 @@ class Treequel::Branch
 			value.freeze if
 				self.class.freeze_converted_values? &&
 				value.respond_to?( :freeze )
-			@values[ attrsym ] = value
+			@values[ attrsym ] = value if value
 		end
 
 		return @values[ attrsym ]

data/lib/treequel/exceptions.rb

@@ -40,9 +40,34 @@ module Treequel
 			end
 		end
 
+		######
+		public
+		######
+
 		# @return [Treequel::Model::Errors] the validation errors
 		attr_reader :errors
-	end
+
+	end # class ValidationFailed
+
+	### Exception class raised when a before_* hooks returns a false value when saving
+	### or destroying a Treequel::Model object.
+	class BeforeHookFailed < Treequel::ModelError
+
+		### Create a new Treequel::BeforeHookFailed exception that indicates that the
+		### specified +hook+ returned a false value.
+		def initialize( hook )
+			@hook = hook.to_sym
+			super "The 'before' hook failed when trying to %s" % [ hook ]
+		end
+
+		######
+		public
+		######
+
+		# The hook that failed
+		attr_reader :hook
+
+	end # class BeforeHookFailed
 
 end # module Treequel
 

data/lib/treequel/model/errors.rb

@@ -47,11 +47,11 @@ class Treequel::Model::Errors < ::Hash
 	end
 
 
-	### Adds an error for the given +attribute+.
-	### @param [Symbol, #to_sym] attribute  the attribute with an error
+	### Adds an error for the given +subject+.
+	### @param [Symbol, #to_sym] subject    the subject of the error
 	### @param [String] message             the description of the error condition
-	def add( attribute, message )
-		self[ attribute ] << message
+	def add( subject, message )
+		self[ subject ] << message
 	end
 
 

data/lib/treequel/model/schemavalidations.rb

@@ -12,12 +12,21 @@ module Treequel::Model::SchemaValidations
 	def validate( options={} )
 		return unless options[:with_schema]
 
+		self.validate_structural_objectclass
 		self.validate_must_attributes
 		self.validate_may_attributes
 		self.validate_attribute_syntax
 	end
 
 
+	### Ensure that the object has at least one structural objectClass.
+	def validate_structural_objectclass
+		unless self.object_classes.any? {|oc| oc.structural? }
+			self.errors.add( :entry, "must have at least one structural objectClass" )
+		end
+	end
+
+
 	### Validate that all attributes that MUST be included according to the entry's
 	### objectClasses have at least one value.
 	def validate_must_attributes

data/lib/treequel/model.rb

@@ -53,6 +53,16 @@ class Treequel::Model < Treequel::Branch
 		:with_schema => true,
 	}
 
+	# Defaults for #save options
+	DEFAULT_SAVE_OPTIONS = {
+		:raise_on_failure => true,
+	}
+
+	# Defaults for #destroy options
+	DEFAULT_DESTROY_OPTIONS = {
+		:raise_on_failure => true,
+	}
+
 
 	#################################################################
 	###	C L A S S   M E T H O D S
@@ -191,6 +201,7 @@ class Treequel::Model < Treequel::Branch
 	def initialize( directory, dn, entry=nil, from_directory=false )
 		if from_directory
 			super( directory, dn, entry )
+			@dirty = false
 		else
 			super( directory, dn )
 			@values = entry ? symbolify_keys( entry ) : {}
@@ -218,6 +229,7 @@ class Treequel::Model < Treequel::Branch
 	HOOKS.each do |hook|
 		define_method( hook ) do |*args|
 			self.log.debug "#{hook} default hook called."
+			true
 		end
 	end
 
@@ -321,31 +333,36 @@ class Treequel::Model < Treequel::Branch
 	### 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
-
+		self.validate( opts )
 		return self.errors.empty? ? true : false
 	end
 
 
-	### Validate the object with the specified +options+.
+	### Validate the object with the specified +options+. Appending validation errors onto
+	### the #errors object.
 	### @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.before_validation or
+			raise Treequel::BeforeHookFailed, :validation
 		self.errors.add( :objectClass, 'must have at least one' ) if self.object_classes.empty?
 
 		super( options )
+		self.after_validation
 	end
 
 
 	### Write any pending changes in the model object to the directory.
-	def save
+	### @param [Hash] opts  save options
+	### @option opts [Boolean] :raise_on_failure  (true) raise a Treequel::ValidationFailed or
+	###      Treequel::BeforeHookFailed if either the validations or before_{save,create}
+	def save( opts={} )
+		opts = DEFAULT_SAVE_OPTIONS.merge( opts )
+
 		self.log.debug "Saving %s..." % [ self.dn ]
-		raise Treequel::ValidationFailed, self.errors unless self.valid?
+		raise Treequel::ValidationFailed, self.errors unless self.valid?( opts )
 		self.log.debug "  validation succeeded."
 
 		unless mods = self.modifications
@@ -354,24 +371,25 @@ class Treequel::Model < Treequel::Branch
 		end
 
 		self.log.debug "  got %d modifications." % [ mods.length ]
-		self.before_save( mods ) or return nil
+		self.before_save( mods ) or
+			raise Treequel::BeforeHookFailed, :save
 
 		if self.exists?
-			self.log.debug "    entry already exists: updating..."
-			self.before_update( mods ) or return nil
-			self.modify( mods )
-			self.after_update( mods )
-
+			self.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
+	rescue Treequel::BeforeHookFailed => err
+		self.log.info( err.message )
+		raise if opts[:raise_on_failure]
+	rescue Treequel::ValidationFailed => err
+		self.log.error( "Save aborted: validation failed." )
+		self.log.info( err.errors.full_messages.join(', ') )
+		raise if opts[:raise_on_failure]
 	end
 
 
@@ -437,6 +455,21 @@ class Treequel::Model < Treequel::Branch
 	end
 
 
+	### Like #delete, but runs destroy hooks before and after deleting.
+	def destroy( opts={} )
+		opts = DEFAULT_DESTROY_OPTIONS.merge( opts )
+
+		self.before_destroy or raise Treequel::BeforeHookFailed, :destroy
+		self.delete
+		self.after_destroy
+
+		return true
+	rescue Treequel::BeforeHookFailed => err
+		self.log.info( err.message )
+		raise if opts[:raise_on_failure]
+	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 )
@@ -493,6 +526,28 @@ class Treequel::Model < Treequel::Branch
 	end
 
 
+	### Update the object's entry with the specified +mods+.
+	### @param [Array<LDAP::Mod>] mods  the modifications to make
+	def update( mods )
+		self.log.debug "    entry already exists: updating..."
+		self.before_update( mods ) or
+			raise Treequel::BeforeHookFailed, :update
+		self.modify( mods )
+		self.after_update( mods )
+	end
+
+
+	### Create the entry for the object, using the specified +mods+ to set the attributes.
+	### @param [Array<LDAP::Mod>] mods  the modifications to set attributes
+	def create( mods )
+		self.log.debug "    entry doesn't exist: creating..."
+		self.before_create( mods ) or
+			raise Treequel::BeforeHookFailed, :create
+		super( mods )
+		self.after_create( mods )
+	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 )

data/spec/treequel/branch_spec.rb

@@ -801,6 +801,15 @@ describe Treequel::Branch do
 				2.times { @branch[ :description ] }
 			end
 
+			it "doesn't cache nil values that don't correspond to an attribute type in the schema" do
+				@conn.should_receive( :search_ext2 ).
+					with( TEST_HOSTS_DN, LDAP::LDAP_SCOPE_BASE, "(objectClass=*)" ).
+					and_return([ @entry ])
+
+				@branch[ :string_beans ]
+				@branch.instance_variable_get( :@values ).should_not have_key( :string_beans )
+			end
+
 			it "freezes the values fetched from its entry by default to prevent accidental " +
 			   "in-place modification" do
 				@conn.should_receive( :search_ext2 ).

data/spec/treequel/model/errors_spec.rb

@@ -47,8 +47,8 @@ describe Treequel::Model::Errors do
 
 	it "knows how many errors there are" do
 		@errors.add( :l, "is not valid" )
-		@errors.add( :description, "must " )
-		@errors.add( :description, "must have at least one description" )
+		@errors.add( :description, "must be this tall to ride" )
+		@errors.add( :description, "must have at least one value" )
 
 		@errors.count.should == 3
 	end

data/spec/treequel/model/schemavalidations_spec.rb

@@ -45,10 +45,23 @@ describe Treequel::Model::SchemaValidations do
 	# 	MUST ( sn $ cn ) 
 	# 	MAY ( userPassword $ telephoneNumber $ seeAlso $ description ) )
 
+	it "adds an error if the object doesn't have at least one structural objectClass" do
+		@conn.stub( :search_ext2 ).and_return( [] )
+		@modelobj.object_class = ['ipHost', 'ieee802device']
+		@modelobj.cn = 'testhost'
+		@modelobj.ip_host_number = '127.0.0.1'
+
+		@modelobj.should_not be_valid()
+		@modelobj.errors.should have( 1 ).member
+		@modelobj.errors.full_messages.
+			should include( 'entry must have at least one structural objectClass' )
+	end
+
 	it "adds an error if the object doesn't have at least one value for all of its MUST attributes" do
 		@conn.stub( :search_ext2 ).and_return( [] )
 		@modelobj.object_class = 'person'
-		@modelobj.validate
+
+		@modelobj.should_not be_valid()
 		@modelobj.errors.should have( 2 ).members
 		@modelobj.errors.full_messages.should include( 'cn MUST have at least one value' )
 		@modelobj.errors.full_messages.should include( 'sn MUST have at least one value' )
@@ -66,7 +79,7 @@ describe Treequel::Model::SchemaValidations do
 
 		# ..then remove the objectclass that grants it and validate
 		@modelobj.object_class -= ['inetOrgPerson']
-		@modelobj.validate
+		@modelobj.should_not be_valid()
 
 		@modelobj.errors.full_messages.
 			should == [%{displayName is not allowed by entry's objectClasses}]
@@ -92,7 +105,7 @@ describe Treequel::Model::SchemaValidations do
 		@modelobj.uid_number = "something that's not a number"
 		@modelobj.gid_number = "also not a number"
 
-		@modelobj.validate
+		@modelobj.should_not be_valid()
 
 		@modelobj.errors.should have( 2 ).members
 		@modelobj.errors.full_messages.should include( "uidNumber isn't a valid Integer value" )

data/spec/treequel/model_spec.rb

@@ -446,7 +446,53 @@ describe Treequel::Model do
 		end
 
 		it "knows if any validation errors have been encountered" do
-			@obj.errors.should be_a( Hash )
+			@obj.errors.should be_a( Treequel::Model::Errors )
+		end
+
+		it "can delete its entry with callbacks" do
+			class << @obj; attr_reader :callbacks; end
+			@obj.instance_variable_set( :@callbacks, [] )
+			def @obj.before_destroy
+				self.callbacks << :before_destroy
+			end
+			def @obj.after_destroy
+				self.callbacks << :after_destroy
+			end
+
+			@conn.should_receive( :delete ).with( @obj.dn )
+
+			@obj.destroy
+			@obj.callbacks.should == [ :before_destroy, :after_destroy ]
+		end
+
+		it "doesn't delete its entry if the destroy callback returns something falseish" do
+			def @obj.before_destroy
+				false
+			end
+			def @obj.after_destroy
+				fail "shouldn't call the after_destroy hook, either"
+			end
+
+			@conn.should_not_receive( :delete )
+
+			expect {
+				@obj.destroy
+			}.to raise_error( Treequel::BeforeHookFailed, /destroy/i )
+		end
+
+		it "doesn't raise a BeforeHookFailed if destroyed without :raise_on_failure" do
+			def @obj.before_destroy
+				false
+			end
+
+			@conn.should_not_receive( :delete )
+
+			result = nil
+			expect {
+				result = @obj.destroy( :raise_on_failure => false )
+			}.to_not raise_error()
+
+			result.should be_false()
 		end
 
 
@@ -501,6 +547,54 @@ describe Treequel::Model do
 				@obj.save
 			end
 
+
+			it "calls update hooks when saved" do
+				class << @obj; attr_reader :callbacks; end
+				@obj.instance_variable_set( :@callbacks, [] )
+				def @obj.before_update( mods )
+					self.callbacks << :before_update
+				end
+				def @obj.after_update( mods )
+					self.callbacks << :after_update
+				end
+
+				@conn.should_receive( :modify )
+
+				@obj.save
+				@obj.callbacks.should == [ :before_update, :after_update ]
+			end
+
+			it "doesn't modify its entry if the before_update callback returns something falseish" do
+				def @obj.before_update( mods )
+					false
+				end
+				def @obj.after_update( mods )
+					fail "shouldn't call the after_update hook, either"
+				end
+
+				@conn.should_not_receive( :modify )
+
+				expect {
+					@obj.save
+				}.to raise_error( Treequel::BeforeHookFailed, /update/i )
+			end
+
+			it "doesn't raise a BeforeHookFailed if saved without :raise_on_failure" do
+				def @obj.before_update( mods )
+					false
+				end
+
+				@conn.stub( :search_ext2 ).with( @obj.dn, LDAP::LDAP_SCOPE_BASE, "(objectClass=*)" ).
+					and_return( [] )
+				@conn.should_not_receive( :modify )
+
+				result = nil
+				expect {
+					result = @obj.save( :raise_on_failure => false )
+				}.to_not raise_error()
+
+				result.should be_false()
+			end
 		end
 
 
@@ -593,11 +687,11 @@ describe Treequel::Model do
 
 		it "creates the entry in the directory when saved" do
 			@conn.stub( :search_ext2 ).
-				with( TEST_PERSON_DN, LDAP::LDAP_SCOPE_BASE, '(objectClass=*)').
+				with( @obj.dn, LDAP::LDAP_SCOPE_BASE, '(objectClass=*)').
 				and_return( [] )
 
 			@conn.should_receive( :add ).
-				with( TEST_PERSON_DN, [
+				with( @obj.dn, [
 					ldap_mod_add("cn", "James"),
 					ldap_mod_add("displayName", "J. Random Hacker"),
 					ldap_mod_add("gidNumber", "200"),
@@ -612,6 +706,58 @@ describe Treequel::Model do
 			@obj.save
 		end
 
+		it "calls creation hooks when saved" do
+			class << @obj; attr_reader :callbacks; end
+			@obj.instance_variable_set( :@callbacks, [] )
+			def @obj.before_create( mods )
+				self.callbacks << :before_create
+			end
+			def @obj.after_create( mods )
+				self.callbacks << :after_create
+			end
+
+			@conn.stub( :search_ext2 ).with( @obj.dn, LDAP::LDAP_SCOPE_BASE, "(objectClass=*)" ).
+				and_return( [] )
+			@conn.should_receive( :add )
+
+			@obj.save
+			@obj.callbacks.should == [ :before_create, :after_create ]
+		end
+
+		it "doesn't add its entry if the before_create callback returns something falseish" do
+			def @obj.before_create( mods )
+				false
+			end
+			def @obj.after_create( mods )
+				fail "shouldn't call the after_create hook, either"
+			end
+
+			@conn.stub( :search_ext2 ).with( @obj.dn, LDAP::LDAP_SCOPE_BASE, "(objectClass=*)" ).
+				and_return( [] )
+			@conn.should_not_receive( :add )
+
+			expect {
+				@obj.save
+			}.to raise_error( Treequel::BeforeHookFailed, /create/i )
+		end
+
+		it "doesn't raise a BeforeHookFailed if saved without :raise_on_failure" do
+			def @obj.before_create( mods )
+				false
+			end
+
+			@conn.stub( :search_ext2 ).with( @obj.dn, LDAP::LDAP_SCOPE_BASE, "(objectClass=*)" ).
+				and_return( [] )
+			@conn.should_not_receive( :add )
+
+			result = nil
+			expect {
+				result = @obj.save( :raise_on_failure => false )
+			}.to_not raise_error()
+
+			result.should be_false()
+		end
+
 	end
 
 end

metadata

@@ -7,7 +7,7 @@ version: !ruby/object:Gem::Version
   - 1
   - 3
   - 0
-  version: 1.3.0pre384
+  version: 1.3.0
 platform: ruby
 authors: 
 - Michael Granger
@@ -36,7 +36,7 @@ cert_chain:
   cmlhXe46pZNJgWKbxZah85jIjx95hR8vOI+NAM5iH9kOqK13DrxacTKPhqj5PjwF
   -----END CERTIFICATE-----
 
-date: 2011-01-10 00:00:00 -08:00
+date: 2011-01-13 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -136,9 +136,25 @@ dependencies:
   type: :development
   version_requirements: *id006
 - !ruby/object:Gem::Dependency 
-  name: hoe
+  name: sysexits
   prerelease: false
   requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 1
+        - 0
+        - 2
+        version: 1.0.2
+  type: :development
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  prerelease: false
+  requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -150,7 +166,7 @@ dependencies:
         - 0
         version: 2.8.0
   type: :development
-  version_requirements: *id007
+  version_requirements: *id008
 description: |-
   Treequel is an LDAP toolkit for Ruby. It is intended to allow quick, easy
   access to LDAP directories in a manner consistent with LDAP's hierarchical,