cloud.opencode.base.core.Preconditions

public final class Preconditions extends Object

Preconditions Class - Guava-style precondition checks for library/framework developers 前置条件校验类 - 面向库/框架开发者的 Guava 风格前置条件检查

Provides Guava-style precondition checks (checkNotNull, checkArgument, checkState, checkElementIndex, checkPositionIndex) designed for library and framework development. Methods return the validated value to support fluent chaining, and use lightweight %s placeholder formatting.

提供 Guava 风格的前置条件检查方法（checkNotNull、checkArgument、checkState、 checkElementIndex、checkPositionIndex），专为库和框架开发设计。方法返回校验后的值以支持链式调用，使用轻量的 %s 占位符格式化。

When to use this class vs OpenAssert | 本类与 OpenAssert 的选择:

Preconditions — Guava-style, for library/framework internals: compact API (checkNotNull, checkArgument, checkState), index boundary checks, %s template formatting. 适用于库/框架内部：紧凑的 API，索引边界检查，%s 模板格式化。
OpenAssert — Spring Assert-style, for business application code: rich validation API (notNull, notEmpty, notBlank, inclusiveBetween, isInstanceOf, matchesPattern), collection/map/array emptiness checks, type checks. 适用于业务应用代码：丰富的验证 API，集合/Map/数组空值检查，类型检查。

Features | 主要功能:

Null checking (checkNotNull) - 非空校验
Argument validation (checkArgument) - 参数校验
State validation (checkState) - 状态校验
Index validation (checkElementIndex, checkPositionIndex) - 索引校验
Formatted error messages with %s placeholders - 格式化错误消息

Usage Examples | 使用示例:

// Null checking - 非空校验
this.name = Preconditions.checkNotNull(name, "name cannot be null");

// Argument validation - 参数校验
Preconditions.checkArgument(age > 0, "age must be positive, got: %s", age);

// State validation - 状态校验
Preconditions.checkState(isInitialized, "service not initialized");

// Index validation - 索引校验
int idx = Preconditions.checkElementIndex(index, list.size(), "index");

Security | 安全性:

Thread-safe: Yes (stateless) - 线程安全: 是 (无状态)
Null-safe: Yes - 空值安全: 是

Since:

JDK 25, opencode-base-core V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

static void

checkArgument(boolean expression)

Checks the argument condition, otherwise throws OpenIllegalArgumentException 检查参数条件，否则抛出 OpenIllegalArgumentException

static void

checkArgument(boolean expression, String errorMessage)

Checks the argument condition, otherwise throws OpenIllegalArgumentException with message 检查参数条件，否则抛出带消息的 OpenIllegalArgumentException

static void

checkArgument(boolean expression, String template, Object... args)

Checks the argument condition, otherwise throws OpenIllegalArgumentException with formatted message 检查参数条件，否则抛出格式化消息的 OpenIllegalArgumentException

static int

checkBetween(int value, int min, int max, String name)

Checks that the value is between min and max (inclusive), returns the value for chaining.

static long

checkBetween(long value, long min, long max, String name)

Checks that the value is between min and max (inclusive), returns the value for chaining.

static int

checkElementIndex(int index, int size)

Checks if the element index is valid [0, size) 检查元素索引是否有效 [0, size)

static int

checkElementIndex(int index, int size, String desc)

Checks if the element index is valid [0, size) 检查元素索引是否有效 [0, size)

static int

checkNonNegative(int value, String name)

Checks that the value is non-negative (>= 0), returns the value for chaining.

static long

checkNonNegative(long value, String name)

Checks that the value is non-negative (>= 0), returns the value for chaining.

static String

checkNotBlank(String value, String name)

Checks that the string is not null and not blank (after trimming), returns it for chaining.

static <T extends Collection<?>> T

checkNotEmpty(T collection, String name)

Checks that the collection is not null and not empty, returns it for chaining.

static <T extends Map<?,?>> T

checkNotEmpty(T map, String name)

Checks that the map is not null and not empty, returns it for chaining.

static <T> T

checkNotNull(T reference)

Checks that the object is not null, otherwise throws NullPointerException 检查对象非空，否则抛出 NullPointerException

static <T> T

checkNotNull(T reference, String errorMessage)

Checks that the object is not null, otherwise throws NullPointerException with message 检查对象非空，否则抛出带消息的 NullPointerException

static <T> T

checkNotNull(T reference, String template, Object... args)

Checks that the object is not null, otherwise throws NullPointerException with formatted message 检查对象非空，否则抛出格式化消息的 NullPointerException

