UnboundID LDAP SDK for Java Documentation

Release Notes

Version 4.0.0

The following changes were made between the 3.2.1 and 4.0.0 releases:

  • The LDAP SDK now requires Java SE 7 or later. It was previously possible to build and run the LDAP SDK with Java SE 1.5 or later, but now neither Java SE 1.5 nor Java SE 1.6 are supported. We officially support Java SE 7 and 8. There are known issues with building the LDAP SDK in early access versions of Java SE 9, but a version of the LDAP SDK built on Java SE 7 or 8 should run without problems under Java SE 9.

  • We no longer maintain separate editions of the LDAP SDK. Previously, we had three different editions: Standard Edition, Commercial Edition, and Minimal Edition. While there were valid reasons for them in the past, those reasons no longer apply, and it is simpler to maintain just a single edition. The new edition is simply called "UnboundID LDAP SDK for Java", and it contains all of the content that had previously been in the Commercial Edition (which was itself a superset of the Standard Edition, which was a superset of the Minimal Edition).

  • The GitHub repository for the UnboundID LDAP SDK for Java has been moved into the Ping Identity organization. The URL to the repository has changed from https://github.com/unboundid/ldapsdk to https://github.com/pingidentity/ldapsdk, but a redirect is in place to ensure that clients using the old URL are automatically transferred to the new location.

  • The content in the open source repositories for the LDAP SDK (on GitHub at https://github.com/pingidentity/ldapsdk and on SourceForge at https://sourceforge.net/p/ldap-sdk/code/HEAD/tree/) now matches the content in the internal repository. The full source code for all LDAP SDK unit tests is now available, along with some supporting build components.

  • Fixed a bug in the logic for parsing DNs with RDN values that used a raw BER encoding, which is indicated in the string representation by starting an attribute value with the octothorpe (#) character. The LDAP SDK would incorrectly use the entire set of bytes (representing the BER type, length, and value of the BER element) following the octothorpe character as the attribute value instead of just the BER value.

  • Fixed a bug in the LDAP connection pool that could cause the pool to lose a connection if createIfNecessary is false and if the replaceDefunctConnection method was called but could not successfully create a new connection. If this happened enough times, the pool could run out of connections, and it would refuse to create new ones.

  • Fixed a bug that could cause the LDAP SDK to use the same message ID for all stages of a multi-stage SASL bind instead of using a different message ID for each stage.

  • Fixed a bug in the in-memory directory server LDIF import code that prevented imported entries from being subjected to the configured schema.

  • Fixed a bug in the in-memory directory server's handling of LDAP subentries. The server could incorrectly return entries that are not LDAP subentries in response to a search request that included the LDAP subentries request control.

  • Fixed a bug that could cause tools to incorrectly launch in interactive mode even if default values for some tool arguments were provided through a properties file.

  • Updated the ldapmodify tool to fix a bug that could cause it to use an exit code of zero even if an error was encountered while reading LDIF data. It would have always used a nonzero exit code for unrecoverable LDIF parsing errors, but the exit code may not have indicated a problem if the error was recoverable and the tool was able to continue parsing subsequent LDIF records.

  • Updated the ldapmodify tool to fix a bug that could cause it to incorrectly use an exit code of zero when processing operations as part of a transaction but the attempt to commit the transaction was unsuccessful.

  • Updated the ldapsearch tool so that the -T argument is associated with the tool-specific --dontWrap argument rather than the generic --trustStorePassword argument that is normally the case for other LDAP tools. This provides better backward compatibility with other versions of the ldapsearch tool.

  • Updated the ldapsearch tool to add support for the --skipResolvingExplodedIndexes, --fastShortCircuitThreshold, and --slowShortCircuitThreshold options for the matching entry count request control. These options had previously been overlooked.

  • Fixed a bug in the ldapsearch tool that caused it to omit all attributes when run with the --typesOnly argument, indicating that attributes should be returned without any values.

  • Fixed a bug in the LDAP SDK argument parser that involved reading Boolean arguments from a properties file. If a Boolean argument were assigned a value of false in a properties file, that argument would incorrectly be listed among the command-line arguments obtained from the properties file.

  • Updated all copyright notices to reference Ping Identity rather than UnboundID.

  • Updated the LDAP SDK documentation to use Ping Identity branding.

  • Updated the LDAP SDK documentation to include an LDAPv3 wire protocol reference document that provides in-depth coverage of the ASN.1 Basic Encoding Rules (BER) and all kinds of LDAP request and response messages with annotated examples.

  • Updated the LDAP SDK documentation to include a new LDAP result code reference document.

  • Updated the LDAP SDK documentation to include a new LDAP OID reference document.

  • Updated the set of LDAP-related specifications to include RFC 2926 (Conversion of LDAP Schemas to and from SLP Templates), RFC 2985 (PKCS #9: Selected Object Classes and Attribute Types Version 2.0), RFC 4226 (HOTP: An HMAC-Based One-Time Password Algorithm), and RFC 6238 (TOTP: Time-Based One-Time Password Algorithm).

  • Updated the set of LDAP-related specifications to include the latest revisions of the draft-kille-ldap-xmpp-schema, draft-seantek-ldap-pkcs9, and draft-wibrown-ldapssotoken drafts.

  • Updated the build-time collection of information about the source repository to include support for git in addition to the existing support for subversion. If the LDAP SDK is checked out from a git repository, the generated com.unboundid.ldap.sdk.Version class will now include the repository URL and revision ID associated with that git repository.

Version 3.2.1

The following changes were made between the 3.2.0 and 3.2.1 releases:

  • Updated the documentation to indicate that non-public feedback, feature enhancements, support requests, and other kinds of communication should now be sent to ldapsdk-support@pingidentity.com instead of ldapsdk-support@unboundid.com. We also now recommend using the GitHub issue tracker over the SourceForge mailing lists and discussion forums for bug reports and feature requests.

  • Fixed a bug in the RDN parsing code that could cause multiple consecutive spaces in the middle of an attribute value to be condensed down to a single space. The string representation of the RDN was preserved correctly, but the methods used to retrieve attribute values as strings or byte arrays returned the values without all of the spaces.

  • Provided better handling for InterruptedException exceptions. A thread's interrupted state will now be preserved for cases in which the LDAP SDK consumes an InterruptedException without doing something to handle it.

  • Fixed a bug in the support for the ANONYMOUS SASL mechanism that could cause the trace string to be omitted from the encoded bind request sent to the directory server.

  • Updated the searchrate tool to provide support for generic controls, as well as specific support for the assertion, simple paged results, and server-side sort request controls.

  • Updated the authrate tool to add a new --bindOnly argument allows you to indicate that the tool should only perform bind operations, and should omit the initial search used to find the entry for the target user. The base DN pattern will be used to construct the bind DN.

  • Updated the authrate tool to provide support for generic search and bind controls, as well as specific support for the authorization identity and password policy request controls.

  • Updated the search-and-mod-rate tool to provide support for generic search and modify controls, as well as specific support for the assertion, simple paged results, permissive modify, pre-read, and post-read request controls.

  • Added a Schema.getSchema method that can read schema information (in LDIF form) from an input stream. This is in addition to the existing getSchema methods that can be used to read schema from an LDAP server and from one or more LDIF files.

  • Updated the support for the GSSAPI SASL mechanism to make it possible to explicitly indicate whether the client should be a GSSAPI initiator or acceptor in the generated configuration file.

  • Updated the support for the server-side sort request control to add constructors that allow the sort keys to be provided in a list as an alternative to the existing varargs version that allows them to be provided in an array.

  • Updated the support for the matched values request control to add constructors that allow the matched values filters to be provided in a list as an alternative to the existing varargs version that allows them to be provided in an array.

  • Updated the identify-unique-attribute-conflicts tool to include a time limit in search requests intended to determine whether a unique attribute value may also be in use in any other entries. This can help limit the effect of running the tool against a server that is not configured with the appropriate indexes to ensure that equality searches targeting the unique attributes can be processed efficiently.

  • Updated the in-memory directory server to respect the client-requested time limit if that limit is exceeded because of a processing delay that has been configured for the server.

  • Improved the Javadoc documentation for the argument parser to indicate that arguments provided to the addDependentArgumentSet, addExclusiveArgumentSet, and addRequiredArgumentSet methods must have already been registered with the argument parser.

  • Improved the Javadoc documentation for the JSON support to better describe the behavior of the toString, toSingleLineString, and toNormalizedString methods, and to make it clear that the JSONString.toStringtt> method includes the surrounding quotation marks and may have special characters escaped, and the stringValuett> method should be used to obtain the unquoted and unescaped value.

  • Updated the set of LDAP-related specifications to include a reference to the draft-ietf-ldapext-ldap-c-api specification.

  • Added a new version of the ldapsearch tool that provides a lot of additional functionality. It includes much better output formatting (including support for alternate output formats, including JSON, CSV, and tab-delimited text), support for a number of data transformations, more robust connection handling, support for referrals, support for a large number of search and bind controls, support for administrative sessions, support for unsolicited notifications, the ability to process multiple searches with search criteria provided in filter files or LDAP URL files, rate limiting, and the ability to send results to a specified output file (or a separate output file per search).

  • Added a GetUserResourceLimitsResponseControl.getOtherAttribute method that makes it more convenient to get an "other" attribute by name.

  • Implemented caching for the matching rule instance used when the jsonObjectExactMatch matching rule is requested. This matching rule only exists in the Commercial Edition and needs to be loaded via reflection, but that can be expensive if it's done a lot. Caching the result means that we only need to pay that cost once.

  • Updated the access and error log parsing APIs to include support for the triggeredByConn and triggeredByOp fields used to indicate that the message is associated with a given operation.

Version 3.2.0

The following changes were made between the 3.1.1 and 3.2.0 releases:

  • Added a new transform-ldif tool that can be used to apply a number of transformations to data in an LDIF file, and to make these transformations available for programmatic use. This includes:
    • The ability to scramble, replace, redact, or exclude a specified set of attributes.
    • The ability to replace existing values with a specified attribute, or with a generated value that includes a sequential counter.
    • The ability to add a given set of attribute values to entries matching a specified set of criteria.
    • The ability to exclude entries matching a specified set of criteria.
    • The ability to rename attributes.
    • The ability to replace the base DN for entries in a specified subtree.
    • The ability to flatten a DIT, to ensure that all entries more than one level below a specified base DN are moved so that they are directly below that base DN.


  • Updated the EntryValidator class and the validate-ldif tool to provide additional options. It can now check to see if all attribute values contained in an entry's RDN are also present in the entry attributes, can ignore attribute syntax violations on a per-attribute basis, and can check attribute values for compliance with a number of UnboundID-specific attribute type constraints, including X-ALLOWED-VALUE, X-VALUE-REGEX, X-MIN-VALUE-LENGTH, X-MAX-VALUE-LENGTH, X-MIN-VALUE-COUNT, X-MAX-VALUE-COUNT, X-MIN-INT-VALUE, and X-MAX-INT-VALUE.

  • Updated all classes that offer a public void close() method that doesn't throw any exceptions other than a possible IOException so that they implement the java.io.Closeable interface. This includes classes like LDAPConnection, LDAPConnectionPool, LDIFReader, LDIFWriter, all EntrySource implementations, and others. This allows code using these classes to take advantage of the try-with-resources facility introduced in Java SE 7.

  • Added support for parsing entries that contain information about the operations processed in the server, using the syntax described in the draft-chu-ldap-logschema-00 draft.

  • Updated the modrate tool to make a number of improvements, including:
    • The --valueCount argument can be used to specify the number of values to use for replace modifications.
    • The --increment argument can be used to indicate that the tool should perform increment modifications rather than replace modifications. The --incrementAmount argument can specify the amount by which values should be incremented (or decremented, in the case of a negative value).
    • The --assertionFilter argument can be used to include an LDAP assertion request control in modify requests so that the change will only be applied if the target entry matches the specified filter.
    • The --permissiveModify argument can be used to include a permissive modify request control in modify requests.
    • The --preReadAttribute and --postReadAttribute arguments can be used to include the pre-read or post-read request control in modify requests.
    • The --control argument can be used to include arbitrary controls in modify requests.


  • Added a new JSONBuffer class that can be used to efficiently construct the string representation of a JSON object, and a JSONObjectReader class that can be used to read JSON objects from an input stream.

  • Added the ability to generate formatted, multi-line string representations of JSON objects with better human readability.

  • Updated the in-memory directory server to add support for the LDAP no-operation control as described in draft-zeilenga-ldap-noop-12.

  • Dramatically improved the robustness for both the identify-references-to-missing-entries and identify-unique-attribute-conflicts tools. They now use connection pools with automatic retry in the event of an error that indicates the connection may no longer be valid.

  • Added a new base64 command-line tool that can be used to encode and decode data using the base64 format.

  • Updated the LDIF reader to make it possible to specify the character set to use when reading LDIF data. Previously, the character set was always assumed to be UTF-8.

  • Updated the LDIF writer to make it possible to automatically include a comment below any base64-encoded values that provides a non-base64-encoded representation (with special characters escaped) of the preceding value.

  • Dramatically simplified the exception message used if it is not possible to establish a connection to the directory server.

  • Updated the command-line argument parser to provide support for subcommands with their own distinct sets of arguments.

  • Updated the command-line argument parser to add support for timestamp arguments, whose values are either timestamps in generalized time format (which explicitly specifies the time zone), or timestamps in the form YYYYMMDDhhmm,YYYYMMDDhhmmss, or YYYYMMDDhhmmss.uuu (generalized time without a time zone specifier) that will be assumed to be in the local time zone. A new timestamp range argument value validator can be used to ensure that timestamp values are only permitted to be within a specified range.

  • Updated the command-line argument parsing framework to add support for an IP address argument value validator. This can be used to configure an argument to only accept properly-formed IPv4 or IPv6 addresses.

  • Updated the command-line tool API to provide the ability to default to interactively prompting for bind passwords when appropriate. Tools would previously only prompt for a password if explicitly requested to do so using the --promptForBindPassword argument.

  • Updated the command-line tool API to provide the ability for tools to offer an --outputFile argument that causes them to send their output to a specified file. It can be paired with the --teeOutput argument to cause the output to be sent to both the specified file and to the console. The --appendToOutputFile argument will cause the tool to append to an existing output file rather than overwriting it.

  • Updated the LDAP command-line tool API to make the --bindDN and --saslOption arguments are mutually exclusive. None of the supported SASL mechanisms make use of a bind DN, and combining these options is only likely to cause confusion.

  • Updated the SSLUtil methods for creating SSL server sockets so that their enabled protocols will be set more intelligently. This was already in place for SSL client sockets, but had been overlooked for server sockets.

  • Updated the aggregate trust manager to provide a more useful error message when none of the nested trust managers accept a presented certificate.

  • Updated the rate adjustor so that when using a rate tool to generate a sample rate data file, the resulting file will now include a number of additional examples of common rate patterns, including square, stairstep, sine, sawtooth, triangle, and hockey stick.

  • Updated the command-line tool API so that if any tool registers a shutdown hook (to allow it to perform cleanup in the event of an unexpected graceful JVM termination), that shutdown hook will be de-registered if the tool completes its processing without an unexpected JVM shutdown.

  • Added a utility class for reading a file containing entry DNs. Blank lines and lines containing comments will be ignored. Each DN must be on a line by itself, and it may optionally be prefixed by "dn:". It is also possible to include base64-encoded DNs prefixed by "dn::".

  • Added a utility class for reading a file containing search filtersNs. Blank lines and lines containing comments will be ignored. Each filter must be on a line by itself.

  • Updated the code used to parse a search filter from its string representation to support up to 100 levels of nesting rather than the previous maximum of 50 levels.

  • Added new convenience methods and constructors for use when programmatically creating schema elements.

  • Updated the LDAPBindException.toLDAPResult and LDAPExtendedOperationException.toLDAPResult methods so that they return the underlying BindResult or ExtendedResult rather than creating a new generic LDAPResult

  • Updated the Netscape Directory API migration support to make it possible to abandon a search operation with an LDAPSearchResults object.

  • Updated the JNDI migration support to make it possible to specify a context base DN when converting between an LDAP SDK entry and a JNDI search result.

  • Updated the LDAP SDK documentation to include the latest revisions of updated IETF drafts, including draft-seantek-ldap-pkcs9 and draft-wibrown-ldapssotoken.

  • Added a version of the ldapmodify tool with support for a wide range of features, including a wide range of controls, LDAP transactions and multi-update operations, following referrals, bulk operation processing, rate limiting, and automatically retrying operations that fail in a manner that indicates the connection may no longer be usable.

  • Added a new manage-account tool that can be used to perform a large number of password policy state operations on a specified user entries, or on sets of user entries. This tool is completely backwards-compatible with the manage-account tool formerly provided with UnboundID server products (and in fact, that tool has now been replaced with the version included in the LDAP SDK), but the new tool provides support for many more operations, and much better support for bulk operations that target multiple users instead of just one. The LDAP SDK's support for the password policy state extended operation has also been updated to make it possible to take advantage of a number of new operation types.

  • Added a new split-ldif tool that can be used to split a single LDIF file so that entries below a given base DN are split into multiple distinct sets. This may be useful for preparing data for use with the Directory Proxy Server in an entry-balancing deployment. The data may be split according to a number of types of criteria.

  • Added support for a new task that can be used to trigger the rotation of one or more server log files.

  • Added support for "generate TOTP shared secret" and "revoke TOTP shared secret" extended operations, which can be used to help automate the process of configuring a user account to support two-factor authentication with the UNBOUNDID-TOTP SASL mechanism. A new generate-totp-secret command-line tool is also provided, which can be used to invoke these extended operations from the command line.

  • Added support for the UNBOUNDID-EXTERNALLY-PROCESSED-AUTHENTICATION SASL mechanism, which can be used to indicate that a user has attempted to authenticate through some mechanism that is external to the Directory Server, but allows the server to override a successful authentication attempt to indicate a failure (e.g., if the user's account is in an unusable state, like being disabled or locked, or having an expired password), or to perform any appropriate state processing (e.g., to update the last login time and IP address for a successful authentication, or the failure count for a failed attempt).

  • Added support for parsing the new index monitor attributes used for counting keys near and over the index entry limit that have been accessed while processing search and update operations. Also updated the log parsing API to support parsing the corresponding elements from access log messages.

  • Fixed a bug in the summarize-access-log tool that could cause it to take a very long time to process log messages for search operations with certain types of very deeply-nested filters.

Version 3.1.1

The following changes were made between the 3.1.0 and 3.1.1 releases:

  • Updated the AddRequest constructor that allows you to create an add request from lines that compose the LDIF representation so that you can use an LDIF add change record (including the "changetype: add" line, and optionally including one or more controls) as an alternative to providing the LDIF representation of an entry.

  • Added two new LDAP listener request handler implementations that can be used to limit the load that LDAP clients are able to impose on the server. The concurrent request limiter implementation imposes a limit on the number of requests that may be processed simultaneously. The rate limiter implementation imposes a limit on the maximum rate of operations that may be processed in a particular time period.

  • Fixed a bug in which the LDAP connection pool statistics were not always properly updated after an unsuccessful attempt to establish a new connection for use in the pool.

  • Updated LDAP command-line tools to provide a new "--helpSASL" argument that can be used to display information about the supported SASL mechanisms and the SASL options available for each mechanism.

  • Updated the command-line argument parser to the use of a properties file for obtaining default values for a specified set of arguments. This can help administrators define a properties file with commonly-used argument values (e.g., LDAP server address, port, TLS settings, bind DN, etc.) so that they do not need to be explicitly specified in the set of arguments when running a tool. Command-line tools can choose to enable or disable this feature, and tools that enable it will also have an option to generate a template file that makes it easier to specify the desired properties for that file.

  • Updated the command-line argument parser to support assigning group names to arguments. This allows related arguments to be grouped together in the usage information obtained with the "--help" argument.

  • Updated command-line tools to provide alternate long identifiers for a number of arguments. This primarily covers the difference between camelCase versus dash-separated words (e.g., what was previously only available as "--bindDN" can now alternately be specified as "--bind-dn").

  • Updated the documentation to include the most recent versions of a number of LDAP-related specifications.

  • Added client-side support for a new UNBOUNDID-YUBIKEY-OTP SASL mechanism that can be used to perform single-factor or two-factor authentication using a one-time password generated by a YubiKey device.

  • Added client-side support for a pair of extended operations that can be used to register or deregister YubiKey OTP devices for use by a specified user.

  • Updated the matching entry count request control to provide support for new options that allow the client to have some control over the balance between how quickly the matching entry count estimate should be obtained versus how accurate that estimate should be. In particular, it is now possible for the client to control the short-circuit threshold, and to indicate whether to actually retrieve entry ID sets from exploded indexes in the case that the number of entries in the set is already known.

Version 3.1.0

The following changes were made between the 3.0.0 and 3.1.0 releases:

  • Updated the command-line tool API to make it possible to run tools in an interactive mode. This mode, which is enabled by default in most of the example tools that ship with the LDAP SDK, allows the tool to prompt the user for the values of all the connection and authentication details, as well as for any tool-specific required properties. It will then display a menu that can be used to edit the arguments, run the tool with the specified settings, and display the command-line arguments to run the tool with those settings in non-interactive mode.

  • Updated the ldap-debugger tool to add the ability to generate source code that can be used to process all of the operations passing through it. The in-memory directory server has also been updated to provide a similar capability. This can help make it easier to migrate applications written using other APIs to the UnboundID LDAP SDK.

  • Updated the LDAP connection pool to make it possible to configure a minimum available connection goal. If set, the connection pool will try to maintain at least this many connections available for immediate use. This can help avoid application performance problems that can result if the pool is empty and connections must be created on-demand for new requests.

  • Added support for LDIF translators that can be used to transform LDIF change records when reading from or writing to LDIF. These translators are especially useful when using multiple threads to read or write multiple change records in parallel.

  • Updated the GSSAPI bind request implementation to add the ability to obtain credentials from a keytab, and to indicate that the configuration should be refreshed before attempting the JAAS login.

  • Updated the in-memory directory server to make it possible to use a specific entry as the root DSE instead of the dynamically-generated version.

  • Updated the LDAP listener framework and the in-memory directory server to make it possible to limit the number of connections that may be established at any given time.

  • Added new Entry.applyModifyDN methods that can be used to retrieve a new entry that reflects the changes associated with processing a modify DN operation against that entry. In addition to updating the DN for the entry, it will also apply any appropriate attribute changes for the entry's new RDN.

  • Improved support for the LDAP SDK's automatic selection of enabled TLS protocols to improve compatibility with TLS implementations that do not support the most recent TLS protocol offered by the JVM and also don't properly handle a TLS client hello message that references the newer protocol.

  • Updated the LDAP SDK so that it will always throw an LDAPException if the server returns a non-success result for a StartTLS extended operation. It was previously possible for the LDAP SDK to return a non-success result without throwing an exception (as is the case for other types of extended operations), but that could potentially cause the client to continue using a connection that it incorrectly believed to be secure.

  • Added the ability to create a StartTLSPostConnectProcessor with an SSLSocketFactory instead of an SSLContext. Using a socket factory created with the SSLUtil.createSSLSocketFactory will provide better support for a the full range of enabled TLS protocols.

  • Added a new LDAPBindException class that is a subclass of LDAPException and can provide access to the server SASL credentials returned to the client in a bind failure.

  • Added a new LDAPExtendedOperationException class that is a subclass of LDAPException and can provide access to the OID and value returned to the client in an extended operation failure.

  • Improved the LDAP SDK's handling of connect timeouts to ensure that a connection attempt is less likely to block for longer than the configured connect timeout.

  • Updated the LDAP connection pool health check to add the ability to perform validation after the pool performs a bind, either at the time a connection is created or when the pool re-authenticates a connection as a result of a call to bindAndRevertAuthentication or releaseAndReAuthenticateConnection.

  • Added a new password expiration LDAP connection pool health check that can be used to warn about or reject connections in which the bind result indicates a current or upcoming password-policy-related problem like password expiration or account lockout.

  • Added a new aggregate LDAP connection pool health check that can be used to invoke multiple health checks as a single unit.

  • Added a new aggregate post-connect processor that can be used to invoke multiple post-connect processors as a single unit.

  • Updated the LDAP command-line tool API to make it possible to specify more options when creating a connection pool using the settings provided via command-line arguments.

  • Updated the LDAP SDK to include Java implementations from Azul Systems in the whitelist of JVMs that permit concurrent socket factory use by default.

  • Fixed a potential thread safety problem in the LDAPConnectionPool.releaseAndReAuthenticateConnection method.

  • Deprecated the LDAPConnectionOptions support for auto-reconnect. It has always been inherently fragile and only useful under limited circumstances. Using a connection pool, even when only a single connection is expected at any given time, is a much more reliable and feature-rich way to achieve the same benefits.

  • Updated the LDIF reader to be more permissive when encountering mismatches between the declared attribute description for a modification and the attribute description provided with the set of values. It will now accept differences in the order of attribute options, and, if a schema is available, will accept equivalent names (or the numeric OID) for an attribute type. It can also handle the case in which the binary transfer option was not included in the initial attribute description but is used in one or more values.

  • Updated the LDIF reader to make it possible to specify the trailing space behavior when using static methods to decode LDIF entries and change records.

  • Added minimal constructors for a number of argument types that assume common values for a number of properties. Also added default placeholder strings for arguments so that it is not always necessary to provide a non-null value when creating an argument.

  • Improved the argument descriptions for arguments in performance testing tools (including searchrate, modrate, authrate, and search-and-modrate) to provide the URL to online documentation that describes complete details for the value pattern syntax.

  • Updated the methods used to retrieve schema information from the directory server so that they use the correct "(objectClass=subschema)" filter and will request all user attributes in addition to the schema-related operational attributes. Also, ensure that schema entries read from LDIF files always include at least the top, ldapSubentry, and subschema object classes.

  • Removed the @ThreadSafety annotation from the ThreadSafetyLevel enum class, since an enum should not be marked with an annotation whose argument list includes a value of that enum. This will also eliminate a compile warning when building a Scala application that uses the LDAP SDK.

  • Updated the way that the LDAP SDK maintains thread-local buffers used for building LDAP messages. Previously, the LDAP SDK would create thread-local buffers and maintain them for the life of the threads used to construct LDAP messages. It will now only maintain these buffers as long as there is at least one connection established. Once all connections are closed, any buffers that may have been created will be freed.

  • Updated the documentation to include the most recent versions of a number of LDAP-related specifications.

  • Added support for a new "name with entryUUID" control that can be included in an add request to indicate that the resulting entry should use the server-generated entryUUID as the naming attribute.

  • Added support for a new get password policy state issues request control that may be included in a bind request under certain circumstances to obtain detailed information about notices, warnings, and errors pertaining to the password policy state for the user trying to authenticate.

  • Updated support for the password policy state extended operation to provide access to additional information, including the last authentication time, the account activation time, and summaries of the notice, warning, and error conditions for the user's password policy state.

  • Added support for a new task that can be used to synchronize encryption settings definitions between server instances within the same topology.

  • Added new result codes that may be used to obtain information about the status of an attempt to deliver a one-time password, a password reset token, or a single-use token.

  • Added a new start administrative session post-connect processor that can be used to create a connection pool in which the connections are part of an administrative session.

Version 3.0.0

The following changes were made between the 2.3.8 and 3.0.0 releases:

  • Make the UnboundID LDAP SDK for Java available via GitHub at https://github.com/UnboundID/ldapsdk. The SourceForge subversion repository, mailing lists, and discussion forums will continue to be maintained in addition to the new GitHub support.

  • The LDAP SDK now includes support for using a JSON-based configuration to specify a number of settings that can be used to create LDAP connections and connection pools. This includes options for connecting to a single server or selecting from a group of servers using a number of algorithms, securing communication with SSL or StartTLS, and authenticating connections using simple or SASL mechanisms. Basic support for creating, parsing, and interacting with general-purpose JSON objects is also available.

  • Fix a bug in the LDIF reader's attribute parsing code that could prevent it from using the correct matching rule for attributes read from LDIF.

  • Fix a bug that could cause the Schema class to throw a null pointer exception when attempting to get the set of required or optional attribute type definitions for an object class in the event that any of the superclasses were not defined in the schema.

  • Add the ability to manually invoke a synchronous health check against an LDAP connection pool, optionally with a different health check mechanism than is otherwise configured for the pool.

  • Update the default LDAP connection pool configuration so that it no longer has the possibility of blocking for up to five seconds while waiting for a connection to be released if one is needed but none are immediately available.

  • Ensure that connection pool statistics are properly updated when a connection is closed as a result of a health check failure.

  • Update support for parsing command-line arguments to add special support for arguments that describe LDAP controls, and to add improved support for ensuring that argument values match a number of common formats.

  • Improve support for establishing connections with a connect timeout to try to separate the process of creating a socket and connecting it to the target server whenever possible.

  • Add the ability to specify an alternate key or trust store type when running the in-memory directory server via the command line.

  • Update the value pattern support to make it possible to access the contents of files in sequential order. It was previously only possible to access file contents in random order.

  • Update the identify-unique-attribute-conflicts example tool to make it possible to only identify conflicts in entries that match a given filter.

  • The Commercial Edition of the UnboundID LDAP SDK for Java is now open source under the terms of the GNU General Public License version 2 and the GNU Lesser General Public License version 2.1. The Commercial Edition source code is available in the GitHub repository at https://github.com/UnboundID/ldapsdk.

  • Add support for a new JSON object filter mechanism, which can be used to perform advanced matching against JSON objects stored in the Directory Server.

  • Add support for a new deliver password reset token extended operation that can generate a single-use token and deliver it to a specified user through some out-of-band mechanism (e.g., email, SMS, voice call, etc.). This password reset token can be provided to the password modify extended operation as an alternative to the user's current password in order to allow that user to choose a new password.

  • Add support for a new get password quality requirements extended operation that can be used to retrieve information about the constraints that the server will impose on user passwords. A new set of password validation details request and response controls can be used to obtain information about the result of any validation performed against a password included in the associated request.

  • Add support for a new deliver single-use tokens extended operation that can be used to generate and deliver single-use tokens for arbitrary purposes (e.g., for validating a provided email address or phone number). The new consume single-use tokens extended operation can be used to consume those tokens after they have been delivered.

  • Add support for a new get supported OTP delivery mechanisms extended operation that can be used to determine which out-of-band mechanisms can be used to deliver one-time passwords, password reset tokens, and other single-use tokens to a specified user.

  • Add support for creating and interacting with the Directory Proxy Server's reload global index task.

  • Update the matching entry count control to add the ability to determine whether the associated search is considered indexed.

  • Add a new get changelog batch change selection criteria that can be used to target only changelog entries that match a specific notification destination.

  • Update access log parsing support to provide the ability to get information about any privileges used, or any required privileges that were missing, in the course of processing an operation.

  • Update the javadoc documentation for all Commercial Edition classes to add a note to help clarify that they are part of the Commercial Edition and are not available in the Standard Edition of the LDAP SDK.

Version 2.3.8

The following changes were made between the 2.3.7 and 2.3.8 releases:

  • Fix a synchronization bug in the in-memory directory server that could potentially cause a concurrent modification exception under concurrent load from multiple connections.

  • Add a new Filter.simplifyFilter method that can be used to simplify a search filter in a manner that may allow some directory servers to process the search more efficiently. Some searches used within the persistence framework have been updated to use this method to simplify the filters generated for those searches.

  • Add a utility class that can be used to work with OIDs.

  • Update the documentation to include a number of LDAP specification documents, including LDAP-related RFCs and Internet Drafts, as well as an OID reference and a result code reference.

  • Updated the UnboundIDChangelogEntry class to add support for the upcoming ds-changelog-target-attribute attribute, which will indicate which attributes were included in the associated change.

  • Updated the access log parsing framework to add support for the usedPrivileges and missingPrivileges access log elements.

Version 2.3.7

The following changes were made between the 2.3.6 and 2.3.7 releases:

  • Update the logic used to control the default set of enabled SSL protocols. SSLv3 is now disabled by default (in response to the recent POODLE bug that could cause SSLv3 connections to be decrypted by a network observer), and the set of enabled protocols is more broadly compatible than was previously the case when running on IBM VMs.

  • 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.

  • Add a new "database lock conflict" result code that may be returned by the UnboundID Directory Server.

  • Expose the LDAPConnection.getStartTLSRequest method so that it can be used by third-party code that might want to be able to process StartTLS operations in the same way as had been performed for the associated connection.

  • 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 in the Entry.applyModifications method that could cause it to reject a valid modifications that targets an attribute used in the entry's RDN even if the modification would not alter the entry RDN.

  • Fix a bug in the Entry.diff method when given a specific set of attributes to process. Attributes with options would be incorrectly excluded from the attributes that were processed.

  • 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.

  • Fix a bug in the way that a connection retained a handle to the last bind request processed on that connection. This could be incorrect in some cases if the bind was processed using the UnboundID-proprietary retain identity request control.

  • Fix a bug in the prompt trust manager that could cause it to enter an infinite loop if the end of the input stream was reached while waiting for confirmation about whether to trust the certificate.

  • Eliminate a potential null pointer exception that could arise from a race condition in the course of closing a connection.

  • Eliminate a potential illegal argument exception that could be thrown if an attempt is made to close the pool using multiple threads if there are currently no connections in the pool.

  • 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.

  • Add support for a get backend set ID control, which can be used to request that the Directory Proxy Server return information about which entry-balancing backend set(s) were used to process the associated operation.

  • Add support for a route to backend set control, which can be used to influence the entry-balancing backend set(s) to which the Directory Proxy Server forwards a request for processing.

  • Add support for a matching entry count control, which can be used to request that the Directory Server or Directory Proxy Server return information about the number of entries that match the search criteria rather than returning the matching entries themselves.

  • Add support for a transaction settings request control that may be included in an end transaction or atomic multi-update extended request to specify a number of transaction-related settings that should be used when processing and committing the transaction.

  • Add support for a number of extended operations that may be used to interact with notification destinations and subscriptions in the UnboundID Directory Server.

  • Update support for the set subtree accessibility extended request to make it possible to atomically alter the accessibility of multiple subtrees in a single request.

  • Add support for parsing alarm entries as exposed in the alarms backend.

  • Add support for retrieving and parsing the group cache monitor entry.

  • Add support for retrieving and parsing the recent CPU and memory usage monitor entry.

  • Add support for retrieving and parsing the result code monitor entry.

  • Add support for retrieving and parsing gauge monitor entries.

  • Update the support for the processing time histogram monitor entry to make it possible to retrieve information about extended operations, and to support an upcoming format change for aggregate percent values.

  • Update the support for the load-balancing algorithm monitor entry to make it possible to retrieve information about aggregate local and non-local health check states, as well as the name of the load-balancing algorithm.

  • Update the deliver-one-time-password tool so that it provides a more useful error message if the underlying extended request does not complete successfully.

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.

  • Add support for the retire password and purge password request controls. Also update the password policy state extended request to support a number of operations for interacting with retired passwords, and update the access log parser to support the new retiredPasswordUsed element that may appear in bind response messages.

  • Add support for load-balancing algorithm monitor entries.

  • Update the class-level documentation for the start interactive transaction extended request to indicate that it is no longer recommended for use, and to suggest alternative means of achieving atomicity and/or bulk operations.

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.

  • Add support for a new list configurations extended operation, which may be used to request information about active, baseline, and archived configurations available to the server, and a get configuration extended operation, which may be used to retrieve a specific version of the configuration. These are primarily intended for use in processing performed by the new config-diff tool, but may be useful in other contexts as well.

  • Add support for a get backup compatibility descriptor extended operation, and for an identify backup compatibility problems extended operation. These operations may be used to help determine whether a backup taken from one server instance can be successfully restored into another server instance.

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.

  • Add support for an extended operation and a SASL mechanism that can be used to support multifactor authentication using a one-time password delivered to the end user through some out-of-band mechanism (e.g., e-mail, SMS messages, etc.). A command-line tool has also been provided that can be used to easily test the ability to deliver one-time passwords to users, and the LDAP command-line tool API has been updated to provide support for this new SASL mechanism.

  • Update the summarize-access-log tool to provide additional information, including a breakdown of selected client connection policies and their relative percentages, a breakdown of disconnect reasons and their relative percentages, and information about the number and relative percentage of operations that resulted in access to uncached data.

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.

  • Add support for a new multi-update extended operation that can be used to request multiple updates in a single request. The updates may optionally be processed as a single atomic unit so that any failure encountered while processing any of the operations will prevent any of the changes from being applied.

  • Add support for a new UNBOUNDID-CERTIFICATE-PLUS-PASSWORD SASL mechanism handler that can be used to perform multifactor authentication using both a client certificate and a password.

  • Add support for a new set of controls that can be used with a bind operation to request information about a number of user resource limits, including the user's size limit, time limit, idle time limit, lookthrough limit, group membership, assigned privileges, default entry balancing authorization DN, and the name of the client connection policy that would have been assigned to the user.

  • Add support for extended operations that can be used to get and set information about restricted subtree accessibility in the server. This makes it possible to indicate that a specified subtree should be hidden or read-only except for access by a specified user. A command-line tool has been provided that can be used to get and set the accessibility of a specified subtree in the server.

  • Add support for a control that can be used to indicate that updates for certain operational attributes (e.g., last access time, last login time, last login IP address, and lastmod attributes) should be suppressed for the associated operation.

  • Add support for a set of controls that can be used in conjunction with assured replication, in order to request the desired assurance level and receive feedback about the level of assurance that was attained.

  • Add support for a control that can be used in conjunction with a delete or modify DN operation to indicate that no referential integrity processing should be performed for the associated operation.

  • Add support for a task that can be used to cause the server to re-encode entries within a specified branch. This can help transition existing data to use encryption, compression, uncached content, or other altered encodings without the need to export data to LDIF and re-import.

  • Add a class and command-line tool that can be used to help move a single entry or a tree of entries from one server to another. The move can be accomplished using either interactive transactions or via restricted subtree accessibility.

  • Update support for the get changelog batch extended request to make it possible to indicate whether to return modifications to and/or deletes of soft-deleted entries.

  • Update the MonitorManager class so that methods for retrieving monitor entries now allow LDAPInterface objects as an alternative to LDAPConnection.

  • Update the SASLUtils class so that if the Commercial Edition classes are available, then any Commercial Edition SASL mechanisms will be supported.

  • Update the log parsing API to add support for the new security negotiation, entry rebalancing, and assured replication access log message types, and for the uncachedDataAccessed element.

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.

  • Add support for HMAC-based one-time passwords (HOTP, as described in RFC 4226) and time-based one-time passwords (TOTP, as described in RFC 6238). Also, add support for a new UNBOUNDID-TOTP SASL mechanism, which can be used to perform multifactor authentication (combining a TOTP code with a username and password) to UnboundID Directory Server instances which support this mechanism, and a validate TOTP password extended request that can be used to validate a TOTP password without performing a bind on the connection.

  • Add a number of changes in support for soft delete and undelete functionality in the UnboundID Directory Server. This includes a soft delete request control (to request a soft delete operation) and a corresponding response control, a hard delete request control (to request an entry be completely removed), an undelete request control (to request that a soft-deleted entry be restored), and a soft-deleted entry access request control (to request that search results include soft-deleted entries). It also includes updates to access log parsing, changelog entry parsing, and monitor entry parsing to expose information about soft delete and undelete processing, and a new SoftDeletedEntry object that can obtain information about a soft-deleted entry stored in the server.

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.

  • Add support for new start and end administrative session extended operations.

  • Update changelog entry support to reflect a number of changes, including information about suppressed attributes and virtual attributes.

  • Update support for the get changelog batch extended operation to make it possible to indicate that the set of changelog entries to retrieve should be filtered based on target attributes, and to indicate whether changelog entries should be pared based on access control and sensitive attribute constraints (optionally using the identity of another target user).

  • Add support for the new audit data security task, which can be used to examine all entries in a specified set of backends for potential security-related issues.

  • Update the support for the enter and leave lockdown mode tasks to make it possible to specify a reason that the server is being placed in or taken out of lockdown mode.

  • Update monitor entry support for the new FIFO entry cache and per-application processing time histogram monitor entries.

  • Update monitor entry support for the general monitor entry to add support for the new thirdPartyExtensionDN attribute.

  • Update monitor entry support for the UnboundID work queue to add support for new attributes regarding the use of a separate thread pool for administrative operations.

  • Update monitor entry support for the replication server monitor entry to add support for the new ssl-encryption-available attribute.

  • Update the summarize-access-log tool to add support for working with gzip-compressed access log files.

  • Update access log parsing support to add support for a number of new log fields, including the use of an administrative session worker thread, add and modify attribute names, search entry attributes returned, and search request size limit, time limit, typesOnly, and dereference policy values.

  • Improve documentation for UnboundID-proprietary controls and extended operations, and provide examples for elements that were missing them.

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.

  • Updated the access log parsing code to add support for the new intermediateResponsesReturned element that can appear in result messages for operations in which one or more intermediate responses were returned.

  • Updated the LDIF import task to provide support for the new strip trailing spaces option.

  • Added support for the new operation purpose request control, which may be included in any kind of LDAP request to identify the reason for that operation. The log parsing framework has also been updated to provide a mechanism for accessing operation purpose information in server access log messages.

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.

  • Added a new UnboundIDChangeLogEntry class which provides access to a number of attributes which are specific to changelog entries included in the UnboundID Directory Server, including the full set of previous and resulting values for attributes altered by the associated operation, as well as the values of other specified key attributes from the target entry.

  • Updated the access log parsing code to add support for the serversAccessed and replicationChangeID elements which may appear in result log messages.

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.

  • Added support for a new task which may be used to cause the server to reload the set of defined encryption settings definitions.

  • Updated the support for parsing UnboundID server log files to handle timestamps with millisecond accuracy, and to add support the new intermediate response access log message type.

  • Updated the summarize-access-log example tool so that it can differentiate between unindexed searches that were completed successfully and those that were rejected by the server.

  • Updated the LDAP SDK monitor parsing capabilities to support the new index monitor entry type. Also, update the version monitor entry type to provide methods for accessing version information for several libraries used by the server, and to update the replication summary monitor entry to support the new term "replication backlog" rather than the old and potentially confusing term "missing changes".

  • Added support for an exclude branch request control, which can be used to request that entries at or below one or more base DNs be excluded from search results.

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.

  • Updated the LDAP join control support to include the ability to use the reverse DN join type which has recently been added to the UnboundID Directory Server.

  • Added support for Java-based and Groovy-scripted third-party tasks that will be supported in an upcoming version of the UnboundID Directory Server.

  • Added support for get a server ID request control, get server ID response control, and route to server request control, which may be used in an upcoming version of the UnboundID Directory Server and/or Directory Proxy Server to retrieve information about which server was used to process a request, and to request that an operation be processed by a specific server.

  • Added support for a get changelog batch extended operation which will be supported in an upcoming version of the UnboundID Directory Server in order to retrieve a set of changes processed within the server.

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.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.

  • Added support for a new dump DB details task which can be used to cause the UnboundID Directory Server to write a summary of the contents of the databases in a JE backend.

  • Added support for a new administrative alert task which can be used to cause the UnboundID Directory Server to generate an arbitrary administrative alert and/or to alter the set of degraded and unavailable alert types.

  • Improved support for replication server monitor entries to provide the ability to parse additional replication server content, including the last known status for the server, the last successful connect time, the last failed attempt time, and the number of failed connection attempts.

  • Updated the support for the UnboundID work queue monitor entry to include access to the recent-average-queue-size and current-worker-thread-percent-busy attributes.

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.

  • Added a new example tool that uses the stream directory values extended operation to dump a list of the DNs of all entries located at or below a specified base DN.

  • Updated the system info monitor entry to add support for the new userName, jvmPID, systemProperty, and environmentVariable attributes.

  • Updated the join request control to support the new "contains" join rule, which makes it possible to have a generated filter using a subAny substring filter rather than an equality filter.

  • Updated the access log parsing code to add support for parsing forward information contained in result messages, and for parsing client certificate log messages.

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.

  • Added support for a new extended schema info request control, which can be included in a search request targeting the schema subentry to cause it to return extended information (including elements like X-SCHEMA-FILE and X-READ-ONLY) in the schema elements that are returned.

  • Updated the UnboundID work queue monitor entry to include support for the new num-busy-worker-threads, average-operation-queue-time-millis, and recent-operation-queue-time-millis attributes.

  • Updated the access log parsing code to provide the ability to access the new qtime element if it is present.

  • Added support for the search task, which can be used to perform an internal search in the UnboundID Directory Server and write the results to an LDIF file on the server filesystem.

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.

  • Updated the access log parsing classes to add support for the FORWARD-FAILED messages which may be logged by the UnboundID Directory Proxy Server.

  • Added support for the administrative operation request control that may be included in client requests sent to the UnboundID Directory Server to indicate that the associated operation is administrative in nature rather than part of a normal client request.

  • Updated the monitor entry parsing code to provide support for the num-operations-in-progress and num-persistent-searches-in-progress attributes exposed in the active operations monitor entry.

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 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 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 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.

  • Added an example tool that may be used to analyze and summarize the contents of one or more UnboundID Directory Server access logs. A number of useful items are included, including information about the number, rate, and duration of operations processed, the most common result codes returned, and the most common types of filters used.

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.

  • Added support for the unsolicited cancel response control, which may be included in responses the that UnboundID Directory Server sends for requests that are canceled by the server for some reason other than being canceled by the client (e.g., if the server is shutting down or the client connection is being terminated and all outstanding operations for the client are being canceled).

  • Added support for the stream values extended request and intermediate response. This request may be used to retrieve information about entry DNs or attribute values for a specified set of entries in the server.

  • Added the ability to parse alert entries as included in the administrative alert backend of the UnboundID Directory Server.

  • Updated the general monitor entry to add support for the degraded-alert-type, unavailable-alert-type, instanceName, and startupID attributes.

  • Updated the active operations monitor entry to add support for the list of active persistent searches.

  • Updated the processing time histogram monitor entry to add support for the total count and average response time attributes.

  • Added support for the LDAP external server, replica, replication server, and replication summary monitor entry types.

  • Updated the monitor entry API so that information from any types of Directory Server monitor entries which are not explicitly supported by the LDAP SDK may still be accessed using the generic API.

  • Added a new API which may be used for parsing access and error log messages as generated by the UnboundID Directory Server.

  • Added support for the replication repair request control, which may be used to process an add, delete, modify, or modify DN operation which will not be replicated to any other server. This control is primarily intended for use in manually repairing replication conflicts.

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.