com.unboundid.ldap.sdk.unboundidds

Class MoveSubtree

java.lang.Object

com.unboundid.util.CommandLineTool

com.unboundid.util.MultiServerLDAPCommandLineTool

com.unboundid.ldap.sdk.unboundidds.MoveSubtree

All Implemented Interfaces:

MoveSubtreeListener, UnsolicitedNotificationHandler

@ThreadSafety(level=NOT_THREADSAFE)
public final class MoveSubtree
extends MultiServerLDAPCommandLineTool
implements UnsolicitedNotificationHandler, MoveSubtreeListener

This class provides a utility that may be used to move a single entry or a small subtree of entries from one server to another.

NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

Constructor Summary

Constructors

Constructor and Description
MoveSubtree(java.io.OutputStream out, java.io.OutputStream err) Creates a new instance of this tool with the provided output and error streams.

Method Summary

Modifier and Type	Method and Description
void	addNonLDAPArguments(ArgumentParser parser) Adds the arguments needed by this command-line tool to the provided argument parser which are not related to connecting or authenticating to the directory server.
void	doPostAddProcessing(ReadOnlyEntry entry) Performs any processing which may be needed after the provided entry has been added to the target server.
void	doPostDeleteProcessing(DN entryDN) Performs any processing which may be needed after the specified entry has been deleted from the source server.
ReadOnlyEntry	doPreAddProcessing(ReadOnlyEntry entry) Performs any processing which may be needed before the provided entry is added to the target server.
void	doPreDeleteProcessing(DN entryDN) Performs any processing which may be needed before the specified entry is deleted from the source server.
protected void	doShutdownHookProcessing(ResultCode resultCode) Performs any processing that may be needed when the JVM is shutting down, whether because tool processing has completed or because it has been interrupted (e.g., by a kill or break signal).
ResultCode	doToolProcessing() Performs the core set of processing for this tool.
LDAPConnectionOptions	getConnectionOptions() Retrieves the connection options that should be used for connections that are created with this command line tool.
java.util.LinkedHashMap<java.lang.String[],java.lang.String>	getExampleUsages() Retrieves a set of information that may be used to generate example usage information.
java.lang.String	getToolDescription() Retrieves a human-readable description for this tool.
java.lang.String	getToolName() Retrieves the name of this tool.
java.lang.String	getToolVersion() Retrieves a version string for this tool, if available.
void	handleUnsolicitedNotification(LDAPConnection connection, ExtendedResult notification) Performs any processing that may be necessary in response to the provided unsolicited notification that has been received from the server.
protected boolean	includeAlternateLongIdentifiers() Indicates whether the LDAP-specific arguments should include alternate versions of all long identifiers that consist of multiple words so that they are available in both camelCase and dash-separated versions.
protected boolean	logToolInvocationByDefault() Indicates whether to log messages about the launch and completion of this tool into the invocation log of Ping Identity server products that may include it.
static void	main(java.lang.String... args) Parse the provided command line arguments and perform the appropriate processing.
static ResultCode	main(java.lang.String[] args, java.io.OutputStream out, java.io.OutputStream err) Parse the provided command line arguments and perform the appropriate processing.
static MoveSubtreeResult	moveEntryWithInteractiveTransaction(LDAPConnection sourceConnection, LDAPConnection targetConnection, java.lang.String entryDN, OperationPurposeRequestControl opPurposeControl, boolean suppressRefInt, MoveSubtreeListener listener) Deprecated. The use of interactive transactions is strongly discouraged because it can create conditions which are prone to deadlocks between operations that may significantly affect performance and will result in the cancellation of one or both operations.
static MoveSubtreeResult	moveEntryWithInteractiveTransaction(LDAPConnection sourceConnection, LDAPConnection targetConnection, java.lang.String entryDN, OperationPurposeRequestControl opPurposeControl, MoveSubtreeListener listener) Deprecated. The use of interactive transactions is strongly discouraged because it can create conditions which are prone to deadlocks between operations that may significantly affect performance and will result in the cancellation of one or both operations.
static MoveSubtreeResult	moveSubtreeWithRestrictedAccessibility(LDAPConnection sourceConnection, LDAPConnection targetConnection, MoveSubtreeProperties properties) Moves a subtree of entries using a process in which access to the subtree will be restricted while the move is in progress.
static MoveSubtreeResult	moveSubtreeWithRestrictedAccessibility(LDAPConnection sourceConnection, LDAPConnection targetConnection, java.lang.String baseDN, int sizeLimit, OperationPurposeRequestControl opPurposeControl, boolean suppressRefInt, MoveSubtreeListener listener) Moves a subtree of entries using a process in which access to the subtree will be restricted while the move is in progress.
static MoveSubtreeResult	moveSubtreeWithRestrictedAccessibility(LDAPConnection sourceConnection, LDAPConnection targetConnection, java.lang.String baseDN, int sizeLimit, OperationPurposeRequestControl opPurposeControl, MoveSubtreeListener listener) Moves a subtree of entries using a process in which access to the subtree will be restricted while the move is in progress.
protected boolean	registerShutdownHook() Indicates whether this tool should register a shutdown hook with the JVM.
protected boolean	supportsDebugLogging() Indicates whether this tool supports the ability to generate a debug log file.
protected boolean	supportsOutputFile() Indicates whether this tool should provide arguments for redirecting output to a file.
boolean	supportsPropertiesFile() Indicates whether this tool supports the use of a properties file for specifying default values for arguments that aren't specified on the command line.

