com.unboundid.ldap.sdk.unboundidds.tools

Class ToolUtils

java.lang.Object

com.unboundid.ldap.sdk.unboundidds.tools.ToolUtils

@ThreadSafety(level=NOT_THREADSAFE)
public final class ToolUtils
extends java.lang.Object

This class provides a number of utility methods primarily intended for use with command-line tools.

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.

Method Summary

Modifier and Type	Method and Description
static ObjectPair<java.io.InputStream,java.lang.String>	getInputStreamForLDIFFiles(java.util.List<java.io.File> ldifFiles, java.lang.String encryptionPassphrase, java.io.PrintStream out, java.io.PrintStream err) Retrieves an input stream that can be used to read data from the specified list of files.
static java.io.InputStream	getPossiblyGZIPCompressedInputStream(java.io.InputStream inputStream) Retrieves an InputStream that can be used to read data from the provided input stream that may have potentially been GZIP-compressed.
static java.io.InputStream	getPossiblyPassphraseEncryptedInputStream(java.io.InputStream inputStream) Retrieves an InputStream that can be used to read data from the provided input stream that may have potentially been encrypted with a PassphraseEncryptedOutputStream using a key from a Ping Identity or Nokia/Alcatel-Lucent 8661 Directory Server's encryption settings database.
static ObjectPair<java.io.InputStream,char[]>	getPossiblyPassphraseEncryptedInputStream(java.io.InputStream inputStream, char[] potentialPassphrase, boolean promptOnIncorrectPassphrase, java.lang.CharSequence passphrasePrompt, java.lang.CharSequence incorrectPassphraseError, java.io.PrintStream standardOutput, java.io.PrintStream standardError) Retrieves an InputStream that can be used to read data from the provided input stream that may have potentially been encrypted with a PassphraseEncryptedOutputStream.
static ObjectPair<java.io.InputStream,char[]>	getPossiblyPassphraseEncryptedInputStream(java.io.InputStream inputStream, java.util.Collection<char[]> potentialPassphrases, boolean promptOnIncorrectPassphrase, java.lang.CharSequence passphrasePrompt, java.lang.CharSequence incorrectPassphraseError, java.io.PrintStream standardOutput, java.io.PrintStream standardError) Retrieves an InputStream that can be used to read data from the provided input stream that may have potentially been encrypted with a PassphraseEncryptedOutputStream.
static ObjectPair<java.io.InputStream,java.lang.String>	getPossiblyPassphraseEncryptedInputStream(java.io.InputStream inputStream, java.lang.String potentialPassphrase, boolean promptOnIncorrectPassphrase, java.lang.CharSequence passphrasePrompt, java.lang.CharSequence incorrectPassphraseError, java.io.PrintStream standardOutput, java.io.PrintStream standardError) Retrieves an InputStream that can be used to read data from the provided input stream that may have potentially been encrypted with a PassphraseEncryptedOutputStream.
static java.lang.String	promptForEncryptionPassphrase(boolean allowEmpty, boolean confirm, java.lang.CharSequence initialPrompt, java.lang.CharSequence confirmPrompt, java.io.PrintStream out, java.io.PrintStream err) Interactively prompts the user for an encryption passphrase.
static java.lang.String	promptForEncryptionPassphrase(boolean allowEmpty, boolean confirm, java.io.PrintStream out, java.io.PrintStream err) Interactively prompts the user for an encryption passphrase.
static java.lang.String	readEncryptionPassphraseFromFile(java.io.File f) Reads an encryption passphrase from the specified file.
static void	wrap(java.lang.CharSequence message, java.io.PrintStream out) Writes a wrapped version of the provided message to the given stream.
static void	wrapPrompt(java.lang.CharSequence prompt, boolean ensureTrailingSpace, java.io.PrintStream out) Wraps the provided prompt such that every line except the last will be followed by a newline, but the last line will not be followed by a newline.

Methods inherited from class java.lang.Object

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

Method Detail

readEncryptionPassphraseFromFile

@NotNull
public static java.lang.String readEncryptionPassphraseFromFile(@NotNull
                                                                         java.io.File f)
                                                                  throws LDAPException

Reads an encryption passphrase from the specified file. The file must contain exactly one line, which must not be empty, and must be comprised entirely of the encryption passphrase.

Parameters:

f - The file from which the passphrase should be read. It must not be null.

Returns:

The encryption passphrase read from the specified file.

Throws:

LDAPException - If a problem occurs while attempting to read the encryption passphrase.

