undeprecated Net::LDAP#modify.

This commit is contained in:
blackhedd 2006-08-05 15:20:18 +00:00
parent f96e4ff4fa
commit ad24ad979d
3 changed files with 31 additions and 40 deletions

View file

@ -1,5 +1,9 @@
= Net::LDAP Changelog = 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 == Net::LDAP 0.0.3: July 26, 2006
* Added simple TLS encryption. * Added simple TLS encryption.
Thanks to Garett Shulman for suggestions and for helping test. Thanks to Garett Shulman for suggestions and for helping test.

View file

@ -1,40 +1,16 @@
We're pleased to announce version 0.0.3 of Net::LDAP, the first We're pleased to announce version 0.0.4 of Net::LDAP, the first
pure-Ruby LDAP library. Net::LDAP intends to be a feature-complete pure-Ruby LDAP library.
LDAP client which can access as much as possible of the functionality
of the most-used LDAP server implementations. This library does This version un-deprecates Net::LDAP#modify, which can be useful with
not wrap any existing native-code LDAP libraries, creates no 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. 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) If anyone wants to contribute suggestions, insights or (especially)
code, please email me at garbagecat10 .. .. gmail.com. code, please email me at garbagecat10 .. .. gmail.com.

View file

@ -757,8 +757,6 @@ module Net
end end
# _DEPRECATED_ - Please use #add_attribute, #replace_attribute, or #delete_attribute.
#
# Modifies the attribute values of a particular entry on the LDAP directory. # Modifies the attribute values of a particular entry on the LDAP directory.
# Takes a hash with arguments. Supported arguments are: # Takes a hash with arguments. Supported arguments are:
# :dn :: (the full DN of the entry whose attributes are to be modified) # :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 # succeeded or failed, with extended information available by calling
# #get_operation_result. # #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 # 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 # for changing the values of attributes, but they are necessarily somewhat complex
# and not always intuitive. If these instructions are confusing or incomplete, # 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 :add operator will, unsurprisingly, add the specified values to
# the specified attribute. If the attribute does not already exist, # the specified attribute. If the attribute does not already exist,
# :add will create it. Most LDAP servers will generate an error if you # :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, # :replace will erase the current value(s) for the specified attribute,
# if there are any, and replace them with the specified value(s). # if there are any, and replace them with the specified value(s).
# #
# :delete will remove the specified value(s) from the specified attribute. # :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 # 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: # For example:
# #
@ -808,13 +810,14 @@ module Net
# <i>(This example is contrived since you probably wouldn't add a mail # <i>(This example is contrived since you probably wouldn't add a mail
# value right before replacing the whole attribute, but it shows that order # 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 # of execution matters. Also, many LDAP servers won't let you delete SN
# because it would be a schema violation.)</i> # because that would be a schema violation.)</i>
# #
# It's essential to keep in mind that if you specify more than one operation in # 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 # a call to #modify, most LDAP servers will attempt to perform all of the operations
# in the order you gave them. # in the order you gave them.
# This matters because you may specify operations on the # This matters because you may specify operations on the
# same attribute which must be performed in a certain order. # same attribute which must be performed in a certain order.
#
# Most LDAP servers will _stop_ processing your modifications if one of them # Most LDAP servers will _stop_ processing your modifications if one of them
# causes an error on the server (such as a schema-constraint violation). # 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 # 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 # not be "rolled back," resulting in a partial update. This is a limitation
# of the LDAP protocol, not of Net::LDAP. # 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 def modify args
if @open_connection if @open_connection