treequel 1.0.4 → 1.1.0

data/lib/treequel/directory.rb

@@ -9,6 +9,7 @@ require 'treequel'
 require 'treequel/schema'
 require 'treequel/mixins'
 require 'treequel/constants'
+require 'treequel/branch'
 
 
 # The object in Treequel that represents a connection to a directory, the
@@ -27,17 +28,33 @@ class Treequel::Directory
 		:connect_type  => :tls,
 		:base_dn       => nil,
 		:bind_dn       => nil,
-		:pass          => nil
+		:pass          => nil,
+		:results_class => Treequel::Branch,
 	}
 
-	# Default mapping of SYNTAX OIDs to conversions. See #add_syntax_mapping for more
-	# information on what a valid conversion is.
-	DEFAULT_SYNTAX_MAPPING = {
-		OIDS::BIT_STRING_SYNTAX       => lambda {|bs| bs[0..-1].to_i(2) },
-		OIDS::BOOLEAN_SYNTAX          => { 'TRUE' => true, 'FALSE' => false },
-		OIDS::GENERALIZED_TIME_SYNTAX => lambda {|string| Time.parse(string) },
-		OIDS::UTC_TIME_SYNTAX         => lambda {|string| Time.parse(string) },
-		OIDS::INTEGER_SYNTAX          => lambda {|string| Integer(string) },
+	# Default mapping of SYNTAX OIDs to conversions from an LDAP string. 
+	# See #add_attribute_conversions for more information on what a valid conversion is.
+	DEFAULT_ATTRIBUTE_CONVERSIONS = {
+		OIDS::BIT_STRING_SYNTAX         => lambda {|bs, _| bs[0..-1].to_i(2) },
+		OIDS::BOOLEAN_SYNTAX            => { 'TRUE' => true, 'FALSE' => false },
+		OIDS::GENERALIZED_TIME_SYNTAX   => lambda {|string, _| Time.parse(string) },
+		OIDS::UTC_TIME_SYNTAX           => lambda {|string, _| Time.parse(string) },
+		OIDS::INTEGER_SYNTAX            => lambda {|string, _| Integer(string) },
+		OIDS::DISTINGUISHED_NAME_SYNTAX => lambda {|dn, directory|
+			resclass = directory.results_class
+			resclass.new( directory, dn )
+		},
+	}
+
+	# Default mapping of SYNTAX OIDs to conversions to an LDAP string from a Ruby object. 
+	# See #add_object_conversion for more information on what a valid conversion is.
+	DEFAULT_OBJECT_CONVERSIONS = {
+		OIDS::BIT_STRING_SYNTAX         => lambda {|bs, _| bs.to_i.to_s(2) },
+		OIDS::BOOLEAN_SYNTAX            => lambda {|obj, _| obj ? 'TRUE' : 'FALSE' },
+		OIDS::GENERALIZED_TIME_SYNTAX   => lambda {|time, _| time.ldap_generalized },
+		OIDS::UTC_TIME_SYNTAX           => lambda {|time, _| time.ldap_utc },
+		OIDS::INTEGER_SYNTAX            => lambda {|obj, _| Integer(obj).to_s },
+		OIDS::DISTINGUISHED_NAME_SYNTAX => lambda {|obj, _| obj.dn },
 	}
 
 	# :NOTE: the docs for #search_ext2 lie. The method signature is actually:
@@ -102,22 +119,26 @@ class Treequel::Directory
 	###    The DN of the user to bind as; if unset, binds anonymously.
 	### @option options [String] :pass (nil)
 	###    The password to use when binding.
+	### @option options [CLass] :results_class (Treequel::Branch)
+	###    The class to instantiate by default for entries fetched from the Directory.
 	def initialize( options={} )
-		options       = DEFAULT_OPTIONS.merge( options )
+		options                = DEFAULT_OPTIONS.merge( options )
 
-		@host         = options[:host]
-		@port         = options[:port]
-		@connect_type = options[:connect_type]
+		@host                  = options[:host]
+		@port                  = options[:port]
+		@connect_type          = options[:connect_type]
+		@results_class         = options[:results_class]
 
-		@conn         = nil
-		@bound_user   = nil
+		@conn                  = nil
+		@bound_user            = nil
 
-		@base_dn      = options[:base_dn] || self.get_default_base_dn
+		@base_dn               = options[:base_dn] || self.get_default_base_dn
 
-		@base         = nil
+		@base                  = nil
 
-		@syntax_mapping      = DEFAULT_SYNTAX_MAPPING.dup
-		@registered_controls = []
+		@object_conversions    = DEFAULT_OBJECT_CONVERSIONS.dup
+		@attribute_conversions = DEFAULT_ATTRIBUTE_CONVERSIONS.dup
+		@registered_controls   = []
 
 		# Immediately bind if credentials are passed to the initializer.
 		if ( options[:bind_dn] && options[:pass] )
@@ -134,7 +155,7 @@ class Treequel::Directory
 	def_method_delegators :base, *DELEGATED_BRANCH_METHODS
 
 	# Delegate some methods to the connection via the #conn method
-	def_method_delegators :conn, :controls, :referrals
+	def_method_delegators :conn, :controls, :referrals, :root_dse
 
 
 	# The host to connect to.
@@ -149,6 +170,10 @@ class Treequel::Directory
 	# @return [Symbol]
 	attr_accessor :connect_type
 
+	# The Class to instantiate when wrapping results fetched from the Directory.
+	# @return [Class]
+	attr_accessor :results_class
+
 	# The base DN of the directory
 	# @return [String]
 	attr_accessor :base_dn
@@ -165,7 +190,7 @@ class Treequel::Directory
 	### Fetch the Branch for the base node of the directory.
 	### @return [Treequel::Branch]
 	def base
-		return @base ||= Treequel::Branch.new( self, self.base_dn )
+		return @base ||= self.results_class.new( self, self.base_dn )
 	end
 
 
@@ -330,8 +355,8 @@ class Treequel::Directory
 	### 
 	### @option options [Class] :results_class (Treequel::Branch)
 	###    The Class to use when wrapping results; if not specified, defaults to the class 
-	###    of +base+ if it responds to #new_from_entry, or Treequel::Branch 
-	###    if it does not.
+	###    of +base+ if it responds to #new_from_entry, or the directory object's 
+	###    #results_class if it does not.
 	### @option options [Array<String, Symbol>] :selectattrs (['*'])
 	###    The attributes to return from the search; defaults to '*', which means to
 	###    return all non-operational attributes. Specifying '+' will cause the search
@@ -372,7 +397,9 @@ class Treequel::Directory
 		if options.key?( :results_class )
 			collectclass = options.delete( :results_class )
 		else
-			collectclass = base.class.respond_to?( :new_from_entry ) ? base.class : Treequel::Branch
+			collectclass = base.class.respond_to?( :new_from_entry ) ?
+				base.class :
+				self.results_class
 		end
 
 		# Format the arguments in the way #search_ext2 expects them
@@ -395,7 +422,6 @@ class Treequel::Directory
 		]]
 
 		results = []
