com.unboundid.ldap.sdk.unboundidds
Class MoveSubtree

java.lang.Object
  extended by com.unboundid.util.CommandLineTool
      extended by com.unboundid.util.MultiServerLDAPCommandLineTool
          extended by com.unboundid.ldap.sdk.unboundidds.MoveSubtree
All Implemented Interfaces:
MoveSubtreeListener, UnsolicitedNotificationHandler

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

NOTE: This class is part of the Commercial Edition of the UnboundID LDAP SDK for Java. It is not available for use in applications that include only the Standard Edition of the LDAP SDK, and is not supported for use in conjunction with non-UnboundID products.
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.


Constructor Summary
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
 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.
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)
          Moves a single leaf entry using a pair of interactive transactions.
static MoveSubtreeResult moveEntryWithInteractiveTransaction(LDAPConnection sourceConnection, LDAPConnection targetConnection, java.lang.String entryDN, OperationPurposeRequestControl opPurposeControl, MoveSubtreeListener listener)
          Moves a single leaf entry using a pair of interactive transactions.
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.
 
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
createArgumentParser, err, getErr, getMaxTrailingArguments, getOut, getTrailingArgumentsPlaceholder, out, runTool, 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(java.io.OutputStream out,
                   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(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

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

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

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

public java.lang.String getToolDescription()
Retrieves a human-readable description for this tool.

Specified by:
getToolDescription in class CommandLineTool
Returns:
A human-readable description for this tool.

getToolVersion

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.

addNonLDAPArguments

public void addNonLDAPArguments(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

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.

doToolProcessing

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

public static MoveSubtreeResult moveEntryWithInteractiveTransaction(LDAPConnection sourceConnection,
                                                                    LDAPConnection targetConnection,
                                                                    java.lang.String entryDN,
                                                                    OperationPurposeRequestControl opPurposeControl,
                                                                    MoveSubtreeListener listener)
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:

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

public static MoveSubtreeResult moveEntryWithInteractiveTransaction(LDAPConnection sourceConnection,
                                                                    LDAPConnection targetConnection,
                                                                    java.lang.String entryDN,
                                                                    OperationPurposeRequestControl opPurposeControl,
                                                                    boolean suppressRefInt,
                                                                    MoveSubtreeListener listener)
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:

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

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

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

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

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.

handleUnsolicitedNotification

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

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

public ReadOnlyEntry doPreAddProcessing(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(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(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(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: 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(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

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.