edu.iu.iv.modeling.tarl.util.impl
Class ExtendedHashSet

java.lang.Object
  |
  +--java.util.AbstractCollection
        |
        +--java.util.AbstractSet
              |
              +--java.util.HashSet
                    |
                    +--edu.iu.iv.modeling.tarl.util.impl.ExtendedHashSet

All Implemented Interfaces:

java.lang.Cloneable, java.util.Collection, java.io.Serializable, java.util.Set

public class ExtendedHashSet

extends java.util.HashSet

implements java.util.Set

This class defines an extended form of the HashSet - available via the Java Collections Framework. This class adds a few utility methods in order to make the Set more useful to use. Some of the utility methods are :

• Retrieve a random element from the Set
• Retrieve n different random elements from the Set
• Define Set Union
• Define Subset operation
• Define equals operation

Author:

Jeegar T Maru

See Also:

HashSet, Serialized Form

Constructor Summary

ExtendedHashSet()
Creates a new instance of ExtendedHashSet such that it is empty

ExtendedHashSet(java.util.Collection collection)
Creates a new instance of ExtendedHashSet such that it contains a specified Collection

ExtendedHashSet(int initialCapacity)
Creates a new instance of an empty ExtendedHashSet with the specified initial capacity

ExtendedHashSet(int initialCapacity, float loadFactor)
Creates a new instance of an empty ExtendedHashSet with the specified initial capacity and load factor

Method Summary

static boolean	areSetEqual(java.util.Collection collection1, java.util.Collection collection2) Tests whether the two Collections are equal or not in terms of Set Equality.
void	difference(java.util.Collection collection) Modifies the Set to be the difference of the current Set and the specified Collection.
static ExtendedHashSet	difference(java.util.Collection collection1, java.util.Collection collection2) Returns the difference of the two specified Collections.
java.lang.Object	getRandomElement() Returns a Random element from the Set.
ExtendedHashSet	getRandomElements(int numElements) Returns the specified number of different random elements from the Set as an ExtendedHashSet.
void	intersection(java.util.Collection collection) Modifies the Set to be the intersection of the Set and the specified Collection.
static ExtendedHashSet	intersection(java.util.Collection collection1, java.util.Collection collection2) Returns the intersection of two specified Collections.
static boolean	isSubset(java.util.Collection collection1, java.util.Collection collection2) Tests whether the Collection specified by the second argument is a subset of the Collection specified by the first argument
static ExtendedHashSet	partitionSet(java.util.Collection collection, int numElements) Partitions the specified Collection into a Collection of subsets each of a fixed specified size.
void	union(java.util.Collection collection) Modifies the Set to be the union of itself and the specified Collection.
static ExtendedHashSet	union(java.util.Collection collection1, java.util.Collection collection2) Returns the union of two specified Collections as an ExtendedHashSet.

Methods inherited from class java.util.HashSet

add, clear, clone, contains, isEmpty, iterator, remove, size

Methods inherited from class java.util.AbstractSet

equals, hashCode, removeAll

Methods inherited from class java.util.AbstractCollection

addAll, containsAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Set

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

Constructor Detail

ExtendedHashSet

public ExtendedHashSet()

Creates a new instance of ExtendedHashSet such that it is empty

ExtendedHashSet

public ExtendedHashSet(java.util.Collection collection)
                throws java.lang.NullPointerException

Creates a new instance of ExtendedHashSet such that it contains a specified Collection

Parameters:

collection - Specifies the collection to initialize the extended hash set with

Throws:

java.lang.NullPointerException - if the specified collection is null

ExtendedHashSet

public ExtendedHashSet(int initialCapacity)

Creates a new instance of an empty ExtendedHashSet with the specified initial capacity

Parameters:

initialCapacity - Specifies the initial capacity for the extended hash set

ExtendedHashSet

public ExtendedHashSet(int initialCapacity,
                       float loadFactor)

Creates a new instance of an empty ExtendedHashSet with the specified initial capacity and load factor

Parameters:

initialCapacity - Specifies the initial capacity for the extended hash set

loadFactor - Specifies the load factor for the extended hash set

Method Detail

getRandomElement

public java.lang.Object getRandomElement()

Returns a Random element from the Set. Returns null if the Set if empty.

Returns:

a random element in the set

getRandomElements

public ExtendedHashSet getRandomElements(int numElements)

