@ThreadSafety(level=NOT_THREADSAFE) public final class ToolUtils extends java.lang.Object
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 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.
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 ObjectPair<java.io.InputStream,char[]> |
getPossiblyPassphraseEncryptedInputStream(java.io.InputStream inputStream,
char[] passphrase,
boolean promptOnIncorrectPassphrase,
java.lang.CharSequence passphrasePrompt,
java.lang.CharSequence incorrectPassphraseError,
java.io.PrintStream out,
java.io.PrintStream err)
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 passphrase,
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.
|
public static java.lang.String readEncryptionPassphraseFromFile(java.io.File f) throws LDAPException
f
- The file from which the passphrase should be read. It must not
be null
.LDAPException
- If a problem occurs while attempting to read the
encryption passphrase.public static java.lang.String promptForEncryptionPassphrase(boolean allowEmpty, boolean confirm, java.io.PrintStream out, java.io.PrintStream err) throws LDAPException
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
.LDAPException
- If a problem is encountered while trying to obtain
the passphrase from the user.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
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
.LDAPException
- If a problem is encountered while trying to obtain
the passphrase from the user.public static void wrap(java.lang.CharSequence message, java.io.PrintStream out)
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.public static void wrapPrompt(java.lang.CharSequence prompt, boolean ensureTrailingSpace, java.io.PrintStream out)
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
.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
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
.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.java.io.IOException
- If a problem is encountered while attempting to get
the input stream for reading the data.public static java.io.InputStream getPossiblyGZIPCompressedInputStream(java.io.InputStream inputStream) throws java.io.IOException
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.
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.inputStream
- The input stream from which the data is to be read.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.java.io.IOException
- If a problem is encountered while attempting to
determine whether the stream contains GZIP-compressed
data.public static ObjectPair<java.io.InputStream,java.lang.String> getPossiblyPassphraseEncryptedInputStream(java.io.InputStream inputStream, java.lang.String passphrase, 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
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.
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.
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.inputStream
- The input stream from which the data
is to be read. It must not be
null
.passphrase
- The passphrase to use to generate the
encryption key. It may be
null
if the passphrase should
only be obtained via interactive
prompting. 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
.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
.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.public static ObjectPair<java.io.InputStream,char[]> getPossiblyPassphraseEncryptedInputStream(java.io.InputStream inputStream, char[] passphrase, boolean promptOnIncorrectPassphrase, java.lang.CharSequence passphrasePrompt, java.lang.CharSequence incorrectPassphraseError, java.io.PrintStream out, java.io.PrintStream err) throws java.io.IOException, java.security.InvalidKeyException, java.security.GeneralSecurityException
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.
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.
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.inputStream
- The input stream from which the data
is to be read. It must not be
null
.passphrase
- The passphrase to use to generate the
encryption key. It may be
null
if the passphrase should
only be obtained via interactive
prompting. 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.out
- The PrintStream
to use to
write to standard output while
interactively prompting for the
passphrase. It must not be
null
.err
- The PrintStream
to use to
write to standard error while
interactively prompting for the
passphrase. It must not be
null
.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
.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.