org.openide.util
Class NbCollections

java.lang.Object
  extended by org.openide.util.NbCollections

public class NbCollections
extends java.lang.Object

Utilities for working with generics.

Note that there is no checkedListByFilter method currently. If constant-time operation is important (e.g. your raw list is large and RandomAccess) you can use checkedListByCopy(java.util.List, java.lang.Class, boolean), assuming you do not need to modify the underlying list. If you are only interested in an iterator anyway, try checkedIteratorByFilter(java.util.Iterator, java.lang.Class, boolean).

Since:
org.openide.util 7.1
Author:
Jesse Glick

Method Summary
static
<E> java.util.Enumeration<E>
checkedEnumerationByFilter(java.util.Enumeration rawEnum, java.lang.Class<E> type, boolean strict)
          Create a typesafe filter of an unchecked enumeration.
static
<E> java.util.Iterator<E>
checkedIteratorByFilter(java.util.Iterator rawIterator, java.lang.Class<E> type, boolean strict)
          Create a typesafe filter of an unchecked iterator.
static
<E> java.util.List<E>
checkedListByCopy(java.util.List rawList, java.lang.Class<E> type, boolean strict)
          Create a typesafe copy of a raw list.
static
<K,V> java.util.Map<K,V>
checkedMapByCopy(java.util.Map rawMap, java.lang.Class<K> keyType, java.lang.Class<V> valueType, boolean strict)
          Create a typesafe copy of a raw map.
static
<K,V> java.util.Map<K,V>
checkedMapByFilter(java.util.Map rawMap, java.lang.Class<K> keyType, java.lang.Class<V> valueType, boolean strict)
          Create a typesafe view over an underlying raw map.
static
<E> java.util.Set<E>
checkedSetByCopy(java.util.Set rawSet, java.lang.Class<E> type, boolean strict)
          Create a typesafe copy of a raw set.
static
<E> java.util.Set<E>
checkedSetByFilter(java.util.Set rawSet, java.lang.Class<E> type, boolean strict)
          Create a typesafe view over an underlying raw set.
static
<E> java.lang.Iterable<E>
iterable(java.util.Enumeration<E> enumeration)
          Treat an Enumeration as an Iterable so it can be used in an enhanced for-loop.
static
<E> java.lang.Iterable<E>
iterable(java.util.Iterator<E> iterator)
          Treat an Iterator as an Iterable so it can be used in an enhanced for-loop.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

checkedSetByCopy

public static <E> java.util.Set<E> checkedSetByCopy(java.util.Set rawSet,
                                                    java.lang.Class<E> type,
                                                    boolean strict)
                                         throws java.lang.ClassCastException
Create a typesafe copy of a raw set.

Parameters:
rawSet - an unchecked set
type - the desired supertype of the entries
strict - true to throw a ClassCastException if the raw set has an invalid entry, false to skip over such entries (warnings may be logged)
Returns:
a typed set guaranteed to contain only entries assignable to the named type (or they may be null)
Throws:
java.lang.ClassCastException - if some entry in the raw set was not well-typed, and only if strict was true

checkedListByCopy

public static <E> java.util.List<E> checkedListByCopy(java.util.List rawList,
                                                      java.lang.Class<E> type,
                                                      boolean strict)
                                           throws java.lang.ClassCastException
Create a typesafe copy of a raw list.

Parameters:
rawList - an unchecked list
type - the desired supertype of the entries
strict - true to throw a ClassCastException if the raw list has an invalid entry, false to skip over such entries (warnings may be logged)
Returns:
a typed list guaranteed to contain only entries assignable to the named type (or they may be null)
Throws:
java.lang.ClassCastException - if some entry in the raw list was not well-typed, and only if strict was true

checkedMapByCopy

public static <K,V> java.util.Map<K,V> checkedMapByCopy(java.util.Map rawMap,
                                                        java.lang.Class<K> keyType,
                                                        java.lang.Class<V> valueType,
                                                        boolean strict)
                                           throws java.lang.ClassCastException
Create a typesafe copy of a raw map.

Parameters:
rawMap - an unchecked map
keyType - the desired supertype of the keys
valueType - the desired supertype of the values
strict - true to throw a ClassCastException if the raw map has an invalid key or value, false to skip over such map entries (warnings may be logged)
Returns:
a typed map guaranteed to contain only keys and values assignable to the named types (or they may be null)
Throws:
java.lang.ClassCastException - if some key or value in the raw map was not well-typed, and only if strict was true

