ucb_ldap 1.3.2 → 1.4.2

data/CHANGELOG

@@ -1,5 +1,10 @@
 = UCB::LDAP Changelog
 
+== Version 1.4.1
+* Remove hack that tried to persist the net-ldap connection instance as this cause problems
+with leaving countless file descriptors open when run under JRuby.
+* Updated bundled schema.yml file
+
 == Version 1.2.1, January 22, 2008
 
 * fixed bug: include UCB::LDAP call at top level that corrupted namespace

data/Manifest

@@ -3,7 +3,6 @@ Manifest
 README
 Rakefile
 TODO
-init.rb
 lib/person/adv_con_person.rb
 lib/person/affiliation_methods.rb
 lib/person/generic_attributes.rb
@@ -21,4 +20,5 @@ lib/ucb_ldap_schema_attribute.rb
 lib/ucb_ldap_service.rb
 lib/ucb_ldap_student_term.rb
 schema/schema.yml
+ucb_ldap.gemspec
 version.yml

data/README

@@ -5,7 +5,7 @@ LDAP directory: http://directory.berkeley.edu
 
 ==Introduction to LDAP
 If you are blissfully ignorant of LDAP, you should familiarize yourself with some of the basics.
-Here is a great online resource: http://www.zytrax.com/books/ldap.
+Here is a great online resource: http://www.zytrax.com/books/ldap
 
 The RDoc for the ruby-net-ldap Gem (http://rubyfurnace.com/docs/ruby-net-ldap-0.0.4/classes/Net/LDAP.html) also has a good introduction to LDAP. 
 
@@ -29,7 +29,7 @@ See UCB::LDAP::Entry for more information.
 
 Search the Person tree getting back UCB::LDAP::Person instances:
 
-  person = UCB::LDAP::Person.person_by_uid "123"
+  person = UCB::LDAP::Person.find_by_uid("123")
   
   person.firstname           #=> "John"
   person.affiliations        #=> ['EMPLOYEE-TYPE-STAFF']
@@ -56,11 +56,11 @@ See UCB::LDAP::Org for more information.
 If you want access the directory anonomously, no credentials are required.
 If you want to access via a privileged bind, authenticate before querying:
 
-  p = UCB::LDAP::Person.person_by_uid("123")
+  p = UCB::LDAP::Person.find_by_uid("123")
   p.non_public_attr    #=> NoMethodError
   
   UCB::LDAP.authenticate("mybind", "mypassword")
-  p = UCB::LDAP::Person.person_by_uid("123")
+  p = UCB::LDAP::Person.find_by_uid("123")
   p.non_public_attr    #=> "some value"
   
 === Privileged Binds and Rails
@@ -70,7 +70,7 @@ See UCB::LDAP.bind_for_rails()
 ==Dependencies
 
 * Net::LDAP
-* Ruby 1.8.2 or better
+* Ruby 1.8.5 or better
 
 ==Authors
 

data/Rakefile

@@ -3,14 +3,14 @@ require 'rake'
 require 'echoe'
 require 'hanna/rdoctask'
 
-Echoe.new('ucb_ldap', '1.3.2') do |p|
+Echoe.new('ucb_ldap', '1.4.2') do |p|
   p.description    = "Convenience classes for interacing with UCB's LDAP directory"
   p.url            = "http://ucbrb.rubyforge.org/ucb_ldap"
   p.author         = "Steven Hansen, Steve Downey, Lucas Rockwell"
   p.email          = "runner@berkeley.edu"
   p.ignore_pattern = ["svn_user.yml", "tasks/ucb_ldap.rake", "spec/**/**", "test/**/**"]
   p.project = "ucbrb"
-  p.runtime_dependencies = ["ruby-net-ldap >= 0.0.4"]
+  p.runtime_dependencies = ["ruby-net-ldap >=0.0.4"]
   p.rdoc_options = "-o doc --inline-source -T hanna lib/*.rb"
   p.rdoc_pattern = ["README", "lib/**/**"]
 end

data/TODO

@@ -1,2 +1,2 @@
-= TODO List for UCB::LDAP
+* Make thread safe, mutex around search?
 

data/lib/person/affiliation_methods.rb

@@ -2,25 +2,31 @@
 
 module UCB::LDAP
     module AffiliationMethods
-
-      # Returns an <tt>Array</tt> of Person's affiliations.    
+      
+      ##
+      # Returns an <tt>Array</tt> of Person's affiliations.
+      #
       def affiliations
         @affiliations ||= berkeleyEduAffiliations.map { |a| a.upcase }
       end
-
+      
+      ##
       # Returns <tt>true</tt> if entry's affiliations contain _affiliation_.
       # 
       # Case-insensitive.
+      #
       def has_affiliation?(affiliation)
         affiliations.include?(affiliation.upcase)
       end
-
+      
+      ##
       # Returns <tt>true</tt> if Person's affiliations contain at least one affiliation of a particular type.
       #
       #   p = Person.find_by_uid ...
       #   p.affiliations                         #=> ['EMPLOYEE-TYPE-STAFF']
       #   p.has_affiliation_of_type?(:employee)  #=> true
       #   p.has_affiliation_of_type?(:student)   #=> false
+      #
       def has_affiliation_of_type?(affiliation_type)
         aff_type_string = affiliation_type.to_s.upcase
         affiliations.find{|a| a =~ /^#{aff_type_string}-TYPE-/} ? true : false
@@ -30,8 +36,10 @@ module UCB::LDAP
       ############################################
       #  Determine if the person is an EMPLOYEE  #
       ############################################
-
+      
+      ##
       # Returns <tt>true</tt> if entry has the "staff" affiliation.
+      #
       def employee_staff?
         has_affiliation? 'EMPLOYEE-TYPE-STAFF'
       end
@@ -56,8 +64,10 @@ module UCB::LDAP
       ##########################################
       #  Determine if the person is a STUDENT  #
       ##########################################
-
+      
+      ##
       # Returns +true+ if is an expired student.
+      #
       def student_expired?
         has_affiliation? 'STUDENT-STATUS-EXPIRED'
       end
@@ -73,9 +83,11 @@ module UCB::LDAP
       def student_not_registered?
         has_affiliation? 'STUDENT-TYPE-NOT REGISTERED'
       end
-
+      
+      ##
       # Returns <tt>true</tt> if entry has a studend affiliation and
       # is not expired.
+      #
       def student?
         has_affiliation_of_type?(:student) && !student_expired?
       end
@@ -100,9 +112,11 @@ module UCB::LDAP
       def affiliate_directory_only?
         has_affiliation? 'AFFILIATE-TYPE-DIRECTORY ONLY'
       end
-
+      
+      ##
       # Note: there are actually 2 types of visting affiliaties, visiting student and 
       # visiting scholars.  But for now we will generalize.
+      #
       def affiliate_visiting?
         has_affiliation? 'AFFILIATE-TYPE-VISITING'
       end
@@ -209,4 +223,3 @@ module UCB::LDAP
     
   end 
 end
-    

data/lib/ucb_ldap.rb

@@ -1,4 +1,3 @@
-#
 require 'rubygems'
 require 'net/ldap'
 require 'time'
@@ -19,8 +18,8 @@ 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
@@ -37,29 +36,34 @@ module UCB #:nodoc:
 
     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()
+        new_net_ldap() # to force bind()
       end
-
+      
+      ##
       # Removes current bind (username, password).
-      def clear_authentication
+      #
+      def clear_authentication()
         authenticate(nil, nil)
       end
-      
+
+      ##
       # Returns LDAP host used for lookups.  Default is HOST_PRODUCTION.
-      def host
+      #
+      def host()
         @host || HOST_PRODUCTION
       end
-  
+      
+      ##
       # Setter for #host.
       # 
       # Note: validation of host is deferred until a search is performed
@@ -67,13 +71,15 @@ module UCB #:nodoc:
       # 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.
       #
@@ -81,19 +87,21 @@ module UCB #:nodoc:
       # 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
-        connection_open? ? @net_ldap : new_net_ldap
+      # are prepared to handle timed-out connections (which this method does).
+      #
+      def net_ldap()
+        @net_ldap ||= new_net_ldap
       end
 
-      def password #:nodoc:
+      def password() #:nodoc:
         @password
       end
       
-      def username #:nodoc:
+      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.
       #
@@ -113,6 +121,7 @@ module UCB #:nodoc:
       # 
       # 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
@@ -123,85 +132,73 @@ module UCB #:nodoc:
         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
+      #
+      def authentication_information()
         password.nil? ? 
           {:method => :anonymous} : 
           {:method => :simple, :username => username, :password => password}
       end
-      
-      # Returns +true+ if we have a Net::LDAP instance with an open
-      # connection.
-      def connection_open?
-        @net_ldap.nil? ? false : ldap_ping
-      rescue
-        false
-      end
-      
+
+      ##
       # Returns +true+ if connection simple search works.
-      def ldap_ping
+      #
+      def ldap_ping()
         search_attrs = {
           :base => "",
           :scope => Net::LDAP::SearchScope_BaseObject,
           :attributes => [1.1]
         }
         result = false
-        @net_ldap.search(search_attrs){result = true}
+        @net_ldap.search(search_attrs) { result = true }
         result
       end
-      
-      # Returns new Net::LDAP instance.  Also
-      # reaches into the Net::LDAP to set the @open_connection instance
-      # variable.
+
+      ##
+      # Returns new Net::LDAP instance.
       #
-      # Warning: this seems to be contrary to the Net::LDAP author's
-      # intent and may break with future versions of Net::LDAP.
       def new_net_ldap()
-        @net_ldap = Net::LDAP.new(
+        params = {
           :host => host,
           :auth => authentication_information,
           :port => 636, 
           :encryption => {:method =>:simple_tls}
-          )
-        @net_ldap.instance_variable_set(:@open_connection, new_net_ldap_connection)
+        }
+        @net_ldap = Net::LDAP.new(params)
         @net_ldap.bind || raise(BindFailedException)
         @net_ldap
+      rescue Net::LDAP::LdapError => e
+        raise(BindFailedException)
       end
-      
-      # Return a new Net::LDAP::Connection
-      def new_net_ldap_connection
-        Net::LDAP::Connection.new(
-          :host => host,
-          :port => 636,
-          :encryption => {:method => :simple_tls}
-        )
-      rescue Net::LDAP::LdapError
-        raise UCB::LDAP::ConnectionFailedException
-      end
-  
+
+      ##
       # Used for testing
-      def clear_instance_variables
+      #
+      def clear_instance_variables()
         @host = nil
         @net_ldap = nil
         @username = nil
         @password = nil
       end
-      
     end
-    
- end
+  end
 end
 

data/lib/ucb_ldap_entry.rb

@@ -1,5 +1,6 @@
 module UCB
   module LDAP
+    ##
     # = UCB::LDAP::Entry
     # 
     # Abstract class representing an entry in the UCB LDAP directory.  You
@@ -75,12 +76,14 @@ module UCB
     # * #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(net_ldap_entry) #:nodoc:
         # Don't store Net::LDAP entry in object since it uses the block
         # initialization method of Hash which can't be marshalled ... this 
@@ -90,7 +93,8 @@ module UCB
           @attributes[canonical(attr)] = value.map{|v| v.dup}
         end
       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.
@@ -98,11 +102,14 @@ module UCB
       # 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
@@ -110,7 +117,8 @@ module UCB
       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"}
@@ -124,18 +132,24 @@ module UCB
         end
         false
       end
-      
-      # Same as #update_attributes(), but raises DirectoryNotUpdated on failure. 
+
+      ##
+      # 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
@@ -146,30 +160,38 @@ module UCB
       
       
       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. 
+      
+      ##
+      # 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.    
+      
+      ##
+      # 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)
@@ -220,10 +242,12 @@ module UCB
         #
         def create(args)
           args[:attributes][:objectclass] = object_classes
-          net_ldap.add(args) or return false
+          result = net_ldap.add(args)
+          result or return false
           find_by_dn(args[:dn])
         end
-
+        
+        ##
         # Returns entry whose distinguised name is _dn_.
         def find_by_dn(dn)
           search(
@@ -232,12 +256,14 @@ module UCB
             :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).
@@ -253,7 +279,8 @@ module UCB
         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 "&".
         #
@@ -271,7 +298,8 @@ module UCB
           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"]
@@ -281,14 +309,45 @@ module UCB
           @unique_object_class ||= UCB::LDAP::Schema.schema_hash[entity_name]["uniqueObjectClass"]
         end
         
+        ##
+        # returns an Array of symbols where each symbol is the name of
+        # a required attribute for the Entry
+        def required_attributes
+          required_schema_attributes.keys
+        end
+        
+        ##
+        # returns Hash of SchemaAttribute objects that are required
+        # for the Entry.  Each SchemaAttribute object is keyed to the
+        # attribute's name.
+        #
+        # Note: required_schema_attributes will not return aliases, it
+        # only returns the original attributes
+        #
+        # Example:
+        #  Person.required_schema_attribues[:cn]
+        #  => <UCB::LDAP::Schema::Attribute:0x11c6b68>
+        #
+        def required_schema_attributes
+          required_atts = schema_attributes_hash.reject { |key, value| !value.required? }
+          required_atts.reject do |key, value|
+            aliases = value.aliases.map { |a| canonical(a) }
+            aliases.include?(key)
+          end
+        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
@@ -298,7 +357,8 @@ module UCB
           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.
         #
@@ -325,27 +385,35 @@ module UCB
           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 = {}
@@ -360,10 +428,12 @@ module UCB
           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