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
019package org.apache.hadoop.lib.util;
020
021import java.text.MessageFormat;
022import java.util.List;
023import java.util.regex.Pattern;
024
025/**
026 * Utility methods to check preconditions.
027 * <p/>
028 * Commonly used for method arguments preconditions.
029 */
030public 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}