static int

checkPositionIndex(int index, int size)

Checks if the position index is valid [0, size] 检查位置索引是否有效 [0, size]

static int

checkPositionIndex(int index, int size, String desc)

Checks if the position index is valid [0, size] 检查位置索引是否有效 [0, size]

static void

checkPositionIndexes(int start, int end, int size)

Checks if the position range is valid [start, end] and end <= size.

static int

checkPositive(int value, String name)

Checks that the value is positive (> 0), returns the value for chaining.

static long

checkPositive(long value, String name)

Checks that the value is positive (> 0), returns the value for chaining.

static void

checkState(boolean expression)

Checks the state condition, otherwise throws OpenIllegalStateException 检查状态条件，否则抛出 OpenIllegalStateException

static void

checkState(boolean expression, String errorMessage)

Checks the state condition, otherwise throws OpenIllegalStateException with message 检查状态条件，否则抛出带消息的 OpenIllegalStateException

static void

checkState(boolean expression, String template, Object... args)

Checks the state condition, otherwise throws OpenIllegalStateException with formatted message 检查状态条件，否则抛出格式化消息的 OpenIllegalStateException

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- checkNotNull
  
  public static <T> T checkNotNull(T reference)
  
  Checks that the object is not null, otherwise throws NullPointerException 检查对象非空，否则抛出 NullPointerException
  
  Type Parameters:
  
  T - the object type | 对象类型
  
  Parameters:
  
  reference - the object to check | 待检查的对象
  
  Returns:
  
  the validated object (supports chaining) | 校验后的对象（支持链式调用）
  
  Throws:
  
  NullPointerException - if the object is null | 如果对象为 null
- checkNotNull
  
  public static <T> T checkNotNull(T reference, String errorMessage)
  
  Checks that the object is not null, otherwise throws NullPointerException with message 检查对象非空，否则抛出带消息的 NullPointerException
  
  Type Parameters:
  
  T - the object type | 对象类型
  
  Parameters:
  
  reference - the object to check | 待检查的对象
  
  errorMessage - the error message | 异常消息
  
  Returns:
  
  the validated object (supports chaining) | 校验后的对象（支持链式调用）
  
  Throws:
  
  NullPointerException - if the object is null | 如果对象为 null
- checkNotNull
  
  public static <T> T checkNotNull(T reference, String template, Object... args)
  
  Checks that the object is not null, otherwise throws NullPointerException with formatted message 检查对象非空，否则抛出格式化消息的 NullPointerException
  
  Type Parameters:
  
  T - the object type | 对象类型
  
  Parameters:
  
  reference - the object to check | 待检查的对象
  
  template - the message template with %s placeholders | 消息模板，使用 %s 作为占位符
  
  args - the template arguments | 模板参数
  
  Returns:
  
  the validated object (supports chaining) | 校验后的对象（支持链式调用）
  
  Throws:
  
  NullPointerException - if the object is null | 如果对象为 null
- checkArgument
  
  public static void checkArgument(boolean expression)
  
  Checks the argument condition, otherwise throws OpenIllegalArgumentException 检查参数条件，否则抛出 OpenIllegalArgumentException
  
  Parameters:
  
  expression - the condition expression | 条件表达式
  
  Throws:
  
  OpenIllegalArgumentException - if the condition is false | 如果条件为 false
- checkArgument
  
  public static void checkArgument(boolean expression, String errorMessage)
  
  Checks the argument condition, otherwise throws OpenIllegalArgumentException with message 检查参数条件，否则抛出带消息的 OpenIllegalArgumentException
  
  Parameters:
  
  expression - the condition expression | 条件表达式
  
  errorMessage - the error message | 异常消息
  
  Throws:
  
  OpenIllegalArgumentException - if the condition is false | 如果条件为 false
- checkArgument
  
  public static void checkArgument(boolean expression, String template, Object... args)
  
  Checks the argument condition, otherwise throws OpenIllegalArgumentException with formatted message 检查参数条件，否则抛出格式化消息的 OpenIllegalArgumentException
  
  Parameters:
  
  expression - the condition expression | 条件表达式
  
  template - the message template with %s placeholders | 消息模板，使用 %s 作为占位符
  
  args - the template arguments | 模板参数
  
  Throws:
  
  OpenIllegalArgumentException - if the condition is false | 如果条件为 false
