Module org.apache.sis.util

Package org.apache.sis.util.collection

Class Containers

Object

Static

Containers

public final class Containers
extends Static

Static methods working on Collection or Checked­Container objects. Unless otherwise noted in the javadoc, every collections returned by the methods in this class implement the Checked­Container interface.

Since:

0.3

Method Summary

Modifier and Type	Method	Description
static <E extends Comparable<E>> int	compare(Iterator<E> it1, Iterator<? extends E> it2)	Compares element-by-element the values provided by two iterators, in iteration order.
static <SK, SV, K, V> Map<K,V>	derived­Map(Map<SK,SV> storage, Object­Converter<SK,K> key­Converter, Object­Converter<SV,V> value­Converter)	Returns a map whose keys and values are derived on-the-fly from the given map.
static <S, E> Set<E>	derived­Set(Set<S> storage, Object­Converter<S,E> converter)	Returns a set whose elements are derived on-the-fly from the given set.
static int	hash­Map­Capacity(int count)	Returns the capacity to be given to the Hash­Map constructor for holding the given number of elements.
static boolean	is­Null­Or­Empty(Collection<?> collection)	Returns true if the given collection is either null or empty.
static boolean	is­Null­Or­Empty(Map<?,?> map)	Returns true if the given map is either null or empty.
static <T> T	property(Map<?,?> properties, Object key, Class<T> type)	Returns the value mapped to the given key casted to the given type, or null if the map is null or does not contain a value for the key.
static <E> List<? extends E>	unmodifiable­List(E... array)	Returns an unmodifiable view of the given array.
static <E> List<? extends E>	unmodifiable­List(E[] array, int lower, int upper)	Returns an unmodifiable view of a subregion of the given array.

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Method Details

isNullOrEmpty

public static boolean isNullOrEmpty(Collection<?> collection)

Returns true if the given collection is either null or empty. If this method returns false, then the given collection is guaranteed to be non-null and to contain at least one element.

This is a convenience method for classes implementing the lazy instantiation pattern. In such cases, null collections (i.e. collections not yet instantiated) are typically considered as empty.

Parameters:

collection - the collection to test, or null.

Returns:

true if the given collection is null or empty, or false otherwise.

isNullOrEmpty

public static boolean isNullOrEmpty(Map<?,?> map)

Returns true if the given map is either null or empty. If this method returns false, then the given map is guaranteed to be non-null and to contain at least one element.

This is a convenience method for classes implementing the lazy instantiation pattern. In such cases, null maps (i.e. maps not yet instantiated) are typically considered as empty.

Parameters:

map - the map to test, or null.

Returns:

true if the given map is null or empty, or false otherwise.

unmodifiableList

@SafeVarargs
public static <E> List<? extends E> unmodifiableList(E... array)

Returns an unmodifiable view of the given array. A direct reference to the given array is retained (i.e. the array is not cloned). Consequently, the given array shall not be modified after construction if the returned list is intended to be immutable.

The returned list implements the Checked­Container interface. The value returned by its Checked­Container.get­Element­Type() method is inferred from the array component type. Because arrays in the Java language are covariant (at the contrary of collections), the list type have to be <? extends E> instead of <E>.

Type Parameters:

E - the base type of elements in the list.

Parameters:

array - the array to wrap, or null if none.

Returns:

the given array wrapped in an unmodifiable list, or null if the given array was null.

See Also:

• Arrays.as­List(Object[])

unmodifiableList

public static <E> List<? extends E> unmodifiableList(E[] array,
 int lower,
 int upper)

Returns an unmodifiable view of a subregion of the given array. A direct reference to the given array is retained (i.e. the array is not cloned). Consequently, the specified sub-region of the given array shall not be modified after construction if the returned list is intended to be immutable.

The returned list implements the Checked­Container interface. The value returned by its Checked­Container.get­Element­Type() method is inferred from the array component type. Because arrays in the Java language are covariant (at the contrary of collections), the list type have to be <? extends E> instead of <E>.

Type Parameters:

E - the type of elements in the list.

Parameters:

array - the array to wrap (cannot be null).

lower - low endpoint (inclusive) of the sublist.

upper - high endpoint (exclusive) of the sublist.

Returns:

the given array wrapped in an unmodifiable list.

Throws:

Index­Out­Of­Bounds­Exception - if the lower or upper value are out of bounds.

derivedSet

public static <S,
E> Set<E> derivedSet(Set<S> storage,
 ObjectConverter<S,E> converter)

Returns a set whose elements are derived on-the-fly from the given set. Conversions from the original elements to the derived elements are performed when needed by invoking the Object­Converter.apply(Object) method on the given converter. Those conversions are repeated every time a Set method is invoked; there is no cache. Consequently, any change in the original set is immediately visible in the derived set, and conversely.

The Set.add(E) method is supported only if the given converter is invertible. An invertible converter is not mandatory for other Set operations. However, contains and remove operations are likely to be faster if the inverse converter is available.

