Module: Ldaptic::Methods

Defined in:
lib/ldaptic/methods.rb

Overview

These methods are accessible directly from the Ldaptic object.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#adapter ⇒ Object (readonly)

Returns the value of attribute adapter.



48
49
50
 
# File 'lib/ldaptic/methods.rb', line 48

def adapter
  @adapter
end

Instance Method Details

#/(*args) ⇒ Object

Find an RDN relative to the base. This method is experimental.

class L < Ldaptic::Class(:base => "DC=ruby-lang,DC=org", ...)
end

(L/{:cn => "Matz"}).dn #=> "CN=Matz,DC=ruby-lang,DC=org"



71
72
73
 
# File 'lib/ldaptic/methods.rb', line 71

def /(*args)
  find(base.send(:/, *args))
end

#[](*args) ⇒ Object

Like #/, only the search results are cached. This method is experimental.

L[:cn=>"Why"].bacon = "chunky"
L[:cn=>"Why"].bacon #=> "chunky"
L[:cn=>"Why"].save



81
82
83
84
85
86
87
 
# File 'lib/ldaptic/methods.rb', line 81

def [](*args)
  if args.empty?
    @self ||= find(base)
  else
    self[][*args]
  end
end

#[]=(*args) ⇒ Object

Like Ldaptic::Entry#[]= for the root node. Only works for assigning children. This method is experimental.

MyCompany[:cn=>"New Employee"] = MyCompany::User.new



93
94
95
 
# File 'lib/ldaptic/methods.rb', line 93

def []=(*args) #:nodoc:
  self[].send(:[]=, *args)
end

#add(dn, attributes) ⇒ Object

Performs an LDAP add.



250
251
252
253
254
 
# File 'lib/ldaptic/methods.rb', line 250

def add(dn, attributes)
  log_dispatch(:add, dn, attributes)
  attributes = normalize_attributes(attributes)
  adapter.add(dn, attributes)
end

#attribute_syntax(attribute) ⇒ Object

Returns an Ldaptic::Schema::LdapSyntax object encapsulating server provided information about the syntax of an attribute.

L.attribute_syntax(:cn).desc #=> "Directory String"



330
331
332
333
334
335
336
337
 
# File 'lib/ldaptic/methods.rb', line 330

def attribute_syntax(attribute)
  type   = attribute_type(attribute)
  syntax = nil
  until type.nil? || syntax = type.syntax
    type = attribute_type(type.sup)
  end
  syntax
end

#attribute_type(attribute) ⇒ Object

Returns an Ldaptic::Schema::AttibuteType object encapsulating server provided information about an attribute type.

L.attribute_type(:cn).desc #=> "RFC2256: common name..."



323
324
325
 
# File 'lib/ldaptic/methods.rb', line 323

def attribute_type(attribute)
  adapter.attribute_type(Ldaptic.encode(attribute))
end

#authenticate(dn, password) ⇒ Object

Verifies the given credentials are authorized to connect to the server by temporarily binding with them. Returns a boolean.



341
342
343
 
# File 'lib/ldaptic/methods.rb', line 341

def authenticate(dn, password)
  adapter.authenticate(dn, password)
end

#base ⇒ Object Also known as: dn

Access the base DN.



56
57
58
 
# File 'lib/ldaptic/methods.rb', line 56

def base
  @base ||= Ldaptic::DN(adapter.default_base_dn, self)
end

#base=(dn) ⇒ Object

Set a new base DN. Generally, the base DN should be set when the namespace is created and left unchanged.



52
53
54
 
# File 'lib/ldaptic/methods.rb', line 52

def base=(dn)
  @base = Ldaptic::DN(dn, self)
end

#compare(dn, key, value) ⇒ Object

Performs an LDAP compare.



280
281
282
283
 
# File 'lib/ldaptic/methods.rb', line 280

def compare(dn, key, value)
  log_dispatch(:compare, dn, key, value)
  adapter.compare(dn, Ldaptic.encode(key), Ldaptic.encode(value))
