Release Notes
Version 2.3.7
The following changes were made between the 2.3.6 and 2.3.7 releases:
-
Add the ability to perform validation on an SSLSocket immediately
after its establishment (regardless of whether the connection was initially
secured via SSL/TLS or secured after the fact with the StartTLS extended
operation). This can be used to better perform hostname validation in a
more secure manner than was otherwise available through the trust manager
framework. Also, add the ability to get access to the SSLSession
associated with a connection that has been secured via SSL/TLS or StartTLS.
-
Make a number of updates to GSSAPI support, including the ability to specify the
JAAS client name (which allows the use of a single JAAS configuration file with
a number of different configurations), the ability to customize the use of a
property indicating whether to allow credentials from outside the current
subject, and to suppress the alteration of a specified set of system properties
in the event that they had already been set by some other mechanism.
-
Add a new server set that can use round-robin DNS configurations to support
hostnames that resolve to multiple IP addresses. The selection of which IP
address to use for a given connection may be made at random, in round-robin
order, or based on the order in which the addresses were returned from the name
service.
-
Update the connection pool to add a method that can be used to shrink the
current size of the pool to a specified number of connections. This will have
no effect on the maximum size of the pool, but can reduce the number of
established connections if an earlier spike in utilization resulted in the
creation of a number of extra connections that are no longer needed.
-
Update the persistence framework to improve support for classes marked with
@LDAPObject that are subclasses of other classes marked with
@LDAPObject. If a subclass does not define any RDN fields or getters,
they will now be inherited from a superclass. If a subclass does not define any
default parent DN, then it will be inherited from a superclass. DN fields and
entry fields defined in superclasses will now be properly handled. The set of
attributes to request for inclusion in search result entries will also be
properly aggregated from all superclasses.
-
Update the in-memory directory server to make it possible to reject anonymous
binds, whether via simple or SASL authentication. Note, however, that the
effect net effect on the authenticated state of the connection will be the same
as if it were successful, since a failed bind always results in an
unauthenticated connection.
-
Update the in-memory directory server to add a new interceptor API. This API
can be used to alter client requests before they are processed by the server,
and to alter responses before they are returned to the client.
-
Update the DNS SRV record server set to make it possible to customize the set of
properties used to initialize the JNDI context to use when interacting with the
DNS server.
-
Add a new rate adjustor utility class that can be used in conjunction with the
fixed-rate barrier to adjust the rate over time based on a specified definition.
The searchrate, modrate, authrate, and search-and-mod-rate tools have been
updated to provide a new "--variableRateData" argument that makes it
possible to use this feature in conjunction with those tools.
-
Add the ability to programmatically interrupt the searchrate, modrate, authrate,
and search-and-mod-rate tools.
-
Update the logic used for automatic referral following so that if a referral is
received over a connection secured via StartTLS, then the connection established
to follow that referral will also be secured via StartTLS.
-
Fix a bug in the code responsible for automatically re-establishing a connection
if it becomes disconnected (which is only attempted if auto-reconnect is enabled
in the connection options). If the connection had been secured with StartTLS,
the re-established connection was previously not secured in the same way.
-
Fix a bug that could prevent active asynchronous operations from being notified
if the connection becomes disconnected. Also, fix a bug that could prevent the
connection reader thread from waiting on a response to an asynchronous operation
that has timed out or been abandoned.
-
Fix a bug that could prevent parsing a DN or RDN that contains a zero-length
attribute value.
-
Make it easier to build the LDAP SDK with an external version of Apache ant
rather than the one included in the repository. Also, make it possible to
build without invoking the checkstyle tool.
Version 2.3.6
The following changes were made between the 2.3.5 and 2.3.6 releases:
-
Update the LDAPConnectionPool class to make it possible to specify a
health check that should be used for the initial set of connections established
when the pool is created.
-
Update the LDIF change record implementations to include support for change
records with request controls.
-
Update the GSSAPI and DIGEST-MD5 SASL mechanisms to provide support for the
auth-int and auth-conf quality of protection modes.
-
Update the DIGEST-MD5 SASL mechanism so that if the caller does not explicitly
specify a realm but the server suggests a default realm, the default realm will
be used.
-
Update the framework for processing asynchronous operations to make it more
convenient to invoke an add, compare, delete, modify, or modify DN operation in
cases in which the result will be obtained through the
java.util.concurrent.Future API and no async result listener is
desired.
-
Add a new processRequestsAsync method to connection pool
implementations that can be used to cause multiple asynchronous add, compare,
delete, modify, modify DN, and/or search operations to be processed concurrently
on the same pooled connection.
-
Update the LDAPThreadLocalConnectionPool.getConnection method to use
the LDAPConnection,isConnected method to provide additional
verification that the connection is still established before returning it to
the caller.
-
Fix a bug in the in-memory directory server support for the post-read response
control that caused the post-read entry to be generated before some updates
(e.g., those for operational attributes like modifiersName and modifyTimestamp)
had been processed.
-
Fix a potential thread safety bug in the get entry connection pool health check.
-
Add convenience constructors to make it easier to create a bind result, compare
result, or extended result from an LDAPException.
-
Add a convenience method that can be used to extract a password expired control
from an LDAPException just as easily as from an LDAPResult.
Version 2.3.5
The following changes were made between the 2.3.4 and 2.3.5 releases:
-
Fix a bug in the LDIF writer that could cause it to write the original entry
rather than a new entry generated by an LDIFWriterEntryTranslator.
-
Fix a bug that could cause the LDAP SDK to enter an infinite loop when attempting
to read data from a malformed intermediate response.
-
Fix a bug in the parsing and generation of the string representation of search
filters that contain non-UTF-8 data.
-
Ensure that the LDIF representation of modify change records includes a trailing
dash after the last change, in strict accordance with the LDIF specification in
RFC 2849.
-
Update the LDIF writer to add a new writeVersionHeader method that can
be used to ensure that the "version: 1" header is written to the LDIF
output. In addition, the LDIF reader's static decodeEntry and
decodeChangeRecord methods have been updated to handle the case in which
the provided entry or change record has a first line that is the version header.
The LDIF reader already handled this header in normal parsing, but the static
methods that could be used for decoding individual records did not properly
support this capability.
-
Update the in-memory directory server to provide support for enforcing a maximum
search size limit.
-
Improve debugging support for response messages for connections operating in
synchronous mode.
-
Dramatically improve code examples included in class-level javadoc comments. All
code examples are now covered by unit tests to ensure that the code is valid, and
many of the examples have been improved to be more useful and production quality.
-
Add a new FewestConnectionServerSet class that can be used to cause
connections to be established to the server with the fewest number of established
connections (based only on connections already created by that server set
instance). This can help ensure that the distribution of connections across
multiple servers remains relatively even.
-
Update the FailoverServerSet to make it possible to specify an alternate
maximum connection age that will be used for "failover" connections (i.e.,
connections established to any server except the first server in the list, or that
are created using any server set other than the first set in the list). This will
only have any effect if the server set is used to create an
LDAPConnectionPool, but it can be used to help ensure a faster fail-back
to a "preferred" configuration after a connection failure is encountered.
-
Add a new LDAPConnection.getLastCommunicationTime method that can be
used to determine the time that the connection was last used to send a request or
read a response (and therefore determine how long the connection has been idle).
-
Add a new LDAPConnectionPool.getConnection method that can be used to
request a connection to a particular server by providing the address and port of
the target server. This is primarily useful when the connection pool may contain
connections to multiple servers, but a specific server is desired for handling a
particular request.
-
Add a new LDAPConnectionPool.discardConnection method that can be used
to indicate that the provided connection is no longer needed and should be
closed without creating a new connection to take its place. This can be used to
reduce the number of connections in the pool if desired.
-
Update the connection pool so that by default, connections will be closed and
re-established as a result of the maximum connection age only by the background
health check. Previously, the pool would also check the age of a connection
whenever that connection was released back to the pool, but in busy applications
this could result in multiple connections being closed and re-established
concurrently, which could have a significant performance impact on the directory
server.
-
Update the connection pool so that it is possible to set a different maximum
connection age for connections that were created to replace defunct connections
than connections that were created under normal conditions. This can help
ensure a faster fail-back to a more normal allocation of connections in a pool
that may have connections balanced across multiple servers.
-
Add new addAttribute and setAttribute methods to the entry
class that make it possible to specify multiple string values for the attributes
using a collection.
-
Add two new example tools: identify-references-to-missing-entries (which can be
used to identify any entries which contain attributes whose values are DNs that
reference nonexistent entries), and identify-unique-attribute-conflicts (which
can be used to identify any values for an attribute or set of attributes that
appear in multiple entries).
-
Provide a more useful error message if a client-side timeout is encountered while
waiting for the response to a request. Previously, this message would only
include the type of operation that timed out. It now also includes the LDAP
message ID for the operation, as well as additional operation-specific
information about the request.
-
Provide a more useful error message if a problem is encountered during SASL bind
processing when one or more unhandled callbacks were encountered during
processing.
-
Update the GSSAPI bind request to make it possible to specify a server name that
is different from the address used to establish the connection to that server.
-
Define a new system property that can be used to specify the default SSL/TLS
protocol that should be used for secure communication. It is still possible to
programmatically specify the default protocol using the
SSLUtil.setDefaultSSLProtocol method.
-
Add the ability to provide an SSLSocketFactory as an alternative to an
SSLContext when creating a StartTLS extended request.
-
Update the StartTLS post-connect processor to include a client-side timeout in
the StartTLS extended request if appropriate.
-
Update the prompt trust manager to make it possible to determine whether the
trust manager would interactively prompt the user about a certificate.
-
Omit the "entriesReturned" and "referencesReturned" elements from the string
representation of a search result if those values are not known. Previously,
these elements would be included with a value of "-1" in such cases.
Version 2.3.4
The following changes were made between the 2.3.3 and 2.3.4 releases:
-
A bug in the Oracle javadoc tool (as described in
VU#225657) could cause
javadoc documentation generated by vulnerable versions of that tool to include a
javascript flaw that could allow an attacker to craft a URI that could cause an
arbitrary page to be displayed. The LDAP SDK javadoc documentation is now
generated with an updated version of the javadoc tool that no longer contains
this vulnerability.
-
Fix a connection pool bug that could cause a connection to be unnecessarily
closed and re-established in the course of processing a simple bind operation if
the connection was configured to operate in synchronous mode.
-
Fix a bug in the LDAP SDK schema parser that could prevent it from properly
decoding schema elements in which the closing parenthesis immediately followed an
OBSOLETE, SINGLE-VALUE, or NO-USER-MODIFICATION token without a space between the
token and the parenthesis.
-
Change the way the LDAP SDK maintains disconnect information to eliminate a
potential code flow that could allow multiple disconnect notifications for a
single disconnect.
-
Add support for the Microsoft DirSync control that may be used with Active
Directory in order to obtain information about changes that have been processed
in the server.
-
Fix a bug in the entry validator class that could cause it to incorrectly
classify entries with multiple structural object classes as entries that were
missing a structural object class.
-
The LDAP command-line tool API has been updated so to provide new
"--promptForBindPassword", "--promptForKeyStorePassword", and
"--promptForTrustStorePassword" arguments. These arguments may allow the
associated password to be interactively provided by the end user in a secure
manner as an alternative to requiring the password to be provided as a
command-line argument or stored in a clear-text file.
-
The LDAP command-line tool API has been updated to make it possible to create
tools that do not offer arguments for simple or SASL authentication. This can
allow creating tools that may need to establish only unauthenticated connections.
-
Improve the argument validation used by LDAP command-line tools to help
avoid problems that result from arguments provided when they are not needed.
Version 2.3.3
The following changes were made between the 2.3.2 and 2.3.3 releases:
-
Fix a problem with the CSS file used to generate javadoc documentation that could
cause it to appear malformed when built with Java SE 7, even though it looked
fine when built with Java SE 6.
Version 2.3.2
The following changes were made between the 2.3.1 and 2.3.2 releases:
-
Update the LDAPConnectionPool class to make it possible to successfully
create a connection pool even if a failure is encountered while attempting to
establish one or more of the initial connections.
-
Update the LDAPConnectionPool class to make it possible to use multiple
threads to establish the initial set of connections more quickly. This can
dramatically reduce the length of time required to create a pool, especially
when establishing a large number of connections and/or when connecting to a
remote or slow-to-respond server. It is also now possible to use multiple
threads to close connections in parallel and optionally skip sending an unbind
request before closing the connections.
-
Update connection pooling support when connections are configured to
automatically retrieve schema information from the server. In a connection
pool, it is now possible to cache the schema so that it will not be retrieved
for every connection that is established.
-
Update connection pool support to a method that can be used to process a bind,
and then immediately re-bind with the credentials that were initially used when
the connection was established. Also add a method that can be used to release a
connection and have it be re-authenticated using the credentials that were
initially used when the connection was established.
-
Update the in-memory directory server to make it possible to specify multiple
schema files that will all be combined to generate the server schema.
-
Update the persistence framework so that the default object encoder includes
support for serialized objects. This may result in attribute values that aren't
useful to non-Java clients, but may still provide a convenient way to store some
complex information in LDAP entries.
-
Update the persistence framework to provide a new getAll method that
makes it possible to retrieve all objects of the associated type below a given
base DN.
-
Update the generate-schema-from-source tool so that it will include default
values for the equality, ordering and/or substring matching rules for all
attribute types that it creates.
-
Update the generate-schema-from-source tool so that it provides a new
"--modifyFormat" argument that will cause the tool to generate new schema
elements as LDIF modify change records instead of as attributes in an LDIF
entry.
-
Update the javadoc for getter methods in the Filter class to make it
clearer which methods may be used with which filter types.
-
Update the javadoc for methods that may be used for performing searches, as well
as for methods that may be used to set search size and time limits, to make it
clear that if an LDAPSearchException is thrown, it may include information about
any entries and/or references that were returned before the exception was
thrown.
-
Update the SSLUtil class to the ability to specify the default SSL/TLS
protocol string that will be used for creating SSL contexts when the caller
doesn't explicitly specify a protocol.
-
Update the LDAP listener canned response request handler to add the ability to
return a specified set of entries and/or references for every search operation.
-
Ensure that disconnect information is always set for a connection that is being
closed. If the connection is closed through an unexpected code path, then it
will now include a stack trace that provides information about the call path
that resulted in the connection closure.
-
Add a new MultiServerLDAPCommandLineTool API that can be used to easily
create command-line tools that need to interact with multiple LDAP servers.
-
Update the LDAP SDK command-line tool API to add convenience methods for
registering a JVM shutdown hook that will be invoked when the JVM in which the
tool is running is shut down (e.g., when all non-daemon threads have completed
running the JVM receives a break or kill signal).
-
Add a convenience method to the LDIFAddChangeRecord class that makes it
easy to get the entry to be added.
-
Add a new SASLBindInProgressException that extends
LDAPException and will be thrown instead of a generic
LDAPException if the server returns a "SASL bind in progress" result.
This will most likely occur when processing a SASL bind using the
GenericSASLBindRequest class.
-
Add a new LDIFWriterEntryTranslator class that can be used to transform
or suppress entries to be written to an LDIF file.
-
Update the LDAP debugger tool so that it can be used to accept SSL-based
connections from clients.
-
Improve the Attribute.equals method to make it much more efficient for
attributes with multiple values.
-
Add a new LDAPTestUtils.assertDNsEqual method that can be used to
ensure that two strings represent equivalent LDAP DNs.
-
Improve the amount of detail provided by the assertValueExists and
assertAttributeMissing methods in the LDAPTestUtils class if
the assertion fails.
-
Fix a bug in the LDIF reader that could prevent it from properly handling
comment lines that had been wrapped.
-
Fix a synchronization bug in the round-robin server set that could cause it to
throw an exception under highly concurrent load.
-
Fix a bug in the in-memory directory server that could cause it to send an
incorrectly-formatted search result done message for the case in which the size
size limit was exceeded.
-
Fix a bug in the LDAPThreadLocalConnectionPool that could cause it to
establish an extra connection if a health check is configured for the pool and
the ensureConnectionValidForCheckout method indicates that the existing
connection is not valid.
-
Fix a bug that could prevent connections from using the referral behavior
specified in the LDAP connection options that were set after the connection was
already established.
-
Fix a number of bugs that could interfere with the ability for a connection to
be automatically re-established if it becomes invalid.
-
Update the DurationArgument class to eliminate its dependency on the
MINUTES, HOURS, and DAYS values for the
TimeUnit enum. These values were not added until Java SE 6, and
attempts to use the DurationArgument class in a Java SE 5 environment
could result in errors.
-
Fix a bug in the persistence framework in which the inModify element of
LDAPField and LDAPGetter annotations may not be honored if the
object being modified was retrieved from a directory and references a copy of
the original entry in a field marked with LDAPEntryField.
-
Fix a bug in the persistence framework that can interfere with the ability to
generate search filters when using annotated objects that extend other annotated
objects.
-
Fix a potential null pointer exception that could arise in some cases when
trying to use a connection that was not established. An LDAP exception will now
be thrown instead.
-
Fix a potential null pointer exception that could be thrown when creating a
connection pool and a problem was encountered while attempting to establish one
of the initial connections after at least one connection had already been
established.
-
Fix a problem with the LDAP SDK build process that prevented building it with
Java SE 7, and clean up the code to remove a number of warnings generated when
building with Java SE 7.
Version 2.3.1
The following changes were made between the 2.3.0 and 2.3.1 releases:
-
Fix a bug that could result in memory pressure with a high volume of
asynchronous operations. This was a regression introduced by a change which
made it possible for timeouts to be honored for asynchronous operations.
-
Made a number of improvements to SSL support, including the addition of a new
aggregate trust manager (which can combine the result of multiple trust managers
when deciding whether to trust a certificate), a validity date trust manager
(which can reject a certificate based on its validity time period), and a
hostname trust manager (which can reject a certificate based on a conflict
between the expected server hostname and the value of the certificate's CN
subject attribute or a subjectAltName extension). In addition, the prompt trust
manager now displays additional information, including MD5 and SHA-1
fingerprints, to allow the user to make more informed decisions about whether to
trust a certificate.
-
Updated support for the SASL EXTERNAL bind request so that it is now possible
to request an authorization identity element in the SASL credentials. It is
now possible to create a SASL EXTERNAL bind request which does or does not
include SASL credentials.
-
Update the persistence framework to provide more complete support for modify
processing when the resulting entry may be altered via a post-encode method. If
the object has a field marked with @LDAPEntryField, then the updated object will
be encoded and compared with the original entry to determine the appropriate set
of modifications.
-
Add a connection option that controls whether multiple threads will be allowed
to make concurrent use of the same socket factory instance to create multiple
connections. A change introduced in the 2.3.0 release made all socket factory
interaction synchronized because it was observed that some IBM VMs do not
support concurrent use of an SSL socket factory instance. The default behavior
is now to allow concurrent socket factory use for Sun and Oracle VMs, but to
require synchronized use in other VMs. However, this default can be overridden
in the LDAPConnectionOptions class.
-
Add a new fastest connect server set implementation which attempts to connect to
all associated servers in parallel and will return the first connection to be
established. This may increase the connect-time load across all servers, but
will minimize the length of time required to establish a connection in the event
that any of the servers is having a problem.
-
Update the LDIF reader to add new options which can be used to have more control
over the treatment of trailing spaces in non-base64-encoded values (reject,
strip, or retain) and the treatment of duplicate attribute values (reject,
strip, or retain).
-
Update the LDIF reader to add support for file URLs with relative paths. By
default, these paths will be relative to the JVM's current working directory,
but it is possible to specify a custom base directory for relative paths.
-
Update the searchrate, modrate, and search-and-mod-rate tools to provide a new
"--iterationsBeforeReconnect" argument, which makes it possible to periodically
close and re-establish each connection. The default behavior, in which each
thread will create its own connection that it will continue to use for the
entire run, has not changed.
-
Update the base64 encoding and decoding capabilities to support the base64url
encoding as described in RFC 4648 section 5. Also, add support for base32
encoding and decoding as described in RFC 4648 section 6.
-
Updated the LDAPCommandLineTool class to provide a new
getUnauthenticatedConnection method that can be used to obtain a
connection to the target server (including the use of SSL or StartTLS if so
configured) but without performing any authentication on that connection. Also
make the createSSLUtil and createBindRequest methods public so
that they can be used by third-party code.
-
Updated the DurationArgument class to provide a public static method
that can be used to parse a duration string to a numeric value based on a given
time unit.
-
Update the ResultCode class to make it possible to provide a user-friendly name
for result codes not defined in the out-of-the-box set included with the LDAP
SDK.
-
Change the way that localization message files are stored and referenced within
the code. Some users have reported problems with their own applications having
properties files with names that conflict with properties file names used by
the LDAP SDK (e.g., "ldap.properties", "util.properties", etc.). To avoid this
problem, all LDAP SDK property files now have names starting with
"unboundid-ldapsdk-". In addition, the code has been updated to make even this
unlikely conflict less troublesome.
-
Updated the source for the Android LDAP client to use positional indicators in
format strings with multiple substitutions. It appears this is now required for
recent versions of the Android SDK.
Version 2.3.0
The following changes were made between the 2.2.0 and 2.3.0 releases:
-
Add a new DNSSrvRecordServerSet class, which is a ServerSet
implementation that can use DNS SRV records (as described in RFC 2782) to
discover available directory servers. This new implementation can consider
defined priorities and weights for SRV records so that some servers may be
preferred over based on information contained in the DNS server.
-
Add a new SASLUtils class that can be used to more easily work with
command-line tools that don't inherit from LDAPCommandLineTool but
may still need to perform SASL binds. It provides methods for getting access to
supported SASL mechanisms and the options that they support.
-
Add a new com.unboundid.ldap.sdk.experimental package with classes that
may be used to support certain features that may still be works in progress and
have the potential to change significantly (including in incompatible ways) in
the future. At present, this includes support for controls from
draft-behera-ldap-password-policy-10 and draft-zeilenga-ldap-noop-12.
-
Update the connection support for schema caching so that if multiple connections
reference equivalent schemas, then they will reference the same object rather
than separate equivalent objects. This can dramatically reduce memory
consumption if schema caching is enabled.
-
Fix a bug that could cause the output of ByteStringBuffer.toByteString
to be unstable and reflect subsequent changes in the content of the associated
ByteBuffer.
-
Update support for asynchronous operations so that it is possible for them to
respect a configured timeout. Previously, operation timeouts were ignored for
asynchronous operations.
-
Update the LDAP SDK persistence framework to add support for attributes with
options. It is now possible to use attribute names with options.
-
Update the LDAP SDK persistence framework to make it possible to specify
superior object classes in the @LDAPObject annotation type. If specified, these
object classes will be included in generated entries. The
generate-source-from-schema tool has been updated to populate this
element if appropriate.
-
Update the in-memory directory server to make it possible to alter the server
schema using LDAP modify operations. Only add and delete modifications will be
allowed for the attributeTypes, objectClasses, nameForms, dITContentRules,
dITStructureRules, and matchingRuleUse attributes. No modifications will be
allowed for the ldapSyntaxes and matchingRules attributes.
-
Update the in-memory directory server to make it possible to customize schema
enforcement. It is now possible to allow values which violate the associated
attribute syntax, and/or to allow entries which do not have exactly one
structural object class.
-
Update the in-memory directory server so that it is possible to indicate that
equality indexes should be maintained for specified attributes. If enabled, the
server may exhibit better performance for certain kinds of searches (those using
an equality component targeting an indexed attribute, including those which may
be included in AND or OR filters).
-
Update the in-memory directory server to make it possible to perform simple and
SASL PLAIN binds directly against the server itself without the need to
establish a connection to it.
-
Update the in-memory directory server to make a number of logging-related
improvements. A race condition which could cause incorrect entry counts to be
included in log messages has been fixed. Log messages now include timestamps.
Access and/or LDAP debug messages can now be written to standard output.
-
Update the in-memory directory server to make it possible to customize the
values included in the vendorName and vendorVersion attributes of the server
root DSE. This can help make it easier for the in-memory server to impersonate
another type of directory to fool applications which will only work with certain
types of servers and which use these attributes to make that determination.
-
Update the in-memory directory server so that the authorization identity
response control will always use the "dn:" form of the authorization identity,
even for PLAIN binds that initially used the "u:" form. Also, fix a bug in
which it would incorrectly return "dn:" instead of just "" for an anonymous
authorization identity.
-
Update connection pool health checking support to make it possible to more
quickly recognize server-initiated disconnects and unsolicited notifications for
connections operating in synchronous mode.
-
Update connection pool support for retrying failed operations to make it
possible to control the types of operations that should be retried. It was
previously only possible to configure it on an all-or-nothing basis.
-
Update the default standard schema (which will be used by the in-memory
directory server unless configured to do otherwise) so that it includes
information about supported syntaxes and matching rules. These ldapSyntaxes and
matchingRules values will be included in the schema exposed by the in-memory
directory server.
-
Update the LDIF reader to add static methods that make it easy to read entries
from an LDIF file and return them as a list. This is a convenient way to read
entries from small LDIF files (e.g., for use in unit tests).
-
Improve the efficiency of the Entry.diff method when using reversible
form and working with entries with attributes that have a large number of
values.
-
Update the CommandLineTool class to provide an optional
getToolVersion method that may be used to retrieve the version string
for the associated tool. If a version string is made available, then a new
"--version" argument may be automatically added to the tool to cause it
to display the version string.
-
Update the support for LDAP URLs to provide support for URLs with the "ldapi"
scheme. Note that the LDAP SDK does not directly support LDAPI (although it may
be possible to use with a third-party library that provides support for UNIX
domain sockets), but it can now parse LDAP URLs with a scheme of "ldapi".
-
Update value pattern implementations to make it possible to specify a seed to
use for the random number generator, which can provide for more reproducible
results. The searchrate, modrate, authrate, and search-adn-mod-rate tools have
been updated to add a --randomSeed argument that can be used to specify
a random seed if one is desired.
-
Update the validate-ldif tool to add support for working with gzip-compressed
LDIF files.
-
Update the LDAPException.toLDAPResult method so that it will use the
exception message as the diagnostic message for the resulting
LDAPResult object if the exception does not have a specific diagnostic
message.
-
Update the ObjectPair class to provide hashCode,
equals, and toString methods.
-
Update all uses of SocketFactory.createSocket methods are synchronized
on the associated socket factory. In some implementations (including those used
by the IBM JVM), unsynchronized calls to these methods may result in unexpected
exceptions or other strange behavior.
-
Update support for the GSSAPI SASL mechanism to provide the ability to operate
in IBM JVMs.
Version 2.2.0
The following changes were made between the 2.1.0 and 2.2.0 releases:
-
Introduced a new way of packaging the LDAP SDK in a way that results in a
significantly smaller jar file. The Minimal Edition provides full support for
LDAP communication and LDIF parsing, but strips out a number of optional
features (e.g., SASL authentication, support for many controls and extended
operations, examples, the LDAP listener package and in-memory directory server,
the LDAP SDK persistence framework, migration support for JNDI and the Netscape
SDK, command-line argument parsing). The Minimal Edition is primarily intended
for use in space-constrained environments (e.g., Android applications) in which
the smallest possible jar file is desired.
-
Updated connection pool implementations to make it possible to configure the
pools to automatically retry operations if the first attempt fails in a manner
that indicates the connection may no longer be valid. In such cases, a new
connection will be created (which may be established to a different server if a
server set is used) and used to retry the failed operation.
-
Add the ability to make use of schema information when generating the normalized
representation of DNs and RDNs, and for more operations when interacting with
entries.
-
Updated the in-memory directory server to add support for referential integrity
for delete and modify DN operations. This can be used to remove or update
references to an entry if that entry is deleted or renamed.
-
Updated the in-memory directory server to add support for LDAP transactions as
described in RFC 5805. This can be used to add, delete, and/or modify multiple
entries as a single atomic unit.
-
Updated the in-memory directory server to add the ability to insert an arbitrary
delay before processing operations. This can be useful in simulating
environments with slower response times or higher network latencies.
-
Improved support for GSSAPI authentication to add a number of new options,
including: the ability to indicate whether a ticket cache should be used, the
ability to specify an alternate path to the ticket cache file, the ability to
require the use of cached credentials, and the ability to request that the TGT
be renewed. It is also easier to obtain GSSAPI debugging information.
-
Update the default standard schema to include a definition for the aci attribute
type, which is not standard but is supported by a number of directory servers
and may commonly appear in many data sets. Also, update the groupOfNames and
groupOfUniqueNames object classes to make it possible to have groups without any
members which is nonstandard but allowed by many servers. Finally, make it more
efficient to retrieve the default standard schema for subsequent calls.
-
Updated the LDAPConnectionOptions object to add an option that can be
used to send an abandon request to the server whenever a client-side response
timeout has occurred. Previously, the client would stop waiting for a response
but would not attempt to prevent the server from completing processing on the
operation.
-
Updated the LDIF reader to provide an option to read from multiple LDIF files.
If this option is used, then the contents of the files will be read in the order
they were provided (e.g., all the records will be read from the first file, then
all the records from the second file, etc.). That is, this provides a way to
treat multiple LDIF files as if they were a single file.
-
Introduced new methods to make it much easier to work with response controls.
Each response control class now includes one or more static get methods
that can be used to retrieve and decode the control from a response message.
-
Updated the LDAP SDK persistence framework so that the
generate-source-from-schema tool will now generate methods that can make it
easier to search for objects using arbitrary criteria. The persistence
framework previously only provided support for equality searches, but it is now
possible to perform more advanced types of searches, including presence,
substring, greater-or-equal, less-or-equal, and approximate matching.
-
Updated the LDAP SDK entry validator to make it possible to reject entries that
were missing superior object classes. This also fixed a bug in the in-memory
directory server that made it possible for clients to perform modify operations
to remove superior object classes from an entry.
-
Fixed a bug in the filter evaluation logic that caused it to return the wrong
result for greater-or-equal and less-or-equal filters.
-
Fixed a bug in the in-memory directory server that could cause some superior
object classes to appear twice in an entry if the superior class was specified
after its subordinate class when the entry was added.
-
Fixed a bug in the persistence framework that caused it to throw an exception
when trying to perform a modify an object that had not been altered. The code
has been updated so that it will now return null (as an alternative to the
LDAPResult that would be returned if a modification was actually attempted)
rather than throwing an exception.
-
Update the javadoc documentation for controls and extended operations to make
the OIDs used for those purposes more visible.
-
Fixed a bug in the command-line tool that may be used to interact with the
in-memory directory server that made it impossible to run the server with no
schema.
Version 2.1.0
The following changes were made between the 2.0.1 and 2.1.0 releases:
-
Added the ability to easily create a simple memory-based LDAP server that
supports a wide range of LDAP functionality (including a number of controls and
extended operations). It may be used as a server for testing or demonstrating
directory-enabled applications, and it provides a number of convenience methods
for interacting with and verifying the contents of that server.
-
Added a new LDAPTestUtils class that provides a number of convenience
methods that can be usd to help write test cases for directory-enabled
applications and make determinations about the content of an LDAP directory
server.
-
Added a new LDAPConnection.processOperation method that can be used to
process a generic request without needing to know the type of operation that it
represents.
-
Added a new Schema.getDefaultStandardSchema method that can be used to
obtain a schema object populated with a number of standard attribute type and
object class definitions from various RFCs and IETF drafts.
-
Added a new GenericSASLBindRequest class that can be used to process
any kind of SASL bind request if the caller is capable of properly encoding
and decoding request and response credentials.
-
Added a new PasswordProvider API which can be used when performing
simple bind operations in order to minimize the length of time that the
clear-text password remains in memory. If a password provider is used rather
than explicitly including the password in the bind request, then the memory
containing that password will be overwritten as soon as the password is no
longer needed. A ReadFromFilePasswordProvider implementation of this
API is also included in the LDAP SDK, which makes it possible to obtain the
password from a file whenever it is needed.
-
Added support for the LDAP don't use copy request control as defined in RFC 6171
and can be used to request that only an authoritative directory server be used
to process the associated search or compare operation.
-
Added a new Entry.mergeEntries method that can be used to create a new
entry containing all of the attribute values present in at least one of the
provided entries, and a new Entry.intersectEntries method that can be
used to create a new entry containing only those attribute values present in all
of the given entries.
-
Fixed a bug in the LDAPPersister.modify method that prevented it from
including controls in the request sent to the directory server.
-
Fixed a bug that could prevent a configured ReferralConnector from
being used. In addition, it is now possible to use the
LDAPConnectionOptions class to configure a referral connector that will
be used for all connections created with those options rather than requiring
each connection to be explicitly assigned a custom referral connector if one was
needed.
-
Updated the FixedRateBarrier class to use a much more efficient process
for dealing with low operation rates that can consume significantly less CPU.
Previously, it would always spin, but it will now try to sleep if there is a
long enough interval before the next operation can be processed.
-
Updated the FailoverServerSet class to provide an option to re-order
the internal list of servers so that if a failover does occur, any unavailable
servers are moved to the end of the list so that the server to which the
connection was successfully established is now at the top of the list and will
be the first server tried for subsequent attempts. The same behavior is
available for failing over between server sets rather than individual servers.
Note that the previous behavior of preserving the original order is still
available, and will continue to be used unless the server set is explicitly
configured to allow re-ordering the list.
-
Updated the LDIF reader to provide better handling for illegal trailing spaces.
Previously, such spaces would be simply included in the content being read,
which is always the wrong thing to do. Now, there is an option to either reject
entries and change records containing trailing spaces (which is the default) or
to silently strip them out.
-
Updated the AsyncRequestID class so that it implements the
java.util.concurrent.Future API. This can make it easier to wait for
and retrieve the response to asynchronous operations requested through the
LDAP SDK.
-
Updated the LDAPConnection.processExtendedOperation methods so that
they are more likely to throw an exception in the event that the connection is
no longer valid. Because extended operation responses may often include result
codes other than "success" even when the operation completed successfully, and
because it is undesirable to throw an exception when the operation completed
successfully, the LDAP SDK is more likely to return an ExtendedResult
object even for an unsuccessful operation in cases where it would have thrown an
LDAPException for other types of operations. However, it was
previously too hesitant to throw an exception in cases where there clearly was a
failure, including when the associated connection was no longer valid, and this
could sometimes cause problems. The LDAP SDK will now throw an exception in
cases where the operation was clearly not successful, and particularly in cases
where the connection may no longer be valid.
-
Improved the behavior of many of the command-line tools that can be used to
issue repeated requests against a directory server (e.g., searchrate,
modrate, etc.) so that they exhibit better behavior in the event that
the connection is lost or becomes no longer usable. In some rare conditions,
the previous approach would attempt to re-establish connections which were no
longer authenticated, which could lead to failures or unexpected behavior in
the operations that had been attempted.
-
Updated the behavior of connections operating in asynchronous mode so that they
are less likely to encounter SO_TIMEOUT exceptions (or at least, will encounter
them with much less frequency) when connections remain idle for extended periods
of time. These exceptions are harmless and are handled entirely by the LDAP SDK
so that the underlying application does not need to deal with them, but having
them occur too frequently has been observed to cause unnecessarily high CPU
utilization in some client systems.
-
Updated support for the GSSAPI SASL bind request so that it is possible to
specify an alternate protocol for use in the Kerberos service principal. The
bind request previously always used a protocol of "ldap", and this is still the
default, but it is now possible to request that an alternate protocol be used in
the server's service principal.
-
Updated the ldap-debugger tool so that it can be used for some kinds of
SASL authentication. In addition, the format of the output that the tool
generates has been improved, particularly when dealing with binary data such as
may be present in control and extended operation values or SASL bind
credentials. In such cases, the hex representation of the binary data may be
accompanied by a text representation of any printable ASCII characters contained
in that binary data.
-
Added an LDIFWriter.flush method, which can be used to flush any
buffered LDIF content to disk or the underlying output stream without the need
to close the writer.
-
Updated the SSLUtil class to provide convenience methods for creating
SSLServerSocketFactory objects.
-
Updated the LDAPConnectionOptions class-level documentation to indicate
that the auto-reconnect option doesn't apply to connections that are part of a
connection pool. Connections in a connection pool will be closed and replaced
rather than attempting to re-establishing the existing connections.
Version 2.0.1
The following changes were made between the 2.0.0 and 2.0.1 releases:
-
Updated the persistence framework to support inheritance. If a class marked
with the @LDAPObject annotation type has a superclass which is also
annotated, then the annotated fields and methods of the superclass will be used
in the course of converting between entries and instances of the subclass.
-
Updated the ValuePattern class to provide support for back-references,
in which it is possible to have a generated substring repeated later in the
generated value. Also, fix a bug in its support for obtaining values from files
that could interfere with the ability to use Windows absolute paths containing a
drive letter.
-
Updated the formatter used to generate output for tools like searchrate,
modrate, and authrate so that they will use a string of "inf" for a numeric
value of infinity, and "NaN" for a numeric value of "not a number". Also,
fix a couple of potential conditions that could cause divide by zero
errors.
-
Updated the argument parsing support to add a new "argument list" argument type,
in which values may themselves be parsed as argument strings, validated with
their own argument parser. Also, updated string arguments to make it possible
to use a regular expression to restrict the set of values that may be used for
that argument.
-
Fixed a potential bug in the entry validator that could cause it to throw an
exception when attempting to parse an entry that does not have all of the
superior classes for the object classes it does include.
-
Updated the LDAP connection pool implementation so that it is possible to
request that zero connections be initially created, so that the first connection
will only be created when the first operation is attempted.
-
Added static Filter.encodeValue methods that may be used to properly
escape a value for use in the string representation of a search filter.
-
Updated the intermediate response API to add a valueToString method, which may
be used to obtain a human-readable representation of the intermediate response
value.
-
Improved the quality of debugging information so that it can be more useful in
cases in which there may be multiple connections active at the same time.
Messages about LDAP communication will include a connection ID and LDAP message
ID, and result messages will include the protocol op type.
-
Updated the LDAP SDK jar file manifest to include new attributes with
additional metadata about the LDAP SDK build, including the build time and
source repository path and revision number.
Version 2.0.0
The following changes were made between the 1.1.6 and 2.0.0 releases:
-
Added a new persistence API which can be used to make it easy to represent LDAP
entries as Java objects, and vice-versa. Java annotation types may be used to
mark fields and methods within a class to provide information about the way that
instances of that object should be represented in LDAP entries.
-
Added a generate-source-from-schema tool that can be used to generate
the source code for a Java class based on information contained in a directory
server schema. The generated Java source will have all of the necessary
annotations to allow that object to be used in conjunction with the LDAP SDK
persistence framework.
-
Added a generate-schema-from-source tool that can be used to generate
LDAP schema from a Java class configured for use with the LDAP SDK persistence
framework. The generated schema may be added to a directory server to be able to
store objects of the specified type in the directory.
-
Added a new listener API which can be used to develop applications which accept
connections and manage communication with LDAP clients. It may be used to help
develop applications which support interaction with LDAP clients.
-
Added a new ldap-debugger tool which uses the listener API and other
components of the LDAP SDK to intercept communication from LDAP clients and
write details of the LDAP communication to standard output or a specified log
file. The received LDAP requests will then be forwarded on to a target directory
server and any responses returned will be decoded and written to the same
location as the decoded requests before the responses are returned to the client.
This tool acts as a simple LDAP proxy server that can be used to help better
understand exactly what communication occurs between an LDAP client and server.
-
Added new argument types, including a BooleanValueArgument (in which the
provided value must be either "true" or "false", which is more useful in some
cases than the BooleanArgument in which the Boolean value is inferred based on
whether the argument was provided), a DurationArgument (in which the value
contains both an integer portion and a time unit, like "50ms", to indicate a
length of time), and a ScopeArgument (in which the value should represent an LDAP
search scope).
-
Updated the LDAP command-line tool interface to make it possible to specify the
format to use for the Java key store and trust store files. The default
format will be JKS, but you can indicate that an alternate format (e.g., JCEKS
or PKCS12) if desired.
-
Updated the support for the LDAP assertion control to add a new generate
convenience method that can be used to easily generate an assertion request
control from some or all of the attributes in a provided entry. This can be
used when updating an entry to help ensure that it has not been altered by
something else since it was last read.
-
Updated the support for the FileArgument class in which allows you to specify
the base directory to use for relative paths. If no relative base path is
defined, then relative paths will be relative to the current working directory
(which has always been the case), but if a relative base path is defined, then
any relative paths will be relative to that base directory.
-
Fixed a bug that could cause problems when attempting to process operations which
return one or more intermediate response messages on a connection operating in
synchronous mode.
Version 1.1.6
The following changes were made between the 1.1.5 and 1.1.6 releases:
-
Fixed an error in the documentation for the ContentSyncRequestControl that
indicated a response timeout of -1 should be used instead of the correct
recommendation of 0. A value of 0 indicates that no timeout should be used,
while -1 indicates that the connection-level timeout (5 minutes by default)
should be used.
-
Fixed the way that RDNs are created when decoding a DN from a string.
Previously, RDNs created in this way were treated in a way that could cause
extra spaces to be removed from their string representation. While the resulting
RDN was technically equivalent to the expected version, the user-provided string
representation should have been retained.
-
Updated the source code for the Android LDAP client to match the 1.1 version
published in the Android market.
Version 1.1.5
The following changes were made between the 1.1.4 and 1.1.5 releases:
-
Added support for the content synchronization operation as defined in RFC 4533,
including the various controls and the intermediate response needed to interact
with servers supporting this feature.
-
Fixed a couple of bugs in the way that SSL handshaking is performed to make it
more robust, particularly when used over higher-latency network links.
-
Fixed a bug that could prevent an unbind request from being sent to the server
when closing a connection that had previously been closed and re-established.
Version 1.1.4
The following changes were made between the 1.1.3 and 1.1.4 releases:
-
Fixed a bug in the way that the LDAP SDK performed SSL or StartTLS negotiation
when using synchronous mode. As a result of this bug, a race condition created a
condition in which the connection could be terminated with an error if any part
of the negotiation process took longer than 50 milliseconds.
-
Added a new search-and-mod-rate tool that can be used to perform
searches as quickly as possible while also modifying each entry returned from
those searches.
-
Added a new Launcher class that can be used to invoke the various command-line
utilities without needing to use the associated shell scripts. This is primarily
a convenience that makes it possible to use the tools when only the LDAP SDK jar
file is available. The tools can be invoked using a command like:
java -jar unboundid-ldapsdk-se.jar {tool-name} {tool-args}
-
Updated the ldapsearch tool to add the ability to perform the same search
multiple times using a specified interval. This can be useful, for example, to
repeatedly retrieve a server monitor entry at regular intervals.
-
Updated the ldapsearch tool to add a terse mode that can be used to minimize the
output that it generates to include only minimal content. It will exclude the
connect message, and entry and reference counts. Further, all such messages
written in non-terse mode will be prefixed with "#" characters so that the entire
output will be valid LDIF.
-
Updated the traditional and thread-local connection pool implementations to
provide the ability to define the minimum length of time that should pass between
connection closures because they have been established for longer than the
maximum connection age. This can help avoid cases in which a large number of
connections are closed and re-established in a short period of time.
-
Updated the LDAP SDK to provide a more useful exception in the event that the
connection is terminated as a result of an error encountered while trying to read
a response from the server.
-
Improved the searchrate, modrate, and authrate tools so that they are better able
to handle the case in which the connection to the server is lost or the server
becomes unavailable. The tools will attempt to re-establish the connections
when the server again becomes available.
-
Updated several parts of the LDAP SDK to reduce the amount of memory allocation
performed and the amount of garbage created during processing.
-
Added a missing space between the numeric value and name in the string
representation of a result code.
Version 1.1.3
The following changes were made between the 1.1.2 and 1.1.3 releases:
-
Added support for LDAP transactions as defined in RFC 5805. This includes
support for the start and end transaction extended requests and results, the
transaction specification request control, and the aborted transaction
unsolicited notification.
-
Added a new LDAPConnection.getActiveOperationCount method, which can be
used to obtain the number of operations that have been started but not yet
completed on that connection. This will only be valid for connections that are
established and not operating in synchronous mode.
-
Added a new searchForEntry method to the LDAPInterface
interface (and therefore for individual connections and connection pools) that
can be used to perform a search expected to return a single entry in a manner
that is more convenient than other search methods.
-
Added a number of convenience methods that make it easier to manipulate the
content of an add request request like an entry.
-
Updated the schema parsing code to be more lenient when attempting to parse
definitions which violate the specification. In particular, it will now accept
OIDs surrounded in single quotes or OID lists not followed by spaces. Even
though these are not allowed according to the LDAP specification, Active
Directory generates schema elements exhibiting these problems. With these
changes, the LDAP SDK can now parse Active Directory schema elements.
-
Updated the CommandLineTool API to provide methods for getting access to
the output and error streams to allow for more complex use than simply printing
messages to the terminal.
-
Fixed a potiential bug in the value normalization code which could cause a string
index out of range exception when attempting to normalize a value containing only
non-ASCII space characters.
-
Fixed a bug in the EntryValidator class that could cause it to throw a
null pointer exception when attempting to process an entry that does not have any
object classes.
-
Fixed a bug in which a debug message for an LDIF read is inadvertently written as
if it were an LDIF write.
-
Updated the searchrate tool so that it provides an asynchronous mode that can be
used to have multiple outstanding requests on a single connection. When
operating in this mode, it is necessary to use either the existing
"--ratePerSecond" or the new "--maxOutstandingRequest" argument
to restrict the number of concurrent outstanding requests. The total number of
connections to establish will still be controlled by the number of client
threads.
-
Updated the source for the Android LDAP client to reflect the code used for the
1.0 release available in the Android Market.
Version 1.1.2
The following changes were made between the 1.1.1 and 1.1.2 releases:
-
Improved the behavior of the AttributeTypeDefinition class so that it
can better deal with attribute type definitions whose syntax element contains
the optional minimum upper bound component. The getSyntaxOID() method
still returns the complete syntax OID (including the minimum upper bound, if
present), but a new getBaseSyntaxOID() method has been added that can
be used to obtain the syntax OID without the minimum upper bound, and a
getSyntaxMinimumUpperBound() method has been added that can be used to
obtain the minimum upper bound (or -1 if no minimum upper bound is defined).
In addition, the Schema.getAttributeSyntax method has been updated so
that it will ignore any minimum upper bound portion that may be included in the
provided OID.
-
Added a new Entry.diff method that makes it possible to indicate
whether you want the resulting modifications to be reversible. If the
modifications should be reversible (which was always the case in the past), then
the resulting list will contain only modifications with the ADD and DELETE
modification types, which could be played in reverse to recreate the source
entry from the target entry, but is more likely to fail if the entry has been
altered in some way since attempting to apply the modifications. If the
modifications should not be reversible, then they will all use the REPLACE
modification type, which is not reversible but more likely to succeed even if
the entry has been altered.
-
Improved the way that the LDAP SDK generates string representations of DNs and
RDNs. When creating a DN from a set of RDNs (or from an RDN and parent DN), it
will now use the string representations of the provided RDNs (and optionally DN)
rather than reconstructing the entire string representation. This can help
preserve a user-supplied string representation if you do something like
"new DN(existingDN.getRDNs())", particularly if the existing DN had
characters that may be escaped but don't have to be. In addition, a new
toMinimallyEncodedString method has been added to both the DN
and RDN classes which will construct a string representation of the
DN or RDN with a minimal set of escaped characters (e.g., non-ASCII characters
and non-printible ASCII characters will not be escaped).
-
Fixed a bug in the LDIF reader in which it would refuse to decode an entry
containing only a DN but no attributes (e.g., like might be the case with a
search result entry where the requested attribute set contained only "1.1").
-
Fixed a bug in the way that LDAP URLs were generated for URLs containing the
subordinate subtree search scope. Previously, the string representation of
such URLs would have a scope of "subord" instead of the correct "subordinates"
as specified in draft-sermersheim-ldap-subordinate-scope. It will still accept
URLs containing "subord", but will no longer generate them.
-
Fixed a bug in the LDAPCommandLineTool class that prevented the
--bindPasswordFile argument from being used in conjunction with the
--bindDN argument. Due to an oversight, --bindPasswordFile
could only be used when performing SASL authentication when no bind DN was
given.
Version 1.1.1
The following changes were made between the 1.1.0 and 1.1.1 releases:
-
Updated the searchrate, modrate, and authrate tools to change the way that they
signal the processing threads to start. The previous approach could lead to
resource starvation causing the system to run with 100% CPU utilization for a
period of time.
-
Improved the accuracy of the searchrate, modrate, and authrate tools. The
overall rates were accurate, but the recent rates could be slightly off.
In addition, the recent and overall rates for the first interval often didn't
match up. These problems have been resolved.
-
Updated the searchrate and modrate tools to support the use of the proxied
authorization v2 control. The authorization ID may be specified as a value
pattern, which makes it possible to specify a range of alternate authorization
identities.
-
Added isClosed methods to the connection pool implementations which can
be used to determine whether the connection pool has been closed.
-
Updated the value pattern implementation to provide support for reading values
from files. Files should be referenced by URL, and it supports both local files
(using a URL like "file:///path/to/file") and remote files via HTTP (using a URL
like "http://server.example.com/path/to/file"), and that URL should be enclosed
in square brackets. For example, a value pattern of "[file:///tmp/filters.txt]"
will cause the individual lines of the file "/tmp/filters.txt" to be read and
randomly substituted for that portion of the value pattern.
-
Updated the searchrate, modrate, and authrate tools so that they provide the
ability to display information about the result codes for operations that don't
complete successfully. If any errors are encountered during processing, then
the result codes for those failures will be displayed along with the number of
times that result was returned. The "--suppressErrorResultCodes" argument may
be provided to disable this capability.
-
Improved the behavior exhibited by the LDAP SDK when interacting with a server
that is completely unresponsive (e.g., as in the case in which the network cable
has been removed, or the server process has been halted with a command like
pstop). This includes improved support for honoring any configured connect
timeout, even for SSL-based connections which did not previously support it.
Bind and extended requests can now have an explicit timeout assigned to them,
like was already possible for all other types of requests. When duplicating a
request, any assigned timeout is also duplicated along with the other details of
that request.
-
Improved the error message in the exception thrown if a client-side timeout
occurs. The updated message now includes the type of operation and the length
of time the client waited before considering the operation to have timed out.
-
Updated the RootDSE and Schema classes so that their
constructors which take Entry objects are made public, since they can
be useful in code outside of the LDAP SDK.
-
Made the SearchRequest.getSearchResultListener method public so that
code outside of the LDAP SDK can determine whether a search result listener has
been configured for the search.
-
Updated the message properties files to use better format strings for messages
containing numbers. Previously, large numbers could be formatted awkwardly
(e.g., including commas as grouping separators, like "12,345" instead of just
"12345").
-
Updated the LDAP SDK so that the thread-local ASN1Buffer object used for
connections is made static rather than per-instance. This can dramatically
reduce the amount of memory consumed for applications with large numbers of
connections that can be used by multiple threads.
-
Added methods that can be used to determine whether an attribute value needs to
be base64-encoded when represented in LDIF. Also, updated the
Attribute.toString methods so that values will be base64-encoded in
that string representation if they should be base64-encoded in LDIF.
-
Updated the LDAP SDK so that it allows working with ASN.1 elements whose values
are contained in a portion of a byte array rather than always requiring them to
be the full array. The sequence and set parsing code now takes advantage of
this, and elements decoded from them no longer require allocation of new arrays
for holding their values.
-
Improved support for client-side use of matching rules. All matching rule
classes now provide the ability to retrieve the name and OID of the equality,
ordering, and substring matching rules that they implement. The
MatchingRule class now provides the ability to select a matching rule
instance from the OID of the desired matching rule. The EntrySorter
class has been updated so that if a sort key contains a matching rule ID, then
it will be used to select the matching rule to use for the client-side sorting.
-
Updated the schema parsing code so that when reading schema definitions from
LDAP or LDIF, any leading and trailing spaces will be trimmed before attempting
to parse the elements. Technically, leading and trailing spaces are illegal
and should not be present in such definitions, but some servers are lenient and
allow them so the LDAP SDK should attempt to accommodate such definitions. It
will still never generate schema element definitions containing leading or
trailing spaces.
-
Updated the LDAP SDK so that any debug messages or string representations of
exception stack traces that it generates will include the revision number of the
source repository from which the LDAP SDK was built. This can help make it
easier to troubleshoot problems, since it is easier to identify the version of
the source used to generate the LDAP SDK build being used.
-
Fixed a bug that can cause problems for clients operating in the default
asynchronous mode if the server sends response messages broken up into small
pieces rather than all a once. In particular, if a response message contains
only the BER type, or only the BER type and a portion (but not all of) the
length, then the LDAP SDK may not be able to properly decode the full message if
there is a delay between the first and second packets with portions of the type
and length. If this problem occurs, then the client would terminate the
connection to the server.
Version 1.1.0
The following changes were made between the 1.0.0 and 1.1.0 releases:
-
A new license has been added to the UnboundID LDAP SDK for Java. In addition
to the previous GNU General Public License (GPLv2) and UnboundID LDAP SDK Free
Use License, the Standard Edition of the LDAP SDK is now available under the
terms of the GNU Lesser General Public License (LGPLv2.1). This is an
OSI-approved open source license which allows the SDK to be used in a very wide
range of applications (including proprietary and commercial applications).
-
The Standard Edition of the LDAP SDK is now available in a SourceForge project
at http://sourceforge.net/projects/ldap-sdk/.
This includes a subversion repository containing the source code, as well as a
new set of project mailing lists and a forum.
-
The Standard Edition of the LDAP SDK is now available for use with Maven. It
is available at
http://ldap-sdk.sourceforge.net/maven/
with a groupId of "com.unboundid", an artifactId of "unboundid-ldapsdk", and a
version of "1.1.0". In the near future, it will also be included in the Central
Repository.
-
Updated the LDAPCommandLineTool class to provide support for handling
connections to multiple servers. If this capability is enabled, then it will
allow multiple occurrences of the "--hostname" and "--port" arguments to be
provided. If multiple addresses and ports are provided, then the same number of
each must be given, and a RoundRobinServerSet will be used when creating
connections so that each subsequent connection will be established to the next
server in the list, looping back to the beginning of the list when all servers
have been used. The searchrate, modrate, and authrate tools have been updated
to take advantage of this capability, so they may now be used to process
operations concurrently against multiple servers.
-
Updated the build process so that the manifest for the generated jar file
contains an appropriate set of attributes to make the LDAP SDK more suitable for
use in an OSGi environment. The added attributes include: Bundle-Name,
Bundle-Version, Bundle-Vendor, Bundle-Copyright, Bundle-ManifestVersion,
Bundle-RequiredExecutionEnvironment, Bundle-Category, Bundle-DocURL, and
Export-Package.
-
Updated the ResultCode.isConnectionUsable() method to be more
conservative so that it is more likely to return a false positive (i.e., the
connection will be considered unusable when it may still be usable) than a false
negative (the connection will be considered usable when it that is not the
case). Also, non-static versions of the isClientSideResultCode() and
isConnectionUsable() methods have been added for convenience.
-
Added finalize() methods for the connection pool implementations so
that the pool will be closed when it is reaped by the garbage collector if that
was not already done.
-
Added support to make it easier to migrate applications written to use the
Netscape Directory SDK for Java to the UnboundID LDAP SDK for Java. This
includes wrappers for a number of commonly-used classes in the Netscape API so
that in many cases it may be sufficient to simply change the import statements
of the application so that they reference
"com.unboundid.ldap.sdk.migrate.ldapjdk" instead of "netscape.ldap". This is
not a complete re-implementation of the Netscape API (e.g., it does not directly
support applications written to use asynchronous operations), but in the common
case it should help significantly reduce the code change required to migrate an
application from the Netscape API to the UnboundID LDAP SDK for Java.
-
Added support to make it easier to migrate applications written to use the Java
Naming and Directory Interface (JNDI) to the UnboundID LDAP SDK for Java, or to
allow applications which use functionality provided by both APIs concurrently.
A new JNDIConverter class has been added which provides support for converting
between corresponding JNDI and LDAP SDK implementations of common data
structures, including attributes, controls, extended requests and responses,
modifications, and search result entries.
-
Added a new "use schema" LDAP connection option which can be used to cause
operations on the connection to make use of schema information when reading
data from the directory server. In particular, the schema will be used to
select the appropriate matching rule for each attribute included in search
result entries. The Attribute class has been updated to provide new
constructors which take Schema objects that allow that schema to be
used to select the appropriate matching rule for that attribute.
-
Added a set of Attribute.nameIsValid methods which can be used to
determine whether a provided string is a valid attribute name.
-
Added additional Attribute.hasValue and
Entry.hasAttributeValue methods which allow an alternate matching rule
to be provided which will be used when making the determination rather than the
matching rule with which that attribute type is associated.
-
Added support for the case-ignore list equality and substring matching rules,
as used by the postal address syntax.
-
Updated the searchrate, modrate, and authrate tools to include new command-line
options. The "--timestampFormat" argument may be used to indicate
whether timestamps should be included in the output, and if so what format
should be used (either the time only or both the date and the time). The
"--warmUpIntervals" argument may be used to indicate that the tool
should be allowed to run for a specified number of intervals before beginning
overall statistics collection to allow the client and the server to warm up.
Version 1.0.0
The following changes were made between the 0.9.10 and 1.0.0 releases:
-
Updated the code used to read server responses so that it uses a result code of
"server down" rather than "protocol error" whenever an I/O error occurs while
reading the response.
-
Added support for the permissive modify control, which may be used to request
that the directory server accept modify requests which attempt to add an
attribute value that already exists in the target entry, or to remove an
attribute value which does not exist in the target entry.
-
Updated the code used to parse schema elements to be more lenient and
standards-compliant when handling optional spaces in definitions.
-
Added a new LDAPThreadLocalConnectionPool class, which is very similar
to the existing LDAPConnectionPool class, except that it uses a
thread-local mechanism to maintain a separate connection for each client thread
that attempts to communicate with the server. This can help eliminate some
thread contention, and can help avoid the need to define an explicit size for
the pool, since it will have as many connections as threads attempting to use
the pool.
-
Added the ability to create a Schema object by reading schema
definitions from one or more LDIF files. It was previously only possible to
read schema information from a directory server over LDAP.
-
Updated the LDIF reader to provide the ability to reject entries containing
duplicate values for the same attribute. Previously, if an entry had multiple
occurrences of the same value for the same attribute, the LDIF reader would
simply silently ignore the duplicate values. This is still the default
behavior, but it is now possible to configure the LDIF reader to reject
entries with duplicate attribute values.
-
Updated the LDIF reader to provide the ability to use schema information when
reading entries and change records. This can be used to help better handle
treatment of different values which might have otherwise been considered
duplicates using the default case-ignore string matching rule (e.g., attributes
that should use case-exact matching and have values that differ only in
capitalization).
-
Updated the validate-ldif tool provided with the LDAP SDK so that it offers the
ability to use schema definitions read from files rather than over LDAP (so that
it can be used in a completely offline manner). It will also now reject entries
with duplicate attribute values by default, but provides an option to ignore such
errors.
-
Updated the EntryValidator class so that it properly handles entries
with the extensibleObject object class.
-
Fixed a bug that could prevent LDAP connection statistics from being updated for
asynchronous search operations.
-
Added convenience methods to the Attribute and Entry classes
which may be used to retrieve attribute values as DNs.
-
Added convenience methods to the DN and Entry classes which
may be used to determine whether a given DN or entry is within the range of a
specified search base and scope.
Version 0.9.10
The following changes were made between the 0.9.9 and 0.9.10 releases:
-
Updated the schema parsing code so that schema elements will be held in ordered
maps so that they can be accessed in the order they were returned by the server.
This can help ensure that order-based dependencies (e.g., an object class which
inherits from a superior class) may be properly maintained if they are returned
from the server in that order.
-
Fixed a bug in the schema parsing code that incorrectly selected a generalized
time matching rule when it should have chosen an integer matching rule. This
could cause the validate-ldif tool to incorrectly report syntax violations for
data using an integer syntax, along with other failures for code relying on this
capability in the LDAP SDK.
-
Updated the LDAP SDK to add an option to operate in synchronous mode. For
connections which do not need to invoke asynchronous operations and which will
not be used concurrently by multiple threads, then the application can use the
LDAPConnectionOptions.setUseSynchronousMode(true) method to enable
synchronous mode for the connection options before connecting to the directory
server. When in this mode, responses will be read by the same thread which sent
the request, rather than by a separate reader thread. This can significantly
improve performance when communicating with the server.
Other performance improvements have also been made in the LDAP SDK which may
benefit both the default asynchronous mode as well as the new synchronous
mode.
-
Fixed a bug that could cause intermittent failures with a "server down" result
in which the connection was terminated. The problem would be triggered if the
client could not read an entire LDAP message at once and there was a significant
delay of greater than 50 milliseconds when attempting to read additional data as
part of the message. This could cause the SDK to attempt to read the middle of
an LDAP message as if it were the beginning, which would cause a decoding
failure that would trigger the SDK to terminate the connection.
-
Fixed a bug in the ObjectClassDefinition class that caused it to ignore the
recursive argument. Previously, it would always recursively get all superior
classes even if the recursive argument was set to false.
-
Fixed a bug that prevented entries returned by automatically following a
referral from being included in the search result entry count.
-
Updated the LDAPSearch example tool to include an option for following referrals
encountered during processing.
Version 0.9.9
The following changes were made between the 0.9.8 and 0.9.9 releases:
-
Updated the javadoc documentation to make the EntrySource API (and in particular
the LDAPEntrySource class) more visible. References to LDAPEntrySource are now
present in the class-level documentation for the SearchRequest class and
SearchResultListener interface.
-
Created a new SearchResultReferenceEntrySourceException as a subclass of
EntrySourceException that will be thrown if a search result reference is returned
when using the LDAPEntrySource class. This makes it easier to access the
contents of any search result references returned through this API.
-
Added LDAPException.hasControl methods that mirror the LDAPResult.hasControl
methods and provide additional convenience when working with controls in results
for operations that returned with a non-successful result.
-
Placed a maximum size on the blocking queue used to hold search result entries
and references while waiting for them to be processed. This can help prevent
problems in which a client could be potentially overwhelmed or required to use a
lot of memory for a search that returns a large number of entries when a search
result listener is used and the client cannot process entries as quickly as they
are returned. If the queue becomes full, then the LDAP SDK will push back
against the directory server so that it will only be able to send entries as
fast as the client can consume them.
-
Added the ability to control automatic referral following at a per-request level.
By default, the LDAP SDK will still use the behavior defined at the connection
level, but it is now possible to override that on a per-request level if desired.
-
Added the ability to include a call stack trace in debug log messages.
-
Updated the LDAP connection pool implementation to ensure that the auto-reconnect
connection option is ignored for connections which are part of a connection pool.
In some cases, the use of this option for pooled connections could cause
connections to be re-established when the pool had attempted to close them.
-
Added the ability to assign user-friendly names to connections and connection
pools. This can be helpful in applications which maintain multiple connections
or connection pools for different purposes. The name of the connection or
connection pool can be queried via code and will also appear in the names of the
threads used to read responses from the directory server for those connections so
that they will be more visible in thread stack traces.
-
Fixed a bug in the LDIF writer that could cause an extra space to be added to the
beginning of the last line of a multi-line comment.
-
Updated LDAP connection pool implementations so that releasing a defunct
connection will not automatically cause a new connection to be created to replace
it if the pool already has the maximum number of available connections.
Previously, the connection pool could have created and then immediately closed
a connection in that scenario.
-
Added additional connection pool statistics that can be used to help distinguish
between differences in behavior when a connection was successfully checked out of
the pool. It is now possible to differentiate between cases in which an
existing connection was returned without any wait, an existing connection was
returned after waiting for it to become available, or a new connection was
created to return to the client. This can help make information available for
applications to understand whether their connection pools are sized
appropriately.
-
Updated the LDAP SDK to change the manner in which a connection is closed if it
is done by the Java finalizer (which would presumably only occur if a connection
was leaked by the application using it). If the connection is part of a
connection pool, then it will now simply be terminated rather than released back
to the pool as a defunct connection.
-
Made the LDAPRequest.getLastMessageID() method public. This was previously used
internally, but may be useful when trying to cancel a synchronous request from a
different thread.
-
Added the ability to control the send and receive buffer sizes for sockets used
when communicating with the directory server.
-
Updated the LDAP SDK to provide better information to clients in the event that a
connection is terminated because of an unrecoverable error encountered while
reading responses from the directory server. This information was previously
only available through the debugging framework, but the LDAP SDK will now attempt
to generate a response to provide to the client with information about the
failure so that it will be available when debugging isn't enabled.
-
Added a static Attribute.getBaseName(String) method that may be used to retrieve
the base name without any attribute options for a specified attribute
description.
-
Updated the format of LDAP SDK debug messages to make them more consistent and
easier to parse.
-
Added the ability to capture a thread stack trace at the time that an attempt is
made to establish a connection. This can be useful for debugging purposes,
especially for tracking down the source of a leaked connection.
-
Added the ability to update an Entry object with one or more modifications.
-
Fixed a bug that could prevent the LDAP SDK from correctly following referrals
for search operations.
Version 0.9.8
The following changes were made between the 0.9.7 and 0.9.8 releases:
-
Fixed a bug that could prevent the LDAP SDK from returning a response to the
StartTLS extended request if the server certificate was not trusted.
-
Fixed a bug that could cause the connection pool implementation to leak a
connection when performing a background health check if that connection was
examined multiple times in the same health check sequence.
-
Fixed a bug in the LDAPConnectionPool.getRootDSE() method in which it
could inadvertently check out two connections when only one was required. Both
connections were properly returned to the pool, but holding the unnecessary
connection could create an artificial shortage of available connections.
-
Fixed a problem that caused the name of the background thread used by the
internal LDAPConnectionReader class to be set to "Connection reader for
LDAPConnection(not connected)" even when the connection was established. This
has been changed so that it will be "Connection reader for {host}:{port}" when
the connection is established, and "Connection reader for {host}:{port} (closed)"
when the connection has been closed.
-
Added a new com.unboundid.util.FixedRateBarrier class which can be used
to help try to perform operations no faster than a specified rate. The authrate,
modrate, and searchrate tools have been updated to include a new
"--ratePerSecond" argument that can be used to attempt to process
authentications, modifies, and searches at the specified rate.
-
Updated the CompareRequest class to make the
setAssertionValue(ASN1OctetString) method public, since it can be useful
in code outside of the LDAP SDK itself.
-
Added an Attribute.getMatchingRule() method that can be used to get the
matching rule that will be used by default for matching operations involving that
attribute.
-
Added the ability to easily convert between Filter objects (which are
normal search filters) and MatchedValuesFilter objects (which are used
in the matched values request control). Not all search filters are valid matched
values filters, so an attempt to convert a search filter using an AND, OR, or NOT
component, or using an extensible match component with the "dnAttributes" flag
set will throw an exception.
-
Message strings used by the LDAP SDK have been updated so that they use single
quotes rather than double quotes. If the messages generated by the LDAP SDK
(especially those included in exceptions) are consumed by and embedded in
messages from another application, then single quotes are less likely to create
confusion or need escaping if anything tries to parse those messages.
-
Updated the output of the authrate, modrate, and searchrate tools so that a row
of dashes is displayed between the column headings and the data, which moderately
improves the appearance. This will not be used when CSV-formatted output is
requested.
Version 0.9.7
The following changes were made between the 0.9.6 and 0.9.7 releases:
-
Further improved the performance of the LDIFReader for entries containing
multi-valued attributes. The change introduced the 0.9.6 version was only
applicable for entries with an LDIF representation of at least 100 lines. The
new implementation works for entries of any size and can help dramatically
improve read performance for smaller static groups, whereas the previous change
only worked for large groups.
-
Added a new com.unboundid.ldap.sdk.CompactEntry class that provides much
of the same functionality of the Entry class but in a manner that
requires much less memory. This is particularly useful for cases in which it may
be necessary to store a large number of entries in memory. For one test
involving typical user entries, CompactEntry has been found to require only about
25% as much memory as Entry. For another test involving static groups with 20
members each, CompactEntry has been found to require only about 31% as much
memory as Entry.
Note that some operations involving CompactEntry may not perform as well as with
the corresponding methods in the Entry class, so it is generally recommended that
CompactEntry only be used when it is necessary to store a large number of entries
in memory. Further, CompactEntry objects are read-only and the API does not
expose any way to directly alter their contents.
-
Fixed a potential null pointer exception that could arise as a result of a race
condition when closing a connection.
-
Made a minor change to the com.unboundid.ldif.LDIFChangeRecord class so
that the processChange method now takes an LDAPInterface
argument rather than an LDAPConnection. This change is completely
backward compatible, since LDAPConnection implements
LDAPInterface, but the new version makes it more convenient to use with
connection pools.
-
Added source code for a simple application that allows the UnboundID LDAP SDK for
Java to be used to communicate with an LDAP directory server on Android mobile
devices. This application makes it possible to perform searches against an LDAP
directory server, and can parse user entries to make it possible to call or
e-mail a user found in the directory, show a map of their location, or add
information about that user to the device's local contacts. More information
about this application can be found at
http://directorymanager.wordpress.com/2009/03/24/using-ldap-on-android/,
including a video demonstrating its use.
Version 0.9.6
The following changes were made between the 0.9.5 and 0.9.6 releases:
-
Added support for the LDAP intermediate response protocol op type as described in
RFC 3771. Intermediate responses provide the ability for operations to return
multiple responses to a single request. A new
IntermediateResponseListener interface has been added, and clients can
use the LDAPRequest.setIntermediateResponseListener method to indicate
that any intermediate response messages returned in response to that request
should be made available via that interface. If no intermediate response
listener is defined for a request, then any intermediate response messages
returned in response to that request will be silently discarded (although a debug
message will be generated).
-
Fixed a problem in the LDIFReader class in which it did not properly
propagate the LDIFException that was thrown if the first line of an
LDIF record started with a space.
-
Fixed a potential problem in the searchrate and modrate tools in which the
auto-reconnect flag did not get properly set on the connections that they used.
Before this fix, if the connection to the server was lost for some reason, then
they would not make any attempt to re-establish the connection.
-
Added a new authrate tool as an example. It can be used to measure
authentication performance, where each authentication consists of a search to
retrieve a user entry followed by a bind to verify the password for that user.
It supports simple authentication, as well as the CRAM-MD5, DIGEST-MD5, and PLAIN
SASL mechanisms.
-
Updated the CommandLineTool API to make it possible to include example
usages for tools that will be included whenever the usage information is
displayed. This can make it easier to understand how a given tool might be used.
The example tools provided with the LDAP SDK have been updated to provide this
capability.
-
Updated LDAP connection pools to provide support for a maximum connection age.
If a maximum connection age is defined, then any connection which has been
established for a longer period than this will be closed and replaced with a new
connection.
-
Created a new LDAPConnectionStatistics class that can be used to provide
information about the processing performed by the LDAP SDK. The connection
statistics can be retrieved using the
LDAPConnection.getConnectionStatistics method, and they include
information about the number of times the connection has been established and
closed, the number of times each type of request message has been sent, the
number of times each type of response message has been received, and the total
and average response times for those operations. This feature was suggested by
Philip Peake.
-
Created a new LDAPConnectionPoolStatistics class that can be used to
provide information about the processing performed by the connection pool. The
connection pool statistics can be retrieved using the
LDAPConnectionPool.getConnectionPoolStatistics() method, and they
include the number of connections currently available in the pool, the maximum
number of connections that may be maintained in the pool, the number of
successful and failed attempts to create connections, the number of connections
that have been closed as defunct, expired, or unneeded, the number of successful
and failed attempts to retrieve a connection, and the number of valid connections
released back to the pool. This feature was suggested by Philip Peake.
-
Updated LDAP connection pools to provide support for connection health checking.
Health check implementations may be used to perform custom checks to determine
whether a connection is valid at any of the following times:
- Whenever a new connection is created for use in the pool
- Whenever a connection is checked out of the pool
- Whenever a connection is released back to the pool
- After an exception has been caught while processing an operation in the
pool
In addition, a background thread will be used to periodically invoke health
checks against all available connections. The ServerSet API has been
updated to provide the ability to make use of a health check in the course of
creating new connections. A health check implementation has been provided that
can be used to retrieve a specified entry from the directory server. The ability
or inability to retrieve the entry, as well as the time required to do so, can be
taken into consideration. This feature was suggested by Philip Peake.
-
Added a number of convenience methods to the DN and RDN class that make it easier
to interact with them using their string representations. For example, there are
now methods for determining if a string represents a valid DN or RDN, if two
strings represent the same DN or RDN, to determine whether there is a
hierarchical relationship between two strings representing DNs, and to compare
two DNs or RDNs based on their string representations. This feature was
suggested by Felix Gaehtgens.
-
Updated the LDIF reader to significantly improve performance when reading entries
containing attributes with a large number of values (e.g., large static groups).
In a single-threaded test case involving reading static group entries with 2000
members each, performance has been improved by over 360x (i.e., over 36,000%).
This problem was reported by Felix Gaehtgens.
Version 0.9.5
This was the initial public release of the UnboundID LDAP SDK for Java.