Guava学习笔记(2)--使用Preconditions作参数的预判断[翻译+学习笔记]

Guava中提供了一个作参数检查的工具类--Preconditions, 静态导入这个类, 可以大大地简化代码中对于参数的预判断和处理.

import static com.google.common.base.Preconditions.*;

在以前, 我们需要判断一个参数不为空的话, 需要像下面这样写

	public void testMethod(Object obj) {
		if (obj == null) {
			throw new NullPointerException();
		}
		// ... other operations
	}

 每次都要添加if语句来做判断, 重复的工作会做好多次. 使用Preconditions可以简化成下面这样

	public void testMethod(Object obj) {
		Object other = checkNotNull(obj);
		// ... other operations
	}

 checkNotNull会检查参数是否为null, 当为null的时候会抛出NullPointerException, 否则直接返回参数.

checkNotNull, checkArgument和checkState, 都有三种形式的参数:

• public static <T> T checkNotNull(T reference), 只包含需要判断的对象, 无其他多余的参数, 抛出的异常不带有任何异常信息
• public static <T> T checkNotNull(T reference, @Nullable Object errorMessage), 包含一个错误信息的额外参数, 抛出的异常带有errorMessage.toString()的异常信息
• public static <T> T checkNotNull(T reference, @Nullable String errorMessageTemplate, @Nullable Object... errorMessageArgs), 这种是printf风格的错误信息, 后面是变参, errorMessageTemplate可以使用一些占位符. 例如可以这样写

 

checkArgument(i >= 0, "Argument was %s but expected nonnegative", i);
checkArgument(i < j, "Expected i < j, but %s > %s", i, j);

捕获异常后可以获取自定义的详细错误信息, 对于调试来说很有帮助, 而且代码也很简洁. 例如,

		Object obj = null;
		try {
			checkNotNull(obj, "cannot be null");
		} catch(Exception e) {
			System.out.println(e.getMessage());
		}

 运行后可以获得自定义的异常信息"cannot be null".

Preconditions里面的方法有下面几个

方法签名 (不包含额外参数)	功能描述	失败时抛出的异常类型
checkArgument(boolean)	检查boolean是否为真. 用作方法中检查参数.	IllegalArgumentException
checkNotNull(T)	检查value不为null. 直接返回value.	NullPointerException
checkState(boolean)	检查对象的一些状态, 不依赖方法参数. 例如, Iterator可以用来next是否在remove之前被调用.	IllegalStateException
checkElementIndex(int index, int size)	检查index是否为在一个长度为size的list, string或array合法的范围. index的范围区间是[0, size)(包含0不包含size). 无需直接传入list, string或array, 只需传入大小. 返回index.	IndexOutOfBoundsException
checkPositionIndex(int index, int size)	检查位置index是否为在一个长度为size的list, string或array合法的范围. index的范围区间是[0, size)(包含0不包含size). 无需直接传入list, string或array, 只需传入大小. 返回index.	IndexOutOfBoundsException
checkPositionIndexes(int start, int end, int size)	检查[start, end)是一个长度为size的list, string或array合法的范围子集.伴随着错误信息.	IndexOutOfBoundsException

 Guava的preconditions有这样几个优点:

• 在静态导入后, 方法很明确无歧义, checkNotNull可以清楚地告诉你它是干什么的, 它会抛出怎样的异常.
• checkNotNull在验证通过后直接返回, 可以这样方便地写代码: this.field = checkNotNull(field).
• 简单而又强大的可变参数'printf'风格的自定义错误信息.

我们建议将preconditions放置在单独的行上, 这样可以在调试的时候清楚地指明哪个precondition出现错误. 另外, 提供有帮助的错误信息也非常有用.

简单的preconditions确实强大而且易用.

参考资料:

1. 官方wiki: http://code.google.com/p/guava-libraries/wiki/GuavaExplained
2. Preconditions: http://code.google.com/p/guava-libraries/wiki/PreconditionsExplained