ucb_ldap 1.3.0

data/lib/ucb_ldap_person_job_appointment.rb

@@ -0,0 +1,79 @@
+
+module UCB
+  module LDAP
+    # = UCB::LDAP::JobAppointment
+    # 
+    # This class models a person's job appointment instance in the UCB LDAP directory.
+    #
+    #   appts = JobAppontment.find_by_uid("1234")       #=> [#<UCB::LDAP::JobAppointment: ...>, ...]
+    #
+    # JobAppointments are usually loaded through a Person instance:
+    #
+    #   p = Person.find_by_uid("1234")    #=> #<UCB::LDAP::Person: ...>
+    #   appts = p.job_appointments        #=> [#<UCB::LDAP::JobAppointment: ...>, ...]
+    #
+    # == Note on Binds
+    # 
+    # You must have a privileged bind and pass your credentials to UCB::LDAP.authenticate()
+    # before performing your JobAppointment search.
+    #
+    class JobAppointment < Entry
+      @entity_name = 'personJobAppointment'
+
+      def cto_code
+        berkeleyEduPersonJobApptCTOCode
+      end
+      
+      def deptid
+        berkeleyEduPersonJobApptDepartment
+      end
+      
+      def record_number
+        berkeleyEduPersonJobApptEmpRecNumber.to_i
+      end
+      
+      def personnel_program_code
+        berkeleyEduPersonJobApptPersPgmCode
+      end
+      
+      def primary?
+        berkeleyEduPersonJobApptPrimaryFlag
+      end
+      
+      # Returns Employee Relation Code
+      def erc_code
+        berkeleyEduPersonJobApptRelationsCode
+      end
+      
+      def represented?
+        berkeleyEduPersonJobApptRepresentation != 'U'
+      end
+      
+      def title_code
+        berkeleyEduPersonJobApptTitleCode
+      end
+      
+      def appointment_type
+        berkeleyEduPersonJobApptType
+      end
+      
+      # Returns +true+ if appointment is Without Salary
+      def wos?
+        berkeleyEduPersonJobApptWOS
+      end
+      
+      class << self
+        # Returns an Array of JobAppointment for <tt>uid</tt>, sorted by
+        # record_number().
+        # 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", 'berkeleyEduPersonJobAppt')
+          search(:base => base, :filter => filter).sort_by{|appt| appt.record_number}
+        end
+         
+      end
+    end
+  end
+end

data/lib/ucb_ldap_schema.rb

@@ -0,0 +1,115 @@
+#require 'open-uri'
+#require 'net/http'
+require 'yaml'
+require 'net/https'
+
+module UCB #:nodoc:
+  module LDAP
+    # = UCB::LDAP::Schema
+    #
+    # Class responsible for getting schema information for all of the UCB::LDAP
+    # entities.  Attributes are modeled as instances of UCB::LDAP::Schema::Attribute.
+    #
+    # Each entity (Person, Org, etc.) has a Hash of attributes where the keys are
+    # canonical (see Entry.canonical) attribute/alias names 
+    # and the values are Schema::Attribute's.
+    #
+    # You don't have to explicitly load schema information; the UCB::LDAP module
+    # loads schema information as needed.  Unless you want to override the schema
+    # url (or file) you probably won't need to work directly with this class.
+    #
+    # == Schema Source
+    #
+    # Schema information is loaded from a url defined by the 
+    # SCHEMA_* constants.  A version of the file is distributed
+    # with this Gem and is used in case the web version is not accessible.
+    #
+    module Schema
+    
+      SCHEMA_BASE_URL = 'calnet.berkeley.edu'
+      SCHEMA_CONTENT_PATH = '/developers/developerResources/yaml/schema/schema.yaml'
+      SCHEMA_FILE = "#{File.dirname(__FILE__)}/../schema/schema.yml"
+      
+      class << self
+      
+        # Returns a hash of all attributes for all entities.  Keys are 
+        # entity names, values hash of attributes for given entity.
+        def schema_hash()
+          @schema_hash ||= load_attributes
+        end
+        
+        # Returns schema base url.  Defaults to SCHEMA_BASE_URL constant.
+        def schema_base_url()
+          @schema_base_url || SCHEMA_BASE_URL
+        end
+        
+        # Setter for schema_base_url().  Use this to override url of LDAP
+        # schema information.
+        def schema_base_url=(base_url)
+          @schema_base_url = base_url
+        end
+        
+        # Returns schema content path.  Defaults to SCHEMA_CONTENT_PATH constant.
+        def schema_content_path()
+          @schema_content_path || SCHEMA_CONTENT_PATH
+        end
+        
+        # Setter for schema_content_path().  Use this to override content path of LDAP
+        # schema information.
+        def schema_content_path=(content_path)
+          @schema_content_path = content_path
+        end
+        
+        # Returns schema file.  Defaults fo SCHEMA_FILE constant.
+        def schema_file()
+          @schema_file || SCHEMA_FILE
+        end
+        
+        # Setter for schema_file().  Use this to override location of
+        # local schema file.
+        def schema_file=(file)
+          @schema_file = file
+        end
+        
+      #private unless $TESTING
+        
+        # Setter for schema_hash()
+        def schema_hash=(h) #:nodoc:
+          @schema_hash = h
+        end
+        
+        # Load attributes from URL or file
+        def load_attributes #:nodoc:
+          load_attributes_from_url
+        rescue
+          puts "Warning: schema loading from file"
+          load_attributes_from_file
+        end
+        
+        def load_attributes_from_url() #:nodoc:
+          self.schema_hash = YAML.load(yaml_from_url)
+        end
+        
+        def yaml_from_url() #:nodoc:
+          http = Net::HTTP.new(SCHEMA_BASE_URL, 443)
+          http.use_ssl = true
+          http.get(SCHEMA_CONTENT_PATH).body
+        end
+        
+        def load_attributes_from_file() #:nodoc:
+          self.schema_hash = YAML.load(yaml_from_file)
+        end
+
+        def yaml_from_file #:nodoc:
+          IO.read(schema_file)
+        end
+        
+        # Get instance variable w/o loading -- for testing purposes.
+        def schema_hash_i() #:nodoc:
+          @schema_hash
+        end
+        
+      end
+    end
+  end
+end

