javaemul.internal

Class InternalPreconditions

java.lang.Object

javaemul.internal.InternalPreconditions

public final class InternalPreconditions
extends Object

A utility class that provides utility functions to do precondition checks inside GWT-SDK.

Following table summarizes the grouping of the checks:

 ┌────────┬─────────────────────────────────────────────────────┬───────────────────────────────┐
 │Group   │Description                                          │Common Exception Types         │
 ├────────┼─────────────────────────────────────────────────────┼───────────────────────────────┤
 │BOUNDS  │Checks related to the bound checking in collections. │IndexOutBoundsException        │
 │        │                                                     │ArrayIndexOutOfBoundsException │
 ├────────┼─────────────────────────────────────────────────────┼───────────────────────────────┤
 │API     │Checks related to the correct usage of APIs.         │IllegalStateException          │
 │        │                                                     │NoSuchElementException         │
 │        │                                                     │NullPointerException           │
 │        │                                                     │IllegalArgumentException       │
 │        │                                                     │ConcurrentModificationException│
 ├────────┼─────────────────────────────────────────────────────┼───────────────────────────────┤
 │NUMERIC │Checks related to numeric operations.                │ArithmeticException            │
 ├────────┼─────────────────────────────────────────────────────┼───────────────────────────────┤
 │TYPE    │Checks related to java type system.                  │ClassCastException             │
 │        │                                                     │ArrayStoreException            │
 ├────────┼─────────────────────────────────────────────────────┼───────────────────────────────┤
 │CRITICAL│Checks for cases where not failing-fast will keep    │IllegalArgumentException       │
 │        │the object in an inconsistent state and/or degrade   │                               │
 │        │debugging significantly. Currently disabling these   │                               │
 │        │checks is not supported.                             │                               │
 └────────┴─────────────────────────────────────────────────────┴───────────────────────────────┘
 

Following table summarizes predefined check levels:

 ┌────────────────┬──────────┬─────────┬─────────┬─────────┬─────────┐
 │Check level     │  BOUNDS  │   API   │ NUMERIC |  TYPE   │CRITICAL │
 ├────────────────┼──────────┼─────────┼─────────┼─────────┼─────────┤
 │Normal (default)│    X     │    X    │    X    │    X    │    X    │
 ├────────────────┼──────────┼─────────┼─────────┼─────────┼─────────┤
 │Optimized       │          │         │         │    X    │    X    │
 ├────────────────┼──────────┼─────────┼─────────┼─────────┼─────────┤
 │Minimal         │          │         │         │         │    X    │
 ├────────────────┼──────────┼─────────┼─────────┼─────────┼─────────┤
 │None (N/A yet)  │          │         │         │         │         │
 └────────────────┴──────────┴─────────┴─────────┴─────────┴─────────┘
 

Please note that, in development mode (jre.checkedMode=ENABLED), these checks will always be performed regardless of configuration but will be converted to AssertionError if check is disabled. This so that any reliance on related exceptions could be detected early on. For this detection to work properly; it is important for apps to share the same config in all environments.

Method Summary

