ucb_ldap 1.3.0

data/lib/person/generic_attributes.rb

@@ -0,0 +1,68 @@
+
+module UCB::LDAP
+  module GenericAttributes
+    
+  
+    # Returns +true+ if the entry represents a test entry.
+    def test?
+      berkeleyEduTestIDFlag
+    end
+    
+    def uid
+      super.first
+    end
+    
+    def firstname
+      givenname.first
+    end
+    alias :first_name :firstname
+    
+    def lastname
+      sn.first
+    end
+    alias :last_name :lastname
+    
+    def email
+      mail.first
+    end
+    
+    def phone
+      telephoneNumber.first
+    end
+
+    # Returns +Array+ of Affiliation for this Person. Requires a bind with access to affiliations.
+    # See UCB::LDAP.authenticate().
+    def affiliate_affiliations
+      @affiliate_affiliations ||= Affiliation.find_by_uid(uid)
+    end
+ 
+    # Returns +Array+ of Address for this Person.
+    # Requires a bind with access to addresses.
+    # See UCB::LDAP.authenticate().
+    def addresses
+      @addresses ||= Address.find_by_uid(uid)
+    end
+     
+    # Returns +Array+ of Namespace for this Person.
+    # Requires a bind with access to namespaces.
+    # See UCB::LDAP.authenticate().
+    def namespaces
+      @namespaces ||= Namespace.find_by_uid(uid)
+    end
+   
+    # Returns +Array+ of Service for this Person.
+    # Requires a bind with access to services.
+    # See UCB::LDAP.authenticate().
+    def services
+      @services ||= Service.find_by_uid(uid)
+    end
+    
+    # Returns +Array+ of Address for this Person.
+    # Requires a bind with access to addresses.
+    # See UCB::LDAP.authenticate().
+    def addresses
+      @addresses ||= Address.find_by_uid(uid)
+    end
+  
+  end
+end

data/lib/ucb_ldap.rb