-
 		self.conn.search_ext2( base_dn, scope, filter, *parameters ).each do |entry|
 			branch = collectclass.new_from_entry( entry, self )
 			branch.include_operational_attrs = base.include_operational_attrs? if
@@ -495,25 +521,41 @@ class Treequel::Directory
 	end
 
 
+	### Add +conversion+ mapping for attributes of specified +oid+ to a Ruby object. A 
+	### conversion is any object that responds to #[] with a String 
+	### argument(e.g., Proc, Method, Hash); the argument is the raw value String returned 
+	### from the LDAP entry, and it should return the converted value. Adding a mapping 
+	### with a nil +conversion+ effectively clears it.
+	### @see #convert_to_object
+	def add_attribute_conversion( oid, conversion=nil )
+		conversion = Proc.new if block_given?
+		@attribute_conversions[ oid ] = conversion
+	end
+
+
 	### Add +conversion+ mapping for the specified +oid+. A conversion is any object that
-	### responds to #[] with a String argument(e.g., Proc, Method, Hash); the argument is 
-	### the raw value String returned from the LDAP entry, and it should return the 
-	### converted value. Adding a mapping with a nil +conversion+ effectively clears it.
-	def add_syntax_mapping( oid, conversion=nil )
+	### responds to #[] with an object argument(e.g., Proc, Method, Hash); the argument is 
+	### the Ruby object that's being set as a value in an LDAP entry, and it should return the 
+	### raw LDAP string. Adding a mapping with a nil +conversion+ effectively clears it.
+	### @see #convert_to_attribute
+	def add_object_conversion( oid, conversion=nil )
 		conversion = Proc.new if block_given?
-		@syntax_mapping[ oid ] = conversion
+		@object_conversions[ oid ] = conversion
 	end
 
 
 	### Register the specified +modules+
 	def register_controls( *modules )