- checkState
  
  public static void checkState(boolean expression)
  
  Checks the state condition, otherwise throws OpenIllegalStateException 检查状态条件，否则抛出 OpenIllegalStateException
  
  Parameters:
  
  expression - the condition expression | 条件表达式
  
  Throws:
  
  OpenIllegalStateException - if the condition is false | 如果条件为 false
- checkState
  
  public static void checkState(boolean expression, String errorMessage)
  
  Checks the state condition, otherwise throws OpenIllegalStateException with message 检查状态条件，否则抛出带消息的 OpenIllegalStateException
  
  Parameters:
  
  expression - the condition expression | 条件表达式
  
  errorMessage - the error message | 异常消息
  
  Throws:
  
  OpenIllegalStateException - if the condition is false | 如果条件为 false
- checkState
  
  public static void checkState(boolean expression, String template, Object... args)
  
  Checks the state condition, otherwise throws OpenIllegalStateException with formatted message 检查状态条件，否则抛出格式化消息的 OpenIllegalStateException
  
  Parameters:
  
  expression - the condition expression | 条件表达式
  
  template - the message template with %s placeholders | 消息模板，使用 %s 作为占位符
  
  args - the template arguments | 模板参数
  
  Throws:
  
  OpenIllegalStateException - if the condition is false | 如果条件为 false
- checkElementIndex
  
  public static int checkElementIndex(int index, int size)
  
  Checks if the element index is valid [0, size) 检查元素索引是否有效 [0, size)
  
  Parameters:
  
  index - the index value | 索引值
  
  size - the collection size | 集合大小
  
  Returns:
  
  the validated index | 校验后的索引
  
  Throws:
  
  IndexOutOfBoundsException - if the index is invalid | 如果索引无效
- checkElementIndex
  
  public static int checkElementIndex(int index, int size, String desc)
  
  Checks if the element index is valid [0, size) 检查元素索引是否有效 [0, size)
  
  Parameters:
  
  index - the index value | 索引值
  
  size - the collection size | 集合大小
  
  desc - the index description | 索引描述
  
  Returns:
  
  the validated index | 校验后的索引
  
  Throws:
  
  IndexOutOfBoundsException - if the index is invalid | 如果索引无效
- checkPositionIndex
  
  public static int checkPositionIndex(int index, int size)
  
  Checks if the position index is valid [0, size] 检查位置索引是否有效 [0, size]
  
  Parameters:
  
  index - the index value | 索引值
  
  size - the collection size | 集合大小
  
  Returns:
  
  the validated index | 校验后的索引
  
  Throws:
  
  IndexOutOfBoundsException - if the index is invalid | 如果索引无效
- checkPositionIndex
  
  public static int checkPositionIndex(int index, int size, String desc)
  
  Checks if the position index is valid [0, size] 检查位置索引是否有效 [0, size]
  
  Parameters:
  
  index - the index value | 索引值
  
  size - the collection size | 集合大小
  
  desc - the index description | 索引描述
  
  Returns:
  
  the validated index | 校验后的索引
  
  Throws:
  
  IndexOutOfBoundsException - if the index is invalid | 如果索引无效
- checkPositionIndexes
  
  public static void checkPositionIndexes(int start, int end, int size)
  
  Checks if the position range is valid [start, end] and end <= size. 检查位置范围是否有效 [start, end] 且 end <= size。
  
  Parameters:
  
  start - the start index | 起始索引
  
  end - the end index | 结束索引
  
  size - the collection size | 集合大小
  
  Throws:
  
  IndexOutOfBoundsException - if the range is invalid | 如果范围无效
- checkPositive
  
  public static int checkPositive(int value, String name)
  
  Checks that the value is positive (> 0), returns the value for chaining. 检查值为正数（> 0），返回值以支持链式调用。
  
  Parameters:
  
  value - the value to check | 待检查的值
  
  name - the parameter name for error message | 参数名，用于错误消息
  
  Returns:
  
  the validated value | 校验后的值
  
  Throws:
  
  OpenIllegalArgumentException - if the value is not positive | 如果值不为正数
- checkPositive
  
  public static long checkPositive(long value, String name)
  
  Checks that the value is positive (> 0), returns the value for chaining. 检查值为正数（> 0），返回值以支持链式调用。
  
  Parameters:
  
  value - the value to check | 待检查的值
  
  name - the parameter name for error message | 参数名，用于错误消息
  
  Returns:
  
  the validated value | 校验后的值
  
  Throws:
  
  OpenIllegalArgumentException - if the value is not positive | 如果值不为正数
