1 package org.jsoup.helper; 2 3 import org.jspecify.annotations.Nullable; 4 5 /** 6 * Validators to check that method arguments meet expectations. 7 */ 8 public final class Validate { 9 Validate()10 private Validate() {} 11 12 /** 13 * Validates that the object is not null 14 * @param obj object to test 15 * @throws ValidationException if the object is null 16 */ notNull(@ullable Object obj)17 public static void notNull(@Nullable Object obj) { 18 if (obj == null) 19 throw new ValidationException("Object must not be null"); 20 } 21 22 /** 23 Validates that the parameter is not null 24 25 * @param obj the parameter to test 26 * @param param the name of the parameter, for presentation in the validation exception. 27 * @throws ValidationException if the object is null 28 */ notNullParam(@ullable final Object obj, final String param)29 public static void notNullParam(@Nullable final Object obj, final String param) { 30 if (obj == null) 31 throw new ValidationException(String.format("The parameter '%s' must not be null.", param)); 32 } 33 34 /** 35 * Validates that the object is not null 36 * @param obj object to test 37 * @param msg message to include in the Exception if validation fails 38 * @throws ValidationException if the object is null 39 */ notNull(@ullable Object obj, String msg)40 public static void notNull(@Nullable Object obj, String msg) { 41 if (obj == null) 42 throw new ValidationException(msg); 43 } 44 45 /** 46 Verifies the input object is not null, and returns that object. Effectively this casts a nullable object to a non- 47 null object. (Works around lack of Objects.requestNonNull in Android version.) 48 * @param obj nullable object to case to not-null 49 * @return the object, or throws an exception if it is null 50 * @throws ValidationException if the object is null 51 */ ensureNotNull(@ullable Object obj)52 public static Object ensureNotNull(@Nullable Object obj) { 53 if (obj == null) 54 throw new ValidationException("Object must not be null"); 55 else return obj; 56 } 57 58 /** 59 Verifies the input object is not null, and returns that object. Effectively this casts a nullable object to a non- 60 null object. (Works around lack of Objects.requestNonNull in Android version.) 61 * @param obj nullable object to case to not-null 62 * @param msg the String format message to include in the validation exception when thrown 63 * @param args the arguments to the msg 64 * @return the object, or throws an exception if it is null 65 * @throws ValidationException if the object is null 66 */ ensureNotNull(@ullable Object obj, String msg, Object... args)67 public static Object ensureNotNull(@Nullable Object obj, String msg, Object... args) { 68 if (obj == null) 69 throw new ValidationException(String.format(msg, args)); 70 else return obj; 71 } 72 73 /** 74 * Validates that the value is true 75 * @param val object to test 76 * @throws ValidationException if the object is not true 77 */ isTrue(boolean val)78 public static void isTrue(boolean val) { 79 if (!val) 80 throw new ValidationException("Must be true"); 81 } 82 83 /** 84 * Validates that the value is true 85 * @param val object to test 86 * @param msg message to include in the Exception if validation fails 87 * @throws ValidationException if the object is not true 88 */ isTrue(boolean val, String msg)89 public static void isTrue(boolean val, String msg) { 90 if (!val) 91 throw new ValidationException(msg); 92 } 93 94 /** 95 * Validates that the value is false 96 * @param val object to test 97 * @throws ValidationException if the object is not false 98 */ isFalse(boolean val)99 public static void isFalse(boolean val) { 100 if (val) 101 throw new ValidationException("Must be false"); 102 } 103 104 /** 105 * Validates that the value is false 106 * @param val object to test 107 * @param msg message to include in the Exception if validation fails 108 * @throws ValidationException if the object is not false 109 */ isFalse(boolean val, String msg)110 public static void isFalse(boolean val, String msg) { 111 if (val) 112 throw new ValidationException(msg); 113 } 114 115 /** 116 * Validates that the array contains no null elements 117 * @param objects the array to test 118 * @throws ValidationException if the array contains a null element 119 */ noNullElements(Object[] objects)120 public static void noNullElements(Object[] objects) { 121 noNullElements(objects, "Array must not contain any null objects"); 122 } 123 124 /** 125 * Validates that the array contains no null elements 126 * @param objects the array to test 127 * @param msg message to include in the Exception if validation fails 128 * @throws ValidationException if the array contains a null element 129 */ noNullElements(Object[] objects, String msg)130 public static void noNullElements(Object[] objects, String msg) { 131 for (Object obj : objects) 132 if (obj == null) 133 throw new ValidationException(msg); 134 } 135 136 /** 137 * Validates that the string is not null and is not empty 138 * @param string the string to test 139 * @throws ValidationException if the string is null or empty 140 */ notEmpty(@ullable String string)141 public static void notEmpty(@Nullable String string) { 142 if (string == null || string.length() == 0) 143 throw new ValidationException("String must not be empty"); 144 } 145 146 /** 147 Validates that the string parameter is not null and is not empty 148 * @param string the string to test 149 * @param param the name of the parameter, for presentation in the validation exception. 150 * @throws ValidationException if the string is null or empty 151 */ notEmptyParam(@ullable final String string, final String param)152 public static void notEmptyParam(@Nullable final String string, final String param) { 153 if (string == null || string.length() == 0) 154 throw new ValidationException(String.format("The '%s' parameter must not be empty.", param)); 155 } 156 157 /** 158 * Validates that the string is not null and is not empty 159 * @param string the string to test 160 * @param msg message to include in the Exception if validation fails 161 * @throws ValidationException if the string is null or empty 162 */ notEmpty(@ullable String string, String msg)163 public static void notEmpty(@Nullable String string, String msg) { 164 if (string == null || string.length() == 0) 165 throw new ValidationException(msg); 166 } 167 168 /** 169 * Blow up if we reach an unexpected state. 170 * @param msg message to think about 171 * @throws IllegalStateException if we reach this state 172 */ wtf(String msg)173 public static void wtf(String msg) { 174 throw new IllegalStateException(msg); 175 } 176 177 /** 178 Cause a failure. 179 @param msg message to output. 180 @throws IllegalStateException if we reach this state 181 */ fail(String msg)182 public static void fail(String msg) { 183 throw new ValidationException(msg); 184 } 185 186 /** 187 Cause a failure, but return false so it can be used in an assert statement. 188 @param msg message to output. 189 @return false, always 190 @throws IllegalStateException if we reach this state 191 */ assertFail(String msg)192 static boolean assertFail(String msg) { 193 fail(msg); 194 return false; 195 } 196 197 /** 198 Cause a failure. 199 @param msg message to output. 200 @param args the format arguments to the msg 201 @throws IllegalStateException if we reach this state 202 */ fail(String msg, Object... args)203 public static void fail(String msg, Object... args) { 204 throw new ValidationException(String.format(msg, args)); 205 } 206 } 207