Class: Net::LDAP::Entry

Inherits:
Object
  • Object
show all
Defined in:
lib/net/ldap/entry.rb

Overview

Objects of this class represent individual entries in an LDAP directory. User code generally does not instantiate this class. Net::LDAP#search provides objects of this class to user code, either as block parameters or as return values.

In LDAP-land, an “entry” is a collection of attributes that are uniquely and globally identified by a DN (“Distinguished Name”). Attributes are identified by short, descriptive words or phrases. Although a directory is free to implement any attribute name, most of them follow rigorous standards so that the range of commonly-encountered attribute names is not large.

An attribute name is case-insensitive. Most directories also restrict the range of characters allowed in attribute names. To simplify handling attribute names, Net::LDAP::Entry internally converts them to a standard format. Therefore, the methods which take attribute names can take Strings or Symbols, and work correctly regardless of case or capitalization.

An attribute consists of zero or more data items called values. An entry is the combination of a unique DN, a set of attribute names, and a (possibly-empty) array of values for each attribute.

Class Net::LDAP::Entry provides convenience methods for dealing with LDAP entries. In addition to the methods documented below, you may access individual attributes of an entry simply by giving the attribute name as the name of a method call. For example:

ldap.search( ... ) do |entry|
  puts "Common name: #{entry.cn}"
  puts "Email addresses:"
  entry.mail.each {|ma| puts ma}
end

If you use this technique to access an attribute that is not present in a particular Entry object, a NoMethodError exception will be raised.

– Ugly problem to fix someday: We key off the internal hash with a canonical form of the attribute name: convert to a string, downcase, then take the symbol. Unfortunately we do this in at least three places. Should do it in ONE place.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(dn = nil) ⇒ Entry

This constructor is not generally called by user code.



47
48
49
50
 
# File 'lib/net/ldap/entry.rb', line 47

def initialize(dn = nil) #:nodoc:
  @myhash = {}
  @myhash[:dn] = [dn]
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(sym, *args, &block) ⇒ Object

:nodoc:



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/net/ldap/entry.rb', line 169

def method_missing(sym, *args, &block) #:nodoc:
  name = self.class.attribute_name(sym)

  if valid_attribute?(name )
    if setter?(sym) && args.size == 1
      value = args.first
      value = Array(value)
      self[name]= value
      return value
    elsif args.empty?
      return self[name]
    end
  end

  super
end

Class Method Details

._load(entry) ⇒ Object

Use the LDIF format for Marshal serialization.



60
61
62
 
# File 'lib/net/ldap/entry.rb', line 60

def self._load(entry) #:nodoc:
  from_single_ldif_string(entry)
end

.attribute_name(name) ⇒ Object

Canonicalizes an LDAP attribute name as a Symbol. The name is lowercased and, if present, a trailing equals sign is removed.



85
86
87
88
89
 
# File 'lib/net/ldap/entry.rb', line 85

def attribute_name(name)
  name = name.to_s.downcase
  name = name[0..-2] if name[-1] == ?=
  name.to_sym
end

.from_single_ldif_string(ldif) ⇒ Object

Converts a single LDIF entry string into an Entry object. Useful for Marshal serialization. If a string with multiple LDIF entries is provided, an exception will be raised.

Raises:



69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/net/ldap/entry.rb', line 69

def from_single_ldif_string(ldif)
  ds = Net::LDAP::Dataset.read_ldif(::StringIO.new(ldif))

  return nil if ds.empty?

  raise Net::LDAP::EntryOverflowError, "Too many LDIF entries" unless ds.size == 1

  entry = ds.to_entries.first

  return nil if entry.dn.nil?
  entry
end

Instance Method Details

#==(other) ⇒ Object 



198
199
200
 
# File 'lib/net/ldap/entry.rb', line 198

def ==(other)
  other.instance_of?(self.class) && @myhash == other.to_h
end

#[](name) ⇒ Object

Reads the array of values for the provided attribute. The attribute name is canonicalized prior to reading. Returns an empty array if the attribute does not exist.



111
112
113
114
 
# File 'lib/net/ldap/entry.rb', line 111

def [](name)
  name = self.class.attribute_name(name)
  @myhash[name] || []
end

#[]=(name, value) ⇒ Object

Sets or replaces the array of values for the provided attribute. The attribute name is canonicalized prior to assignment.

When an attribute is set using this, that attribute is now made accessible through methods as well.

entry = Net::LDAP::Entry.new("dc=com")
entry.foo             # => NoMethodError
entry["foo"] = 12345  # => [12345]
entry.foo             # => [12345]



103
104
105
 
# File 'lib/net/ldap/entry.rb', line 103

def []=(name, value)
  @myhash[self.class.attribute_name(name)] = Kernel::Array(value)
end

#_dump(depth) ⇒ Object

Use the LDIF format for Marshal serialization.



54
55
56
 
# File 'lib/net/ldap/entry.rb', line 54

def _dump(depth) #:nodoc:
  to_ldif
end

#attribute_names ⇒ Object

Returns an array of the attribute names present in the Entry.



132
133
134
 
# File 'lib/net/ldap/entry.rb', line 132

def attribute_names
  @myhash.keys
end

#dn ⇒ Object

Returns the first distinguished name (dn) of the Entry as a String.



126
127
128
 
# File 'lib/net/ldap/entry.rb', line 126

def dn
  self[:dn].first.to_s
end

#each ⇒ Object Also known as: each_attribute

Accesses each of the attributes present in the Entry.

Calls a user-supplied block with each attribute in turn, passing two arguments to the block: a Symbol giving the name of the attribute, and a (possibly empty) Array of data values.



149
150
151
152
153
154
155
 
# File 'lib/net/ldap/entry.rb', line 149

def each # :yields: attribute-name, data-values-array
  return unless block_given?
  attribute_names.each do|a|
    attr_name, values = a, self[a]
    yield attr_name, values
  end
end

#first(name) ⇒ Object

Read the first value for the provided attribute. The attribute name is canonicalized prior to reading. Returns nil if the attribute does not exist.



120
121
122
 
# File 'lib/net/ldap/entry.rb', line 120

def first(name)
  self[name].first
end

#respond_to?(sym, include_all = false) ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


164
165
166
167
 
# File 'lib/net/ldap/entry.rb', line 164

def respond_to?(sym, include_all = false) #:nodoc:
  return true if valid_attribute?(self.class.attribute_name(sym))
  return super
end

#to_h ⇒ Object

Creates a duplicate of the internal Hash containing the attributes of the entry.



139
140
141
 
# File 'lib/net/ldap/entry.rb', line 139

def to_h
  @myhash.dup
end

#to_ldif ⇒ Object

Converts the Entry to an LDIF-formatted String



160
161
162
 
# File 'lib/net/ldap/entry.rb', line 160

def to_ldif
  Net::LDAP::Dataset.from_entry(self).to_ldif_string
end