Methods inherited from class com.unboundid.util.MultiServerLDAPCommandLineTool

addToolArguments, createBindRequest, createServerSet, createSSLUtil, doExtendedArgumentValidation, doExtendedNonLDAPArgumentValidation, getConnection, getConnectionPool, getUnauthenticatedConnection

Methods inherited from class com.unboundid.util.CommandLineTool

addEnableSSLDebuggingArgument, createArgumentParser, defaultsToInteractiveMode, err, getAdditionalDescriptionParagraphs, getErr, getMaxTrailingArguments, getMinTrailingArguments, getOriginalErr, getOriginalOut, getOut, getPasswordFileReader, getToolCompletionMessage, getTrailingArgumentsPlaceholder, out, requestToolArgumentsInteractively, runTool, supportsInteractiveMode, wrapErr, wrapOut

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MoveSubtree

public MoveSubtree(@Nullable
                   java.io.OutputStream out,
                   @Nullable
                   java.io.OutputStream err)

Creates a new instance of this tool with the provided output and error streams.

Parameters:

out - The output stream to which standard out should be written. It may be null if output should be suppressed.

err - The output stream to which standard error should be written. It may be null if error messages should be suppressed.

Method Detail

main

public static void main(@NotNull
                        java.lang.String... args)

Parse the provided command line arguments and perform the appropriate processing.

Parameters:

args - The command line arguments provided to this program.

main

@NotNull
public static ResultCode main(@NotNull
                                       java.lang.String[] args,
                                       @Nullable
                                       java.io.OutputStream out,
                                       @Nullable
                                       java.io.OutputStream err)

Parse the provided command line arguments and perform the appropriate processing.

Parameters:

args - The command line arguments provided to this program.

out - The output stream to which standard out should be written. It may be null if output should be suppressed.

err - The output stream to which standard error should be written. It may be null if error messages should be suppressed.

Returns:

A result code indicating whether the processing was successful.

getToolName

@NotNull
public java.lang.String getToolName()

Retrieves the name of this tool. It should be the name of the command used to invoke this tool.

Specified by:

getToolName in class CommandLineTool

Returns:

The name for this tool.

getToolDescription

@NotNull
public java.lang.String getToolDescription()

Retrieves a human-readable description for this tool. If the description should include multiple paragraphs, then this method should return the text for the first paragraph, and the CommandLineTool.getAdditionalDescriptionParagraphs() method should be used to return the text for the subsequent paragraphs.

Specified by:

getToolDescription in class CommandLineTool

Returns:

A human-readable description for this tool.

getToolVersion

@NotNull
public java.lang.String getToolVersion()

Retrieves a version string for this tool, if available.

Overrides:

getToolVersion in class CommandLineTool

Returns:

A version string for this tool, or null if none is available.

includeAlternateLongIdentifiers

protected boolean includeAlternateLongIdentifiers()

Indicates whether the LDAP-specific arguments should include alternate versions of all long identifiers that consist of multiple words so that they are available in both camelCase and dash-separated versions.

Overrides:

includeAlternateLongIdentifiers in class MultiServerLDAPCommandLineTool

Returns:

true if this tool should provide multiple versions of long identifiers for LDAP-specific arguments, or false if not.

addNonLDAPArguments

public void addNonLDAPArguments(@NotNull
                                ArgumentParser parser)
                         throws ArgumentException

