org.apache.river.api.io

Class Valid

java.lang.Object

org.apache.river.api.io.Valid

public class Valid
extends Object

Utilities for validating invariants.

Collections de-serialized by AtomicMarshalInputStream are always safe, that is, they do not call hashCode or equals on elements. These collections are not intended to be used as Collections in object form and must be replaced during construction. Although Comparator's contained in SortedMap's and SortedSet's are serialized, they are not used by any of the following methods. It is generally recommended, although not compulsory, to prefer constructing a Comparator when constructing defensive copies, instead of using the de-serialized Comparator.

Before using a de-serialized Comparator, it should be type checked, to ensure it is suitable for comparison of types of elements contained in a SortedSet or SortedMap.

Since Java 8, HashMap key's and HashSet elements that implement Comparable are provided with improved protection against hash collision DOS.

It is recommended that when using Set's or Map's, that Comparable keys or elements, or a Comparator, be used to avoid hash collisions. Remember to type check all keys, values and elements first, convenience methods have been provided here to ease type checks in Collections.

Note that an attacker may deliberately generate a hash collision to ensure equals is called and try to install the collection in another object that later invokes it. This is why type checking of all elements is so important.

When considering the security of a collection, remember that an attacker may try to obtain a reference to the collection, as such, defensive copies of collections should not be allowed to leak through your API during de-serialization, as your object is accessible via shared references.

Users are cautioned against using Maps and Sets that use hashing functions when keys or elements contained therein are not type specific.

Author:

peter

Constructor Summary

Constructors

Constructor and Description
Valid()

Method Summary

Modifier and Type	Method and Description
static boolean[]	copy(boolean[] arry) Convenience method to create a copy of a boolean array if non null.
static byte[]	copy(byte[] arry) Convenience method to create a copy of a byte array if non null.
static char[]	copy(char[] arry) Convenience method to create a copy of a char array if non null.
static double[]	copy(double[] arry) Convenience method to create a copy of a double array if non null.
static float[]	copy(float[] arry) Convenience method to create a copy of a float array if non null.
static int[]	copy(int[] arry) Convenience method to create a copy of a int array if non null.
static long[]	copy(long[] arry) Convenience method to create a copy of a long array if non null.
static short[]	copy(short[] arry) Convenience method to create a copy of a short array if non null.
static <T> T	copy(T obj) Convenience method to copy Cloneable objects.
static <T> T[]	copy(T[] arry) Convenience method to create a shallow copy of an array if non null.
static <T extends Collection<E>,E> T	copyCol(T source, T destination, Class<E> type) Convenience method to copy and type check all elements from the source collection, into the destination collection.
static <T extends Map<K,V>,K,V> T	copyMap(T source, T destination, Class<K> key, Class<V> val) Convenience method to copy and type check all keys and values from the source map, into the destination map.
static <T extends Map<K,V>,K,V> T	copyMap(T source, T destination, Class<K> key, Class<V> val, int allowableHashCollisions) Convenience method to copy and type check all keys and values from the source map, into the destination map.
static <T extends Set<E>,E> T	copySet(T source, T destination, Class<E> type, int allowableHashCollisions) Convenience method to copy and type check all elements from the source collection, into the destination collection.
static <T> T[]	deepCopy(T[] arry) Convenience method to perform a deep copy of an array containing Cloneable objects
static <T> T	hasClass(Class<T> type, Object o) Checks class of an Object is equal to the Class type and returns it as that type, if true and throws an InvalidObjectException if false.
static <T> T	isInstance(Class<T> type, Object o) Type checks an object is an instance of type and returns it cast as the type if true, otherwise throws an InvalidObjectException.
static <T> T	notNull(T obj, String message) Convenience method to check that an object is non null.
static <T> T[]	nullElement(T[] arry, String message) Checks all elements in an array for null values, if the arry parameter is not null.
static void	throwIOE(Exception cause)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Valid

public Valid()

Method Detail

isInstance

public static <T> T isInstance(Class<T> type,
                               Object o)
                        throws InvalidObjectException

Type checks an object is an instance of type and returns it cast as the type if true, otherwise throws an InvalidObjectException.

