gumbo.util
Interface Group

All Superinterfaces:

java.util.Collection

All Known Implementing Classes:

AbstractGroup

public interface Group

extends java.util.Collection

A collection of members backed by any common collection type (Set, List, SetList) as the group store to achieve ordering and/or uniqueness in the group, as well as efficient group mutation. Includes lightweight support for building lists (if the group store is a List). The identity (equals(), hashCode()) of a group is that of the group store (tries List first, then Set view), with an instanceof test for Group.

Version:

$Revision: 1.3 $

Author:

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

Method Summary

void	add(int index, java.lang.Object member) Similar to List.add(int, Object), but functionally equivalent to Collection.add(Object) if index is <0.
void	addAll(int index, java.util.Collection members) Similar to List.addAll(int, Collection), but functionally equivalent to Collection.addAll(Collection) if index is <0.
boolean	containsAny(java.util.Collection members) Returns true if this group contains any of the specified members.
Group	getGroup() Gets an immutable view of this group.
java.util.List	getList() Gets a singleton immutable view of the group store as a list, which is useful for testing equality with another list.
java.util.Set	getSet() Gets a singleton immutable view of the group store as a set, which is useful for testing equality with another set.

Methods inherited from interface java.util.Collection

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Method Detail

add

public void add(int index,
                java.lang.Object member)

Similar to List.add(int, Object), but functionally equivalent to Collection.add(Object) if index is <0. Can be safely called with index <0 even if the group store is not a List. Some stores (such as SetList) may throw an exception when attempting to add a duplicate member.

Parameters:

index - Index of the added member. If <0 the member is added to the end of the list.

member - The member to be added, which may be null.

Throws:

java.lang.UnsupportedOperationException - The group store is not a List.

addAll

public void addAll(int index,
                   java.util.Collection members)

Similar to List.addAll(int, Collection), but functionally equivalent to Collection.addAll(Collection) if index is <0. Can be safely called with index <0 even if the group store is not a List. Some stores (such as SetList) may throw an exception when attempting to add a duplicate member.

Parameters:

index - Index of the first added member. If <0 the members are added to the end of the list.

members - The members (Object) to be added, which may be null. Never null.

Throws:

java.lang.UnsupportedOperationException - The group store is not a List.

containsAny

public boolean containsAny(java.util.Collection members)

Returns true if this group contains any of the specified members.

Parameters:

members - The members, which may be null. Never null.

Returns:

The result.

getGroup

public Group getGroup()

Gets an immutable view of this group. When possible, use other accessors, such as isEmpty(), instead of this view, which minimizes lazy builds.

Returns:

The view (Object). Never null.

getSet

public java.util.Set getSet()

Gets a singleton immutable view of the group store as a set, which is useful for testing equality with another set. When possible, use other accessors, such as isEmpty(), instead of this view, which minimizes lazy builds.

Returns:

The view (Object). Never null.

Throws:

java.lang.UnsupportedOperationException - The group store is not a Set or viewable as a Set.

getList

public java.util.List getList()

Gets a singleton immutable view of the group store as a list, which is useful for testing equality with another list. If the group store is a SetList, the view will be castable to SetList. When possible, use other accessors, such as isEmpty(), instead of this view, which minimizes lazy builds.

Returns:

The view (Object). Never null.

Throws:

java.lang.UnsupportedOperationException - The group store is not a List or viewable as a List.