From ad24ad979d77f6e1249813bd61a100ad83457901 Mon Sep 17 00:00:00 2001 From: blackhedd Date: Sat, 5 Aug 2006 15:20:18 +0000 Subject: [PATCH] undeprecated Net::LDAP#modify. --- ChangeLog | 4 ++++ Release-Announcement | 46 +++++++++++--------------------------------- lib/net/ldap.rb | 21 +++++++++++++++----- 3 files changed, 31 insertions(+), 40 deletions(-) diff --git a/ChangeLog b/ChangeLog index 44df06d..6bea4ce 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,9 @@ = Net::LDAP Changelog +== Net::LDAP 0.0.4: August xx, 2006 +* Undeprecated Net::LDAP#modify. Thanks to Justin Forder for + providing the rationale for this. + == Net::LDAP 0.0.3: July 26, 2006 * Added simple TLS encryption. Thanks to Garett Shulman for suggestions and for helping test. diff --git a/Release-Announcement b/Release-Announcement index effd985..3ff4020 100644 --- a/Release-Announcement +++ b/Release-Announcement @@ -1,40 +1,16 @@ -We're pleased to announce version 0.0.3 of Net::LDAP, the first -pure-Ruby LDAP library. Net::LDAP intends to be a feature-complete -LDAP client which can access as much as possible of the functionality -of the most-used LDAP server implementations. This library does -not wrap any existing native-code LDAP libraries, creates no +We're pleased to announce version 0.0.4 of Net::LDAP, the first +pure-Ruby LDAP library. + +This version un-deprecates Net::LDAP#modify, which can be useful with +LDAP servers that observe non-standard transactional and concurrency +semantics in LDAP Modify operations. Note: this is a documentation change, +not a code change. + +Net::LDAP is a feature-complete LDAP client which can access as much as +possible of the functionality of the most-used LDAP server implementations. +This library does not wrap any existing native-code LDAP libraries, creates no Ruby extensions, and has no dependencies external to Ruby. -Version 0.0.3 adds support for encrypted communications to LDAP servers. -There is a new optional parameter for Net::LDAP#new and Net::LDAP#open -that allows you to specify encryption characteristics. Here's a quick -example: - - require 'net/ldap' - ldap = Net::LDAP.new( - :host => "an_ip_address", - :port => 636, - :auth => {:method => :simple, :username => "mickey", :password => "mouse" }, - :encryption => {:method => :simple_tls} - ) - ldap.bind or raise "bind failed" - ldap.search( ... ) - # etc, etc. - -This release supports simple TLS encryption with no client or server -validation. Future versions will add support for the STARTTLS control, -and for certificate validation. Additional parameters will appear to -support these options. - -Net::LDAP encryption requires Ruby's openssl library. We're not -quite sure what happens when this library is present but the underlying -OpenSSL libraries are missing or not configured appropriately, -especially on back versions of Ruby. If anyone encounters problems -using encryption in Net::LDAP, please let us know and give us the -details of your platform and Ruby build info. - -Thanks to Garett Shulman for helping to test the new code. - If anyone wants to contribute suggestions, insights or (especially) code, please email me at garbagecat10 .. .. gmail.com. diff --git a/lib/net/ldap.rb b/lib/net/ldap.rb index 414f02a..e0214a3 100644 --- a/lib/net/ldap.rb +++ b/lib/net/ldap.rb @@ -757,8 +757,6 @@ module Net end - # _DEPRECATED_ - Please use #add_attribute, #replace_attribute, or #delete_attribute. - # # Modifies the attribute values of a particular entry on the LDAP directory. # Takes a hash with arguments. Supported arguments are: # :dn :: (the full DN of the entry whose attributes are to be modified) @@ -768,6 +766,9 @@ module Net # succeeded or failed, with extended information available by calling # #get_operation_result. # + # Also see #add_attribute, #replace_attribute, or #delete_attribute, which + # provide simpler interfaces to this functionality. + # # The LDAP protocol provides a full and well thought-out set of operations # for changing the values of attributes, but they are necessarily somewhat complex # and not always intuitive. If these instructions are confusing or incomplete, @@ -786,14 +787,15 @@ module Net # The :add operator will, unsurprisingly, add the specified values to # the specified attribute. If the attribute does not already exist, # :add will create it. Most LDAP servers will generate an error if you - # to add a value that already exists. + # try to add a value that already exists. # # :replace will erase the current value(s) for the specified attribute, # if there are any, and replace them with the specified value(s). # # :delete will remove the specified value(s) from the specified attribute. # If you pass nil, an empty string, or an empty array as the value parameter - # to a :delete operation, the _entire_ _attribute_ will be deleted. + # to a :delete operation, the _entire_ _attribute_ will be deleted, along + # with all of its values. # # For example: # @@ -808,13 +810,14 @@ module Net # (This example is contrived since you probably wouldn't add a mail # value right before replacing the whole attribute, but it shows that order # of execution matters. Also, many LDAP servers won't let you delete SN - # because it would be a schema violation.) + # because that would be a schema violation.) # # It's essential to keep in mind that if you specify more than one operation in # a call to #modify, most LDAP servers will attempt to perform all of the operations # in the order you gave them. # This matters because you may specify operations on the # same attribute which must be performed in a certain order. + # # Most LDAP servers will _stop_ processing your modifications if one of them # causes an error on the server (such as a schema-constraint violation). # If this happens, you will probably get a result code from the server that @@ -825,6 +828,14 @@ module Net # not be "rolled back," resulting in a partial update. This is a limitation # of the LDAP protocol, not of Net::LDAP. # + # The lack of transactional atomicity in LDAP means that you're usually + # better off using the convenience methods #add_attribute, #replace_attribute, + # and #delete_attribute, which are are wrappers over #modify. However, certain + # LDAP servers may provide concurrency semantics, in which the several operations + # contained in a single #modify call are not interleaved with other + # modification-requests received simultaneously by the server. + # It bears repeating that this concurrency does _not_ imply transactional + # atomicity, which LDAP does not provide. # def modify args if @open_connection