In addition to the controls documented on the Using Standard Controls page of the Getting Started Guide, the UnboundID LDAP SDK for Java provides support for a number of other controls that are either less standardized or are specific to a particular server or set of servers. These controls are only tested and assured to work with the Ping Identity, UnboundID, and Nokia/Alcatel-Lucent Directory Server and are not recommended for use in conjunction with any other type of server.
The account usable request control may be included in a search request to indicate that matching search result entries should include the corresponding response control. The response control will indicate whether the user account associated with the search result entry is usable (i.e., whether attempts to authenticate as that user with valid credentials should succeed). If the account is usable, then the control may also include the length of time until the user's password expires. If the account is not usable, then the response control may include information about why it is not usable including:
The following example performs a search to retrieve a user entry and determine whether it is usable.
SearchRequest searchRequest =
new SearchRequest("dc=example,dc=com", SearchScope.SUB, "(uid=john.doe)");
searchRequest.addControl(new AccountUsableRequestControl());
SearchResult searchResult = connection.search(searchRequest);
boolean isUsable = false;
for (SearchResultEntry entry : searchResult.getSearchEntries())
{
for (Control c : entry.getControls())
{
if (c instanceof AccountUsableResponseControl)
{
AccountUsableResponseControl usableResponse =
(AccountUsableResponseControl) c;
isUsable = usableResponse.isUsable();
if (isUsable)
{
System.out.println("The account is usable.");
}
else
{
System.err.println("The account is not usable.");
List<String> unusableReasons =
usableResponse.getUnusableReasons();
if (! unusableReasons.isEmpty())
{
System.err.println("Unusable reasons:");
for (String s : unusableReasons)
{
System.err.println(" " + s);
}
}
}
}
}
}
The administrative operation request control may be used to indicate that the associated operation is used for performing some administrative action in the server and is not associated with a "normal" client. The server can use this information to treat the operation differently in some way (e.g., exclude it from the processing time histogram, or to include additional information about the operation in the server access log).
The assured replication request control can be used to request that the server delay the response to the associated operation until it has confirmed that it has met a minimum set of replication requirements. This can be used for both durability (ensuring that the change is on at least one other server, or in at least one other data center) and for avoiding differences due to propagation delay (ensuring that the change will be visible on all servers in the local data center and/or across all data centers). The corresponding response control provides information about whether the requested level of assurance was satisfied.
The batched transaction specification control is based on the definition in draft-zeilenga-ldap-txn and may be used to indicate that the associated add, delete, modify, or modify DN operation is part of a batched transaction. The start batched transaction extended request should first be used in order to obtain the transaction ID, and then that transaction ID should be included in the batched transaction specification request control for all operations that are part of the transaction. Once all operations which are to be part of the transaction have been requested, then the end batched transaction extended operation should be used to commit the operation. See the Extended Operations page for more information about the start and end batched transaction operations and for an example illustrating their use.
The exclude branch request control can be included in a search request to indicate that the search should not be processed in one or more branches of the DIT.
The extended schema info request control can be used to request that the server return extended information when retrieving the subschema subentry. This extended information includes content like the name of the schema file in which the element is defined, and whether that schema element is considered read-only.
The get authorization entry request control may be included in a bind request to ask the server to return the entries for the authentication and/or authorization identities resulting from the bind. This is similar to the standard authorization identity request control, but retrieves the actual content of the authentication and authorization entries, and not just an authorization ID string.
The get backend set ID request control may be included in a request expected to pass through an entry-balanced Directory Proxy Server to indicate which backend sets were used in the course of processing the operation. This may be used in conjunction with the route to backend set request control to allow for more efficient routing of subsequent requests targeting the same entries.
The get effective rights request control may be included in a search request to determine what rights a given user has when interacting with entries matching the search criteria.
The following example illustrates the process of including the get effective rights request control in a search request to determine whether user "uid=admin,dc=example,dc=com" has the ability to change the password for the user with uid "john.doe":
SearchRequest searchRequest =
new SearchRequest("dc=example,dc=com", SearchScope.SUB, "(uid=john.doe)",
"userPassword", "aclRights");
searchRequest.addControl(new GetEffectiveRightsRequestControl(
"dn:uid=admin,dc=example,dc=com"));
SearchResult searchResult = connection.search(searchRequest);
for (SearchResultEntry entry : searchResult.getSearchEntries())
{
EffectiveRightsEntry effectiveRightsEntry =
new EffectiveRightsEntry(entry);
if (effectiveRightsEntry.rightsInformationAvailable())
{
if (effectiveRightsEntry.hasAttributeRight(AttributeRight.WRITE,
"userPassword"))
{
System.out.println("The admin user has permission to change the " +
"target user's password.");
}
else
{
System.out.println("The admin user does not have permission to " +
"change the target user's password.");
}
}
else
{
System.err.println("No effective rights information was returned.");
}
}
The get server ID request control may be included in a request expected to pass through a Directory Proxy Server to indicate which backend server(s) were used to process the operation. This may be used in conjunction with the route to server request control to allow subsequent requests to be processed in the same backend server.
The get user resource limits request control can be included in a bind request to request that the server return information about a number of resource limits and other properties for the authenticated user, including the search size/time/lookthrough limits, the idle time limit, the set of privileges assigned to the user, etc.
The hard delete request control may be included in a delete request to indicate that the server should permanently remove the entry, even if it would have normally performed a soft delete operation.
The ignore NO-USER-MODIFICATION request control may be included in an add request to indicate that the entry to be added may include operational attributes which are defined with the NO-USER-MODIFICATION flag in the server schema. Such attributes are generally not allowed to be altered by external clients, but in some cases it may be useful to do so (e.g., if you wish to move an entry from one server to another, or if you want to add an entry that had previously existed).
The following example illustrates the process of including the get effective rights request control in a search request to determine whether user "uid=admin,dc=example,dc=com" has the ability to change the password for the user with uid "john.doe":
AddRequest addRequest = new AddRequest("dc=example,dc=com",
new Attribute("objectClass", "top", "domain"),
new Attribute("dc", "example"),
new Attribute("creatorsName", "cn=Admin User DN"),
new Attribute("createTimestamp", "20080101000000Z"));
addRequest.addControl(new IgnoreNoUserModificationRequestControl());
try
{
LDAPResult result = connection.add(addRequest);
System.out.println("The entry was added successfully.");
}
catch (LDAPException le)
{
System.err.println("The attempt to add the entry failed.");
}
The interactive transaction specification control may be used to indicate that the associated operation is part of an interactive transaction. The start interactive transaction extended request should first be used in order to obtain the transaction ID, and then that transaction ID should be included in the interactive transaction specification request control for all operations that are part of the transaction. Once all operations which are to be part of the transaction have been requested, then the end interactive transaction extended operation should be used to commit the operation. See the Extended Operations page for more information about the start and end interactive transaction operations and for an example illustrating their use.
The intermediate client request control may be used to pass information about a client (and any clients which are downstream of it) on to a server, and the corresponding response control may be used to pass information about the server back to the client. This can be very useful for tracking requests and responses through a directory environment (e.g., from a directory-enabled application, through a directory proxy server, to the directory server, and back). Information that may be included in the request control includes:
Information that may be included in the response control includes:
The following example illustrates the process of including an intermediate client request control in a search request to indicate that the request is coming from a client application named "my client" with a session identifier of "session123" and a request identifier of "request456":
SearchRequest searchRequest =
new SearchRequest("dc=example,dc=com", SearchScope.SUB, "(uid=john.doe)");
searchRequest.addControl(new IntermediateClientRequestControl(null, null,
null, null, "my client", "session123", "request456"));
SearchResult searchResult = connection.search(searchRequest);
for (Control c : searchResult.getResponseControls())
{
if (c instanceof IntermediateClientResponseControl)
{
IntermediateClientResponseControl intermediateClientResponse =
(IntermediateClientResponseControl) c;
System.out.println("Intermediate client response: " +
intermediateClientResponse.getResponseValue().toString());
}
}
The LDAP join request control may be included in a search request to indicate that the server should also include information about entries that are related to the matching search result entries in some way. The relation is specified using a join rule, and may include criteria like retrieving entries whose DNs are included in attribute values in the search result entry, retrieving entries that contain a specified attribute value from the search result entry, or retrieving entries that contain an attribute value that matches the DN of the search result entry.
The matching entry count request control may be included in a search request to ask that the server return information about the number of entries that match the search criteria rather than actually returning the matching entries. The request control has options that can make it possible to make trade-offs between speed and accuracy (e.g., whether to get an exact count, or whether it is acceptable to simply return an upper bound), and the corresponding response control includes information about how accurate the returned count is.
The LDAP no-op request control is defined in draft-zeilenga-ldap-noop, although because it has not yet been standardized no official OID has been allocated for this control and therefore it uses a temporary OID which is used by OpenLDAP, OpenDS, and the Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 Directory Server. This control may be included in an add, delete, modify, or modify DN request to indicate that the server should perform as much processing as possible for the associated operation but should not actually make any changes to server data. It may be used to verify whether the operation would likely be successful, and may include things like ensuring that the all of the necessary preconditions are met, that the requester has appropriate rights to perform the operation, and that the change would not violate the server schema.
Note that operations including the LDAP no-op request control should never return a result of "SUCCESS", but if all processing up to the point at which the server would have applied the change to the data was successful, then it will return a "NO_OPERATION" result. Otherwise, the server will return a response with the appropriate result code for the error that occurred. The UnboundID LDAP SDK for Java will not throw an exception if the response includes the NO_OPERATION result code, but that result code will be included in the LDAPResult object that is returned.
The following example demonstrates the use of the LDAP no-op request control to verify that a delete operation would likely succeed:
ModifyRequest modifyRequest = new ModifyRequest("dc=example,dc=com",
new Modification(ModificationType.REPLACE, "description", "new value"));
modifyRequest.addControl(new NoOpRequestControl());
try
{
LDAPResult result = connection.modify(modifyRequest);
if (result.getResultCode() == ResultCode.NO_OPERATION)
{
System.out.println("The modify would likely have succeeded.");
}
else
{
System.err.println("The modify would have failed.");
}
}
catch (LDAPException le)
{
System.err.println("The modify would have failed.");
}
The operation purpose request control may be included in a request to provide additional information about the purpose of the associated operation, including elements like the name, version number, and code location for the application that issued the request, and a description of the purpose of that operation. This is primarily used to provide additional access log information for that operation.
The password policy request and response controls are based on the definition in the draft-behera-ldap-password-policy Internet Draft. The request control does not include any content, but the corresponding response control may include either, both, or neither of a warning element and an error element with information about the state of the associated user's account. It is similar to (but somewhat more limited than) the account usable control.
The following example will include the password policy request control in a bind request and retrieve the response control from the bind result:
SimpleBindRequest bindRequest = new SimpleBindRequest(
"uid=john.doe,ou=People,dc=example,dc=com", "password",
new PasswordPolicyRequestControl());
Control[] responseControls;
try
{
BindResult bindResult = connection.bind(bindRequest);
// If we've gotten here, then the bind was successful but there may still
// be a password policy warning included.
responseControls = bindResult.getResponseControls();
}
catch (LDAPException le)
{
// The bind failed. There may be a password policy response control to
// help tell us why.
responseControls = le.getResponseControls();
}
for (Control c : responseControls)
{
if (c instanceof PasswordPolicyResponseControl)
{
PasswordPolicyResponseControl pwpResponse =
(PasswordPolicyResponseControl) c;
PasswordPolicyErrorType errorType = pwpResponse.getErrorType();
if (errorType != null)
{
System.err.println("Password policy error: " + errorType.getName());
}
PasswordPolicyWarningType warningType =
pwpResponse.getWarningType();
if (warningType != null)
{
int value = pwpResponse.getWarningValue();
switch (warningType)
{
case TIME_BEFORE_EXPIRATION:
System.err.println("Your password will expire in " + value +
" seconds.");
break;
case GRACE_LOGINS_REMAINING:
System.err.println("You have " + value +
" grace logins remaining.");
}
}
}
}
The password validation details request control may be included in an add, modify, or password modify request that attempts to set or update a user password. The corresponding response control provides information about the result of password validation processing performed for that operation. In the event that the provided password was rejected, this can provide more detailed information about which constraints were violated so that the application can present a more useful error response to the end user.
The purge password request control may be included in a modify or password modify operation used to change a user password to indicate that the user's former password should be purged from the entry, even if the server configuration would normally have caused that password to be retired. See the description of the retire password request control for a brief description of password retirement.
The real attributes only request control may be included in a search request to indicate that the server should only include the "real" attribute values in resulting entries and should not include the values of virtual attributes. There is no corresponding response control.
The following example illustrates the use of the real attributes only request control:
SearchRequest searchRequest =
new SearchRequest("dc=example,dc=com", SearchScope.SUB, "(uid=john.doe)");
searchRequest.addControl(new RealAttributesOnlyRequestControl());
SearchResult searchResult = connection.search(searchRequest);
The replication repair request control may be included in an update request to indicate that the associated change should be processed only on the server that receives the request and should not be replicated to any other server in the environment. This may be used to take corrective action for any replication conflicts that have been detected but could not be automatically resolved.
The retain identity request control may be included in a bind request to indicate that the server should process the bind operation, but that it should not actually change the identity associated with the client connection. This can be used to make it easier to process bind operations using connections that are part of a connection pool. Rather than requiring a separate pool for bind operations or re-binding after each bind to restore the original identity, the retain identity control may be used to process the bind without destroying the authentication state of the pooled connection.
The following example illustrates the use of the retain identity request control:
SimpleBindRequest bindRequest = new SimpleBindRequest(
"uid=john.doe,ou=People,dc=example,dc=com", "password",
new RetainIdentityRequestControl());
try
{
BindResult bindResult = connection.bind(bindRequest);
// The bind was successful and the account is usable, but the identity
// associated with the client connection hasn't changed.
}
catch (LDAPException le)
{
// The bind was unsuccessful, potentially because the credentials were
// invalid or the account is unusable for some reason (e.g., disabled,
// locked, expired password, etc.). The identity associated with the
// client connection hasn't changed.
}
The retire password request control may be included in a modify or password modify operation used to change a user password to indicate that the user's former password should temporarily be retained and remain usable in the entry for a period of time. This can be useful in cases where it may be necessary to coordinate a password change across multiple applications or multiple instances of the same application.
The return conflict entries request control may be included in a search request to indicate that the server should include any replication conflict entries (that are normally excluded from search results) that match the search criteria.
The route to backend set request control may be included in a request expected to pass through an entry-balanced Directory Proxy Server to provide information about which backend set(s) should be used in the course of processing the operation. This control may specify either an absolute routing request, to indicate that only the specified backend set(s) should be used, or a routing hint that may help provide better performance in cases where the Directory Proxy Server might otherwise have had to perform a broadcast across all backend sets to determine where to process the operation.
The route to server request control may be included in a request expected to pass through a Directory Proxy Server to indicate which backend server should be used to process the operation. This may be used to ensure that separate operations are processed by the same backend server to avoid the potential for problems that could arise as a result of replication propagation delay.
The soft delete request control may be included in a delete request to indicate that the target entry should not be immediately purged from the database but should instead be temporarily hidden. A soft-deleted entry is normally not visible to clients, but it may be searchable using the soft-deleted entry access request control, and it may be restored using the undelete request control.
The soft-deleted entry access request control may be included in a search request to indicate that the server should any return soft-deleted entries (which are normally excluded from search results) that match the search criteria.
The suppress operational attribute update request control can be included in a request to indicate that the server should not alter one or more operational attributes that might otherwise be updated by the operation, including the last access time, last login time, last login IP address, creators name, create timestamp, modifiers name, and modify timestamp.
The transaction settings request control may be included in a request in order to provide information used to tune the database transaction processing for the associated operation, including the commit durability, number of retry attempts, the transaction lock timeout, and whether to attempt to acquire an exclusive lock within the backend to ensure that no other operations may be in progress in the backend while the operation is being processed.
The undelete request control may be included in an add request to indicate that the add is an attempt to restore a soft-deleted entry to its original state (optionally with a different DN than had originally been used for the entry).
The virtual attributes only request control may be included in a search request to indicate that the server should only include virtual attribute values in resulting entries and should not include the values of "real" attributes. There is no corresponding response control.
The following example illustrates the use of the virtual attributes only request control:
SearchRequest searchRequest =
new SearchRequest("dc=example,dc=com", SearchScope.SUB, "(uid=john.doe)");
searchRequest.addControl(new VirtualAttributesOnlyRequestControl());
SearchResult searchResult = connection.search(searchRequest);