Class: ActiveLdap::Base

Inherits:
Object
  • Object
show all
Includes:
GetTextSupport, Reloadable::Deprecated, Reloadable::Subclasses
Defined in:
lib/active_ldap/base.rb

Overview

Base

Base is the primary class which contains all of the core ActiveLdap functionality. It is meant to only ever be subclassed by extension classes.

Direct Known Subclasses

Entry

Constant Summary collapse

VALID_LDAP_MAPPING_OPTIONS = 
[:dn_attribute, :prefix, :scope,
:classes, :recommended_classes,
:excluded_classes, :sort_by, :order]
@@configurations = 
{}

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from GetTextSupport

included

Constructor Details

#initialize(attributes = nil) {|_self| ... } ⇒ Base

new

Creates a new instance of Base initializing all class and all initialization. Defines local defaults. See examples If multiple values exist for dn_attribute, the first one put here will be authoritative

Yields:

  • (_self)

Yield Parameters:



690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
 
# File 'lib/active_ldap/base.rb', line 690

def initialize(attributes=nil)
  init_base
  @new_entry = true
  initial_classes = required_classes | recommended_classes
  case attributes
  when nil
    self.classes = initial_classes
  when String, Array, DN
    self.classes = initial_classes
    self.dn = attributes
  when Hash
    attributes = attributes.clone
    classes = extract_object_class!(attributes)
    self.classes = classes | initial_classes
    self.attributes = attributes
  else
    format = _("'%s' must be either nil, DN value as ActiveLdap::DN, " \
               "String or Array or attributes as Hash")
    raise ArgumentError, format % attributes.inspect
  end
  yield self if block_given?
  run_callbacks :initialize unless _initialize_callbacks.empty?
end

Class Attribute Details

.abstract_class ⇒ Object

Returns the value of attribute abstract_class.



514
515
516
 
# File 'lib/active_ldap/base.rb', line 514

def abstract_class
  @abstract_class
end

Class Method Details

.abstract_class? ⇒ Boolean

Returns:

  • (Boolean) 


515
516
517
 
# File 'lib/active_ldap/base.rb', line 515

def abstract_class?
  defined?(@abstract_class) && @abstract_class
end

.base ⇒ Object

Base.base

This method when included into Base provides an inheritable, overwritable configuration setting

This should be a string with the base of the ldap server such as 'dc=example,dc=com', and it should be overwritten by including configuration.rb into this class. When subclassing, the specified prefix will be concatenated.



442
443
444
 
# File 'lib/active_ldap/base.rb', line 442

def base
  @base ||= compute_base
end

.base=(value) ⇒ Object 



447
448
449
450
 
# File 'lib/active_ldap/base.rb', line 447

def base=(value)
  self.inheritable_base = value
  @base = nil
end

.base_class ⇒ Object 



475
476
477
478
479
480
481
 
# File 'lib/active_ldap/base.rb', line 475

def base_class
  if self == Base or superclass == Base
    self
  else
    superclass.base_class
  end
end

.class_local_attr_accessor(search_ancestors, *syms) ⇒ Object 



304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/active_ldap/base.rb', line 304

