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