data/lib/ucb_ldap_schema_attribute.rb

@@ -0,0 +1,153 @@
+
+module UCB
+  module LDAP
+    module Schema
+      # = UCB::LDAP::SchemaAttribute
+      # 
+      # This class models <em>schema</em> information about an LDAP attribute.
+      # 
+      # This class is used internally by various UCB::LDAP classes.
+      # Users of UCB::LDAP probably won't need to interact with this
+      # class directly.
+      #
+      # The LDAP entity classes have access to their Attribute's.
+      #
+      #   uid_attr = UCB::LDAP::Person.attribute(:uid) # :symbol ok as attribute name
+      #
+      #   uid_attr.name             #=> 'uid'
+      #   uid_attr.aliases          #=> ['userid']
+      #   uid_attr.description      #=> 'Standard LDAP attribute type'
+      #   uid_attr.multi_valued?    #=> true
+      #   uid_attr.required?        #=> true
+      #   uid_attr.type             #=> 'string'
+      #
+      #   uas_attr = UCB::LDAP::Person.attribute('berkeleyEduUasEligFlag') # case doesn't matter
+      #
+      #   uas_attr.name             #=> 'berkeleyEduUasEligFlag'
+      #   uas_attr.aliases          #=> ['ucbvalidflag']
+      #   uas_attr.description      #=> 'UAS Eligibility Flag'
+      #   uas_attr.multi_valued?    #=> false
+      #   uas_attr.required?        #=> false
+      #   uas_attr.type             #=> 'boolean'
+      #
+      class Attribute
+      
+        # Constructor called by UCB::LDAP::Entry.set_schema_attributes().
+        def initialize(args) #:nodoc:
+          @name = args["name"]
+          @type = args["syntax"]
+          @aliases = args["aliases"] || []
+          @description = args["description"]
+          @required = args["required"]
+          @multi_valued = args["multi"]
+        end
+        
+        # Returns attribute name as found in the schema 
+        def name
+          @name
+        end
+        
+        # Returns Array of aliases as found in schema.  Returns empty
+        # Array ([]) if no aliases.
+        #
+        def aliases
+          @aliases
+        end
+        
+        # Returns (data) type.  Used by get_value() to cast value to correct Ruby type.
+        #
+        # Supported types and corresponding Ruby type:
+        #
+        #   * string      String
+        #   * integer     Fixnum
+        #   * boolean     TrueClass / FalseClass
+        #   * timestamp   DateTime (convenience methods may return Date if attribute's semantics don't include time)
+        #
+        def type
+          @type
+        end
+        
+        # Returns attribute description.  Of limited value since all
+        # standard LDAP attributes have a description of 
+        # "Standard LDAP attribute type".
+        def description
+          @description
+        end
+        
+        # Returns <tt>true</tt> if attribute is required, else <tt>false</tt>
+        def required?
+          @required
+        end
+        
+        # Returns <tt>true</tt> if attribute is multi-valued, else <tt>false</tt>.
+        # Multi-valued attribute values are returned as an Array.
+        def multi_valued?
+          @multi_valued
+        end
+        
+        # Takes a value returned from an LDAP attribute (+Array+ of +String+)
+        # and returns value with correct cardinality (array or scalar)
+        # cast to correct #type.
+        def get_value(array)
+          if array.nil?
+            return false if boolean?
+            return [] if multi_valued?
+            return nil
+          end
+          typed_array = apply_type_to_array(array)
+          multi_valued? ? typed_array : typed_array.first
+        end
+        
+        # Cast each element to correct type.
+        def apply_type_to_array(array) #:nodoc:
+          array.map{|scalar| apply_type_to_scalar scalar}
+        end
+        
+        # Case element to correct type
+        def apply_type_to_scalar(string) #:nodoc:
+          return string if string?
+          return string.to_i if integer?
+          return %w{true 1}.include?(string) ? true : false if boolean?
+          return UCB::LDAP.local_datetime_parse(string) if timestamp?
+          raise "unknown type '#{type}' for attribute '#{name}'"
+        end
+        
+        # Return <tt>true</tt> if attribute type is string.
+        def string?
+          type == "string"
+        end
+        
+        # Return <tt>true</tt> if attribute type is integer.
+        def integer?
+          type == "integer"
+        end
+        
+        # Return <tt>true</tt> if attribute type is boolean.
+        def boolean?
+          type == "boolean"
+        end
+        
+        # Return <tt>true</tt> if attribute type is timestamp
+        def timestamp?
+          type == "timestamp" 
+        end
+        
+        # Returns a value in LDAP attribute value format (+Array+ of +String+).
+        def ldap_value(value)
+          return nil if value.nil?
+          return value.map{|v| ldap_value_stripped(v)} if value.instance_of?(Array)
+          return [ldap_value_stripped(value)]
+        end
+        
+        private 
+        
+        # Remove leading/trailing white-space and imbedded newlines.
+        def ldap_value_stripped(s)
+          s.to_s.strip.gsub(/\n/,"")
+        end
+        
+      end
+      
+    end
+  end 
+end