@@ -0,0 +1,177 @@
+#
+require 'rubygems'
+require 'net/ldap'
+require 'time'
+require 'ucb_ldap_exceptions'
+require 'ucb_ldap_schema'
+require 'ucb_ldap_schema_attribute'
+require 'ucb_ldap_entry'
+
+require 'person/affiliation_methods.rb'
+require 'person/generic_attributes.rb'
+require 'ucb_ldap_person.rb'
+
+require 'ucb_ldap_person_job_appointment'
+require 'ucb_ldap_org'
+require 'ucb_ldap_namespace'
+require 'ucb_ldap_address'
+require 'ucb_ldap_student_term'
+require 'ucb_ldap_affiliation'
+require 'ucb_ldap_service'
+
+
+module UCB #:nodoc:
+
+  # =UCB::LDAP
+  #
+  # <b>If you are doing searches that don't require a privileged bind
+  # and are accessing the default (production) server
+  # you probably don't need to call any of the methods in this module.</b>
+  # 
+  # Methods in this module are about making <em>connections</em>
+  # to the LDAP directory.
+  # 
+  # Interaction with the directory (searches and updates) is usually through the search()
+  # and other methods of UCB::LDAP::Entry and its sub-classes.
+  # 
+  module LDAP
+  
+    
+    HOST_PRODUCTION = 'ldap.berkeley.edu'
+    HOST_TEST       = 'ldap-test.berkeley.edu'
+
+    
+    # class methods
+    class << self
+      
+      # Give (new) bind credentials to LDAP.  An attempt will be made
+      # to bind and will raise BindFailedException if bind fails.
+      # 
+      # Call clear_authentication() to remove privileged bind.
+      def authenticate(username, password)
+        @username, @password = username, password
+        new_net_ldap # to force bind()
+      end
+
+      # Removes current bind (username, password).
+      def clear_authentication()
+        authenticate(nil, nil)
+      end
+      
+      # Returns LDAP host used for lookups.  Default is HOST_PRODUCTION.
+      def host()
+        @host || HOST_PRODUCTION
+      end
+  
+      # Setter for #host.
+      # 
+      # Note: validation of host is deferred until a search is performed
+      # or #authenticate() is called at which time a bad host will
+      # raise ConnectionFailedException.
+      #---
+      # Don't want to reconnect unless host really changed.
+      def host=(host)
+        if host != @host
+          @host = host
+          @net_ldap = nil
+        end
+      end
+  
+      # Returns Net::LDAP instance that is used by UCB::LDAP::Entry
+      # and subclasses for directory searches.
+      #
+      # You might need this to perform searches not supported by 
+      # sub-classes of Entry.
+      #
+      # Note: callers should not cache the results of this call unless they
+      # are prepared to handle timed-out connections (which this method does).  
+      def net_ldap()
+        @net_ldap ||= new_net_ldap()
+      end
+
+      def password() #:nodoc:
+        @password
+      end
+      
+      def username() #:nodoc:
+        @username
+      end
+      
+      # If you are using UCB::LDAP in a Rails application you can specify binds on a
+      # per-environment basis, just as you can with database credentials.
+      #
+      #   # in ../config/ldap.yml
+      #   
+      #   development:
+      #     username: user_dev
+      #     password: pass_dev
+      #   
+      #   # etc.
+      #
+      # 
+      #   # in ../config/environment.rb
+      #
+      #   require 'ucb_ldap'
+      #   UCB::LDAP.bind_for_rails()
+      # 
+      # Runtime error will be raised if bind_file not found or if environment key not
+      # found in bind_file.
+      def bind_for_rails(bind_file = "#{RAILS_ROOT}/config/ldap.yml", environment = RAILS_ENV)
+        bind(bind_file, environment)
+      end
+      
+      def bind(bind_file, environment)
+        raise "Can't find bind file: #{bind_file}" unless FileTest.exists?(bind_file)
+        binds = YAML.load(IO.read(bind_file))
+        bind = binds[environment] || raise("Can't find environment=#{environment} in bind file")
+        authenticate(bind['username'], bind['password'])
+      end
+
+      # Returns +arg+ as a Ruby +Date+ in local time zone.  Returns +nil+ if +arg+ is +nil+.
+      def local_date_parse(arg)        
+        arg.nil? ? nil : Date.parse(Time.parse(arg.to_s).localtime.to_s)
+      end
+
+      # Returns +arg+ as a Ruby +DateTime+ in local time zone.  Returns +nil+ if +arg+ is +nil+.
+      def local_datetime_parse(arg)        
+        arg.nil? ? nil : DateTime.parse(Time.parse(arg.to_s).localtime.to_s)
+      end
+  
+    private unless $TESTING
+      
+      # The value of the :auth parameter for Net::LDAP.new().
+      def authentication_information()
+        password.nil? ? 
+          {:method => :anonymous} : 
+          {:method => :simple, :username => username, :password => password}
+      end
+      
+      # Returns new Net::LDAP instance.
+      # Note: Calling Net::LDAP.new does not result in a connection to the LDAP
+      # server. Rather, it stores the connection and binding parameters in the object.
+      # Later calls to: [search, add_attribute, rename_attribute, delete_attribute]
+      # will each result result in a new connection to the LDAP server.
+      def new_net_ldap()
+        @net_ldap = Net::LDAP.new(
+          :host => host,
+          :auth => authentication_information,
+          :port => 636, 
+          :encryption => {:method =>:simple_tls}
+        )
+        raise(BindFailedException, @net_ldap.get_operation_result.to_s) unless @net_ldap.bind
+        @net_ldap
+      end
+      
+      # Used for testing
+      def clear_instance_variables()
+        @host = nil
+        @net_ldap = nil
+        @username = nil
+        @password = nil
+      end
+      
+    end
+    
+ end
+end
+

data/lib/ucb_ldap_address.rb

