1 /*
2  * Copyright 2014 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.hardware.camera2.cts.helpers;
18 
19 import java.util.Collection;
20 import java.util.Objects;
21 
22 /**
23  * Helper set of methods to perform precondition checks before starting method execution.
24  *
25  * <p>Typically used to sanity check arguments or the current object state.</p>
26  */
27 public final class Preconditions {
28 
29     /**
30      * Checks that the value has the expected bitwise flags set.
31      *
32      * @param argName Name of the argument
33      * @param arg Argument to check
34      * @param flagsName Name of the bitwise flags
35      * @param flags Bit flags to check.
36      * @return arg
37      *
38      * @throws IllegalArgumentException if the bitwise flags weren't set
39      */
checkBitFlags(String argName, int arg, String flagsName, int flags)40     public static int checkBitFlags(String argName, int arg, String flagsName, int flags) {
41         if ((arg & flags) == 0) {
42             throw new IllegalArgumentException(
43                     String.format("Argument '%s' must have flags '%s' set", argName, flagsName));
44         }
45 
46         return arg;
47     }
48 
49     /**
50      * Checks that the value is {@link Object#equals equal} to the expected value.
51      *
52      * @param argName Name of the argument
53      * @param arg Argument to check
54      * @param expectedName Name of the expected value
55      * @param expectedValue Expected value
56      * @return arg
57      *
58      * @throws IllegalArgumentException if the values were not equal
59      */
checkEquals(String argName, T arg, String expectedName, T expectedValue)60     public static <T> T checkEquals(String argName, T arg,
61             String expectedName, T expectedValue) {
62         if (!Objects.equals(arg, expectedValue)) {
63             throw new IllegalArgumentException(
64                     String.format(
65                             "Argument '%s' must be equal to '%s' (was '%s', but expected '%s')",
66                             argName, expectedName, arg, expectedValue));
67         }
68 
69         return arg;
70     }
71 
72     /**
73      * Checks that the value is not {@code null}.
74      *
75      * <p>
76      * Returns the value directly, so you can use {@code checkNotNull("value", value)} inline.
77      * </p>
78      *
79      * @param argName Name of the argument
80      * @param arg Argument to check
81      * @return arg
82      *
83      * @throws NullPointerException if arg was {@code null}
84      */
checkNotNull(String argName, T arg)85     public static <T> T checkNotNull(String argName, T arg) {
86         if (arg == null) {
87             throw new NullPointerException("Argument '" + argName + "' must not be null");
88         }
89 
90         return arg;
91     }
92 
93     /**
94      * Checks that the value is not {@code null}.
95      *
96      * <p>
97      * Returns the value directly, so you can use {@code checkNotNull("value", value)} inline.
98      * </p>
99      *
100      * @param arg Argument to check
101      * @return arg
102      *
103      * @throws NullPointerException if arg was {@code null}
104      */
checkNotNull(T arg)105     public static <T> T checkNotNull(T arg) {
106         return checkNotNull("", arg);
107     }
108 
109     /**
110      * Checks that the state is currently {@link true}.
111      *
112      * @param message Message to raise an exception with if the state checking fails.
113      * @param state State to check
114      *
115      * @throws IllegalStateException if state was {@code false}
116      *
117      * @return The state value (always {@code true}).
118      */
checkState(String message, boolean state)119     public static boolean checkState(String message, boolean state) {
120         if (!state) {
121             throw new IllegalStateException(message);
122         }
123 
124         return state;
125     }
126 
127         /**
128      * Ensures that the {@link Collection} is not {@code null}, and none of its elements are
129      * {@code null}.
130      *
131      * @param value a {@link Collection} of boxed objects
132      * @param valueName the name of the argument to use if the check fails
133      *
134      * @return the validated {@link Collection}
135      *
136      * @throws NullPointerException if the {@code value} or any of its elements were {@code null}
137      */
checkCollectionElementsNotNull(final Collection<T> value, final String valueName)138     public static <T> Collection<T> checkCollectionElementsNotNull(final Collection<T> value,
139             final String valueName) {
140         if (value == null) {
141             throw new NullPointerException(valueName + " must not be null");
142         }
143 
144         long ctr = 0;
145         for (T elem : value) {
146             if (elem == null) {
147                 throw new NullPointerException(
148                         String.format("%s[%d] must not be null", valueName, ctr));
149             }
150             ++ctr;
151         }
152 
153         return value;
154     }
155 
156     /**
157      * Ensures that the {@link Collection} is not {@code null}, and contains at least one element.
158      *
159      * @param value a {@link Collection} of boxed elements.
160      * @param valueName the name of the argument to use if the check fails.
161 
162      * @return the validated {@link Collection}
163      *
164      * @throws NullPointerException if the {@code value} was {@code null}
165      * @throws IllegalArgumentException if the {@code value} was empty
166      */
checkCollectionNotEmpty(final Collection<T> value, final String valueName)167     public static <T> Collection<T> checkCollectionNotEmpty(final Collection<T> value,
168             final String valueName) {
169         if (value == null) {
170             throw new NullPointerException(valueName + " must not be null");
171         }
172         if (value.isEmpty()) {
173             throw new IllegalArgumentException(valueName + " is empty");
174         }
175         return value;
176     }
177 
178     // Suppress default constructor for noninstantiability
Preconditions()179     private Preconditions() { throw new AssertionError(); }
180 }
181