Modifier and Type	Method and Description
static void	checkArgument(boolean expression) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkArgument(boolean expression, Object errorMessage) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkArgument(boolean expression, String errorMessageTemplate, Object... errorMessageArgs) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkArithmetic(boolean expression)
static void	checkArraySize(int size) Ensures that size specifies a valid array size (i.e.
static void	checkArrayType(boolean expression) Ensures the truth of an expression that verifies array type.
static void	checkArrayType(boolean expression, Object errorMessage) Ensures the truth of an expression that verifies array type.
static void	checkCriticalArgument(boolean expression) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkCriticalArgument(boolean expression, Object errorMessage) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkCriticalArgument(boolean expression, String errorMessageTemplate, Object... errorMessageArgs) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkCriticalArithmetic(boolean expression)
static void	checkCriticalArrayBounds(int start, int end, int length) Checks that array bounds are correct.
static void	checkCriticalArraySize(int size)
static void	checkCriticalArrayType(boolean expression)
static void	checkCriticalArrayType(boolean expression, Object errorMessage)
static void	checkCriticalElement(boolean expression) Ensures the truth of an expression involving existence of an element.
static void	checkCriticalElement(boolean expression, Object errorMessage) Ensures the truth of an expression involving existence of an element.
static void	checkCriticalElementIndex(int index, int size)
static void	checkCriticalNotNull(Object reference, Object errorMessage)
static <T> T	checkCriticalNotNull(T reference)
static void	checkCriticalPositionIndex(int index, int size)
static void	checkCriticalPositionIndexes(int start, int end, int size) Ensures that start and end specify a valid positions in a list of size size, and are in order.
static void	checkCriticalState(boolean expression) Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.
static void	checkCriticalState(boolean expression, Object errorMessage) Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.
static void	checkCriticalStringBounds(int start, int end, int length) Checks that string bounds are correct.
static void	checkCriticalStringElementIndex(int index, int size)
static void	checkCriticalType(boolean expression)
static void	checkCriticalType(boolean expression, String message)
static void	checkElement(boolean expression) Ensures the truth of an expression involving existence of an element.
static void	checkElement(boolean expression, Object errorMessage) Ensures the truth of an expression involving existence of an element.
static void	checkElementIndex(int index, int size) Ensures that index specifies a valid element in a list or string of size size.
static void	checkNotNull(Object reference, Object errorMessage) Ensures that an object reference passed as a parameter to the calling method is not null.
static <T> T	checkNotNull(T reference) Ensures that an object reference passed as a parameter to the calling method is not null.
static void	checkPositionIndex(int index, int size) Ensures that index specifies a valid position in a list of size size.
static void	checkPositionIndexes(int start, int end, int size) Ensures that start and end specify a valid positions in a list of size size, and are in order.
static void	checkState(boolean expression) Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.
static void	checkState(boolean expression, Object errorMessage) Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.
static void	checkStringElementIndex(int index, int size)
static void	checkType(boolean expression)
static void	checkType(boolean expression, String message)
static boolean	isApiChecked() This method reports if the code is compiled with api checks.
static boolean	isTypeChecked() This method reports if the code is compiled with type checks.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, toString

Method Detail

isTypeChecked

public static boolean isTypeChecked()

This method reports if the code is compiled with type checks. It must be used in places where code can be replaced with a simpler one when we know that no checks will occur. See System.arraycopy(Object, int, Object, int, int) for example. Please note that checkType(boolean) should be preferred where feasible.

isApiChecked

public static boolean isApiChecked()

This method reports if the code is compiled with api checks. It must be used in places where code can be replaced with a simpler one when we know that no checks will occur. Please note that #checkXXX(boolean) should be preferred where feasible.

checkType

public static void checkType(boolean expression)

checkType

public static void checkType(boolean expression,
                             String message)

checkCriticalType

public static void checkCriticalType(boolean expression)

checkCriticalType

public static void checkCriticalType(boolean expression,
                                     String message)

checkArrayType

public static void checkArrayType(boolean expression)

Ensures the truth of an expression that verifies array type.

checkCriticalArrayType

public static void checkCriticalArrayType(boolean expression)

checkArrayType

public static void checkArrayType(boolean expression,
                                  Object errorMessage)

Ensures the truth of an expression that verifies array type.

checkCriticalArrayType

public static void checkCriticalArrayType(boolean expression,
                                          Object errorMessage)

checkArithmetic

public static void checkArithmetic(boolean expression)

checkCriticalArithmetic

public static void checkCriticalArithmetic(boolean expression)

checkElement

public static void checkElement(boolean expression)

Ensures the truth of an expression involving existence of an element.

checkCriticalElement

public static void checkCriticalElement(boolean expression)

Ensures the truth of an expression involving existence of an element.

For cases where failing fast is pretty important and not failing early could cause bugs that are much harder to debug.

checkElement

public static void checkElement(boolean expression,
                                Object errorMessage)

Ensures the truth of an expression involving existence of an element.

checkCriticalElement

public static void checkCriticalElement(boolean expression,
                                        Object errorMessage)

Ensures the truth of an expression involving existence of an element.

For cases where failing fast is pretty important and not failing early could cause bugs that are much harder to debug.

checkArgument

public static void checkArgument(boolean expression)

Ensures the truth of an expression involving one or more parameters to the calling method.

checkCriticalArgument

public static void checkCriticalArgument(boolean expression)

Ensures the truth of an expression involving one or more parameters to the calling method.

For cases where failing fast is pretty important and not failing early could cause bugs that are much harder to debug.

checkArgument

public static void checkArgument(boolean expression,
                                 Object errorMessage)

Ensures the truth of an expression involving one or more parameters to the calling method.

checkCriticalArgument

public static void checkCriticalArgument(boolean expression,
                                         Object errorMessage)

Ensures the truth of an expression involving one or more parameters to the calling method.

For cases where failing fast is pretty important and not failing early could cause bugs that are much harder to debug.

checkArgument

public static void checkArgument(boolean expression,
                                 String errorMessageTemplate,
                                 Object... errorMessageArgs)

Ensures the truth of an expression involving one or more parameters to the calling method.

checkCriticalArgument

public static void checkCriticalArgument(boolean expression,
                                         String errorMessageTemplate,
                                         Object... errorMessageArgs)

Ensures the truth of an expression involving one or more parameters to the calling method.

For cases where failing fast is pretty important and not failing early could cause bugs that are much harder to debug.

checkState

public static void checkState(boolean expression)

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

Parameters:

expression - a boolean expression

Throws:

IllegalStateException - if expression is false

checkCriticalState

public static void checkCriticalState(boolean expression)

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

For cases where failing fast is pretty important and not failing early could cause bugs that are much harder to debug.

checkState

public static void checkState(boolean expression,
                              Object errorMessage)

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

checkCriticalState

public static void checkCriticalState(boolean expression,
                                      Object errorMessage)

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

checkNotNull

public static <T> T checkNotNull(T reference)

Ensures that an object reference passed as a parameter to the calling method is not null.

checkCriticalNotNull

public static <T> T checkCriticalNotNull(T reference)

checkNotNull

public static void checkNotNull(Object reference,
                                Object errorMessage)

Ensures that an object reference passed as a parameter to the calling method is not null.

checkCriticalNotNull

public static void checkCriticalNotNull(Object reference,
                                        Object errorMessage)

checkArraySize

public static void checkArraySize(int size)

Ensures that size specifies a valid array size (i.e. non-negative).

checkCriticalArraySize

public static void checkCriticalArraySize(int size)

checkElementIndex

public static void checkElementIndex(int index,
                                     int size)

Ensures that index specifies a valid element in a list or string of size size. An element index may range from zero, inclusive, to size, exclusive.

checkCriticalElementIndex

public static void checkCriticalElementIndex(int index,
                                             int size)

checkStringElementIndex

public static void checkStringElementIndex(int index,
                                           int size)

checkCriticalStringElementIndex

public static void checkCriticalStringElementIndex(int index,
                                                   int size)

checkPositionIndex

public static void checkPositionIndex(int index,
                                      int size)

Ensures that index specifies a valid position in a list of size size. A position index may range from zero to size, inclusive.

checkCriticalPositionIndex

public static void checkCriticalPositionIndex(int index,
                                              int size)

checkPositionIndexes

public static void checkPositionIndexes(int start,
                                        int end,
                                        int size)

Ensures that start and end specify a valid positions in a list of size size, and are in order. A position index may range from zero to size, inclusive.

checkCriticalPositionIndexes

public static void checkCriticalPositionIndexes(int start,
                                                int end,
                                                int size)

Ensures that start and end specify a valid positions in a list of size size, and are in order. A position index may range from zero to size, inclusive.

checkCriticalArrayBounds

public static void checkCriticalArrayBounds(int start,
                                            int end,
                                            int length)

Checks that array bounds are correct.

Throws:

IllegalArgumentException - if start > end

ArrayIndexOutOfBoundsException - if the range is not legal

checkCriticalStringBounds

public static void checkCriticalStringBounds(int start,
                                             int end,
                                             int length)

Checks that string bounds are correct.

Throws:

StringIndexOutOfBoundsException - if the range is not legal