promptForEncryptionPassphrase

@NotNull
public static java.lang.String promptForEncryptionPassphrase(boolean allowEmpty,
                                                                      boolean confirm,
                                                                      @NotNull
                                                                      java.io.PrintStream out,
                                                                      @NotNull
                                                                      java.io.PrintStream err)
                                                               throws LDAPException

Interactively prompts the user for an encryption passphrase.

Parameters:

allowEmpty - Indicates whether the encryption passphrase is allowed to be empty. If this is false, then the user will be re-prompted for the passphrase if the value they enter is empty.

confirm - Indicates whether the user will asked to confirm the passphrase. If this is true, then the user will have to enter the same passphrase twice. If this is false, then the user will only be prompted once.

out - The PrintStream that will be used for standard output. It must not be null.

err - The PrintStream that will be used for standard error. It must not be null.

Returns:

The encryption passphrase provided by the user.

Throws:

LDAPException - If a problem is encountered while trying to obtain the passphrase from the user.

promptForEncryptionPassphrase

@NotNull
public static java.lang.String promptForEncryptionPassphrase(boolean allowEmpty,
                                                                      boolean confirm,
                                                                      @NotNull
                                                                      java.lang.CharSequence initialPrompt,
                                                                      @Nullable
                                                                      java.lang.CharSequence confirmPrompt,
                                                                      @NotNull
                                                                      java.io.PrintStream out,
                                                                      @NotNull
                                                                      java.io.PrintStream err)
                                                               throws LDAPException

Interactively prompts the user for an encryption passphrase.

Parameters:

allowEmpty - Indicates whether the encryption passphrase is allowed to be empty. If this is false, then the user will be re-prompted for the passphrase if the value they enter is empty.

confirm - Indicates whether the user will asked to confirm the passphrase. If this is true, then the user will have to enter the same passphrase twice. If this is false, then the user will only be prompted once.

initialPrompt - The initial prompt that will be presented to the user. It must not be null or empty.

confirmPrompt - The prompt that will be presented to the user when asked to confirm the passphrase. It may be null only if confirm is false.

out - The PrintStream that will be used for standard output. It must not be null.

err - The PrintStream that will be used for standard error. It must not be null.

Returns:

The encryption passphrase provided by the user.

Throws:

LDAPException - If a problem is encountered while trying to obtain the passphrase from the user.

wrap

public static void wrap(@NotNull
                        java.lang.CharSequence message,
                        @NotNull
                        java.io.PrintStream out)

Writes a wrapped version of the provided message to the given stream.

Parameters:

message - The message to be written. If it is null or empty, then an empty line will be printed.

out - The PrintStream that should be used to write the provided message.

wrapPrompt

public static void wrapPrompt(@NotNull
                              java.lang.CharSequence prompt,
                              boolean ensureTrailingSpace,
                              @NotNull
                              java.io.PrintStream out)

Wraps the provided prompt such that every line except the last will be followed by a newline, but the last line will not be followed by a newline.

Parameters:

prompt - The prompt to be wrapped. It must not be null or empty.

ensureTrailingSpace - Indicates whether to ensure that there is a trailing space after the end of the prompt.

out - The PrintStream to which the prompt should be written. It must not be null.

getInputStreamForLDIFFiles

@NotNull
public static ObjectPair<java.io.InputStream,java.lang.String> getInputStreamForLDIFFiles(@NotNull
                                                                                                   java.util.List<java.io.File> ldifFiles,
                                                                                                   @Nullable
                                                                                                   java.lang.String encryptionPassphrase,
                                                                                                   @NotNull
                                                                                                   java.io.PrintStream out,
                                                                                                   @NotNull
                                                                                                   java.io.PrintStream err)
                                                                                            throws java.io.IOException

Retrieves an input stream that can be used to read data from the specified list of files. It will handle the possibility that any or all of the LDIF files are encrypted and/or compressed.

Parameters:

ldifFiles - The list of LDIF files from which the data is to be read. It must not be null or empty.

encryptionPassphrase - The passphrase that should be used to access encrypted LDIF files. It may be null if the user should be interactively prompted for the passphrase if any of the files is encrypted.

out - The print stream to use for standard output. It must not be null.

err - The print stream to use for standard error. It must not be null.

Returns:

An ObjectPair whose first element is an input stream that can be used to read data from the specified list of files, and whose second element is a possibly-null passphrase that is used to encrypt the input data.

Throws:

java.io.IOException - If a problem is encountered while attempting to get the input stream for reading the data.

getPossiblyGZIPCompressedInputStream

@NotNull
public static java.io.InputStream getPossiblyGZIPCompressedInputStream(@NotNull
                                                                                java.io.InputStream inputStream)
                                                                         throws java.io.IOException

Retrieves an InputStream that can be used to read data from the provided input stream that may have potentially been GZIP-compressed. If the provided input stream does not appear to contain GZIP-compressed data, then the returned stream will permit reading the data from the provided stream without any alteration.

The determination will be made by looking to see if the first two bytes read from the provided input stream are 0x1F and 0x8B, respectively (which is the GZIP magic header). To avoid false positives, this method should only be used if it is known that if the input stream does not contain compressed data, then it will not start with that two-byte sequence. This method should always be safe to use if the data to be read is text. If the data may be binary and that binary data may happen to start with 0x1F 0x8B, then this method should not be used.

The input stream's mark and reset methods will be used to permit peeking at the data at the head of the input stream. If the provided stream does not support the use of those methods, then it will be wrapped in a BufferedInputStream, which does support them.

Parameters:

inputStream - The input stream from which the data is to be read.

Returns:

A GZIPInputStream that wraps the provided input stream if the stream appears to contain GZIP-compressed data, or the provided input stream (potentially wrapped in a BufferedInputStream) if the provided stream does not appear to contain GZIP-compressed data.

Throws:

java.io.IOException - If a problem is encountered while attempting to determine whether the stream contains GZIP-compressed data.

getPossiblyPassphraseEncryptedInputStream

@NotNull
public static java.io.InputStream getPossiblyPassphraseEncryptedInputStream(@NotNull
                                                                                     java.io.InputStream inputStream)
                                                                              throws java.io.IOException,
                                                                                     java.security.GeneralSecurityException

Retrieves an InputStream that can be used to read data from the provided input stream that may have potentially been encrypted with a PassphraseEncryptedOutputStream using a key from a Ping Identity or Nokia/Alcatel-Lucent 8661 Directory Server's encryption settings database. This method will throw an exception rather than interactively prompting for a passphrase if the content is encrypted but the encryption key is not readily available.

The determination will be made by looking to see if the input stream starts with a valid PassphraseEncryptedStreamHeader. Because of the complex nature of that header, it is highly unlikely that the input stream will just happen to start with a valid header if the stream does not actually contain encrypted data.

The input stream's mark and reset methods will be used to permit peeking at the data at the head of the input stream. If the provided stream does not support the use of those methods, then it will be wrapped in a BufferedInputStream, which does support them.

Parameters:

inputStream - The input stream from which the data is to be read. It must not be null.

Returns:

The resulting input stream that may be used to read from the given input stream. If the data was encrypted, then the returned stream will be a PassphraseEncryptedInputStream that may be used to read decrypted data from it. If the data was not encrypted, then the original stream (possibly wrapped by a BufferedInputStream will be returned.

Throws:

java.io.IOException - If a problem is encountered while attempting to determine whether the stream contains passphrase-encrypted data.

java.security.GeneralSecurityException - If a problem is encountered while attempting to prepare to decrypt data read from the input stream, or if the stream is encrypted with a key that is not readily available.

getPossiblyPassphraseEncryptedInputStream

@NotNull
public static ObjectPair<java.io.InputStream,java.lang.String> getPossiblyPassphraseEncryptedInputStream(@NotNull
                                                                                                                  java.io.InputStream inputStream,
                                                                                                                  @Nullable
                                                                                                                  java.lang.String potentialPassphrase,
                                                                                                                  boolean promptOnIncorrectPassphrase,
                                                                                                                  @NotNull
                                                                                                                  java.lang.CharSequence passphrasePrompt,
                                                                                                                  @NotNull
                                                                                                                  java.lang.CharSequence incorrectPassphraseError,
                                                                                                                  @NotNull
                                                                                                                  java.io.PrintStream standardOutput,
                                                                                                                  @NotNull
                                                                                                                  java.io.PrintStream standardError)
                                                                                                           throws java.io.IOException,
                                                                                                                  java.security.InvalidKeyException,
                                                                                                                  java.security.GeneralSecurityException

Retrieves an InputStream that can be used to read data from the provided input stream that may have potentially been encrypted with a PassphraseEncryptedOutputStream. If the provided input stream does not appear to contain passphrase-encrypted data, then the returned stream will permit reading the data from the provided stream without any alteration.

The determination will be made by looking to see if the input stream starts with a valid PassphraseEncryptedStreamHeader. Because of the complex nature of that header, it is highly unlikely that the input stream will just happen to start with a valid header if the stream does not actually contain encrypted data.

The input stream's mark and reset methods will be used to permit peeking at the data at the head of the input stream. If the provided stream does not support the use of those methods, then it will be wrapped in a BufferedInputStream, which does support them.

Parameters:

inputStream - The input stream from which the data is to be read. It must not be null.

potentialPassphrase - A potential passphrase that may have been used to encrypt the data. It may be null if the passphrase should only be obtained via interactive prompting, or if the data was encrypted with a server-side encryption settings definition. If the passphrase is not null but is incorrect, then the user may be interactively prompted for the correct passphrase.

promptOnIncorrectPassphrase - Indicates whether the user should be interactively prompted for the correct passphrase if the provided passphrase is non-null and is also incorrect.

passphrasePrompt - The prompt that will be presented to the user if the input stream does contain encrypted data and the passphrase needs to be interactively requested from the user. It must not be null or empty.

incorrectPassphraseError - The error message that will be presented to the user if the entered passphrase is not correct. It must not be null or empty.

standardOutput - The PrintStream to use to write to standard output while interactively prompting for the passphrase. It must not be null.

standardError - The PrintStream to use to write to standard error while interactively prompting for the passphrase. It must not be null.

Returns:

An ObjectPair that combines the resulting input stream with the associated encryption passphrase. If the provided input stream is encrypted, then the returned input stream element will be a PassphraseEncryptedInputStream and the returned passphrase element will be non-null. If the provided input stream is not encrypted, then the returned input stream element will be the provided input stream (potentially wrapped in a BufferedInputStream), and the returned passphrase element will be null.

Throws:

java.io.IOException - If a problem is encountered while attempting to determine whether the stream contains passphrase-encrypted data.

java.security.InvalidKeyException - If the provided passphrase is incorrect and the user should not be interactively prompted for the correct passphrase.

java.security.GeneralSecurityException - If a problem is encountered while attempting to prepare to decrypt data read from the input stream.

getPossiblyPassphraseEncryptedInputStream

@NotNull
public static ObjectPair<java.io.InputStream,char[]> getPossiblyPassphraseEncryptedInputStream(@NotNull
                                                                                                        java.io.InputStream inputStream,
                                                                                                        @Nullable
                                                                                                        char[] potentialPassphrase,
                                                                                                        boolean promptOnIncorrectPassphrase,
                                                                                                        @NotNull
                                                                                                        java.lang.CharSequence passphrasePrompt,
                                                                                                        @NotNull
                                                                                                        java.lang.CharSequence incorrectPassphraseError,
                                                                                                        @NotNull
                                                                                                        java.io.PrintStream standardOutput,
                                                                                                        @NotNull
                                                                                                        java.io.PrintStream standardError)
                                                                                                 throws java.io.IOException,
                                                                                                        java.security.InvalidKeyException,
                                                                                                        java.security.GeneralSecurityException

Retrieves an InputStream that can be used to read data from the provided input stream that may have potentially been encrypted with a PassphraseEncryptedOutputStream. If the provided input stream does not appear to contain passphrase-encrypted data, then the returned stream will permit reading the data from the provided stream without any alteration.

The determination will be made by looking to see if the input stream starts with a valid PassphraseEncryptedStreamHeader. Because of the complex nature of that header, it is highly unlikely that the input stream will just happen to start with a valid header if the stream does not actually contain encrypted data.

The input stream's mark and reset methods will be used to permit peeking at the data at the head of the input stream. If the provided stream does not support the use of those methods, then it will be wrapped in a BufferedInputStream, which does support them.

Parameters:

inputStream - The input stream from which the data is to be read. It must not be null.

potentialPassphrase - A potential passphrase that may have been used to encrypt the data. It may be null if the passphrase should only be obtained via interactive prompting, or if the data was encrypted with a server-side encryption settings definition. If the passphrase is not null but is incorrect, then the user may be interactively prompted for the correct passphrase.

promptOnIncorrectPassphrase - Indicates whether the user should be interactively prompted for the correct passphrase if the provided passphrase is non-null and is also incorrect.

passphrasePrompt - The prompt that will be presented to the user if the input stream does contain encrypted data and the passphrase needs to be interactively requested from the user. It must not be null or empty.

incorrectPassphraseError - The error message that will be presented to the user if the entered passphrase is not correct. It must not be null or empty.

standardOutput - The PrintStream to use to write to standard output while interactively prompting for the passphrase. It must not be null.

standardError - The PrintStream to use to write to standard error while interactively prompting for the passphrase. It must not be null.

Returns:

An ObjectPair that combines the resulting input stream with the associated encryption passphrase. If the provided input stream is encrypted, then the returned input stream element will be a PassphraseEncryptedInputStream and the returned passphrase element will be non-null. If the provided input stream is not encrypted, then the returned input stream element will be the provided input stream (potentially wrapped in a BufferedInputStream), and the returned passphrase element will be null.

Throws:

java.io.IOException - If a problem is encountered while attempting to determine whether the stream contains passphrase-encrypted data.

java.security.InvalidKeyException - If the provided passphrase is incorrect and the user should not be interactively prompted for the correct passphrase.

java.security.GeneralSecurityException - If a problem is encountered while attempting to prepare to decrypt data read from the input stream.

getPossiblyPassphraseEncryptedInputStream

@NotNull
public static ObjectPair<java.io.InputStream,char[]> getPossiblyPassphraseEncryptedInputStream(@NotNull
                                                                                                        java.io.InputStream inputStream,
                                                                                                        @Nullable
                                                                                                        java.util.Collection<char[]> potentialPassphrases,
                                                                                                        boolean promptOnIncorrectPassphrase,
                                                                                                        @NotNull
                                                                                                        java.lang.CharSequence passphrasePrompt,
                                                                                                        @NotNull
                                                                                                        java.lang.CharSequence incorrectPassphraseError,
                                                                                                        @NotNull
                                                                                                        java.io.PrintStream standardOutput,
                                                                                                        @NotNull
                                                                                                        java.io.PrintStream standardError)
                                                                                                 throws java.io.IOException,
                                                                                                        java.security.InvalidKeyException,
                                                                                                        java.security.GeneralSecurityException

Retrieves an InputStream that can be used to read data from the provided input stream that may have potentially been encrypted with a PassphraseEncryptedOutputStream. If the provided input stream does not appear to contain passphrase-encrypted data, then the returned stream will permit reading the data from the provided stream without any alteration.

The determination will be made by looking to see if the input stream starts with a valid PassphraseEncryptedStreamHeader. Because of the complex nature of that header, it is highly unlikely that the input stream will just happen to start with a valid header if the stream does not actually contain encrypted data.

The input stream's mark and reset methods will be used to permit peeking at the data at the head of the input stream. If the provided stream does not support the use of those methods, then it will be wrapped in a BufferedInputStream, which does support them.

Parameters:

inputStream - The input stream from which the data is to be read. It must not be null.

potentialPassphrases - A collection of potential passphrases that may have been used to encrypt the data. It may be null or empty if the passphrase should only be obtained via interactive prompting, or if the data was encrypted with a server-side encryption settings definition. If none of the provided passphrases are correct, then the user may still be interactively prompted for the correct passphrase based on the value of the promptOnIncorrectPassphrase argument.

promptOnIncorrectPassphrase - Indicates whether the user should be interactively prompted for the correct passphrase if the set of potential passphrases is non-null and non-empty, but none of the passphrases were correct.

passphrasePrompt - The prompt that will be presented to the user if the input stream does contain encrypted data and the passphrase needs to be interactively requested from the user. It must not be null or empty.

incorrectPassphraseError - The error message that will be presented to the user if the entered passphrase is not correct. It must not be null or empty.

standardOutput - The PrintStream to use to write to standard output while interactively prompting for the passphrase. It must not be null.

standardError - The PrintStream to use to write to standard error while interactively prompting for the passphrase. It must not be null.

Returns:

An ObjectPair that combines the resulting input stream with the associated encryption passphrase. If the provided input stream is encrypted, then the returned input stream element will be a PassphraseEncryptedInputStream and the returned passphrase element will be non-null. If the provided input stream is not encrypted, then the returned input stream element will be the provided input stream (potentially wrapped in a BufferedInputStream), and the returned passphrase element will be null.

Throws:

java.io.IOException - If a problem is encountered while attempting to determine whether the stream contains passphrase-encrypted data.

java.security.InvalidKeyException - If the provided passphrase is incorrect and the user should not be interactively prompted for the correct passphrase.

java.security.GeneralSecurityException - If a problem is encountered while attempting to prepare to decrypt data read from the input stream.