class UCB::LDAP::Entry
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 underlying attribute as multi-valued becuase in practice the 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 an attribute value for an invalid attribute name will raise a BadAttributeNameException.
Constants
- TESTING
Public Class Methods
Returns the canonical representation of a symbol or string so we can look up attributes in a number of ways.
# File lib/ucb_ldap/entry.rb, line 304 def canonical(string_or_symbol) string_or_symbol.to_s.downcase.to_sym end
Returns a new Net::LDAP::Filter that is the result of combining filters using operator (filters 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
# File lib/ucb_ldap/entry.rb, line 190 def combine_filters(filters, operator = '&') filters.inject { |accum, filter| accum.send(operator, filter) } end
Creates and returns new entry. Returns false
if unsuccessful. Sets :objectclass key of args[:attributes] 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.
# File lib/ucb_ldap/entry.rb, line 154 def create(args) args[:attributes][:objectclass] = object_classes result = net_ldap.add(args) result or return false find_by_dn(args[:dn]) end
Same as create(), but raises DirectoryNotUpdated on failure.
# File lib/ucb_ldap/entry.rb, line 173 def create!(args) create(args) || raise(DirectoryNotUpdatedException) end
Schema
entity name. Set in each subclass.
# File lib/ucb_ldap/entry.rb, line 321 def entity_name @entity_name end
# File lib/ucb_ldap/entry.rb, line 134 def filter_in(attribute_name, array_of_values) filters = array_of_values.map { |value| Net::LDAP::Filter.eq(attribute_name, value) } UCB::LDAP::Entry.combine_filters(filters, '|') end
Returns entry whose distinguised name is dn.
# File lib/ucb_ldap/entry.rb, line 163 def find_by_dn(dn) search( :base => dn, :scope => Net::LDAP::SearchScope_BaseObject, :filter => "objectClass=*" ).first end
Returns Net::LDAP::Filter. Allows for filter 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)
# File lib/ucb_ldap/entry.rb, line 201 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.
# File lib/ucb_ldap/entry.rb, line 215 def object_classes @object_classes ||= UCB::LDAP::Schema.schema_hash[entity_name]["objectClasses"] end
returns an Array of symbols where each symbol is the name of a required attribute for the Entry
# File lib/ucb_ldap/entry.rb, line 226 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>
# File lib/ucb_ldap/entry.rb, line 242 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
# File lib/ucb_ldap/entry.rb, line 267 def schema_attribute(attribute_name) schema_attributes_hash[canonical(attribute_name)] || raise(BadAttributeNameException, "'#{attribute_name}' is not a recognized attribute name") end
Returns an Array
of Schema::Attribute
for the entity.
# File lib/ucb_ldap/entry.rb, line 253 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.
# File lib/ucb_ldap/entry.rb, line 262 def schema_attributes_hash @schema_attributes_hash || set_schema_attributes @schema_attributes_hash 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 :base
and :filter
. Search methods of subclasses have default :base
that can be overriden.
See make_search_filter
for :filter
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'}
# File lib/ucb_ldap/entry.rb, line 288 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 << new(entry) end results end
Want an array of Schema::Attributes as well as a hash of all possible variations on a name pointing to correct array element.
# File lib/ucb_ldap/entry.rb, line 329 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 :base
parm.
# File lib/ucb_ldap/entry.rb, line 349 def tree_base @tree_base end
# File lib/ucb_ldap/entry.rb, line 353 def tree_base=(tree_base) @tree_base = tree_base end
# File lib/ucb_ldap/entry.rb, line 219 def unique_object_class @unique_object_class ||= UCB::LDAP::Schema.schema_hash[entity_name]["uniqueObjectClass"] end
Public Instance Methods
# File lib/ucb_ldap/entry.rb, line 125 def assigned_attributes @assigned_attributes ||= {} end
Hash
of attributes returned from underlying NET::LDAP::Entry instance. Hash keys are canonical attribute names, hash values are attribute values as returned from LDAP, 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.
# File lib/ucb_ldap/entry.rb, line 89 def attributes @attributes end
Returns the value of the Distinguished Name attribute.
# File lib/ucb_ldap/entry.rb, line 96 def dn attributes[canonical(:dn)] end
# File lib/ucb_ldap/entry.rb, line 104 def net_ldap self.class.net_ldap end