data/lib/ucb_ldap_service.rb

@@ -0,0 +1,109 @@
+
+module UCB
+  module LDAP
+    # = UCB::LDAP::Service
+    # 
+    # This class models a person's service entries in the UCB LDAP directory.
+    #
+    #   services = Services.find_by_uid("1234")       #=> [#<UCB::LDAP::Service: ...>, ...]
+    #
+    # Servicess are usually loaded through a Person instance:
+    #
+    #   p = Person.find_by_uid("1234")    #=> #<UCB::LDAP::Person: ...>
+    #   services = p.services        #=> [#<UCB::LDAP::Service: ...>, ...]
+    #
+    # == Note on Binds
+    # 
+    # You must have a privileged bind and pass your credentials to UCB::LDAP.authenticate()
+    # before performing your Service search.
+    #
+    class Service < Entry
+      @entity_name = 'personService'
+      
+      def eligible_by
+        berkeleyEduPersonServiceEligibleBy
+      end
+
+      def eligible_date
+        berkeleyEduPersonServiceEligibleDate
+      end
+      
+      def ended_by
+        berkeleyEduPersonServiceEndBy
+      end
+
+      def end_date
+        berkeleyEduPersonServiceEndDate
+      end
+
+      def entered_by
+        berkeleyEduPersonServiceEnteredBy
+      end
+
+      def entered_date
+        berkeleyEduPersonServiceEnteredDate
+      end
+      
+      def level
+        berkeleyEduPersonServiceLevel
+      end
+
+      def modified_by
+        berkeleyEduPersonServiceModifiedBy
+      end
+
+      def modified_date
+        berkeleyEduPersonServiceModifiedDate
+      end
+
+      def naughty_bit
+        berkeleyEduPersonServiceNaughtyBit
+      end
+
+      def notified_by
+        berkeleyEduPersonServiceNotifyBy
+      end
+
+      def notify_date
+        berkeleyEduPersonServiceNotifyDate
+      end
+
+      def stopped_by
+        berkeleyEduPersonServiceStopBy
+      end
+
+      def stop_date
+        berkeleyEduPersonServiceStopDate
+      end
+      
+      def value
+        berkeleyEduPersonServiceValue
+      end
+
+      def service
+        berkeleyEduService
+      end
+
+      def common_name
+        cn
+      end
+
+      def description
+        super.first
+      end
+      
+      class << self
+        # Returns an Array of JobAppointment for <tt>uid</tt>, sorted by
+        # record_number().
+        # 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", 'berkeleyEduPersonService')
+          search(:base => base, :filter => filter)
+        end
+         
+      end
+    end
+  end
+end