ucb_ldap 1.3.0

data/CHANGELOG

@@ -0,0 +1,127 @@
+= UCB::LDAP Changelog
+
+== Version 1.2.1, January 22, 2008
+
+* fixed bug: include UCB::LDAP call at top level that corrupted namespace
+* fixed rspec tests to use production ldap server to verify Org structure
+
+
+== Version 1.2.0, September 20, 2007
+
+* fixed UCB::LDAP::Person.student_not_registered? which was broken
+* added support for new entities
+  * Affiliation
+  * Service
+  * StudentTerm
+* added handling of timestamp attributes
+* various additions and clean-up to the various employee_*, student_*, affiliate_* methods 
+  including handling of expiration
+* fetches schema from url rather than file packaged with gem
+* made UCB::LDAP::Person searches exclude test entries by default
+* Rails applications can use UCB::LDAP.bind_for_rails() to get environment-specific binds
+
+== Version 1.1.1, August 2, 2007
+
+* fixed bug around deleting LDAP entries.
+
+== Version 1.1.0, August 1, 2007
+
+* added Org#level_<n>_code and Org#level_<n>_name where <n> is 1-6.  Returns the
+  org node's level "n" code/name
+* added option to Org.flattened_tree() to restrict levels returned.
+
+== Version 1.0.1, July 25, 2007
+
+* do a better job trapping dropped connections in UCB::LDAP.connection_open?
+* added Person#test? to check for test entries
+
+== Version 1.0.0
+
+* got complete schema info for attributes
+* replaced attribute synonyms in favor of explicit methods
+* added support for ldap updates
+* added support for new entities (if your bind supports it):
+  * appointment
+  * address
+
+== Version 0.8.1, May 18, 2007
+
+* added Person#dept_org (synonym for Person#deptid)
+* added Person#dept_name
+
+== Version 0.8.0, April 27, 2007
+
+* added support for privileged binds via UCB::LDAP::authenticate()
+
+== Version 0.7.0, January 16, 2007
+
+* updated: UCB::LDAP::Entry.search to use Net::LDAP::Filter objects: this fixed the
+   problem with embedded whitespace
+* updated UCB::LDAP::Person.person_by_uid() to work with an Integer or a String
+   and UCB::LDAP::Person.persons_by_uids() to work with an Array of Integers or Strings.
+* updated: UCB::LDAP::Person.student? to utilize the new LDAP v2 ou structure
+* added: UCB::LDAP::Person.student_registered?, UCB::LDAP::Person.student_not_registered?
+* deprecated: UCB::LDAP::Person.student_summer?, UCB::LDAP::Person.student_summer_only?,
+   UCB::LDAP::Person.spring?, UCB::LDAP::Person.fall?. Except for UCB::LDAP::Person.student_summer_only?,
+   these methods may be added in later versions of UCB::LDAP::Person.  Note: accessing these 
+   attributes will required a privileged bind.
+ * changed UCB::LDAP::Entry to only allow filter options in hash form: :filter => {:uid => 12345}
+ * updated documentations
+ * updated unit tests. 
+
+== Version 0.6.0, January 10, 2007
+
+* Added loading/caching of all nodes
+* Added calculation of all child nodes
+* Added UCB::LDAP::Org.flattened_tree()
+* Added UCB::LDAP::Person.org_node()
+
+== Version 0.5.0, December 20, 2006
+
+* Added following methods to Org:
+  * child_nodes
+  * parent_node
+  * parent_nodes
+  * persons
+  
+== Version 0.4.0, December 14, 2006
+
+* Added Person.persons_by_uids to return array of Person for given
+  array of uids.
+* Changed implementation of Person.person_by_uid to use new Person.persons_by_uid.
+
+== Version 0.3.1, December 13, 2006
+
+* Added SchemaAttribute class and methods to load schema
+  attributes in UCB::LDAP.  Did not make use of the schema
+  attributes.
+  
+== Version 0.3.0, October 20, 2006
+
+* Moved to SVN
+* Reorganized doc directory
+
+== Version 0.2.2, October 12, 2006
+
+* Made more "booleans" actually return <tt>true</tt> and <tt>false</tt>
+  rather than expressions that evaluate to <tt>true</tt> and <tt>false</tt>.
+  
+* Added TODO[link:files/TODO.html].
+
+* Some documentation updates.  
+
+== Version 0.2.1, October 10, 2006
+
+* Changed module name and namespace from UcbLdap to UCB::LDAP.
+* Fixed so UCB::LDAP::Entry and subclasses can be marshalled,
+  otherwise can't store in a Rails session.
+
+== Version 0.2.0, October 9, 2006
+
+* Packaged as a Ruby Gem.
+* Converted underlying code to use Net::LDAP instead of LDAP.
+* Added support for searching the org unit tree.
+
+== Version 0.1.0, October 5, 2006
+
+* Initial release.

