com.unboundid.util.StaticUtils Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of unboundid-ldapsdk Show documentation
Show all versions of unboundid-ldapsdk Show documentation
The UnboundID LDAP SDK for Java is a fast, comprehensive, and easy-to-use
Java API for communicating with LDAP directory servers and performing
related tasks like reading and writing LDIF, encoding and decoding data
using base64 and ASN.1 BER, and performing secure communication. This
package contains the Standard Edition of the LDAP SDK, which is a
complete, general-purpose library for communicating with LDAPv3 directory
servers.
/*
* Copyright 2007-2022 Ping Identity Corporation
* All Rights Reserved.
*/
/*
* Copyright 2007-2022 Ping Identity Corporation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* Copyright (C) 2007-2022 Ping Identity Corporation
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License (GPLv2 only)
* or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see .
*/
package com.unboundid.util;
import java.io.BufferedReader;
import java.io.File;
import java.io.FileOutputStream;
import java.io.FileReader;
import java.io.IOException;
import java.io.PrintWriter;
import java.io.StringReader;
import java.lang.reflect.Array;
import java.net.Inet4Address;
import java.net.Inet6Address;
import java.net.InetAddress;
import java.net.NetworkInterface;
import java.nio.charset.StandardCharsets;
import java.text.DecimalFormat;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.Collections;
import java.util.Date;
import java.util.Enumeration;
import java.util.GregorianCalendar;
import java.util.HashSet;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.Properties;
import java.util.Random;
import java.util.Set;
import java.util.StringTokenizer;
import java.util.TimeZone;
import java.util.TreeSet;
import java.util.UUID;
import java.util.logging.Handler;
import java.util.logging.Level;
import java.util.logging.Logger;
import com.unboundid.ldap.sdk.Attribute;
import com.unboundid.ldap.sdk.Control;
import com.unboundid.ldap.sdk.LDAPConnectionOptions;
import com.unboundid.ldap.sdk.NameResolver;
import com.unboundid.ldap.sdk.Version;
import static com.unboundid.util.UtilityMessages.*;
/**
* This class provides a number of static utility functions.
*/
@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
public final class StaticUtils
{
/**
* A pre-allocated byte array containing zero bytes.
*/
@NotNull public static final byte[] NO_BYTES = new byte[0];
/**
* A pre-allocated empty character array.
*/
@NotNull public static final char[] NO_CHARS = new char[0];
/**
* A pre-allocated empty control array.
*/
@NotNull public static final Control[] NO_CONTROLS = new Control[0];
/**
* A pre-allocated empty integer array.
*/
@NotNull public static final int[] NO_INTS = new int[0];
/**
* A pre-allocated empty string array.
*/
@NotNull public static final String[] NO_STRINGS = new String[0];
/**
* The end-of-line marker for the platform on which the LDAP SDK is
* currently running.
*/
@NotNull public static final String EOL =
getSystemProperty("line.separator", "\n");
/**
* The end-of-line marker that consists of a carriage return character
* followed by a line feed character, as used on Windows systems.
*/
@NotNull public static final String EOL_CR_LF = "\r\n";
/**
* The end-of-line marker that consists of just the line feed character, as
* used on UNIX-based systems.
*/
@NotNull public static final String EOL_LF = "\n";
/**
* A byte array containing the end-of-line marker for the platform on which
* the LDAP SDK is currently running.
*/
@NotNull public static final byte[] EOL_BYTES = getBytes(EOL);
/**
* A byte array containing the end-of-line marker that consists of a carriage
* return character followed by a line feed character, as used on Windows
* systems.
*/
@NotNull public static final byte[] EOL_BYTES_CR_LF = getBytes(EOL_CR_LF);
/**
* A byte array containing the end-of-line marker that consists of just the
* line feed character, as used on UNIX-based systems.
*/
@NotNull public static final byte[] EOL_BYTES_LF = getBytes(EOL_LF);
/**
* Indicates whether the unit tests are currently running.
*/
private static final boolean IS_WITHIN_UNIT_TESTS =
Boolean.getBoolean("com.unboundid.ldap.sdk.RunningUnitTests") ||
Boolean.getBoolean("com.unboundid.directory.server.RunningUnitTests");
/**
* The thread-local date formatter used to encode generalized time values.
*/
@NotNull private static final ThreadLocal
GENERALIZED_TIME_FORMATTERS = new ThreadLocal<>();
/**
* The thread-local date formatter used to encode RFC 3339 time values.
*/
@NotNull private static final ThreadLocal
RFC_3339_TIME_FORMATTERS = new ThreadLocal<>();
/**
* The {@code TimeZone} object that represents the UTC (universal coordinated
* time) time zone.
*/
@NotNull private static final TimeZone UTC_TIME_ZONE =
TimeZone.getTimeZone("UTC");
/**
* A set containing the names of attributes that will be considered sensitive
* by the {@code toCode} methods of various request and data structure types.
*/
@NotNull private static volatile Set
TO_CODE_SENSITIVE_ATTRIBUTE_NAMES = setOf("userpassword", "2.5.4.35",
"authpassword", "1.3.6.1.4.1.4203.1.3.4");
/**
* The width of the terminal window, in columns.
*/
public static final int TERMINAL_WIDTH_COLUMNS;
static
{
// Try to dynamically determine the size of the terminal window using the
// COLUMNS environment variable.
int terminalWidth = 80;
final String columnsEnvVar = getEnvironmentVariable("COLUMNS");
if (columnsEnvVar != null)
{
try
{
terminalWidth = Integer.parseInt(columnsEnvVar);
}
catch (final Exception e)
{
Debug.debugException(e);
}
}
TERMINAL_WIDTH_COLUMNS = terminalWidth;
}
/**
* An array containing the set of lowercase ASCII letters.
*/
@NotNull private static final char[] LOWERCASE_LETTERS =
"abcdefghijklmnopqrstuvwxyz".toCharArray();
/**
* An array containing the set of ASCII numeric digits.
*/
@NotNull private static final char[] NUMERIC_DIGITS =
"0123456789".toCharArray();
/**
* An array containing the set of ASCII alphanumeric characters. It will
* include both uppercase and lowercase letters.
*/
@NotNull private static final char[] ALPHANUMERIC_CHARACTERS =
("abcdefghijklmnopqrstuvwxyz" +
"ABCDEFGHIJKLMNOPQRSTUVWXYZ" +
"0123456789").toCharArray();
/**
* Prevent this class from being instantiated.
*/
private StaticUtils()
{
// No implementation is required.
}
/**
* Retrieves the set of currently defined system properties. If possible,
* this will simply return the result of a call to
* {@code 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 {@code System.getProperties} will be rejected
* with a {@code SecurityException} because the returned structure is mutable
* and could be used to alter system property values. In such cases, a new
* empty {@code Properties} object will be created, and may optionally be
* populated with the values of a specific set of named properties.
*
* @param propertyNames An optional set of property names whose values (if
* defined) should be included in the
* {@code Properties} object that will be returned if a
* security manager prevents retrieving the full set of
* system properties. This may be {@code null} or
* empty if no specific properties should be retrieved.
*
* @return The value returned by a call to {@code 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.
*/
@NotNull()
public static Properties getSystemProperties(
@Nullable final String... propertyNames)
{
try
{
final Properties properties = System.getProperties();
final String forceThrowPropertyName =
StaticUtils.class.getName() + ".forceGetSystemPropertiesToThrow";
// To ensure that we can get coverage for the code below in which there is
// a restrictive security manager in place, look for a system property
// that will cause us to throw an exception.
final Object forceThrowPropertyValue =
properties.getProperty(forceThrowPropertyName);
if (forceThrowPropertyValue != null)
{
throw new SecurityException(forceThrowPropertyName + '=' +
forceThrowPropertyValue);
}
return properties;
}
catch (final SecurityException e)
{
Debug.debugException(e);
}
// If we have gotten here, then we can assume that a security manager
// prevents us from accessing all system properties. Create a new proper
final Properties properties = new Properties();
if (propertyNames != null)
{
for (final String propertyName : propertyNames)
{
final Object propertyValue = System.getProperty(propertyName);
if (propertyValue != null)
{
properties.put(propertyName, propertyValue);
}
}
}
return properties;
}
/**
* Retrieves the value of the specified system property.
*
* @param name The name of the system property for which to retrieve the
* value.
*
* @return The value of the requested system property, or {@code null} if
* that variable was not set or its value could not be retrieved
* (for example, because a security manager prevents it).
*/
@Nullable()
public static String getSystemProperty(@NotNull final String name)
{
try
{
return System.getProperty(name);
}
catch (final Throwable t)
{
// It is possible that the call to System.getProperty could fail under
// some security managers. In that case, simply swallow the error and
// act as if that system property is not set.
Debug.debugException(t);
return null;
}
}
/**
* Retrieves the value of the specified system property.
*
* @param name The name of the system property for which to retrieve
* the value.
* @param defaultValue The default value to return if the specified
* system property is not set or could not be
* retrieved.
*
* @return 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).
*/
@Nullable()
public static String getSystemProperty(@NotNull final String name,
@Nullable final String defaultValue)
{
try
{
return System.getProperty(name, defaultValue);
}
catch (final Throwable t)
{
// It is possible that the call to System.getProperty could fail under
// some security managers. In that case, simply swallow the error and
// act as if that system property is not set.
Debug.debugException(t);
return defaultValue;
}
}
/**
* 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.
*
* @param name The name of the System property to set. It must not be
* {@code null}.
* @param value The value to use for the system property. If it is
* {@code null}, then the property will be cleared.
*
* @return The former value of the system property, or {@code null} if it
* did not have a value or if it could not be set (for example,
* because a security manager prevents it).
*/
@Nullable()
public static String setSystemProperty(@NotNull final String name,
@Nullable final String value)
{
try
{
if (value == null)
{
return System.clearProperty(name);
}
else
{
return System.setProperty(name, value);
}
}
catch (final Throwable t)
{
// It is possible that the call to System.setProperty or
// System.clearProperty could fail under some security managers. In that
// case, simply swallow the error and act as if that system property is
// not set.
Debug.debugException(t);
return null;
}
}
/**
* 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.
*
* @param name The name of the System property to clear. It must not be
* {@code null}.
*
* @return The former value of the system property, or {@code null} if it
* did not have a value or if it could not be set (for example,
* because a security manager prevents it).
*/
@Nullable()
public static String clearSystemProperty(@NotNull final String name)
{
try
{
return System.clearProperty(name);
}
catch (final Throwable t)
{
// It is possible that the call to System.clearProperty could fail under
// some security managers. In that case, simply swallow the error and
// act as if that system property is not set.
Debug.debugException(t);
return null;
}
}
/**
* Retrieves a map of all environment variables defined in the JVM's process.
*
* @return 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).
*/
@NotNull()
public static Map getEnvironmentVariables()
{
try
{
return System.getenv();
}
catch (final Throwable t)
{
// It is possible that the call to System.getenv could fail under some
// security managers. In that case, simply swallow the error and pretend
// that the environment variable is not set.
Debug.debugException(t);
return Collections.emptyMap();
}
}
/**
* Retrieves the value of the specified environment variable.
*
* @param name The name of the environment variable for which to retrieve
* the value.
*
* @return The value of the requested environment variable, or {@code null}
* if that variable was not set or its value could not be retrieved
* (for example, because a security manager prevents it).
*/
@Nullable()
public static String getEnvironmentVariable(@NotNull final String name)
{
try
{
return System.getenv(name);
}
catch (final Throwable t)
{
// It is possible that the call to System.getenv could fail under some
// security managers. In that case, simply swallow the error and pretend
// that the environment variable is not set.
Debug.debugException(t);
return null;
}
}
/**
* Retrieves the value of the specified environment variable.
*
* @param name The name of the environment variable for which to
* retrieve the value.
* @param defaultValue The default value to use if the specified environment
* variable is not set. It may be {@code null} if no
* default should be used.
*
* @return The value of the requested environment variable, or {@code 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.
*/
@Nullable()
public static String getEnvironmentVariable(@NotNull final String name,
@Nullable final String defaultValue)
{
final String value = getEnvironmentVariable(name);
if (value == null)
{
return defaultValue;
}
else
{
return value;
}
}
/**
* 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.
*
* @param logger The logger whose level should be updated.
* @param logLevel The log level to set for the logger.
*/
public static void setLoggerLevel(@NotNull final Logger logger,
@NotNull final Level logLevel)
{
try
{
logger.setLevel(logLevel);
}
catch (final Throwable t)
{
Debug.debugException(t);
}
}
/**
* 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.
*
* @param logHandler The log handler whose level should be updated.
* @param logLevel The log level to set for the log handler.
*/
public static void setLogHandlerLevel(@NotNull final Handler logHandler,
@NotNull final Level logLevel)
{
try
{
logHandler.setLevel(logLevel);
}
catch (final Throwable t)
{
Debug.debugException(t);
}
}
/**
* Retrieves a UTF-8 byte representation of the provided string.
*
* @param s The string for which to retrieve the UTF-8 byte representation.
*
* @return The UTF-8 byte representation for the provided string.
*/
@NotNull()
public static byte[] getBytes(@Nullable final String s)
{
final int length;
if ((s == null) || ((length = s.length()) == 0))
{
return NO_BYTES;
}
final byte[] b = new byte[length];
for (int i=0; i < length; i++)
{
final char c = s.charAt(i);
if (c <= 0x7F)
{
b[i] = (byte) (c & 0x7F);
}
else
{
return s.getBytes(StandardCharsets.UTF_8);
}
}
return b;
}
/**
* Retrieves a byte array containing the UTF-8 representation of the bytes
* that comprise the provided Unicode code point.
*
* @param codePoint The code point for which to retrieve the UTF-8 bytes.
*
* @return A byte array containing the UTF-8 representation of the bytes that
* comprise the provided Unicode code point.
*/
@NotNull()
public static byte[] getBytesForCodePoint(final int codePoint)
{
if (codePoint <= 0x7F)
{
return new byte[] { (byte) codePoint };
}
else
{
final String codePointString = new String(new int[] { codePoint }, 0, 1);
return codePointString.getBytes(StandardCharsets.UTF_8);
}
}
/**
* 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.
*
* @param b The byte array for which to make the determination. It must
* not be {@code null}.
*
* @return {@code true} if the contents of the provided array represent an
* ASCII string, or {@code false} if not.
*/
public static boolean isASCIIString(@NotNull final byte[] b)
{
for (final byte by : b)
{
if ((by & 0x80) == 0x80)
{
return false;
}
}
return true;
}
/**
* Indicates whether the contents of the provided string represent an ASCII
* string, which is also known in LDAP terminology as an IA5 string. An ASCII
* string is one that contains only bytes in which the most significant bit is
* zero.
*
* @param s The string for which to make the determination. It must not be
* {@code null}.
*
* @return {@code true} if the contents of the provided string represent an
* ASCII string, or {@code false} if not.
*/
public static boolean isASCIIString(@NotNull final String s)
{
return isASCIIString(getBytes(s));
}
/**
* 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.
*
*
* @param c The character for which to make the determination.
*
* @return {@code true} if the provided character is a printable ASCII
* character, or {@code false} if not.
*/
public static boolean isPrintable(final char c)
{
if (((c >= 'a') && (c <= 'z')) ||
((c >= 'A') && (c <= 'Z')) ||
((c >= '0') && (c <= '9')))
{
return true;
}
switch (c)
{
case '\'':
case '(':
case ')':
case '+':
case ',':
case '-':
case '.':
case '=':
case '/':
case ':':
case '?':
case ' ':
return true;
default:
return false;
}
}
/**
* 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.
*
* @param b The byte array for which to make the determination. It must
* not be {@code null}.
*
* @return {@code true} if the contents of the provided byte array represent
* a printable LDAP string, or {@code false} if not.
*/
public static boolean isPrintableString(@NotNull final byte[] b)
{
for (final byte by : b)
{
if ((by & 0x80) == 0x80)
{
return false;
}
if (((by >= 'a') && (by <= 'z')) ||
((by >= 'A') && (by <= 'Z')) ||
((by >= '0') && (by <= '9')))
{
continue;
}
switch (by)
{
case '\'':
case '(':
case ')':
case '+':
case ',':
case '-':
case '.':
case '=':
case '/':
case ':':
case '?':
case ' ':
continue;
default:
return false;
}
}
return true;
}
/**
* Indicates whether the provided string represents a printable LDAP string,
* as per RFC 4517 section 3.2. The only characters allowed in a printable
* string are:
*
* - All uppercase and lowercase ASCII alphabetic letters
* - All ASCII numeric digits
* - The following additional ASCII characters: single quote, left
* parenthesis, right parenthesis, plus, comma, hyphen, period, equals,
* forward slash, colon, question mark, space.
*
* 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.
*
* @param s The string for which to make the determination. It must not be
* {@code null}.
*
* @return {@code true} if the provided string represents a printable LDAP
* string, or {@code false} if not.
*/
public static boolean isPrintableString(@NotNull final String s)
{
final int length = s.length();
for (int i=0; i < length; i++)
{
final char c = s.charAt(i);
if ((c & 0x80) == 0x80)
{
return false;
}
if (((c >= 'a') && (c <= 'z')) ||
((c >= 'A') && (c <= 'Z')) ||
((c >= '0') && (c <= '9')))
{
continue;
}
switch (c)
{
case '\'':
case '(':
case ')':
case '+':
case ',':
case '-':
case '.':
case '=':
case '/':
case ':':
case '?':
case ' ':
continue;
default:
return false;
}
}
return true;
}
/**
* Indicates whether the specified Unicode code point represents a character
* that is believed to be displayable. Displayable characters include
* letters, numbers, spaces, dashes, punctuation, and symbols.
* Non-displayable characters include control characters, combining marks,
* enclosing marks, directionality indicators, format characters, and
* surrogate characters.
*
* @param codePoint The code point for which to make the determination.
*
* @return {@code true} if the specified Unicode character is believed to be
* displayable, or {@code false} if not.
*/
public static boolean isLikelyDisplayableCharacter(final int codePoint)
{
final int charType = Character.getType(codePoint);
switch (charType)
{
case Character.UPPERCASE_LETTER:
case Character.LOWERCASE_LETTER:
case Character.TITLECASE_LETTER:
case Character.MODIFIER_LETTER:
case Character.OTHER_LETTER:
case Character.DECIMAL_DIGIT_NUMBER:
case Character.LETTER_NUMBER:
case Character.OTHER_NUMBER:
case Character.SPACE_SEPARATOR:
case Character.DASH_PUNCTUATION:
case Character.START_PUNCTUATION:
case Character.END_PUNCTUATION:
case Character.CONNECTOR_PUNCTUATION:
case Character.OTHER_PUNCTUATION:
case Character.INITIAL_QUOTE_PUNCTUATION:
case Character.FINAL_QUOTE_PUNCTUATION:
case Character.MATH_SYMBOL:
case Character.CURRENCY_SYMBOL:
case Character.OTHER_SYMBOL:
return true;
default:
return false;
}
}
/**
*Indicates whether the provided string is comprised entirely of characters
* that are believed to be displayable (as determined by the
* {@link #isLikelyDisplayableCharacter} method).
*
* @param s The string for which to make the determination. It must not e
* {@code null}.
*
* @return {@code true} if the provided string is believed to be displayable,
* or {@code false} if not.
*/
public static boolean isLikelyDisplayableString(@NotNull final String s)
{
int pos = 0;
while (pos < s.length())
{
final int codePoint = s.codePointAt(pos);
if (! isLikelyDisplayableCharacter(codePoint))
{
return false;
}
pos += Character.charCount(codePoint);
}
return true;
}
/**
* Indicates whether the contents of the provided array are valid UTF-8.
*
* @param b The byte array to examine. It must not be {@code null}.
*
* @return {@code true} if the byte array can be parsed as a valid UTF-8
* string, or {@code false} if not.
*/
public static boolean isValidUTF8(@NotNull final byte[] b)
{
int i = 0;
while (i < b.length)
{
final byte currentByte = b[i++];
// If the most significant bit is not set, then this represents a valid
// single-byte character.
if ((currentByte & 0b1000_0000) == 0b0000_0000)
{
continue;
}
// If the first byte starts with 0b110, then it must be followed by
// another byte that starts with 0b10.
if ((currentByte & 0b1110_0000) == 0b1100_0000)
{
if (! hasExpectedSubsequentUTF8Bytes(b, i, 1))
{
return false;
}
i++;
continue;
}
// If the first byte starts with 0b1110, then it must be followed by two
// more bytes that start with 0b10.
if ((currentByte & 0b1111_0000) == 0b1110_0000)
{
if (! hasExpectedSubsequentUTF8Bytes(b, i, 2))
{
return false;
}
i += 2;
continue;
}
// If the first byte starts with 0b11110, then it must be followed by
// three more bytes that start with 0b10.
if ((currentByte & 0b1111_1000) == 0b1111_0000)
{
if (! hasExpectedSubsequentUTF8Bytes(b, i, 3))
{
return false;
}
i += 3;
continue;
}
// If the first byte starts with 0b111110, then it must be followed by
// four more bytes that start with 0b10.
if ((currentByte & 0b1111_1100) == 0b1111_1000)
{
if (! hasExpectedSubsequentUTF8Bytes(b, i, 4))
{
return false;
}
i += 4;
continue;
}
// If the first byte starts with 0b1111110, then it must be followed by
// five more bytes that start with 0b10.
if ((currentByte & 0b1111_1110) == 0b1111_1100)
{
if (! hasExpectedSubsequentUTF8Bytes(b, i, 5))
{
return false;
}
i += 5;
continue;
}
// This is not a valid first byte for a UTF-8 character.
return false;
}
// If we've gotten here, then the provided array represents a valid UTF-8
// string.
return true;
}
/**
* Ensures that the provided array has the expected number of bytes that start
* with 0b10 starting at the specified position in the array.
*
* @param b The byte array to examine.
* @param p The position in the byte array at which to start looking.
* @param n The number of bytes to examine.
*
* @return {@code true} if the provided byte array has the expected number of
* bytes that start with 0b10, or {@code false} if not.
*/
private static boolean hasExpectedSubsequentUTF8Bytes(@NotNull final byte[] b,
final int p,
final int n)
{
if (b.length < (p + n))
{
return false;
}
for (int i=0; i < n; i++)
{
if ((b[p+i] & 0b1100_0000) != 0b1000_0000)
{
return false;
}
}
return true;
}
/**
* Retrieves a string generated from the provided byte array using the UTF-8
* encoding.
*
* @param b The byte array for which to return the associated string.
*
* @return The string generated from the provided byte array using the UTF-8
* encoding.
*/
@NotNull()
public static String toUTF8String(@NotNull final byte[] b)
{
try
{
return new String(b, StandardCharsets.UTF_8);
}
catch (final Exception e)
{
// This should never happen.
Debug.debugException(e);
return new String(b);
}
}
/**
* Retrieves a string generated from the specified portion of the provided
* byte array using the UTF-8 encoding.
*
* @param b The byte array for which to return the associated string.
* @param offset The offset in the array at which the value begins.
* @param length The number of bytes in the value to convert to a string.
*
* @return The string generated from the specified portion of the provided
* byte array using the UTF-8 encoding.
*/
@NotNull()
public static String toUTF8String(@NotNull final byte[] b, final int offset,
final int length)
{
try
{
return new String(b, offset, length, StandardCharsets.UTF_8);
}
catch (final Exception e)
{
// This should never happen.
Debug.debugException(e);
return new String(b, offset, length);
}
}
/**
* Retrieves a version of the provided string with the first character
* converted to lowercase but all other characters retaining their original
* capitalization.
*
* @param s The string to be processed.
*
* @return A version of the provided string with the first character
* converted to lowercase but all other characters retaining their
* original capitalization. It may be {@code null} if the provided
* string is {@code null}.
*/
@Nullable()
public static String toInitialLowerCase(@Nullable final String s)
{
if ((s == null) || s.isEmpty())
{
return s;
}
else if (s.length() == 1)
{
return toLowerCase(s);
}
else
{
final char c = s.charAt(0);
if (((c >= 'A') && (c <= 'Z')) || (c < ' ') || (c > '~'))
{
final StringBuilder b = new StringBuilder(s);
b.setCharAt(0, Character.toLowerCase(c));
return b.toString();
}
else
{
return s;
}
}
}
/**
* Retrieves an all-lowercase version of the provided string.
*
* @param s The string for which to retrieve the lowercase version.
*
* @return An all-lowercase version of the provided string, or {@code null}
* if the provided string was {@code null}.
*/
@Nullable()
public static String toLowerCase(@Nullable final String s)
{
if (s == null)
{
return null;
}
final int length = s.length();
final char[] charArray = s.toCharArray();
for (int i=0; i < length; i++)
{
switch (charArray[i])
{
case 'A':
charArray[i] = 'a';
break;
case 'B':
charArray[i] = 'b';
break;
case 'C':
charArray[i] = 'c';
break;
case 'D':
charArray[i] = 'd';
break;
case 'E':
charArray[i] = 'e';
break;
case 'F':
charArray[i] = 'f';
break;
case 'G':
charArray[i] = 'g';
break;
case 'H':
charArray[i] = 'h';
break;
case 'I':
charArray[i] = 'i';
break;
case 'J':
charArray[i] = 'j';
break;
case 'K':
charArray[i] = 'k';
break;
case 'L':
charArray[i] = 'l';
break;
case 'M':
charArray[i] = 'm';
break;
case 'N':
charArray[i] = 'n';
break;
case 'O':
charArray[i] = 'o';
break;
case 'P':
charArray[i] = 'p';
break;
case 'Q':
charArray[i] = 'q';
break;
case 'R':
charArray[i] = 'r';
break;
case 'S':
charArray[i] = 's';
break;
case 'T':
charArray[i] = 't';
break;
case 'U':
charArray[i] = 'u';
break;
case 'V':
charArray[i] = 'v';
break;
case 'W':
charArray[i] = 'w';
break;
case 'X':
charArray[i] = 'x';
break;
case 'Y':
charArray[i] = 'y';
break;
case 'Z':
charArray[i] = 'z';
break;
default:
if (charArray[i] > 0x7F)
{
return s.toLowerCase();
}
break;
}
}
return new String(charArray);
}
/**
* Retrieves an all-uppercase version of the provided string.
*
* @param s The string for which to retrieve the uppercase version.
*
* @return An all-uppercase version of the provided string, or {@code null}
* if the provided string was {@code null}.
*/
@Nullable()
public static String toUpperCase(@Nullable final String s)
{
if (s == null)
{
return null;
}
final int length = s.length();
final char[] charArray = s.toCharArray();
for (int i=0; i < length; i++)
{
switch (charArray[i])
{
case 'a':
charArray[i] = 'A';
break;
case 'b':
charArray[i] = 'B';
break;
case 'c':
charArray[i] = 'C';
break;
case 'd':
charArray[i] = 'D';
break;
case 'e':
charArray[i] = 'E';
break;
case 'f':
charArray[i] = 'F';
break;
case 'g':
charArray[i] = 'G';
break;
case 'h':
charArray[i] = 'H';
break;
case 'i':
charArray[i] = 'I';
break;
case 'j':
charArray[i] = 'J';
break;
case 'k':
charArray[i] = 'K';
break;
case 'l':
charArray[i] = 'L';
break;
case 'm':
charArray[i] = 'M';
break;
case 'n':
charArray[i] = 'N';
break;
case 'o':
charArray[i] = 'O';
break;
case 'p':
charArray[i] = 'P';
break;
case 'q':
charArray[i] = 'Q';
break;
case 'r':
charArray[i] = 'R';
break;
case 's':
charArray[i] = 'S';
break;
case 't':
charArray[i] = 'T';
break;
case 'u':
charArray[i] = 'U';
break;
case 'v':
charArray[i] = 'V';
break;
case 'w':
charArray[i] = 'W';
break;
case 'x':
charArray[i] = 'X';
break;
case 'y':
charArray[i] = 'Y';
break;
case 'z':
charArray[i] = 'Z';
break;
default:
if (charArray[i] > 0x7F)
{
return s.toUpperCase();
}
break;
}
}
return new String(charArray);
}
/**
* Indicates whether the provided character is a valid hexadecimal digit.
*
* @param c The character for which to make the determination.
*
* @return {@code true} if the provided character does represent a valid
* hexadecimal digit, or {@code false} if not.
*/
public static boolean isHex(final char c)
{
switch (c)
{
case '0':
case '1':
case '2':
case '3':
case '4':
case '5':
case '6':
case '7':
case '8':
case '9':
case 'a':
case 'A':
case 'b':
case 'B':
case 'c':
case 'C':
case 'd':
case 'D':
case 'e':
case 'E':
case 'f':
case 'F':
return true;
default:
return false;
}
}
/**
* Retrieves a hexadecimal representation of the provided byte.
*
* @param b The byte to encode as hexadecimal.
*
* @return A string containing the hexadecimal representation of the provided
* byte.
*/
@NotNull()
public static String toHex(final byte b)
{
final StringBuilder buffer = new StringBuilder(2);
toHex(b, buffer);
return buffer.toString();
}
/**
* Appends a hexadecimal representation of the provided byte to the given
* buffer.
*
* @param b The byte to encode as hexadecimal.
* @param buffer The buffer to which the hexadecimal representation is to be
* appended.
*/
public static void toHex(final byte b, @NotNull final StringBuilder buffer)
{
switch (b & 0xF0)
{
case 0x00:
buffer.append('0');
break;
case 0x10:
buffer.append('1');
break;
case 0x20:
buffer.append('2');
break;
case 0x30:
buffer.append('3');
break;
case 0x40:
buffer.append('4');
break;
case 0x50:
buffer.append('5');
break;
case 0x60:
buffer.append('6');
break;
case 0x70:
buffer.append('7');
break;
case 0x80:
buffer.append('8');
break;
case 0x90:
buffer.append('9');
break;
case 0xA0:
buffer.append('a');
break;
case 0xB0:
buffer.append('b');
break;
case 0xC0:
buffer.append('c');
break;
case 0xD0:
buffer.append('d');
break;
case 0xE0:
buffer.append('e');
break;
case 0xF0:
buffer.append('f');
break;
}
switch (b & 0x0F)
{
case 0x00:
buffer.append('0');
break;
case 0x01:
buffer.append('1');
break;
case 0x02:
buffer.append('2');
break;
case 0x03:
buffer.append('3');
break;
case 0x04:
buffer.append('4');
break;
case 0x05:
buffer.append('5');
break;
case 0x06:
buffer.append('6');
break;
case 0x07:
buffer.append('7');
break;
case 0x08:
buffer.append('8');
break;
case 0x09:
buffer.append('9');
break;
case 0x0A:
buffer.append('a');
break;
case 0x0B:
buffer.append('b');
break;
case 0x0C:
buffer.append('c');
break;
case 0x0D:
buffer.append('d');
break;
case 0x0E:
buffer.append('e');
break;
case 0x0F:
buffer.append('f');
break;
}
}
/**
* Appends a hexadecimal representation of the provided byte to the given
* buffer.
*
* @param b The byte to encode as hexadecimal.
* @param buffer The buffer to which the hexadecimal representation is to be
* appended.
*/
public static void toHex(final byte b, @NotNull final ByteStringBuffer buffer)
{
switch (b & 0xF0)
{
case 0x00:
buffer.append((byte) '0');
break;
case 0x10:
buffer.append((byte) '1');
break;
case 0x20:
buffer.append((byte) '2');
break;
case 0x30:
buffer.append((byte) '3');
break;
case 0x40:
buffer.append((byte) '4');
break;
case 0x50:
buffer.append((byte) '5');
break;
case 0x60:
buffer.append((byte) '6');
break;
case 0x70:
buffer.append((byte) '7');
break;
case 0x80:
buffer.append((byte) '8');
break;
case 0x90:
buffer.append((byte) '9');
break;
case 0xA0:
buffer.append((byte) 'a');
break;
case 0xB0:
buffer.append((byte) 'b');
break;
case 0xC0:
buffer.append((byte) 'c');
break;
case 0xD0:
buffer.append((byte) 'd');
break;
case 0xE0:
buffer.append((byte) 'e');
break;
case 0xF0:
buffer.append((byte) 'f');
break;
}
switch (b & 0x0F)
{
case 0x00:
buffer.append((byte) '0');
break;
case 0x01:
buffer.append((byte) '1');
break;
case 0x02:
buffer.append((byte) '2');
break;
case 0x03:
buffer.append((byte) '3');
break;
case 0x04:
buffer.append((byte) '4');
break;
case 0x05:
buffer.append((byte) '5');
break;
case 0x06:
buffer.append((byte) '6');
break;
case 0x07:
buffer.append((byte) '7');
break;
case 0x08:
buffer.append((byte) '8');
break;
case 0x09:
buffer.append((byte) '9');
break;
case 0x0A:
buffer.append((byte) 'a');
break;
case 0x0B:
buffer.append((byte) 'b');
break;
case 0x0C:
buffer.append((byte) 'c');
break;
case 0x0D:
buffer.append((byte) 'd');
break;
case 0x0E:
buffer.append((byte) 'e');
break;
case 0x0F:
buffer.append((byte) 'f');
break;
}
}
/**
* 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.
*
* @param b The byte array to be represented as a hexadecimal string. It
* must not be {@code null}.
*
* @return A string containing a hexadecimal representation of the contents
* of the provided byte array.
*/
@NotNull()
public static String toHex(@NotNull final byte[] b)
{
Validator.ensureNotNull(b);
final StringBuilder buffer = new StringBuilder(2 * b.length);
toHex(b, buffer);
return buffer.toString();
}
/**
* 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.
*
* @param b The byte array to be represented as a hexadecimal string.
* It must not be {@code null}.
* @param buffer A buffer to which the hexadecimal representation of the
* contents of the provided byte array should be appended.
*/
public static void toHex(@NotNull final byte[] b,
@NotNull final StringBuilder buffer)
{
toHex(b, null, 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.
*
* @param b The byte array to be represented as a hexadecimal
* string. It must not be {@code null}.
* @param delimiter A delimiter to be inserted between bytes. It may be
* {@code null} if no delimiter should be used.
* @param buffer A buffer to which the hexadecimal representation of the
* contents of the provided byte array should be appended.
*/
public static void toHex(@NotNull final byte[] b,
@Nullable final String delimiter,
@NotNull final StringBuilder buffer)
{
boolean first = true;
for (final byte bt : b)
{
if (first)
{
first = false;
}
else if (delimiter != null)
{
buffer.append(delimiter);
}
toHex(bt, buffer);
}
}
/**
* 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.
*
* @param array The array whose contents should be processed.
* @param indent The number of spaces to insert on each line prior to the
* first hex byte.
*
* @return A hex-encoded representation of the contents of the provided
* array, along with an ASCII representation of its contents next to
* it.
*/
@NotNull()
public static String toHexPlusASCII(@NotNull final byte[] array,
final int indent)
{
final StringBuilder buffer = new StringBuilder();
toHexPlusASCII(array, indent, buffer);
return buffer.toString();
}
/**
* 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.
*
* @param array The array whose contents should be processed.
* @param indent The number of spaces to insert on each line prior to the
* first hex byte.
* @param buffer The buffer to which the encoded data should be appended.
*/
public static void toHexPlusASCII(@Nullable final byte[] array,
final int indent,
@NotNull final StringBuilder buffer)
{
if ((array == null) || (array.length == 0))
{
return;
}
for (int i=0; i < indent; i++)
{
buffer.append(' ');
}
int pos = 0;
int startPos = 0;
while (pos < array.length)
{
toHex(array[pos++], buffer);
buffer.append(' ');
if ((pos % 16) == 0)
{
buffer.append(" ");
for (int i=startPos; i < pos; i++)
{
if ((array[i] < ' ') || (array[i] > '~'))
{
buffer.append(' ');
}
else
{
buffer.append((char) array[i]);
}
}
buffer.append(EOL);
startPos = pos;
if (pos < array.length)
{
for (int i=0; i < indent; i++)
{
buffer.append(' ');
}
}
}
}
// If the last line isn't complete yet, then finish it off.
if ((array.length % 16) != 0)
{
final int missingBytes = (16 - (array.length % 16));
for (int i=0; i < missingBytes; i++)
{
buffer.append(" ");
}
buffer.append(" ");
for (int i=startPos; i < array.length; i++)
{
if ((array[i] < ' ') || (array[i] > '~'))
{
buffer.append(' ');
}
else
{
buffer.append((char) array[i]);
}
}
buffer.append(EOL);
}
}
/**
* Retrieves the bytes that correspond to the provided hexadecimal string.
*
* @param hexString The hexadecimal string for which to retrieve the bytes.
* It must not be {@code null}, and there must not be any
* delimiter between bytes.
*
* @return The bytes that correspond to the provided hexadecimal string.
*
* @throws ParseException If the provided string does not represent valid
* hexadecimal data, or if the provided string does
* not contain an even number of characters.
*/
@NotNull()
public static byte[] fromHex(@NotNull final String hexString)
throws ParseException
{
if ((hexString.length() % 2) != 0)
{
throw new ParseException(
ERR_FROM_HEX_ODD_NUMBER_OF_CHARACTERS.get(hexString.length()),
hexString.length());
}
final byte[] decodedBytes = new byte[hexString.length() / 2];
for (int i=0, j=0; i < decodedBytes.length; i++, j+= 2)
{
switch (hexString.charAt(j))
{
case '0':
// No action is required.
break;
case '1':
decodedBytes[i] = 0x10;
break;
case '2':
decodedBytes[i] = 0x20;
break;
case '3':
decodedBytes[i] = 0x30;
break;
case '4':
decodedBytes[i] = 0x40;
break;
case '5':
decodedBytes[i] = 0x50;
break;
case '6':
decodedBytes[i] = 0x60;
break;
case '7':
decodedBytes[i] = 0x70;
break;
case '8':
decodedBytes[i] = (byte) 0x80;
break;
case '9':
decodedBytes[i] = (byte) 0x90;
break;
case 'a':
case 'A':
decodedBytes[i] = (byte) 0xA0;
break;
case 'b':
case 'B':
decodedBytes[i] = (byte) 0xB0;
break;
case 'c':
case 'C':
decodedBytes[i] = (byte) 0xC0;
break;
case 'd':
case 'D':
decodedBytes[i] = (byte) 0xD0;
break;
case 'e':
case 'E':
decodedBytes[i] = (byte) 0xE0;
break;
case 'f':
case 'F':
decodedBytes[i] = (byte) 0xF0;
break;
default:
throw new ParseException(ERR_FROM_HEX_NON_HEX_CHARACTER.get(j), j);
}
switch (hexString.charAt(j+1))
{
case '0':
// No action is required.
break;
case '1':
decodedBytes[i] |= 0x01;
break;
case '2':
decodedBytes[i] |= 0x02;
break;
case '3':
decodedBytes[i] |= 0x03;
break;
case '4':
decodedBytes[i] |= 0x04;
break;
case '5':
decodedBytes[i] |= 0x05;
break;
case '6':
decodedBytes[i] |= 0x06;
break;
case '7':
decodedBytes[i] |= 0x07;
break;
case '8':
decodedBytes[i] |= 0x08;
break;
case '9':
decodedBytes[i] |= 0x09;
break;
case 'a':
case 'A':
decodedBytes[i] |= 0x0A;
break;
case 'b':
case 'B':
decodedBytes[i] |= 0x0B;
break;
case 'c':
case 'C':
decodedBytes[i] |= 0x0C;
break;
case 'd':
case 'D':
decodedBytes[i] |= 0x0D;
break;
case 'e':
case 'E':
decodedBytes[i] |= 0x0E;
break;
case 'f':
case 'F':
decodedBytes[i] |= 0x0F;
break;
default:
throw new ParseException(ERR_FROM_HEX_NON_HEX_CHARACTER.get(j+1),
j+1);
}
}
return decodedBytes;
}
/**
* 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.
*
* @param c The character to be encoded.
* @param buffer The buffer to which the hex-encoded representation should
* be appended.
*/
public static void hexEncode(final char c,
@NotNull final StringBuilder buffer)
{
final byte[] charBytes;
if (c <= 0x7F)
{
charBytes = new byte[] { (byte) (c & 0x7F) };
}
else
{
charBytes = getBytes(String.valueOf(c));
}
for (final byte b : charBytes)
{
buffer.append('\\');
toHex(b, 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.
*
* @param codePoint The code point to be encoded.
* @param buffer The buffer to which the hex-encoded representation
* should be appended.
*/
public static void hexEncode(final int codePoint,
@NotNull final StringBuilder buffer)
{
final byte[] charBytes =
getBytes(new String(new int[] { codePoint }, 0, 1));
for (final byte b : charBytes)
{
buffer.append('\\');
toHex(b, buffer);
}
}
/**
* Appends the Java code that may be used to create the provided byte
* array to the given buffer.
*
* @param array The byte array containing the data to represent. It must
* not be {@code null}.
* @param buffer The buffer to which the code should be appended.
*/
public static void byteArrayToCode(@NotNull final byte[] array,
@NotNull final StringBuilder buffer)
{
buffer.append("new byte[] {");
for (int i=0; i < array.length; i++)
{
if (i > 0)
{
buffer.append(',');
}
buffer.append(" (byte) 0x");
toHex(array[i], buffer);
}
buffer.append(" }");
}
/**
* Retrieves a single-line string representation of the stack trace for the
* provided {@code Throwable}. It will include the unqualified name of the
* {@code 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).
*
* @param t The {@code Throwable} for which to retrieve the stack trace.
*
* @return A single-line string representation of the stack trace for the
* provided {@code Throwable}.
*/
@NotNull()
public static String getStackTrace(@NotNull final Throwable t)
{
final StringBuilder buffer = new StringBuilder();
getStackTrace(t, buffer);
return buffer.toString();
}
/**
* Appends a single-line string representation of the stack trace for the
* provided {@code Throwable} to the given buffer. It will include the
* unqualified name of the {@code 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).
*
* @param t The {@code Throwable} for which to retrieve the stack
* trace.
* @param buffer The buffer to which the information should be appended.
*/
public static void getStackTrace(@NotNull final Throwable t,
@NotNull final StringBuilder buffer)
{
buffer.append(getUnqualifiedClassName(t.getClass()));
buffer.append('(');
final String message = t.getMessage();
if (message != null)
{
buffer.append("message='");
buffer.append(message);
buffer.append("', ");
}
buffer.append("trace='");
getStackTrace(t.getStackTrace(), buffer);
buffer.append('\'');
final Throwable cause = t.getCause();
if (cause != null)
{
buffer.append(", cause=");
getStackTrace(cause, buffer);
}
final String ldapSDKVersionString = ", ldapSDKVersion=" +
Version.NUMERIC_VERSION_STRING + ", revision=" + Version.REVISION_ID;
if (buffer.indexOf(ldapSDKVersionString) < 0)
{
buffer.append(ldapSDKVersionString);
}
buffer.append(')');
}
/**
* 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.
*
* @param elements The stack trace.
*
* @return A single-line string representation of the stack trace.
*/
@NotNull()
public static String getStackTrace(
@NotNull final StackTraceElement[] elements)
{
final StringBuilder buffer = new StringBuilder();
getStackTrace(elements, buffer);
return buffer.toString();
}
/**
* 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.
*
* @param elements The stack trace.
* @param buffer The buffer to which the information should be appended.
*/
public static void getStackTrace(@NotNull final StackTraceElement[] elements,
@NotNull final StringBuilder buffer)
{
getStackTrace(elements, buffer, -1);
}
/**
* 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.
*
* @param elements The stack trace.
* @param buffer The buffer to which the information should be
* appended.
* @param 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
*/
public static void getStackTrace(@NotNull final StackTraceElement[] elements,
@NotNull final StringBuilder buffer,
final int maxPreSDKFrames)
{
boolean sdkElementFound = false;
int numPreSDKElementsFound = 0;
for (int i=0; i < elements.length; i++)
{
if (i > 0)
{
buffer.append(" / ");
}
if (elements[i].getClassName().startsWith("com.unboundid."))
{
sdkElementFound = true;
}
else if (sdkElementFound)
{
if ((maxPreSDKFrames >= 0) &&
(numPreSDKElementsFound >= maxPreSDKFrames))
{
buffer.append("...");
return;
}
numPreSDKElementsFound++;
}
buffer.append(elements[i].getMethodName());
buffer.append('(');
buffer.append(elements[i].getFileName());
final int lineNumber = elements[i].getLineNumber();
if (lineNumber > 0)
{
buffer.append(':');
buffer.append(lineNumber);
}
else if (elements[i].isNativeMethod())
{
buffer.append(":native");
}
else
{
buffer.append(":unknown");
}
buffer.append(')');
}
}
/**
* Retrieves a string representation of the provided {@code 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 {@code 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.
*
* @param t The {@code Throwable} for which to generate the exception
* message.
*
* @return A string representation of the provided {@code Throwable} object
* suitable for use in a message.
*/
@NotNull()
public static String getExceptionMessage(@NotNull final Throwable t)
{
final boolean includeCause =
Boolean.getBoolean(Debug.PROPERTY_INCLUDE_CAUSE_IN_EXCEPTION_MESSAGES);
final boolean includeStackTrace = Boolean.getBoolean(
Debug.PROPERTY_INCLUDE_STACK_TRACE_IN_EXCEPTION_MESSAGES);
return getExceptionMessage(t, includeCause, includeStackTrace);
}
/**
* Retrieves a string representation of the provided {@code 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 {@code 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.
*
* @param t The {@code Throwable} for which to generate the
* exception message.
* @param includeCause Indicates whether to include information about
* the cause (if any) in the exception message.
* @param includeStackTrace Indicates whether to include a condensed
* representation of the stack trace in the
* exception message.
*
* @return A string representation of the provided {@code Throwable} object
* suitable for use in a message.
*/
@NotNull()
public static String getExceptionMessage(@Nullable final Throwable t,
final boolean includeCause,
final boolean includeStackTrace)
{
if (t == null)
{
return ERR_NO_EXCEPTION.get();
}
final StringBuilder buffer = new StringBuilder();
if (t instanceof LDAPSDKException)
{
buffer.append(((LDAPSDKException) t).getExceptionMessage());
}
else if (t instanceof LDAPSDKRuntimeException)
{
buffer.append(((LDAPSDKRuntimeException) t).getExceptionMessage());
}
else if (t instanceof NullPointerException)
{
// For NullPointerExceptions, we'll always print at least a portion of
// the stack trace that includes all of the LDAP SDK code, and up to
// three frames of whatever called into the SDK.
buffer.append("NullPointerException(");
getStackTrace(t.getStackTrace(), buffer, 3);
buffer.append(')');
}
else if ((t.getMessage() == null) || t.getMessage().isEmpty() ||
t.getMessage().equalsIgnoreCase("null"))
{
getStackTrace(t, buffer);
}
else
{
buffer.append(t.getClass().getSimpleName());
buffer.append('(');
buffer.append(t.getMessage());
buffer.append(')');
if (includeStackTrace)
{
buffer.append(" trace=");
getStackTrace(t, buffer);
}
else if (includeCause)
{
final Throwable cause = t.getCause();
if (cause != null)
{
buffer.append(" caused by ");
buffer.append(getExceptionMessage(cause));
}
}
}
final String ldapSDKVersionString = ", ldapSDKVersion=" +
Version.NUMERIC_VERSION_STRING + ", revision=" + Version.REVISION_ID;
if (buffer.indexOf(ldapSDKVersionString) < 0)
{
buffer.append(ldapSDKVersionString);
}
return buffer.toString();
}
/**
* Retrieves the unqualified name (i.e., the name without package information)
* for the provided class.
*
* @param c The class for which to retrieve the unqualified name.
*
* @return The unqualified name for the provided class.
*/
@NotNull()
public static String getUnqualifiedClassName(@NotNull final Class c)
{
final String className = c.getName();
final int lastPeriodPos = className.lastIndexOf('.');
if (lastPeriodPos > 0)
{
return className.substring(lastPeriodPos+1);
}
else
{
return className;
}
}
/**
* Retrieves a {@code TimeZone} object that represents the UTC (universal
* coordinated time) time zone.
*
* @return A {@code TimeZone} object that represents the UTC time zone.
*/
@NotNull()
public static TimeZone getUTCTimeZone()
{
return UTC_TIME_ZONE;
}
/**
* Encodes the provided timestamp in generalized time format.
*
* @param timestamp The timestamp to be encoded in generalized time format.
* It should use the same format as the
* {@code System.currentTimeMillis()} method (i.e., the
* number of milliseconds since 12:00am UTC on January 1,
* 1970).
*
* @return The generalized time representation of the provided date.
*/
@NotNull()
public static String encodeGeneralizedTime(final long timestamp)
{
return encodeGeneralizedTime(new Date(timestamp));
}
/**
* Encodes the provided date in generalized time format.
*
* @param d The date to be encoded in generalized time format.
*
* @return The generalized time representation of the provided date.
*/
@NotNull()
public static String encodeGeneralizedTime(@NotNull final Date d)
{
SimpleDateFormat dateFormat = GENERALIZED_TIME_FORMATTERS.get();
if (dateFormat == null)
{
dateFormat = new SimpleDateFormat("yyyyMMddHHmmss.SSS'Z'");
dateFormat.setTimeZone(UTC_TIME_ZONE);
GENERALIZED_TIME_FORMATTERS.set(dateFormat);
}
return dateFormat.format(d);
}
/**
* Decodes the provided string as a timestamp in generalized time format.
*
* @param t The timestamp to be decoded. It must not be {@code null}.
*
* @return The {@code Date} object decoded from the provided timestamp.
*
* @throws ParseException If the provided string could not be decoded as a
* timestamp in generalized time format.
*/
@NotNull()
public static Date decodeGeneralizedTime(@NotNull final String t)
throws ParseException
{
Validator.ensureNotNull(t);
// Extract the time zone information from the end of the value.
int tzPos;
final TimeZone tz;
if (t.endsWith("Z"))
{
tz = TimeZone.getTimeZone("UTC");
tzPos = t.length() - 1;
}
else
{
tzPos = t.lastIndexOf('-');
if (tzPos < 0)
{
tzPos = t.lastIndexOf('+');
if (tzPos < 0)
{
throw new ParseException(ERR_GENTIME_DECODE_CANNOT_PARSE_TZ.get(t),
0);
}
}
tz = TimeZone.getTimeZone("GMT" + t.substring(tzPos));
if (tz.getRawOffset() == 0)
{
// This is the default time zone that will be returned if the value
// cannot be parsed. If it's valid, then it will end in "+0000" or
// "-0000". Otherwise, it's invalid and GMT was just a fallback.
if (! (t.endsWith("+0000") || t.endsWith("-0000")))
{
throw new ParseException(ERR_GENTIME_DECODE_CANNOT_PARSE_TZ.get(t),
tzPos);
}
}
}
// See if the timestamp has a sub-second portion. Note that if there is a
// sub-second portion, then we may need to massage the value so that there
// are exactly three sub-second characters so that it can be interpreted as
// milliseconds.
final String subSecFormatStr;
final String trimmedTimestamp;
int periodPos = t.lastIndexOf('.', tzPos);
if (periodPos > 0)
{
final int subSecondLength = tzPos - periodPos - 1;
switch (subSecondLength)
{
case 0:
subSecFormatStr = "";
trimmedTimestamp = t.substring(0, periodPos);
break;
case 1:
subSecFormatStr = ".SSS";
trimmedTimestamp = t.substring(0, (periodPos+2)) + "00";
break;
case 2:
subSecFormatStr = ".SSS";
trimmedTimestamp = t.substring(0, (periodPos+3)) + '0';
break;
default:
subSecFormatStr = ".SSS";
trimmedTimestamp = t.substring(0, periodPos+4);
break;
}
}
else
{
subSecFormatStr = "";
periodPos = tzPos;
trimmedTimestamp = t.substring(0, tzPos);
}
// Look at where the period is (or would be if it existed) to see how many
// characters are in the integer portion. This will give us what we need
// for the rest of the format string.
final String formatStr;
switch (periodPos)
{
case 10:
formatStr = "yyyyMMddHH" + subSecFormatStr;
break;
case 12:
formatStr = "yyyyMMddHHmm" + subSecFormatStr;
break;
case 14:
formatStr = "yyyyMMddHHmmss" + subSecFormatStr;
break;
default:
throw new ParseException(ERR_GENTIME_CANNOT_PARSE_INVALID_LENGTH.get(t),
periodPos);
}
// We should finally be able to create an appropriate date format object
// to parse the trimmed version of the timestamp.
final SimpleDateFormat dateFormat = new SimpleDateFormat(formatStr);
dateFormat.setTimeZone(tz);
dateFormat.setLenient(false);
return dateFormat.parse(trimmedTimestamp);
}
/**
* Encodes the provided timestamp to the ISO 8601 format described in RFC
* 3339.
*
* @param timestamp The timestamp to be encoded in the RFC 3339 format.
* It should use the same format as the
* {@code System.currentTimeMillis()} method (i.e., the
* number of milliseconds since 12:00am UTC on January 1,
* 1970).
*
* @return The RFC 3339 representation of the provided date.
*/
@NotNull()
public static String encodeRFC3339Time(final long timestamp)
{
return encodeRFC3339Time(new Date(timestamp));
}
/**
* Encodes the provided timestamp to the ISO 8601 format described in RFC
* 3339.
*
* @param d The date to be encoded in the RFC 3339 format.
*
* @return The RFC 3339 representation of the provided date.
*/
@NotNull()
public static String encodeRFC3339Time(@NotNull final Date d)
{
SimpleDateFormat dateFormat = RFC_3339_TIME_FORMATTERS.get();
if (dateFormat == null)
{
dateFormat = new SimpleDateFormat("yyyy'-'MM'-'dd'T'HH':'mm':'ss.SSS'Z'");
dateFormat.setTimeZone(UTC_TIME_ZONE);
RFC_3339_TIME_FORMATTERS.set(dateFormat);
}
return dateFormat.format(d);
}
/**
* Decodes the provided string as a timestamp encoded in the ISO 8601 format
* described in RFC 3339.
*
* @param timestamp The timestamp to be decoded in the RFC 3339 format.
*
* @return The {@code Date} object decoded from the provided timestamp.
*
* @throws ParseException If the provided string could not be decoded as a
* timestamp in the RFC 3339 time format.
*/
@NotNull()
public static Date decodeRFC3339Time(@NotNull final String timestamp)
throws ParseException
{
// Make sure that the string representation has the minimum acceptable
// length.
if (timestamp.length() < 20)
{
throw new ParseException(ERR_RFC_3339_TIME_TOO_SHORT.get(timestamp), 0);
}
// Parse the year, month, day, hour, minute, and second components from the
// timestamp, and make sure the appropriate separator characters are between
// those components.
final int year = parseRFC3339Number(timestamp, 0, 4);
validateRFC3339TimestampSeparatorCharacter(timestamp, 4, '-');
final int month = parseRFC3339Number(timestamp, 5, 2);
validateRFC3339TimestampSeparatorCharacter(timestamp, 7, '-');
final int day = parseRFC3339Number(timestamp, 8, 2);
validateRFC3339TimestampSeparatorCharacter(timestamp, 10, 'T');
final int hour = parseRFC3339Number(timestamp, 11, 2);
validateRFC3339TimestampSeparatorCharacter(timestamp, 13, ':');
final int minute = parseRFC3339Number(timestamp, 14, 2);
validateRFC3339TimestampSeparatorCharacter(timestamp, 16, ':');
final int second = parseRFC3339Number(timestamp, 17, 2);
// Make sure that the month and day values are acceptable.
switch (month)
{
case 1:
case 3:
case 5:
case 7:
case 8:
case 10:
case 12:
// January, March, May, July, August, October, and December all have 31
// days.
if ((day < 1) || (day > 31))
{
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_DAY_FOR_MONTH.get(timestamp, day,
month),
8);
}
break;
case 4:
case 6:
case 9:
case 11:
// April, June, September, and November all have 30 days.
if ((day < 1) || (day > 30))
{
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_DAY_FOR_MONTH.get(timestamp, day,
month),
8);
}
break;
case 2:
// February can have 28 or 29 days, depending on whether it's a leap
// year. Although we could determine whether the provided year is a
// leap year, we'll just always accept up to 29 days for February.
if ((day < 1) || (day > 29))
{
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_DAY_FOR_MONTH.get(timestamp, day,
month),
8);
}
break;
default:
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_MONTH.get(timestamp, month), 5);
}
// Make sure that the hour, minute, and second values are acceptable. Note
// that while ISO 8601 permits a value of 24 for the hour, RFC 3339 only
// permits hour values between 0 and 23. Also note that some minutes can
// have up to 61 seconds for leap seconds, so we'll always account for that.
if ((hour < 0) || (hour > 23))
{
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_HOUR.get(timestamp, hour), 11);
}
if ((minute < 0) || (minute > 59))
{
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_MINUTE.get(timestamp, minute), 14);
}
if ((second < 0) || (second > 60))
{
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_SECOND.get(timestamp, second), 17);
}
// See if there is a sub-second portion. If so, then there will be a
// period at position 19 followed by at least one digit. This
// implementation will only support timestamps with no more than three
// sub-second digits.
int milliseconds = 0;
int timeZoneStartPos = -1;
if (timestamp.charAt(19) == '.')
{
int numDigits = 0;
final StringBuilder subSecondString = new StringBuilder(3);
for (int pos=20; pos < timestamp.length(); pos++)
{
final char c = timestamp.charAt(pos);
switch (c)
{
case '0':
numDigits++;
if (subSecondString.length() > 0)
{
// Only add a zero if it's not the first digit.
subSecondString.append(c);
}
break;
case '1':
case '2':
case '3':
case '4':
case '5':
case '6':
case '7':
case '8':
case '9':
numDigits++;
subSecondString.append(c);
break;
case 'Z':
case '+':
case '-':
timeZoneStartPos = pos;
break;
default:
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_SUB_SECOND_CHAR.get(timestamp, c,
pos),
pos);
}
if (timeZoneStartPos > 0)
{
break;
}
if (numDigits > 3)
{
throw new ParseException(
ERR_RFC_3339_TIME_TOO_MANY_SUB_SECOND_DIGITS.get(timestamp),
20);
}
}
if (timeZoneStartPos < 0)
{
throw new ParseException(
ERR_RFC_3339_TIME_MISSING_TIME_ZONE_AFTER_SUB_SECOND.get(
timestamp),
(timestamp.length() - 1));
}
if (numDigits == 0)
{
throw new ParseException(
ERR_RFC_3339_TIME_NO_SUB_SECOND_DIGITS.get(timestamp), 19);
}
if (subSecondString.length() == 0)
{
// This is possible if the sub-second portion is all zeroes.
subSecondString.append('0');
}
milliseconds = Integer.parseInt(subSecondString.toString());
if (numDigits == 1)
{
milliseconds *= 100;
}
else if (numDigits == 2)
{
milliseconds *= 10;
}
}
else
{
timeZoneStartPos = 19;
}
// The remainder of the timestamp should be the time zone.
final TimeZone timeZone;
if (timestamp.substring(timeZoneStartPos).equals("Z"))
{
// This is shorthand for the UTC time zone.
timeZone = UTC_TIME_ZONE;
}
else
{
// This is an offset from UTC, which should be in the form "+HH:MM" or
// "-HH:MM". Make sure it has the expected length.
if ((timestamp.length() - timeZoneStartPos) != 6)
{
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_TZ.get(timestamp), timeZoneStartPos);
}
// Make sure it starts with "+" or "-".
final int firstChar = timestamp.charAt(timeZoneStartPos);
if ((firstChar != '+') && (firstChar != '-'))
{
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_TZ.get(timestamp), timeZoneStartPos);
}
// Make sure the hour offset is valid.
final int timeZoneHourOffset =
parseRFC3339Number(timestamp, (timeZoneStartPos+1), 2);
if ((timeZoneHourOffset < 0) || (timeZoneHourOffset > 23))
{
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_TZ.get(timestamp), timeZoneStartPos);
}
// Make sure there is a colon between the hour and the minute portions of
// the offset.
if (timestamp.charAt(timeZoneStartPos+3) != ':')
{
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_TZ.get(timestamp), timeZoneStartPos);
}
final int timeZoneMinuteOffset =
parseRFC3339Number(timestamp, (timeZoneStartPos+4), 2);
if ((timeZoneMinuteOffset < 0) || (timeZoneMinuteOffset > 59))
{
throw new ParseException(
ERR_RFC_3339_TIME_INVALID_TZ.get(timestamp), timeZoneStartPos);
}
timeZone = TimeZone.getTimeZone(
"GMT" + timestamp.substring(timeZoneStartPos));
}
// Put everything together to construct the appropriate date.
final GregorianCalendar calendar =
new GregorianCalendar(year,
(month-1), // NOTE: Calendar stupidly uses zero-indexed months.
day, hour, minute, second);
calendar.set(GregorianCalendar.MILLISECOND, milliseconds);
calendar.setTimeZone(timeZone);
return calendar.getTime();
}
/**
* Ensures that the provided timestamp string has the expected character at
* the specified position.
*
* @param timestamp The timestamp to examine.
* It must not be {@code null}.
* @param pos The position of the character to examine.
* @param expectedChar The character expected at the specified position.
*
* @throws ParseException If the provided timestamp does not have the
* expected
*/
private static void validateRFC3339TimestampSeparatorCharacter(
@NotNull final String timestamp, final int pos,
final char expectedChar)
throws ParseException
{
if (timestamp.charAt(pos) != expectedChar)
{
throw new ParseException(
ERR_RFC_3339_INVALID_SEPARATOR.get(timestamp, timestamp.charAt(pos),
pos, expectedChar),
pos);
}
}
/**
* Parses the number at the specified location in the timestamp.
*
* @param timestamp The timestamp to examine. It must not be {@code null}.
* @param pos The position at which to begin parsing the number.
* @param numDigits The number of digits in the number.
*
* @return The number parsed from the provided timestamp.
*
* @throws ParseException If a problem is encountered while trying to parse
* the number from the timestamp.
*/
private static int parseRFC3339Number(@NotNull final String timestamp,
final int pos, final int numDigits)
throws ParseException
{
int value = 0;
for (int i=0; i < numDigits; i++)
{
value *= 10;
switch (timestamp.charAt(pos+i))
{
case '0':
break;
case '1':
value += 1;
break;
case '2':
value += 2;
break;
case '3':
value += 3;
break;
case '4':
value += 4;
break;
case '5':
value += 5;
break;
case '6':
value += 6;
break;
case '7':
value += 7;
break;
case '8':
value += 8;
break;
case '9':
value += 9;
break;
default:
throw new ParseException(
ERR_RFC_3339_INVALID_DIGIT.get(timestamp,
timestamp.charAt(pos+i), (pos+i)),
(pos+i));
}
}
return value;
}
/**
* Trims only leading spaces from the provided string, leaving any trailing
* spaces intact.
*
* @param s The string to be processed. It must not be {@code null}.
*
* @return 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.
*/
@NotNull()
public static String trimLeading(@NotNull final String s)
{
Validator.ensureNotNull(s);
int nonSpacePos = 0;
final int length = s.length();
while ((nonSpacePos < length) && (s.charAt(nonSpacePos) == ' '))
{
nonSpacePos++;
}
if (nonSpacePos == 0)
{
// There were no leading spaces.
return s;
}
else if (nonSpacePos >= length)
{
// There were no non-space characters.
return "";
}
else
{
// There were leading spaces, so return the string without them.
return s.substring(nonSpacePos, length);
}
}
/**
* Trims only trailing spaces from the provided string, leaving any leading
* spaces intact.
*
* @param s The string to be processed. It must not be {@code null}.
*
* @return 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.
*/
@NotNull()
public static String trimTrailing(@NotNull final String s)
{
Validator.ensureNotNull(s);
final int lastPos = s.length() - 1;
int nonSpacePos = lastPos;
while ((nonSpacePos >= 0) && (s.charAt(nonSpacePos) == ' '))
{
nonSpacePos--;
}
if (nonSpacePos < 0)
{
// There were no non-space characters.
return "";
}
else if (nonSpacePos == lastPos)
{
// There were no trailing spaces.
return s;
}
else
{
// There were trailing spaces, so return the string without them.
return s.substring(0, (nonSpacePos+1));
}
}
/**
* 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.
*
* @param line The line to be wrapped. It must not be {@code null}.
* @param 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.
*
* @return A list of the wrapped lines. It may be empty if the provided line
* contained only spaces.
*/
@NotNull()
public static List wrapLine(@NotNull final String line,
final int maxWidth)
{
return wrapLine(line, maxWidth, 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.
*
* @param line The line to be wrapped. It must not be
* {@code null}.
* @param 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.
* @param maxSubsequentLineWidth The maximum length for all lines except the
* first line. This must be greater than zero
* unless {@code maxFirstLineWidth} is less
* than or equal to zero.
*
* @return A list of the wrapped lines. It may be empty if the provided line
* contained only spaces.
*/
@NotNull()
public static List wrapLine(@NotNull final String line,
final int maxFirstLineWidth,
final int maxSubsequentLineWidth)
{
if (maxFirstLineWidth > 0)
{
Validator.ensureTrue(maxSubsequentLineWidth > 0);
}
// See if the provided string already contains line breaks. If so, then
// treat it as multiple lines rather than a single line.
final int breakPos = line.indexOf('\n');
if (breakPos >= 0)
{
final ArrayList lineList = new ArrayList<>(10);
final StringTokenizer tokenizer = new StringTokenizer(line, "\r\n");
while (tokenizer.hasMoreTokens())
{
lineList.addAll(wrapLine(tokenizer.nextToken(), maxFirstLineWidth,
maxSubsequentLineWidth));
}
return lineList;
}
final int length = line.length();
if ((maxFirstLineWidth <= 0) || (length < maxFirstLineWidth))
{
return Collections.singletonList(line);
}
int wrapPos = maxFirstLineWidth;
int lastWrapPos = 0;
final ArrayList lineList = new ArrayList<>(5);
while (true)
{
final int spacePos = line.lastIndexOf(' ', wrapPos);
if (spacePos > lastWrapPos)
{
// We found a space in an acceptable location, so use it after trimming
// any trailing spaces.
final String s = trimTrailing(line.substring(lastWrapPos, spacePos));
// Don't bother adding the line if it contained only spaces.
if (! s.isEmpty())
{
lineList.add(s);
}
wrapPos = spacePos;
}
else
{
// We didn't find any spaces, so we'll have to insert a hard break at
// the specified wrap column.
lineList.add(line.substring(lastWrapPos, wrapPos));
}
// Skip over any spaces before the next non-space character.
while ((wrapPos < length) && (line.charAt(wrapPos) == ' '))
{
wrapPos++;
}
lastWrapPos = wrapPos;
wrapPos += maxSubsequentLineWidth;
if (wrapPos >= length)
{
// The last fragment can fit on the line, so we can handle that now and
// break.
if (lastWrapPos >= length)
{
break;
}
else
{
final String s = line.substring(lastWrapPos);
lineList.add(s);
break;
}
}
}
return lineList;
}
/**
* 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 {@link 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
* {@link ExampleCommandLineArgument#getCleanArgument}.
*
* @param s The string to be processed. It must not be {@code null}.
*
* @return 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.
*/
@NotNull()
public static String cleanExampleCommandLineArgument(@NotNull final String s)
{
return ExampleCommandLineArgument.getCleanArgument(s).getLocalForm();
}
/**
* Retrieves a single string which is a concatenation of all of the provided
* strings.
*
* @param a The array of strings to concatenate. It must not be
* {@code null} but may be empty.
*
* @return A string containing a concatenation of all of the strings in the
* provided array.
*/
@NotNull()
public static String concatenateStrings(@NotNull final String... a)
{
return concatenateStrings(null, null, " ", null, null, a);
}
/**
* Retrieves a single string which is a concatenation of all of the provided
* strings.
*
* @param l The list of strings to concatenate. It must not be
* {@code null} but may be empty.
*
* @return A string containing a concatenation of all of the strings in the
* provided list.
*/
@NotNull()
public static String concatenateStrings(@NotNull final List l)
{
return concatenateStrings(null, null, " ", null, null, l);
}
/**
* Retrieves a single string which is a concatenation of all of the provided
* strings.
*
* @param beforeList A string that should be placed at the beginning of
* the list. It may be {@code null} or empty if
* nothing should be placed at the beginning of the
* list.
* @param beforeElement A string that should be placed before each element
* in the list. It may be {@code null} or empty if
* nothing should be placed before each element.
* @param betweenElements The separator that should be placed between
* elements in the list. It may be {@code null} or
* empty if no separator should be placed between
* elements.
* @param afterElement A string that should be placed after each element
* in the list. It may be {@code null} or empty if
* nothing should be placed after each element.
* @param afterList A string that should be placed at the end of the
* list. It may be {@code null} or empty if nothing
* should be placed at the end of the list.
* @param a The array of strings to concatenate. It must not
* be {@code null} but may be empty.
*
* @return A string containing a concatenation of all of the strings in the
* provided list.
*/
@NotNull()
public static String concatenateStrings(@Nullable final String beforeList,
@Nullable final String beforeElement,
@Nullable final String betweenElements,
@Nullable final String afterElement,
@Nullable final String afterList,
@NotNull final String... a)
{
return concatenateStrings(beforeList, beforeElement, betweenElements,
afterElement, afterList, Arrays.asList(a));
}
/**
* Retrieves a single string which is a concatenation of all of the provided
* strings.
*
* @param beforeList A string that should be placed at the beginning of
* the list. It may be {@code null} or empty if
* nothing should be placed at the beginning of the
* list.
* @param beforeElement A string that should be placed before each element
* in the list. It may be {@code null} or empty if
* nothing should be placed before each element.
* @param betweenElements The separator that should be placed between
* elements in the list. It may be {@code null} or
* empty if no separator should be placed between
* elements.
* @param afterElement A string that should be placed after each element
* in the list. It may be {@code null} or empty if
* nothing should be placed after each element.
* @param afterList A string that should be placed at the end of the
* list. It may be {@code null} or empty if nothing
* should be placed at the end of the list.
* @param l The list of strings to concatenate. It must not
* be {@code null} but may be empty.
*
* @return A string containing a concatenation of all of the strings in the
* provided list.
*/
@NotNull()
public static String concatenateStrings(@Nullable final String beforeList,
@Nullable final String beforeElement,
@Nullable final String betweenElements,
@Nullable final String afterElement,
@Nullable final String afterList,
@NotNull final List l)
{
Validator.ensureNotNull(l);
final StringBuilder buffer = new StringBuilder();
if (beforeList != null)
{
buffer.append(beforeList);
}
final Iterator iterator = l.iterator();
while (iterator.hasNext())
{
if (beforeElement != null)
{
buffer.append(beforeElement);
}
buffer.append(iterator.next());
if (afterElement != null)
{
buffer.append(afterElement);
}
if ((betweenElements != null) && iterator.hasNext())
{
buffer.append(betweenElements);
}
}
if (afterList != null)
{
buffer.append(afterList);
}
return buffer.toString();
}
/**
* 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.
*
* @param s The number of seconds to be represented.
*
* @return A string containing a human-readable representation of the
* provided time.
*/
@NotNull()
public static String secondsToHumanReadableDuration(final long s)
{
return millisToHumanReadableDuration(s * 1000L);
}
/**
* 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.
*
* @param m The number of milliseconds to be represented.
*
* @return A string containing a human-readable representation of the
* provided time.
*/
@NotNull()
public static String millisToHumanReadableDuration(final long m)
{
final StringBuilder buffer = new StringBuilder();
long numMillis = m;
final long numDays = numMillis / 86_400_000L;
if (numDays > 0)
{
numMillis -= (numDays * 86_400_000L);
if (numDays == 1)
{
buffer.append(INFO_NUM_DAYS_SINGULAR.get(numDays));
}
else
{
buffer.append(INFO_NUM_DAYS_PLURAL.get(numDays));
}
}
final long numHours = numMillis / 3_600_000L;
if (numHours > 0)
{
numMillis -= (numHours * 3_600_000L);
if (buffer.length() > 0)
{
buffer.append(", ");
}
if (numHours == 1)
{
buffer.append(INFO_NUM_HOURS_SINGULAR.get(numHours));
}
else
{
buffer.append(INFO_NUM_HOURS_PLURAL.get(numHours));
}
}
final long numMinutes = numMillis / 60_000L;
if (numMinutes > 0)
{
numMillis -= (numMinutes * 60_000L);
if (buffer.length() > 0)
{
buffer.append(", ");
}
if (numMinutes == 1)
{
buffer.append(INFO_NUM_MINUTES_SINGULAR.get(numMinutes));
}
else
{
buffer.append(INFO_NUM_MINUTES_PLURAL.get(numMinutes));
}
}
if (numMillis == 1000)
{
if (buffer.length() > 0)
{
buffer.append(", ");
}
buffer.append(INFO_NUM_SECONDS_SINGULAR.get(1));
}
else if ((numMillis > 0) || (buffer.length() == 0))
{
if (buffer.length() > 0)
{
buffer.append(", ");
}
final long numSeconds = numMillis / 1000L;
numMillis -= (numSeconds * 1000L);
if ((numMillis % 1000L) != 0L)
{
final double numSecondsDouble = numSeconds + (numMillis / 1000.0);
final DecimalFormat decimalFormat = new DecimalFormat("0.000");
buffer.append(INFO_NUM_SECONDS_WITH_DECIMAL.get(
decimalFormat.format(numSecondsDouble)));
}
else
{
buffer.append(INFO_NUM_SECONDS_PLURAL.get(numSeconds));
}
}
return buffer.toString();
}
/**
* Converts the provided number of nanoseconds to milliseconds.
*
* @param nanos The number of nanoseconds to convert to milliseconds.
*
* @return The number of milliseconds that most closely corresponds to the
* specified number of nanoseconds.
*/
public static long nanosToMillis(final long nanos)
{
return Math.max(0L, Math.round(nanos / 1_000_000.0d));
}
/**
* Converts the provided number of milliseconds to nanoseconds.
*
* @param millis The number of milliseconds to convert to nanoseconds.
*
* @return The number of nanoseconds that most closely corresponds to the
* specified number of milliseconds.
*/
public static long millisToNanos(final long millis)
{
return Math.max(0L, (millis * 1_000_000L));
}
/**
* 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.
*
* @param s The string to examine. It must not be {@code null}.
*
* @return {@code true} if the provided string is a valid numeric OID, or
* {@code false} if not.
*/
public static boolean isNumericOID(@NotNull final String s)
{
boolean digitRequired = true;
boolean periodFound = false;
for (final char c : s.toCharArray())
{
switch (c)
{
case '0':
case '1':
case '2':
case '3':
case '4':
case '5':
case '6':
case '7':
case '8':
case '9':
digitRequired = false;
break;
case '.':
if (digitRequired)
{
return false;
}
else
{
digitRequired = true;
}
periodFound = true;
break;
default:
return false;
}
}
return (periodFound && (! digitRequired));
}
/**
* Capitalizes the provided string. The first character will be converted to
* uppercase, and the rest of the string will be left unaltered.
*
* @param s The string to be capitalized.
*
* @return A capitalized version of the provided string, or {@code null} if
* the provided string was {@code null}.
*/
@Nullable()
public static String capitalize(@Nullable final String s)
{
return capitalize(s, false);
}
/**
* Capitalizes the provided string. The first character of the string (or
* optionally the first character of each word in the string)
*
* @param s The string to be capitalized.
* @param allWords Indicates whether to capitalize all words in the string,
* or only the first word.
*
* @return A capitalized version of the provided string, or {@code null} if
* the provided string was {@code null}.
*/
@Nullable()
public static String capitalize(@Nullable final String s,
final boolean allWords)
{
if (s == null)
{
return null;
}
switch (s.length())
{
case 0:
return s;
case 1:
return s.toUpperCase();
default:
boolean capitalize = true;
final char[] chars = s.toCharArray();
final StringBuilder buffer = new StringBuilder(chars.length);
for (final char c : chars)
{
// Whitespace and punctuation will be considered word breaks.
if (Character.isWhitespace(c) ||
(((c >= '!') && (c <= '.')) ||
((c >= ':') && (c <= '@')) ||
((c >= '[') && (c <= '`')) ||
((c >= '{') && (c <= '~'))))
{
buffer.append(c);
capitalize |= allWords;
}
else if (capitalize)
{
buffer.append(Character.toUpperCase(c));
capitalize = false;
}
else
{
buffer.append(c);
}
}
return buffer.toString();
}
}
/**
* Encodes the provided UUID to a byte array containing its 128-bit
* representation.
*
* @param uuid The UUID to be encoded. It must not be {@code null}.
*
* @return The byte array containing the 128-bit encoded UUID.
*/
@NotNull()
public static byte[] encodeUUID(@NotNull final UUID uuid)
{
final byte[] b = new byte[16];
final long mostSignificantBits = uuid.getMostSignificantBits();
b[0] = (byte) ((mostSignificantBits >> 56) & 0xFF);
b[1] = (byte) ((mostSignificantBits >> 48) & 0xFF);
b[2] = (byte) ((mostSignificantBits >> 40) & 0xFF);
b[3] = (byte) ((mostSignificantBits >> 32) & 0xFF);
b[4] = (byte) ((mostSignificantBits >> 24) & 0xFF);
b[5] = (byte) ((mostSignificantBits >> 16) & 0xFF);
b[6] = (byte) ((mostSignificantBits >> 8) & 0xFF);
b[7] = (byte) (mostSignificantBits & 0xFF);
final long leastSignificantBits = uuid.getLeastSignificantBits();
b[8] = (byte) ((leastSignificantBits >> 56) & 0xFF);
b[9] = (byte) ((leastSignificantBits >> 48) & 0xFF);
b[10] = (byte) ((leastSignificantBits >> 40) & 0xFF);
b[11] = (byte) ((leastSignificantBits >> 32) & 0xFF);
b[12] = (byte) ((leastSignificantBits >> 24) & 0xFF);
b[13] = (byte) ((leastSignificantBits >> 16) & 0xFF);
b[14] = (byte) ((leastSignificantBits >> 8) & 0xFF);
b[15] = (byte) (leastSignificantBits & 0xFF);
return b;
}
/**
* Decodes the value of the provided byte array as a Java UUID.
*
* @param b The byte array to be decoded as a UUID. It must not be
* {@code null}.
*
* @return The decoded UUID.
*
* @throws ParseException If the provided byte array cannot be parsed as a
* UUID.
*/
@NotNull()
public static UUID decodeUUID(@NotNull final byte[] b)
throws ParseException
{
if (b.length != 16)
{
throw new ParseException(ERR_DECODE_UUID_INVALID_LENGTH.get(toHex(b)), 0);
}
long mostSignificantBits = 0L;
for (int i=0; i < 8; i++)
{
mostSignificantBits = (mostSignificantBits << 8) | (b[i] & 0xFF);
}
long leastSignificantBits = 0L;
for (int i=8; i < 16; i++)
{
leastSignificantBits = (leastSignificantBits << 8) | (b[i] & 0xFF);
}
return new UUID(mostSignificantBits, leastSignificantBits);
}
/**
* Returns {@code true} if and only if the current process is running on
* a Windows-based operating system.
*
* @return {@code true} if the current process is running on a Windows-based
* operating system and {@code false} otherwise.
*/
public static boolean isWindows()
{
final String osName = toLowerCase(getSystemProperty("os.name"));
return ((osName != null) && osName.contains("windows"));
}
/**
* Retrieves the string that should be appended to the end of all but the last
* line of a multi-line command to indicate that the command continues onto
* the next line.
*
* This will be the caret (also called a circumflex accent) character on
* Windows systems, and a backslash (also called a reverse solidus) character
* on Linux and UNIX-based systems.
*
* The string value that is returned will not include a space, but it should
* generally be preceded by one or more space to separate it from the previous
* component on the command line.
*
* @return The string that should be appended (generally after one or more
* spaces to separate it from the previous component) to the end of
* all but the last line of a multi-line command to indicate that the
* command continues onto the next line.
*/
@NotNull()
public static String getCommandLineContinuationString()
{
if (isWindows())
{
return "^";
}
else
{
return "\\";
}
}
/**
* 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").
*
* @param s The string to be converted to an argument list.
*
* @return The parsed argument list.
*
* @throws ParseException If a problem is encountered while attempting to
* parse the given string to an argument list.
*/
@NotNull()
public static List toArgumentList(@Nullable final String s)
throws ParseException
{
if ((s == null) || s.isEmpty())
{
return Collections.emptyList();
}
int quoteStartPos = -1;
boolean inEscape = false;
final ArrayList argList = new ArrayList<>(20);
final StringBuilder currentArg = new StringBuilder();
for (int i=0; i < s.length(); i++)
{
final char c = s.charAt(i);
if (inEscape)
{
currentArg.append(c);
inEscape = false;
continue;
}
if (c == '\\')
{
inEscape = true;
}
else if (c == '"')
{
if (quoteStartPos >= 0)
{
quoteStartPos = -1;
}
else
{
quoteStartPos = i;
}
}
else if (c == ' ')
{
if (quoteStartPos >= 0)
{
currentArg.append(c);
}
else if (currentArg.length() > 0)
{
argList.add(currentArg.toString());
currentArg.setLength(0);
}
}
else
{
currentArg.append(c);
}
}
if (s.endsWith("\\") && (! s.endsWith("\\\\")))
{
throw new ParseException(ERR_ARG_STRING_DANGLING_BACKSLASH.get(),
(s.length() - 1));
}
if (quoteStartPos >= 0)
{
throw new ParseException(ERR_ARG_STRING_UNMATCHED_QUOTE.get(
quoteStartPos), quoteStartPos);
}
if (currentArg.length() > 0)
{
argList.add(currentArg.toString());
}
return Collections.unmodifiableList(argList);
}
/**
* Retrieves an array containing the elements of the provided collection.
*
* @param The type of element included in the provided
* collection.
* @param collection The collection to convert to an array.
* @param type The type of element contained in the collection.
*
* @return An array containing the elements of the provided list, or
* {@code null} if the provided list is {@code null}.
*/
@Nullable()
public static T[] toArray(@Nullable final Collection collection,
@NotNull final Class type)
{
if (collection == null)
{
return null;
}
@SuppressWarnings("unchecked")
final T[] array = (T[]) Array.newInstance(type, collection.size());
return collection.toArray(array);
}
/**
* Creates a modifiable list with all of the items of the provided array in
* the same order. This method behaves much like {@code Arrays.asList},
* except that if the provided array is {@code null}, then it will return a
* {@code null} list rather than throwing an exception.
*
* @param The type of item contained in the provided array.
*
* @param array The array of items to include in the list.
*
* @return The list that was created, or {@code null} if the provided array
* was {@code null}.
*/
@Nullable()
public static List toList(@Nullable final T[] array)
{
if (array == null)
{
return null;
}
final ArrayList l = new ArrayList<>(array.length);
l.addAll(Arrays.asList(array));
return l;
}
/**
* Creates a modifiable list with all of the items of the provided array in
* the same order. This method behaves much like {@code Arrays.asList},
* except that if the provided array is {@code null}, then it will return an
* empty list rather than throwing an exception.
*
* @param The type of item contained in the provided array.
*
* @param array The array of items to include in the list.
*
* @return The list that was created, or an empty list if the provided array
* was {@code null}.
*/
@NotNull()
public static List toNonNullList(@Nullable final T[] array)
{
if (array == null)
{
return new ArrayList<>(0);
}
final ArrayList l = new ArrayList<>(array.length);
l.addAll(Arrays.asList(array));
return l;
}
/**
* Indicates whether both of the provided objects are {@code null} or both
* are logically equal (using the {@code equals} method).
*
* @param o1 The first object for which to make the determination.
* @param o2 The second object for which to make the determination.
*
* @return {@code true} if both objects are {@code null} or both are
* logically equal, or {@code false} if only one of the objects is
* {@code null} or they are not logically equal.
*/
public static boolean bothNullOrEqual(@Nullable final Object o1,
@Nullable final Object o2)
{
if (o1 == null)
{
return (o2 == null);
}
else if (o2 == null)
{
return false;
}
return o1.equals(o2);
}
/**
* Indicates whether both of the provided strings are {@code null} or both
* are logically equal ignoring differences in capitalization (using the
* {@code equalsIgnoreCase} method).
*
* @param s1 The first string for which to make the determination.
* @param s2 The second string for which to make the determination.
*
* @return {@code true} if both strings are {@code null} or both are
* logically equal ignoring differences in capitalization, or
* {@code false} if only one of the objects is {@code null} or they
* are not logically equal ignoring capitalization.
*/
public static boolean bothNullOrEqualIgnoreCase(@Nullable final String s1,
@Nullable final String s2)
{
if (s1 == null)
{
return (s2 == null);
}
else if (s2 == null)
{
return false;
}
return s1.equalsIgnoreCase(s2);
}
/**
* 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 {@code null} strings, and that
* no string appears more than once in each array.
*
* @param a1 The first array for which to make the determination.
* @param a2 The second array for which to make the determination.
*
* @return {@code true} if both arrays have the same set of strings, or
* {@code false} if not.
*/
public static boolean stringsEqualIgnoreCaseOrderIndependent(
@Nullable final String[] a1,
@Nullable final String[] a2)
{
if (a1 == null)
{
return (a2 == null);
}
else if (a2 == null)
{
return false;
}
if (a1.length != a2.length)
{
return false;
}
if (a1.length == 1)
{
return (a1[0].equalsIgnoreCase(a2[0]));
}
final HashSet s1 = new HashSet<>(computeMapCapacity(a1.length));
for (final String s : a1)
{
s1.add(toLowerCase(s));
}
final HashSet s2 = new HashSet<>(computeMapCapacity(a2.length));
for (final String s : a2)
{
s2.add(toLowerCase(s));
}
return s1.equals(s2);
}
/**
* Indicates whether the provided arrays have the same elements, ignoring the
* order in which they appear. It is assumed that neither array contains
* {@code null} elements, and that no element appears more than once in each
* array.
*
* @param The type of element contained in the arrays.
*
* @param a1 The first array for which to make the determination.
* @param a2 The second array for which to make the determination.
*
* @return {@code true} if both arrays have the same set of elements, or
* {@code false} if not.
*/
public static boolean arraysEqualOrderIndependent(@Nullable final T[] a1,
@Nullable final T[] a2)
{
if (a1 == null)
{
return (a2 == null);
}
else if (a2 == null)
{
return false;
}
if (a1.length != a2.length)
{
return false;
}
if (a1.length == 1)
{
return (a1[0].equals(a2[0]));
}
final HashSet s1 = new HashSet<>(Arrays.asList(a1));
final HashSet s2 = new HashSet<>(Arrays.asList(a2));
return s1.equals(s2);
}
/**
* Determines the number of bytes in a UTF-8 character that starts with the
* given byte.
*
* @param b The byte for which to make the determination.
*
* @return 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.
*/
public static int numBytesInUTF8CharacterWithFirstByte(final byte b)
{
if ((b & 0x7F) == b)
{
return 1;
}
else if ((b & 0xE0) == 0xC0)
{
return 2;
}
else if ((b & 0xF0) == 0xE0)
{
return 3;
}
else if ((b & 0xF8) == 0xF0)
{
return 4;
}
else
{
return -1;
}
}
/**
* Indicates whether the provided attribute name should be considered a
* sensitive attribute for the purposes of {@code toCode} methods. If an
* attribute is considered sensitive, then its values will be redacted in the
* output of the {@code toCode} methods.
*
* @param name The name for which to make the determination. It may or may
* not include attribute options. It must not be {@code null}.
*
* @return {@code true} if the specified attribute is one that should be
* considered sensitive for the
*/
public static boolean isSensitiveToCodeAttribute(@NotNull final String name)
{
final String lowerBaseName = Attribute.getBaseName(name).toLowerCase();
return TO_CODE_SENSITIVE_ATTRIBUTE_NAMES.contains(lowerBaseName);
}
/**
* Retrieves a set containing the base names (in all lowercase characters) of
* any attributes that should be considered sensitive for the purposes of the
* {@code toCode} methods. By default, only the userPassword and
* authPassword attributes and their respective OIDs will be included.
*
* @return A set containing the base names (in all lowercase characters) of
* any attributes that should be considered sensitive for the
* purposes of the {@code toCode} methods.
*/
@NotNull()
public static Set getSensitiveToCodeAttributeBaseNames()
{
return TO_CODE_SENSITIVE_ATTRIBUTE_NAMES;
}
/**
* Specifies the names of any attributes that should be considered sensitive
* for the purposes of the {@code toCode} methods.
*
* @param names The names of any attributes that should be considered
* sensitive for the purposes of the {@code toCode} methods.
* It may be {@code null} or empty if no attributes should be
* considered sensitive.
*/
public static void setSensitiveToCodeAttributes(
@Nullable final String... names)
{
setSensitiveToCodeAttributes(toList(names));
}
/**
* Specifies the names of any attributes that should be considered sensitive
* for the purposes of the {@code toCode} methods.
*
* @param names The names of any attributes that should be considered
* sensitive for the purposes of the {@code toCode} methods.
* It may be {@code null} or empty if no attributes should be
* considered sensitive.
*/
public static void setSensitiveToCodeAttributes(
@Nullable final Collection names)
{
if ((names == null) || names.isEmpty())
{
TO_CODE_SENSITIVE_ATTRIBUTE_NAMES = Collections.emptySet();
}
else
{
final LinkedHashSet nameSet = new LinkedHashSet<>(names.size());
for (final String s : names)
{
nameSet.add(Attribute.getBaseName(s).toLowerCase());
}
TO_CODE_SENSITIVE_ATTRIBUTE_NAMES = Collections.unmodifiableSet(nameSet);
}
}
/**
* Creates a new {@code 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.
*
* @param message The message to use for the exception. This may be
* {@code null} if the message should be generated from the
* provided cause.
* @param cause The underlying cause for the exception. It may be
* {@code null} if the exception should have only a message.
*
* @return The {@code IOException} object that was created.
*/
@NotNull()
public static IOException createIOExceptionWithCause(
@Nullable final String message,
@Nullable final Throwable cause)
{
if (cause == null)
{
return new IOException(message);
}
else if (message == null)
{
return new IOException(cause);
}
else
{
return new IOException(message, cause);
}
}
/**
* Converts the provided string (which may include line breaks) into a list
* containing the lines without the line breaks.
*
* @param s The string to convert into a list of its representative lines.
*
* @return A list containing the lines that comprise the given string.
*/
@NotNull()
public static List stringToLines(@Nullable final String s)
{
final ArrayList l = new ArrayList<>(10);
if (s == null)
{
return l;
}
final BufferedReader reader = new BufferedReader(new StringReader(s));
try
{
while (true)
{
try
{
final String line = reader.readLine();
if (line == null)
{
return l;
}
else
{
l.add(line);
}
}
catch (final Exception e)
{
Debug.debugException(e);
// This should never happen. If it does, just return a list
// containing a single item that is the original string.
l.clear();
l.add(s);
return l;
}
}
}
finally
{
try
{
// This is technically not necessary in this case, but it's good form.
reader.close();
}
catch (final Exception e)
{
Debug.debugException(e);
// This should never happen, and there's nothing we need to do even if
// it does.
}
}
}
/**
* 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).
*
* @param lines The lines to include in the string.
*
* @return The string resulting from concatenating the provided lines with
* line breaks.
*/
@NotNull()
public static String linesToString(@Nullable final CharSequence... lines)
{
if (lines == null)
{
return "";
}
return linesToString(Arrays.asList(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).
*
* @param lines The lines to include in the string.
*
* @return The string resulting from concatenating the provided lines with
* line breaks.
*/
@NotNull()
public static String linesToString(
@Nullable final List lines)
{
if (lines == null)
{
return "";
}
final StringBuilder buffer = new StringBuilder();
for (final CharSequence line : lines)
{
buffer.append(line);
buffer.append(EOL);
}
return buffer.toString();
}
/**
* Constructs a {@code File} object from the provided path.
*
* @param baseDirectory The base directory to use as the starting point.
* It must not be {@code null} and is expected to
* represent a directory.
* @param 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 {@code null} or empty if the
* base directory should be used.
*
* @return The constructed {@code File} object.
*/
@NotNull()
public static File constructPath(@NotNull final File baseDirectory,
@Nullable final String... pathElements)
{
Validator.ensureNotNull(baseDirectory);
File f = baseDirectory;
if (pathElements != null)
{
for (final String pathElement : pathElements)
{
f = new File(f, pathElement);
}
}
return f;
}
/**
* 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.
*
* @param bytes The values to include in the byte array.
*
* @return A byte array with the provided set of values.
*/
@NotNull()
public static byte[] byteArray(@Nullable final int... bytes)
{
if ((bytes == null) || (bytes.length == 0))
{
return NO_BYTES;
}
final byte[] byteArray = new byte[bytes.length];
for (int i=0; i < bytes.length; i++)
{
byteArray[i] = (byte) (bytes[i] & 0xFF);
}
return byteArray;
}
/**
* Indicates whether the unit tests are currently running in this JVM.
*
* @return {@code true} if the unit tests are currently running, or
* {@code false} if not.
*/
public static boolean isWithinUnitTest()
{
return IS_WITHIN_UNIT_TESTS;
}
/**
* Throws an {@code Error} or a {@code RuntimeException} based on the provided
* {@code Throwable} object. This method will always throw something,
* regardless of the provided {@code Throwable} object.
*
* @param throwable The {@code Throwable} object to use to create the
* exception to throw.
*
* @throws Error If the provided {@code Throwable} object is an
* {@code Error} instance, then that {@code Error} instance
* will be re-thrown.
*
* @throws RuntimeException If the provided {@code Throwable} object is a
* {@code RuntimeException} instance, then that
* {@code RuntimeException} instance will be
* re-thrown. Otherwise, it must be a checked
* exception and that checked exception will be
* re-thrown as a {@code RuntimeException}.
*/
public static void throwErrorOrRuntimeException(
@NotNull final Throwable throwable)
throws Error, RuntimeException
{
Validator.ensureNotNull(throwable);
if (throwable instanceof Error)
{
throw (Error) throwable;
}
else if (throwable instanceof RuntimeException)
{
throw (RuntimeException) throwable;
}
else
{
throw new RuntimeException(throwable);
}
}
/**
* Re-throws the provided {@code Throwable} instance only if it is an
* {@code Error} or a {@code RuntimeException} instance; otherwise, this
* method will return without taking any action.
*
* @param throwable The {@code Throwable} object to examine and potentially
* re-throw.
*
* @throws Error If the provided {@code Throwable} object is an
* {@code Error} instance, then that {@code Error} instance
* will be re-thrown.
*
* @throws RuntimeException If the provided {@code Throwable} object is a
* {@code RuntimeException} instance, then that
* {@code RuntimeException} instance will be
* re-thrown.
*/
public static void rethrowIfErrorOrRuntimeException(
@NotNull final Throwable throwable)
throws Error, RuntimeException
{
if (throwable instanceof Error)
{
throw (Error) throwable;
}
else if (throwable instanceof RuntimeException)
{
throw (RuntimeException) throwable;
}
}
/**
* Re-throws the provided {@code Throwable} instance only if it is an
* {@code Error}; otherwise, this method will return without taking any
* action.
*
* @param throwable The {@code Throwable} object to examine and potentially
* re-throw.
*
* @throws Error If the provided {@code Throwable} object is an
* {@code Error} instance, then that {@code Error} instance
* will be re-thrown.
*/
public static void rethrowIfError(@NotNull final Throwable throwable)
throws Error
{
if (throwable instanceof Error)
{
throw (Error) throwable;
}
}
/**
* 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.
*
* @param 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.
*
* @return The capacity that should be used for a map or a set with the
* expected number of elements
*/
public static int computeMapCapacity(final int expectedItemCount)
{
switch (expectedItemCount)
{
case 0:
return 0;
case 1:
return 2;
case 2:
return 3;
case 3:
return 5;
case 4:
return 6;
case 5:
return 7;
case 6:
return 9;
case 7:
return 10;
case 8:
return 11;
case 9:
return 13;
case 10:
return 14;
case 11:
return 15;
case 12:
return 17;
case 13:
return 18;
case 14:
return 19;
case 15:
return 21;
case 16:
return 22;
case 17:
return 23;
case 18:
return 25;
case 19:
return 26;
case 20:
return 27;
case 30:
return 41;
case 40:
return 54;
case 50:
return 67;
case 60:
return 81;
case 70:
return 94;
case 80:
return 107;
case 90:
return 121;
case 100:
return 134;
case 110:
return 147;
case 120:
return 161;
case 130:
return 174;
case 140:
return 187;
case 150:
return 201;
case 160:
return 214;
case 170:
return 227;
case 180:
return 241;
case 190:
return 254;
case 200:
return 267;
default:
Validator.ensureTrue((expectedItemCount >= 0),
"StaticUtils.computeMapOrSetCapacity.expectedItemCount must be " +
"greater than or equal to zero.");
// NOTE: 536,870,911 is Integer.MAX_VALUE/4. If the value is larger
// than that, then we'll fall back to using floating-point arithmetic
//
if (expectedItemCount > 536_870_911)
{
final int computedCapacity = ((int) (expectedItemCount / 0.75)) + 1;
if (computedCapacity <= expectedItemCount)
{
// This suggests that the expected number of items is so big that
// the computed capacity can't be adequately represented by an
// integer. In that case, we'll just return the expected item
// count and let the map or set get re-hashed/re-balanced if it
// actually gets anywhere near that size.
return expectedItemCount;
}
else
{
return computedCapacity;
}
}
else
{
return ((expectedItemCount * 4) / 3) + 1;
}
}
}
/**
* Creates an unmodifiable set containing the provided items. The iteration
* order of the provided items will be preserved.
*
* @param The type of item to include in the set.
* @param items The items to include in the set. It must not be
* {@code null}, but may be empty.
*
* @return An unmodifiable set containing the provided items.
*/
@SafeVarargs()
@SuppressWarnings("varargs")
@NotNull()
public static Set setOf(@NotNull final T... items)
{
return Collections.unmodifiableSet(
new LinkedHashSet<>(Arrays.asList(items)));
}
/**
* Creates a {@code HashSet} containing the provided items.
*
* @param The type of item to include in the set.
* @param items The items to include in the set. It must not be
* {@code null}, but may be empty.
*
* @return A {@code HashSet} containing the provided items.
*/
@SafeVarargs()
@SuppressWarnings("varargs")
@NotNull()
public static HashSet hashSetOf(@NotNull final T... items)
{
return new HashSet<>(Arrays.asList(items));
}
/**
* Creates a {@code LinkedHashSet} containing the provided items.
*
* @param The type of item to include in the set.
* @param items The items to include in the set. It must not be
* {@code null}, but may be empty.
*
* @return A {@code LinkedHashSet} containing the provided items.
*/
@SafeVarargs()
@SuppressWarnings("varargs")
@NotNull()
public static LinkedHashSet linkedHashSetOf(@NotNull final T... items)
{
return new LinkedHashSet<>(Arrays.asList(items));
}
/**
* Creates a {@code TreeSet} containing the provided items.
*
* @param The type of item to include in the set.
* @param items The items to include in the set. It must not be
* {@code null}, but may be empty.
*
* @return A {@code LinkedHashSet} containing the provided items.
*/
@SafeVarargs()
@SuppressWarnings("varargs")
@NotNull()
public static TreeSet treeSetOf(@NotNull final T... items)
{
return new TreeSet<>(Arrays.asList(items));
}
/**
* Creates an unmodifiable map containing the provided items.
*
* @param The type for the map keys.
* @param The type for the map values.
* @param key The only key to include in the map.
* @param value The only value to include in the map.
*
* @return The unmodifiable map that was created.
*/
@NotNull()
public static Map mapOf(@NotNull final K key,
@NotNull final V value)
{
return Collections.singletonMap(key, value);
}
/**
* Creates an unmodifiable map containing the provided items.
*
* @param The type for the map keys.
* @param The type for the map values.
* @param key1 The first key to include in the map.
* @param value1 The first value to include in the map.
* @param key2 The second key to include in the map.
* @param value2 The second value to include in the map.
*
* @return The unmodifiable map that was created.
*/
@NotNull()
public static Map mapOf(@NotNull final K key1,
@NotNull final V value1,
@NotNull final K key2,
@NotNull final V value2)
{
final LinkedHashMap map = new LinkedHashMap<>(computeMapCapacity(2));
map.put(key1, value1);
map.put(key2, value2);
return Collections.unmodifiableMap(map);
}
/**
* Creates an unmodifiable map containing the provided items.
*
* @param The type for the map keys.
* @param The type for the map values.
* @param key1 The first key to include in the map.
* @param value1 The first value to include in the map.
* @param key2 The second key to include in the map.
* @param value2 The second value to include in the map.
* @param key3 The third key to include in the map.
* @param value3 The third value to include in the map.
*
* @return The unmodifiable map that was created.
*/
@NotNull()
public static Map mapOf(@NotNull final K key1,
@NotNull final V value1,
@NotNull final K key2,
@NotNull final V value2,
@NotNull final K key3,
@NotNull final V value3)
{
final LinkedHashMap map = new LinkedHashMap<>(computeMapCapacity(3));
map.put(key1, value1);
map.put(key2, value2);
map.put(key3, value3);
return Collections.unmodifiableMap(map);
}
/**
* Creates an unmodifiable map containing the provided items.
*
* @param The type for the map keys.
* @param The type for the map values.
* @param key1 The first key to include in the map.
* @param value1 The first value to include in the map.
* @param key2 The second key to include in the map.
* @param value2 The second value to include in the map.
* @param key3 The third key to include in the map.
* @param value3 The third value to include in the map.
* @param key4 The fourth key to include in the map.
* @param value4 The fourth value to include in the map.
*
* @return The unmodifiable map that was created.
*/
@NotNull()
public static Map mapOf(@NotNull final K key1,
@NotNull final V value1,
@NotNull final K key2,
@NotNull final V value2,
@NotNull final K key3,
@NotNull final V value3,
@NotNull final K key4,
@NotNull final V value4)
{
final LinkedHashMap map = new LinkedHashMap<>(computeMapCapacity(4));
map.put(key1, value1);
map.put(key2, value2);
map.put(key3, value3);
map.put(key4, value4);
return Collections.unmodifiableMap(map);
}
/**
* Creates an unmodifiable map containing the provided items.
*
* @param The type for the map keys.
* @param The type for the map values.
* @param key1 The first key to include in the map.
* @param value1 The first value to include in the map.
* @param key2 The second key to include in the map.
* @param value2 The second value to include in the map.
* @param key3 The third key to include in the map.
* @param value3 The third value to include in the map.
* @param key4 The fourth key to include in the map.
* @param value4 The fourth value to include in the map.
* @param key5 The fifth key to include in the map.
* @param value5 The fifth value to include in the map.
*
* @return The unmodifiable map that was created.
*/
@NotNull()
public static Map mapOf(@NotNull final K key1,
@NotNull final V value1,
@NotNull final K key2,
@NotNull final V value2,
@NotNull final K key3,
@NotNull final V value3,
@NotNull final K key4,
@NotNull final V value4,
@NotNull final K key5,
@NotNull final V value5)
{
final LinkedHashMap map = new LinkedHashMap<>(computeMapCapacity(5));
map.put(key1, value1);
map.put(key2, value2);
map.put(key3, value3);
map.put(key4, value4);
map.put(key5, value5);
return Collections.unmodifiableMap(map);
}
/**
* Creates an unmodifiable map containing the provided items.
*
* @param The type for the map keys.
* @param The type for the map values.
* @param key1 The first key to include in the map.
* @param value1 The first value to include in the map.
* @param key2 The second key to include in the map.
* @param value2 The second value to include in the map.
* @param key3 The third key to include in the map.
* @param value3 The third value to include in the map.
* @param key4 The fourth key to include in the map.
* @param value4 The fourth value to include in the map.
* @param key5 The fifth key to include in the map.
* @param value5 The fifth value to include in the map.
* @param key6 The sixth key to include in the map.
* @param value6 The sixth value to include in the map.
*
* @return The unmodifiable map that was created.
*/
@NotNull()
public static Map mapOf(@NotNull final K key1,
@NotNull final V value1,
@NotNull final K key2,
@NotNull final V value2,
@NotNull final K key3,
@NotNull final V value3,
@NotNull final K key4,
@NotNull final V value4,
@NotNull final K key5,
@NotNull final V value5,
@NotNull final K key6,
@NotNull final V value6)
{
final LinkedHashMap map = new LinkedHashMap<>(computeMapCapacity(6));
map.put(key1, value1);
map.put(key2, value2);
map.put(key3, value3);
map.put(key4, value4);
map.put(key5, value5);
map.put(key6, value6);
return Collections.unmodifiableMap(map);
}
/**
* Creates an unmodifiable map containing the provided items.
*
* @param The type for the map keys.
* @param The type for the map values.
* @param key1 The first key to include in the map.
* @param value1 The first value to include in the map.
* @param key2 The second key to include in the map.
* @param value2 The second value to include in the map.
* @param key3 The third key to include in the map.
* @param value3 The third value to include in the map.
* @param key4 The fourth key to include in the map.
* @param value4 The fourth value to include in the map.
* @param key5 The fifth key to include in the map.
* @param value5 The fifth value to include in the map.
* @param key6 The sixth key to include in the map.
* @param value6 The sixth value to include in the map.
* @param key7 The seventh key to include in the map.
* @param value7 The seventh value to include in the map.
*
* @return The unmodifiable map that was created.
*/
@NotNull()
public static Map mapOf(@NotNull final K key1,
@NotNull final V value1,
@NotNull final K key2,
@NotNull final V value2,
@NotNull final K key3,
@NotNull final V value3,
@NotNull final K key4,
@NotNull final V value4,
@NotNull final K key5,
@NotNull final V value5,
@NotNull final K key6,
@NotNull final V value6,
@NotNull final K key7,
@NotNull final V value7)
{
final LinkedHashMap map = new LinkedHashMap<>(computeMapCapacity(7));
map.put(key1, value1);
map.put(key2, value2);
map.put(key3, value3);
map.put(key4, value4);
map.put(key5, value5);
map.put(key6, value6);
map.put(key7, value7);
return Collections.unmodifiableMap(map);
}
/**
* Creates an unmodifiable map containing the provided items.
*
* @param The type for the map keys.
* @param The type for the map values.
* @param key1 The first key to include in the map.
* @param value1 The first value to include in the map.
* @param key2 The second key to include in the map.
* @param value2 The second value to include in the map.
* @param key3 The third key to include in the map.
* @param value3 The third value to include in the map.
* @param key4 The fourth key to include in the map.
* @param value4 The fourth value to include in the map.
* @param key5 The fifth key to include in the map.
* @param value5 The fifth value to include in the map.
* @param key6 The sixth key to include in the map.
* @param value6 The sixth value to include in the map.
* @param key7 The seventh key to include in the map.
* @param value7 The seventh value to include in the map.
* @param key8 The eighth key to include in the map.
* @param value8 The eighth value to include in the map.
*
* @return The unmodifiable map that was created.
*/
@NotNull()
public static Map mapOf(@NotNull final K key1,
@NotNull final V value1,
@NotNull final K key2,
@NotNull final V value2,
@NotNull final K key3,
@NotNull final V value3,
@NotNull final K key4,
@NotNull final V value4,
@NotNull final K key5,
@NotNull final V value5,
@NotNull final K key6,
@NotNull final V value6,
@NotNull final K key7,
@NotNull final V value7,
@NotNull final K key8,
@NotNull final V value8)
{
final LinkedHashMap map = new LinkedHashMap<>(computeMapCapacity(8));
map.put(key1, value1);
map.put(key2, value2);
map.put(key3, value3);
map.put(key4, value4);
map.put(key5, value5);
map.put(key6, value6);
map.put(key7, value7);
map.put(key8, value8);
return Collections.unmodifiableMap(map);
}
/**
* Creates an unmodifiable map containing the provided items.
*
* @param The type for the map keys.
* @param The type for the map values.
* @param key1 The first key to include in the map.
* @param value1 The first value to include in the map.
* @param key2 The second key to include in the map.
* @param value2 The second value to include in the map.
* @param key3 The third key to include in the map.
* @param value3 The third value to include in the map.
* @param key4 The fourth key to include in the map.
* @param value4 The fourth value to include in the map.
* @param key5 The fifth key to include in the map.
* @param value5 The fifth value to include in the map.
* @param key6 The sixth key to include in the map.
* @param value6 The sixth value to include in the map.
* @param key7 The seventh key to include in the map.
* @param value7 The seventh value to include in the map.
* @param key8 The eighth key to include in the map.
* @param value8 The eighth value to include in the map.
* @param key9 The ninth key to include in the map.
* @param value9 The ninth value to include in the map.
*
* @return The unmodifiable map that was created.
*/
@NotNull()
public static Map mapOf(@NotNull final K key1,
@NotNull final V value1,
@NotNull final K key2,
@NotNull final V value2,
@NotNull final K key3,
@NotNull final V value3,
@NotNull final K key4,
@NotNull final V value4,
@NotNull final K key5,
@NotNull final V value5,
@NotNull final K key6,
@NotNull final V value6,
@NotNull final K key7,
@NotNull final V value7,
@NotNull final K key8,
@NotNull final V value8,
@NotNull final K key9,
@NotNull final V value9)
{
final LinkedHashMap map = new LinkedHashMap<>(computeMapCapacity(9));
map.put(key1, value1);
map.put(key2, value2);
map.put(key3, value3);
map.put(key4, value4);
map.put(key5, value5);
map.put(key6, value6);
map.put(key7, value7);
map.put(key8, value8);
map.put(key9, value9);
return Collections.unmodifiableMap(map);
}
/**
* Creates an unmodifiable map containing the provided items.
*
* @param The type for the map keys.
* @param The type for the map values.
* @param key1 The first key to include in the map.
* @param value1 The first value to include in the map.
* @param key2 The second key to include in the map.
* @param value2 The second value to include in the map.
* @param key3 The third key to include in the map.
* @param value3 The third value to include in the map.
* @param key4 The fourth key to include in the map.
* @param value4 The fourth value to include in the map.
* @param key5 The fifth key to include in the map.
* @param value5 The fifth value to include in the map.
* @param key6 The sixth key to include in the map.
* @param value6 The sixth value to include in the map.
* @param key7 The seventh key to include in the map.
* @param value7 The seventh value to include in the map.
* @param key8 The eighth key to include in the map.
* @param value8 The eighth value to include in the map.
* @param key9 The ninth key to include in the map.
* @param value9 The ninth value to include in the map.
* @param key10 The tenth key to include in the map.
* @param value10 The tenth value to include in the map.
*
* @return The unmodifiable map that was created.
*/
@NotNull()
public static Map mapOf(@NotNull final K key1,
@NotNull final V value1,
@NotNull final K key2,
@NotNull final V value2,
@NotNull final K key3,
@NotNull final V value3,
@NotNull final K key4,
@NotNull final V value4,
@NotNull final K key5,
@NotNull final V value5,
@NotNull final K key6,
@NotNull final V value6,
@NotNull final K key7,
@NotNull final V value7,
@NotNull final K key8,
@NotNull final V value8,
@NotNull final K key9,
@NotNull final V value9,
@NotNull final K key10,
@NotNull final V value10)
{
final LinkedHashMap map = new LinkedHashMap<>(computeMapCapacity(10));
map.put(key1, value1);
map.put(key2, value2);
map.put(key3, value3);
map.put(key4, value4);
map.put(key5, value5);
map.put(key6, value6);
map.put(key7, value7);
map.put(key8, value8);
map.put(key9, value9);
map.put(key10, value10);
return Collections.unmodifiableMap(map);
}
/**
* Creates an unmodifiable map containing the provided items. The map entries
* must have the same data type for keys and values.
*
* @param The type for the map keys and values.
* @param 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.
*
* @return The unmodifiable map that was created.
*/
@SafeVarargs()
@NotNull()
public static Map mapOf(@Nullable final T... items)
{
if ((items == null) || (items.length == 0))
{
return Collections.emptyMap();
}
Validator.ensureTrue(((items.length % 2) == 0),
"StaticUtils.mapOf.items must have an even number of elements");
final int numEntries = items.length / 2;
final LinkedHashMap map =
new LinkedHashMap<>(computeMapCapacity(numEntries));
for (int i=0; i < items.length; )
{
map.put(items[i++], items[i++]);
}
return Collections.unmodifiableMap(map);
}
/**
* Creates an unmodifiable map containing the provided items.
*
* @param The type for the map keys.
* @param The type for the map values.
* @param items The items to include in the map.
*
* @return The unmodifiable map that was created.
*/
@SafeVarargs()
@NotNull()
public static Map mapOfObjectPairs(
@Nullable final ObjectPair... items)
{
if ((items == null) || (items.length == 0))
{
return Collections.emptyMap();
}
final LinkedHashMap map = new LinkedHashMap<>(
computeMapCapacity(items.length));
for (final ObjectPair item : items)
{
map.put(item.getFirst(), item.getSecond());
}
return Collections.unmodifiableMap(map);
}
/**
* Attempts to determine all addresses associated with the local system,
* including loopback addresses.
*
* @param nameResolver The name resolver to use to determine the local host
* and loopback addresses. If this is {@code null},
* then the LDAP SDK's default name resolver will be
* used.
*
* @return A set of the local addresses that were identified.
*/
@NotNull()
public static Set getAllLocalAddresses(
@Nullable final NameResolver nameResolver)
{
return getAllLocalAddresses(nameResolver, true);
}
/**
* Attempts to determine all addresses associated with the local system,
* optionally including loopback addresses.
*
* @param nameResolver The name resolver to use to determine the local
* host and loopback addresses. If this is
* {@code null}, then the LDAP SDK's default name
* resolver will be used.
* @param includeLoopback Indicates whether to include loopback addresses in
* the set that is returned.
*
* @return A set of the local addresses that were identified.
*/
@NotNull()
public static Set getAllLocalAddresses(
@Nullable final NameResolver nameResolver,
final boolean includeLoopback)
{
final NameResolver resolver;
if (nameResolver == null)
{
resolver = LDAPConnectionOptions.DEFAULT_NAME_RESOLVER;
}
else
{
resolver = nameResolver;
}
final LinkedHashSet localAddresses =
new LinkedHashSet<>(computeMapCapacity(10));
try
{
final InetAddress localHostAddress = resolver.getLocalHost();
if (includeLoopback || (! localHostAddress.isLoopbackAddress()))
{
localAddresses.add(localHostAddress);
}
}
catch (final Exception e)
{
Debug.debugException(e);
}
try
{
final Enumeration networkInterfaces =
NetworkInterface.getNetworkInterfaces();
while (networkInterfaces.hasMoreElements())
{
final NetworkInterface networkInterface =
networkInterfaces.nextElement();
if (includeLoopback || (! networkInterface.isLoopback()))
{
final Enumeration interfaceAddresses =
networkInterface.getInetAddresses();
while (interfaceAddresses.hasMoreElements())
{
final InetAddress address = interfaceAddresses.nextElement();
if (includeLoopback || (! address.isLoopbackAddress()))
{
localAddresses.add(address);
}
}
}
}
}
catch (final Exception e)
{
Debug.debugException(e);
}
if (includeLoopback)
{
try
{
localAddresses.add(resolver.getLoopbackAddress());
}
catch (final Exception e)
{
Debug.debugException(e);
}
}
return Collections.unmodifiableSet(localAddresses);
}
/**
* Retrieves the canonical host name for the provided address, if it can be
* resolved to a name.
*
* @param nameResolver The name resolver to use to obtain the canonical
* host name. If this is {@code null}, then the LDAP
* SDK's default name resolver will be used.
* @param address The {@code InetAddress} for which to attempt to
* obtain the canonical host name.
*
* @return The canonical host name for the provided address, or {@code null}
* if it cannot be obtained (either because the attempt returns
* {@code null}, which shouldn't happen, or because it matches the
* IP address).
*/
@Nullable()
public static String getCanonicalHostNameIfAvailable(
@Nullable final NameResolver nameResolver,
@NotNull final InetAddress address)
{
final NameResolver resolver;
if (nameResolver == null)
{
resolver = LDAPConnectionOptions.DEFAULT_NAME_RESOLVER;
}
else
{
resolver = nameResolver;
}
final String hostAddress = address.getHostAddress();
final String trimmedHostAddress =
trimInterfaceNameFromHostAddress(hostAddress);
final String canonicalHostName = resolver.getCanonicalHostName(address);
if ((canonicalHostName == null) ||
canonicalHostName.equalsIgnoreCase(hostAddress) ||
canonicalHostName.equalsIgnoreCase(trimmedHostAddress))
{
return null;
}
return canonicalHostName;
}
/**
* Retrieves the canonical host names for the provided set of
* {@code 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.
*
* @param nameResolver The name resolver to use to obtain the canonical
* host names. If this is {@code null}, then the LDAP
* SDK's default name resolver will be used.
* @param addresses The set of addresses for which to obtain the
* canonical host names.
*
* @return A set of the canonical host names that could be obtained from the
* provided addresses.
*/
@NotNull()
public static Set getAvailableCanonicalHostNames(
@Nullable final NameResolver nameResolver,
@NotNull final Collection addresses)
{
final NameResolver resolver;
if (nameResolver == null)
{
resolver = LDAPConnectionOptions.DEFAULT_NAME_RESOLVER;
}
else
{
resolver = nameResolver;
}
final Set canonicalHostNames =
new LinkedHashSet<>(computeMapCapacity(addresses.size()));
for (final InetAddress address : addresses)
{
final String canonicalHostName =
getCanonicalHostNameIfAvailable(resolver, address);
if (canonicalHostName != null)
{
canonicalHostNames.add(canonicalHostName);
}
}
return Collections.unmodifiableSet(canonicalHostNames);
}
/**
* 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.
*
* @param hostAddress The host address to be trimmed.
*
* @return The provided host address without the interface name.
*/
@NotNull()
public static String trimInterfaceNameFromHostAddress(
@NotNull final String hostAddress)
{
final int percentPos = hostAddress.indexOf('%');
if (percentPos > 0)
{
return hostAddress.substring(0, percentPos);
}
else
{
return hostAddress;
}
}
/**
* Indicates whether the provided address is marked as reserved in the IANA
* IPv4 address space registry at
* https://www.iana.org/assignments/ipv4-address-space/ipv4-address-space.txt
* or the IPv6 address space registry at
* https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.txt.
*
* @param address
* The address for which to make the determination. It must
* not be {@code null}, and it must be an IPv4 or IPv6 address.
* @param includePrivateUseNetworkAddresses
* Indicates whether to consider addresses in a private-use
* network address range (including 10.0.0.0/8, 172.16.0.0/12,
* 192.168.0.0/16, and fc00::/7) as reserved addresses. If this
* is {@code true}, then this method will return {@code true} for
* addresses in a private-use network range; if it is
* {@code false}, then this method will return {@code false} for
* addresses in those ranges. This does not have any effect for
* addresses in other reserved address ranges.
*
* @return {@code true} if the provided address is in a reserved address
* range, or {@code false} if not.
*/
public static boolean isIANAReservedIPAddress(
@NotNull final InetAddress address,
final boolean includePrivateUseNetworkAddresses)
{
if (address instanceof Inet4Address)
{
return isIANAReservedIPv4Address((Inet4Address) address,
includePrivateUseNetworkAddresses);
}
else if (address instanceof Inet6Address)
{
return isIANAReservedIPv6Address((Inet6Address) address,
includePrivateUseNetworkAddresses);
}
else
{
// It's an unrecognized address type. We have to assume it's not
// reserved.
return false;
}
}
/**
* Indicates whether the provided address is marked as reserved in the IANA
* IPv4 address space registry at
* https://www.iana.org/assignments/ipv4-address-space/ipv4-address-space.txt.
* This implementation is based on the version of the registry that was
* updated on 2019-12-27.
*
* @param address
* The IPv4 address for which to make the determination. It must
* not be {@code null}, and it must be an IPv4 address.
* @param includePrivateUseNetworkAddresses
* Indicates whether to consider addresses in a private-use
* network address range as reserved addresses.
*
* @return {@code true} if the provided address is in a reserved address
* range, or {@code false} if not.
*/
public static boolean isIANAReservedIPv4Address(
@NotNull final Inet4Address address,
final boolean includePrivateUseNetworkAddresses)
{
final byte[] addressBytes = address.getAddress();
final int firstOctet = addressBytes[0] & 0xFF;
final int secondOctet = addressBytes[1] & 0xFF;
final int thirdOctet = addressBytes[2] & 0xFF;
switch (firstOctet)
{
// * Addresses 0.*.*.* are reserved for self-identification.
case 0:
// * Addresses 127.*.*.* are reserved for loopback addresses.
case 127:
// * Addresses 224.*.*.* through 239.*.*.* are reserved for multicast.
case 224:
case 225:
case 226:
case 227:
case 228:
case 229:
case 230:
case 231:
case 232:
case 233:
case 234:
case 235:
case 236:
case 237:
case 238:
case 239:
// * Addresses 240.*.*.* through 255.*.*.* are reserved for future use.
case 240:
case 241:
case 242:
case 243:
case 244:
case 245:
case 246:
case 247:
case 248:
case 249:
case 250:
case 251:
case 252:
case 253:
case 254:
case 255:
return true;
// * Addresses 10.*.*.* are reserved for private-use networks.
case 10:
return includePrivateUseNetworkAddresses;
// * Addresses 100.64.0.0 through 100.127.255.255. are in the shared
// address space range described in RFC 6598.
case 100: // First octet 100 -- Partially reserved
return ((secondOctet >= 64) && (secondOctet <= 127));
// * Addresses 169.254.*.* are reserved for link-local addresses.
case 169:
return (secondOctet == 254);
// * Addresses 172.16.0.0 through 172.31.255.255 are reserved for
// private-use networks.
case 172:
if ((secondOctet >= 16) && (secondOctet <= 31))
{
return includePrivateUseNetworkAddresses;
}
else
{
return false;
}
// * Addresses 192.0.0.* are reserved for IPv4 Special Purpose Address.
// * Addresses 192.0.2.* are reserved for TEST-NET-1.
// * Addresses 192.88.99.* are reserved for 6to4 Relay Anycast.
// * Addresses 192.168.*.* are reserved for private-use networks.
case 192:
if (secondOctet == 0)
{
return ((thirdOctet == 0) || (thirdOctet == 2));
}
else if (secondOctet == 88)
{
return (thirdOctet == 99);
}
else if (secondOctet == 168)
{
return includePrivateUseNetworkAddresses;
}
else
{
return false;
}
// * Addresses 198.18.0.0 through 198.19.255.255 are reserved for Network
// Interconnect Device Benchmark Testing.
// * Addresses 198.51.100.* are reserved for TEST-NET-2.
case 198:
if ((secondOctet >= 18) && (secondOctet <= 19))
{
return true;
}
else
{
return ((secondOctet == 51) && (thirdOctet == 100));
}
// * Addresses 203.0.113.* are reserved for TEST-NET-3.
case 203:
return ((secondOctet == 0) && (thirdOctet == 113));
// All other addresses are not reserved.
default:
return false;
}
}
/**
* Indicates whether the provided address is marked as reserved in the IANA
* IPv6 address space registry at
* https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.txt.
* This implementation is based on the version of the registry that was
* updated on 2019-09-13.
*
* @param address
* The IPv4 address for which to make the determination. It must
* not be {@code null}, and it must be an IPv6 address.
* @param includePrivateUseNetworkAddresses
* Indicates whether to consider addresses in a private-use
* network address range as reserved addresses.
*
* @return {@code true} if the provided address is in a reserved address
* range, or {@code false} if not.
*/
public static boolean isIANAReservedIPv6Address(
@NotNull final Inet6Address address,
final boolean includePrivateUseNetworkAddresses)
{
final byte[] addressBytes = address.getAddress();
final int firstOctet = addressBytes[0] & 0xFF;
// Addresses with a first octet between 0x20 and 0x3F are not reserved.
if ((firstOctet >= 0x20) && (firstOctet <= 0x3F))
{
return false;
}
// Addresses with a first octet between 0xFC and 0xFD are reserved for
// private-use networks.
if ((firstOctet >= 0xFC) && (firstOctet <= 0xFD))
{
return includePrivateUseNetworkAddresses;
}
// All other addresses are reserved.
return true;
}
/**
* Reads the bytes that comprise the specified file.
*
* @param path The path to the file to be read.
*
* @return The bytes that comprise the specified file.
*
* @throws IOException If a problem occurs while trying to read the file.
*/
@NotNull()
public static byte[] readFileBytes(@NotNull final String path)
throws IOException
{
return readFileBytes(new File(path));
}
/**
* Reads the bytes that comprise the specified file.
*
* @param file The file to be read.
*
* @return The bytes that comprise the specified file.
*
* @throws IOException If a problem occurs while trying to read the file.
*/
@NotNull()
public static byte[] readFileBytes(@NotNull final File file)
throws IOException
{
final ByteStringBuffer buffer = new ByteStringBuffer((int) file.length());
buffer.readFrom(file);
return buffer.toByteArray();
}
/**
* Reads the contents of the specified file as a string. All line breaks in
* the file will be preserved, with the possible exception of the one on the
* last line.
*
* @param path The path to the file to be read.
* @param includeFinalLineBreak Indicates whether the final line break (if
* there is one) should be preserved.
*
* @return The contents of the specified file as a string.
*
* @throws IOException If a problem occurs while trying to read the file.
*/
@NotNull()
public static String readFileAsString(@NotNull final String path,
final boolean includeFinalLineBreak)
throws IOException
{
return readFileAsString(new File(path), includeFinalLineBreak);
}
/**
* Reads the contents of the specified file as a string. All line breaks in
* the file will be preserved, with the possible exception of the one on the
* last line.
*
* @param file The file to be read.
* @param includeFinalLineBreak Indicates whether the final line break (if
* there is one) should be preserved.
*
* @return The contents of the specified file as a string.
*
* @throws IOException If a problem occurs while trying to read the file.
*/
@NotNull()
public static String readFileAsString(@NotNull final File file,
final boolean includeFinalLineBreak)
throws IOException
{
final ByteStringBuffer buffer = new ByteStringBuffer((int) file.length());
buffer.readFrom(file);
if (! includeFinalLineBreak)
{
if (buffer.endsWith(EOL_BYTES_CR_LF))
{
buffer.setLength(buffer.length() - EOL_BYTES_CR_LF.length);
}
else if (buffer.endsWith(EOL_BYTES_LF))
{
buffer.setLength(buffer.length() - EOL_BYTES_LF.length);
}
}
return buffer.toString();
}
/**
* Reads the lines that comprise the specified file.
*
* @param path The path to the file to be read.
*
* @return The lines that comprise the specified file.
*
* @throws IOException If a problem occurs while trying to read the file.
*/
@NotNull()
public static List readFileLines(@NotNull final String path)
throws IOException
{
return readFileLines(new File(path));
}
/**
* Reads the lines that comprise the specified file.
*
* @param file The file to be read.
*
* @return The lines that comprise the specified file.
*
* @throws IOException If a problem occurs while trying to read the file.
*/
@NotNull()
public static List readFileLines(@NotNull final File file)
throws IOException
{
try (FileReader fileReader = new FileReader(file);
BufferedReader bufferedReader = new BufferedReader(fileReader))
{
final List lines = new ArrayList<>();
while (true)
{
final String line = bufferedReader.readLine();
if (line == null)
{
return Collections.unmodifiableList(lines);
}
lines.add(line);
}
}
}
/**
* Writes the provided bytes to the specified file. If the file already
* exists, it will be overwritten.
*
* @param path The path to the file to be written.
* @param bytes The bytes to be written to the specified file.
*
* @throws IOException If a problem is encountered while writing the file.
*/
public static void writeFile(@NotNull final String path,
@NotNull final byte[] bytes)
throws IOException
{
writeFile(new File(path), bytes);
}
/**
* Writes the provided bytes to the specified file. If the file already
* exists, it will be overwritten.
*
* @param file The file to be written.
* @param bytes The bytes to be written to the specified file.
*
* @throws IOException If a problem is encountered while writing the file.
*/
public static void writeFile(@NotNull final File file,
@NotNull final byte[] bytes)
throws IOException
{
try (FileOutputStream outputStream = new FileOutputStream(file))
{
outputStream.write(bytes);
}
}
/**
* Writes the provided lines to the specified file, with each followed by an
* appropriate end-of-line marker for the current platform. If the file
* already exists, it will be overwritten.
*
* @param path The path to the file to be written.
* @param lines The lines to be written to the specified file.
*
* @throws IOException If a problem is encountered while writing the file.
*/
public static void writeFile(@NotNull final String path,
@NotNull final CharSequence... lines)
throws IOException
{
writeFile(new File(path), lines);
}
/**
* Writes the provided lines to the specified file, with each followed by an
* appropriate end-of-line marker for the current platform. If the file
* already exists, it will be overwritten.
*
* @param file The file to be written.
* @param lines The lines to be written to the specified file.
*
* @throws IOException If a problem is encountered while writing the file.
*/
public static void writeFile(@NotNull final File file,
@NotNull final CharSequence... lines)
throws IOException
{
writeFile(file, toList(lines));
}
/**
* Writes the provided lines to the specified file, with each followed by an
* appropriate end-of-line marker for the current platform. If the file
* already exists, it will be overwritten.
*
* @param path The path to the file to be written.
* @param lines The lines to be written to the specified file.
*
* @throws IOException If a problem is encountered while writing the file.
*/
public static void writeFile(@NotNull final String path,
@Nullable final List lines)
throws IOException
{
writeFile(new File(path), lines);
}
/**
* Writes the provided lines to the specified file, with each followed by an
* appropriate end-of-line marker for the current platform. If the file
* already exists, it will be overwritten.
*
* @param file The file to be written.
* @param lines The lines to be written to the specified file.
*
* @throws IOException If a problem is encountered while writing the file.
*/
public static void writeFile(@NotNull final File file,
@Nullable final List lines)
throws IOException
{
try (PrintWriter writer = new PrintWriter(file))
{
if (lines != null)
{
for (final CharSequence line : lines)
{
writer.println(line);
}
}
}
}
/**
* Retrieves a byte array with the specified number of randomly selected
* bytes.
*
* @param numBytes The number of bytes of random data to retrieve. It must
* be greater than or equal to zero.
* @param secure Indicates whether to use a cryptographically secure
* random number generator.
*
* @return A byte array with the specified number of randomly selected
* bytes.
*/
@NotNull()
public static byte[] randomBytes(final int numBytes,
final boolean secure)
{
final byte[] byteArray = new byte[numBytes];
getThreadLocalRandom(secure).nextBytes(byteArray);
return byteArray;
}
/**
* Retrieves a randomly selected integer between the given upper and lower
* bounds.
*
* @param lowerBound The lowest value that may be selected at random. It
* must be less than or equal to the upper bound.
* @param upperBound The highest value that may be selected at random. It
* must be greater than or equal to the lower bound.
* @param secure Indicates whether to use a cryptographically secure
* random number generator.
*
* @return A randomly selected integer between the given upper and lower
* bounds.
*/
public static int randomInt(final int lowerBound, final int upperBound,
final boolean secure)
{
// Compute the span of values. We need to use a long for this, because it's
// possible that this could cause an integer overflow.
final long span = 1L + upperBound - lowerBound;
// Select a random long value between zero and that span.
final long randomLong = getThreadLocalRandom(secure).nextLong();
final long positiveLong = randomLong & 0x7F_FF_FF_FF_FF_FF_FF_FFL;
final long valueWithinSpan = positiveLong % span;
return (int) (lowerBound + valueWithinSpan);
}
/**
* Retrieves a string containing the specified number of randomly selected
* ASCII letters. It will contain only lowercase letters.
*
* @param length The number of letters to include in the string. It must be
* greater than or equal to zero.
* @param secure Indicates whether to use a cryptographically secure random
* number generator.
*
* @return The randomly generated alphabetic string.
*/
@NotNull()
public static String randomAlphabeticString(final int length,
final boolean secure)
{
return randomString(length, LOWERCASE_LETTERS, secure);
}
/**
* Retrieves a string containing the specified number of randomly selected
* ASCII numeric digits.
*
* @param length The number of digits to include in the string. It must be
* greater than or equal to zero.
* @param secure Indicates whether to use a cryptographically secure random
* number generator.
*
* @return The randomly generated numeric string.
*/
@NotNull()
public static String randomNumericString(final int length,
final boolean secure)
{
return randomString(length, NUMERIC_DIGITS, secure);
}
/**
* Retrieves a string containing the specified number of randomly selected
* ASCII alphanumeric characters. It may contain a mix of lowercase letters,
* uppercase letters, and numeric digits.
*
* @param length The number of characters to include in the string. It must
* be greater than or equal to zero.
* @param secure Indicates whether to use a cryptographically secure random
* number generator.
*
* @return The randomly generated alphanumeric string.
*/
@NotNull()
public static String randomAlphanumericString(final int length,
final boolean secure)
{
return randomString(length, ALPHANUMERIC_CHARACTERS, secure);
}
/**
* Retrieves a string containing the specified number of randomly selected
* characters from the given set.
*
* @param length The number of characters to include in the string.
* It must be greater than or equal to zero.
* @param allowedChars The set of characters that are allowed to be included
* in the string. It must not be {@code null} or
* empty.
* @param secure Indicates whether to use a cryptographically secure
* random number generator.
*
* @return The randomly generated string.
*/
@NotNull()
public static String randomString(final int length,
@NotNull final char[] allowedChars,
final boolean secure)
{
final StringBuilder buffer = new StringBuilder(length);
final Random random = getThreadLocalRandom(secure);
for (int i=0; i < length; i++)
{
buffer.append(allowedChars[random.nextInt(allowedChars.length)]);
}
return buffer.toString();
}
/**
* Retrieves a thread-local random number generator.
*
* @param secure Indicates whether to retrieve a cryptographically secure
* random number generator.
*
* @return The thread-local random number generator.
*/
@NotNull()
private static Random getThreadLocalRandom(final boolean secure)
{
if (secure)
{
return ThreadLocalSecureRandom.get();
}
else
{
return ThreadLocalRandom.get();
}
}
}