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:

Missing Attribute Values

If an attribute value is not present, the value returned depends on type and multi/single value field:

Attempting to get an attribute value for an invalid attribute name will raise a BadAttributeNameException.

Constants

TESTING

Public Class Methods

canonical(string_or_symbol) click to toggle source

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
combine_filters(filters, operator = '&') click to toggle source

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
create(args) click to toggle source

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
create!(args) click to toggle source

Same as create(), but raises DirectoryNotUpdated on failure.

# File lib/ucb_ldap/entry.rb, line 173
def create!(args)
  create(args) || raise(DirectoryNotUpdatedException)
end
entity_name() click to toggle source

Schema entity name. Set in each subclass.

# File lib/ucb_ldap/entry.rb, line 321
def entity_name
  @entity_name
end
filter_in(attribute_name, array_of_values) click to toggle source
# 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
find_by_dn(dn) click to toggle source

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
make_search_filter(filter) click to toggle source

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
object_classes() click to toggle source

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
required_attributes() click to toggle source

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
required_schema_attributes() click to toggle source

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
schema_attribute(attribute_name) click to toggle source
# 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
schema_attributes_array() click to toggle source

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
schema_attributes_hash() click to toggle source

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
set_schema_attributes() click to toggle source

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
tree_base() click to toggle source

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
tree_base=(tree_base) click to toggle source
# File lib/ucb_ldap/entry.rb, line 353
def tree_base=(tree_base)
  @tree_base = tree_base
end
unique_object_class() click to toggle source
# 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

assigned_attributes() click to toggle source
# File lib/ucb_ldap/entry.rb, line 125
def assigned_attributes
  @assigned_attributes ||= {}
end
attributes() click to toggle source

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
dn() click to toggle source

Returns the value of the Distinguished Name attribute.

# File lib/ucb_ldap/entry.rb, line 96
def dn
  attributes[canonical(:dn)]
end
net_ldap() click to toggle source
# File lib/ucb_ldap/entry.rb, line 104
def net_ldap
  self.class.net_ldap
end