Type Parameters:

T - instance type to return.

Parameters:

type - to check instance.

o - Object instance to type check.

Returns:

a type cast instance of o.

Throws:

InvalidObjectException

hasClass

public static <T> T hasClass(Class<T> type,
                             Object o)
                      throws InvalidObjectException

Checks class of an Object is equal to the Class type and returns it as that type, if true and throws an InvalidObjectException if false.

Type Parameters:

T - type cast object as.

Parameters:

type -

o - the Object.

Returns:

the Object cast as type.

Throws:

InvalidObjectException

copyCol

public static <T extends Collection<E>,E> T copyCol(T source,
                                                    T destination,
                                                    Class<E> type)
                                             throws InvalidObjectException

Convenience method to copy and type check all elements from the source collection, into the destination collection. Instances of java.util.Collection will be replaced in the stream by a safe limited functionality immutable Collection instance that must be replaced during deserialization. Do not use this to validate collections that use hashing and do not protect adequately against hash collisions. Since Java 8, HashSet protects against hash collisions, only if elements are Comparable.

Type Parameters:

T - Collection or subtype.

E - Element type.

Parameters:

source - Collection containing unchecked elements.

destination - Empty Collection to populate with checked elements.

type -

Returns:

the populated destination collection, or null if source is null.

Throws:

InvalidObjectException - if invariant checks fail.

NullPointerException - if any parameter, other than source, is null.

copySet

public static <T extends Set<E>,E> T copySet(T source,
                                             T destination,
                                             Class<E> type,
                                             int allowableHashCollisions)
                                      throws InvalidObjectException

Convenience method to copy and type check all elements from the source collection, into the destination collection.

Instances of java.util.Set have been replaced in the stream by a safe limited functionality immutable Set instance that must be replaced during deserialization.

This method checks for hash collisions before populating the destination set.

Type Parameters:

T - Set or subtype.

E - Element type.

Parameters:

source - Collection containing unchecked elements.

destination - Empty Collection to populate with checked elements.

type - Element type.

allowableHashCollisions - number of hash collisions allowed per bucket.

Returns:

the populated destination collection, or null if source is null.

Throws:

InvalidObjectException - if invariant checks fail.

NullPointerException - if any parameter (other than comp or source) is null.

IllegalArgumentException - if allowableHashCollisions is negative.

notNull

public static <T> T notNull(T obj,
                            String message)
                     throws InvalidObjectException

Convenience method to check that an object is non null.

Type Parameters:

T -

Parameters:

obj -

message - reason for exception.

Returns:

obj if non null.

Throws:

InvalidObjectException - with a NullPointerException as its cause.

nullElement

public static <T> T[] nullElement(T[] arry,
                                  String message)
                           throws InvalidObjectException

Checks all elements in an array for null values, if the arry parameter is not null.

Type Parameters:

T -

Parameters:

arry - the array

message - the message for the InvalidObjectException

Returns:

the array or null if arry is null.

Throws:

InvalidObjectException - if array contains null elements.

deepCopy

public static <T> T[] deepCopy(T[] arry)
                        throws CloneNotSupportedException

Convenience method to perform a deep copy of an array containing Cloneable objects

Type Parameters:

T -

Parameters:

arry - - may be null or contain null elements.

Returns:

A deep clone of arry, or null if arry is null.

Throws:

CloneNotSupportedException

copy

public static <T> T[] copy(T[] arry)

Convenience method to create a shallow copy of an array if non null.

Since arrays are mutable, an attacker can retain a reference to a de-serialized array, that allows an attacker to mutate that array.

Type Parameters:

T - type

Parameters:

arry - that will be cloned.

Returns:

A clone of arry, or null if arry is null.

copy

public static byte[] copy(byte[] arry)

Convenience method to create a copy of a byte array if non null.

Since arrays are mutable, an attacker can retain a reference to a de-serialized array, that allows an attacker to mutate that array.

Parameters:

arry - that will be cloned.

Returns:

A clone of arry, or null if arry is null.

copy

public static boolean[] copy(boolean[] arry)

Convenience method to create a copy of a boolean array if non null.