The derived set may contain fewer elements than the original set if some elements are not convertible. Non-convertible elements are S values for which converter.apply(S) returns null. As a consequence of this sentinel value usage, the derived set cannot contain null elements.

The returned set can be serialized if the given set and converter are serializable. The returned set is not synchronized by itself, but is nevertheless thread-safe if the given set (including its iterator) and converter are thread-safe.

Type Parameters:

S - the type of elements in the storage (original) set.

E - the type of elements in the derived set.

Parameters:

storage - the storage set containing the original elements, or null.

converter - the converter from the elements in the storage set to the elements in the derived set.

Returns:

a view over the storage set containing all elements converted by the given converter, or null if storage was null.

See Also:

• Object­Converters.derived­Set(Set, Object­Converter)

derivedMap

public static <SK,
SV,
K,
V> Map<K,V> derivedMap(Map<SK,SV> storage,
 ObjectConverter<SK,K> keyConverter,
 ObjectConverter<SV,V> valueConverter)

Returns a map whose keys and values are derived on-the-fly from the given map. Conversions from the original entries to the derived entries are performed when needed by invoking the Object­Converter.apply(Object) method on the given converters. Those conversions are repeated every time a Map method is invoked; there is no cache. Consequently, any change in the original map is immediately visible in the derived map, and conversely.

The Map.put(K,V) method is supported only if the given converters are invertible. An invertible converter is not mandatory for other Map operations like Map.get(Object), but some of them may be faster if the inverse converters are available.

The derived map may contain fewer entries than the original map if some keys are not convertible. A key K is non-convertible if key­Converter.apply(K) returns null. As a consequence of this sentinel key usage, the derived map cannot contain null keys. It may contain null values however.

The returned map can be serialized if the given map and converters are serializable. The returned map is not thread-safe.

The returned map does not implement the Checked­Container interface since Map is not a Collection sub-type, but the derived map key set and entry set do.

Type Parameters:

SK - the type of keys in the storage map.

SV - the type of values in the storage map.

K - the type of keys in the derived map.

V - the type of values in the derived map.

Parameters:

storage - the storage map containing the original entries, or null.

key­Converter - the converter from the keys in the storage map to the keys in the derived map.

value­Converter - the converter from the values in the storage map to the values in the derived map.

Returns:

a view over the storage map containing all entries converted by the given converters, or null if storage was null.

See Also:

• Object­Converters.derived­Map(Map, Object­Converter, Object­Converter)
• Object­Converters.derived­Keys(Map, Object­Converter, Class)
• Object­Converters.derived­Values(Map, Class, Object­Converter)

property

public static <T> T property(Map<?,?> properties,
 Object key,
 Class<T> type)
                      throws IllegalArgumentException

Returns the value mapped to the given key casted to the given type, or null if the map is null or does not contain a value for the key. If the mapped value is non-null but cannot be casted to the given type, then this method throws an Illegal­Argument­Exception with a message of the form "Property ‘key’ does not accept instances of ‘value.class’.".

This is a helper method for processing a Map argument containing property values of various kinds, as in the Abstract­Identified­Object constructor.

Type Parameters:

T - the compile-time value of the type argument.

Parameters:

properties - the map of properties from which to get a value, or null if none.

key - the key of the property value to return. Can be null if the map supports null key.

type - the expected type of the property value. Cannot be null.

Returns:

the property value for the given key casted to the given type, or null if none.

Throws:

Illegal­Argument­Exception - if a non-null property value exists for the given key but can not be casted to the given type.

See Also:

• Argument­Checks.ensure­Can­Cast(String, Class, Object)

hashMapCapacity

public static int hashMapCapacity(int count)

Returns the capacity to be given to the Hash­Map constructor for holding the given number of elements. This method computes the capacity for the default load factor, which is 0.75.

The same calculation can be used for Linked­Hash­Map and Hash­Set as well, which are built on top of Hash­Map. However, it is not needed for Identity­Hash­Map.

Parameters:

count - the number of elements to be put into the hash map or hash set.

Returns:

the minimal initial capacity to be given to the hash map constructor.

compare

public static <E extends Comparable<E>> int compare(Iterator<E> it1,
 Iterator<? extends E> it2)

Compares element-by-element the values provided by two iterators, in iteration order. Let o1 be an element from the first iterator and o2 the element at the same position from the second iterator. This method returns the result of the first o1.compare­To(o2) call which returned a value different than zero. If all o1.compare­To(o2) calls returned zero, then this method returns -1 if it1 iteration finished before it2, +1 if it2 iteration finished before it1, or 0 if both iterators finished at the same time.

Iterators may return null elements. Null elements are considered "after" any non-null element.

Type Parameters:

E - the type of elements returned by the iterators.

Parameters:

it1 - the first iterator (cannot be null).

it2 - the second iterator (cannot be null).

Returns:

-1 if the content given by the first iterator is considered "before" the content given by the second iterator, +1 if considered "after", or 0 if considered equal.

Since:

1.0