Chapter 2 -- Preconditions

Using Guava's precondition checking utilities, explained. 
explained

Updated  Apr 23, 2012 by  wasserman.louis

Preconditions

Guava provides a number of precondition checking utilities. We strongly recommend importing these statically. (How to do this easily in Eclipse.)

Guava提供了一系列precondition检查工具. 我们强烈推荐你静态引入这些工具

Each method has three variants:

每种方法都有三种变体

• No extra arguments. Any exceptions are thrown without error messages.
• 无额外参数版本.异常抛出时不带错误消息
• An extra Object argument. Any exception is thrown with the error message object.toString().
• 有一个额外的Object参数版本.异常抛出时会附带一个object.toString()的错误消息
• An extra String argument, with an arbitrary number of additional Object arguments. This behaves something like printf, but for GWT compatibility and efficiency, it only allows %s indicators. Example:
• 有一个额外的String参数和任意个Object参数版本. 这种表现类似于printf, 但是为了GWT的兼容性和效率,他仅仅支持 s% 标识符. 例子:

 

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

 

Signature (not including extra args)	Description	Exception thrown on failure
checkArgument(boolean)	Checks that the boolean is true. Use for validating arguments to methods. 检查boolean是否是true. 用来验证方法参数	IllegalArgumentException
checkNotNull(T)	Checks that the value is not null. Returns the value directly, so you can use checkNotNull(value) inline. 检查值是否是null. 方法直接这个值,所以你可以直接在行内使用checkNotNull(value)	NullPointerException
checkState(boolean)	Checks some state of the object, not dependent on the method arguments. For example, an Iterator might use this to check that next has been called before any call to remove. 检查对象的状态, 它不依赖于方法参数. 例如, Iterator可能会用这个方法来检查next是否在remove之前调用	IllegalStateException
checkElementIndex(int index, int size)	Checks that index is a valid element index into a list, string, or array with the specified size. An element index may range from 0 inclusive to size exclusive. You don't pass the list, string, or array directly; you just pass its size. 检查index是否是一个合法的长度为size的list,string,array的element index.element index的范围从0(包括)到size(不包括).你不需要直接传list,string,array,只要传他们的ize Returns index. 返回index	IndexOutOfBoundsException
checkPositionIndex(int index, int size)	Checks that index is a valid position index into a list, string, or array with the specified size. A position index may range from 0 inclusive to size inclusive. You don't pass the list, string, or array directly; you just pass its size. 检查index是否是一个合法的长度为size的list.string.array的position index.position index的范围从0(包括)到size(包括).你不需要直接传list,string,array,只需要传他们的size Returns index.	IndexOutOfBoundsException
checkPositionIndexes(int start, int end, int size)	Checks that [start, end) is a valid sub range of a list, string, or array with the specified size. Comes with its own error message. 检查[start, end)是否是一个长度为size的list,string,array的子范围.	IndexOutOfBoundsException

 

We preferred rolling our own preconditions checks over e.g. the comparable utilities from Apache Commons for a few reasons. Piotr Jagielski discusses why he prefers our utilities, but briefly:

因为某些原因,我们更建议使用我们的preconditions而不是使用Apache Commons 的 comparable工具. Piotr Jagielski 讨论了 为什么他愿意这么做, 简要的说一下原因:

• After static imports, the Guava methods are clear and unambiguous. checkNotNull makes it clear what is being done, and what exception will be thrown.
• 通过静态引入, Guava方法更清晰且没有歧义. checkNotNull 可以清楚的知道方法将会做什么, 它会抛出什么异常.
• checkNotNull returns its argument after validation, allowing simple one-liners in constructors: this.field = checkNotNull(field).
• checkNotNull 在验证完后返回它的参数, 允许使用简单的行内写法: this.field = checkNotNull(field).
• Simple, varargs "printf-style" exception messages. (This advantage is also why we recommend continuing to use checkNotNull overObjects.requireNonNull introduced in JDK 7.)
• 简单的可变参式"printf-style"异常信息. (这个有点也是我们为什么会在JDK7的Objects.requireNonNull的介绍中推荐使用checkNotNull的原因)

We recommend that you split up preconditions into distinct lines, which can help you figure out which precondition failed while debugging. Additionally, you should provide helpful error messages, which is easier when each check is on its own line.

我们推荐你切分preconditions到不同的行中,这样可以帮助你在debug时找出哪个precondition失败了. 另外, 你应该提供有用的错误信息, 这样当每个check在他自己的行上时更容易确认错误所在.