001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing, software
013     * distributed under the License is distributed on an "AS IS" BASIS,
014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    
019    package org.apache.hadoop.lib.util;
020    
021    import java.text.MessageFormat;
022    import java.util.List;
023    import java.util.regex.Pattern;
024    
025    /**
026     * Utility methods to check preconditions.
027     * <p/>
028     * Commonly used for method arguments preconditions.
029     */
030    public class Check {
031    
032      /**
033       * Verifies a variable is not NULL.
034       *
035       * @param obj the variable to check.
036       * @param name the name to use in the exception message.
037       *
038       * @return the variable.
039       *
040       * @throws IllegalArgumentException if the variable is NULL.
041       */
042      public static <T> T notNull(T obj, String name) {
043        if (obj == null) {
044          throw new IllegalArgumentException(name + " cannot be null");
045        }
046        return obj;
047      }
048    
049      /**
050       * Verifies a list does not have any NULL elements.
051       *
052       * @param list the list to check.
053       * @param name the name to use in the exception message.
054       *
055       * @return the list.
056       *
057       * @throws IllegalArgumentException if the list has NULL elements.
058       */
059      public static <T> List<T> notNullElements(List<T> list, String name) {
060        notNull(list, name);
061        for (int i = 0; i < list.size(); i++) {
062          notNull(list.get(i), MessageFormat.format("list [{0}] element [{1}]", name, i));
063        }
064        return list;
065      }
066    
067      /**
068       * Verifies a string is not NULL and not emtpy
069       *
070       * @param str the variable to check.
071       * @param name the name to use in the exception message.
072       *
073       * @return the variable.
074       *
075       * @throws IllegalArgumentException if the variable is NULL or empty.
076       */
077      public static String notEmpty(String str, String name) {
078        if (str == null) {
079          throw new IllegalArgumentException(name + " cannot be null");
080        }
081        if (str.length() == 0) {
082          throw new IllegalArgumentException(name + " cannot be empty");
083        }
084        return str;
085      }
086    
087      /**
088       * Verifies a string list is not NULL and not emtpy
089       *
090       * @param list the list to check.
091       * @param name the name to use in the exception message.
092       *
093       * @return the variable.
094       *
095       * @throws IllegalArgumentException if the string list has NULL or empty
096       * elements.
097       */
098      public static List<String> notEmptyElements(List<String> list, String name) {
099        notNull(list, name);
100        for (int i = 0; i < list.size(); i++) {
101          notEmpty(list.get(i), MessageFormat.format("list [{0}] element [{1}]", name, i));
102        }
103        return list;
104      }
105    
106      private static final String IDENTIFIER_PATTERN_STR = "[a-zA-z_][a-zA-Z0-9_\\-]*";
107    
108      private static final Pattern IDENTIFIER_PATTERN = Pattern.compile("^" + IDENTIFIER_PATTERN_STR + "$");
109    
110      /**
111       * Verifies a value is a valid identifier,
112       * <code>[a-zA-z_][a-zA-Z0-9_\-]*</code>, up to a maximum length.
113       *
114       * @param value string to check if it is a valid identifier.
115       * @param maxLen maximun length.
116       * @param name the name to use in the exception message.
117       *
118       * @return the value.
119       *
120       * @throws IllegalArgumentException if the string is not a valid identifier.
121       */
122      public static String validIdentifier(String value, int maxLen, String name) {
123        Check.notEmpty(value, name);
124        if (value.length() > maxLen) {
125          throw new IllegalArgumentException(
126            MessageFormat.format("[{0}] = [{1}] exceeds max len [{2}]", name, value, maxLen));
127        }
128        if (!IDENTIFIER_PATTERN.matcher(value).find()) {
129          throw new IllegalArgumentException(
130            MessageFormat.format("[{0}] = [{1}] must be '{2}'", name, value, IDENTIFIER_PATTERN_STR));
131        }
132        return value;
133      }
134    
135      /**
136       * Verifies an integer is greater than zero.
137       *
138       * @param value integer value.
139       * @param name the name to use in the exception message.
140       *
141       * @return the value.
142       *
143       * @throws IllegalArgumentException if the integer is zero or less.
144       */
145      public static int gt0(int value, String name) {
146        return (int) gt0((long) value, name);
147      }
148    
149      /**
150       * Verifies an long is greater than zero.
151       *
152       * @param value long value.
153       * @param name the name to use in the exception message.
154       *
155       * @return the value.
156       *
157       * @throws IllegalArgumentException if the long is zero or less.
158       */
159      public static long gt0(long value, String name) {
160        if (value <= 0) {
161          throw new IllegalArgumentException(
162            MessageFormat.format("parameter [{0}] = [{1}] must be greater than zero", name, value));
163        }
164        return value;
165      }
166    
167      /**
168       * Verifies an integer is greater or equal to zero.
169       *
170       * @param value integer value.
171       * @param name the name to use in the exception message.
172       *
173       * @return the value.
174       *
175       * @throws IllegalArgumentException if the integer is greater or equal to zero.
176       */
177      public static int ge0(int value, String name) {
178        return (int) ge0((long) value, name);
179      }
180    
181      /**
182       * Verifies an long is greater or equal to zero.
183       *
184       * @param value integer value.
185       * @param name the name to use in the exception message.
186       *
187       * @return the value.
188       *
189       * @throws IllegalArgumentException if the long is greater or equal to zero.
190       */
191      public static long ge0(long value, String name) {
192        if (value < 0) {
193          throw new IllegalArgumentException(MessageFormat.format(
194            "parameter [{0}] = [{1}] must be greater than or equals zero", name, value));
195        }
196        return value;
197      }
198    
199    }