Class 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

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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 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,​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 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 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 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 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

        public static java.lang.String readEncryptionPassphraseFromFile​(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

        public static java.lang.String promptForEncryptionPassphrase​(boolean allowEmpty,
                                                                     boolean confirm,
                                                                     java.io.PrintStream out,
                                                                     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

        public 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)
                                                              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​(java.lang.CharSequence message,
                                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​(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.
        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

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

        public static java.io.InputStream getPossiblyGZIPCompressedInputStream​(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

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

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

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