gumbo.util
Class GumboCollections

java.lang.Object
  |
  +--gumbo.util.GumboCollections

public final class GumboCollections

extends java.lang.Object

Constants and utilities provided by Gumbo that are related to Collections. See StateFlags for additional utilities that can be used with collections in general (such as hasAny(), addedAll(), changedCount()).

Version:

$Revision: 1.8 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Nested Class Summary

static class

GumboCollections.ImmutableCollection Immutable wrapper for a target collection.

Field Summary

static java.util.Collection	EMPTY_COLLECTION A singleton instance of an empty and immutable collection.
static Group	EMPTY_GROUP A singleton instance of an empty and immutable group backed by an empty collection.
static GroupBimap	EMPTY_GROUP_BIMAP A singleton instance of an empty and immutable group bimap.
static java.util.Iterator	EMPTY_ITERATOR A singleton instance of an iterator for an empty and immutable collection.
static java.util.List	EMPTY_LIST A singleton instance of an empty and immutable set.
static Group	EMPTY_LIST_GROUP A singleton instance of an empty and immutable group backed by an empty list.
static java.util.ListIterator	EMPTY_LIST_ITERATOR A singleton instance of a list iterator for an empty and immutable collection.
static java.util.Map	EMPTY_MAP A singleton instance of an empty and immutable map.
static java.util.Set	EMPTY_SET A singleton instance of an empty and immutable set.
static Group	EMPTY_SET_GROUP A singleton instance of an empty and immutable group backed by an empty set.
static SetList	EMPTY_SET_LIST A singleton instance of an empty and immutable listset.
static Group	EMPTY_SET_LIST_GROUP A singleton instance of an empty and immutable group backed by an empty setlist.

Method Summary

static Bimap	immutableBimap(Bimap target) Returns an immutable view of a bimap.
static java.util.Collection	immutableCollection(java.util.Collection target) Returns an immutable view of a collection.
static Group	immutableGroup(Group target) Returns an immutable view of a group.
static GroupBimap	immutableGroupBimap(GroupBimap target) Returns an immutable view of a group bimap.
static java.util.Iterator	immutableIterator(java.util.Iterator target) Returns an iterator that preserves the immutability of its target collection.
static java.util.List	immutableList(java.util.List target) Returns an immutable view of a list.
static java.util.ListIterator	immutableListIterator(java.util.ListIterator target) Returns a list iterator that preserves the immutability of its target collection.
static java.util.Map	immutableMap(java.util.Map target) Returns an immutable view of a map.
static java.util.Set	immutableSet(java.util.Set target) Returns an immutable view of a set.
static SetList	immutableSetList(SetList target) Returns an immutable view of a setlist.
static java.util.Collection	keepUnique(java.util.Set oldObjs, java.util.Collection newObjs) For each new object, checks if it is a member of the old object set.
static void	keepUnique(java.util.Set oldObjs, java.util.Collection newObjs, java.util.Collection retAdded, java.util.Collection retRemoved) For each new object, checks if it is a member of the old object set.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_COLLECTION

public static final java.util.Collection EMPTY_COLLECTION

A singleton instance of an empty and immutable collection. hashCode() and equals() apply to the singleton instance (reference equality). If the collection type (Set, List) is known, the corresponding empty constant should be used instead.

EMPTY_LIST

public static final java.util.List EMPTY_LIST

A singleton instance of an empty and immutable set. Convenience constant that uses Collections.

EMPTY_SET

public static final java.util.Set EMPTY_SET

A singleton instance of an empty and immutable set. Convenience constant that uses Collections.

EMPTY_SET_LIST

public static final SetList EMPTY_SET_LIST

A singleton instance of an empty and immutable listset. hashCode() and equals() forward to an empty list, consistent with the contract for SetList.

EMPTY_GROUP

public static final Group EMPTY_GROUP

A singleton instance of an empty and immutable group backed by an empty collection. As such, this empty group will not test equal to any other group (collections rely on reference equality).

EMPTY_SET_GROUP

public static final Group EMPTY_SET_GROUP

A singleton instance of an empty and immutable group backed by an empty set.