data/Manifest

@@ -0,0 +1,25 @@
+CHANGELOG
+Manifest
+README
+Rakefile
+TODO
+init.rb
+lib/person/adv_con_person.rb
+lib/person/affiliation_methods.rb
+lib/person/generic_attributes.rb
+lib/ucb_ldap.rb
+lib/ucb_ldap_address.rb
+lib/ucb_ldap_affiliation.rb
+lib/ucb_ldap_entry.rb
+lib/ucb_ldap_exceptions.rb
+lib/ucb_ldap_namespace.rb
+lib/ucb_ldap_org.rb
+lib/ucb_ldap_person.rb
+lib/ucb_ldap_person_job_appointment.rb
+lib/ucb_ldap_schema.rb
+lib/ucb_ldap_schema_attribute.rb
+lib/ucb_ldap_service.rb
+lib/ucb_ldap_student_term.rb
+lib/ucb_simple_ldap_entry.rb
+schema/schema.yml
+version.yml

data/README

@@ -0,0 +1,80 @@
+=UC Berkeley LDAP
+
+UCB::LDAP is a wrapper module around Net::LDAP intended to simplify searching the UC Berkeley 
+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.
+
+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. 
+
+
+==Examples
+
+===General Search
+
+Search the directory specifying tree base and
+filter, getting back generic UCB::LDAP::Entry instances:
+
+  entries = UCB::LDAP.search(:base => "ou=people,dc=berkeley,dc=edu", :filter => {:uid => 123}
+
+  entry.uid             #=> '123'
+  entry.givenname       #=> 'John'
+  entry.sn              #=> 'Doe'
+
+See UCB::LDAP::Entry for more information.
+
+===Person Search
+
+Search the Person tree getting back UCB::LDAP::Person instances:
+
+  person = UCB::LDAP::Person.person_by_uid "123"
+  
+  person.firstname           #=> "John"
+  person.affiliations        #=> ['EMPLOYEE-TYPE-STAFF']
+  person.employee?           #=> true
+  person.employee_staff?     #=> true
+  person.employee_academic?  #=> false
+  person.student?            #=> false
+
+See UCB::LDAP::Person for more information.
+
+===Org Unit Search
+
+Search the Org Unit tree getting back UCB::LDAP::Org instances:
+
+  dept = UCB::LDAP::Org.org_by_ou 'jkasd'
+  
+  dept.deptid         #=> "JKASD"
+  dept.name           #=> "Administrative Systems Dept"
+
+See UCB::LDAP::Org for more information.
+
+===Privileged Binds
+
+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.non_public_attr    #=> NoMethodError
+  
+  UCB::LDAP.authenticate("mybind", "mypassword")
+  p = UCB::LDAP::Person.person_by_uid("123")
+  p.non_public_attr    #=> "some value"
+  
+=== Privileged Binds and Rails
+
+See UCB::LDAP.bind_for_rails()
+
+==Dependencies
+
+* Net::LDAP
+* Ruby 1.8.2 or better
+
+==Authors
+
+Steven Hansen runner@berkeley.edu
+Lucas Rockwell
+Steve Downey
+

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+require 'hanna/rdoctask'
+
+Echoe.new('ucb_ldap', '1.3.0') 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.rdoc_options = "-o doc --inline-source -T hanna lib/*.rb"
+  p.rdoc_pattern = ["README", "lib/**/**"]
+end
+ 
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }
+
+
+
+

data/TODO

@@ -0,0 +1,2 @@
+= TODO List for UCB::LDAP
+

data/init.rb

@@ -0,0 +1 @@
+require 'ucb_ldap'

data/lib/person/affiliation_methods.rb