- checkNonNegative
  
  public static int checkNonNegative(int value, String name)
  
  Checks that the value is non-negative (>= 0), returns the value for chaining. 检查值为非负数（>= 0），返回值以支持链式调用。
  
  Parameters:
  
  value - the value to check | 待检查的值
  
  name - the parameter name for error message | 参数名，用于错误消息
  
  Returns:
  
  the validated value | 校验后的值
  
  Throws:
  
  OpenIllegalArgumentException - if the value is negative | 如果值为负数
- checkNonNegative
  
  public static long checkNonNegative(long value, String name)
  
  Checks that the value is non-negative (>= 0), returns the value for chaining. 检查值为非负数（>= 0），返回值以支持链式调用。
  
  Parameters:
  
  value - the value to check | 待检查的值
  
  name - the parameter name for error message | 参数名，用于错误消息
  
  Returns:
  
  the validated value | 校验后的值
  
  Throws:
  
  OpenIllegalArgumentException - if the value is negative | 如果值为负数
- checkBetween
  
  public static int checkBetween(int value, int min, int max, String name)
  
  Checks that the value is between min and max (inclusive), returns the value for chaining. 检查值在 min 和 max 之间（包含边界），返回值以支持链式调用。
  
  Parameters:
  
  value - the value to check | 待检查的值
  
  min - the minimum (inclusive) | 最小值（包含）
  
  max - the maximum (inclusive) | 最大值（包含）
  
  name - the parameter name for error message | 参数名，用于错误消息
  
  Returns:
  
  the validated value | 校验后的值
  
  Throws:
  
  OpenIllegalArgumentException - if the value is out of range | 如果值超出范围
- checkBetween
  
  public static long checkBetween(long value, long min, long max, String name)
  
  Checks that the value is between min and max (inclusive), returns the value for chaining. 检查值在 min 和 max 之间（包含边界），返回值以支持链式调用。
  
  Parameters:
  
  value - the value to check | 待检查的值
  
  min - the minimum (inclusive) | 最小值（包含）
  
  max - the maximum (inclusive) | 最大值（包含）
  
  name - the parameter name for error message | 参数名，用于错误消息
  
  Returns:
  
  the validated value | 校验后的值
  
  Throws:
  
  OpenIllegalArgumentException - if the value is out of range | 如果值超出范围
- checkNotBlank
  
  public static String checkNotBlank(String value, String name)
  
  Checks that the string is not null and not blank (after trimming), returns it for chaining. 检查字符串非 null 且非空白（去除空格后），返回以支持链式调用。
  
  Parameters:
  
  value - the string to check | 待检查的字符串
  
  name - the parameter name for error message | 参数名，用于错误消息
  
  Returns:
  
  the validated string | 校验后的字符串
  
  Throws:
  
  OpenIllegalArgumentException - if the string is null or blank | 如果字符串为 null 或空白
- checkNotEmpty
  
  public static <T extends Collection<?>> T checkNotEmpty(T collection, String name)
  
  Checks that the collection is not null and not empty, returns it for chaining. 检查集合非 null 且非空，返回以支持链式调用。
  
  Type Parameters:
  
  T - the collection type | 集合类型
  
  Parameters:
  
  collection - the collection to check | 待检查的集合
  
  name - the parameter name for error message | 参数名，用于错误消息
  
  Returns:
  
  the validated collection | 校验后的集合
  
  Throws:
  
  OpenIllegalArgumentException - if the collection is null or empty | 如果集合为 null 或为空
- checkNotEmpty
  
  public static <T extends Map<?,?>> T checkNotEmpty(T map, String name)
  
  Checks that the map is not null and not empty, returns it for chaining. 检查映射非 null 且非空，返回以支持链式调用。
  
  Type Parameters:
  
  T - the map type | 映射类型
  
  Parameters:
  
  map - the map to check | 待检查的映射
  
  name - the parameter name for error message | 参数名，用于错误消息
  
  Returns:
  
  the validated map | 校验后的映射
  
  Throws:
  
  OpenIllegalArgumentException - if the map is null or empty | 如果映射为 null 或为空

Class Preconditions

Method Summary

Methods inherited from class Object

Method Details

checkNotNull

checkNotNull

checkNotNull

checkArgument

checkArgument

checkArgument

checkState

checkState

checkState

checkElementIndex

checkElementIndex

checkPositionIndex

checkPositionIndex

checkPositionIndexes

checkPositive

checkPositive

checkNonNegative

checkNonNegative

checkBetween

checkBetween

checkNotBlank

checkNotEmpty

checkNotEmpty