org.openide.util
Class Enumerations

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

public final class Enumerations
extends java.lang.Object

Factory methods for various types of Enumeration. Allows composition of existing enumerations, filtering their contents, and/or modifying them. All of this is designed to be done lazily, i.e. elements created on demand.

Since:
4.37
Author:
Jaroslav Tulach
See Also:
NbCollections.checkedEnumerationByFilter(java.util.Enumeration, java.lang.Class, boolean), NbCollections.iterable(Enumeration)

Nested Class Summary
static interface Enumerations.Processor<T,R>
          Processor interface that can filter out objects from the enumeration, change them or add aditional objects to the end of the current enumeration.
 
Method Summary
static
<T> java.util.Enumeration<T>
array(T... arr)
          Returns an enumeration that iterates over provided array.
static
<T> java.util.Enumeration<T>
concat(java.util.Enumeration<? extends java.util.Enumeration<? extends T>> enumOfEnums)
          Concatenates the content of many enumerations.
static
<T> java.util.Enumeration<T>
concat(java.util.Enumeration<? extends T> en1, java.util.Enumeration<? extends T> en2)
          Concatenates the content of two enumerations into one.
static
<T,R> java.util.Enumeration<R>
convert(java.util.Enumeration<? extends T> en, Enumerations.Processor<T,R> processor)
          For each element of the input enumeration en asks the Enumerations.Processor to provide a replacement.
static
<T> java.util.Enumeration<T>
empty()
          An empty enumeration.
static
<T,R> java.util.Enumeration<R>
filter(java.util.Enumeration<? extends T> en, Enumerations.Processor<T,R> filter)
          Filters some elements out from the input enumeration.
static
<T,R> java.util.Enumeration<R>
queue(java.util.Enumeration<? extends T> en, Enumerations.Processor<T,R> filter)
          Support for breadth-first enumerating.
static
<T> java.util.Enumeration<T>
removeDuplicates(java.util.Enumeration<T> en)
          Filters the input enumeration to new one that should contain each of the provided elements just once.
static
<T> java.util.Enumeration<T>
removeNulls(java.util.Enumeration<T> en)
          Removes all nulls from the input enumeration.
static
<T> java.util.Enumeration<T>
singleton(T obj)
          Creates an enumeration with one element.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

empty

public static final <T> java.util.Enumeration<T> empty()
An empty enumeration. Always returns false from empty().hasMoreElements() and throws NoSuchElementException from empty().nextElement().

Returns:
the enumeration

singleton

public static <T> java.util.Enumeration<T> singleton(T obj)
Creates an enumeration with one element.

Parameters:
obj - the element to be present in the enumeration.
Returns:
enumeration

concat

public static <T> java.util.Enumeration<T> concat(java.util.Enumeration<? extends T> en1,
                                                  java.util.Enumeration<? extends T> en2)
Concatenates the content of two enumerations into one. Until the end of en1 is reached its elements are being served. As soon as the en1 has no more elements, the content of en2 is being returned.

Parameters:
en1 - first enumeration
en2 - second enumeration
Returns:
enumeration

concat

public static <T> java.util.Enumeration<T> concat(java.util.Enumeration<? extends java.util.Enumeration<? extends T>> enumOfEnums)
Concatenates the content of many enumerations. The input value is enumeration of Enumeration elements and the result is composed all their content. Each of the provided enumeration is fully read and their content returned before the next enumeration is asked for their elements.

Parameters:
enumOfEnums - Enumeration of Enumeration elements
Returns:
enumeration

removeDuplicates

public static <T> java.util.Enumeration<T> removeDuplicates(java.util.Enumeration<T> en)
Filters the input enumeration to new one that should contain each of the provided elements just once. The elements are compared using their default equals and hashCode methods.

Parameters:
en - enumeration to filter
Returns:
enumeration without duplicated items

array

public static <T> java.util.Enumeration<T> array(T... arr)
Returns an enumeration that iterates over provided array.

Parameters:
arr - the array of object
Returns:
enumeration of those objects

removeNulls

public static <T> java.util.Enumeration<T> removeNulls(java.util.Enumeration<T> en)
Removes all nulls from the input enumeration.

Parameters:
en - enumeration that can contain nulls
Returns:
new enumeration without null values

convert

public static <T,R> java.util.Enumeration<R> convert(java.util.Enumeration<? extends T> en,
                                                     Enumerations.Processor<T,R> processor)
For each element of the input enumeration en asks the Enumerations.Processor to provide a replacement. The toAdd argument of the processor is always null.

Example to convert any objects into strings:

 Processor convertToString = new Processor() {
     public Object process(Object obj, Collection alwaysNull) {
         return obj.toString(); // converts to string
     }
 };
 Enumeration strings = Enumerations.convert(elems, convertToString);
 

Parameters:
en - enumeration of any objects
processor - a callback processor for the elements (its toAdd arguments is always null)
Returns:
new enumeration where all elements has been processed

filter

public static <T,R> java.util.Enumeration<R> filter(java.util.Enumeration<? extends T> en,
                                                    Enumerations.Processor<T,R> filter)
Filters some elements out from the input enumeration. Just make the Enumerations.Processor return null. Please notice the toAdd argument of the processor is always null.

Example to remove all objects that are not strings:

 Processor onlyString = new Processor() {
     public Object process(Object obj, Collection alwaysNull) {
         if (obj instanceof String) {
             return obj;
         } else {
             return null;
         }
     }
 };
 Enumeration strings = Enumerations.filter(elems, onlyString);
 

Parameters:
en - enumeration of any objects
filter - a callback processor for the elements (its toAdd arguments is always null)
Returns:
new enumeration which does not include non-processed (returned null from processor) elements
See Also:
NbCollections.checkedEnumerationByFilter(java.util.Enumeration, java.lang.Class, boolean)

queue

public static <T,R> java.util.Enumeration<R> queue(java.util.Enumeration<? extends T> en,
                                                   Enumerations.Processor<T,R> filter)
Support for breadth-first enumerating. Before any element is returned for the resulting enumeration it is processed in the Enumerations.Processor and the processor is allowed to modify it and also add additional elements at the (current) end of the queue by calling toAdd.add or toAdd.addAll. No other methods can be called on the provided toAdd collection.

Example of doing breadth-first walk through a tree:

 Processor queueSubnodes = new Processor() {
     public Object process(Object obj, Collection toAdd) {
         Node n = (Node)obj;
         toAdd.addAll (n.getChildrenList());
         return n;
     }
 };
 Enumeration strings = Enumerations.queue(elems, queueSubnodes);
 

Parameters:
en - initial content of the resulting enumeration
filter - the processor that is called for each element and can add and addAll elements to its toAdd Collection argument and also change the value to be returned
Returns:
enumeration with the initial and queued content (it can contain null if the filter returned null from its Enumerations.Processor.process(T, java.util.Collection) method.