-		dse = self.conn.root_dse.first
-		supported_controls = dse['supportedControl']
+		supported_controls = self.supported_control_oids
+		self.log.debug "Got %d supported controls: %p" %
+			[ supported_controls.length, supported_controls ]
 
 		modules.each do |mod|
 			oid = mod.const_get( :OID ) if mod.const_defined?( :OID )
 			raise NotImplementedError, "%s doesn't define an OID" % [ mod.name ] if oid.nil?
 
+			self.log.debug "Checking for directory support for %p (%s)" % [ mod, oid ]
+
 			if supported_controls.include?( oid )
 				@registered_controls << mod
 			else
@@ -524,17 +566,30 @@ class Treequel::Directory
 	end
 
 
-	### Map the specified +value+ to its Ruby datatype if one is registered for the given 
+	### Map the specified LDAP +attribute+ to its Ruby datatype if one is registered for the given 
 	### syntax +oid+. If there is no conversion registered, just return the +value+ as-is.
-	def convert_syntax_value( oid, value )
-		self.log.debug "Converting value %p using the syntax rule for %p" % [ value, oid ]
-		unless conversion = @syntax_mapping[ oid ]
-			self.log.debug "  ...no conversion, returning it as-is."
-			return value
+	def convert_to_object( oid, attribute )
+		return attribute unless conversion = @attribute_conversions[ oid ]
+
+		if conversion.respond_to?( :call )
+			return conversion.call( attribute, self )
+		else
+			return conversion[ attribute ]
 		end
+	end
 
-		self.log.debug "  ...found conversion: %p" % [ conversion ]
-		return conversion[ value ]
+
+	### Map the specified Ruby +object+ to its LDAP string equivalent if a conversion is 
+	### registered for the given syntax +oid+. If there is no conversion registered, just 
+	### returns the +value+ as a String (via #to_s).
+	def convert_to_attribute( oid, object )
+		return object.to_s unless conversion = @object_conversions[ oid ]
+
+		if conversion.respond_to?( :call )
+			return conversion.call( object, self )
+		else
+			return conversion[ object ]
+		end
 	end
 
 
@@ -619,7 +674,7 @@ class Treequel::Directory
 
 	### Fetch the default base dn for the server from the server's Root DSE.
 	def get_default_base_dn
-		dse = self.conn.root_dse
+		dse = self.root_dse
 		return '' if dse.nil? || dse.empty?
 		return dse.first['namingContexts'].first
 	end

data/lib/treequel/filter.rb

@@ -62,6 +62,15 @@ class Treequel::Filter
 			return self.filters.collect {|f| f.to_s }.join
 		end
 
+
+		### Append operator: add the +other+ filter to the list.
+		### @param [Treequel::Filter] other  the new filter to add
+		### @return [Treequel::Filter::FilterList]  self (for chaining)
+		def <<( other )
+			@filters << other
+			return self
+		end
+
 	end # class FilterList
 
 
@@ -140,6 +149,12 @@ class Treequel::Filter
 			return '&' + @filterlist.to_s
 		end
 
+		### Add an additional filter to the list of requirements
+		### @param [Treequel::Filter] filter  the new requirement
+		def add_requirement( filter )
+			@filterlist << filter
+		end
+
 	end # AndComponent
 
 
@@ -160,6 +175,12 @@ class Treequel::Filter
 			return '|' + @filterlist.to_s
 		end
 
+		### Add an additional filter to the list of alternatives
+		### @param [Treequel::Filter] filter  the new alternative
+		def add_alternation( filter )
+			@filterlist << filter
+		end
+
 	end # class OrComponent
 
 
@@ -215,8 +236,10 @@ class Treequel::Filter
 			self.log.debug "creating a new %s %s for %p and %p" %
 				[ filtertype, self.class.name, attribute, value ]
 
-			filtertype = filtertype.to_s.downcase.to_sym
+			# Handle Sequel :attribute.identifier
+			attribute = attribute.value if attribute.respond_to?( :value )
 
+			filtertype = filtertype.to_s.downcase.to_sym
 			if FILTERTYPE_OP.key?( filtertype )
 				# no-op
 			elsif FILTEROP_NAMES.key?( filtertype.to_s )
@@ -688,6 +711,24 @@ class Treequel::Filter
 	alias_method :+, :&
 
 