Adds the arguments needed by this command-line tool to the provided argument parser which are not related to connecting or authenticating to the directory server.

Specified by:

addNonLDAPArguments in class MultiServerLDAPCommandLineTool

Parameters:

parser - The argument parser to which the arguments should be added.

Throws:

ArgumentException - If a problem occurs while adding the arguments.

getConnectionOptions

@NotNull
public LDAPConnectionOptions getConnectionOptions()

Retrieves the connection options that should be used for connections that are created with this command line tool. Subclasses may override this method to use a custom set of connection options.

Overrides:

getConnectionOptions in class MultiServerLDAPCommandLineTool

Returns:

The connection options that should be used for connections that are created with this command line tool.

supportsOutputFile

protected boolean supportsOutputFile()

Indicates whether this tool should provide arguments for redirecting output to a file. If this method returns true, then the tool will offer an "--outputFile" argument that will specify the path to a file to which all standard output and standard error content will be written, and it will also offer a "--teeToStandardOut" argument that can only be used if the "--outputFile" argument is present and will cause all output to be written to both the specified output file and to standard output.

Overrides:

supportsOutputFile in class CommandLineTool

Returns:

true if this tool should provide arguments for redirecting output to a file, or false if not.

supportsPropertiesFile

public boolean supportsPropertiesFile()

Indicates whether this tool supports the use of a properties file for specifying default values for arguments that aren't specified on the command line.

Overrides:

supportsPropertiesFile in class CommandLineTool

Returns:

true if this tool supports the use of a properties file for specifying default values for arguments that aren't specified on the command line, or false if not.

supportsDebugLogging

protected boolean supportsDebugLogging()

Indicates whether this tool supports the ability to generate a debug log file. If this method returns true, then the tool will expose additional arguments that can control debug logging.

Overrides:

supportsDebugLogging in class CommandLineTool

Returns:

true if this tool supports the ability to generate a debug log file, or false if not.

logToolInvocationByDefault

protected boolean logToolInvocationByDefault()

Indicates whether to log messages about the launch and completion of this tool into the invocation log of Ping Identity server products that may include it. This method is not needed for tools that are not expected to be part of the Ping Identity server products suite. Further, this value may be overridden by settings in the server's tool-invocation-logging.properties file.

This method should generally return true for tools that may alter the server configuration, data, or other state information, and false for tools that do not make any changes.

Overrides:

logToolInvocationByDefault in class CommandLineTool

Returns:

true if Ping Identity server products should include messages about the launch and completion of this tool in tool invocation log files by default, or false if not.

doToolProcessing

@NotNull
public ResultCode doToolProcessing()

Performs the core set of processing for this tool.

Specified by:

doToolProcessing in class CommandLineTool

Returns:

A result code that indicates whether the processing completed successfully.

moveEntryWithInteractiveTransaction

@Deprecated
 @NotNull
public static MoveSubtreeResult moveEntryWithInteractiveTransaction(@NotNull
                                                                                          LDAPConnection sourceConnection,
                                                                                          @NotNull
                                                                                          LDAPConnection targetConnection,
                                                                                          @NotNull
                                                                                          java.lang.String entryDN,
                                                                                          @Nullable
                                                                                          OperationPurposeRequestControl opPurposeControl,
                                                                                          @Nullable
                                                                                          MoveSubtreeListener listener)

Deprecated. The use of interactive transactions is strongly discouraged because it can create conditions which are prone to deadlocks between operations that may significantly affect performance and will result in the cancellation of one or both operations.

NOTE: The use of interactive transactions is strongly discouraged because it can create conditions which are prone to deadlocks between operations that may significantly affect performance and will result in the cancellation of one or both operations. Use one of the moveSubtreeWithRestrictedAccessibility methods instead.

Moves a single leaf entry using a pair of interactive transactions. The logic used to accomplish this is as follows:

1. Start an interactive transaction in the source server.
2. Start an interactive transaction in the target server.
3. Read the entry from the source server. The search request will have a subtree scope with a size limit of one, a filter of "(objectClass=*)", will request all user and operational attributes, and will include the following request controls: interactive transaction specification, ManageDsaIT, LDAP subentries, return conflict entries, soft-deleted entry access, real attributes only, and operation purpose.
4. Add the entry to the target server. The add request will include the following controls: interactive transaction specification, ignore NO-USER-MODIFICATION, and operation purpose.
5. Delete the entry from the source server. The delete request will include the following controls: interactive transaction specification, ManageDsaIT, and operation purpose.
6. Commit the interactive transaction in the target server.
7. Commit the interactive transaction in the source server.

