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. – Originally, myhash took a block so we wouldn’t have to make sure its elements returned empty arrays when necessary. Got rid of that to enable marshalling of Entry objects, but that doesn’t work anyway, because Entry objects have singleton methods. So we define a custom dump and load.



89
90
91
92
 
# File 'lib/net/ldap/entry.rb', line 89

def initialize dn = nil # :nodoc:
  @myhash = {} # originally: Hash.new {|k,v| k[v] = [] }
  @myhash[:dn] = [dn]
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(*args, &block) ⇒ Object

– Convenience method to convert unknown method names to attribute references. Of course the method name comes to us as a symbol, so let’s save a little time and not bother with the to_s.downcase two-step. Of course that means that a method name like mAIL won’t work, but we shouldn’t be encouraging that kind of bad behavior in the first place. Maybe we should thow something if the caller sends arguments or a block…



226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/net/ldap/entry.rb', line 226

def method_missing *args, &block # :nodoc:
  s = args[0].to_s.downcase.intern
  if attribute_names.include?(s)
    self[s]
  elsif s.to_s[-1] == 61 and s.to_s.length > 1
    value = args[1] or raise RuntimeError.new( "unable to set value" )
    value = [value] unless value.is_a?(Array)
    name = s.to_s[0..-2].intern
    self[name] = value
  else
    raise NoMethodError.new( "undefined method '#{s}'" )
  end
end

Class Method Details

._load(entry) ⇒ Object 



99
100
101
 
# File 'lib/net/ldap/entry.rb', line 99

def _load entry
  from_single_ldif_string entry
end

.from_single_ldif_string(ldif) ⇒ Object 



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/net/ldap/entry.rb', line 198

def from_single_ldif_string ldif
  entry = Entry.new
  entry[:dn] = []
  ldif.split(/\r?\n/m).each {|line|
    break if line.length == 0
    if line =~ /\A([\w]+):(:?)[\s]*/
      entry[$1] <<= if $2 == ':'
        Base64.decode64($')
      else
        $'
      end
    end
  }
  entry.dn ? entry : nil
end

Instance Method Details

#[](name) ⇒ Object

– We have to deal with this one as we do with []= because this one and not the other one gets called in formulations like entry << cn.



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

def [] name # :nodoc:
  name = name.to_s.downcase.intern unless name.is_a?(Symbol)
  @myhash[name] || []
end

#[]=(name, value) ⇒ Object

– Discovered bug, 26Aug06: I noticed that we’re not converting the incoming value to an array if it isn’t already one.



107
108
109
110
111
 
# File 'lib/net/ldap/entry.rb', line 107

def []= name, value # :nodoc:
  sym = name.to_s.downcase.intern
  value = [value] unless value.is_a?(Array)
  @myhash[sym] = value
end

#_dump(depth) ⇒ Object 



94
95
96
 
# File 'lib/net/ldap/entry.rb', line 94

def _dump depth
  to_ldif
end

#attribute_names ⇒ Object

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



130
131
132
 
# File 'lib/net/ldap/entry.rb', line 130

def attribute_names
  @myhash.keys
end

#dn ⇒ Object

Returns the dn of the Entry as a String.



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

def dn
  self[:dn][0].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.



140
141
142
143
144
145
146
147
 
# File 'lib/net/ldap/entry.rb', line 140

def each
  if block_given?
    attribute_names.each {|a|
      attr_name,values = a,self[a]
      yield attr_name, values
    }
  end
end

#to_ldif ⇒ Object

Converts the Entry to a String, representing the Entry’s attributes in LDIF format. –



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/net/ldap/entry.rb', line 156

def to_ldif
  ary = []
  ary << "dn: #{dn}\n"
  v2 = "" # temp value, save on GC
  each_attribute do |k,v|
    unless k == :dn
      v.each {|v1|
        v2 = if (k == :userpassword) || is_attribute_value_binary?(v1)
          ": #{Base64.encode64(v1).chomp.gsub(/\n/m,"\n ")}"
        else
          " #{v1}"
        end
        ary << "#{k}:#{v2}\n"
      }
    end
  end
  ary << "\n"
  ary.join
end

#write ⇒ Object 



240
241
 
# File 'lib/net/ldap/entry.rb', line 240

def write
end