Returns the specified number of different random elements from the Set as an ExtendedHashSet. If the specified number is larger than the size of the Set, the entire Set is returned.

Parameters:

numElements - Specifies the number of elements required

Returns:

the Set of different random elements

union

public void union(java.util.Collection collection)
           throws java.lang.NullPointerException

Modifies the Set to be the union of itself and the specified Collection. It acts like the operation (a = a union b), where a is the current Set and b is the specified Collection

Parameters:

collection - Specifies the collection to be unioned with

Throws:

java.lang.NullPointerException - if the specified collection is null

union

public static ExtendedHashSet union(java.util.Collection collection1,
                                    java.util.Collection collection2)
                             throws java.lang.NullPointerException

Returns the union of two specified Collections as an ExtendedHashSet. Does not change any of the Collections.

Parameters:

collection1 - Specifies the first collection

collection2 - Specifies the second collection

Returns:

the extended hash set containing the union

Throws:

java.lang.NullPointerException - if any of the specified collection is null

intersection

public void intersection(java.util.Collection collection)
                  throws java.lang.NullPointerException

Modifies the Set to be the intersection of the Set and the specified Collection. It acts like the operation (a = a intersection b), where a is the current Set and b is the specified Collection

Parameters:

collection - Specifies the collection to be intersected with

Throws:

java.lang.NullPointerException - if the specified collection is null

intersection

public static ExtendedHashSet intersection(java.util.Collection collection1,
                                           java.util.Collection collection2)
                                    throws java.lang.NullPointerException

Returns the intersection of two specified Collections. Does not change any of the Collections.

Parameters:

collection1 - Specifies the first collection

collection2 - Specifies the second collection

Returns:

the extended hash set containing the intersection

Throws:

java.lang.NullPointerException - if any of the specified collection is null

difference

public void difference(java.util.Collection collection)
                throws java.lang.NullPointerException

Modifies the Set to be the difference of the current Set and the specified Collection. It acts like the operation (a = a - b), where a is the current Set and b is the specified Collection

Parameters:

collection - Specifies the Collection to be intersected with

Throws:

java.lang.NullPointerException - if the specified collection is null

difference

public static ExtendedHashSet difference(java.util.Collection collection1,
                                         java.util.Collection collection2)
                                  throws java.lang.NullPointerException

Returns the difference of the two specified Collections. Does not change any of the Collections. The operation can be expressed as (a - b), where a and b are the collections as defined by the first and second argument respectively.

Parameters:

collection1 - Specifies the first Collection

collection2 - Specifies the second Collection

Returns:

the extended hash set containing the difference

Throws:

java.lang.NullPointerException - if the specified collection is null

isSubset

public static boolean isSubset(java.util.Collection collection1,
                               java.util.Collection collection2)
                        throws java.lang.NullPointerException

Tests whether the Collection specified by the second argument is a subset of the Collection specified by the first argument

Parameters:

collection1 - Specifies the first colletion

collection2 - Specifies the second colletion

Returns:

true, if collection2 is a subset of collection1

Throws:

java.lang.NullPointerException - if the specified collection is null

areSetEqual

public static boolean areSetEqual(java.util.Collection collection1,
                                  java.util.Collection collection2)
                           throws java.lang.NullPointerException

Tests whether the two Collections are equal or not in terms of Set Equality. Two collections are Set Equal if first is the subset of the second and the second is a subset of the first.

Parameters:

collection1 - Specifies the first collection

collection2 - Specifies the second collection

Returns:

true, if the two collections are set equal

Throws:

java.lang.NullPointerException - if any of the specified collections is null

partitionSet

public static ExtendedHashSet partitionSet(java.util.Collection collection,
                                           int numElements)
                                    throws java.lang.NullPointerException,
                                           java.lang.IllegalArgumentException

Partitions the specified Collection into a Collection of subsets each of a fixed specified size. The elements for the subsets are chosen randomly. The subsets are mutually exclusive and exhaustive over the entire Set. Each of the subsets do not contain duplicate elements (as given by the equals method). Just one subset may have less number of elements than the number specified if the total number of elements is not exactly divisible by the specified number.

Parameters:

collection - the collection to be partitioned

numElements - the number of elements in each subset

Returns:

the collection of the subsets

Throws:

java.lang.NullPointerException - if the collection is null

java.lang.IllegalArgumentException - if the value of numElements is 0 or less