@@ -0,0 +1,212 @@
+
+
+module UCB::LDAP
+    module AffiliationMethods
+
+      # 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
+      end
+
+
+      ############################################
+      #  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
+
+      def employee_academic?
+        has_affiliation? 'EMPLOYEE-TYPE-ACADEMIC'
+      end
+
+      def employee_expired?
+        has_affiliation? 'EMPLOYEE-STATUS-EXPIRED'
+      end
+
+      def employee_expiration_date
+        Date.parse(berkeleyEduEmpExpDate.to_s)
+      end
+
+      def employee?
+        has_affiliation_of_type?(:employee) && !employee_expired?
+      end
+
+     
+      ##########################################
+      #  Determine if the person is a STUDENT  #
+      ##########################################
+
+      # Returns +true+ if is an expired student.
+      def student_expired?
+        has_affiliation? 'STUDENT-STATUS-EXPIRED'
+      end
+
+      def student_expiration_date
+        Date.parse(berkeleyEduStuExpDate.to_s)
+      end
+
+      def student_registered?
+        has_affiliation? 'STUDENT-TYPE-REGISTERED'
+      end
+
+      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
+
+
+      ##############################################      
+      #  Determine if the persone is an AFFILIATE  #
+      ##############################################
+
+      def affiliate_aws_only?
+        has_affiliation? 'AFFILIATE-TYPE-AWS ONLY'
+      end
+
+      def affiliate_staff_retiree?
+        has_affiliation? 'AFFILIATE-TYPE-STAFF RETIREE'  
+      end
+
+      def affiliate_emeritus?
+        has_affiliation? 'AFFILIATE-TYPE-EMERITUS'
+      end
+
+      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
+
+      def affiliate_contractor?
+        has_affiliation? 'AFFILIATE-TYPE-CONTRACTOR'
+      end
+
+      def affiliate_lbl_doe_postdoc?
+        has_affiliation? 'AFFILIATE-TYPE-LBL/DOE POSTDOC'
+      end
+
+      def affiliate_lbl_op_staff?
+        has_affiliation? 'AFFILIATE-TYPE-LBLOP STAFF'
+      end
+     
+      def affiliate_committee_member?
+        has_affiliation? 'AFFILIATE-TYPE-COMMITTEE MEMBER'
+      end
+
+      def affiliate_consultant?
+        has_affiliation? 'AFFILIATE-TYPE-CONSULTANT'
+      end
+
+      def affiliate_volunteer?
+        has_affiliation? 'AFFILIATE-TYPE-VOLUNTEER'
+      end
+
+      def affiliate_hhmi_researcher?
+        has_affiliation? 'AFFILIATE-TYPE-HHMI RESEARCHER'
+      end
+     
+      def affiliate_concurrent_enrollment?
+        has_affiliation? 'AFFILIATE-TYPE-CONCURR ENROLL'
+      end
+
+      def affiliate_temp_agency?
+        has_affiliation? 'AFFILIATE-TYPE-TEMP AGENCY'  
+      end
+
+      def affiliate_departmental?
+        has_affiliation? 'AFFILIATE-TYPE-DEPARTMENTAL'
+      end
+
+      def affiliate_test?
+        has_affiliation? 'AFFILIATE-TYPE-TEST'
+      end
+
+      def affiliate_staff_affiliate?
+        has_affiliation? 'AFFILIATE-TYPE-STAFF-AFFILIATE'
+      end
+
+      def affiliate_academic_case_tracking?
+        has_affiliation? 'AFFILIATE-TYPE-ACADEMIC CASE TRACKING'
+      end
+
+      def affiliate_maintenance?
+        has_affiliation? 'AFFILIATE-TYPE-MAINTENANCE'
+      end
+
+      def affiliate_billing_only?
+        has_affiliation? 'AFFILIATE-TYPE-BILLING ONLY'
+      end
+
+      def affiliate_advcon_trustee?
+        has_affiliation? 'AFFILIATE-TYPE-ADVCON-TRUSTEE'
+      end
+
+      def affiliate_advcon_friend?
+        has_affiliation? 'AFFILIATE-TYPE-ADVCON-FRIEND'
+      end
+
+      def affiliate_advcon_alumnus?
+        has_affiliation? 'AFFILIATE-TYPE-ADVCON-ALUMNUS'
+      end
+
+      def affiliate_advcon_caa_member?
+        has_affiliation? 'AFFILIATE-TYPE-ADVCON-CAA-MEMBER'
+      end
+
+      def affiliate_advcon_i_house_resident?
+        has_affiliation? 'AFFILIATE-TYPE-ADVCON-I-HOUSE-RESIDENT'  
+      end
+
+      def affiliate_advcon_student?
+        has_affiliation? 'AFFILIATE-TYPE-ADVCON-STUDENT'
+      end
+
+      def affiliate_advcon_attendee?
+        has_affiliation? 'AFFILIATE-TYPE-ADVCON-ATTENDEE'
+      end
+
+      def affiliate_expired?
+        has_affiliation? 'AFFILIATE-STATUS-EXPIRED'
+      end
+
+      def affiliate?
+        has_affiliation_of_type?(:affiliate) && !affiliate_expired?
+      end
+
+      def affiliate_expiration_date
+        Date.parse(berkeleyEduAffExpDate.to_s)
+      end
+    
+  end 
+end
+