end

#delete(dn) ⇒ Object

Performs an LDAP delete.



268
269
270
271
 
# File 'lib/ldaptic/methods.rb', line 268

def delete(dn)
  log_dispatch(:delete, dn)
  adapter.delete(dn)
end

#dit_content_rule(oid) ⇒ Object 



285
286
287
 
# File 'lib/ldaptic/methods.rb', line 285

def dit_content_rule(oid)
  adapter.dit_content_rules[oid]
end

#fetch(dn = self.dn, options = {}) ⇒ Object

A potential replacement or addition to find. Does not handle array arguments or do any of the active record monkey business.



156
157
158
 
# File 'lib/ldaptic/methods.rb', line 156

def fetch(dn = self.dn, options = {}) #:nodoc:
  find_one(dn, options)
end

#filter(controller = nil) ⇒ Object

Convenience method for use with Rails. Allows the singleton to be used as a before filter, an after filter, or an around filter.

class ApplicationController < ActionController::Base
  prepend_around_filter MyCompany
end

When invoked, the filter clears cached children. This operation is cheap and quite necessary if you care to avoid stale data.



363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
 
# File 'lib/ldaptic/methods.rb', line 363

def filter(controller = nil)
  if controller
    reload
    if block_given?
      begin
        yield
      ensure
        reload
      end
    end
  else
    yield if block_given?
  end
  self
end

#find(dn = self.dn, options = {}) ⇒ Object

Find an absolute DN, raising an error when no results are found.

L.find("CN=Matz,DC=ruby-lang,DC=org")

A hash is treated as an RDN relative to the default base.

L.find(:cn=>"Matz")

Equivalent to

L.search(:base => dn, :scope => :base, :limit => true) or raise ...



166
167
168
169
170
171
172
173
174
 
# File 'lib/ldaptic/methods.rb', line 166

def find(dn = self.dn, options = {})
  # Some misguided attempts to emulate active record.
  case dn
  when :all   then search({:limit => false}.merge(options))
  when :first then first(options)
  when Array  then dn.map {|d| fetch(d, options)}
  else             fetch(dn, options)
  end
end

#first(options = {}) ⇒ Object

Like #search, but only returns one entry.



177
178
179
 
# File 'lib/ldaptic/methods.rb', line 177

def first(options = {})
  search(options.merge(:limit => true))
end

#log_dispatch(method, *args) ⇒ Object 



379
380
381
382
383
 
# File 'lib/ldaptic/methods.rb', line 379

def log_dispatch(method, *args)
  if logger.debug?
    logger.debug("#{inspect}.#{method}(#{args.inspect[1..-2]})")
  end
end

#logger ⇒ Object 



61
62
63
 
# File 'lib/ldaptic/methods.rb', line 61

def logger
  @logger ||= adapter.logger
end

#model_name ⇒ Object

Delegated to from Ldaptic::Entry for Active Model compliance.



346
347
348
349
350
351
352
 
# File 'lib/ldaptic/methods.rb', line 346

def model_name
  if defined?(ActiveSupport::ModelName)
    ActiveSupport::ModelName.new(name)
  else
    ActiveModel::Name.new(self)
  end
end

#modify(dn, attributes) ⇒ Object

Performs an LDAP modify.



257
258
259
260
261
262
263
264
265
 
# File 'lib/ldaptic/methods.rb', line 257

def modify(dn, attributes)
  log_dispatch(:modify, dn, attributes)
  if attributes.kind_of?(Hash)
    attributes = normalize_attributes(attributes)
  else
    attributes = attributes.map {|(action, key, values)| [action, Ldaptic.encode(key), Array(values)]}
  end
  adapter.modify(dn, attributes) unless attributes.empty?
end

#object_class(klass) ⇒ Object

Returns the object class for a given name or OID.

L.object_class("top") #=> L::Top



315
316
317
 
# File 'lib/ldaptic/methods.rb', line 315

def object_class(klass)
  @object_classes[klass.to_s.tr('-', '_').downcase]
