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"



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

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



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

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



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

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

#add(dn, attributes) ⇒ Object

Performs an LDAP add.



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

def add(dn, attributes)
  attributes = normalize_attributes(attributes)
  log_dispatch(:add, dn, 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"



333
334
335
336
337
338
339
340
 
# File 'lib/ldaptic/methods.rb', line 333

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..."



326
327
328
 
# File 'lib/ldaptic/methods.rb', line 326

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.



344
345
346
 
# File 'lib/ldaptic/methods.rb', line 344

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

#base ⇒ Object Also known as: dn

Access the base DN.



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

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

#base=(dn) ⇒ Object Also known as: dn=

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.



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

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.



271
272
273
274
 
# File 'lib/ldaptic/methods.rb', line 271

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

#dit_content_rule(oid) ⇒ Object 



288
289
290
 
# File 'lib/ldaptic/methods.rb', line 288

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.



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

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.



366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
 
# File 'lib/ldaptic/methods.rb', line 366

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 ...



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

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.



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

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

#log_dispatch(method, *args) ⇒ Object 



382
383
384
385
386
 
# File 'lib/ldaptic/methods.rb', line 382

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

#logger ⇒ Object 



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

def logger
  @logger ||= adapter.logger
end

#model_name ⇒ Object

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



349
350
351
352
353
354
355
 
# File 'lib/ldaptic/methods.rb', line 349

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.



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

def modify(dn, attributes)
  if attributes.kind_of?(Hash)
    attributes = normalize_attributes(attributes)
  else
    attributes = attributes.map do |(action, key, values)|
      [action, Ldaptic.encode(key), values.respond_to?(:before_type_cast) ? values.before_type_cast : [values].flatten.compact]
    end
  end
  log_dispatch(:modify, dn, attributes)
  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



318
319
320
 
# File 'lib/ldaptic/methods.rb', line 318

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 #[].



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

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

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

Performs an LDAP modrdn.



277
278
279
280
 
# File 'lib/ldaptic/methods.rb', line 277

def rename(dn, new_rdn, delete_old, *args)
  log_dispatch(:rename, 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"]



296
297
298
299
300
301
302
303
304
 
# File 'lib/ldaptic/methods.rb', line 296

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

#schema(attrs = nil) ⇒ Object

:nodoc:



306
307
308
309
310
311
312
313
 
# File 'lib/ldaptic/methods.rb', line 306

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)



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
241
 
# File 'lib/ldaptic/methods.rb', line 214

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