com.unboundid.ldap.sdk.migrate.ldapjdk.LDAPConnection Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of unboundid-ldapsdk Show documentation
Show all versions of unboundid-ldapsdk Show documentation
The UnboundID LDAP SDK for Java is a fast, comprehensive, and easy-to-use
Java API for communicating with LDAP directory servers and performing
related tasks like reading and writing LDIF, encoding and decoding data
using base64 and ASN.1 BER, and performing secure communication. This
package contains the Standard Edition of the LDAP SDK, which is a
complete, general-purpose library for communicating with LDAPv3 directory
servers.
The newest version!
/*
* Copyright 2009-2024 Ping Identity Corporation
* All Rights Reserved.
*/
/*
* Copyright 2009-2024 Ping Identity Corporation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* Copyright (C) 2009-2024 Ping Identity Corporation
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License (GPLv2 only)
* or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see .
*/
package com.unboundid.ldap.sdk.migrate.ldapjdk;
import com.unboundid.asn1.ASN1OctetString;
import com.unboundid.ldap.sdk.AddRequest;
import com.unboundid.ldap.sdk.AsyncRequestID;
import com.unboundid.ldap.sdk.BindResult;
import com.unboundid.ldap.sdk.CompareRequest;
import com.unboundid.ldap.sdk.CompareResult;
import com.unboundid.ldap.sdk.Control;
import com.unboundid.ldap.sdk.DeleteRequest;
import com.unboundid.ldap.sdk.DereferencePolicy;
import com.unboundid.ldap.sdk.ExtendedRequest;
import com.unboundid.ldap.sdk.ExtendedResult;
import com.unboundid.ldap.sdk.Filter;
import com.unboundid.ldap.sdk.InternalSDKHelper;
import com.unboundid.ldap.sdk.LDAPConnectionOptions;
import com.unboundid.ldap.sdk.LDAPResult;
import com.unboundid.ldap.sdk.Modification;
import com.unboundid.ldap.sdk.ModifyDNRequest;
import com.unboundid.ldap.sdk.ModifyRequest;
import com.unboundid.ldap.sdk.ResultCode;
import com.unboundid.ldap.sdk.SearchRequest;
import com.unboundid.ldap.sdk.SearchResult;
import com.unboundid.ldap.sdk.SearchScope;
import com.unboundid.ldap.sdk.SimpleBindRequest;
import com.unboundid.ldap.sdk.UpdatableLDAPRequest;
import com.unboundid.util.Debug;
import com.unboundid.util.Mutable;
import com.unboundid.util.NotExtensible;
import com.unboundid.util.NotNull;
import com.unboundid.util.Nullable;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
/**
* This class provides an object that may be used to communicate with an LDAP
* directory server.
*
* This class is primarily intended to be used in the process of updating
* applications which use the Netscape Directory SDK for Java to switch to or
* coexist with the UnboundID LDAP SDK for Java. For applications not written
* using the Netscape Directory SDK for Java, the
* {@link com.unboundid.ldap.sdk.LDAPConnection} class should be used instead.
*/
@Mutable()
@NotExtensible()
@ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE)
public class LDAPConnection
{
/**
* The integer value for the DEREF_NEVER dereference policy.
*/
public static final int DEREF_NEVER = DereferencePolicy.NEVER.intValue();
/**
* The integer value for the DEREF_SEARCHING dereference policy.
*/
public static final int DEREF_SEARCHING =
DereferencePolicy.SEARCHING.intValue();
/**
* The integer value for the DEREF_FINDING dereference policy.
*/
public static final int DEREF_FINDING =
DereferencePolicy.FINDING.intValue();
/**
* The integer value for the DEREF_ALWAYS dereference policy.
*/
public static final int DEREF_ALWAYS =
DereferencePolicy.ALWAYS.intValue();
/**
* The integer value for the SCOPE_BASE search scope.
*/
public static final int SCOPE_BASE = SearchScope.BASE_INT_VALUE;
/**
* The integer value for the SCOPE_ONE search scope.
*/
public static final int SCOPE_ONE = SearchScope.ONE_INT_VALUE;
/**
* The integer value for the SCOPE_SUB search scope.
*/
public static final int SCOPE_SUB = SearchScope.SUB_INT_VALUE;
// The connection used to perform the actual communication with the server.
@NotNull private volatile com.unboundid.ldap.sdk.LDAPConnection conn;
// The default constraints that will be used for non-search operations.
@NotNull private LDAPConstraints constraints;
// The set of controls returned from the last operation.
@Nullable private LDAPControl[] responseControls;
// The default constraints that will be used for search operations.
@NotNull private LDAPSearchConstraints searchConstraints;
// The socket factory for this connection.
@Nullable private LDAPSocketFactory socketFactory;
// The DN last used to bind to the server.
@Nullable private String authDN;
// The password last used to bind to the server.
@Nullable private String authPW;
/**
* Creates a new LDAP connection which will use the default socket factory.
*/
public LDAPConnection()
{
this(null);
}
/**
* Creates a new LDAP connection which will use the provided socket factory.
*
* @param socketFactory The socket factory to use when creating the socket
* to use for communicating with the server.
*/
public LDAPConnection(@Nullable final LDAPSocketFactory socketFactory)
{
this.socketFactory = socketFactory;
if (socketFactory == null)
{
conn = new com.unboundid.ldap.sdk.LDAPConnection();
}
else
{
conn = new com.unboundid.ldap.sdk.LDAPConnection(
new LDAPToJavaSocketFactory(socketFactory));
}
authDN = null;
authPW = null;
constraints = new LDAPConstraints();
searchConstraints = new LDAPSearchConstraints();
}
/**
* Closes the connection to the server if the client forgets to do so.
*
* @throws Throwable If a problem occurs.
*/
@Override()
protected void finalize()
throws Throwable
{
conn.close();
super.finalize();
}
/**
* Retrieves the {@link com.unboundid.ldap.sdk.LDAPConnection} object used to
* back this connection.
*
* @return The {@code com.unboundid.ldap.sdk.LDAPConnection} object used to
* back this connection.
*/
@NotNull()
public com.unboundid.ldap.sdk.LDAPConnection getSDKConnection()
{
return conn;
}
/**
* Retrieves the address to which the connection is established.
*
* @return The address to which the connection is established.
*/
@Nullable()
public String getHost()
{
return conn.getConnectedAddress();
}
/**
* Retrieves the port to which the connection is established.
*
* @return The port to which the connection is established.
*/
public int getPort()
{
return conn.getConnectedPort();
}
/**
* Retrieves the DN of the user that last authenticated on this connection.
*
* @return The DN of the user that last authenticated on this connection,
* or {@code null} if it is not available.
*/
@Nullable()
public String getAuthenticationDN()
{
return authDN;
}
/**
* Retrieves the password of the user that last authenticated on this
* connection.
*
* @return The password of the user that last authenticated on this
* connection, or {@code null} if it is not available.
*/
@Nullable()
public String getAuthenticationPassword()
{
return authPW;
}
/**
* Retrieves the maximum length of time to wait for the connection to be
* established, in seconds.
*
* @return The maximum length of time to wait for the connection to be
* established.
*/
public int getConnectTimeout()
{
final int connectTimeoutMillis =
conn.getConnectionOptions().getConnectTimeoutMillis();
if (connectTimeoutMillis > 0)
{
return Math.max(1, (connectTimeoutMillis / 1000));
}
else
{
return 0;
}
}
/**
* Specifies the maximum length of time to wait for the connection to be
* established, in seconds.
*
* @param timeout The maximum length of time to wait for the connection to
* be established.
*/
public void setConnectTimeout(final int timeout)
{
final LDAPConnectionOptions options = conn.getConnectionOptions();
if (timeout > 0)
{
options.setConnectTimeoutMillis(1000 * timeout);
}
else
{
options.setConnectTimeoutMillis(0);
}
conn.setConnectionOptions(options);
}
/**
* Retrieves the socket factory for this LDAP connection, if specified.
*
* @return The socket factory for this LDAP connection, or {@code null} if
* none has been provided.
*/
@Nullable()
public LDAPSocketFactory getSocketFactory()
{
return socketFactory;
}
/**
* Sets the socket factory for this LDAP connection.
*
* @param socketFactory The socket factory for this LDAP connection.
*/
public void setSocketFactory(@Nullable final LDAPSocketFactory socketFactory)
{
this.socketFactory = socketFactory;
if (socketFactory == null)
{
conn.setSocketFactory(null);
}
else
{
conn.setSocketFactory(new LDAPToJavaSocketFactory(socketFactory));
}
}
/**
* Retrieves the constraints for this connection.
*
* @return The constraints for this connection.
*/
@NotNull()
public LDAPConstraints getConstraints()
{
return constraints;
}
/**
* Updates the constraints for this connection.
*
* @param constraints The constraints for this connection.
*/
public void setConstraints(@Nullable final LDAPConstraints constraints)
{
if (constraints == null)
{
this.constraints = new LDAPConstraints();
}
else
{
this.constraints = constraints;
}
}
/**
* Retrieves the search constraints for this connection.
*
* @return The search constraints for this connection.
*/
@NotNull()
public LDAPSearchConstraints getSearchConstraints()
{
return searchConstraints;
}
/**
* Updates the search constraints for this connection.
*
* @param searchConstraints The search constraints for this connection.
*/
public void setSearchConstraints(
@Nullable final LDAPSearchConstraints searchConstraints)
{
if (searchConstraints == null)
{
this.searchConstraints = new LDAPSearchConstraints();
}
else
{
this.searchConstraints = searchConstraints;
}
}
/**
* Retrieves the response controls from the last operation processed on this
* connection.
*
* @return The response controls from the last operation processed on this
* connection, or {@code null} if there were none.
*/
@Nullable()
public LDAPControl[] getResponseControls()
{
return responseControls;
}
/**
* Indicates whether this connection is currently established.
*
* @return {@code true} if this connection is currently established, or
* {@code false} if not.
*/
public boolean isConnected()
{
return conn.isConnected();
}
/**
* Attempts to establish this connection with the provided information.
*
* @param host The address of the server to which the connection should be
* established.
* @param port The port of the server to which the connection should be
* established.
*
* @throws LDAPException If a problem occurs while attempting to establish
* this connection.
*/
public void connect(@NotNull final String host, final int port)
throws LDAPException
{
authDN = null;
authPW = null;
responseControls = null;
try
{
conn.close();
if (socketFactory == null)
{
conn = new com.unboundid.ldap.sdk.LDAPConnection(host, port);
}
else
{
conn = new com.unboundid.ldap.sdk.LDAPConnection(
new LDAPToJavaSocketFactory(socketFactory), host, port);
}
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
throw new LDAPException(le);
}
}
/**
* Attempts to establish and authenticate this connection with the provided
* information.
*
* @param host The address of the server to which the connection should
* be established.
* @param port The port of the server to which the connection should be
* established.
* @param dn The DN to use to bind to the server.
* @param password The password to use to bind to the server.
*
* @throws LDAPException If a problem occurs while attempting to establish
* or authenticate this connection. If an exception
* is thrown, then the connection will not be
* established.
*/
public void connect(@NotNull final String host, final int port,
@Nullable final String dn,
@Nullable final String password)
throws LDAPException
{
connect(3, host, port, dn, password, null);
}
/**
* Attempts to establish and authenticate this connection with the provided
* information.
*
* @param host The address of the server to which the connection
* should be established.
* @param port The port of the server to which the connection should
* be established.
* @param dn The DN to use to bind to the server.
* @param password The password to use to bind to the server.
* @param constraints The constraints to use when processing the bind.
*
* @throws LDAPException If a problem occurs while attempting to establish
* or authenticate this connection. If an exception
* is thrown, then the connection will not be
* established.
*/
public void connect(@NotNull final String host, final int port,
@Nullable final String dn,
@Nullable final String password,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
connect(3, host, port, dn, password, constraints);
}
/**
* Attempts to establish and authenticate this connection with the provided
* information.
*
* @param version The LDAP protocol version to use for the connection.
* This will be ignored, since this implementation only
* supports LDAPv3.
* @param host The address of the server to which the connection should
* be established.
* @param port The port of the server to which the connection should be
* established.
* @param dn The DN to use to bind to the server.
* @param password The password to use to bind to the server.
*
* @throws LDAPException If a problem occurs while attempting to establish
* or authenticate this connection. If an exception
* is thrown, then the connection will not be
* established.
*/
public void connect(final int version, @NotNull final String host,
final int port, @Nullable final String dn,
@Nullable final String password)
throws LDAPException
{
connect(version, host, port, dn, password, null);
}
/**
* Attempts to establish and authenticate this connection with the provided
* information.
*
* @param version The LDAP protocol version to use for the connection.
* This will be ignored, since this implementation only
* supports LDAPv3.
* @param host The address of the server to which the connection
* should be established.
* @param port The port of the server to which the connection should
* be established.
* @param dn The DN to use to bind to the server.
* @param password The password to use to bind to the server.
* @param constraints The constraints to use when processing the bind.
*
* @throws LDAPException If a problem occurs while attempting to establish
* or authenticate this connection. If an exception
* is thrown, then the connection will not be
* established.
*/
public void connect(final int version, @NotNull final String host,
final int port, @Nullable final String dn,
@Nullable final String password,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
connect(host, port);
try
{
if ((dn != null) && (password != null))
{
bind(version, dn, password, constraints);
}
}
catch (final LDAPException le)
{
conn.close();
throw le;
}
}
/**
* Unbinds and disconnects from the directory server.
*
* @throws LDAPException If a problem occurs.
*/
public void disconnect()
throws LDAPException
{
authDN = null;
authPW = null;
conn.close();
if (socketFactory == null)
{
conn = new com.unboundid.ldap.sdk.LDAPConnection();
}
else
{
conn = new com.unboundid.ldap.sdk.LDAPConnection(
new LDAPToJavaSocketFactory(socketFactory));
}
}
/**
* Disconnects from the directory server and attempts to re-connect and
* re-authenticate.
*
* @throws LDAPException If a problem occurs. If an exception is thrown,
* the connection will have been closed.
*/
public void reconnect()
throws LDAPException
{
final String host = getHost();
final int port = getPort();
final String dn = authDN;
final String pw = authPW;
if ((dn == null) || (pw == null))
{
connect(host, port);
}
else
{
connect(host, port, dn, pw);
}
}
/**
* Sends a request to abandon the request with the specified message ID.
*
* @param id The message ID of the operation to abandon.
*
* @throws LDAPException If a problem occurs while sending the request.
*/
public void abandon(final int id)
throws LDAPException
{
try
{
conn.abandon(InternalSDKHelper.createAsyncRequestID(id, conn),
getControls(null));
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
throw new LDAPException(le);
}
}
/**
* Sends a request to abandon the provided search operation.
*
* @param searchResults The search results object for the search to abandon.
*
* @throws LDAPException If a problem occurs while sending the request.
*/
public void abandon(@NotNull final LDAPSearchResults searchResults)
throws LDAPException
{
try
{
final AsyncRequestID requestID = searchResults.getAsyncRequestID();
if (requestID != null)
{
searchResults.setAbandoned();
conn.abandon(requestID);
}
else
{
// This should never happen.
throw new LDAPException(
"The search request has not been sent to the server",
LDAPException.PARAM_ERROR);
}
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
throw new LDAPException(le);
}
}
/**
* Adds the provided entry to the directory.
*
* @param entry The entry to be added.
*
* @throws LDAPException If a problem occurs while adding the entry.
*/
public void add(@NotNull final LDAPEntry entry)
throws LDAPException
{
add(entry, null);
}
/**
* Adds the provided entry to the directory.
*
* @param entry The entry to be added.
* @param constraints The constraints to use for the add operation.
*
* @throws LDAPException If a problem occurs while adding the entry.
*/
public void add(@NotNull final LDAPEntry entry,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
final AddRequest addRequest = new AddRequest(entry.toEntry());
update(addRequest, constraints);
try
{
final LDAPResult result = conn.add(addRequest);
setResponseControls(result);
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
setResponseControls(le);
throw new LDAPException(le);
}
}
/**
* Authenticates to the directory server using a simple bind with the provided
* information.
*
* @param dn The DN of the user for the bind.
* @param password The password to use for the bind.
*
* @throws LDAPException If the bind attempt fails.
*/
public void authenticate(@Nullable final String dn,
@Nullable final String password)
throws LDAPException
{
bind(3, dn, password, null);
}
/**
* Authenticates to the directory server using a simple bind with the provided
* information.
*
* @param dn The DN of the user for the bind.
* @param password The password to use for the bind.
* @param constraints The constraints to use for the bind operation.
*
* @throws LDAPException If the bind attempt fails.
*/
public void authenticate(@Nullable final String dn,
@Nullable final String password,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
bind(3, dn, password, constraints);
}
/**
* Authenticates to the directory server using a simple bind with the provided
* information.
*
* @param version The LDAP protocol version to use. This will be ignored,
* since this implementation only supports LDAPv3.
* @param dn The DN of the user for the bind.
* @param password The password to use for the bind.
*
* @throws LDAPException If the bind attempt fails.
*/
public void authenticate(final int version, @Nullable final String dn,
@Nullable final String password)
throws LDAPException
{
bind(version, dn, password, null);
}
/**
* Authenticates to the directory server using a simple bind with the provided
* information.
*
* @param version The LDAP protocol version to use. This will be
* ignored, since this implementation only supports
* LDAPv3.
* @param dn The DN of the user for the bind.
* @param password The password to use for the bind.
* @param constraints The constraints to use for the bind operation.
*
* @throws LDAPException If the bind attempt fails.
*/
public void authenticate(final int version, @Nullable final String dn,
@Nullable final String password,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
bind(version, dn, password, constraints);
}
/**
* Authenticates to the directory server using a simple bind with the provided
* information.
*
* @param dn The DN of the user for the bind.
* @param password The password to use for the bind.
*
* @throws LDAPException If the bind attempt fails.
*/
public void bind(@Nullable final String dn, @Nullable final String password)
throws LDAPException
{
bind(3, dn, password, null);
}
/**
* Authenticates to the directory server using a simple bind with the provided
* information.
*
* @param dn The DN of the user for the bind.
* @param password The password to use for the bind.
* @param constraints The constraints to use for the bind operation.
*
* @throws LDAPException If the bind attempt fails.
*/
public void bind(@Nullable final String dn, @Nullable final String password,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
bind(3, dn, password, constraints);
}
/**
* Authenticates to the directory server using a simple bind with the provided
* information.
*
* @param version The LDAP protocol version to use. This will be ignored,
* since this implementation only supports LDAPv3.
* @param dn The DN of the user for the bind.
* @param password The password to use for the bind.
*
* @throws LDAPException If the bind attempt fails.
*/
public void bind(final int version, @Nullable final String dn,
@Nullable final String password)
throws LDAPException
{
bind(version, dn, password, null);
}
/**
* Authenticates to the directory server using a simple bind with the provided
* information.
*
* @param version The LDAP protocol version to use. This will be
* ignored, since this implementation only supports
* LDAPv3.
* @param dn The DN of the user for the bind.
* @param password The password to use for the bind.
* @param constraints The constraints to use for the bind operation.
*
* @throws LDAPException If the bind attempt fails.
*/
public void bind(final int version, @Nullable final String dn,
@Nullable final String password,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
final SimpleBindRequest bindRequest =
new SimpleBindRequest(dn, password, getControls(constraints));
authDN = null;
authPW = null;
try
{
final BindResult bindResult = conn.bind(bindRequest);
setResponseControls(bindResult);
if (bindResult.getResultCode() == ResultCode.SUCCESS)
{
authDN = dn;
authPW = password;
}
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
setResponseControls(le);
throw new LDAPException(le);
}
}
/**
* Indicates whether the specified entry has the given attribute value.
*
* @param dn The DN of the entry to compare.
* @param attribute The attribute (which must have exactly one value) to use
* for the comparison.
*
* @return {@code true} if the compare matched the target entry, or
* {@code false} if not.
*
* @throws LDAPException If a problem occurs while processing the compare.
*/
public boolean compare(@NotNull final String dn,
@NotNull final LDAPAttribute attribute)
throws LDAPException
{
return compare(dn, attribute, null);
}
/**
* Indicates whether the specified entry has the given attribute value.
*
* @param dn The DN of the entry to compare.
* @param attribute The attribute (which must have exactly one value) to
* use for the comparison.
* @param constraints The constraints to use for the compare operation.
*
* @return {@code true} if the compare matched the target entry, or
* {@code false} if not.
*
* @throws LDAPException If a problem occurs while processing the compare.
*/
public boolean compare(@NotNull final String dn,
@NotNull final LDAPAttribute attribute,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
final CompareRequest compareRequest = new CompareRequest(dn,
attribute.getName(), attribute.getByteValueArray()[0]);
update(compareRequest, constraints);
try
{
final CompareResult result = conn.compare(compareRequest);
setResponseControls(result);
return result.compareMatched();
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
setResponseControls(le);
throw new LDAPException(le);
}
}
/**
* Removes an entry from the directory.
*
* @param dn The DN of the entry to delete.
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void delete(@NotNull final String dn)
throws LDAPException
{
delete(dn, null);
}
/**
* Removes an entry from the directory.
*
* @param dn The DN of the entry to delete.
* @param constraints The constraints to use for the delete operation.
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void delete(@NotNull final String dn,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
final DeleteRequest deleteRequest = new DeleteRequest(dn);
update(deleteRequest, constraints);
try
{
final LDAPResult result = conn.delete(deleteRequest);
setResponseControls(result);
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
setResponseControls(le);
throw new LDAPException(le);
}
}
/**
* Processes an extended operation in the directory.
*
* @param extendedOperation The extended operation to process.
*
* @return The result returned from the extended operation.
*
* @throws LDAPException If a problem occurs while processing the operation.
*/
@NotNull()
public LDAPExtendedOperation extendedOperation(
@NotNull final LDAPExtendedOperation extendedOperation)
throws LDAPException
{
return extendedOperation(extendedOperation, null);
}
/**
* Processes an extended operation in the directory.
*
* @param extendedOperation The extended operation to process.
* @param constraints The constraints to use for the operation.
*
* @return The result returned from the extended operation.
*
* @throws LDAPException If a problem occurs while processing the operation.
*/
@NotNull()
public LDAPExtendedOperation extendedOperation(
@NotNull final LDAPExtendedOperation extendedOperation,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
final ExtendedRequest extendedRequest = new ExtendedRequest(
extendedOperation.getID(),
new ASN1OctetString(extendedOperation.getValue()),
getControls(constraints));
try
{
final ExtendedResult result =
conn.processExtendedOperation(extendedRequest);
setResponseControls(result);
if (result.getResultCode() != ResultCode.SUCCESS)
{
throw new LDAPException(result.getDiagnosticMessage(),
result.getResultCode().intValue(), result.getDiagnosticMessage(),
result.getMatchedDN());
}
final byte[] valueBytes;
final ASN1OctetString value = result.getValue();
if (value == null)
{
valueBytes = null;
}
else
{
valueBytes = value.getValue();
}
return new LDAPExtendedOperation(result.getOID(), valueBytes);
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
setResponseControls(le);
throw new LDAPException(le);
}
}
/**
* Modifies an entry in the directory.
*
* @param dn The DN of the entry to modify.
* @param mod The modification to apply to the entry.
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void modify(@NotNull final String dn,
@NotNull final LDAPModification mod)
throws LDAPException
{
modify(dn, new LDAPModification[] { mod }, null);
}
/**
* Modifies an entry in the directory.
*
* @param dn The DN of the entry to modify.
* @param mods The modifications to apply to the entry.
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void modify(@NotNull final String dn,
@NotNull final LDAPModification[] mods)
throws LDAPException
{
modify(dn, mods, null);
}
/**
* Modifies an entry in the directory.
*
* @param dn The DN of the entry to modify.
* @param mod The modification to apply to the entry.
* @param constraints The constraints to use for the modify operation.
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void modify(@NotNull final String dn,
@NotNull final LDAPModification mod,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
modify(dn, new LDAPModification[] { mod }, constraints);
}
/**
* Modifies an entry in the directory.
*
* @param dn The DN of the entry to modify.
* @param mods The modifications to apply to the entry.
* @param constraints The constraints to use for the modify operation.
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void modify(@NotNull final String dn,
@NotNull final LDAPModification[] mods,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
final Modification[] m = new Modification[mods.length];
for (int i=0; i < mods.length; i++)
{
m[i] = mods[i].toModification();
}
final ModifyRequest modifyRequest = new ModifyRequest(dn, m);
update(modifyRequest, constraints);
try
{
final LDAPResult result = conn.modify(modifyRequest);
setResponseControls(result);
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
setResponseControls(le);
throw new LDAPException(le);
}
}
/**
* Modifies an entry in the directory.
*
* @param dn The DN of the entry to modify.
* @param mods The modifications to apply to the entry.
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void modify(@NotNull final String dn,
@NotNull final LDAPModificationSet mods)
throws LDAPException
{
modify(dn, mods.toArray(), null);
}
/**
* Modifies an entry in the directory.
*
* @param dn The DN of the entry to modify.
* @param mods The modifications to apply to the entry.
* @param constraints The constraints to use for the modify operation.
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void modify(@NotNull final String dn,
@NotNull final LDAPModificationSet mods,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
modify(dn, mods.toArray(), constraints);
}
/**
* Retrieves an entry from the directory server.
*
* @param dn The DN of the entry to retrieve.
*
* @return The entry that was read.
*
* @throws LDAPException If a problem occurs while performing the search.
*/
@NotNull()
public LDAPEntry read(@NotNull final String dn)
throws LDAPException
{
return read(dn, null, null);
}
/**
* Retrieves an entry from the directory server.
*
* @param dn The DN of the entry to retrieve.
* @param constraints The constraints to use for the search operation.
*
* @return The entry that was read.
*
* @throws LDAPException If a problem occurs while performing the search.
*/
@NotNull()
public LDAPEntry read(@NotNull final String dn,
@Nullable final LDAPSearchConstraints constraints)
throws LDAPException
{
return read(dn, null, constraints);
}
/**
* Retrieves an entry from the directory server.
*
* @param dn The DN of the entry to retrieve.
* @param attrs The set of attributes to request.
*
* @return The entry that was read.
*
* @throws LDAPException If a problem occurs while performing the search.
*/
@NotNull()
public LDAPEntry read(@NotNull final String dn,
@Nullable final String[] attrs)
throws LDAPException
{
return read(dn, attrs, null);
}
/**
* Retrieves an entry from the directory server.
*
* @param dn The DN of the entry to retrieve.
* @param attrs The set of attributes to request.
* @param constraints The constraints to use for the search operation.
*
* @return The entry that was read.
*
* @throws LDAPException If a problem occurs while performing the search.
*/
@NotNull()
public LDAPEntry read(@NotNull final String dn,
@Nullable final String[] attrs,
@Nullable final LDAPSearchConstraints constraints)
throws LDAPException
{
final Filter filter = Filter.createORFilter(
Filter.createPresenceFilter("objectClass"),
Filter.createEqualityFilter("objectClass", "ldapSubentry"));
final SearchRequest searchRequest =
new SearchRequest(dn, SearchScope.BASE, filter, attrs);
update(searchRequest, constraints);
try
{
final SearchResult searchResult = conn.search(searchRequest);
setResponseControls(searchResult);
if (searchResult.getEntryCount() != 1)
{
throw new LDAPException(null, LDAPException.NO_RESULTS_RETURNED);
}
return new LDAPEntry(searchResult.getSearchEntries().get(0));
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
setResponseControls(le);
throw new LDAPException(le);
}
}
/**
* Alters the DN of an entry in the directory.
*
* @param dn The DN of the entry to modify.
* @param newRDN The new RDN to use for the entry.
* @param deleteOldRDN Indicates whether to remove the old RDN value(s).
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void rename(@NotNull final String dn, @NotNull final String newRDN,
final boolean deleteOldRDN)
throws LDAPException
{
rename(dn, newRDN, null, deleteOldRDN, null);
}
/**
* Alters the DN of an entry in the directory.
*
* @param dn The DN of the entry to modify.
* @param newRDN The new RDN to use for the entry.
* @param deleteOldRDN Indicates whether to remove the old RDN value(s).
* @param constraints The constraints to use for the modify operation.
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void rename(@NotNull final String dn, @NotNull final String newRDN,
final boolean deleteOldRDN,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
rename(dn, newRDN, null, deleteOldRDN, constraints);
}
/**
* Alters the DN of an entry in the directory.
*
* @param dn The DN of the entry to modify.
* @param newRDN The new RDN to use for the entry.
* @param newParentDN The DN of the new parent, or {@code null} if it
* should not be moved below a new parent.
* @param deleteOldRDN Indicates whether to remove the old RDN value(s).
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void rename(@NotNull final String dn, @NotNull final String newRDN,
@Nullable final String newParentDN,
final boolean deleteOldRDN)
throws LDAPException
{
rename(dn, newRDN, newParentDN, deleteOldRDN, null);
}
/**
* Alters the DN of an entry in the directory.
*
* @param dn The DN of the entry to modify.
* @param newRDN The new RDN to use for the entry.
* @param newParentDN The DN of the new parent, or {@code null} if it
* should not be moved below a new parent.
* @param deleteOldRDN Indicates whether to remove the old RDN value(s).
* @param constraints The constraints to use for the modify operation.
*
* @throws LDAPException If a problem occurs while processing the delete.
*/
public void rename(@NotNull final String dn, @NotNull final String newRDN,
@Nullable final String newParentDN,
final boolean deleteOldRDN,
@Nullable final LDAPConstraints constraints)
throws LDAPException
{
final ModifyDNRequest modifyDNRequest =
new ModifyDNRequest(dn, newRDN, deleteOldRDN, newParentDN);
update(modifyDNRequest, constraints);
try
{
final LDAPResult result = conn.modifyDN(modifyDNRequest);
setResponseControls(result);
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
setResponseControls(le);
throw new LDAPException(le);
}
}
/**
* Processes a search in the directory server.
*
* @param baseDN The base DN for the search.
* @param scope The scope for the search.
* @param filter The filter for the search.
* @param attributes The set of attributes to request.
* @param typesOnly Indicates whether to return attribute types only or
* both types and values.
*
* @return The entry that was read.
*
* @throws LDAPException If a problem occurs while performing the search.
*/
@NotNull()
public LDAPSearchResults search(@NotNull final String baseDN, final int scope,
@NotNull final String filter,
@Nullable final String[] attributes,
final boolean typesOnly)
throws LDAPException
{
return search(baseDN, scope, filter, attributes, typesOnly, null);
}
/**
* Processes a search in the directory server.
*
* @param baseDN The base DN for the search.
* @param scope The scope for the search.
* @param filter The filter for the search.
* @param attributes The set of attributes to request.
* @param typesOnly Indicates whether to return attribute types only or
* both types and values.
* @param constraints The constraints to use for the search operation.
*
* @return The entry that was read.
*
* @throws LDAPException If a problem occurs while performing the search.
*/
@NotNull()
public LDAPSearchResults search(@NotNull final String baseDN, final int scope,
@NotNull final String filter,
@Nullable final String[] attributes,
final boolean typesOnly,
@Nullable final LDAPSearchConstraints constraints)
throws LDAPException
{
final LDAPSearchResults results;
final LDAPSearchConstraints c =
(constraints == null) ? searchConstraints : constraints;
results = new LDAPSearchResults(c.getTimeLimit());
try
{
final SearchRequest searchRequest = new SearchRequest(results, baseDN,
SearchScope.valueOf(scope), filter, attributes);
searchRequest.setDerefPolicy(
DereferencePolicy.valueOf(c.getDereference()));
searchRequest.setSizeLimit(c.getMaxResults());
searchRequest.setTimeLimitSeconds(c.getServerTimeLimit());
searchRequest.setTypesOnly(typesOnly);
update(searchRequest, constraints);
results.setAsyncRequestID(conn.asyncSearch(searchRequest));
return results;
}
catch (final com.unboundid.ldap.sdk.LDAPException le)
{
Debug.debugException(le);
setResponseControls(le);
throw new LDAPException(le);
}
}
/**
* Retrieves the set of controls to use in a request.
*
* @param c The constraints to be applied.
*
* @return The set of controls to use in a request.
*/
@NotNull()
private Control[] getControls(@Nullable final LDAPConstraints c)
{
Control[] controls = null;
if (c != null)
{
controls = LDAPControl.toControls(c.getServerControls());
}
else if (constraints != null)
{
controls = LDAPControl.toControls(constraints.getServerControls());
}
if (controls == null)
{
return new Control[0];
}
else
{
return controls;
}
}
/**
* Updates the provided request to account for the given set of constraints.
*
* @param request The request to be updated.
* @param constraints The constraints to be applied.
*/
private void update(@NotNull final UpdatableLDAPRequest request,
@Nullable final LDAPConstraints constraints)
{
final LDAPConstraints c =
(constraints == null) ? this.constraints : constraints;
request.setControls(LDAPControl.toControls(c.getServerControls()));
request.setResponseTimeoutMillis(c.getTimeLimit());
request.setFollowReferrals(c.getReferrals());
}
/**
* Sets the response controls for this connection.
*
* @param ldapResult The result containing the controls to use.
*/
private void setResponseControls(@NotNull final LDAPResult ldapResult)
{
if (ldapResult.hasResponseControl())
{
responseControls =
LDAPControl.toLDAPControls(ldapResult.getResponseControls());
}
else
{
responseControls = null;
}
}
/**
* Sets the response controls for this connection.
*
* @param ldapException The exception containing the controls to use.
*/
private void setResponseControls(
@NotNull final com.unboundid.ldap.sdk.LDAPException ldapException)
{
if (ldapException.hasResponseControl())
{
responseControls =
LDAPControl.toLDAPControls(ldapException.getResponseControls());
}
else
{
responseControls = null;
}
}
}