end

#reload ⇒ Object

Clears the cache of children. This cache is automatically populated when a child is accessed through #[].



99
100
101
102
103
104
 
# File 'lib/ldaptic/methods.rb', line 99

def reload
  if @self
    @self.reload rescue nil
    @self = nil
  end
end

#rename(dn, new_rdn, delete_old, *args) ⇒ Object

Performs an LDAP modrdn.



274
275
276
277
 
# File 'lib/ldaptic/methods.rb', line 274

def rename(dn, new_rdn, delete_old, *args)
  log_dispatch(:delete, dn, new_rdn, delete_old, *args)
  adapter.rename(dn, new_rdn.to_str, delete_old, *args)
end

#root_dse(attrs = nil) ⇒ Object

Retrieves attributes from the Root DSE. If attrs is an array, a hash is returned keyed on the attribute.

L.root_dse(:subschemaSubentry) #=> ["cn=Subschema"]



293
294
295
296
297
298
299
300
301
 
# File 'lib/ldaptic/methods.rb', line 293

def root_dse(attrs = nil) #:nodoc:
  search(
    :base => "",
    :scope => :base,
    :attributes => attrs,
    :limit => true,
    :instantiate => false
  )
end

#schema(attrs = nil) ⇒ Object

:nodoc:



303
304
305
306
307
308
309
310
 
# File 'lib/ldaptic/methods.rb', line 303

def schema(attrs = nil) #:nodoc:
  search(
    :base => Array(root_dse(:subschemaSubentry)).first,
    :scope => :base,
    :attributes => attrs,
    :limit => true
  )
end

#search(options = {}, &block) ⇒ Object

This is the core method for LDAP searching.

  • :base: The base DN of the search. The default is derived from either the :base option of the adapter configuration or by querying the server.

  • :scope: The scope of the search. Valid values are :base (find the base only), :onelevel (children of the base), and :subtree (the base, children, and all descendants). The default is :subtree.

  • :filter: A standard LDAP filter. This can be a string, an Ldaptic::Filter object, or parameters for Ldaptic::Filter().

  • :limit: Maximum number of results to return. If the value is a literal true, the first item is returned directly (or nil if nothing was found). For a literal false, an array always returned (the default).

  • :attributes: Specifies an Array of attributes to return. When unspecified, all attributes are returned. If this is not an Array but rather a String or a Symbol, an array of attributes is returned rather than an array of objects.

  • :instantiate: If this is false, a raw hash is returned rather than an Ldaptic object. Combined with a String or Symbol argument to :attributes, a false value here causes the attribute not to be typecast.

Option examples:

# Returns all people.
MyCompany.search(:filter => {:objectClass => "person"})
# Returns an array of strings because givenName is marked as a singular value on this server.
MyCompany.search(:attribute => :givenName)
# Returns an array of arrays of strings.
MyCompany.search(:attribute => :givenName, :instantiate => false)
# Returns the first object found.
MyCompany.search(:limit => true)



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/ldaptic/methods.rb', line 213

def search(options = {}, &block)
  logger.debug("#{inspect}.search(#{options.inspect[1..-2]})")
  ary = []
  one_attribute = options[:attributes]
  if one_attribute.respond_to?(:to_ary)
    one_attribute = nil
  end
  options = search_options(options)
  if options[:limit] == true
    options[:limit] = 1
    first = true
  end
  adapter.search(options) do |entry|
    if options[:instantiate]
      klass = const_get("Top")
      entry = klass.instantiate(entry)
    end
    if one_attribute
      entry = entry[Ldaptic.encode(one_attribute)]
      entry = entry.one if entry.respond_to?(:one)
    end
    ary << entry
    block.call(entry) if block_given?
    return entry if first == true
    return ary   if options[:limit] == ary.size
  end
  first ? ary.first : ary
end

#to_ldaptic ⇒ Object

For duck typing.



7
8
9
 
# File 'lib/ldaptic/methods.rb', line 7

def to_ldaptic
  self
end