Class StaticUtils

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String EOL
      The end-of-line marker for this platform.
      static byte[] EOL_BYTES
      A byte array containing the end-of-line marker for this platform.
      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 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 are null or both are logically equal (using the equals method).
      static boolean bothNullOrEqualIgnoreCase​(java.lang.String s1, java.lang.String s2)
      Indicates whether both of the provided strings are null or both are logically equal ignoring differences in capitalization (using the equalsIgnoreCase 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 a File object from the provided path.
      static java.io.IOException createIOExceptionWithCause​(java.lang.String message, java.lang.Throwable cause)
      Creates a new IOException 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.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 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.
      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 of InetAddress objects.
      static byte[] getBytes​(java.lang.String s)
      Retrieves a UTF-8 byte representation of the provided string.
      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 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 provided Throwable 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 provided Throwable 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 the toCode 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 provided Throwable.
      static void getStackTrace​(java.lang.Throwable t, java.lang.StringBuilder buffer)
      Appends a single-line string representation of the stack trace for the provided Throwable 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 a TimeZone object that represents the UTC (universal coordinated time) time zone.
      static <T> java.util.HashSet<T> hashSetOf​(T... items)
      Creates a HashSet 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 isHex​(char c)
      Indicates whether the provided character is a valid hexadecimal digit.
      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 isSensitiveToCodeAttribute​(java.lang.String name)
      Indicates whether the provided attribute name should be considered a sensitive attribute for the purposes of toCode methods.
      static boolean isValidUTF8​(byte[] b)
      Indicates whether the contents of the provided array are valid UTF-8.
      static boolean isWindows()
      Returns true 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 a LinkedHashSet 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 void rethrowIfError​(java.lang.Throwable throwable)
      Re-throws the provided Throwable instance only if it is an Error; otherwise, this method will return without taking any action.
      static void rethrowIfErrorOrRuntimeException​(java.lang.Throwable throwable)
      Re-throws the provided Throwable instance only if it is an Error or a RuntimeException 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 the toCode 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 the toCode 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 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 an Error or a RuntimeException based on the provided Throwable 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, 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 a TreeSet 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 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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • NO_BYTES

        public static final byte[] NO_BYTES
        A pre-allocated byte array containing zero bytes.
      • NO_CHARS

        public static final char[] NO_CHARS
        A pre-allocated empty character array.
      • NO_CONTROLS

        public static final Control[] NO_CONTROLS
        A pre-allocated empty control array.
      • NO_STRINGS

        public static final java.lang.String[] NO_STRINGS
        A pre-allocated empty string array.
      • EOL

        public static final java.lang.String EOL
        The end-of-line marker for this platform.
      • EOL_BYTES

        public static final byte[] EOL_BYTES
        A byte array containing the end-of-line marker for this platform.
      • TERMINAL_WIDTH_COLUMNS

        public static final int TERMINAL_WIDTH_COLUMNS
        The width of the terminal window, in columns.
    • Method Detail

      • getBytes

        public static byte[] getBytes​(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.
      • isASCIIString

        public 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. 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 be null.
        Returns:
        true if the contents of the provided array represent an ASCII string, or false 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, or false if not.
      • isPrintableString

        public 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. 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.
        If the provided array contains anything other than the above characters (i.e., if the byte array contains any non-ASCII characters, or any ASCII control characters, or if it contains excluded ASCII characters like the exclamation point, double quote, octothorpe, dollar sign, etc.), then it will not be considered printable.
        Parameters:
        b - The byte array for which to make the determination. It must not be null.
        Returns:
        true if the contents of the provided byte array represent a printable LDAP string, or false if not.
      • isValidUTF8

        public static boolean isValidUTF8​(byte[] b)
        Indicates whether the contents of the provided array are valid UTF-8.
        Parameters:
        b - The byte array to examine. It must not be null.
        Returns:
        true if the byte array can be parsed as a valid UTF-8 string, or false if not.
      • toUTF8String

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

        public 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.
        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.
      • toInitialLowerCase

        public 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.
        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.
      • toLowerCase

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

        public static java.lang.String toUpperCase​(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.
      • 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, or false if not.
      • toHex

        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,
                                 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 java.lang.String toHex​(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 be null.
        Returns:
        A string containing a hexadecimal representation of the contents of the provided byte array.
      • toHex

        public static void toHex​(byte[] b,
                                 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 be null.
        buffer - A buffer to which the hexadecimal representation of the contents of the provided byte array should be appended.
      • toHex

        public 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. 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 be null.
        delimiter - A delimiter to be inserted between bytes. It may be null 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

        public 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. 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​(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. 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

        public static byte[] fromHex​(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 be null, 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,
                                     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,
                                     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​(byte[] array,
                                           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 be null.
        buffer - The buffer to which the code should be appended.
      • getStackTrace

        public static java.lang.String getStackTrace​(java.lang.Throwable t)
        Retrieves a single-line string representation of the stack trace for the provided Throwable. It will include the unqualified name of the Throwable 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 - The Throwable 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​(java.lang.Throwable t,
                                         java.lang.StringBuilder buffer)
        Appends a single-line string representation of the stack trace for the provided Throwable to the given buffer. It will include the unqualified name of the Throwable 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 - The Throwable for which to retrieve the stack trace.
        buffer - The buffer to which the information should be appended.
      • getStackTrace

        public static java.lang.String getStackTrace​(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​(java.lang.StackTraceElement[] elements,
                                         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​(java.lang.StackTraceElement[] elements,
                                         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

        public static java.lang.String getExceptionMessage​(java.lang.Throwable t)
        Retrieves a string representation of the provided Throwable 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 its getExceptionMessage 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 - The Throwable for which to generate the exception message.
        Returns:
        A string representation of the provided Throwable object suitable for use in a message.
      • getExceptionMessage

        public static java.lang.String getExceptionMessage​(java.lang.Throwable t,
                                                           boolean includeCause,
                                                           boolean includeStackTrace)
        Retrieves a string representation of the provided Throwable 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 its getExceptionMessage 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 - The Throwable 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

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

        public static java.util.TimeZone getUTCTimeZone()
        Retrieves a TimeZone object that represents the UTC (universal coordinated time) time zone.
        Returns:
        A TimeZone object that represents the UTC time zone.
      • encodeGeneralizedTime

        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 the System.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

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

        public static java.util.Date decodeGeneralizedTime​(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 be null.
        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.
      • trimLeading

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

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

        public 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. 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 be null.
        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

        public 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. 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 be null.
        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 unless maxFirstLineWidth 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

        public 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. This method is provided as a convenience wrapper around ExampleCommandLineArgument. 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, call ExampleCommandLineArgument.getCleanArgument(java.lang.String).
        Parameters:
        s - The string to be processed. It must not be null.
        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

        public static java.lang.String concatenateStrings​(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 be null.
        Returns:
        A string containing a concatenation of all of the strings in the provided array.
      • concatenateStrings

        public 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.
        Parameters:
        l - The list of strings to concatenate. It must not be null.
        Returns:
        A string containing a concatenation of all of the strings in the provided list.
      • concatenateStrings

        public 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.
        Parameters:
        beforeList - A string that should be placed at the beginning of the list. It may be null 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 be null or empty if nothing should be placed before each element.
        betweenElements - The separator that should be placed between elements in the list. It may be null 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 be null 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 be null or empty if nothing should be placed at the end of the list.
        a - The array of strings to concatenate. It must not be null.
        Returns:
        A string containing a concatenation of all of the strings in the provided list.
      • concatenateStrings

        public 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.
        Parameters:
        beforeList - A string that should be placed at the beginning of the list. It may be null 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 be null or empty if nothing should be placed before each element.
        betweenElements - The separator that should be placed between elements in the list. It may be null 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 be null 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 be null or empty if nothing should be placed at the end of the list.
        l - The list of strings to concatenate. It must not be null.
        Returns:
        A string containing a concatenation of all of the strings in the provided list.
      • secondsToHumanReadableDuration

        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

        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​(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 be null.
        Returns:
        true if the provided string is a valid numeric OID, or false if not.
      • capitalize

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

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

        public static byte[] encodeUUID​(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 be null.
        Returns:
        The byte array containing the 128-bit encoded UUID.
      • decodeUUID

        public static java.util.UUID decodeUUID​(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 be null.
        Returns:
        The decoded UUID.
        Throws:
        java.text.ParseException - If the provided byte array cannot be parsed as a UUID.
      • isWindows

        public static boolean isWindows()
        Returns true 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 and false otherwise.
      • toArgumentList

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

        public static <T> T[] toArray​(java.util.Collection<T> collection,
                                      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.
      • toList

        public 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. This method behaves much like Arrays.asList, except that if the provided array is null, then it will return a null 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 was null.
      • toNonNullList

        public 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. This method behaves much like Arrays.asList, except that if the provided array is null, 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​(java.lang.Object o1,
                                              java.lang.Object o2)
        Indicates whether both of the provided objects are null or both are logically equal (using the equals 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 are null or both are logically equal, or false if only one of the objects is null or they are not logically equal.
      • bothNullOrEqualIgnoreCase

        public static boolean bothNullOrEqualIgnoreCase​(java.lang.String s1,
                                                        java.lang.String s2)
        Indicates whether both of the provided strings are null or both are logically equal ignoring differences in capitalization (using the equalsIgnoreCase 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 are null or both are logically equal ignoring differences in capitalization, or false if only one of the objects is null or they are not logically equal ignoring capitalization.
      • stringsEqualIgnoreCaseOrderIndependent

        public 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. It is assumed that neither array contains null 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, or false if not.
      • arraysEqualOrderIndependent

        public static <T> boolean arraysEqualOrderIndependent​(T[] a1,
                                                              T[] a2)
        Indicates whether the provided arrays have the same elements, ignoring the order in which they appear. It is assumed that neither array contains null 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, or false 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​(java.lang.String name)
        Indicates whether the provided attribute name should be considered a sensitive attribute for the purposes of toCode methods. If an attribute is considered sensitive, then its values will be redacted in the output of the toCode methods.
        Parameters:
        name - The name for which to make the determination. It may or may not include attribute options. It must not be null.
        Returns:
        true if the specified attribute is one that should be considered sensitive for the
      • getSensitiveToCodeAttributeBaseNames

        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 the toCode 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​(java.lang.String... names)
        Specifies the names of any attributes that should be considered sensitive for the purposes of the toCode methods.
        Parameters:
        names - The names of any attributes that should be considered sensitive for the purposes of the toCode methods. It may be null or empty if no attributes should be considered sensitive.
      • setSensitiveToCodeAttributes

        public 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 the toCode methods.
        Parameters:
        names - The names of any attributes that should be considered sensitive for the purposes of the toCode methods. It may be null or empty if no attributes should be considered sensitive.
      • createIOExceptionWithCause

        public static java.io.IOException createIOExceptionWithCause​(java.lang.String message,
                                                                     java.lang.Throwable cause)
        Creates a new IOException 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 be null if the message should be generated from the provided cause.
        cause - The underlying cause for the exception. It may be null if the exception should have only a message.
        Returns:
        The IOException object that was created.
      • stringToLines

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

        public 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).
        Parameters:
        lines - The lines to include in the string.
        Returns:
        The string resulting from concatenating the provided lines with line breaks.
      • linesToString

        public 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).
        Parameters:
        lines - The lines to include in the string.
        Returns:
        The string resulting from concatenating the provided lines with line breaks.
      • constructPath

        public static java.io.File constructPath​(java.io.File baseDirectory,
                                                 java.lang.String... pathElements)
        Constructs a File object from the provided path.
        Parameters:
        baseDirectory - The base directory to use as the starting point. It must not be null 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 be null or empty if the base directory should be used.
        Returns:
        The constructed File object.
      • byteArray

        public static byte[] byteArray​(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, or false if not.
      • throwErrorOrRuntimeException

        public static void throwErrorOrRuntimeException​(java.lang.Throwable throwable)
                                                 throws java.lang.Error,
                                                        java.lang.RuntimeException
        Throws an Error or a RuntimeException based on the provided Throwable object. This method will always throw something, regardless of the provided Throwable object.
        Parameters:
        throwable - The Throwable object to use to create the exception to throw.
        Throws:
        java.lang.Error - If the provided Throwable object is an Error instance, then that Error instance will be re-thrown.
        java.lang.RuntimeException - If the provided Throwable object is a RuntimeException instance, then that RuntimeException instance will be re-thrown. Otherwise, it must be a checked exception and that checked exception will be re-thrown as a RuntimeException.
      • rethrowIfErrorOrRuntimeException

        public static void rethrowIfErrorOrRuntimeException​(java.lang.Throwable throwable)
                                                     throws java.lang.Error,
                                                            java.lang.RuntimeException
        Re-throws the provided Throwable instance only if it is an Error or a RuntimeException instance; otherwise, this method will return without taking any action.
        Parameters:
        throwable - The Throwable object to examine and potentially re-throw.
        Throws:
        java.lang.Error - If the provided Throwable object is an Error instance, then that Error instance will be re-thrown.
        java.lang.RuntimeException - If the provided Throwable object is a RuntimeException instance, then that RuntimeException instance will be re-thrown.
      • rethrowIfError

        public static void rethrowIfError​(java.lang.Throwable throwable)
                                   throws java.lang.Error
        Re-throws the provided Throwable instance only if it is an Error; otherwise, this method will return without taking any action.
        Parameters:
        throwable - The Throwable object to examine and potentially re-throw.
        Throws:
        java.lang.Error - If the provided Throwable object is an Error instance, then that Error 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
        public static <T> java.util.Set<T> setOf​(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 be null, but may be empty.
        Returns:
        An unmodifiable set containing the provided items.
      • hashSetOf

        @SafeVarargs
        public static <T> java.util.HashSet<T> hashSetOf​(T... items)
        Creates a HashSet 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 be null, but may be empty.
        Returns:
        A HashSet containing the provided items.
      • linkedHashSetOf

        @SafeVarargs
        public static <T> java.util.LinkedHashSet<T> linkedHashSetOf​(T... items)
        Creates a LinkedHashSet 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 be null, but may be empty.
        Returns:
        A LinkedHashSet containing the provided items.
      • treeSetOf

        @SafeVarargs
        public static <T> java.util.TreeSet<T> treeSetOf​(T... items)
        Creates a TreeSet 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 be null, but may be empty.
        Returns:
        A LinkedHashSet containing the provided items.
      • mapOf

        public static <K,​V> java.util.Map<K,​V> mapOf​(K key,
                                                                 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

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

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

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

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

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

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

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

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

        public 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.
        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
        public static <T> java.util.Map<T,​T> mapOf​(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
        public static <K,​V> java.util.Map<K,​V> mapOfObjectPairs​(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.
      • getSystemProperties

        public static java.util.Properties getSystemProperties​(java.lang.String... propertyNames)
        Retrieves the set of currently defined system properties. If possible, this will simply return the result of a call to System.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 to System.getProperties will be rejected with a SecurityException because the returned structure is mutable and could be used to alter system property values. In such cases, a new empty Properties 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 the Properties object that will be returned if a security manager prevents retrieving the full set of system properties. This may be null 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

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

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

        public static java.lang.String setSystemProperty​(java.lang.String name,
                                                         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 be null.
        value - The value to use for the system property. If it is null, 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).
      • clearSystemProperty

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

        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

        public static java.lang.String getEnvironmentVariable​(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).
      • setLoggerLevel

        public static void setLoggerLevel​(java.util.logging.Logger logger,
                                          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​(java.util.logging.Handler logHandler,
                                              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.
      • getAllLocalAddresses

        public static java.util.Set<java.net.InetAddress> getAllLocalAddresses​(NameResolver nameResolver)
        Attempts to determine all addresses associated with the local system.
        Parameters:
        nameResolver - The name resolver to use to determine the local host and loopback addresses. If this is null, then the LDAP SDK's default name resolver will be used.
        Returns:
        A set of the local addresses that were identified.
      • getCanonicalHostNameIfAvailable

        public 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.
        Parameters:
        nameResolver - The name resolver to use to obtain the canonical host name. If this is null, then the LDAP SDK's default name resolver will be used.
        address - The InetAddress 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 returns null, which shouldn't happen, or because it matches the IP address).
      • getAvailableCanonicalHostNames

        public 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 of InetAddress 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 is null, 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

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

        public static java.lang.String getEnvironmentVariable​(java.lang.String name,
                                                              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 be null 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.