@@ -0,0 +1,106 @@
+
+module UCB
+  module LDAP
+    # = UCB::LDAP::Address
+    # 
+    # This class models a person address instance in the UCB LDAP directory.
+    #
+    #   a = Address.find_by_uid("1234")       #=> [#<UCB::LDAP::Address: ...>, ...]
+    #
+    # Addresses are usually loaded through a Person instance:
+    #
+    #   p = Person.find_by_uid("1234")    #=> #<UCB::LDAP::Person: ...>
+    #   addrs = p.addresses               #=> [#<UCB::LDAP::Address: ...>, ...]
+    #
+    # == Note on Binds
+    # 
+    # You must have a privileged bind and pass your credentials to UCB::LDAP.authenticate()
+    # before performing your Address search.
+    #
+    class Address < Entry
+      @entity_name = 'personAddress'
+
+      def primary_work_address?
+        berkeleyEduPersonAddressPrimaryFlag
+      end
+      
+      def address_type
+        berkeleyEduPersonAddressType
+      end
+      
+      def building_code
+        berkeleyEduPersonAddressBuildingCode
+      end
+      
+      def city
+        l.first
+      end
+      
+      def country_code
+        berkeleyEduPersonAddressCountryCode
+      end
+      
+      def department_name
+        berkeleyEduPersonAddressUnitCalNetDeptName
+      end
+      
+      def department_acronym
+        berkeleyEduPersonAddressUnitHRDeptName
+      end
+      
+      def directories
+        berkeleyEduPersonAddressPublications
+      end
+      
+      # Returns email address associated with this Address.
+      def email
+        mail.first
+      end
+      
+      def mail_code
+        berkeleyEduPersonAddressMailCode
+      end
+      
+      def mail_release?
+        berkeleyEduEmailRelFlag
+      end
+      
+      def phone
+        telephoneNumber.first
+      end
+      
+      # Returns postal address as an Array.
+      #
+      #   addr.attribute(:postalAddress) #=> '501 Banway Bldg.$Berkeley, CA 94720-3814$USA'
+      #   addr.postal_address            #=> ['501 Banway Bldg.', 'Berkeley, CA 94720-3814', 'USA']
+      #
+      def postal_address
+        postalAddress == [] ? nil : postalAddress.split("$")  
+      end
+      
+      def sort_order
+        berkeleyEduPersonAddressSortOrder.first || 0
+      end
+      
+      def state
+        st.first
+      end
+      
+      def zip
+        postalCode
+      end
+      
+      class << self
+        # Returns an Array of Address for <tt>uid</tt>, sorted by sort_order().
+        # Returns an empty Array ([]) if nothing is found.  
+        #
+        def find_by_uid(uid)
+          base = "uid=#{uid},ou=people,dc=berkeley,dc=edu"
+          filter = Net::LDAP::Filter.eq("objectclass", 'berkeleyEduPersonAddress')
+          search(:base => base, :filter => filter).sort_by{|addr| addr.sort_order}
+        end
+         
+      end
+    end
+  end
+end

data/lib/ucb_ldap_affiliation.rb

