Class MoveSubtree

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