001package org.jsoup.helper; 002 003import org.jspecify.annotations.Nullable; 004 005/** 006 * Validators to check that method arguments meet expectations. 007 */ 008public final class Validate { 009 010 private Validate() {} 011 012 /** 013 * Validates that the object is not null 014 * @param obj object to test 015 * @throws ValidationException if the object is null 016 */ 017 public static void notNull(@Nullable Object obj) { 018 if (obj == null) 019 throw new ValidationException("Object must not be null"); 020 } 021 022 /** 023 Validates that the parameter is not null 024 025 * @param obj the parameter to test 026 * @param param the name of the parameter, for presentation in the validation exception. 027 * @throws ValidationException if the object is null 028 */ 029 public static void notNullParam(@Nullable final Object obj, final String param) { 030 if (obj == null) 031 throw new ValidationException(String.format("The parameter '%s' must not be null.", param)); 032 } 033 034 /** 035 * Validates that the object is not null 036 * @param obj object to test 037 * @param msg message to include in the Exception if validation fails 038 * @throws ValidationException if the object is null 039 */ 040 public static void notNull(@Nullable Object obj, String msg) { 041 if (obj == null) 042 throw new ValidationException(msg); 043 } 044 045 /** 046 Verifies the input object is not null, and returns that object. Effectively this casts a nullable object to a non- 047 null object. (Works around lack of Objects.requestNonNull in Android version.) 048 * @param obj nullable object to case to not-null 049 * @return the object, or throws an exception if it is null 050 * @throws ValidationException if the object is null 051 */ 052 public static Object ensureNotNull(@Nullable Object obj) { 053 if (obj == null) 054 throw new ValidationException("Object must not be null"); 055 else return obj; 056 } 057 058 /** 059 Verifies the input object is not null, and returns that object. Effectively this casts a nullable object to a non- 060 null object. (Works around lack of Objects.requestNonNull in Android version.) 061 * @param obj nullable object to case to not-null 062 * @param msg the String format message to include in the validation exception when thrown 063 * @param args the arguments to the msg 064 * @return the object, or throws an exception if it is null 065 * @throws ValidationException if the object is null 066 */ 067 public static Object ensureNotNull(@Nullable Object obj, String msg, Object... args) { 068 if (obj == null) 069 throw new ValidationException(String.format(msg, args)); 070 else return obj; 071 } 072 073 /** 074 * Validates that the value is true 075 * @param val object to test 076 * @throws ValidationException if the object is not true 077 */ 078 public static void isTrue(boolean val) { 079 if (!val) 080 throw new ValidationException("Must be true"); 081 } 082 083 /** 084 * Validates that the value is true 085 * @param val object to test 086 * @param msg message to include in the Exception if validation fails 087 * @throws ValidationException if the object is not true 088 */ 089 public static void isTrue(boolean val, String msg) { 090 if (!val) 091 throw new ValidationException(msg); 092 } 093 094 /** 095 * Validates that the value is false 096 * @param val object to test 097 * @throws ValidationException if the object is not false 098 */ 099 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 203 public static void fail(String msg, Object... args) { 204 throw new ValidationException(String.format(msg, args)); 205 } 206}