activeldap.rb in ruby-activeldap-0.4.4

- old
+ new

@@ -1,10 +1,9 @@
 #!/usr/bin/ruby -W0
 # = Ruby/ActiveLDAP 
 #
 # "Ruby/ActiveLDAP" Copyright (C) 2004 Will Drewry mailto:will@alum.bu.edu
-# Documentation Version 0.3
 #
 # == Introduction
 # 
 # Ruby/ActiveLDAP is a novel way of interacting with LDAP.  Most interaction with
 # LDAP is done using clunky LDIFs, web interfaces, or with painful APIs that
@@ -212,10 +211,15 @@
 # to define what attributes a LDAP object may have. Ruby/ActiveLDAP needs to know
 # what classes are required when creating a new object.  Of course, you can leave
 # that field out to default to ['top'] only.  Then you can let each application
 # choose what objectClasses their objects should have by calling the method e.g.
 # Group#objectClass=(value).
+#
+# Note that is can be very important to define the default :classes value. Due to
+# implementation choices with most LDAP servers, once an object is created, its
+# structural objectclasses may not be removed (or replaced).  Setting a sane default
+# may help avoid programmer error later.
 # 
 # :classes isn't the only optional argument.  If :dnattr is left off, it defaults
 # to 'cn'.  If :prefix is left off, it will default to 'ou=CLASSNAME'. In this
 # case, it would be 'ou=Group'.
 # 
@@ -677,25 +681,33 @@
 # So that's a lot to take in. Here's what is going on. I just set the LDAP 
 # object's cn to "wad" and cn:lang-en-us to ["wad", "Will Drewry"].
 # Anytime a LDAP subtype is required, you must encapsulate the data in a Hash.
 #
 # But wait a minute, I just read in a binary certificate without wrapping it up.
-# So any binary attribute will automagically get wrapped in {'binary' => value}
-# if you don't do it. This keeps your #writes from breaking, and my code from
-# crying.  For correctness, I could have easily done the following:
+# So any binary attribute _that requires ;binary subtyping_ will automagically 
+# get wrapped in {'binary' => value} if you don't do it. This keeps your #writes 
+# from breaking, and my code from crying.  For correctness, I could have easily 
+# done the following:
 #
 #   irb>  user.userCertificate = {'binary' => File.read('example.der')}
 #
-# Really, it's up to you. The only subtypes defined in LDAPv3 are lang-* and
-# binary.  These can be nested through:
+# You should note that some binary data does not use the binary subtype all the time.
+# One example is jpegPhoto. You can use it as jpegPhoto;binary or just as jpegPhoto.
+# Since the schema dictates that it is a binary value, Ruby/ActiveLDAP will write
+# it as binary, but the subtype will not be automatically appended as above. The
+# use of the subtype on attributes like jpegPhoto is ultimately decided by the 
+# LDAP site policy and not by any programmatic means.
 #
+# The only subtypes defined in LDAPv3 are lang-* and binary.  These can be nested
+# though:
+#
 #  irb> user.cn = [{'lang-JP-jp' => {'binary' => 'somejp'}}]
 # 
 # As I understand it, OpenLDAP does not support nested subtypes, but some
 # documentation I've read suggests that Netscape's LDAP server does. I only
-# have access to OpenLDAP. If anyone tests thisout, please let me know how it 
-# goes!.
+# have access to OpenLDAP. If anyone tests this out, please let me know how it 
+# goes!
 #
 #
 # And that pretty much wraps up this section.
 #
 # ==== Further integration with your environment aka namespacing
@@ -878,10 +890,10 @@
 require 'activeldap/associations'
 require 'activeldap/configuration'
 require 'activeldap/schema2'
 
 module ActiveLDAP
-  VERSION = "0.4.3"
+  VERSION = "0.4.4"
 end
 
 ActiveLDAP::Base.class_eval do
   include ActiveLDAP::Configuration
   include ActiveLDAP::Associations