EMPTY_LIST_GROUP

public static final Group EMPTY_LIST_GROUP

A singleton instance of an empty and immutable group backed by an empty list.

EMPTY_SET_LIST_GROUP

public static final Group EMPTY_SET_LIST_GROUP

A singleton instance of an empty and immutable group backed by an empty setlist.

EMPTY_MAP

public static final java.util.Map EMPTY_MAP

A singleton instance of an empty and immutable map. Convenience constant that uses Collections.

EMPTY_GROUP_BIMAP

public static final GroupBimap EMPTY_GROUP_BIMAP

A singleton instance of an empty and immutable group bimap.

EMPTY_ITERATOR

public static final java.util.Iterator EMPTY_ITERATOR

A singleton instance of an iterator for an empty and immutable collection. hashCode() and equals() apply to the singleton instance.

EMPTY_LIST_ITERATOR

public static final java.util.ListIterator EMPTY_LIST_ITERATOR

A singleton instance of a list iterator for an empty and immutable collection. hashCode() and equals() apply to the singleton instance.

Method Detail

keepUnique

public static java.util.Collection keepUnique(java.util.Set oldObjs,
                                              java.util.Collection newObjs)

For each new object, checks if it is a member of the old object set. If not, the new object is added to the old object set; otherwise, the duplicate object is removed from the new object collection.

Parameters:

oldObjs - Old objects (Object), which may be modified. Never null.

newObjs - New objects (Object), which may be modified. Never null.

Returns:

Reference to newObjs. Never null.

keepUnique

public static void keepUnique(java.util.Set oldObjs,
                              java.util.Collection newObjs,
                              java.util.Collection retAdded,
                              java.util.Collection retRemoved)

For each new object, checks if it is a member of the old object set. If a new object is old, the new object is added to the "removed" result. If a new object is new, the new object is added to the old object set and to the "added" result.

Parameters:

oldObjs - Old objects (Object), which may be modified. Never null.

newObjs - New objects (Object). Never null.

retAdded - Return value object. Objects (Object) from newObjs that were "added" to oldObjs as being unique. Ignored if null.

retRemoved - Return value object. Objects (Object) from newObjs that were "removed" from newObjs as being duplicates. Ignored if null.

immutableCollection

public static java.util.Collection immutableCollection(java.util.Collection target)

Returns an immutable view of a collection. Identity (equals(), hashCode()) forwards to the target, which is possible because identity is assumed based on contents. Note that Collections.unmodifiableCollection() does not forward to the target.

immutableGroup

public static Group immutableGroup(Group target)

Returns an immutable view of a group. Identity (equals(), hashCode()) forwards to the target.

immutableList

public static java.util.List immutableList(java.util.List target)

Returns an immutable view of a list. Identity (equals(), hashCode()) forwards to the target. Convenience method that forwards to Collections.

immutableSet

public static java.util.Set immutableSet(java.util.Set target)

Returns an immutable view of a set. Identity (equals(), hashCode()) forwards to the target. Convenience method that forwards to Collections.

immutableSetList

public static SetList immutableSetList(SetList target)

Returns an immutable view of a setlist. Identity (equals(), hashCode()) forwards to the target.

immutableMap

public static java.util.Map immutableMap(java.util.Map target)

Returns an immutable view of a map. Identity (equals(), hashCode()) forwards to the target. Convenience method that forwards to Collections.

immutableBimap

public static Bimap immutableBimap(Bimap target)

Returns an immutable view of a bimap. Identity (equals(), hashCode()) forwards to the target.

immutableGroupBimap

public static GroupBimap immutableGroupBimap(GroupBimap target)

Returns an immutable view of a group bimap. Identity (equals(), hashCode()) forwards to the target.

immutableIterator

public static java.util.Iterator immutableIterator(java.util.Iterator target)

Returns an iterator that preserves the immutability of its target collection. Identity (equals(), hashCode()) forwards to the target.

immutableListIterator

public static java.util.ListIterator immutableListIterator(java.util.ListIterator target)

Returns a list iterator that preserves the immutability of its target collection. Identity (equals(), hashCode()) forwards to the target.