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 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
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method 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, 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
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
-
-
-
-
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 benull
if output should be suppressed.err
- The output stream to which standard error should be written. It may benull
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 benull
if output should be suppressed.err
- The output stream to which standard error should be written. It may benull
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 classCommandLineTool
- 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 theCommandLineTool.getAdditionalDescriptionParagraphs()
method should be used to return the text for the subsequent paragraphs.- Specified by:
getToolDescription
in classCommandLineTool
- 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 classCommandLineTool
- 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 classMultiServerLDAPCommandLineTool
- Returns:
true
if this tool should provide multiple versions of long identifiers for LDAP-specific arguments, orfalse
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 classMultiServerLDAPCommandLineTool
- 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 classMultiServerLDAPCommandLineTool
- 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 returnstrue
, 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 classCommandLineTool
- Returns:
true
if this tool should provide arguments for redirecting output to a file, orfalse
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 classCommandLineTool
- 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, orfalse
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 returntrue
for tools that may alter the server configuration, data, or other state information, andfalse
for tools that do not make any changes.- Overrides:
logToolInvocationByDefault
in classCommandLineTool
- 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, orfalse
if not.
-
doToolProcessing
@NotNull public ResultCode doToolProcessing()
Performs the core set of processing for this tool.- Specified by:
doToolProcessing
in classCommandLineTool
- 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
Moves a single leaf entry using a pair of interactive transactions. The logic used to accomplish this is as follows:moveSubtreeWithRestrictedAccessibility
methods instead.- Start an interactive transaction in the source server.
- Start an interactive transaction in the target server.
- 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.
- 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.
- Delete the entry from the source server. The delete request will include the following controls: interactive transaction specification, ManageDsaIT, and operation purpose.
- Commit the interactive transaction in the target server.
- Commit the interactive transaction in the source server.
- 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
Moves a single leaf entry using a pair of interactive transactions. The logic used to accomplish this is as follows:moveSubtreeWithRestrictedAccessibility
methods instead.- Start an interactive transaction in the source server.
- Start an interactive transaction in the target server.
- 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.
- 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.
- Delete the entry from the source server. The delete request will include the following controls: interactive transaction specification, ManageDsaIT, and operation purpose.
- Commit the interactive transaction in the target server.
- Commit the interactive transaction in the source server.
- 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:- Make the subtree hidden in the target server.
- Make the subtree read-only in the source server.
- 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.
- 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.
- Make the subtree read-only in the target server.
- Make the subtree hidden in the source server.
- Make the subtree accessible in the target server.
- 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.
- Make the subtree accessible in the source server.
- 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:- Make the subtree hidden in the target server.
- Make the subtree read-only in the source server.
- 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.
- 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.
- Make the subtree read-only in the target server.
- Make the subtree hidden in the source server.
- Make the subtree accessible in the target server.
- 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.
- Make the subtree accessible in the source server.
- 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.
-
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 interfaceUnsolicitedNotificationHandler
- 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 interfaceMoveSubtreeListener
- 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 interfaceMoveSubtreeListener
- 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 interfaceMoveSubtreeListener
- 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 interfaceMoveSubtreeListener
- 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()
orRuntime.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).
System.halt()
orRuntime.halt()
methods).
If this method is overridden to returntrue
, then theCommandLineTool.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 classCommandLineTool
- Returns:
true
if this tool should register a shutdown hook, orfalse
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 thejava.lang.Runtime.addShutdownHook
method for recommendations and restrictions about writing shutdown hooks.- Overrides:
doShutdownHookProcessing
in classCommandLineTool
- Parameters:
resultCode
- The result code returned by the tool. It may benull
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 classCommandLineTool
- 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.
-
-