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 cast to not-null
049     * @return the object, or throws an exception if it is null
050     * @throws ValidationException if the object is null
051     * @deprecated prefer to use {@link #expectNotNull(Object, String, Object...)} instead; will be removed in jsoup 1.24.1
052     */
053    @Deprecated
054    public static Object ensureNotNull(@Nullable Object obj) {
055        if (obj == null)
056            throw new ValidationException("Object must not be null");
057        else return obj;
058    }
059
060    /**
061     Verifies the input object is not null, and returns that object. Effectively this casts a nullable object to a non-
062     null object. (Works around lack of Objects.requestNonNull in Android version.)
063     * @param obj nullable object to cast to not-null
064     * @param msg the String format message to include in the validation exception when thrown
065     * @param args the arguments to the msg
066     * @return the object, or throws an exception if it is null
067     * @throws ValidationException if the object is null
068     * @deprecated prefer to use {@link #expectNotNull(Object, String, Object...)} instead; will be removed in jsoup 1.24.1
069     */
070    @Deprecated
071    public static Object ensureNotNull(@Nullable Object obj, String msg, Object... args) {
072        if (obj == null)
073            throw new ValidationException(String.format(msg, args));
074        else return obj;
075    }
076
077    /**
078     Verifies the input object is not null, and returns that object, maintaining its type. Effectively this casts a
079     nullable object to a non-null object.
080
081     @param obj nullable object to cast to not-null
082     @return the object, or throws an exception if it is null
083     @throws ValidationException if the object is null
084     */
085    public static <T> T expectNotNull(@Nullable T obj) {
086        if (obj == null)
087            throw new ValidationException("Object must not be null");
088        else return obj;
089    }
090
091    /**
092     Verifies the input object is not null, and returns that object, maintaining its type. Effectively this casts a
093     nullable object to a non-null object.
094
095     @param obj nullable object to cast to not-null
096     @param msg the String format message to include in the validation exception when thrown
097     @param args the arguments to the msg
098     @return the object, or throws an exception if it is null
099     @throws ValidationException if the object is null
100     */
101    public static <T> T expectNotNull(@Nullable T obj, String msg, Object... args) {
102        if (obj == null)
103            throw new ValidationException(String.format(msg, args));
104        else return obj;
105    }
106
107    /**
108     * Validates that the value is true
109     * @param val object to test
110     * @throws ValidationException if the object is not true
111     */
112    public static void isTrue(boolean val) {
113        if (!val)
114            throw new ValidationException("Must be true");
115    }
116
117    /**
118     * Validates that the value is true
119     * @param val object to test
120     * @param msg message to include in the Exception if validation fails
121     * @throws ValidationException if the object is not true
122     */
123    public static void isTrue(boolean val, String msg) {
124        if (!val)
125            throw new ValidationException(msg);
126    }
127
128    /**
129     * Validates that the value is false
130     * @param val object to test
131     * @throws ValidationException if the object is not false
132     */
133    public static void isFalse(boolean val) {
134        if (val)
135            throw new ValidationException("Must be false");
136    }
137
138    /**
139     * Validates that the value is false
140     * @param val object to test
141     * @param msg message to include in the Exception if validation fails
142     * @throws ValidationException if the object is not false
143     */
144    public static void isFalse(boolean val, String msg) {
145        if (val)
146            throw new ValidationException(msg);
147    }
148
149    /**
150     * Validates that the array contains no null elements
151     * @param objects the array to test
152     * @throws ValidationException if the array contains a null element
153     */
154    public static void noNullElements(Object[] objects) {
155        noNullElements(objects, "Array must not contain any null objects");
156    }
157
158    /**
159     * Validates that the array contains no null elements
160     * @param objects the array to test
161     * @param msg message to include in the Exception if validation fails
162     * @throws ValidationException if the array contains a null element
163     */
164    public static void noNullElements(Object[] objects, String msg) {
165        for (Object obj : objects)
166            if (obj == null)
167                throw new ValidationException(msg);
168    }
169
170    /**
171     * Validates that the string is not null and is not empty
172     * @param string the string to test
173     * @throws ValidationException if the string is null or empty
174     */
175    public static void notEmpty(@Nullable String string) {
176        if (string == null || string.length() == 0)
177            throw new ValidationException("String must not be empty");
178    }
179
180    /**
181     Validates that the string parameter is not null and is not empty
182     * @param string the string to test
183     * @param param the name of the parameter, for presentation in the validation exception.
184     * @throws ValidationException if the string is null or empty
185     */
186    public static void notEmptyParam(@Nullable final String string, final String param) {
187        if (string == null || string.length() == 0)
188            throw new ValidationException(String.format("The '%s' parameter must not be empty.", param));
189    }
190
191    /**
192     * Validates that the string is not null and is not empty
193     * @param string the string to test
194     * @param msg message to include in the Exception if validation fails
195     * @throws ValidationException if the string is null or empty
196     */
197    public static void notEmpty(@Nullable String string, String msg) {
198        if (string == null || string.length() == 0)
199            throw new ValidationException(msg);
200    }
201
202    /**
203     * Blow up if we reach an unexpected state.
204     * @param msg message to think about
205     * @throws IllegalStateException if we reach this state
206     */
207    public static void wtf(String msg) {
208        throw new IllegalStateException(msg);
209    }
210
211    /**
212     Cause a failure.
213     @param msg message to output.
214     @throws IllegalStateException if we reach this state
215     */
216    public static void fail(String msg) {
217        throw new ValidationException(msg);
218    }
219
220    /**
221     Cause a failure, but return false so it can be used in an assert statement.
222     @param msg message to output.
223     @return false, always
224     @throws IllegalStateException if we reach this state
225     */
226    static boolean assertFail(String msg) {
227        fail(msg);
228        return false;
229    }
230
231    /**
232     Cause a failure.
233     @param msg message to output.
234     @param args the format arguments to the msg
235     @throws IllegalStateException if we reach this state
236     */
237    public static void fail(String msg, Object... args) {
238        throw new ValidationException(String.format(msg, args));
239    }
240}