+	### OR two filters together
+	### @param [Treequel::Filter] other_filter
+	def |( other_filter )
+		return other_filter if self.promiscuous?
+		return self.dup if other_filter.promiscuous?
+
+		# Collapse nested ORs into a single one with an additional alternation
+		# if possible.
+		if self.component.respond_to?( :add_alternation )
+			self.log.debug "collapsing nested ORs..."
+			newcomp = self.component.dup
+			newcomp.add_alternation( other_filter )
+			return self.class.new( newcomp )
+		else
+			return self.class.new( :or, [self, other_filter] )
+		end
+	end
+
 
 end # class Treequel::Filter
 

data/lib/treequel/model/objectclass.rb

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+require 'treequel'
+require 'treequel/model'
+require 'treequel/mixins'
+require 'treequel/constants'
+
+
+# Mixin that provides Treequel::Model characteristics to a mixin module.
+module Treequel::Model::ObjectClass
+
+	### Extension callback -- add data structures to the extending +mod+.
+	### @param [Module] mod  the mixin module to be extended
+	def self::extended( mod )
+		# mod.instance_variable_set( :@model_directory, nil )
+		# mod.instance_variable_set( :@model_bases, [] )
+		mod.instance_variable_set( :@model_class, Treequel::Model )
+		mod.instance_variable_set( :@model_objectclasses, [] )
+		mod.instance_variable_set( :@model_bases, [] )
+		super
+	end
+
+
+	### Inclusion callback -- Methods should be applied to the module rather than an instance.
+	### Warn the user if they use include() and extend() instead.
+	def self::included( mod )
+		warn "extending %p rather than appending features to it" % [ mod ]
+		mod.extend( self )
+	end
+
+
+	### Declare which Treequel::Model subclasses the mixin will register itself with. If this is
+	### used, it should be declared *before* declaring the mixin's bases and/or objectClasses.
+	def model_class( mclass=nil )
+		if mclass
+
+			# If there were already registered objectclasses, remove them from the previous
+			# model class
+			unless @model_objectclasses.empty? && @model_bases.empty?
+				Treequel.log.warn "%p: model_class should come before model_objectclasses" % [ self ]
+				@model_class.unregister_mixin( self )
+				mclass.register_mixin( self )
+			end
+			@model_class = mclass
+		end
+
+		return @model_class
+	end
+
+
+	### Set or get objectClasses that the mixin requires. Also registers the mixin with
+	### Treequel::Model.
+	### 
+	### @param [Array<Symbol>] objectclasses  the objectClasses the mixin will apply to, as an
+	###                                       array of Symbols
+	### @return [Array<Symbol>] the objectClasses that the module requires
+	def model_objectclasses( *objectclasses )
+		unless objectclasses.empty?
+			@model_objectclasses = objectclasses
+			@model_class.register_mixin( self )
+		end
+		return @model_objectclasses.dup
+	end
+
+
+	### Set or get base DNs that the mixin applies to.
+	def model_bases( *base_dns )
+		unless base_dns.empty?
+			@model_bases = base_dns.collect {|dn| dn.gsub(/\s+/, '') }
+			@model_class.register_mixin( self )
+		end
+
+		return @model_bases.dup
+	end
+
+
+	### Return a Branchset (or BranchCollection if the receiver has more than one
+	### base) that can be used to search the given +directory+ for entries to which
+	### the receiver applies.
+	###
+	### @param [Treequel::Directory] directory  the directory to search
+	### @return [Treequel::Branchset, Treequel::BranchCollection]  the encapsulated search
+	def search( directory )
+		bases = self.model_bases
+		objectclasses = self.model_objectclasses
+
+		raise Treequel::ModelError, "%p has no search criteria defined" % [ self ] if
+			bases.empty? && objectclasses.empty?
+
+		Treequel.log.debug "Creating search for %s using model class %p" %
+			[ self.name, self.model_class ]
+
+		# Start by making a Branchset or BranchCollection for the mixin's bases. If
+		# the mixin doesn't have any bases, just use the base DN of the directory
+		# to be searched
+		bases = [directory.base_dn] if bases.empty?
+		search = bases.
+			map {|base| self.model_class.new(directory, base).branchset }.
+			inject {|branch1,branch2| branch1 + branch2 }
+
+		Treequel.log.debug "Search branch after applying bases is: %p" % [ search ]
+
+		return self.model_objectclasses.inject( search ) do |branchset, oid|
+			Treequel.log.debug "  adding filter for objectClass=%s to %p" % [ oid, branchset ]
+			branchset.filter( :objectClass => oid )
+		end
+	end
+
+end # Treequel::Model::ObjectClass
+