@@ -0,0 +1,84 @@
+
+module UCB
+  module LDAP
+    # = UCB::LDAP::Affiliation
+    # 
+    # This class models a persons affiliate entries in the UCB LDAP directory.
+    #
+    #   affiliations = Affiliation.find_by_uid("1234")  #=> [#<UCB::LDAP::Affiliation: ...>, ...]
+    #
+    # Affiliation are usually loaded through a Person instance:
+    #
+    #   p = Person.find_by_uid("1234")    #=> #<UCB::LDAP::Person: ...>
+    #   affs = p.affiliations        #=> [#<UCB::LDAP::Affiliation: ...>, ...]
+    #
+    # == Note on Binds
+    # 
+    # You must have a privileged bind and pass your credentials to UCB::LDAP.authenticate()
+    # before performing your Affiliation search.
+    #
+    class Affiliation < Entry
+      @entity_name = 'personAffiliateAffiliation'
+
+      def create_datetime
+        berkeleyEduAffCreateDate
+      end
+      
+      def expired_by
+        berkeleyEduAffExpBy
+      end
+      
+      def expiration_date
+         UCB::LDAP.local_date_parse(berkeleyEduAffExpDate)
+      end
+      
+      def affiliate_id
+        berkeleyEduAffID.first
+      end
+      
+      def affiliate_type
+        berkeleyEduAffType
+      end
+
+      def first_name
+        givenName.first
+      end
+      
+      def middle_name
+        berkeleyEduMiddleName
+      end
+      
+      def last_name
+        sn.first
+      end
+      
+      def modified_by
+        berkeleyEduModifiedBy
+      end
+      
+      def source
+        berkeleyEduPersonAffiliateSource
+      end
+      
+      def dept_code
+        departmentNumber.first
+      end
+      
+      def dept_name
+        berkeleyEduUnitCalNetDeptName
+      end
+      
+      class << self
+        # Returns an Array of Affiliation for <tt>uid</tt>.
+        # Returns an empty Array ([]) if nothing is found.  
+        #
+        def find_by_uid(uid)
+          base = "uid=#{uid},ou=people,dc=berkeley,dc=edu"
+          filter = Net::LDAP::Filter.eq("objectclass", 'berkeleyEduPersonAffiliate')
+          search(:base => base, :filter => filter)
+        end
+         
+      end
+    end
+  end
+end

data/lib/ucb_ldap_entry.rb