checkedIteratorByFilter

public static <E> java.util.Iterator<E> checkedIteratorByFilter(java.util.Iterator rawIterator,
                                                                java.lang.Class<E> type,
                                                                boolean strict)
Create a typesafe filter of an unchecked iterator. Iterator.remove() will work if it does in the unchecked iterator.

Parameters:
rawIterator - an unchecked iterator
type - the desired enumeration type
strict - if false, elements which are not null but not assignable to the requested type are omitted; if true, ClassCastException may be thrown from an iterator operation
Returns:
an iterator guaranteed to contain only objects of the requested type (or null)

checkedSetByFilter

public static <E> java.util.Set<E> checkedSetByFilter(java.util.Set rawSet,
                                                      java.lang.Class<E> type,
                                                      boolean strict)
Create a typesafe view over an underlying raw set. Mutations affect the underlying set (this is not a copy). Set.clear() will make the view empty but may not clear the underlying set. You may add elements only of the requested type. Set.contains(java.lang.Object) also performs a type check and will throw ClassCastException for an illegal argument. The view is serializable if the underlying set is.

Parameters:
rawSet - an unchecked set
type - the desired element type
strict - if false, elements in the underlying set which are not null and which are not assignable to the requested type are omitted from the view; if true, a ClassCastException may arise during some set operation
Returns:
a view over the raw set guaranteed to match the specified type

checkedMapByFilter

public static <K,V> java.util.Map<K,V> checkedMapByFilter(java.util.Map rawMap,
                                                          java.lang.Class<K> keyType,
                                                          java.lang.Class<V> valueType,
                                                          boolean strict)
Create a typesafe view over an underlying raw map. Mutations affect the underlying map (this is not a copy). Map.clear() will make the view empty but may not clear the underlying map. You may add entries only of the requested type pair. Map.get(java.lang.Object), Map.containsKey(java.lang.Object), and Map.containsValue(java.lang.Object) also perform a type check and will throw ClassCastException for an illegal argument. The view is serializable if the underlying map is.

Parameters:
rawMap - an unchecked map
keyType - the desired entry key type
valueType - the desired entry value type
strict - if false, entries in the underlying map for which the key is not null but not assignable to the requested key type, and/or the value is not null but not assignable to the requested value type, are omitted from the view; if true, a ClassCastException may arise during some map operation
Returns:
a view over the raw map guaranteed to match the specified type

checkedEnumerationByFilter

public static <E> java.util.Enumeration<E> checkedEnumerationByFilter(java.util.Enumeration rawEnum,
                                                                      java.lang.Class<E> type,
                                                                      boolean strict)
Create a typesafe filter of an unchecked enumeration.

Parameters:
rawEnum - an unchecked enumeration
type - the desired enumeration type
strict - if false, elements which are not null but not assignable to the requested type are omitted; if true, ClassCastException may be thrown from an enumeration operation
Returns:
an enumeration guaranteed to contain only objects of the requested type (or null)

iterable

public static <E> java.lang.Iterable<E> iterable(java.util.Iterator<E> iterator)
Treat an Iterator as an Iterable so it can be used in an enhanced for-loop. Bear in mind that the iterator is "consumed" by the loop and so should be used only once. Generally it is best to put the code which obtains the iterator inside the loop header.

Example of correct usage:

 String text = ...;
 for (String token : NbCollections.iterable(new Scanner(text))) {
     // ...
 }
 

Parameters:
iterator - an iterator
Returns:
an iterable wrapper which will traverse the iterator once
Throws:
java.lang.NullPointerException - if the iterator is null
Since:
org.openide.util 7.5
See Also:
Java bug #6312085, Java bug #6360734, Java bug #4988624

iterable

public static <E> java.lang.Iterable<E> iterable(java.util.Enumeration<E> enumeration)
Treat an Enumeration as an Iterable so it can be used in an enhanced for-loop. Bear in mind that the enumeration is "consumed" by the loop and so should be used only once. Generally it is best to put the code which obtains the enumeration inside the loop header.

Example of correct usage:

 ClassLoader loader = ...;
 String name = ...;
 for (URL resource : NbCollections.iterable(loader.getResources(name))) {
     // ...
 }
 

Parameters:
enumeration - an enumeration
Returns:
an iterable wrapper which will traverse the enumeration once (Iterator.remove() is not supported)
Throws:
java.lang.NullPointerException - if the enumeration is null
Since:
org.openide.util 7.5
See Also:
Java bug #6349852