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 validity 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