@@ -0,0 +1,398 @@
+
+module UCB
+  module LDAP
+    # = UCB::LDAP::Entry
+    # 
+    # Abstract class representing an entry in the UCB LDAP directory.  You
+    # won't ever deal with Entry instances, but instead instances of Entry
+    # sub-classes.
+    # 
+    # == Accessing LDAP Attributes
+    # 
+    # You will not see the attributes documented in the
+    # instance method section of the documentation for Entry sub-classes,
+    # even though you can access them as
+    # if they _were_ instance methods.
+    #
+    #   person = Person.find_by_uid("123")  #=> #<UCB::LDAP::Person ..>
+    #   people.givenname                    #=> ["John"]
+    #   
+    # Entry sub-classes may have convenience methods that
+    # allow for accessing attributes by friendly names:
+    # 
+    #   person = Person.person_by_uid("123")  #=> #<UCB::LDAP::Person ..>
+    #   person.firstname                      #=> "John"
+    #
+    # See the sub-class documentation for specifics.
+    # 
+    # ===Single- / Multi-Value Attributes
+    #
+    # Attribute values are returned as arrays or scalars based on how 
+    # they are defined in the LDAP schema.  
+    #
+    # Entry subclasses may have convenience
+    # methods that return scalars even though the schema defines
+    # the unerlying attribute as multi-valued becuase in practice they are single-valued.
+    # 
+    # === Attribute Types
+    # 
+    # Attribute values are stored as arrays of strings in LDAP, but 
+    # when accessed through Entry sub-class methods are returned
+    # cast to their Ruby type as defined in the schema.  Types are one of:
+    #
+    # * string
+    # * integer
+    # * boolean
+    # * datetime
+    #
+    # === Missing Attribute Values
+    # 
+    # If an attribute value is not present, the value returned depends on
+    # type and multi/single value field:
+    #
+    # * empty multi-valued attributes return an empty array ([])
+    # * empty booleans return +false+
+    # * everything else returns +nil+ if empty
+    #
+    # Attempting to get or set an attribute value for an invalid attriubte name
+    # will raise a BadAttributeNameException.
+    #
+    # == Updating LDAP
+    #
+    # If your bind has privleges for updating the directory you can update
+    # the directory using methods of Entry sub-classes.  Make sure you call
+    # UCB::LDAP.authenticate before calling any update methods.
+    #
+    # There are three pairs of update methods that behave like Rails ActiveRecord
+    # methods of the same name.  These methods are fairly thin wrappers around
+    # standard LDAP update commands.
+    #
+    # The "bang" methods (those ending in "!") differ from their bangless 
+    # counterparts in that the bang methods raise +DirectoryNotUpdatedException+
+    # on failure, while the bangless return +false+.
+    #
+    # * #create/#create! - class methods that do LDAP add
+    # * #update_attributes/#update_attributes! - instance methods that do LDAP modify
+    # * #delete/#delete! - instance methods that do LDAP delete
+    #
+    class Entry
+
+      # Returns new instance of UCB::LDAP::Entry.  The argument
+      # net_ldap_entry is an instance of Net::LDAP::Entry.
+      # 
+      # You should not need to create any UCB::LDAP::Entry instances;
+      # they are created by calls to UCB::LDAP.search and friends.
+      def initialize(dn = nil) #:nodoc:
+        @new_record = true
+        @attributes = {}
+        @tainted_attributes = {}
+      end
+      
+      def new_record?
+        @new_record
+      end
+      
+      # Hydrates (populates) the object with values from the ldap resultset.      
+      def self.hydrate(net_ldap_entry)
+        new_ldap_entry = self.new
+        new_ldap_entry.instance_variable_set(:@new_record, false)
+        # Don't store Net::LDAP entry in object since it uses the block
+        # initialization method of Hash which can't be marshalled ... this 
+        # means it can't be stored in a Rails session.
+        net_ldap_entry.each do |attr, value|
+          new_ldap_entry.attributes[canonical(attr)] = value.map{|v| v.dup}
+        end
+        new_ldap_entry
+      end
+    
+      def tainted_attributes
+        @tainted_attributes
+      end
+    
+      # <tt>Hash</tt> of attributes returned from underlying NET::LDAP::Entry
+      # instance.  Hash keys are #canonical attribute names, hash values are attribute
+      # values <em>as returned from LDAP</em>, i.e. arrays.
+      # 
+      # You should most likely be referencing attributes as if they were
+      # instance methods rather than directly through this method.  See top of
+      # this document.
+      def attributes
+        @attributes
+      end
+    
+      # returns the value of the <em>distinguished name</em> attribute.
+      def dn
+        attributes[canonical(:dn)]
+      end
+    
+      def canonical(string_or_symbol) #:nodoc:
+        self.class.canonical(string_or_symbol)
+      end
+    
+      # update an existing entry.  returns entry if successful else false.
+      #
+      #   attrs = {:attr1 => "new_v1", :attr2 => "new_v2"}
+      #   entry.update_attributes(attrs)
+      #
+      def update_attributes(attrs)
+        attrs.each {|k, v| self.send("#{k}=", v)}        
+        if modify()
+          @attributes = self.class.find_by_dn(dn).attributes.dup
+          return true
+        end
+        false
+      end
+      
+      # same as #update_attributes(), but raises directorynotupdated on failure. 
+      def update_attributes!(attrs)
+        update_attributes(attrs) || raise(directorynotupdatedexception)
+      end
+      
+      # delete entry.  returns +true+ on sucess, +false+ on failure.
+      def delete
+        net_ldap.delete(:dn => dn)
+      end
+      
+      # same as #delete() except raises directorynotupdated on failure.
+      def delete!
+        delete || raise(directorynotupdatedexception)
+      end
+      
+      def net_ldap
+        self.class.net_ldap
+      end
+      
+      
+      private unless $testing
+
+      # used to get/set attribute values.
+      #
+      # if we can't make an attribute name out of method, let
+      # regular method_missing() handle it.
+      def method_missing(method, *args) #:nodoc:
+        setter_method?(method) ? value_setter(method, *args) : value_getter(method)
+      rescue BadAttributeNameException
+        return super
+      end
+      
+      # returns +true+ if _method_ is a "setter", i.e., ends in "=".
+      def setter_method?(method)
+        method.to_s[-1, 1] == "="
+      end
+
+      # called by method_missing() to get an attribute value. 
+      def value_getter(method)
+        schema_attribute = self.class.schema_attribute(method)
+        raw_value = attributes[canonical(schema_attribute.name)]
+        schema_attribute.get_value(raw_value)
+      end
+    
+      # called by method_missing() to set an attribute value.    
+      def value_setter(method, *args)
+        schema_attribute = self.class.schema_attribute(method.to_s.chop)
+        attr_key = canonical(schema_attribute.name)
+        tainted_attributes[attr_key] = schema_attribute.ldap_value(args[0])
+      end
+    
+      def modify_operations
+        ops = []
+        tainted_attributes.keys.sort_by{|k| k.to_s}.each do |key|
+          value = tainted_attributes[key]
+          op = value.nil? ? :delete : :replace
+          ops << [op, key, value]
+        end
+        ops
+      end
+    
+      def modify()
+        if ucb::ldap.net_ldap.modify(:dn => dn, :operations => modify_operations)
+          @tainted_attributes = nil
+          return true
+        end
+        false
+      end
+
+      # class methods
+      class << self
+        
+        public
+        
+        # creates and returns new entry.  returns +false+ if unsuccessful.
+        # sets :objectclass key of <em>args[:attributes]</em> to 
+        # object_classes read from schema.
+        #
+        #   dn = "uid=999999,ou=people,dc=example,dc=com"
+        #   attr = {
+        #     :uid => "999999",
+        #     :mail => "gsmith@example.com"
+        #   }
+        #   
+        #   entrysubclass.create(:dn => dn, :attributes => attr)  #=> #<ucb::ldap::entrysubclass ..>
+        #
+        # caller is responsible for setting :dn and :attributes correctly,
+        # as well as any other validation.
+        #
+        def create(args)
+          args[:attributes][:objectclass] = object_classes
+          net_ldap.add(args) or return false
+
+          # why is the object being refetched from ldap here?
+          find_by_dn(args[:dn])
+        end
+        
+        def required_attributes
+          schema_attributes_hash.delete_if {|key, value| value["required"] == false }.keys
+        end
+        
+        # returns entry whose distinguised name is _dn_.
+        def find_by_dn(dn)
+          search(
+            :base => dn,
+            :scope => Net::LDAP::SearchScope_BaseObject,
+            :filter => "objectClass=*"
+          ).first
+        end
+        
+        # Same as #create(), but raises DirectoryNotUpdated on failure.
+        def create!(args)
+          create(args) || raise(DirectoryNotUpdatedException)          
+        end
+        
+        # Returns a new Net::LDAP::Filter that is the result of combining
+        # <em>filters</em> using <em>operator</em> (<em>filters</em> is 
+        # an +Array+ of Net::LDAP::Filter).
+        #
+        # See Net::LDAP#& and Net::LDAP#| for details.
+        #
+        #   f1 = Net::LDAP::Filter.eq("lastname", "hansen")
+        #   f2 = Net::LDAP::Filter.eq("firstname", "steven")
+        #   
+        #   combine_filters([f1, f2])      # same as: f1 & f2
+        #   combine_filters([f1, f2], '|') # same as: f1 | f2
+        #
+        def combine_filters(filters, operator = '&')
+          filters.inject{|accum, filter| accum.send(operator, filter)}
+        end
+
+        # Returns Net::LDAP::Filter.  Allows for <em>filter</em> to
+        # be a +Hash+ of :key => value.  Filters are combined with "&".
+        #
+        #   UCB::LDAP::Entry.make_search_filter(:uid => '123') 
+        #   UCB::LDAP::Entry.make_search_filter(:a1 => v1, :a2 => v2)
+        #
+        def make_search_filter(filter)
+          return filter if filter.instance_of?  Net::LDAP::Filter
+          return filter if filter.instance_of?  String
+          
+          filters = []
+          # sort so result is predictable for unit test
+          filter.keys.sort_by { |symbol| "#{symbol}" }.each do |attr|
+            filters << Net::LDAP::Filter.eq("#{attr}", "#{filter[attr]}")
+          end
+          combine_filters(filters, "&")
+        end
+      
+        # Returns +Array+ of object classes making up this type of LDAP entity.
+        def object_classes
+          @object_classes ||= UCB::LDAP::Schema.schema_hash[entity_name]["objectClasses"]
+        end
+        
+        def unique_object_class
+          @unique_object_class ||= UCB::LDAP::Schema.schema_hash[entity_name]["uniqueObjectClass"]
+        end
+        
+        # Returns an +Array+ of Schema::Attribute for the entity.
+        def schema_attributes_array
+          @schema_attributes_array || set_schema_attributes
+          @schema_attributes_array
+        end
+        
+        # Returns as +Hash+ whose keys are the canonical attribute names
+        # and whose values are the corresponding Schema::Attributes.
+        def schema_attributes_hash
+          @schema_attributes_hash || set_schema_attributes
+          @schema_attributes_hash
+        end
+        
+        def schema_attribute(attribute_name)
+          schema_attributes_hash[canonical(attribute_name)] ||
+            raise(BadAttributeNameException, "'#{attribute_name}' is not a recognized attribute name")
+        end
+        
+        # Returns Array of UCB::LDAP::Entry for entries matching _args_.
+        # When called from a subclass, returns Array of subclass instances.
+        #
+        # See Net::LDAP::search for more information on _args_.
+        #
+        # Most common arguments are <tt>:base</tt> and <tt>:filter</tt>.
+        # Search methods of subclasses have default <tt>:base</tt> that
+        # can be overriden.
+        # 
+        # See make_search_filter for <tt>:filter</tt> options.
+        # 
+        #   base = "ou=people,dc=berkeley,dc=edu"
+        #   entries = UCB::LDAP::Entry.search(:base => base, :filter => {:uid => '123'})
+        #   entries = UCB::LDAP::Entry.search(:base => base, :filter => {:sn => 'Doe', :givenname => 'John'}
+        #
+        def search(args={})
+          args = args.dup
+          args[:base] ||= tree_base
+          args[:filter] = make_search_filter args[:filter] if args[:filter]
+          
+          results = []
+          net_ldap.search(args) do |entry|
+            results << hydrate(entry)
+          end
+          results
+        end
+  
+        # Returns the canonical representation of a symbol or string so
+        # we can look up attributes in a number of ways.
+        def canonical(string_or_symbol)
+          string_or_symbol.to_s.downcase.to_sym
+        end
+   
+        # Returns underlying Net::LDAP instance.
+        def net_ldap #:nodoc:
+          UCB::LDAP.net_ldap
+        end
+
+        private unless $TESTING
+
+        # Schema entity name.  Set in each subclass.
+        def entity_name
+          @entity_name
+        end
+                                
+        # Want an array of Schema::Attributes as well as a hash
+        # of all possible variations on a name pointing to correct array element.
+        def set_schema_attributes
+          @schema_attributes_array = []
+          @schema_attributes_hash = {}
+          UCB::LDAP::Schema.schema_hash[entity_name]["attributes"].each do |k, v|
+            sa = UCB::LDAP::Schema::Attribute.new(v.merge("name" => k))
+            @schema_attributes_array << sa
+            [sa.name, sa.aliases].flatten.each do |name|
+              @schema_attributes_hash[canonical(name)] = sa
+            end
+          end
+        rescue
+          raise "Error loading schema attributes for entity_name '#{entity_name}'"
+        end
+        
+        # Returns tree base for LDAP searches.  Subclasses each have
+        # their own value.
+        # 
+        # Can be overridden in #search by passing in a <tt>:base</tt> parm.
+        def tree_base
+          @tree_base
+        end
+        
+        def tree_base=(tree_base)
+          @tree_base = tree_base
+        end
+        
+      end  # end of class methods
+    end
+  end 
+end