Conditions which could result in an incomplete move include:

• The commit in the target server succeeds but the commit in the source server fails. In this case, the entry may end up in both servers, requiring manual cleanup. If this occurs, then the result returned from this method will indicate this condition.
• The account used to read entries from the source server does not have permission to see all attributes in all entries. In this case, the target server will include only a partial representation of the entry in the source server. To avoid this problem, ensure that the account used to read from the source server has sufficient access rights to see all attributes in the entry to move.
• The source server participates in replication and a change occurs to the entry in a different server in the replicated environment while the move is in progress. In this case, those changes may not be reflected in the target server. To avoid this problem, it is strongly recommended that all write access in the replication environment containing the source server be directed to the source server during the time that the move is in progress (e.g., using a failover load-balancing algorithm in the Directory Proxy Server).

Parameters:

sourceConnection - A connection established to the source server. It should be authenticated as a user with permission to perform all of the operations against the source server as referenced above.

targetConnection - A connection established to the target server. It should be authenticated as a user with permission to perform all of the operations against the target server as referenced above.

entryDN - The base DN for the subtree to move.

opPurposeControl - An optional operation purpose request control that may be included in all requests sent to the source and target servers.

listener - An optional listener that may be invoked during the course of moving entries from the source server to the target server.

Returns:

An object with information about the result of the attempted subtree move.

moveEntryWithInteractiveTransaction

@Deprecated
 @NotNull
public static MoveSubtreeResult moveEntryWithInteractiveTransaction(@NotNull
                                                                                          LDAPConnection sourceConnection,
                                                                                          @NotNull
                                                                                          LDAPConnection targetConnection,
                                                                                          @NotNull
                                                                                          java.lang.String entryDN,
                                                                                          @Nullable
                                                                                          OperationPurposeRequestControl opPurposeControl,
                                                                                          boolean suppressRefInt,
                                                                                          @Nullable
                                                                                          MoveSubtreeListener listener)

Deprecated. The use of interactive transactions is strongly discouraged because it can create conditions which are prone to deadlocks between operations that may significantly affect performance and will result in the cancellation of one or both operations.

NOTE: The use of interactive transactions is strongly discouraged because it can create conditions which are prone to deadlocks between operations that may significantly affect performance and will result in the cancellation of one or both operations. Use one of the moveSubtreeWithRestrictedAccessibility methods instead.

Moves a single leaf entry using a pair of interactive transactions. The logic used to accomplish this is as follows:

1. Start an interactive transaction in the source server.
2. Start an interactive transaction in the target server.
3. Read the entry from the source server. The search request will have a subtree scope with a size limit of one, a filter of "(objectClass=*)", will request all user and operational attributes, and will include the following request controls: interactive transaction specification, ManageDsaIT, LDAP subentries, return conflict entries, soft-deleted entry access, real attributes only, and operation purpose.
4. Add the entry to the target server. The add request will include the following controls: interactive transaction specification, ignore NO-USER-MODIFICATION, and operation purpose.
5. Delete the entry from the source server. The delete request will include the following controls: interactive transaction specification, ManageDsaIT, and operation purpose.
6. Commit the interactive transaction in the target server.
7. Commit the interactive transaction in the source server.

Conditions which could result in an incomplete move include:

• The commit in the target server succeeds but the commit in the source server fails. In this case, the entry may end up in both servers, requiring manual cleanup. If this occurs, then the result returned from this method will indicate this condition.
• The account used to read entries from the source server does not have permission to see all attributes in all entries. In this case, the target server will include only a partial representation of the entry in the source server. To avoid this problem, ensure that the account used to read from the source server has sufficient access rights to see all attributes in the entry to move.
• The source server participates in replication and a change occurs to the entry in a different server in the replicated environment while the move is in progress. In this case, those changes may not be reflected in the target server. To avoid this problem, it is strongly recommended that all write access in the replication environment containing the source server be directed to the source server during the time that the move is in progress (e.g., using a failover load-balancing algorithm in the Directory Proxy Server).

Parameters:

sourceConnection - A connection established to the source server. It should be authenticated as a user with permission to perform all of the operations against the source server as referenced above.