Since arrays are mutable, an attacker can retain a reference to a de-serialized array, that allows an attacker to mutate that array.

Parameters:

arry - that will be cloned.

Returns:

A clone of arry, or null if arry is null.

copy

public static char[] copy(char[] arry)

Convenience method to create a copy of a char array if non null.

Since arrays are mutable, an attacker can retain a reference to a de-serialized array, that allows an attacker to mutate that array.

Parameters:

arry - that will be cloned.

Returns:

A clone of arry, or null if arry is null.

copy

public static short[] copy(short[] arry)

Convenience method to create a copy of a short array if non null.

Since arrays are mutable, an attacker can retain a reference to a de-serialized array, that allows an attacker to mutate that array.

Parameters:

arry - that will be cloned.

Returns:

A clone of arry, or null if arry is null.

copy

public static int[] copy(int[] arry)

Convenience method to create a copy of a int array if non null.

Since arrays are mutable, an attacker can retain a reference to a de-serialized array, that allows an attacker to mutate that array.

Parameters:

arry - that will be cloned.

Returns:

A clone of arry, or null if arry is null.

copy

public static long[] copy(long[] arry)

Convenience method to create a copy of a long array if non null.

Since arrays are mutable, an attacker can retain a reference to a de-serialized array, that allows an attacker to mutate that array.

Parameters:

arry - that will be cloned.

Returns:

A clone of arry, or null if arry is null.

copy

public static double[] copy(double[] arry)

Convenience method to create a copy of a double array if non null.

Since arrays are mutable, an attacker can retain a reference to a de-serialized array, that allows an attacker to mutate that array.

Parameters:

arry - that will be cloned.

Returns:

A clone of arry, or null if arry is null.

copy

public static float[] copy(float[] arry)

Convenience method to create a copy of a float array if non null.

Since arrays are mutable, an attacker can retain a reference to a de-serialized array, that allows an attacker to mutate that array.

Parameters:

arry - that will be cloned.

Returns:

A clone of arry, or null if arry is null.

copy

public static <T> T copy(T obj)
                  throws CloneNotSupportedException

Convenience method to copy Cloneable objects.

Type Parameters:

T -

Parameters:

obj -

Returns:

a clone of obj if non null, otherwise null;

Throws:

CloneNotSupportedException

copyMap

public static <T extends Map<K,V>,K,V> T copyMap(T source,
                                                 T destination,
                                                 Class<K> key,
                                                 Class<V> val)
                                          throws InvalidObjectException

Convenience method to copy and type check all keys and values from the source map, into the destination map.

Note, this shouldn't be used to populate maps that don't have protection against hash collisions. Note that HashMap and ConcurrentHashMap, since Java 8 defend against hash collisions, but only if keys are Comparable.

Type Parameters:

T - Map or subtype.

K - key type.

V - value type.

Parameters:

source - any map containing unchecked keys and values.

destination - a map into which checked values and keys are to be copied.

key - Class of key to type check.

val - Class of value to type check.

Returns:

the populated destination map, or null if source is null.

Throws:

InvalidObjectException - if invariant checks fail.

ClassCastException

NullPointerException - if any parameter other than source is null.

copyMap

public static <T extends Map<K,V>,K,V> T copyMap(T source,
                                                 T destination,
                                                 Class<K> key,
                                                 Class<V> val,
                                                 int allowableHashCollisions)
                                          throws InvalidObjectException

Convenience method to copy and type check all keys and values from the source map, into the destination map. This method checks for hash collisions before populating the destination map.

Type Parameters:

T - Map or subtype.

K - key type.

V - value type.

Parameters:

source - any map containing unchecked keys and values.

destination - a map into which checked values and keys are to be copied.

key - Class of key to type check.

val - Class of value to type check.

allowableHashCollisions - the number of hash collisions allowed per bucket.

Returns:

the populated destination map, or null if source is null.

Throws:

InvalidObjectException - if invariant checks fail.

NullPointerException - if any parameter (other than comp and source) is null.

IllegalArgumentException - if allowableHashCollisions is negative.

throwIOE

public static void throwIOE(Exception cause)
                     throws InvalidObjectException

Throws:

InvalidObjectException