def self.class_local_attr_accessor(search_ancestors, *syms)
  syms.flatten.each do |sym|
    class_eval(<<-EOS, __FILE__, __LINE__ + 1)
      def self.#{sym}(search_superclasses=#{search_ancestors})
        @#{sym} ||= nil
        return @#{sym} if @#{sym}
        if search_superclasses
          target = superclass
          value = nil
          loop do
            break nil unless target.respond_to?(:#{sym})
            value = target.#{sym}
            break if value
            target = target.superclass
          end
          value
        else
          nil
        end
      end
      def #{sym}; self.class.#{sym}; end
      def self.#{sym}=(value); @#{sym} = value; end
    EOS
  end
end

.class_of_active_ldap_descendant(klass) ⇒ Object 



519
520
521
522
523
524
525
526
527
528
 
# File 'lib/active_ldap/base.rb', line 519

def class_of_active_ldap_descendant(klass)
  if klass.superclass == Base or klass.superclass.abstract_class?
    klass
  elsif klass.superclass.nil?
    raise Error, _("%s doesn't belong in a hierarchy descending " \
                   "from ActiveLdap") % (name || to_s)
  else
    class_of_active_ldap_descendant(klass.superclass)
  end
end

.create(attributes = nil, &block) ⇒ Object 



398
399
400
401
402
403
404
405
406
 
# File 'lib/active_ldap/base.rb', line 398

def create(attributes=nil, &block)
  if attributes.is_a?(Array)
    attributes.collect {|attrs| create(attrs, &block)}
  else
    object = new(attributes, &block)
    object.save
    object
  end
end

.default_search_attribute ⇒ Object 



483
484
485
 
# File 'lib/active_ldap/base.rb', line 483

def default_search_attribute
  dn_attribute
end

.establish_connection(config = nil) ⇒ Object

establish_connection is deprecated since 1.1.0. Please use setup_connection() instead.



389
390
391
392
393
394
395
396
 
# File 'lib/active_ldap/base.rb', line 389

def establish_connection(config=nil)
  message =
    _("ActiveLdap::Base.establish_connection has been deprecated " \
      "since 1.1.0. " \
      "Please use ActiveLdap::Base.setup_connection instead.")
  ActiveSupport::Deprecation.warn(message)
  setup_connection(config)
end

.human_name(options = {}) ⇒ Object 



541
542
543
544
545
546
547
548
549
550
551
552
 
# File 'lib/active_ldap/base.rb', line 541

def human_name(options={})
  defaults = self_and_descendants_from_active_ldap.collect do |klass|
    if klass.name.blank?
      nil
    else
      :"#{klass.name.underscore}"
    end
  end
  defaults << name.humanize
  defaults = defaults.compact
  defaults.first || name || to_s
end

.inherited(sub_class) ⇒ Object 



340
341
342
343
344
345
346
 
# File 'lib/active_ldap/base.rb', line 340

def inherited(sub_class)
  super
  sub_class.module_eval do
    include GetTextSupport
  end
  (self.sub_classes ||= []) << sub_class
end

.inspect ⇒ Object 



487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
 
# File 'lib/active_ldap/base.rb', line 487

def inspect
  if self == Base
    super
  elsif abstract_class?
    "#{super}(abstract)"
  else
    detail = nil
    begin
      must = []
      may = []
      class_names = classes.collect do |object_class|
        must.concat(object_class.must)
        may.concat(object_class.may)
        object_class.name
      end
      detail = ["objectClass:<#{class_names.join(', ')}>",
                "must:<#{inspect_attributes(must)}>",
                "may:<#{inspect_attributes(may)}>"].join(", ")
    rescue ActiveLdap::ConnectionNotSetup
      detail = "not-connected"
    rescue ActiveLdap::Error
      detail = "connection-failure"
    end
    "#{super}(#{detail})"
  end
end

.ldap_mapping(options = {}) ⇒ Object

This class function is used to setup all mappings between the subclass and ldap for use in activeldap

Example: ldap_mapping :dn_attribute => 'uid', :prefix => 'ou=People', :classes => ['top', 'posixAccount'], :scope => :sub



415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/active_ldap/base.rb', line 415

def ldap_mapping(options={})
  options = options.symbolize_keys
  validate_ldap_mapping_options(options)

  self.dn_attribute = options[:dn_attribute] || default_dn_attribute
  self.dn_attribute = dn_attribute.to_s if dn_attribute.is_a?(Symbol)
  self.prefix = options[:prefix] || default_prefix
  self.scope = options[:scope]
  self.required_classes = options[:classes]
  self.recommended_classes = options[:recommended_classes]
  self.excluded_classes = options[:excluded_classes]
  self.sort_by = options[:sort_by]
  self.order = options[:order]

  public_class_method :new
end

.parsed_base ⇒ Object

Base.base

This method when included into Base provides an inheritable, overwritable configuration setting

This should be a string with the base of the ldap server such as 'dc=example,dc=com', and it should be overwritten by including configuration.rb into this class. When subclassing, the specified prefix will be concatenated. for backward compatibility



445
446
447
 
# File 'lib/active_ldap/base.rb', line 445

def base
  @base ||= compute_base
end

.prefix ⇒ Object 



452
453
454
 
# File 'lib/active_ldap/base.rb', line 452

def prefix
  @prefix ||= inheritable_prefix and DN.parse(inheritable_prefix)
end

.prefix=(value) ⇒ Object 



456
457
458
459
460
 
# File 'lib/active_ldap/base.rb', line 456

def prefix=(value)
  self.inheritable_prefix = value
  @prefix = nil
  @base = nil
end

.scope=(scope) ⇒ Object 



463
464
465
466
 
# File 'lib/active_ldap/base.rb', line 463

def scope=(scope)
  validate_scope(scope)
  self.scope_without_validation = scope
end

.scope_without_validation= ⇒ Object 



462
 
# File 'lib/active_ldap/base.rb', line 462

alias_method :scope_without_validation=, :scope=

.self_and_descendants_from_active_ldap ⇒ Object 



530
531
532
533
534
535
536
537
538
539
 
# File 'lib/active_ldap/base.rb', line 530

def self_and_descendants_from_active_ldap
  klass = self
  classes = [klass]
  while klass != klass.base_class
    classes << klass = klass.superclass
  end
  classes
rescue
  [self]
end

.setup_connection(config = nil) ⇒ Object

Set LDAP connection configuration up. It doesn't connect and bind to LDAP server. A connection to LDAP server is created when it's needed.

== +config+ +config+ must be a hash that may contain any of the following fields: :password_block, :logger, :host, :port, :base, :bind_dn, :try_sasl, :allow_anonymous :bind_dn specifies the DN to bind with. :password_block specifies a Proc object that will yield a String to be used as the password when called. :logger specifies a logger object (Logger, Log4r::Logger and s on) :host sets the LDAP server hostname :port sets the LDAP server port :base overwrites Base.base - this affects EVERYTHING :try_sasl indicates that a SASL bind should be attempted when binding to the server (default: false) :sasl_mechanisms is an array of SASL mechanism to try (default: ["GSSAPI", "CRAM-MD5", "EXTERNAL"]) :allow_anonymous indicates that a true anonymous bind is allowed when trying to bind to the server (default: true) :retries - indicates the number of attempts to reconnect that will be undertaken when a stale connection occurs. -1 means infinite. :sasl_quiet - if true, sets @sasl_quiet on the Ruby/LDAP connection :method - whether to use :ssl, :tls, or :plain (unencrypted) :retry_wait - seconds to wait before retrying a connection :scope - dictates how to find objects. ONELEVEL by default to avoid dn_attr collisions across OUs. Think before changing. :timeout - time in seconds - defaults to disabled. This CAN interrupt search() requests. Be warned. :retry_on_timeout - whether to reconnect when timeouts occur. Defaults to true See lib/active_ldap/configuration.rb for defaults for each option



381
382
383
384
385
 
# File 'lib/active_ldap/base.rb', line 381

def setup_connection(config=nil)
  super
  ensure_logger
  nil
end

.validate_scope(scope) ⇒ Object

Raises:



468
469
470
471
472
473
 
# File 'lib/active_ldap/base.rb', line 468

def validate_scope(scope)
  scope = scope.to_sym if scope.is_a?(String)
  return if scope.nil? or scope.is_a?(Symbol)
  raise ConfigurationError,
          _("scope '%s' must be a Symbol") % scope.inspect
end

Instance Method Details

#==(comparison_object) ⇒ Object

Returns true if the +comparison_object+ is the same object, or is of the same type and has the same dn.



716
717
718
719
720
721
 
# File 'lib/active_ldap/base.rb', line 716

def ==(comparison_object)
  comparison_object.equal?(self) or
    (comparison_object.instance_of?(self.class) and
     comparison_object.dn == dn and
     !comparison_object.new_entry?)
end

#[](name, force_array = false) ⇒ Object 



912
913
914
915
916
917
918
 
# File 'lib/active_ldap/base.rb', line 912

def [](name, force_array=false)
  if name == "dn"
    array_of(dn, force_array)
  else
    get_attribute(name, force_array)
  end
end

#[]=(name, value) ⇒ Object 



920
921
922
 
# File 'lib/active_ldap/base.rb', line 920

def []=(name, value)
  set_attribute(name, value)
end

#assign_attributes(new_attributes) ⇒ Object 



849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
 
# File 'lib/active_ldap/base.rb', line 849

def assign_attributes(new_attributes)
  return if new_attributes.blank?

  _schema = _local_entry_attribute = nil
  targets = sanitize_for_mass_assignment(new_attributes)
  have_dn = false
  dn_value = nil
  targets.each do |key, value|
    setter = "#{key}="
    unless respond_to?(setter)
      _schema ||= schema
      attribute = _schema.attribute(key)
      next if attribute.id.nil?
      _local_entry_attribute ||= local_entry_attribute
      _local_entry_attribute.register(attribute)
    end
    case setter
    when "dn=", "id="
      have_dn = true
      dn_value = value
    else
      send(setter, value)
    end
  end
  self.dn = dn_value if have_dn
end

#attribute_names(normalize = false) ⇒ Object

attributes

Return attribute methods so that a program can determine available attributes dynamically without schema awareness



758
759
760
 
# File 'lib/active_ldap/base.rb', line 758

def attribute_names(normalize=false)
  entry_attribute.names(normalize)
end

#attribute_present?(name) ⇒ Boolean

Returns:

  • (Boolean) 


762
763
764
765
 
# File 'lib/active_ldap/base.rb', line 762

def attribute_present?(name)
  values = get_attribute(name, true)
  !values.empty? or values.any? {|x| !(x and x.empty?)}
end

#attributes ⇒ Object

This returns the key value pairs in @data with all values cloned



833
834
835
836
 
# File 'lib/active_ldap/base.rb', line 833

def attributes
  @simplified_data ||= simplify_data(@data)
  @simplified_data.clone
end

#attributes=(new_attributes) ⇒ Object

This allows a bulk update to the attributes of a record without forcing an immediate save or validation.

It is unwise to attempt objectClass updates this way. Also be sure to only pass in key-value pairs of your choosing. Do not let URL/form hackers supply the keys.



844
845
846
847
 
# File 'lib/active_ldap/base.rb', line 844

def attributes=(new_attributes)
  return if new_attributes.blank?
  assign_attributes(new_attributes)
end

#base ⇒ Object 



976
977
978
 
# File 'lib/active_ldap/base.rb', line 976

def base
  @base ||= compute_base
end

#base=(object_local_base) ⇒ Object 



980
981
982
983
984
985
 
# File 'lib/active_ldap/base.rb', line 980

def base=(object_local_base)
  ensure_update_dn
  @dn = nil
  @base = nil
  @base_value = object_local_base
end

#bind(config_or_password = {}, config_or_ignore = nil, &block) ⇒ Object 



924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
 
# File 'lib/active_ldap/base.rb', line 924

def bind(config_or_password={}, config_or_ignore=nil, &block)
  if config_or_password.is_a?(String)
    config = (config_or_ignore || {}).merge(:password => config_or_password)
  else
    config = config_or_password
  end
  config = {:bind_dn => dn, :allow_anonymous => false}.merge(config)
  config[:password_block] ||= block if block_given?
  setup_connection(config)

  before_connection = @connection
  begin
    @connection = nil
    connection.connect
    @connection = connection
    clear_connection_based_cache
    clear_association_cache
  rescue ActiveLdap::Error
    remove_connection
    @connection = before_connection
    raise
  end
  true
end

#clear_connection_based_cache ⇒ Object 



949
950
951
952
953
 
# File 'lib/active_ldap/base.rb', line 949

def clear_connection_based_cache
  @schema = nil
  @local_entry_attribute = nil
  clear_object_class_based_cache
end

#clear_object_class_based_cache ⇒ Object 



955
956
957
958
959
 
# File 'lib/active_ldap/base.rb', line 955

def clear_object_class_based_cache
  @entry_attribute = nil
  @real_names = {}
  clear_changes_information
end

#clear_removed_attributes_data(removed_attributes) ⇒ Object 



961
962
963
964
965
966
967
968
969
970
 
# File 'lib/active_ldap/base.rb', line 961

def clear_removed_attributes_data(removed_attributes)
  return if removed_attributes.empty?
  removed_entry_attribute = EntryAttribute.new(nil, [])
  removed_attributes.each do |attribute|
    removed_entry_attribute.register(attribute)
  end
  @data.reject! do |key, _|
    removed_entry_attribute.exist?(key)
  end
end

#default_search_attribute ⇒ Object 



809
810
811
 
# File 'lib/active_ldap/base.rb', line 809

def default_search_attribute
  self.class.default_search_attribute
end

#delete_all(options = {}) ⇒ Object 



997
998
999
 
# File 'lib/active_ldap/base.rb', line 997

def delete_all(options={})
  super({:base => dn}.merge(options || {}))
end

#destroy_all(options = {}) ⇒ Object 



1001
1002
1003
 
# File 'lib/active_ldap/base.rb', line 1001

def destroy_all(options={})
  super({:base => dn}.merge(options || {}))
end

#dn ⇒ Object

dn

Return the authoritative dn



778
779
780
 
# File 'lib/active_ldap/base.rb', line 778

def dn
  @dn ||= compute_dn
end

#dn=(value) ⇒ Object Also known as: id= 



797
798
799
 
# File 'lib/active_ldap/base.rb', line 797

def dn=(value)
  set_attribute(dn_attribute_with_fallback, value)
end

#dn_attribute ⇒ Object 



803
804
805
806
807
 
# File 'lib/active_ldap/base.rb', line 803

def dn_attribute
  ensure_update_dn
  _dn_attribute = @dn_attribute || dn_attribute_of_class
  to_real_attribute_name(_dn_attribute) || _dn_attribute
end

#dn_attribute_of_class ⇒ Object 



802
 
# File 'lib/active_ldap/base.rb', line 802

alias_method(:dn_attribute_of_class, :dn_attribute)

#eql?(comparison_object) ⇒ Boolean

Delegates to ==

Returns:

  • (Boolean) 


724
725
726
 
# File 'lib/active_ldap/base.rb', line 724

def eql?(comparison_object)
  self == (comparison_object)
end

#exist? ⇒ Boolean Also known as: exists?

exist?

Return whether the entry exists in LDAP or not

Returns:

  • (Boolean) 


770
771
772
 
# File 'lib/active_ldap/base.rb', line 770

def exist?
  self.class.exists?(dn)
end

#hash ⇒ Object

Delegates to id in order to allow two records of the same type and id to work with something like: [ User.find("a"), User.find("b"), User.find("c") ] & [ User.find("a"), User.find("d") ] # => [ User.find("a") ]



732
733
734
735
736
737
738
739
740
741
742
743
744
 
# File 'lib/active_ldap/base.rb', line 732

def hash
  return super if @_hashing # workaround for GetText :<
  _dn = nil
  begin
    @_hashing = true
    _dn = dn
  rescue DistinguishedNameInvalid, DistinguishedNameNotSetError
    return super
  ensure
    @_hashing = false
  end
  _dn.hash
end

#have_attribute?(name, except = []) ⇒ Boolean Also known as: has_attribute?

Returns:

  • (Boolean) 


906
907
908
909
 
# File 'lib/active_ldap/base.rb', line 906

def have_attribute?(name, except=[])
  real_name = to_real_attribute_name(name)
  !real_name.nil? and !except.include?(real_name)
end

#id ⇒ Object 



782
783
784
 
# File 'lib/active_ldap/base.rb', line 782

def id
  get_attribute(dn_attribute_with_fallback)
end

#inspect ⇒ Object 



1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
 
# File 'lib/active_ldap/base.rb', line 1005

def inspect
  object_classes = entry_attribute.object_classes
  inspected_object_classes = object_classes.collect do |object_class|
    object_class.name
  end.join(', ')
  must_attributes = must.collect(&:name).sort.join(', ')
  may_attributes = may.collect(&:name).sort.join(', ')
  inspected_attributes = attribute_names.sort.collect do |name|
    inspect_attribute(name)
  end.join(', ')
  result = "\#<#{self.class} objectClass:<#{inspected_object_classes}>, "
  result << "must:<#{must_attributes}>, may:<#{may_attributes}>, "
  result << "#{inspected_attributes}>"
  result
end

#may ⇒ Object 



746
747
748
 
# File 'lib/active_ldap/base.rb', line 746

def may
  entry_attribute.may
end

#must ⇒ Object 



750
751
752
 
# File 'lib/active_ldap/base.rb', line 750

def must
  entry_attribute.must
end

#schema ⇒ Object 



972
973
974
 
# File 'lib/active_ldap/base.rb', line 972

def schema
  @schema ||= super
end

#scope ⇒ Object 



988
989
990
 
# File 'lib/active_ldap/base.rb', line 988

def scope
  @scope || scope_of_class
end

#scope=(scope) ⇒ Object 



992
993
994
995
 
# File 'lib/active_ldap/base.rb', line 992

def scope=(scope)
  self.class.validate_scope(scope)
  @scope = scope
end

#scope_of_class ⇒ Object 



987
 
# File 'lib/active_ldap/base.rb', line 987

alias_method :scope_of_class, :scope

#to_key ⇒ Object

Returns this entity’s dn wrapped in an Array or nil if the entity' s dn is not set.



791
792
793
794
795
 
# File 'lib/active_ldap/base.rb', line 791

def to_key
  [dn]
rescue DistinguishedNameNotSetError
  nil
end

#to_ldif ⇒ Object 



880
881
882
 
# File 'lib/active_ldap/base.rb', line 880

def to_ldif
  Ldif.new([to_ldif_record]).to_s
end

#to_ldif_record ⇒ Object 



876
877
878
 
# File 'lib/active_ldap/base.rb', line 876

def to_ldif_record
  super(dn, normalize_data(@data))
end

#to_param ⇒ Object 



786
787
788
 
# File 'lib/active_ldap/base.rb', line 786

def to_param
  id
end

#to_s ⇒ Object 



902
903
904
 
# File 'lib/active_ldap/base.rb', line 902

def to_s
  to_ldif
end

#to_xml(options = {}) ⇒ Object 



884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
 
# File 'lib/active_ldap/base.rb', line 884

def to_xml(options={})
  options = options.dup
  options[:root] ||= (self.class.name || '').underscore
  options[:root] = 'anonymous' if options[:root].blank?
  [:only, :except].each do |attribute_names_key|
    names = options[attribute_names_key]
    next if names.nil?
    options[attribute_names_key] = names.collect do |name|
      if name.to_s.downcase == "dn"
        "dn"
      else
        to_real_attribute_name(name)
      end
    end.compact
  end
  XML.new(dn, normalize_data(@data), schema).to_s(options)
end

#update_attribute(name, value) ⇒ Object

Updates a given attribute and saves immediately



814
815
816
817
 
# File 'lib/active_ldap/base.rb', line 814

def update_attribute(name, value)
  send("#{name}=", value)
  save
end

#update_attributes(attrs) ⇒ Object

This performs a bulk update of attributes and immediately calls #save.



821
822
823
824
 
# File 'lib/active_ldap/base.rb', line 821

def update_attributes(attrs)
  self.attributes = attrs
  save
end

#update_attributes!(attrs) ⇒ Object 



826
827
828
829
 
# File 'lib/active_ldap/base.rb', line 826

def update_attributes!(attrs)
  self.attributes = attrs
  save!
end