targetConnection - A connection established to the target server. It should be authenticated as a user with permission to perform all of the operations against the target server as referenced above.

entryDN - The base DN for the subtree to move.

opPurposeControl - An optional operation purpose request control that may be included in all requests sent to the source and target servers.

suppressRefInt - Indicates whether to include a request control causing referential integrity updates to be suppressed on the source server.

listener - An optional listener that may be invoked during the course of moving entries from the source server to the target server.

Returns:

An object with information about the result of the attempted subtree move.

moveSubtreeWithRestrictedAccessibility

@NotNull
public static MoveSubtreeResult moveSubtreeWithRestrictedAccessibility(@NotNull
                                                                                LDAPConnection sourceConnection,
                                                                                @NotNull
                                                                                LDAPConnection targetConnection,
                                                                                @NotNull
                                                                                java.lang.String baseDN,
                                                                                int sizeLimit,
                                                                                @Nullable
                                                                                OperationPurposeRequestControl opPurposeControl,
                                                                                @Nullable
                                                                                MoveSubtreeListener listener)

Moves a subtree of entries using a process in which access to the subtree will be restricted while the move is in progress. While entries are being read from the source server and added to the target server, the subtree will be read-only in the source server and hidden in the target server. While entries are being removed from the source server, the subtree will be hidden in the source server while fully accessible in the target. After all entries have been removed from the source server, the accessibility restriction will be removed from that server as well.

The logic used to accomplish this is as follows:

1. Make the subtree hidden in the target server.
2. Make the subtree read-only in the source server.
3. Perform a search in the source server to retrieve all entries in the specified subtree. The search request will have a subtree scope with a filter of "(objectClass=*)", will include the specified size limit, will request all user and operational attributes, and will include the following request controls: ManageDsaIT, LDAP subentries, return conflict entries, soft-deleted entry access, real attributes only, and operation purpose.
4. For each entry returned by the search, add that entry to the target server. This method assumes that the source server will return results in a manner that guarantees that no child entry is returned before its parent. Each add request will include the following controls: ignore NO-USER-MODIFICATION, and operation purpose.
5. Make the subtree read-only in the target server.
6. Make the subtree hidden in the source server.
7. Make the subtree accessible in the target server.
8. Delete each entry from the source server, with all subordinate entries before their parents. Each delete request will include the following controls: ManageDsaIT, and operation purpose.
9. Make the subtree accessible in the source server.

Conditions which could result in an incomplete move include:

• A failure is encountered while altering the accessibility of the subtree in either the source or target server.
• A failure is encountered while attempting to process an add in the target server and a subsequent failure is encountered when attempting to delete previously-added entries.
• A failure is encountered while attempting to delete one or more entries from the source server.

Parameters:

sourceConnection - A connection established to the source server. It should be authenticated as a user with permission to perform all of the operations against the source server as referenced above.

targetConnection - A connection established to the target server. It should be authenticated as a user with permission to perform all of the operations against the target server as referenced above.

baseDN - The base DN for the subtree to move.

sizeLimit - The maximum number of entries to be moved. It may be less than or equal to zero to indicate that no client-side limit should be enforced (although the server may still enforce its own limit).

opPurposeControl - An optional operation purpose request control that may be included in all requests sent to the source and target servers.

listener - An optional listener that may be invoked during the course of moving entries from the source server to the target server.

Returns:

An object with information about the result of the attempted subtree move.

moveSubtreeWithRestrictedAccessibility

@NotNull
public static MoveSubtreeResult moveSubtreeWithRestrictedAccessibility(@NotNull
                                                                                LDAPConnection sourceConnection,
                                                                                @NotNull
                                                                                LDAPConnection targetConnection,
                                                                                @NotNull
                                                                                java.lang.String baseDN,
                                                                                int sizeLimit,
                                                                                @Nullable
                                                                                OperationPurposeRequestControl opPurposeControl,
                                                                                boolean suppressRefInt,
                                                                                @Nullable
                                                                                MoveSubtreeListener listener)

Moves a subtree of entries using a process in which access to the subtree will be restricted while the move is in progress. While entries are being read from the source server and added to the target server, the subtree will be read-only in the source server and hidden in the target server. While entries are being removed from the source server, the subtree will be hidden in the source server while fully accessible in the target. After all entries have been removed from the source server, the accessibility restriction will be removed from that server as well.

The logic used to accomplish this is as follows:

