Package com.unboundid.util
Class StaticUtils
- java.lang.Object
-
- com.unboundid.util.StaticUtils
-
@ThreadSafety(level=COMPLETELY_THREADSAFE) public final class StaticUtils extends java.lang.Object
This class provides a number of static utility functions.
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
EOL
The end-of-line marker for the platform on which the LDAP SDK is currently running.static byte[]
EOL_BYTES
A byte array containing the end-of-line marker for the platform on which the LDAP SDK is currently running.static byte[]
EOL_BYTES_CR_LF
A byte array containing the end-of-line marker that consists of a carriage return character followed by a line feed character, as used on Windows systems.static byte[]
EOL_BYTES_LF
A byte array containing the end-of-line marker that consists of just the line feed character, as used on UNIX-based systems.static java.lang.String
EOL_CR_LF
The end-of-line marker that consists of a carriage return character followed by a line feed character, as used on Windows systems.static java.lang.String
EOL_LF
The end-of-line marker that consists of just the line feed character, as used on UNIX-based systems.static byte[]
NO_BYTES
A pre-allocated byte array containing zero bytes.static char[]
NO_CHARS
A pre-allocated empty character array.static Control[]
NO_CONTROLS
A pre-allocated empty control array.static int[]
NO_INTS
A pre-allocated empty integer array.static java.lang.String[]
NO_STRINGS
A pre-allocated empty string array.static int
TERMINAL_WIDTH_COLUMNS
The width of the terminal window, in columns.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <T> boolean
arraysEqualOrderIndependent(T[] a1, T[] a2)
Indicates whether the provided arrays have the same elements, ignoring the order in which they appear.static boolean
bothNullOrEqual(java.lang.Object o1, java.lang.Object o2)
Indicates whether both of the provided objects arenull
or both are logically equal (using theequals
method).static boolean
bothNullOrEqualIgnoreCase(java.lang.String s1, java.lang.String s2)
Indicates whether both of the provided strings arenull
or both are logically equal ignoring differences in capitalization (using theequalsIgnoreCase
method).static byte[]
byteArray(int... bytes)
Creates a byte array from the provided integer values.static void
byteArrayToCode(byte[] array, java.lang.StringBuilder buffer)
Appends the Java code that may be used to create the provided byte array to the given buffer.static java.lang.String
capitalize(java.lang.String s)
Capitalizes the provided string.static java.lang.String
capitalize(java.lang.String s, boolean allWords)
Capitalizes the provided string.static java.lang.String
cleanExampleCommandLineArgument(java.lang.String s)
This method returns a form of the provided argument that is safe to use on the command line for the local platform.static java.lang.String
clearSystemProperty(java.lang.String name)
Attempts to clear the value of the specified system property.static int
computeMapCapacity(int expectedItemCount)
Computes the capacity that should be used for a map or a set with the expected number of elements, which can help avoid the need to re-hash or re-balance the map if too many items are added.static java.lang.String
concatenateStrings(java.lang.String... a)
Retrieves a single string which is a concatenation of all of the provided strings.static java.lang.String
concatenateStrings(java.lang.String beforeList, java.lang.String beforeElement, java.lang.String betweenElements, java.lang.String afterElement, java.lang.String afterList, java.lang.String... a)
Retrieves a single string which is a concatenation of all of the provided strings.static java.lang.String
concatenateStrings(java.lang.String beforeList, java.lang.String beforeElement, java.lang.String betweenElements, java.lang.String afterElement, java.lang.String afterList, java.util.List<java.lang.String> l)
Retrieves a single string which is a concatenation of all of the provided strings.static java.lang.String
concatenateStrings(java.util.List<java.lang.String> l)
Retrieves a single string which is a concatenation of all of the provided strings.static java.io.File
constructPath(java.io.File baseDirectory, java.lang.String... pathElements)
Constructs aFile
object from the provided path.static java.io.IOException
createIOExceptionWithCause(java.lang.String message, java.lang.Throwable cause)
Creates a newIOException
with a cause.static java.util.Date
decodeGeneralizedTime(java.lang.String t)
Decodes the provided string as a timestamp in generalized time format.static java.util.Date
decodeRFC3339Time(java.lang.String timestamp)
Decodes the provided string as a timestamp encoded in the ISO 8601 format described in RFC 3339.static java.util.UUID
decodeUUID(byte[] b)
Decodes the value of the provided byte array as a Java UUID.static java.lang.String
encodeGeneralizedTime(long timestamp)
Encodes the provided timestamp in generalized time format.static java.lang.String
encodeGeneralizedTime(java.util.Date d)
Encodes the provided date in generalized time format.static java.lang.String
encodeRFC3339Time(long timestamp)
Encodes the provided timestamp to the ISO 8601 format described in RFC 3339.static java.lang.String
encodeRFC3339Time(java.util.Date d)
Encodes the provided timestamp to the ISO 8601 format described in RFC 3339.static byte[]
encodeUUID(java.util.UUID uuid)
Encodes the provided UUID to a byte array containing its 128-bit representation.static byte[]
fromHex(java.lang.String hexString)
Retrieves the bytes that correspond to the provided hexadecimal string.static java.util.Set<java.net.InetAddress>
getAllLocalAddresses(NameResolver nameResolver)
Attempts to determine all addresses associated with the local system, including loopback addresses.static java.util.Set<java.net.InetAddress>
getAllLocalAddresses(NameResolver nameResolver, boolean includeLoopback)
Attempts to determine all addresses associated with the local system, optionally including loopback addresses.static java.util.Set<java.lang.String>
getAvailableCanonicalHostNames(NameResolver nameResolver, java.util.Collection<java.net.InetAddress> addresses)
Retrieves the canonical host names for the provided set ofInetAddress
objects.static java.lang.String
getBacktrace()
Retrieves a single-line string representation of the stack trace for the current thread.static byte[]
getBytes(java.lang.String s)
Retrieves a UTF-8 byte representation of the provided string.static byte[]
getBytesForCodePoint(int codePoint)
Retrieves a byte array containing the UTF-8 representation of the bytes that comprise the provided Unicode code point.static java.lang.String
getCanonicalHostNameIfAvailable(NameResolver nameResolver, java.net.InetAddress address)
Retrieves the canonical host name for the provided address, if it can be resolved to a name.static int[]
getCodePoints(java.lang.String s)
Retrieves an array of the code points that comprise the provided string.static java.lang.String
getCommandLineContinuationString()
Retrieves the string that should be appended to the end of all but the last line of a multi-line command to indicate that the command continues onto the next line.static java.lang.String
getEnvironmentVariable(java.lang.String name)
Retrieves the value of the specified environment variable.static java.lang.String
getEnvironmentVariable(java.lang.String name, java.lang.String defaultValue)
Retrieves the value of the specified environment variable.static java.util.Map<java.lang.String,java.lang.String>
getEnvironmentVariables()
Retrieves a map of all environment variables defined in the JVM's process.static java.lang.String
getExceptionMessage(java.lang.Throwable t)
Retrieves a string representation of the providedThrowable
object suitable for use in a message.static java.lang.String
getExceptionMessage(java.lang.Throwable t, boolean includeCause, boolean includeStackTrace)
Retrieves a string representation of the providedThrowable
object suitable for use in a message.static java.util.Set<java.lang.String>
getSensitiveToCodeAttributeBaseNames()
Retrieves a set containing the base names (in all lowercase characters) of any attributes that should be considered sensitive for the purposes of thetoCode
methods.static java.lang.String
getStackTrace(java.lang.StackTraceElement[] elements)
Returns a single-line string representation of the stack trace.static void
getStackTrace(java.lang.StackTraceElement[] elements, java.lang.StringBuilder buffer)
Appends a single-line string representation of the stack trace to the given buffer.static void
getStackTrace(java.lang.StackTraceElement[] elements, java.lang.StringBuilder buffer, int maxPreSDKFrames)
Appends a single-line string representation of the stack trace to the given buffer.static java.lang.String
getStackTrace(java.lang.Throwable t)
Retrieves a single-line string representation of the stack trace for the providedThrowable
.static void
getStackTrace(java.lang.Throwable t, java.lang.StringBuilder buffer)
Appends a single-line string representation of the stack trace for the providedThrowable
to the given buffer.static java.util.Properties
getSystemProperties(java.lang.String... propertyNames)
Retrieves the set of currently defined system properties.static java.lang.String
getSystemProperty(java.lang.String name)
Retrieves the value of the specified system property.static java.lang.String
getSystemProperty(java.lang.String name, java.lang.String defaultValue)
Retrieves the value of the specified system property.static java.lang.String
getUnqualifiedClassName(java.lang.Class<?> c)
Retrieves the unqualified name (i.e., the name without package information) for the provided class.static java.util.TimeZone
getUTCTimeZone()
Retrieves aTimeZone
object that represents the UTC (universal coordinated time) time zone.static <T> java.util.HashSet<T>
hashSetOf(T... items)
Creates aHashSet
containing the provided items.static void
hexEncode(char c, java.lang.StringBuilder buffer)
Appends a hex-encoded representation of the provided character to the given buffer.static void
hexEncode(int codePoint, java.lang.StringBuilder buffer)
Appends a hex-encoded representation of the provided code point to the given buffer.static boolean
isASCIIString(byte[] b)
Indicates whether the contents of the provided byte array represent an ASCII string, which is also known in LDAP terminology as an IA5 string.static boolean
isASCIIString(java.lang.String s)
Indicates whether the contents of the provided string represent an ASCII string, which is also known in LDAP terminology as an IA5 string.static boolean
isHex(char c)
Indicates whether the provided character is a valid hexadecimal digit.static boolean
isIANAReservedIPAddress(java.net.InetAddress address, boolean includePrivateUseNetworkAddresses)
Indicates whether the provided address is marked as reserved in the IANA IPv4 address space registry at https://www.iana.org/assignments/ipv4-address-space/ipv4-address-space.txt or the IPv6 address space registry at https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.txt.static boolean
isIANAReservedIPv4Address(java.net.Inet4Address address, boolean includePrivateUseNetworkAddresses)
Indicates whether the provided address is marked as reserved in the IANA IPv4 address space registry at https://www.iana.org/assignments/ipv4-address-space/ipv4-address-space.txt.static boolean
isIANAReservedIPv6Address(java.net.Inet6Address address, boolean includePrivateUseNetworkAddresses)
Indicates whether the provided address is marked as reserved in the IANA IPv6 address space registry at https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.txt.static boolean
isLikelyDisplayableCharacter(int codePoint)
Indicates whether the specified Unicode code point represents a character that is believed to be displayable.static boolean
isLikelyDisplayableString(java.lang.String s)
Indicates whether the provided string is comprised entirely of characters that are believed to be displayable (as determined by theisLikelyDisplayableCharacter(int)
method).static boolean
isLikelyDisplayableUTF8String(byte[] b)
Indicates whether the provided byte array represents a valid UTF-8 string that is comprised entirely of characters that are believed to be displayable (as determined by theisLikelyDisplayableCharacter(int)
method).static boolean
isNumericOID(java.lang.String s)
Indicates whether the provided string is a valid numeric OID.static boolean
isPrintable(char c)
Indicates whether the provided character is a printable ASCII character, as per RFC 4517 section 3.2.static boolean
isPrintableString(byte[] b)
Indicates whether the contents of the provided byte array represent a printable LDAP string, as per RFC 4517 section 3.2.static boolean
isPrintableString(java.lang.String s)
Indicates whether the provided string represents a printable LDAP string, as per RFC 4517 section 3.2.static boolean
isSensitiveToCodeAttribute(java.lang.String name)
Indicates whether the provided attribute name should be considered a sensitive attribute for the purposes oftoCode
methods.static boolean
isValidUTF8(byte[] b)
Indicates whether the contents of the provided array represent a valid UTF-8 string, which may or may not contain non-ASCII characters.static boolean
isValidUTF8WithNonASCIICharacters(byte[] b)
Indicates whether the contents of the provided array represent a valid UTF-8 string that contains at least one non-ASCII character (and may contain zero or more ASCII characters).static boolean
isWindows()
Returnstrue
if and only if the current process is running on a Windows-based operating system.static boolean
isWithinUnitTest()
Indicates whether the unit tests are currently running in this JVM.static java.lang.String
linesToString(java.lang.CharSequence... lines)
Creates a string that is a concatenation of all of the provided lines, with a line break (using the end-of-line sequence appropriate for the underlying platform) after each line (including the last line).static java.lang.String
linesToString(java.util.List<? extends java.lang.CharSequence> lines)
Creates a string that is a concatenation of all of the provided lines, with a line break (using the end-of-line sequence appropriate for the underlying platform) after each line (including the last line).static <T> java.util.LinkedHashSet<T>
linkedHashSetOf(T... items)
Creates aLinkedHashSet
containing the provided items.static <K,V>
java.util.Map<K,V>mapOf(K key, V value)
Creates an unmodifiable map containing the provided items.static <K,V>
java.util.Map<K,V>mapOf(K key1, V value1, K key2, V value2)
Creates an unmodifiable map containing the provided items.static <K,V>
java.util.Map<K,V>mapOf(K key1, V value1, K key2, V value2, K key3, V value3)
Creates an unmodifiable map containing the provided items.static <K,V>
java.util.Map<K,V>mapOf(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4)
Creates an unmodifiable map containing the provided items.static <K,V>
java.util.Map<K,V>mapOf(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4, K key5, V value5)
Creates an unmodifiable map containing the provided items.static <K,V>
java.util.Map<K,V>mapOf(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4, K key5, V value5, K key6, V value6)
Creates an unmodifiable map containing the provided items.static <K,V>
java.util.Map<K,V>mapOf(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4, K key5, V value5, K key6, V value6, K key7, V value7)
Creates an unmodifiable map containing the provided items.static <K,V>
java.util.Map<K,V>mapOf(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4, K key5, V value5, K key6, V value6, K key7, V value7, K key8, V value8)
Creates an unmodifiable map containing the provided items.static <K,V>
java.util.Map<K,V>mapOf(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4, K key5, V value5, K key6, V value6, K key7, V value7, K key8, V value8, K key9, V value9)
Creates an unmodifiable map containing the provided items.static <K,V>
java.util.Map<K,V>mapOf(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4, K key5, V value5, K key6, V value6, K key7, V value7, K key8, V value8, K key9, V value9, K key10, V value10)
Creates an unmodifiable map containing the provided items.static <T> java.util.Map<T,T>
mapOf(T... items)
Creates an unmodifiable map containing the provided items.static <K,V>
java.util.Map<K,V>mapOfObjectPairs(ObjectPair<K,V>... items)
Creates an unmodifiable map containing the provided items.static java.lang.String
millisToHumanReadableDuration(long m)
Converts a duration in seconds to a string with a human-readable duration which may include days, hours, minutes, and seconds, to the extent that they are needed.static long
millisToNanos(long millis)
Converts the provided number of milliseconds to nanoseconds.static long
nanosToMillis(long nanos)
Converts the provided number of nanoseconds to milliseconds.static int
numBytesInUTF8CharacterWithFirstByte(byte b)
Determines the number of bytes in a UTF-8 character that starts with the given byte.static java.lang.String
randomAlphabeticString(int length, boolean secure)
Retrieves a string containing the specified number of randomly selected ASCII letters.static java.lang.String
randomAlphanumericString(int length, boolean secure)
Retrieves a string containing the specified number of randomly selected ASCII alphanumeric characters.static byte[]
randomBytes(int numBytes, boolean secure)
Retrieves a byte array with the specified number of randomly selected bytes.static int
randomInt(int lowerBound, int upperBound, boolean secure)
Retrieves a randomly selected integer between the given upper and lower bounds.static java.lang.String
randomNumericString(int length, boolean secure)
Retrieves a string containing the specified number of randomly selected ASCII numeric digits.static java.lang.String
randomString(int length, char[] allowedChars, boolean secure)
Retrieves a string containing the specified number of randomly selected characters from the given set.static java.lang.String
readFileAsString(java.io.File file, boolean includeFinalLineBreak)
Reads the contents of the specified file as a string.static java.lang.String
readFileAsString(java.lang.String path, boolean includeFinalLineBreak)
Reads the contents of the specified file as a string.static byte[]
readFileBytes(java.io.File file)
Reads the bytes that comprise the specified file.static byte[]
readFileBytes(java.lang.String path)
Reads the bytes that comprise the specified file.static java.util.List<java.lang.String>
readFileLines(java.io.File file)
Reads the lines that comprise the specified file.static java.util.List<java.lang.String>
readFileLines(java.lang.String path)
Reads the lines that comprise the specified file.static void
rethrowIfError(java.lang.Throwable throwable)
Re-throws the providedThrowable
instance only if it is anError
; otherwise, this method will return without taking any action.static void
rethrowIfErrorOrRuntimeException(java.lang.Throwable throwable)
Re-throws the providedThrowable
instance only if it is anError
or aRuntimeException
instance; otherwise, this method will return without taking any action.static java.lang.String
secondsToHumanReadableDuration(long s)
Converts a duration in seconds to a string with a human-readable duration which may include days, hours, minutes, and seconds, to the extent that they are needed.static void
setLoggerLevel(java.util.logging.Logger logger, java.util.logging.Level logLevel)
Attempts to set the desired log level for the specified logger.static void
setLogHandlerLevel(java.util.logging.Handler logHandler, java.util.logging.Level logLevel)
Attempts to set the desired log level for the specified log handler.static <T> java.util.Set<T>
setOf(T... items)
Creates an unmodifiable set containing the provided items.static void
setSensitiveToCodeAttributes(java.lang.String... names)
Specifies the names of any attributes that should be considered sensitive for the purposes of thetoCode
methods.static void
setSensitiveToCodeAttributes(java.util.Collection<java.lang.String> names)
Specifies the names of any attributes that should be considered sensitive for the purposes of thetoCode
methods.static java.lang.String
setSystemProperty(java.lang.String name, java.lang.String value)
Attempts to set the value of the specified system property.static java.lang.String
setSystemPropertyIfNotAlreadyDefined(java.lang.String name, java.lang.String value)
Attempts to set the value of the specified system property, but only if the specified property does not already have a value.static boolean
stringsEqualIgnoreCaseOrderIndependent(java.lang.String[] a1, java.lang.String[] a2)
Indicates whether the provided string arrays have the same elements, ignoring the order in which they appear and differences in capitalization.static java.util.List<java.lang.String>
stringToLines(java.lang.String s)
Converts the provided string (which may include line breaks) into a list containing the lines without the line breaks.static void
throwErrorOrRuntimeException(java.lang.Throwable throwable)
Throws anError
or aRuntimeException
based on the providedThrowable
object.static java.util.List<java.lang.String>
toArgumentList(java.lang.String s)
Attempts to parse the contents of the provided string to an argument list (e.g., converts something like "--arg1 arg1value --arg2 --arg3 arg3value" to a list of "--arg1", "arg1value", "--arg2", "--arg3", "arg3value").static <T> T[]
toArray(java.util.Collection<T> collection, java.lang.Class<T> type)
Retrieves an array containing the elements of the provided collection.static java.lang.String
toHex(byte b)
Retrieves a hexadecimal representation of the provided byte.static java.lang.String
toHex(byte[] b)
Retrieves a hexadecimal representation of the contents of the provided byte array.static void
toHex(byte[] b, java.lang.StringBuilder buffer)
Retrieves a hexadecimal representation of the contents of the provided byte array.static void
toHex(byte[] b, java.lang.String delimiter, java.lang.StringBuilder buffer)
Retrieves a hexadecimal representation of the contents of the provided byte array.static void
toHex(byte b, ByteStringBuffer buffer)
Appends a hexadecimal representation of the provided byte to the given buffer.static void
toHex(byte b, java.lang.StringBuilder buffer)
Appends a hexadecimal representation of the provided byte to the given buffer.static java.lang.String
toHexPlusASCII(byte[] array, int indent)
Retrieves a hex-encoded representation of the contents of the provided array, along with an ASCII representation of its contents next to it.static void
toHexPlusASCII(byte[] array, int indent, java.lang.StringBuilder buffer)
Appends a hex-encoded representation of the contents of the provided array to the given buffer, along with an ASCII representation of its contents next to it.static java.lang.String
toInitialLowerCase(java.lang.String s)
Retrieves a version of the provided string with the first character converted to lowercase but all other characters retaining their original capitalization.static <T> java.util.List<T>
toList(T[] array)
Creates a modifiable list with all of the items of the provided array in the same order.static java.lang.String
toLowerCase(java.lang.String s)
Retrieves an all-lowercase version of the provided string.static <T> java.util.List<T>
toNonNullList(T[] array)
Creates a modifiable list with all of the items of the provided array in the same order.static java.lang.String
toUpperCase(java.lang.String s)
Retrieves an all-uppercase version of the provided string.static java.lang.String
toUTF8String(byte[] b)
Retrieves a string generated from the provided byte array using the UTF-8 encoding.static java.lang.String
toUTF8String(byte[] b, int offset, int length)
Retrieves a string generated from the specified portion of the provided byte array using the UTF-8 encoding.static <T> java.util.TreeSet<T>
treeSetOf(T... items)
Creates aTreeSet
containing the provided items.static java.lang.String
trimInterfaceNameFromHostAddress(java.lang.String hostAddress)
Retrieves a version of the provided host address with the interface name stripped off.static java.lang.String
trimLeading(java.lang.String s)
Trims only leading spaces from the provided string, leaving any trailing spaces intact.static java.lang.String
trimTrailing(java.lang.String s)
Trims only trailing spaces from the provided string, leaving any leading spaces intact.static boolean
unicodeStringsAreEquivalent(java.lang.String s1, java.lang.String s2)
Indicates whether the provided strings represent an equivalent sequence of Unicode characters.static boolean
utf8StringsAreEquivalent(byte[] b1, byte[] b2)
Indicates whether the provided byte arrays represent UTF-8 strings that have an equivalent sequence of Unicode characters.static java.util.List<java.lang.String>
wrapLine(java.lang.String line, int maxWidth)
Wraps the contents of the specified line using the given width.static java.util.List<java.lang.String>
wrapLine(java.lang.String line, int maxFirstLineWidth, int maxSubsequentLineWidth)
Wraps the contents of the specified line using the given width.static void
writeFile(java.io.File file, byte[] bytes)
Writes the provided bytes to the specified file.static void
writeFile(java.io.File file, java.lang.CharSequence... lines)
Writes the provided lines to the specified file, with each followed by an appropriate end-of-line marker for the current platform.static void
writeFile(java.io.File file, java.util.List<? extends java.lang.CharSequence> lines)
Writes the provided lines to the specified file, with each followed by an appropriate end-of-line marker for the current platform.static void
writeFile(java.lang.String path, byte[] bytes)
Writes the provided bytes to the specified file.static void
writeFile(java.lang.String path, java.lang.CharSequence... lines)
Writes the provided lines to the specified file, with each followed by an appropriate end-of-line marker for the current platform.static void
writeFile(java.lang.String path, java.util.List<? extends java.lang.CharSequence> lines)
Writes the provided lines to the specified file, with each followed by an appropriate end-of-line marker for the current platform.
-
-
-
Field Detail
-
NO_BYTES
@NotNull public static final byte[] NO_BYTES
A pre-allocated byte array containing zero bytes.
-
NO_CONTROLS
@NotNull public static final Control[] NO_CONTROLS
A pre-allocated empty control array.
-
NO_STRINGS
@NotNull public static final java.lang.String[] NO_STRINGS
A pre-allocated empty string array.
-
EOL
@NotNull public static final java.lang.String EOL
The end-of-line marker for the platform on which the LDAP SDK is currently running.
-
EOL_CR_LF
@NotNull public static final java.lang.String EOL_CR_LF
The end-of-line marker that consists of a carriage return character followed by a line feed character, as used on Windows systems.- See Also:
- Constant Field Values
-
EOL_LF
@NotNull public static final java.lang.String EOL_LF
The end-of-line marker that consists of just the line feed character, as used on UNIX-based systems.- See Also:
- Constant Field Values
-
EOL_BYTES
@NotNull public static final byte[] EOL_BYTES
A byte array containing the end-of-line marker for the platform on which the LDAP SDK is currently running.
-
EOL_BYTES_CR_LF
@NotNull public static final byte[] EOL_BYTES_CR_LF
A byte array containing the end-of-line marker that consists of a carriage return character followed by a line feed character, as used on Windows systems.
-
EOL_BYTES_LF
@NotNull public static final byte[] EOL_BYTES_LF
A byte array containing the end-of-line marker that consists of just the line feed character, as used on UNIX-based systems.
-
TERMINAL_WIDTH_COLUMNS
public static final int TERMINAL_WIDTH_COLUMNS
The width of the terminal window, in columns.
-
-
Method Detail
-
getSystemProperties
@NotNull public static java.util.Properties getSystemProperties(@Nullable java.lang.String... propertyNames)
Retrieves the set of currently defined system properties. If possible, this will simply return the result of a call toSystem.getProperties
. However, the LDAP SDK is known to be used in environments where a security manager prevents setting system properties, and in that case, calls toSystem.getProperties
will be rejected with aSecurityException
because the returned structure is mutable and could be used to alter system property values. In such cases, a new emptyProperties
object will be created, and may optionally be populated with the values of a specific set of named properties.- Parameters:
propertyNames
- An optional set of property names whose values (if defined) should be included in theProperties
object that will be returned if a security manager prevents retrieving the full set of system properties. This may benull
or empty if no specific properties should be retrieved.- Returns:
- The value returned by a call to
System.getProperties
if possible, or a newly-created properties map (possibly including the values of a specified set of system properties) if it is not possible to get a mutable set of the system properties.
-
getSystemProperty
@Nullable public static java.lang.String getSystemProperty(@NotNull java.lang.String name)
Retrieves the value of the specified system property.- Parameters:
name
- The name of the system property for which to retrieve the value.- Returns:
- The value of the requested system property, or
null
if that variable was not set or its value could not be retrieved (for example, because a security manager prevents it).
-
getSystemProperty
@Nullable public static java.lang.String getSystemProperty(@NotNull java.lang.String name, @Nullable java.lang.String defaultValue)
Retrieves the value of the specified system property.- Parameters:
name
- The name of the system property for which to retrieve the value.defaultValue
- The default value to return if the specified system property is not set or could not be retrieved.- Returns:
- The value of the requested system property, or the provided default value if that system property was not set or its value could not be retrieved (for example, because a security manager prevents it).
-
setSystemProperty
@Nullable public static java.lang.String setSystemProperty(@NotNull java.lang.String name, @Nullable java.lang.String value)
Attempts to set the value of the specified system property. Note that this may not be permitted by some security managers, in which case the attempt will have no effect.- Parameters:
name
- The name of the system property to set. It must not benull
.value
- The value to use for the system property. If it isnull
, then the property will be cleared.- Returns:
- The former value of the system property, or
null
if it did not have a value or if it could not be set (for example, because a security manager prevents it).
-
setSystemPropertyIfNotAlreadyDefined
@NotNull public static java.lang.String setSystemPropertyIfNotAlreadyDefined(@NotNull java.lang.String name, @NotNull java.lang.String value)
Attempts to set the value of the specified system property, but only if the specified property does not already have a value. If the specified property is already set, then it will remain set to its current value.- Parameters:
name
- The name of the system property to set. It must not benull
.value
- The value to use for the system property if it is not already set. It must not benull
.- Returns:
- The existing value for the system property, if it was previously
defined, or
null
if it did not already have a value.
-
clearSystemProperty
@Nullable public static java.lang.String clearSystemProperty(@NotNull java.lang.String name)
Attempts to clear the value of the specified system property. Note that this may not be permitted by some security managers, in which case the attempt will have no effect.- Parameters:
name
- The name of the System property to clear. It must not benull
.- Returns:
- The former value of the system property, or
null
if it did not have a value or if it could not be set (for example, because a security manager prevents it).
-
getEnvironmentVariables
@NotNull public static java.util.Map<java.lang.String,java.lang.String> getEnvironmentVariables()
Retrieves a map of all environment variables defined in the JVM's process.- Returns:
- A map of all environment variables defined in the JVM's process, or an empty map if no environment variables are set or the actual set could not be retrieved (for example, because a security manager prevents it).
-
getEnvironmentVariable
@Nullable public static java.lang.String getEnvironmentVariable(@NotNull java.lang.String name)
Retrieves the value of the specified environment variable.- Parameters:
name
- The name of the environment variable for which to retrieve the value.- Returns:
- The value of the requested environment variable, or
null
if that variable was not set or its value could not be retrieved (for example, because a security manager prevents it).
-
getEnvironmentVariable
@Nullable public static java.lang.String getEnvironmentVariable(@NotNull java.lang.String name, @Nullable java.lang.String defaultValue)
Retrieves the value of the specified environment variable.- Parameters:
name
- The name of the environment variable for which to retrieve the value.defaultValue
- The default value to use if the specified environment variable is not set. It may benull
if no default should be used.- Returns:
- The value of the requested environment variable, or
null
if that variable was not set or its value could not be retrieved (for example, because a security manager prevents it) and there is no default value.
-
setLoggerLevel
public static void setLoggerLevel(@NotNull java.util.logging.Logger logger, @NotNull java.util.logging.Level logLevel)
Attempts to set the desired log level for the specified logger. Note that this may not be permitted by some security managers, in which case the attempt will have no effect.- Parameters:
logger
- The logger whose level should be updated.logLevel
- The log level to set for the logger.
-
setLogHandlerLevel
public static void setLogHandlerLevel(@NotNull java.util.logging.Handler logHandler, @NotNull java.util.logging.Level logLevel)
Attempts to set the desired log level for the specified log handler. Note that this may not be permitted by some security managers, in which case the attempt will have no effect.- Parameters:
logHandler
- The log handler whose level should be updated.logLevel
- The log level to set for the log handler.
-
getBytes
@NotNull public static byte[] getBytes(@Nullable java.lang.String s)
Retrieves a UTF-8 byte representation of the provided string.- Parameters:
s
- The string for which to retrieve the UTF-8 byte representation.- Returns:
- The UTF-8 byte representation for the provided string.
-
getBytesForCodePoint
@NotNull public static byte[] getBytesForCodePoint(int codePoint)
Retrieves a byte array containing the UTF-8 representation of the bytes that comprise the provided Unicode code point.- Parameters:
codePoint
- The code point for which to retrieve the UTF-8 bytes.- Returns:
- A byte array containing the UTF-8 representation of the bytes that comprise the provided Unicode code point.
-
isASCIIString
public static boolean isASCIIString(@NotNull byte[] b)
Indicates whether the contents of the provided byte array represent an ASCII string, which is also known in LDAP terminology as an IA5 string. An ASCII string is one that contains only bytes in which the most significant bit is zero.- Parameters:
b
- The byte array for which to make the determination. It must not benull
.- Returns:
true
if the contents of the provided array represent an ASCII string, orfalse
if not.
-
isASCIIString
public static boolean isASCIIString(@NotNull java.lang.String s)
Indicates whether the contents of the provided string represent an ASCII string, which is also known in LDAP terminology as an IA5 string. An ASCII string is one that contains only bytes in which the most significant bit is zero.- Parameters:
s
- The string for which to make the determination. It must not benull
.- Returns:
true
if the contents of the provided string represent an ASCII string, orfalse
if not.
-
isPrintable
public static boolean isPrintable(char c)
Indicates whether the provided character is a printable ASCII character, as per RFC 4517 section 3.2. The only printable characters are:- All uppercase and lowercase ASCII alphabetic letters
- All ASCII numeric digits
- The following additional ASCII characters: single quote, left parenthesis, right parenthesis, plus, comma, hyphen, period, equals, forward slash, colon, question mark, space.
- Parameters:
c
- The character for which to make the determination.- Returns:
true
if the provided character is a printable ASCII character, orfalse
if not.
-
isPrintableString
public static boolean isPrintableString(@NotNull byte[] b)
Indicates whether the contents of the provided byte array represent a printable LDAP string, as per RFC 4517 section 3.2. The only characters allowed in a printable string are:- All uppercase and lowercase ASCII alphabetic letters
- All ASCII numeric digits
- The following additional ASCII characters: single quote, left parenthesis, right parenthesis, plus, comma, hyphen, period, equals, forward slash, colon, question mark, space.
- Parameters:
b
- The byte array for which to make the determination. It must not benull
.- Returns:
true
if the contents of the provided byte array represent a printable LDAP string, orfalse
if not.
-
isPrintableString
public static boolean isPrintableString(@NotNull java.lang.String s)
Indicates whether the provided string represents a printable LDAP string, as per RFC 4517 section 3.2. The only characters allowed in a printable string are:- All uppercase and lowercase ASCII alphabetic letters
- All ASCII numeric digits
- The following additional ASCII characters: single quote, left parenthesis, right parenthesis, plus, comma, hyphen, period, equals, forward slash, colon, question mark, space.
- Parameters:
s
- The string for which to make the determination. It must not benull
.- Returns:
true
if the provided string represents a printable LDAP string, orfalse
if not.
-
isLikelyDisplayableCharacter
public static boolean isLikelyDisplayableCharacter(int codePoint)
Indicates whether the specified Unicode code point represents a character that is believed to be displayable. Displayable characters include letters, numbers, spaces, dashes, punctuation, symbols, and marks. Non-displayable characters include control characters, directionality indicators, like and paragraph separators, format characters, and surrogate characters.- Parameters:
codePoint
- The code point for which to make the determination.- Returns:
true
if the specified Unicode character is believed to be displayable, orfalse
if not.
-
isLikelyDisplayableUTF8String
public static boolean isLikelyDisplayableUTF8String(@NotNull byte[] b)
Indicates whether the provided byte array represents a valid UTF-8 string that is comprised entirely of characters that are believed to be displayable (as determined by theisLikelyDisplayableCharacter(int)
method).- Parameters:
b
- The byte array for which to make the determination. It must not benull
.- Returns:
true
if the provided byte array represents a valid UTF-8 string that is believed to be displayable, orfalse
if not.
-
isLikelyDisplayableString
public static boolean isLikelyDisplayableString(@NotNull java.lang.String s)
Indicates whether the provided string is comprised entirely of characters that are believed to be displayable (as determined by theisLikelyDisplayableCharacter(int)
method).- Parameters:
s
- The string for which to make the determination. It must not benull
.- Returns:
true
if the provided string is believed to be displayable, orfalse
if not.
-
getCodePoints
@NotNull public static int[] getCodePoints(@NotNull java.lang.String s)
Retrieves an array of the code points that comprise the provided string.- Parameters:
s
- The string for which to obtain the code points. It must not benull
.- Returns:
- An array of the code points that comprise the provided string.
-
isValidUTF8
public static boolean isValidUTF8(@NotNull byte[] b)
Indicates whether the contents of the provided array represent a valid UTF-8 string, which may or may not contain non-ASCII characters. Note that this method does not make any attempt to determine whether the characters in the UTF-8 string actually map to assigned Unicode code points.- Parameters:
b
- The byte array to examine. It must not benull
.- Returns:
true
if the byte array can be parsed as a valid UTF-8 string, orfalse
if not.
-
isValidUTF8WithNonASCIICharacters
public static boolean isValidUTF8WithNonASCIICharacters(@NotNull byte[] b)
Indicates whether the contents of the provided array represent a valid UTF-8 string that contains at least one non-ASCII character (and may contain zero or more ASCII characters). Note that this method does not make any attempt to determine whether the characters in the UTF-8 string actually map to assigned Unicode code points.- Parameters:
b
- The byte array to examine. It must not benull
.- Returns:
true
if the byte array can be parsed as a valid UTF-8 string and contains at least one non-ASCII character, orfalse
if not.
-
toUTF8String
@NotNull public static java.lang.String toUTF8String(@NotNull byte[] b)
Retrieves a string generated from the provided byte array using the UTF-8 encoding.- Parameters:
b
- The byte array for which to return the associated string.- Returns:
- The string generated from the provided byte array using the UTF-8 encoding.
-
toUTF8String
@NotNull public static java.lang.String toUTF8String(@NotNull byte[] b, int offset, int length)
Retrieves a string generated from the specified portion of the provided byte array using the UTF-8 encoding.- Parameters:
b
- The byte array for which to return the associated string.offset
- The offset in the array at which the value begins.length
- The number of bytes in the value to convert to a string.- Returns:
- The string generated from the specified portion of the provided byte array using the UTF-8 encoding.
-
unicodeStringsAreEquivalent
public static boolean unicodeStringsAreEquivalent(@NotNull java.lang.String s1, @NotNull java.lang.String s2)
Indicates whether the provided strings represent an equivalent sequence of Unicode characters. In some cases, Unicode supports multiple ways of encoding the same character or sequence of characters, and this method accounts for those alternative encodings in the course of making the determination.- Parameters:
s1
- The first string for which to make the determination. It must not benull
.s2
- The second string for which to make the determination. It must not benull
.- Returns:
true
if the provided strings represent an equivalent sequence of Unicode characters, orfalse
if not.
-
utf8StringsAreEquivalent
public static boolean utf8StringsAreEquivalent(@NotNull byte[] b1, @NotNull byte[] b2)
Indicates whether the provided byte arrays represent UTF-8 strings that have an equivalent sequence of Unicode characters. In some cases, Unicode supports multiple ways of encoding the same character or sequence of characters, and this method accounts for those alternative encodings in the course of making the determination.- Parameters:
b1
- The bytes that comprise the UTF-8 representation of the first string for which to make the determination. It must not benull
.b2
- The bytes that comprise the UTF-8 representation of the second string for which to make the determination. It must not benull
.- Returns:
true
if the provided byte arrays represent UTF-8 strings that have an equivalent sequence of Unicode characters, orfalse
if not.
-
toInitialLowerCase
@Nullable public static java.lang.String toInitialLowerCase(@Nullable java.lang.String s)
Retrieves a version of the provided string with the first character converted to lowercase but all other characters retaining their original capitalization.- Parameters:
s
- The string to be processed.- Returns:
- A version of the provided string with the first character
converted to lowercase but all other characters retaining their
original capitalization. It may be
null
if the provided string isnull
.
-
toLowerCase
@Nullable public static java.lang.String toLowerCase(@Nullable java.lang.String s)
Retrieves an all-lowercase version of the provided string.- Parameters:
s
- The string for which to retrieve the lowercase version.- Returns:
- An all-lowercase version of the provided string, or
null
if the provided string wasnull
.
-
toUpperCase
@Nullable public static java.lang.String toUpperCase(@Nullable java.lang.String s)
Retrieves an all-uppercase version of the provided string.- Parameters:
s
- The string for which to retrieve the uppercase version.- Returns:
- An all-uppercase version of the provided string, or
null
if the provided string wasnull
.
-
isHex
public static boolean isHex(char c)
Indicates whether the provided character is a valid hexadecimal digit.- Parameters:
c
- The character for which to make the determination.- Returns:
true
if the provided character does represent a valid hexadecimal digit, orfalse
if not.
-
toHex
@NotNull public static java.lang.String toHex(byte b)
Retrieves a hexadecimal representation of the provided byte.- Parameters:
b
- The byte to encode as hexadecimal.- Returns:
- A string containing the hexadecimal representation of the provided byte.
-
toHex
public static void toHex(byte b, @NotNull java.lang.StringBuilder buffer)
Appends a hexadecimal representation of the provided byte to the given buffer.- Parameters:
b
- The byte to encode as hexadecimal.buffer
- The buffer to which the hexadecimal representation is to be appended.
-
toHex
public static void toHex(byte b, @NotNull ByteStringBuffer buffer)
Appends a hexadecimal representation of the provided byte to the given buffer.- Parameters:
b
- The byte to encode as hexadecimal.buffer
- The buffer to which the hexadecimal representation is to be appended.
-
toHex
@NotNull public static java.lang.String toHex(@NotNull byte[] b)
Retrieves a hexadecimal representation of the contents of the provided byte array. No delimiter character will be inserted between the hexadecimal digits for each byte.- Parameters:
b
- The byte array to be represented as a hexadecimal string. It must not benull
.- Returns:
- A string containing a hexadecimal representation of the contents of the provided byte array.
-
toHex
public static void toHex(@NotNull byte[] b, @NotNull java.lang.StringBuilder buffer)
Retrieves a hexadecimal representation of the contents of the provided byte array. No delimiter character will be inserted between the hexadecimal digits for each byte.- Parameters:
b
- The byte array to be represented as a hexadecimal string. It must not benull
.buffer
- A buffer to which the hexadecimal representation of the contents of the provided byte array should be appended.
-
toHex
public static void toHex(@NotNull byte[] b, @Nullable java.lang.String delimiter, @NotNull java.lang.StringBuilder buffer)
Retrieves a hexadecimal representation of the contents of the provided byte array. No delimiter character will be inserted between the hexadecimal digits for each byte.- Parameters:
b
- The byte array to be represented as a hexadecimal string. It must not benull
.delimiter
- A delimiter to be inserted between bytes. It may benull
if no delimiter should be used.buffer
- A buffer to which the hexadecimal representation of the contents of the provided byte array should be appended.
-
toHexPlusASCII
@NotNull public static java.lang.String toHexPlusASCII(@NotNull byte[] array, int indent)
Retrieves a hex-encoded representation of the contents of the provided array, along with an ASCII representation of its contents next to it. The output will be split across multiple lines, with up to sixteen bytes per line. For each of those sixteen bytes, the two-digit hex representation will be appended followed by a space. Then, the ASCII representation of those sixteen bytes will follow that, with a space used in place of any byte that does not have an ASCII representation.- Parameters:
array
- The array whose contents should be processed.indent
- The number of spaces to insert on each line prior to the first hex byte.- Returns:
- A hex-encoded representation of the contents of the provided array, along with an ASCII representation of its contents next to it.
-
toHexPlusASCII
public static void toHexPlusASCII(@Nullable byte[] array, int indent, @NotNull java.lang.StringBuilder buffer)
Appends a hex-encoded representation of the contents of the provided array to the given buffer, along with an ASCII representation of its contents next to it. The output will be split across multiple lines, with up to sixteen bytes per line. For each of those sixteen bytes, the two-digit hex representation will be appended followed by a space. Then, the ASCII representation of those sixteen bytes will follow that, with a space used in place of any byte that does not have an ASCII representation.- Parameters:
array
- The array whose contents should be processed.indent
- The number of spaces to insert on each line prior to the first hex byte.buffer
- The buffer to which the encoded data should be appended.
-
fromHex
@NotNull public static byte[] fromHex(@NotNull java.lang.String hexString) throws java.text.ParseException
Retrieves the bytes that correspond to the provided hexadecimal string.- Parameters:
hexString
- The hexadecimal string for which to retrieve the bytes. It must not benull
, and there must not be any delimiter between bytes.- Returns:
- The bytes that correspond to the provided hexadecimal string.
- Throws:
java.text.ParseException
- If the provided string does not represent valid hexadecimal data, or if the provided string does not contain an even number of characters.
-
hexEncode
public static void hexEncode(char c, @NotNull java.lang.StringBuilder buffer)
Appends a hex-encoded representation of the provided character to the given buffer. Each byte of the hex-encoded representation will be prefixed with a backslash.- Parameters:
c
- The character to be encoded.buffer
- The buffer to which the hex-encoded representation should be appended.
-
hexEncode
public static void hexEncode(int codePoint, @NotNull java.lang.StringBuilder buffer)
Appends a hex-encoded representation of the provided code point to the given buffer. Each byte of the hex-encoded representation will be prefixed with a backslash.- Parameters:
codePoint
- The code point to be encoded.buffer
- The buffer to which the hex-encoded representation should be appended.
-
byteArrayToCode
public static void byteArrayToCode(@NotNull byte[] array, @NotNull java.lang.StringBuilder buffer)
Appends the Java code that may be used to create the provided byte array to the given buffer.- Parameters:
array
- The byte array containing the data to represent. It must not benull
.buffer
- The buffer to which the code should be appended.
-
getBacktrace
@NotNull public static java.lang.String getBacktrace()
Retrieves a single-line string representation of the stack trace for the current thread. It will not include the call to thegetBacktrace
method itself, nor anything that it calls either directly or indirectly.- Returns:
- A single-line string representation of the stack trace for the current thread.
-
getStackTrace
@NotNull public static java.lang.String getStackTrace(@NotNull java.lang.Throwable t)
Retrieves a single-line string representation of the stack trace for the providedThrowable
. It will include the unqualified name of theThrowable
class, a list of source files and line numbers (if available) for the stack trace, and will also include the stack trace for the cause (if present).- Parameters:
t
- TheThrowable
for which to retrieve the stack trace.- Returns:
- A single-line string representation of the stack trace for the
provided
Throwable
.
-
getStackTrace
public static void getStackTrace(@NotNull java.lang.Throwable t, @NotNull java.lang.StringBuilder buffer)
Appends a single-line string representation of the stack trace for the providedThrowable
to the given buffer. It will include the unqualified name of theThrowable
class, a list of source files and line numbers (if available) for the stack trace, and will also include the stack trace for the cause (if present).- Parameters:
t
- TheThrowable
for which to retrieve the stack trace.buffer
- The buffer to which the information should be appended.
-
getStackTrace
@NotNull public static java.lang.String getStackTrace(@NotNull java.lang.StackTraceElement[] elements)
Returns a single-line string representation of the stack trace. It will include a list of source files and line numbers (if available) for the stack trace.- Parameters:
elements
- The stack trace.- Returns:
- A single-line string representation of the stack trace.
-
getStackTrace
public static void getStackTrace(@NotNull java.lang.StackTraceElement[] elements, @NotNull java.lang.StringBuilder buffer)
Appends a single-line string representation of the stack trace to the given buffer. It will include a list of source files and line numbers (if available) for the stack trace.- Parameters:
elements
- The stack trace.buffer
- The buffer to which the information should be appended.
-
getStackTrace
public static void getStackTrace(@NotNull java.lang.StackTraceElement[] elements, @NotNull java.lang.StringBuilder buffer, int maxPreSDKFrames)
Appends a single-line string representation of the stack trace to the given buffer. It will include a list of source files and line numbers (if available) for the stack trace.- Parameters:
elements
- The stack trace.buffer
- The buffer to which the information should be appended.maxPreSDKFrames
- The maximum number of stack trace frames to include from code invoked before calling into the LDAP SDK. A value of zero indicates that only stack trace frames from the LDAP SDK itself (or things that it calls) will be included. A negative value indicates that
-
getExceptionMessage
@NotNull public static java.lang.String getExceptionMessage(@NotNull java.lang.Throwable t)
Retrieves a string representation of the providedThrowable
object suitable for use in a message. For runtime exceptions and errors, then a full stack trace for the exception will be provided. For exception types defined in the LDAP SDK, then itsgetExceptionMessage
method will be used to get the string representation. For all other types of exceptions, then the standard string representation will be used.
For all types of exceptions, the message will also include the cause if one exists.- Parameters:
t
- TheThrowable
for which to generate the exception message.- Returns:
- A string representation of the provided
Throwable
object suitable for use in a message.
-
getExceptionMessage
@NotNull public static java.lang.String getExceptionMessage(@Nullable java.lang.Throwable t, boolean includeCause, boolean includeStackTrace)
Retrieves a string representation of the providedThrowable
object suitable for use in a message. For runtime exceptions and errors, then a full stack trace for the exception will be provided. For exception types defined in the LDAP SDK, then itsgetExceptionMessage
method will be used to get the string representation. For all other types of exceptions, then the standard string representation will be used.
For all types of exceptions, the message will also include the cause if one exists.- Parameters:
t
- TheThrowable
for which to generate the exception message.includeCause
- Indicates whether to include information about the cause (if any) in the exception message.includeStackTrace
- Indicates whether to include a condensed representation of the stack trace in the exception message.- Returns:
- A string representation of the provided
Throwable
object suitable for use in a message.
-
getUnqualifiedClassName
@NotNull public static java.lang.String getUnqualifiedClassName(@NotNull java.lang.Class<?> c)
Retrieves the unqualified name (i.e., the name without package information) for the provided class.- Parameters:
c
- The class for which to retrieve the unqualified name.- Returns:
- The unqualified name for the provided class.
-
getUTCTimeZone
@NotNull public static java.util.TimeZone getUTCTimeZone()
Retrieves aTimeZone
object that represents the UTC (universal coordinated time) time zone.- Returns:
- A
TimeZone
object that represents the UTC time zone.
-
encodeGeneralizedTime
@NotNull public static java.lang.String encodeGeneralizedTime(long timestamp)
Encodes the provided timestamp in generalized time format.- Parameters:
timestamp
- The timestamp to be encoded in generalized time format. It should use the same format as theSystem.currentTimeMillis()
method (i.e., the number of milliseconds since 12:00am UTC on January 1, 1970).- Returns:
- The generalized time representation of the provided date.
-
encodeGeneralizedTime
@NotNull public static java.lang.String encodeGeneralizedTime(@NotNull java.util.Date d)
Encodes the provided date in generalized time format.- Parameters:
d
- The date to be encoded in generalized time format.- Returns:
- The generalized time representation of the provided date.
-
decodeGeneralizedTime
@NotNull public static java.util.Date decodeGeneralizedTime(@NotNull java.lang.String t) throws java.text.ParseException
Decodes the provided string as a timestamp in generalized time format.- Parameters:
t
- The timestamp to be decoded. It must not benull
.- Returns:
- The
Date
object decoded from the provided timestamp. - Throws:
java.text.ParseException
- If the provided string could not be decoded as a timestamp in generalized time format.
-
encodeRFC3339Time
@NotNull public static java.lang.String encodeRFC3339Time(long timestamp)
Encodes the provided timestamp to the ISO 8601 format described in RFC 3339.- Parameters:
timestamp
- The timestamp to be encoded in the RFC 3339 format. It should use the same format as theSystem.currentTimeMillis()
method (i.e., the number of milliseconds since 12:00am UTC on January 1, 1970).- Returns:
- The RFC 3339 representation of the provided date.
-
encodeRFC3339Time
@NotNull public static java.lang.String encodeRFC3339Time(@NotNull java.util.Date d)
Encodes the provided timestamp to the ISO 8601 format described in RFC 3339.- Parameters:
d
- The date to be encoded in the RFC 3339 format.- Returns:
- The RFC 3339 representation of the provided date.
-
decodeRFC3339Time
@NotNull public static java.util.Date decodeRFC3339Time(@NotNull java.lang.String timestamp) throws java.text.ParseException
Decodes the provided string as a timestamp encoded in the ISO 8601 format described in RFC 3339.- Parameters:
timestamp
- The timestamp to be decoded in the RFC 3339 format.- Returns:
- The
Date
object decoded from the provided timestamp. - Throws:
java.text.ParseException
- If the provided string could not be decoded as a timestamp in the RFC 3339 time format.
-
trimLeading
@NotNull public static java.lang.String trimLeading(@NotNull java.lang.String s)
Trims only leading spaces from the provided string, leaving any trailing spaces intact.- Parameters:
s
- The string to be processed. It must not benull
.- Returns:
- The original string if no trimming was required, or a new string without leading spaces if the provided string had one or more. It may be an empty string if the provided string was an empty string or contained only spaces.
-
trimTrailing
@NotNull public static java.lang.String trimTrailing(@NotNull java.lang.String s)
Trims only trailing spaces from the provided string, leaving any leading spaces intact.- Parameters:
s
- The string to be processed. It must not benull
.- Returns:
- The original string if no trimming was required, or a new string without trailing spaces if the provided string had one or more. It may be an empty string if the provided string was an empty string or contained only spaces.
-
wrapLine
@NotNull public static java.util.List<java.lang.String> wrapLine(@NotNull java.lang.String line, int maxWidth)
Wraps the contents of the specified line using the given width. It will attempt to wrap at spaces to preserve words, but if that is not possible (because a single "word" is longer than the maximum width), then it will wrap in the middle of the word at the specified maximum width.- Parameters:
line
- The line to be wrapped. It must not benull
.maxWidth
- The maximum width for lines in the resulting list. A value less than or equal to zero will cause no wrapping to be performed.- Returns:
- A list of the wrapped lines. It may be empty if the provided line contained only spaces.
-
wrapLine
@NotNull public static java.util.List<java.lang.String> wrapLine(@NotNull java.lang.String line, int maxFirstLineWidth, int maxSubsequentLineWidth)
Wraps the contents of the specified line using the given width. It will attempt to wrap at spaces to preserve words, but if that is not possible (because a single "word" is longer than the maximum width), then it will wrap in the middle of the word at the specified maximum width.- Parameters:
line
- The line to be wrapped. It must not benull
.maxFirstLineWidth
- The maximum length for the first line in the resulting list. A value less than or equal to zero will cause no wrapping to be performed.maxSubsequentLineWidth
- The maximum length for all lines except the first line. This must be greater than zero unlessmaxFirstLineWidth
is less than or equal to zero.- Returns:
- A list of the wrapped lines. It may be empty if the provided line contained only spaces.
-
cleanExampleCommandLineArgument
@NotNull public static java.lang.String cleanExampleCommandLineArgument(@NotNull java.lang.String s)
This method returns a form of the provided argument that is safe to use on the command line for the local platform. This method is provided as a convenience wrapper aroundExampleCommandLineArgument
. Calling this method is equivalent to:return ExampleCommandLineArgument.getCleanArgument(s).getLocalForm();
For getting direct access to command line arguments that are safe to use on other platforms, callExampleCommandLineArgument.getCleanArgument(java.lang.String)
.- Parameters:
s
- The string to be processed. It must not benull
.- Returns:
- A cleaned version of the provided string in a form that will allow it to be displayed as the value of a command-line argument on.
-
concatenateStrings
@NotNull public static java.lang.String concatenateStrings(@NotNull java.lang.String... a)
Retrieves a single string which is a concatenation of all of the provided strings.- Parameters:
a
- The array of strings to concatenate. It must not benull
but may be empty.- Returns:
- A string containing a concatenation of all of the strings in the provided array.
-
concatenateStrings
@NotNull public static java.lang.String concatenateStrings(@NotNull java.util.List<java.lang.String> l)
Retrieves a single string which is a concatenation of all of the provided strings.- Parameters:
l
- The list of strings to concatenate. It must not benull
but may be empty.- Returns:
- A string containing a concatenation of all of the strings in the provided list.
-
concatenateStrings
@NotNull public static java.lang.String concatenateStrings(@Nullable java.lang.String beforeList, @Nullable java.lang.String beforeElement, @Nullable java.lang.String betweenElements, @Nullable java.lang.String afterElement, @Nullable java.lang.String afterList, @NotNull java.lang.String... a)
Retrieves a single string which is a concatenation of all of the provided strings.- Parameters:
beforeList
- A string that should be placed at the beginning of the list. It may benull
or empty if nothing should be placed at the beginning of the list.beforeElement
- A string that should be placed before each element in the list. It may benull
or empty if nothing should be placed before each element.betweenElements
- The separator that should be placed between elements in the list. It may benull
or empty if no separator should be placed between elements.afterElement
- A string that should be placed after each element in the list. It may benull
or empty if nothing should be placed after each element.afterList
- A string that should be placed at the end of the list. It may benull
or empty if nothing should be placed at the end of the list.a
- The array of strings to concatenate. It must not benull
but may be empty.- Returns:
- A string containing a concatenation of all of the strings in the provided list.
-
concatenateStrings
@NotNull public static java.lang.String concatenateStrings(@Nullable java.lang.String beforeList, @Nullable java.lang.String beforeElement, @Nullable java.lang.String betweenElements, @Nullable java.lang.String afterElement, @Nullable java.lang.String afterList, @NotNull java.util.List<java.lang.String> l)
Retrieves a single string which is a concatenation of all of the provided strings.- Parameters:
beforeList
- A string that should be placed at the beginning of the list. It may benull
or empty if nothing should be placed at the beginning of the list.beforeElement
- A string that should be placed before each element in the list. It may benull
or empty if nothing should be placed before each element.betweenElements
- The separator that should be placed between elements in the list. It may benull
or empty if no separator should be placed between elements.afterElement
- A string that should be placed after each element in the list. It may benull
or empty if nothing should be placed after each element.afterList
- A string that should be placed at the end of the list. It may benull
or empty if nothing should be placed at the end of the list.l
- The list of strings to concatenate. It must not benull
but may be empty.- Returns:
- A string containing a concatenation of all of the strings in the provided list.
-
secondsToHumanReadableDuration
@NotNull public static java.lang.String secondsToHumanReadableDuration(long s)
Converts a duration in seconds to a string with a human-readable duration which may include days, hours, minutes, and seconds, to the extent that they are needed.- Parameters:
s
- The number of seconds to be represented.- Returns:
- A string containing a human-readable representation of the provided time.
-
millisToHumanReadableDuration
@NotNull public static java.lang.String millisToHumanReadableDuration(long m)
Converts a duration in seconds to a string with a human-readable duration which may include days, hours, minutes, and seconds, to the extent that they are needed.- Parameters:
m
- The number of milliseconds to be represented.- Returns:
- A string containing a human-readable representation of the provided time.
-
nanosToMillis
public static long nanosToMillis(long nanos)
Converts the provided number of nanoseconds to milliseconds.- Parameters:
nanos
- The number of nanoseconds to convert to milliseconds.- Returns:
- The number of milliseconds that most closely corresponds to the specified number of nanoseconds.
-
millisToNanos
public static long millisToNanos(long millis)
Converts the provided number of milliseconds to nanoseconds.- Parameters:
millis
- The number of milliseconds to convert to nanoseconds.- Returns:
- The number of nanoseconds that most closely corresponds to the specified number of milliseconds.
-
isNumericOID
public static boolean isNumericOID(@NotNull java.lang.String s)
Indicates whether the provided string is a valid numeric OID. A numeric OID must start and end with a digit, must have at least on period, must contain only digits and periods, and must not have two consecutive periods.- Parameters:
s
- The string to examine. It must not benull
.- Returns:
true
if the provided string is a valid numeric OID, orfalse
if not.
-
capitalize
@Nullable public static java.lang.String capitalize(@Nullable java.lang.String s)
Capitalizes the provided string. The first character will be converted to uppercase, and the rest of the string will be left unaltered.- Parameters:
s
- The string to be capitalized.- Returns:
- A capitalized version of the provided string, or
null
if the provided string wasnull
.
-
capitalize
@Nullable public static java.lang.String capitalize(@Nullable java.lang.String s, boolean allWords)
Capitalizes the provided string. The first character of the string (or optionally the first character of each word in the string)- Parameters:
s
- The string to be capitalized.allWords
- Indicates whether to capitalize all words in the string, or only the first word.- Returns:
- A capitalized version of the provided string, or
null
if the provided string wasnull
.
-
encodeUUID
@NotNull public static byte[] encodeUUID(@NotNull java.util.UUID uuid)
Encodes the provided UUID to a byte array containing its 128-bit representation.- Parameters:
uuid
- The UUID to be encoded. It must not benull
.- Returns:
- The byte array containing the 128-bit encoded UUID.
-
decodeUUID
@NotNull public static java.util.UUID decodeUUID(@NotNull byte[] b) throws java.text.ParseException
Decodes the value of the provided byte array as a Java UUID.- Parameters:
b
- The byte array to be decoded as a UUID. It must not benull
.- Returns:
- The decoded UUID.
- Throws:
java.text.ParseException
- If the provided byte array cannot be parsed as a UUID.
-
isWindows
public static boolean isWindows()
Returnstrue
if and only if the current process is running on a Windows-based operating system.- Returns:
true
if the current process is running on a Windows-based operating system andfalse
otherwise.
-
getCommandLineContinuationString
@NotNull public static java.lang.String getCommandLineContinuationString()
Retrieves the string that should be appended to the end of all but the last line of a multi-line command to indicate that the command continues onto the next line.
This will be the caret (also called a circumflex accent) character on Windows systems, and a backslash (also called a reverse solidus) character on Linux and UNIX-based systems.
The string value that is returned will not include a space, but it should generally be preceded by one or more space to separate it from the previous component on the command line.- Returns:
- The string that should be appended (generally after one or more spaces to separate it from the previous component) to the end of all but the last line of a multi-line command to indicate that the command continues onto the next line.
-
toArgumentList
@NotNull public static java.util.List<java.lang.String> toArgumentList(@Nullable java.lang.String s) throws java.text.ParseException
Attempts to parse the contents of the provided string to an argument list (e.g., converts something like "--arg1 arg1value --arg2 --arg3 arg3value" to a list of "--arg1", "arg1value", "--arg2", "--arg3", "arg3value").- Parameters:
s
- The string to be converted to an argument list.- Returns:
- The parsed argument list.
- Throws:
java.text.ParseException
- If a problem is encountered while attempting to parse the given string to an argument list.
-
toArray
@Nullable public static <T> T[] toArray(@Nullable java.util.Collection<T> collection, @NotNull java.lang.Class<T> type)
Retrieves an array containing the elements of the provided collection.- Type Parameters:
T
- The type of element included in the provided collection.- Parameters:
collection
- The collection to convert to an array.type
- The type of element contained in the collection.- Returns:
- An array containing the elements of the provided list, or
null
if the provided list isnull
.
-
toList
@Nullable public static <T> java.util.List<T> toList(@Nullable T[] array)
Creates a modifiable list with all of the items of the provided array in the same order. This method behaves much likeArrays.asList
, except that if the provided array isnull
, then it will return anull
list rather than throwing an exception.- Type Parameters:
T
- The type of item contained in the provided array.- Parameters:
array
- The array of items to include in the list.- Returns:
- The list that was created, or
null
if the provided array wasnull
.
-
toNonNullList
@NotNull public static <T> java.util.List<T> toNonNullList(@Nullable T[] array)
Creates a modifiable list with all of the items of the provided array in the same order. This method behaves much likeArrays.asList
, except that if the provided array isnull
, then it will return an empty list rather than throwing an exception.- Type Parameters:
T
- The type of item contained in the provided array.- Parameters:
array
- The array of items to include in the list.- Returns:
- The list that was created, or an empty list if the provided array
was
null
.
-
bothNullOrEqual
public static boolean bothNullOrEqual(@Nullable java.lang.Object o1, @Nullable java.lang.Object o2)
Indicates whether both of the provided objects arenull
or both are logically equal (using theequals
method).- Parameters:
o1
- The first object for which to make the determination.o2
- The second object for which to make the determination.- Returns:
true
if both objects arenull
or both are logically equal, orfalse
if only one of the objects isnull
or they are not logically equal.
-
bothNullOrEqualIgnoreCase
public static boolean bothNullOrEqualIgnoreCase(@Nullable java.lang.String s1, @Nullable java.lang.String s2)
Indicates whether both of the provided strings arenull
or both are logically equal ignoring differences in capitalization (using theequalsIgnoreCase
method).- Parameters:
s1
- The first string for which to make the determination.s2
- The second string for which to make the determination.- Returns:
true
if both strings arenull
or both are logically equal ignoring differences in capitalization, orfalse
if only one of the objects isnull
or they are not logically equal ignoring capitalization.
-
stringsEqualIgnoreCaseOrderIndependent
public static boolean stringsEqualIgnoreCaseOrderIndependent(@Nullable java.lang.String[] a1, @Nullable java.lang.String[] a2)
Indicates whether the provided string arrays have the same elements, ignoring the order in which they appear and differences in capitalization. It is assumed that neither array containsnull
strings, and that no string appears more than once in each array.- Parameters:
a1
- The first array for which to make the determination.a2
- The second array for which to make the determination.- Returns:
true
if both arrays have the same set of strings, orfalse
if not.
-
arraysEqualOrderIndependent
public static <T> boolean arraysEqualOrderIndependent(@Nullable T[] a1, @Nullable T[] a2)
Indicates whether the provided arrays have the same elements, ignoring the order in which they appear. It is assumed that neither array containsnull
elements, and that no element appears more than once in each array.- Type Parameters:
T
- The type of element contained in the arrays.- Parameters:
a1
- The first array for which to make the determination.a2
- The second array for which to make the determination.- Returns:
true
if both arrays have the same set of elements, orfalse
if not.
-
numBytesInUTF8CharacterWithFirstByte
public static int numBytesInUTF8CharacterWithFirstByte(byte b)
Determines the number of bytes in a UTF-8 character that starts with the given byte.- Parameters:
b
- The byte for which to make the determination.- Returns:
- The number of bytes in a UTF-8 character that starts with the given byte, or -1 if it does not appear to be a valid first byte for a UTF-8 character.
-
isSensitiveToCodeAttribute
public static boolean isSensitiveToCodeAttribute(@NotNull java.lang.String name)
Indicates whether the provided attribute name should be considered a sensitive attribute for the purposes oftoCode
methods. If an attribute is considered sensitive, then its values will be redacted in the output of thetoCode
methods.- Parameters:
name
- The name for which to make the determination. It may or may not include attribute options. It must not benull
.- Returns:
true
if the specified attribute is one that should be considered sensitive for the
-
getSensitiveToCodeAttributeBaseNames
@NotNull public static java.util.Set<java.lang.String> getSensitiveToCodeAttributeBaseNames()
Retrieves a set containing the base names (in all lowercase characters) of any attributes that should be considered sensitive for the purposes of thetoCode
methods. By default, only the userPassword and authPassword attributes and their respective OIDs will be included.- Returns:
- A set containing the base names (in all lowercase characters) of
any attributes that should be considered sensitive for the
purposes of the
toCode
methods.
-
setSensitiveToCodeAttributes
public static void setSensitiveToCodeAttributes(@Nullable java.lang.String... names)
Specifies the names of any attributes that should be considered sensitive for the purposes of thetoCode
methods.- Parameters:
names
- The names of any attributes that should be considered sensitive for the purposes of thetoCode
methods. It may benull
or empty if no attributes should be considered sensitive.
-
setSensitiveToCodeAttributes
public static void setSensitiveToCodeAttributes(@Nullable java.util.Collection<java.lang.String> names)
Specifies the names of any attributes that should be considered sensitive for the purposes of thetoCode
methods.- Parameters:
names
- The names of any attributes that should be considered sensitive for the purposes of thetoCode
methods. It may benull
or empty if no attributes should be considered sensitive.
-
createIOExceptionWithCause
@NotNull public static java.io.IOException createIOExceptionWithCause(@Nullable java.lang.String message, @Nullable java.lang.Throwable cause)
Creates a newIOException
with a cause. The constructor needed to do this wasn't available until Java SE 6, so reflection is used to invoke this constructor in versions of Java that provide it. In Java SE 5, the provided message will be augmented with information about the cause.- Parameters:
message
- The message to use for the exception. This may benull
if the message should be generated from the provided cause.cause
- The underlying cause for the exception. It may benull
if the exception should have only a message.- Returns:
- The
IOException
object that was created.
-
stringToLines
@NotNull public static java.util.List<java.lang.String> stringToLines(@Nullable java.lang.String s)
Converts the provided string (which may include line breaks) into a list containing the lines without the line breaks.- Parameters:
s
- The string to convert into a list of its representative lines.- Returns:
- A list containing the lines that comprise the given string.
-
linesToString
@NotNull public static java.lang.String linesToString(@Nullable java.lang.CharSequence... lines)
Creates a string that is a concatenation of all of the provided lines, with a line break (using the end-of-line sequence appropriate for the underlying platform) after each line (including the last line).- Parameters:
lines
- The lines to include in the string.- Returns:
- The string resulting from concatenating the provided lines with line breaks.
-
linesToString
@NotNull public static java.lang.String linesToString(@Nullable java.util.List<? extends java.lang.CharSequence> lines)
Creates a string that is a concatenation of all of the provided lines, with a line break (using the end-of-line sequence appropriate for the underlying platform) after each line (including the last line).- Parameters:
lines
- The lines to include in the string.- Returns:
- The string resulting from concatenating the provided lines with line breaks.
-
constructPath
@NotNull public static java.io.File constructPath(@NotNull java.io.File baseDirectory, @Nullable java.lang.String... pathElements)
Constructs aFile
object from the provided path.- Parameters:
baseDirectory
- The base directory to use as the starting point. It must not benull
and is expected to represent a directory.pathElements
- An array of the elements that make up the remainder of the path to the specified file, in order from paths closest to the root of the filesystem to furthest away (that is, the first element should represent a file or directory immediately below the base directory, the second is one level below that, and so on). It may benull
or empty if the base directory should be used.- Returns:
- The constructed
File
object.
-
byteArray
@NotNull public static byte[] byteArray(@Nullable int... bytes)
Creates a byte array from the provided integer values. All of the integer values must be between 0x00 and 0xFF (0 and 255), inclusive. Any bits set outside of that range will be ignored.- Parameters:
bytes
- The values to include in the byte array.- Returns:
- A byte array with the provided set of values.
-
isWithinUnitTest
public static boolean isWithinUnitTest()
Indicates whether the unit tests are currently running in this JVM.- Returns:
true
if the unit tests are currently running, orfalse
if not.
-
throwErrorOrRuntimeException
public static void throwErrorOrRuntimeException(@NotNull java.lang.Throwable throwable) throws java.lang.Error, java.lang.RuntimeException
Throws anError
or aRuntimeException
based on the providedThrowable
object. This method will always throw something, regardless of the providedThrowable
object.- Parameters:
throwable
- TheThrowable
object to use to create the exception to throw.- Throws:
java.lang.Error
- If the providedThrowable
object is anError
instance, then thatError
instance will be re-thrown.java.lang.RuntimeException
- If the providedThrowable
object is aRuntimeException
instance, then thatRuntimeException
instance will be re-thrown. Otherwise, it must be a checked exception and that checked exception will be re-thrown as aRuntimeException
.
-
rethrowIfErrorOrRuntimeException
public static void rethrowIfErrorOrRuntimeException(@NotNull java.lang.Throwable throwable) throws java.lang.Error, java.lang.RuntimeException
Re-throws the providedThrowable
instance only if it is anError
or aRuntimeException
instance; otherwise, this method will return without taking any action.- Parameters:
throwable
- TheThrowable
object to examine and potentially re-throw.- Throws:
java.lang.Error
- If the providedThrowable
object is anError
instance, then thatError
instance will be re-thrown.java.lang.RuntimeException
- If the providedThrowable
object is aRuntimeException
instance, then thatRuntimeException
instance will be re-thrown.
-
rethrowIfError
public static void rethrowIfError(@NotNull java.lang.Throwable throwable) throws java.lang.Error
Re-throws the providedThrowable
instance only if it is anError
; otherwise, this method will return without taking any action.- Parameters:
throwable
- TheThrowable
object to examine and potentially re-throw.- Throws:
java.lang.Error
- If the providedThrowable
object is anError
instance, then thatError
instance will be re-thrown.
-
computeMapCapacity
public static int computeMapCapacity(int expectedItemCount)
Computes the capacity that should be used for a map or a set with the expected number of elements, which can help avoid the need to re-hash or re-balance the map if too many items are added. This method bases its computation on the default map load factor of 0.75.- Parameters:
expectedItemCount
- The expected maximum number of items that will be placed in the map or set. It must be greater than or equal to zero.- Returns:
- The capacity that should be used for a map or a set with the expected number of elements
-
setOf
@SafeVarargs @NotNull public static <T> java.util.Set<T> setOf(@NotNull T... items)
Creates an unmodifiable set containing the provided items. The iteration order of the provided items will be preserved.- Type Parameters:
T
- The type of item to include in the set.- Parameters:
items
- The items to include in the set. It must not benull
, but may be empty.- Returns:
- An unmodifiable set containing the provided items.
-
hashSetOf
@SafeVarargs @NotNull public static <T> java.util.HashSet<T> hashSetOf(@NotNull T... items)
Creates aHashSet
containing the provided items.- Type Parameters:
T
- The type of item to include in the set.- Parameters:
items
- The items to include in the set. It must not benull
, but may be empty.- Returns:
- A
HashSet
containing the provided items.
-
linkedHashSetOf
@SafeVarargs @NotNull public static <T> java.util.LinkedHashSet<T> linkedHashSetOf(@NotNull T... items)
Creates aLinkedHashSet
containing the provided items.- Type Parameters:
T
- The type of item to include in the set.- Parameters:
items
- The items to include in the set. It must not benull
, but may be empty.- Returns:
- A
LinkedHashSet
containing the provided items.
-
treeSetOf
@SafeVarargs @NotNull public static <T> java.util.TreeSet<T> treeSetOf(@NotNull T... items)
Creates aTreeSet
containing the provided items.- Type Parameters:
T
- The type of item to include in the set.- Parameters:
items
- The items to include in the set. It must not benull
, but may be empty.- Returns:
- A
LinkedHashSet
containing the provided items.
-
mapOf
@NotNull public static <K,V> java.util.Map<K,V> mapOf(@NotNull K key, @NotNull V value)
Creates an unmodifiable map containing the provided items.- Type Parameters:
K
- The type for the map keys.V
- The type for the map values.- Parameters:
key
- The only key to include in the map.value
- The only value to include in the map.- Returns:
- The unmodifiable map that was created.
-
mapOf
@NotNull public static <K,V> java.util.Map<K,V> mapOf(@NotNull K key1, @NotNull V value1, @NotNull K key2, @NotNull V value2)
Creates an unmodifiable map containing the provided items.- Type Parameters:
K
- The type for the map keys.V
- The type for the map values.- Parameters:
key1
- The first key to include in the map.value1
- The first value to include in the map.key2
- The second key to include in the map.value2
- The second value to include in the map.- Returns:
- The unmodifiable map that was created.
-
mapOf
@NotNull public static <K,V> java.util.Map<K,V> mapOf(@NotNull K key1, @NotNull V value1, @NotNull K key2, @NotNull V value2, @NotNull K key3, @NotNull V value3)
Creates an unmodifiable map containing the provided items.- Type Parameters:
K
- The type for the map keys.V
- The type for the map values.- Parameters:
key1
- The first key to include in the map.value1
- The first value to include in the map.key2
- The second key to include in the map.value2
- The second value to include in the map.key3
- The third key to include in the map.value3
- The third value to include in the map.- Returns:
- The unmodifiable map that was created.
-
mapOf
@NotNull public static <K,V> java.util.Map<K,V> mapOf(@NotNull K key1, @NotNull V value1, @NotNull K key2, @NotNull V value2, @NotNull K key3, @NotNull V value3, @NotNull K key4, @NotNull V value4)
Creates an unmodifiable map containing the provided items.- Type Parameters:
K
- The type for the map keys.V
- The type for the map values.- Parameters:
key1
- The first key to include in the map.value1
- The first value to include in the map.key2
- The second key to include in the map.value2
- The second value to include in the map.key3
- The third key to include in the map.value3
- The third value to include in the map.key4
- The fourth key to include in the map.value4
- The fourth value to include in the map.- Returns:
- The unmodifiable map that was created.
-
mapOf
@NotNull public static <K,V> java.util.Map<K,V> mapOf(@NotNull K key1, @NotNull V value1, @NotNull K key2, @NotNull V value2, @NotNull K key3, @NotNull V value3, @NotNull K key4, @NotNull V value4, @NotNull K key5, @NotNull V value5)
Creates an unmodifiable map containing the provided items.- Type Parameters:
K
- The type for the map keys.V
- The type for the map values.- Parameters:
key1
- The first key to include in the map.value1
- The first value to include in the map.key2
- The second key to include in the map.value2
- The second value to include in the map.key3
- The third key to include in the map.value3
- The third value to include in the map.key4
- The fourth key to include in the map.value4
- The fourth value to include in the map.key5
- The fifth key to include in the map.value5
- The fifth value to include in the map.- Returns:
- The unmodifiable map that was created.
-
mapOf
@NotNull public static <K,V> java.util.Map<K,V> mapOf(@NotNull K key1, @NotNull V value1, @NotNull K key2, @NotNull V value2, @NotNull K key3, @NotNull V value3, @NotNull K key4, @NotNull V value4, @NotNull K key5, @NotNull V value5, @NotNull K key6, @NotNull V value6)
Creates an unmodifiable map containing the provided items.- Type Parameters:
K
- The type for the map keys.V
- The type for the map values.- Parameters:
key1
- The first key to include in the map.value1
- The first value to include in the map.key2
- The second key to include in the map.value2
- The second value to include in the map.key3
- The third key to include in the map.value3
- The third value to include in the map.key4
- The fourth key to include in the map.value4
- The fourth value to include in the map.key5
- The fifth key to include in the map.value5
- The fifth value to include in the map.key6
- The sixth key to include in the map.value6
- The sixth value to include in the map.- Returns:
- The unmodifiable map that was created.
-
mapOf
@NotNull public static <K,V> java.util.Map<K,V> mapOf(@NotNull K key1, @NotNull V value1, @NotNull K key2, @NotNull V value2, @NotNull K key3, @NotNull V value3, @NotNull K key4, @NotNull V value4, @NotNull K key5, @NotNull V value5, @NotNull K key6, @NotNull V value6, @NotNull K key7, @NotNull V value7)
Creates an unmodifiable map containing the provided items.- Type Parameters:
K
- The type for the map keys.V
- The type for the map values.- Parameters:
key1
- The first key to include in the map.value1
- The first value to include in the map.key2
- The second key to include in the map.value2
- The second value to include in the map.key3
- The third key to include in the map.value3
- The third value to include in the map.key4
- The fourth key to include in the map.value4
- The fourth value to include in the map.key5
- The fifth key to include in the map.value5
- The fifth value to include in the map.key6
- The sixth key to include in the map.value6
- The sixth value to include in the map.key7
- The seventh key to include in the map.value7
- The seventh value to include in the map.- Returns:
- The unmodifiable map that was created.
-
mapOf
@NotNull public static <K,V> java.util.Map<K,V> mapOf(@NotNull K key1, @NotNull V value1, @NotNull K key2, @NotNull V value2, @NotNull K key3, @NotNull V value3, @NotNull K key4, @NotNull V value4, @NotNull K key5, @NotNull V value5, @NotNull K key6, @NotNull V value6, @NotNull K key7, @NotNull V value7, @NotNull K key8, @NotNull V value8)
Creates an unmodifiable map containing the provided items.- Type Parameters:
K
- The type for the map keys.V
- The type for the map values.- Parameters:
key1
- The first key to include in the map.value1
- The first value to include in the map.key2
- The second key to include in the map.value2
- The second value to include in the map.key3
- The third key to include in the map.value3
- The third value to include in the map.key4
- The fourth key to include in the map.value4
- The fourth value to include in the map.key5
- The fifth key to include in the map.value5
- The fifth value to include in the map.key6
- The sixth key to include in the map.value6
- The sixth value to include in the map.key7
- The seventh key to include in the map.value7
- The seventh value to include in the map.key8
- The eighth key to include in the map.value8
- The eighth value to include in the map.- Returns:
- The unmodifiable map that was created.
-
mapOf
@NotNull public static <K,V> java.util.Map<K,V> mapOf(@NotNull K key1, @NotNull V value1, @NotNull K key2, @NotNull V value2, @NotNull K key3, @NotNull V value3, @NotNull K key4, @NotNull V value4, @NotNull K key5, @NotNull V value5, @NotNull K key6, @NotNull V value6, @NotNull K key7, @NotNull V value7, @NotNull K key8, @NotNull V value8, @NotNull K key9, @NotNull V value9)
Creates an unmodifiable map containing the provided items.- Type Parameters:
K
- The type for the map keys.V
- The type for the map values.- Parameters:
key1
- The first key to include in the map.value1
- The first value to include in the map.key2
- The second key to include in the map.value2
- The second value to include in the map.key3
- The third key to include in the map.value3
- The third value to include in the map.key4
- The fourth key to include in the map.value4
- The fourth value to include in the map.key5
- The fifth key to include in the map.value5
- The fifth value to include in the map.key6
- The sixth key to include in the map.value6
- The sixth value to include in the map.key7
- The seventh key to include in the map.value7
- The seventh value to include in the map.key8
- The eighth key to include in the map.value8
- The eighth value to include in the map.key9
- The ninth key to include in the map.value9
- The ninth value to include in the map.- Returns:
- The unmodifiable map that was created.
-
mapOf
@NotNull public static <K,V> java.util.Map<K,V> mapOf(@NotNull K key1, @NotNull V value1, @NotNull K key2, @NotNull V value2, @NotNull K key3, @NotNull V value3, @NotNull K key4, @NotNull V value4, @NotNull K key5, @NotNull V value5, @NotNull K key6, @NotNull V value6, @NotNull K key7, @NotNull V value7, @NotNull K key8, @NotNull V value8, @NotNull K key9, @NotNull V value9, @NotNull K key10, @NotNull V value10)
Creates an unmodifiable map containing the provided items.- Type Parameters:
K
- The type for the map keys.V
- The type for the map values.- Parameters:
key1
- The first key to include in the map.value1
- The first value to include in the map.key2
- The second key to include in the map.value2
- The second value to include in the map.key3
- The third key to include in the map.value3
- The third value to include in the map.key4
- The fourth key to include in the map.value4
- The fourth value to include in the map.key5
- The fifth key to include in the map.value5
- The fifth value to include in the map.key6
- The sixth key to include in the map.value6
- The sixth value to include in the map.key7
- The seventh key to include in the map.value7
- The seventh value to include in the map.key8
- The eighth key to include in the map.value8
- The eighth value to include in the map.key9
- The ninth key to include in the map.value9
- The ninth value to include in the map.key10
- The tenth key to include in the map.value10
- The tenth value to include in the map.- Returns:
- The unmodifiable map that was created.
-
mapOf
@SafeVarargs @NotNull public static <T> java.util.Map<T,T> mapOf(@Nullable T... items)
Creates an unmodifiable map containing the provided items. The map entries must have the same data type for keys and values.- Type Parameters:
T
- The type for the map keys and values.- Parameters:
items
- The items to include in the map. If it is null or empty, the map will be empty. If it is non-empty, then the number of elements in the array must be a multiple of two. Elements in even-numbered indexes will be the keys for the map entries, while elements in odd-numbered indexes will be the map values.- Returns:
- The unmodifiable map that was created.
-
mapOfObjectPairs
@SafeVarargs @NotNull public static <K,V> java.util.Map<K,V> mapOfObjectPairs(@Nullable ObjectPair<K,V>... items)
Creates an unmodifiable map containing the provided items.- Type Parameters:
K
- The type for the map keys.V
- The type for the map values.- Parameters:
items
- The items to include in the map.- Returns:
- The unmodifiable map that was created.
-
getAllLocalAddresses
@NotNull public static java.util.Set<java.net.InetAddress> getAllLocalAddresses(@Nullable NameResolver nameResolver)
Attempts to determine all addresses associated with the local system, including loopback addresses.- Parameters:
nameResolver
- The name resolver to use to determine the local host and loopback addresses. If this isnull
, then the LDAP SDK's default name resolver will be used.- Returns:
- A set of the local addresses that were identified.
-
getAllLocalAddresses
@NotNull public static java.util.Set<java.net.InetAddress> getAllLocalAddresses(@Nullable NameResolver nameResolver, boolean includeLoopback)
Attempts to determine all addresses associated with the local system, optionally including loopback addresses.- Parameters:
nameResolver
- The name resolver to use to determine the local host and loopback addresses. If this isnull
, then the LDAP SDK's default name resolver will be used.includeLoopback
- Indicates whether to include loopback addresses in the set that is returned.- Returns:
- A set of the local addresses that were identified.
-
getCanonicalHostNameIfAvailable
@Nullable public static java.lang.String getCanonicalHostNameIfAvailable(@Nullable NameResolver nameResolver, @NotNull java.net.InetAddress address)
Retrieves the canonical host name for the provided address, if it can be resolved to a name.- Parameters:
nameResolver
- The name resolver to use to obtain the canonical host name. If this isnull
, then the LDAP SDK's default name resolver will be used.address
- TheInetAddress
for which to attempt to obtain the canonical host name.- Returns:
- The canonical host name for the provided address, or
null
if it cannot be obtained (either because the attempt returnsnull
, which shouldn't happen, or because it matches the IP address).
-
getAvailableCanonicalHostNames
@NotNull public static java.util.Set<java.lang.String> getAvailableCanonicalHostNames(@Nullable NameResolver nameResolver, @NotNull java.util.Collection<java.net.InetAddress> addresses)
Retrieves the canonical host names for the provided set ofInetAddress
objects. If any of the provided addresses cannot be resolved to a canonical host name (in which case the attempt to get the canonical host name will return its IP address), it will be excluded from the returned set.- Parameters:
nameResolver
- The name resolver to use to obtain the canonical host names. If this isnull
, then the LDAP SDK's default name resolver will be used.addresses
- The set of addresses for which to obtain the canonical host names.- Returns:
- A set of the canonical host names that could be obtained from the provided addresses.
-
trimInterfaceNameFromHostAddress
@NotNull public static java.lang.String trimInterfaceNameFromHostAddress(@NotNull java.lang.String hostAddress)
Retrieves a version of the provided host address with the interface name stripped off. Java sometimes follows an IP address with a percent sign and the interface name. If that interface name is present in the provided host address, then this method will trim it off, leaving just the IP address. If the provided host address does not include the interface name, then the provided address will be returned as-is.- Parameters:
hostAddress
- The host address to be trimmed.- Returns:
- The provided host address without the interface name.
-
isIANAReservedIPAddress
public static boolean isIANAReservedIPAddress(@NotNull java.net.InetAddress address, boolean includePrivateUseNetworkAddresses)
Indicates whether the provided address is marked as reserved in the IANA IPv4 address space registry at https://www.iana.org/assignments/ipv4-address-space/ipv4-address-space.txt or the IPv6 address space registry at https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.txt.- Parameters:
address
- The address for which to make the determination. It must not benull
, and it must be an IPv4 or IPv6 address.includePrivateUseNetworkAddresses
- Indicates whether to consider addresses in a private-use network address range (including 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, and fc00::/7) as reserved addresses. If this istrue
, then this method will returntrue
for addresses in a private-use network range; if it isfalse
, then this method will returnfalse
for addresses in those ranges. This does not have any effect for addresses in other reserved address ranges.- Returns:
true
if the provided address is in a reserved address range, orfalse
if not.
-
isIANAReservedIPv4Address
public static boolean isIANAReservedIPv4Address(@NotNull java.net.Inet4Address address, boolean includePrivateUseNetworkAddresses)
Indicates whether the provided address is marked as reserved in the IANA IPv4 address space registry at https://www.iana.org/assignments/ipv4-address-space/ipv4-address-space.txt. This implementation is based on the version of the registry that was updated on 2019-12-27.- Parameters:
address
- The IPv4 address for which to make the determination. It must not benull
, and it must be an IPv4 address.includePrivateUseNetworkAddresses
- Indicates whether to consider addresses in a private-use network address range as reserved addresses.- Returns:
true
if the provided address is in a reserved address range, orfalse
if not.
-
isIANAReservedIPv6Address
public static boolean isIANAReservedIPv6Address(@NotNull java.net.Inet6Address address, boolean includePrivateUseNetworkAddresses)
Indicates whether the provided address is marked as reserved in the IANA IPv6 address space registry at https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.txt. This implementation is based on the version of the registry that was updated on 2019-09-13.- Parameters:
address
- The IPv4 address for which to make the determination. It must not benull
, and it must be an IPv6 address.includePrivateUseNetworkAddresses
- Indicates whether to consider addresses in a private-use network address range as reserved addresses.- Returns:
true
if the provided address is in a reserved address range, orfalse
if not.
-
readFileBytes
@NotNull public static byte[] readFileBytes(@NotNull java.lang.String path) throws java.io.IOException
Reads the bytes that comprise the specified file.- Parameters:
path
- The path to the file to be read.- Returns:
- The bytes that comprise the specified file.
- Throws:
java.io.IOException
- If a problem occurs while trying to read the file.
-
readFileBytes
@NotNull public static byte[] readFileBytes(@NotNull java.io.File file) throws java.io.IOException
Reads the bytes that comprise the specified file.- Parameters:
file
- The file to be read.- Returns:
- The bytes that comprise the specified file.
- Throws:
java.io.IOException
- If a problem occurs while trying to read the file.
-
readFileAsString
@NotNull public static java.lang.String readFileAsString(@NotNull java.lang.String path, boolean includeFinalLineBreak) throws java.io.IOException
Reads the contents of the specified file as a string. All line breaks in the file will be preserved, with the possible exception of the one on the last line.- Parameters:
path
- The path to the file to be read.includeFinalLineBreak
- Indicates whether the final line break (if there is one) should be preserved.- Returns:
- The contents of the specified file as a string.
- Throws:
java.io.IOException
- If a problem occurs while trying to read the file.
-
readFileAsString
@NotNull public static java.lang.String readFileAsString(@NotNull java.io.File file, boolean includeFinalLineBreak) throws java.io.IOException
Reads the contents of the specified file as a string. All line breaks in the file will be preserved, with the possible exception of the one on the last line.- Parameters:
file
- The file to be read.includeFinalLineBreak
- Indicates whether the final line break (if there is one) should be preserved.- Returns:
- The contents of the specified file as a string.
- Throws:
java.io.IOException
- If a problem occurs while trying to read the file.
-
readFileLines
@NotNull public static java.util.List<java.lang.String> readFileLines(@NotNull java.lang.String path) throws java.io.IOException
Reads the lines that comprise the specified file.- Parameters:
path
- The path to the file to be read.- Returns:
- The lines that comprise the specified file.
- Throws:
java.io.IOException
- If a problem occurs while trying to read the file.
-
readFileLines
@NotNull public static java.util.List<java.lang.String> readFileLines(@NotNull java.io.File file) throws java.io.IOException
Reads the lines that comprise the specified file.- Parameters:
file
- The file to be read.- Returns:
- The lines that comprise the specified file.
- Throws:
java.io.IOException
- If a problem occurs while trying to read the file.
-
writeFile
public static void writeFile(@NotNull java.lang.String path, @NotNull byte[] bytes) throws java.io.IOException
Writes the provided bytes to the specified file. If the file already exists, it will be overwritten.- Parameters:
path
- The path to the file to be written.bytes
- The bytes to be written to the specified file.- Throws:
java.io.IOException
- If a problem is encountered while writing the file.
-
writeFile
public static void writeFile(@NotNull java.io.File file, @NotNull byte[] bytes) throws java.io.IOException
Writes the provided bytes to the specified file. If the file already exists, it will be overwritten.- Parameters:
file
- The file to be written.bytes
- The bytes to be written to the specified file.- Throws:
java.io.IOException
- If a problem is encountered while writing the file.
-
writeFile
public static void writeFile(@NotNull java.lang.String path, @NotNull java.lang.CharSequence... lines) throws java.io.IOException
Writes the provided lines to the specified file, with each followed by an appropriate end-of-line marker for the current platform. If the file already exists, it will be overwritten.- Parameters:
path
- The path to the file to be written.lines
- The lines to be written to the specified file.- Throws:
java.io.IOException
- If a problem is encountered while writing the file.
-
writeFile
public static void writeFile(@NotNull java.io.File file, @NotNull java.lang.CharSequence... lines) throws java.io.IOException
Writes the provided lines to the specified file, with each followed by an appropriate end-of-line marker for the current platform. If the file already exists, it will be overwritten.- Parameters:
file
- The file to be written.lines
- The lines to be written to the specified file.- Throws:
java.io.IOException
- If a problem is encountered while writing the file.
-
writeFile
public static void writeFile(@NotNull java.lang.String path, @Nullable java.util.List<? extends java.lang.CharSequence> lines) throws java.io.IOException
Writes the provided lines to the specified file, with each followed by an appropriate end-of-line marker for the current platform. If the file already exists, it will be overwritten.- Parameters:
path
- The path to the file to be written.lines
- The lines to be written to the specified file.- Throws:
java.io.IOException
- If a problem is encountered while writing the file.
-
writeFile
public static void writeFile(@NotNull java.io.File file, @Nullable java.util.List<? extends java.lang.CharSequence> lines) throws java.io.IOException
Writes the provided lines to the specified file, with each followed by an appropriate end-of-line marker for the current platform. If the file already exists, it will be overwritten.- Parameters:
file
- The file to be written.lines
- The lines to be written to the specified file.- Throws:
java.io.IOException
- If a problem is encountered while writing the file.
-
randomBytes
@NotNull public static byte[] randomBytes(int numBytes, boolean secure)
Retrieves a byte array with the specified number of randomly selected bytes.- Parameters:
numBytes
- The number of bytes of random data to retrieve. It must be greater than or equal to zero.secure
- Indicates whether to use a cryptographically secure random number generator.- Returns:
- A byte array with the specified number of randomly selected bytes.
-
randomInt
public static int randomInt(int lowerBound, int upperBound, boolean secure)
Retrieves a randomly selected integer between the given upper and lower bounds.- Parameters:
lowerBound
- The lowest value that may be selected at random. It must be less than or equal to the upper bound.upperBound
- The highest value that may be selected at random. It must be greater than or equal to the lower bound.secure
- Indicates whether to use a cryptographically secure random number generator.- Returns:
- A randomly selected integer between the given upper and lower bounds.
-
randomAlphabeticString
@NotNull public static java.lang.String randomAlphabeticString(int length, boolean secure)
Retrieves a string containing the specified number of randomly selected ASCII letters. It will contain only lowercase letters.- Parameters:
length
- The number of letters to include in the string. It must be greater than or equal to zero.secure
- Indicates whether to use a cryptographically secure random number generator.- Returns:
- The randomly generated alphabetic string.
-
randomNumericString
@NotNull public static java.lang.String randomNumericString(int length, boolean secure)
Retrieves a string containing the specified number of randomly selected ASCII numeric digits.- Parameters:
length
- The number of digits to include in the string. It must be greater than or equal to zero.secure
- Indicates whether to use a cryptographically secure random number generator.- Returns:
- The randomly generated numeric string.
-
randomAlphanumericString
@NotNull public static java.lang.String randomAlphanumericString(int length, boolean secure)
Retrieves a string containing the specified number of randomly selected ASCII alphanumeric characters. It may contain a mix of lowercase letters, uppercase letters, and numeric digits.- Parameters:
length
- The number of characters to include in the string. It must be greater than or equal to zero.secure
- Indicates whether to use a cryptographically secure random number generator.- Returns:
- The randomly generated alphanumeric string.
-
randomString
@NotNull public static java.lang.String randomString(int length, @NotNull char[] allowedChars, boolean secure)
Retrieves a string containing the specified number of randomly selected characters from the given set.- Parameters:
length
- The number of characters to include in the string. It must be greater than or equal to zero.allowedChars
- The set of characters that are allowed to be included in the string. It must not benull
or empty.secure
- Indicates whether to use a cryptographically secure random number generator.- Returns:
- The randomly generated string.
-
-