StringUtils.java

  1. /**
  2.  *
  3.  * Copyright 2003-2007 Jive Software, 2016-2024 Florian Schmaus.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  18. package org.jivesoftware.smack.util;

  20. import java.io.IOException;
  21. import java.nio.CharBuffer;
  22. import java.nio.charset.StandardCharsets;
  23. import java.util.ArrayList;
  24. import java.util.Arrays;
  25. import java.util.Collection;
  26. import java.util.Iterator;
  27. import java.util.List;
  28. import java.util.Random;
  29. import java.util.regex.Pattern;

  31. /**
  32.  * A collection of utility methods for String objects.
  33.  */
  34. public class StringUtils {

  36.     public static final String MD5 = "MD5";
  37.     public static final String SHA1 = "SHA-1";

  39.     public static final String QUOTE_ENCODE = """;
  40.     public static final String APOS_ENCODE = "'";
  41.     public static final String AMP_ENCODE = "&";
  42.     public static final String LT_ENCODE = "<";
  43.     public static final String GT_ENCODE = ">";

  45.     public static final char[] HEX_CHARS = "0123456789abcdef".toCharArray();

  47.     /**
  48.      * Escape <code>input</code> for XML.
  49.      *
  50.      * @param input the input to escape.
  51.      * @return the XML escaped variant of <code>input</code>.
  52.      */
  53.     public static CharSequence escapeForXml(CharSequence input) {
  54.         return escapeForXml(input, XmlEscapeMode.safe);
  55.     }

  57.     /**
  58.      * Escape <code>input</code> for XML.
  59.      *
  60.      * @param input the input to escape.
  61.      * @return the XML escaped variant of <code>input</code>.
  62.      * @since 4.2
  63.      */
  64.     public static CharSequence escapeForXmlAttribute(CharSequence input) {
  65.         return escapeForXml(input, XmlEscapeMode.forAttribute);
  66.     }

  68.     /**
  69.      * Escape <code>input</code> for XML.
  70.      * <p>
  71.      * This is an optimized variant of {@link #escapeForXmlAttribute(CharSequence)} for XML where the
  72.      * XML attribute is quoted using ''' (Apos).
  73.      * </p>
  74.      *
  75.      * @param input the input to escape.
  76.      * @return the XML escaped variant of <code>input</code>.
  77.      * @since 4.2
  78.      */
  79.     public static CharSequence escapeForXmlAttributeApos(CharSequence input) {
  80.         return escapeForXml(input, XmlEscapeMode.forAttributeApos);
  81.     }

  83.     /**
  84.      * Escape <code>input</code> for XML.
  85.      *
  86.      * @param input the input to escape.
  87.      * @return the XML escaped variant of <code>input</code>.
  88.      * @since 4.2
  89.      */
  90.     public static CharSequence escapeForXmlText(CharSequence input) {
  91.         return escapeForXml(input, XmlEscapeMode.forText);
  92.     }

  94.     private enum XmlEscapeMode {
  95.         safe,
  96.         forAttribute,
  97.         forAttributeApos,
  98.         forText,
  99.     }

  101.     /**
  102.      * Escapes all necessary characters in the CharSequence so that it can be used
  103.      * in an XML doc.
  104.      *
  105.      * @param input the CharSequence to escape.
  106.      * @return the string with appropriate characters escaped.
  107.      */
  108.     private static CharSequence escapeForXml(final CharSequence input, final XmlEscapeMode xmlEscapeMode) {
  109.         if (input == null) {
  110.             return null;
  111.         }
  112.         final int len = input.length();
  113.         final StringBuilder out = new StringBuilder((int) (len * 1.3));
  114.         CharSequence toAppend;
  115.         char ch;
  116.         int last = 0;
  117.         int i = 0;
  118.         while (i < len) {
  119.             toAppend = null;
  120.             ch = input.charAt(i);
  121.             switch (xmlEscapeMode) {
  122.             case safe:
  123.                 switch (ch) {
  124.                 case '<':
  125.                     toAppend = LT_ENCODE;
  126.                     break;
  127.                 case '>':
  128.                     toAppend = GT_ENCODE;
  129.                     break;
  130.                 case '&':
  131.                     toAppend = AMP_ENCODE;
  132.                     break;
  133.                 case '"':
  134.                     toAppend = QUOTE_ENCODE;
  135.                     break;
  136.                 case '\'':
  137.                     toAppend = APOS_ENCODE;
  138.                     break;
  139.                 default:
  140.                     break;
  141.                 }
  142.                 break;
  143.             case forAttribute:
  144.                 // No need to escape '>' for attributes.
  145.                 switch (ch) {
  146.                 case '<':
  147.                     toAppend = LT_ENCODE;
  148.                     break;
  149.                 case '&':
  150.                     toAppend = AMP_ENCODE;
  151.                     break;
  152.                 case '"':
  153.                     toAppend = QUOTE_ENCODE;
  154.                     break;
  155.                 case '\'':
  156.                     toAppend = APOS_ENCODE;
  157.                     break;
  158.                 default:
  159.                     break;
  160.                 }
  161.                 break;
  162.             case forAttributeApos:
  163.                 // No need to escape '>' and '"' for attributes using '\'' as quote.
  164.                 switch (ch) {
  165.                 case '<':
  166.                     toAppend = LT_ENCODE;
  167.                     break;
  168.                 case '&':
  169.                     toAppend = AMP_ENCODE;
  170.                     break;
  171.                 case '\'':
  172.                     toAppend = APOS_ENCODE;
  173.                     break;
  174.                 default:
  175.                     break;
  176.                 }
  177.                 break;
  178.             case forText:
  179.                 // No need to escape '"', '\'', and '>' for text.
  180.                 switch (ch) {
  181.                 case '<':
  182.                     toAppend = LT_ENCODE;
  183.                     break;
  184.                 case '&':
  185.                     toAppend = AMP_ENCODE;
  186.                     break;
  187.                 default:
  188.                     break;
  189.                 }
  190.                 break;
  191.             }
  192.             if (toAppend != null) {
  193.                 if (i > last) {
  194.                     out.append(input, last, i);
  195.                 }
  196.                 out.append(toAppend);
  197.                 last = ++i;
  198.             } else {
  199.                 i++;
  200.             }
  201.         }
  202.         if (last == 0) {
  203.             return input;
  204.         }
  205.         if (i > last) {
  206.             out.append(input, last, i);
  207.         }
  208.         return out;
  209.     }

  211.     /**
  212.      * Hashes a String using the SHA-1 algorithm and returns the result as a
  213.      * String of hexadecimal numbers. This method is synchronized to avoid
  214.      * excessive MessageDigest object creation. If calling this method becomes
  215.      * a bottleneck in your code, you may wish to maintain a pool of
  216.      * MessageDigest objects instead of using this method.
  217.      * <p>
  218.      * A hash is a one-way function -- that is, given an
  219.      * input, an output is easily computed. However, given the output, the
  220.      * input is almost impossible to compute. This is useful for passwords
  221.      * since we can store the hash and a hacker will then have a very hard time
  222.      * determining the original password.
  223.      *
  224.      * @param data the String to compute the hash of.
  225.      * @return a hashed version of the passed-in String
  226.      * @deprecated use {@link org.jivesoftware.smack.util.SHA1#hex(String)} instead.
  227.      */
  228.     @Deprecated
  229.     public static synchronized String hash(String data) {
  230.         return org.jivesoftware.smack.util.SHA1.hex(data);
  231.     }

  233.     /**
  234.      * Encodes an array of bytes as String representation of hexadecimal.
  235.      *
  236.      * @param bytes an array of bytes to convert to a hex string.
  237.      * @return generated hex string.
  238.      */
  239.     public static String encodeHex(byte[] bytes) {
  240.         char[] hexChars = new char[bytes.length * 2];
  241.         for (int j = 0; j < bytes.length; j++) {
  242.             int v = bytes[j] & 0xFF;
  243.             hexChars[j * 2] = HEX_CHARS[v >>> 4];
  244.             hexChars[j * 2 + 1] = HEX_CHARS[v & 0x0F];
  245.         }
  246.         return new String(hexChars);
  247.     }

  249.     public static byte[] toUtf8Bytes(String string) {
  250.         return string.getBytes(StandardCharsets.UTF_8);
  251.     }

  253.     /**
  254.      * 24 upper case characters from the latin alphabet and numbers without '0' and 'O'.
  255.      */
  256.     public static final String UNAMBIGUOUS_NUMBERS_AND_LETTERS_STRING = "123456789ABCDEFGHIJKLMNPQRSTUVWXYZ";

  258.     /**
  259.      * 24 upper case characters from the latin alphabet and numbers without '0' and 'O'.
  260.      */
  261.     private static final char[] UNAMBIGUOUS_NUMBERS_AND_LETTERS = UNAMBIGUOUS_NUMBERS_AND_LETTERS_STRING.toCharArray();

  263.     /**
  264.      * Returns a random String of numbers and letters (lower and upper case)
  265.      * of the specified length. The method uses the Random class that is
  266.      * built-in to Java which is suitable for low to medium grade security uses.
  267.      * This means that the output is only pseudo random, i.e., each number is
  268.      * mathematically generated so is not truly random.<p>
  269.      *
  270.      * The specified length must be at least one. If not, the method will return
  271.      * null.
  272.      *
  273.      * @param length the desired length of the random String to return.
  274.      * @return a random String of numbers and letters of the specified length.
  275.      */
  276.     public static String insecureRandomString(int length) {
  277.         return randomString(length, RandomUtil.RANDOM.get());
  278.     }

  280.     public static String secureOnlineAttackSafeRandomString() {
  281.         // 34^10 = 2.06e15 possible combinations. Which is enough to protect against online brute force attacks.
  282.         // See also https://www.grc.com/haystack.htm
  283.         final int REQUIRED_LENGTH = 10;

  285.         return randomString(RandomUtil.SECURE_RANDOM.get(), UNAMBIGUOUS_NUMBERS_AND_LETTERS, REQUIRED_LENGTH);
  286.     }

  288.     public static String secureUniqueRandomString() {
  289.         // 34^13 = 8.11e19 possible combinations, which is > 2^64.
  290.         final int REQUIRED_LENGTH = 13;

  292.         return randomString(RandomUtil.SECURE_RANDOM.get(), UNAMBIGUOUS_NUMBERS_AND_LETTERS, REQUIRED_LENGTH);
  293.     }

  295.     /**
  296.      * Generate a secure random string with is human readable. The resulting string consists of 24 upper case characters
  297.      * from the Latin alphabet and numbers without '0' and 'O', grouped into 4-characters chunks, e.g.
  298.      * "TWNK-KD5Y-MT3T-E1GS-DRDB-KVTW". The characters are randomly selected by a cryptographically secure pseudorandom
  299.      * number generator (CSPRNG).
  300.      * <p>
  301.      * The string can be used a backup "code" for secrets, and is in fact the same as the one backup code specified in
  302.      * XEP-0373 and the one used by the <a href="https://github.com/open-keychain/open-keychain/wiki/Backups">Backup
  303.      * Format v2 of OpenKeychain</a>.
  304.      * </p>
  305.      *
  306.      * @see <a href="https://xmpp.org/extensions/xep-0373.html#backup-encryption"> XEP-0373 §5.4 Encrypting the Secret
  307.      *      Key Backup</a>
  308.      * @return a human readable secure random string.
  309.      */
  310.     public static String secureOfflineAttackSafeRandomString() {
  311.         // 34^24 = 2^122.10 possible combinations. Which is enough to protect against offline brute force attacks.
  312.         // See also https://www.grc.com/haystack.htm
  313.         final int REQUIRED_LENGTH = 24;

  315.         return randomString(RandomUtil.SECURE_RANDOM.get(), UNAMBIGUOUS_NUMBERS_AND_LETTERS, REQUIRED_LENGTH);
  316.     }

  318.     private static final int RANDOM_STRING_CHUNK_SIZE = 4;

  320.     private static String randomString(Random random, char[] alphabet, int numRandomChars) {
  321.         // The buffer most hold the size of the requested number of random chars and the chunk separators ('-').
  322.         int bufferSize = numRandomChars + ((numRandomChars - 1) / RANDOM_STRING_CHUNK_SIZE);
  323.         CharBuffer charBuffer = CharBuffer.allocate(bufferSize);

  325.         try {
  326.             randomString(charBuffer, random, alphabet, numRandomChars);
  327.         } catch (IOException e) {
  328.             // This should never happen if we calculate the buffer size correctly.
  329.             throw new AssertionError(e);
  330.         }

  332.         return charBuffer.flip().toString();
  333.     }

  335.     private static void randomString(Appendable appendable, Random random, char[] alphabet, int numRandomChars)
  336.                     throws IOException {
  337.         for (int randomCharNum = 1; randomCharNum <= numRandomChars; randomCharNum++) {
  338.             int randomIndex = random.nextInt(alphabet.length);
  339.             char randomChar = alphabet[randomIndex];
  340.             appendable.append(randomChar);

  342.             if (randomCharNum % RANDOM_STRING_CHUNK_SIZE == 0 && randomCharNum < numRandomChars) {
  343.                 appendable.append('-');
  344.             }
  345.         }
  346.     }

  348.     public static String randomString(final int length) {
  349.         return randomString(length, RandomUtil.SECURE_RANDOM.get());
  350.     }

  352.     public static String randomString(final int length, Random random) {
  353.         if (length == 0) {
  354.             return "";
  355.         }

  357.         char[] randomChars = new char[length];
  358.         for (int i = 0; i < length; i++) {
  359.             int index = random.nextInt(UNAMBIGUOUS_NUMBERS_AND_LETTERS.length);
  360.             randomChars[i] = UNAMBIGUOUS_NUMBERS_AND_LETTERS[index];
  361.         }
  362.         return new String(randomChars);
  363.     }

  365.     /**
  366.      * Returns true if CharSequence is not null and is not empty, false otherwise.
  367.      * Examples:
  368.      *    isNotEmpty(null) - false
  369.      *    isNotEmpty("") - false
  370.      *    isNotEmpty(" ") - true
  371.      *    isNotEmpty("empty") - true
  372.      *
  373.      * @param cs checked CharSequence
  374.      * @return true if string is not null and is not empty, false otherwise
  375.      */
  376.     public static boolean isNotEmpty(CharSequence cs) {
  377.         return !isNullOrEmpty(cs);
  378.     }

  380.     /**
  381.      * Returns true if the given CharSequence is null or empty.
  382.      *
  383.      * @param cs TODO javadoc me please
  384.      * @return true if the given CharSequence is null or empty
  385.      */
  386.     public static boolean isNullOrEmpty(CharSequence cs) {
  387.         return cs == null || isEmpty(cs);
  388.     }

  390.     /**
  391.      * Returns true if all given CharSequences are not empty.
  392.      *
  393.      * @param css the CharSequences to test.
  394.      * @return true if all given CharSequences are not empty.
  395.      */
  396.     public static boolean isNotEmpty(CharSequence... css) {
  397.         for (CharSequence cs : css) {
  398.             if (StringUtils.isNullOrEmpty(cs)) {
  399.                 return false;
  400.             }
  401.         }
  402.         return true;
  403.     }

  405.     /**
  406.      * Returns true if all given CharSequences are either null or empty.
  407.      *
  408.      * @param css the CharSequences to test.
  409.      * @return true if all given CharSequences are null or empty.
  410.      */
  411.     public static boolean isNullOrEmpty(CharSequence... css) {
  412.         for (CharSequence cs : css) {
  413.             if (StringUtils.isNotEmpty(cs)) {
  414.                 return false;
  415.             }
  416.         }
  417.         return true;
  418.     }

  420.     public static boolean isNullOrNotEmpty(CharSequence cs) {
  421.         if (cs == null) {
  422.             return true;
  423.         }
  424.         return !cs.toString().isEmpty();
  425.     }

  427.     /**
  428.      * Returns true if the given CharSequence is empty.
  429.      *
  430.      * @param cs TODO javadoc me please
  431.      * @return true if the given CharSequence is empty
  432.      */
  433.     public static boolean isEmpty(CharSequence cs) {
  434.         return cs.length() == 0;
  435.     }

  437.     /**
  438.      * Transform a collection of objects to a whitespace delimited String.
  439.      *
  440.      * @param collection the collection to transform.
  441.      * @return a String with all the elements of the collection.
  442.      */
  443.     public static String collectionToString(Collection<? extends Object> collection) {
  444.         return toStringBuilder(collection, " ").toString();
  445.     }

  447.     /**
  448.      * Transform a collection of objects to a delimited String.
  449.      *
  450.      * @param collection the collection to transform.
  451.      * @param delimiter the delimiter used to delimit the Strings.
  452.      * @return a StringBuilder with all the elements of the collection.
  453.      */
  454.     public static StringBuilder toStringBuilder(Collection<? extends Object> collection, String delimiter) {
  455.         StringBuilder sb = new StringBuilder(collection.size() * 20);
  456.         appendTo(collection, delimiter, sb);
  457.         return sb;
  458.     }

  460.     public static void appendTo(Collection<? extends Object> collection, StringBuilder sb) {
  461.         appendTo(collection, ", ", sb);
  462.     }

  464.     public static <O extends Object> void appendTo(Collection<O> collection, StringBuilder sb,
  465.                     Consumer<O> appendFunction) {
  466.         appendTo(collection, ", ", sb, appendFunction);
  467.     }

  469.     public static void appendTo(Collection<? extends Object> collection, String delimiter, StringBuilder sb) {
  470.         appendTo(collection, delimiter, sb, o -> sb.append(o));
  471.     }

  473.     public static <O extends Object> void appendTo(Collection<O> collection, String delimiter, StringBuilder sb,
  474.                     Consumer<O> appendFunction) {
  475.         for (Iterator<O> it = collection.iterator(); it.hasNext();) {
  476.             O cs = it.next();
  477.             appendFunction.accept(cs);
  478.             if (it.hasNext()) {
  479.                 sb.append(delimiter);
  480.             }
  481.         }
  482.     }

  484.     public static String returnIfNotEmptyTrimmed(String string) {
  485.         if (string == null)
  486.             return null;
  487.         String trimmedString = string.trim();
  488.         if (trimmedString.length() > 0) {
  489.             return trimmedString;
  490.         } else {
  491.             return null;
  492.         }
  493.     }

  495.     public static boolean nullSafeCharSequenceEquals(CharSequence csOne, CharSequence csTwo) {
  496.         return nullSafeCharSequenceComparator(csOne, csTwo) == 0;
  497.     }

  499.     public static int nullSafeCharSequenceComparator(CharSequence csOne, CharSequence csTwo) {
  500.         if (csOne == null ^ csTwo == null) {
  501.             return (csOne == null) ? -1 : 1;
  502.         }
  503.         if (csOne == null && csTwo == null) {
  504.             return 0;
  505.         }
  506.         return csOne.toString().compareTo(csTwo.toString());
  507.     }

  509.     /**
  510.      * Require a {@link CharSequence} to be neither null, nor empty.
  511.      *
  512.      * @deprecated use {@link #requireNotNullNorEmpty(CharSequence, String)} instead.
  513.      * @param cs CharSequence
  514.      * @param message error message
  515.      * @param <CS> CharSequence type
  516.      * @return cs TODO javadoc me please
  517.      */
  518.     @Deprecated
  519.     public static <CS extends CharSequence> CS requireNotNullOrEmpty(CS cs, String message) {
  520.         return requireNotNullNorEmpty(cs, message);
  521.     }

  523.     /**
  524.      * Require a {@link CharSequence} to be neither null, nor empty.
  525.      *
  526.      * @param cs CharSequence
  527.      * @param message error message
  528.      * @param <CS> CharSequence type
  529.      * @return cs TODO javadoc me please
  530.      */
  531.     public static <CS extends CharSequence> CS requireNotNullNorEmpty(CS cs, String message) {
  532.         if (isNullOrEmpty(cs)) {
  533.             throw new IllegalArgumentException(message);
  534.         }
  535.         return cs;
  536.     }

  538.     public static <CS extends CharSequence> CS requireNullOrNotEmpty(CS cs, String message) {
  539.         if (cs == null) {
  540.             return null;
  541.         }
  542.         if (isEmpty(cs)) {
  543.             throw new IllegalArgumentException(message);
  544.         }
  545.         return cs;
  546.     }

  548.     /**
  549.      * Return the String representation of the given char sequence if it is not null.
  550.      *
  551.      * @param cs the char sequence or null.
  552.      * @return the String representation of <code>cs</code> or null.
  553.      */
  554.     public static String maybeToString(CharSequence cs) {
  555.         if (cs == null) {
  556.             return null;
  557.         }
  558.         return cs.toString();
  559.     }

  561.     /**
  562.      * Defined by XML 1.0 § 2.3 as:
  563.      *  S      ::=      (#x20 | #x9 | #xD | #xA)+
  564.      *
  565.      * @see <a href="https://www.w3.org/TR/xml/#sec-white-space">XML 1.0 § 2.3</a>
  566.      */
  567.     private static final Pattern XML_WHITESPACE = Pattern.compile("[\t\n\r ]");

  569.     public static String deleteXmlWhitespace(String string) {
  570.         return XML_WHITESPACE.matcher(string).replaceAll("");
  571.     }

  573.     public static Appendable appendHeading(Appendable appendable, String heading) throws IOException {
  574.         return appendHeading(appendable, heading, '-');
  575.     }

  577.     public static Appendable appendHeading(Appendable appendable, String heading, char underlineChar) throws IOException {
  578.         appendable.append(heading).append('\n');
  579.         for (int i = 0; i < heading.length(); i++) {
  580.             appendable.append(underlineChar);
  581.         }
  582.         return appendable.append('\n');
  583.     }

  585.     public static final String PORTABLE_NEWLINE_REGEX = "\\r?\\n";

  587.     public static List<String> splitLinesPortable(String input) {
  588.         String[] lines = input.split(PORTABLE_NEWLINE_REGEX);
  589.         return Arrays.asList(lines);
  590.     }

  592.     public static List<String> toStrings(Collection<? extends CharSequence> charSequences) {
  593.         List<String> res = new ArrayList<>(charSequences.size());
  594.         for (CharSequence cs : charSequences) {
  595.             String string = cs.toString();
  596.             res.add(string);
  597.         }
  598.         return res;
  599.     }
  600. }
Created with JaCoCo 0.8.6.202009150832