1. Make the subtree hidden in the target server.
2. Make the subtree read-only in the source server.
3. Perform a search in the source server to retrieve all entries in the specified subtree. The search request will have a subtree scope with a filter of "(objectClass=*)", will include the specified size limit, will request all user and operational attributes, and will include the following request controls: ManageDsaIT, LDAP subentries, return conflict entries, soft-deleted entry access, real attributes only, and operation purpose.
4. For each entry returned by the search, add that entry to the target server. This method assumes that the source server will return results in a manner that guarantees that no child entry is returned before its parent. Each add request will include the following controls: ignore NO-USER-MODIFICATION, and operation purpose.
5. Make the subtree read-only in the target server.
6. Make the subtree hidden in the source server.
7. Make the subtree accessible in the target server.
8. Delete each entry from the source server, with all subordinate entries before their parents. Each delete request will include the following controls: ManageDsaIT, and operation purpose.
9. Make the subtree accessible in the source server.

Conditions which could result in an incomplete move include:

• A failure is encountered while altering the accessibility of the subtree in either the source or target server.
• A failure is encountered while attempting to process an add in the target server and a subsequent failure is encountered when attempting to delete previously-added entries.
• A failure is encountered while attempting to delete one or more entries from the source server.

Parameters:

sourceConnection - A connection established to the source server. It should be authenticated as a user with permission to perform all of the operations against the source server as referenced above.

targetConnection - A connection established to the target server. It should be authenticated as a user with permission to perform all of the operations against the target server as referenced above.

baseDN - The base DN for the subtree to move.

sizeLimit - The maximum number of entries to be moved. It may be less than or equal to zero to indicate that no client-side limit should be enforced (although the server may still enforce its own limit).

opPurposeControl - An optional operation purpose request control that may be included in all requests sent to the source and target servers.

suppressRefInt - Indicates whether to include a request control causing referential integrity updates to be suppressed on the source server.

listener - An optional listener that may be invoked during the course of moving entries from the source server to the target server.

Returns:

An object with information about the result of the attempted subtree move.

moveSubtreeWithRestrictedAccessibility

@NotNull
public static MoveSubtreeResult moveSubtreeWithRestrictedAccessibility(@NotNull
                                                                                LDAPConnection sourceConnection,
                                                                                @NotNull
                                                                                LDAPConnection targetConnection,
                                                                                @NotNull
                                                                                MoveSubtreeProperties properties)

Moves a subtree of entries using a process in which access to the subtree will be restricted while the move is in progress. While entries are being read from the source server and added to the target server, the subtree will be read-only in the source server and hidden in the target server. While entries are being removed from the source server, the subtree will be marked as either hidden or to-be-deleted in the source server while fully accessible in the target. After all entries have been removed from the source server, the accessibility restriction will be removed from that server as well.

The logic used to accomplish this is as follows:

1. Make the subtree hidden in the target server.
2. Make the subtree read-only in the source server.
3. Perform a search in the source server to retrieve all entries in the specified subtree. The search request will have a subtree scope with a filter of "(objectClass=*)", will include the specified size limit, will request all user and operational attributes, and will include the following request controls: ManageDsaIT, LDAP subentries, return conflict entries, soft-deleted entry access, real attributes only, and operation purpose.
4. For each entry returned by the search, add that entry to the target server. This method assumes that the source server will return results in a manner that guarantees that no child entry is returned before its parent. Each add request will include the following controls: ignore NO-USER-MODIFICATION, and operation purpose.
5. Make the subtree read-only in the target server.
6. Make the subtree hidden or to-be-deleted in the source server.
7. Make the subtree accessible in the target server.
8. Delete each entry from the source server, with all subordinate entries before their parents. Each delete request will include the following controls: ManageDsaIT, and operation purpose.
9. Make the subtree accessible in the source server.

Conditions which could result in an incomplete move include:

• A failure is encountered while altering the accessibility of the subtree in either the source or target server.
• A failure is encountered while attempting to process an add in the target server and a subsequent failure is encountered when attempting to delete previously-added entries.
• A failure is encountered while attempting to delete one or more entries from the source server.

Parameters:

sourceConnection - A connection established to the source server. It should be authenticated as a user with permission to perform all of the operations against the source server as referenced above.

targetConnection - A connection established to the target server. It should be authenticated as a user with permission to perform all of the operations against the target server as referenced above.

properties - A set of properties that indicate how the move shoudl be performed.

Returns:

An object with information about the result of the attempted subtree move.

