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}