handleUnsolicitedNotification

public void handleUnsolicitedNotification(@NotNull
                                          LDAPConnection connection,
                                          @NotNull
                                          ExtendedResult notification)

Performs any processing that may be necessary in response to the provided unsolicited notification that has been received from the server.

Specified by:

handleUnsolicitedNotification in interface UnsolicitedNotificationHandler

Parameters:

connection - The connection on which the unsolicited notification was received.

notification - The unsolicited notification that has been received from the server.

doPreAddProcessing

@NotNull
public ReadOnlyEntry doPreAddProcessing(@NotNull
                                                 ReadOnlyEntry entry)

Performs any processing which may be needed before the provided entry is added to the target server.

Specified by:

doPreAddProcessing in interface MoveSubtreeListener

Parameters:

entry - A read-only representation of the entry to be added to the target server.

Returns:

The original entry if the add should proceed without changes, a new entry (which must have the same DN as the provided entry) if the entry should be added with changes, or null if the entry should not be added to the target server (but will still be removed from the source server).

doPostAddProcessing

public void doPostAddProcessing(@NotNull
                                ReadOnlyEntry entry)

Performs any processing which may be needed after the provided entry has been added to the target server.

Specified by:

doPostAddProcessing in interface MoveSubtreeListener

Parameters:

entry - A read-only representation of the entry that was added to the target server. Note that depending on the algorithm used to perform the move, the entry may not yet be accessible in the target server. Also note that the add may potentially be reverted if move processing encounters an error later in its processing.

doPreDeleteProcessing

public void doPreDeleteProcessing(@NotNull
                                  DN entryDN)

Performs any processing which may be needed before the specified entry is deleted from the source server.

Specified by:

doPreDeleteProcessing in interface MoveSubtreeListener

Parameters:

entryDN - The DN of the entry that is to be removed from the source server. Note that depending on the algorithm used to perform the move, the entry may already be inaccessible in the source server.

doPostDeleteProcessing

public void doPostDeleteProcessing(@NotNull
                                   DN entryDN)

Performs any processing which may be needed after the specified entry has been deleted from the source server.

Specified by:

doPostDeleteProcessing in interface MoveSubtreeListener

Parameters:

entryDN - The DN of the entry that has been removed from the source server. Note that the delete may potentially be reverted if move processing encounters an error later in its processing.

registerShutdownHook

protected boolean registerShutdownHook()

Indicates whether this tool should register a shutdown hook with the JVM. Shutdown hooks allow for a best-effort attempt to perform a specified set of processing when the JVM is shutting down under various conditions, including:

• When all non-daemon threads have stopped running (i.e., the tool has completed processing).
• When System.exit() or Runtime.exit() is called.
• When the JVM receives an external kill signal (e.g., via the use of the kill tool or interrupting the JVM with Ctrl+C).

Shutdown hooks may not be invoked if the process is forcefully killed (e.g., using "kill -9", or the System.halt() or Runtime.halt() methods).

If this method is overridden to return true, then the CommandLineTool.doShutdownHookProcessing(ResultCode) method should also be overridden to contain the logic that will be invoked when the JVM is shutting down in a manner that calls shutdown hooks.

Overrides:

registerShutdownHook in class CommandLineTool

Returns:

true if this tool should register a shutdown hook, or false if not.

doShutdownHookProcessing

protected void doShutdownHookProcessing(@Nullable
                                        ResultCode resultCode)

Performs any processing that may be needed when the JVM is shutting down, whether because tool processing has completed or because it has been interrupted (e.g., by a kill or break signal).

Note that because shutdown hooks run at a delicate time in the life of the JVM, they should complete quickly and minimize access to external resources. See the documentation for the java.lang.Runtime.addShutdownHook method for recommendations and restrictions about writing shutdown hooks.

Overrides:

doShutdownHookProcessing in class CommandLineTool

Parameters:

resultCode - The result code returned by the tool. It may be null if the tool was interrupted before it completed processing.

getExampleUsages

@NotNull
public java.util.LinkedHashMap<java.lang.String[],java.lang.String> getExampleUsages()

Retrieves a set of information that may be used to generate example usage information. Each element in the returned map should consist of a map between an example set of arguments and a string that describes the behavior of the tool when invoked with that set of arguments.

Overrides:

getExampleUsages in class CommandLineTool

Returns:

A set of information that may be used to generate example usage information. It may be null or empty if no example usage information is available.