org.jamesframework.core.subset

Class SubsetSolution

java.lang.Object

org.jamesframework.core.problems.sol.Solution

org.jamesframework.core.subset.SubsetSolution

public class SubsetSolution
extends Solution

High-level subset solution modeled in terms of IDs of selected items. The subset is sampled from a data set of items which are each required to be identified with a unique integer ID. By default, the IDs are unordered. If desired, they can be ordered according to the natural ordering of integers (ascending) or a custom comparator, by using an appropriate constructor. In the latter case, it is safe to cast the views returned by getSelectedIDs(), getUnselectedIDs() and getAllIDs() to the NavigableSet subtype.

Author:

Herman De Beukelaer

Constructor Summary

Constructors

Constructor and Description
SubsetSolution(Set<Integer> allIDs) Creates a new subset solution given the set of all IDs, each corresponding to an underlying entity, from which a subset is to be selected.
SubsetSolution(Set<Integer> allIDs, boolean naturalOrder) Creates a new subset solution given the set of all IDs, each corresponding to an underlying entity, from which a subset is to be selected.
SubsetSolution(Set<Integer> allIDs, Comparator<Integer> orderOfIDs) Creates a new subset solution given the set of all IDs, each corresponding to an underlying entity, from which a subset is to be selected.
SubsetSolution(Set<Integer> allIDs, Set<Integer> selectedIDs) Creates a new subset solution given the set of all IDs, and the set of currently selected IDs.
SubsetSolution(Set<Integer> allIDs, Set<Integer> selectedIDs, boolean naturalOrder) Creates a new subset solution given the set of all IDs, and the set of currently selected IDs.
SubsetSolution(Set<Integer> allIDs, Set<Integer> selectedIDs, Comparator<Integer> orderOfIDs) Creates a new subset solution given the set of all IDs, and the set of currently selected IDs.
SubsetSolution(SubsetSolution sol) Copy constructor.

Method Summary

Modifier and Type	Method and Description
SubsetSolution	copy() Create a deep copy of this subset solution, obtained through the copy constructor.
boolean	deselect(int ID) Deselect the given ID.
void	deselectAll() Deselect all IDs.
boolean	deselectAll(Collection<Integer> IDs) Deselect all IDs contained in the given collection.
boolean	equals(Object other) Checks whether the given other object represents the same subset solution.
Set<Integer>	getAllIDs() Returns an unmodifiable view of the set of all IDs.
int	getNumSelectedIDs() Get the number of IDs which are currently selected.
int	getNumUnselectedIDs() Get the number of IDs which are currently unselected.
Comparator<Integer>	getOrderOfIDs() Get the comparator according to which the IDs are ordered, as specified at construction.
Set<Integer>	getSelectedIDs() Returns an unmodifiable view of the set of currently selected IDs.
int	getTotalNumIDs() Get the total number of IDs.
Set<Integer>	getUnselectedIDs() Returns an unmodifiable view of the set of currently non selected IDs.
int	hashCode() Computes a hash code that is consistent with the implementation of equals(Object) meaning that the same hash code is returned for equal subset solutions.
boolean	select(int ID) Select the given ID.
void	selectAll() Select all IDs.
boolean	selectAll(Collection<Integer> IDs) Select all IDs contained in the given collection.
String	toString() Creates a formatted string containing the selected IDs.

Methods inherited from class org.jamesframework.core.problems.sol.Solution

checkedCopy

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SubsetSolution

public SubsetSolution(Set<Integer> allIDs)

Creates a new subset solution given the set of all IDs, each corresponding to an underlying entity, from which a subset is to be selected. Initially, no IDs are selected. Note: IDs are copied to the internal data structures of the subset solution; no reference is stored to the set given at construction. IDs are stored in unordered sets.

Parameters:

allIDs - set of all IDs from which a subset is to be selected

Throws:

NullPointerException - if allIDs is null or contains any null elements

IllegalArgumentException - if allIDs is empty

SubsetSolution

public SubsetSolution(Set<Integer> allIDs,
                      Set<Integer> selectedIDs)

Creates a new subset solution given the set of all IDs, and the set of currently selected IDs. Note: IDs are copied to the internal data structures of the subset solution; no reference is stored to the sets given at construction. IDs are stored in unordered sets.

Parameters:

allIDs - set of all IDs from which a subset is to be selected

selectedIDs - set of currently selected IDs (subset of all IDs)

Throws:

NullPointerException - if allIDs or selectedIDs are null or contain any null elements

IllegalArgumentException - if allIDs is empty or selectedIDs is not a subset of allIDs

SubsetSolution

public SubsetSolution(Set<Integer> allIDs,
                      boolean naturalOrder)

Creates a new subset solution given the set of all IDs, each corresponding to an underlying entity, from which a subset is to be selected. Initially, no IDs are selected. Note: IDs are copied to the internal data structures of the subset solution; no reference is stored to the set given at construction. If naturalOrder is true, the sets of selected, unselected and all IDs are represented as navigable sorted sets ordered according to the natural ordering of integers (ascending); else, no ordering is imposed.

Parameters:

allIDs - set of all IDs from which a subset is to be selected

naturalOrder - if naturalOrder is true, IDs will be ordered according to their natural ordering; else, no ordering is imposed on the IDs

Throws:

NullPointerException - if allIDs is null or contains any null elements

IllegalArgumentException - if allIDs is empty

SubsetSolution

public SubsetSolution(Set<Integer> allIDs,
                      Set<Integer> selectedIDs,
                      boolean naturalOrder)

Creates a new subset solution given the set of all IDs, and the set of currently selected IDs. Note: IDs are copied to the internal data structures of the subset solution; no reference is stored to the sets given at construction. If naturalOrder is true, the sets of selected, unselected and all IDs are represented as navigable sorted sets ordered according to the natural ordering of integers (ascending); else, no ordering is imposed.

Parameters:

allIDs - set of all IDs from which a subset is to be selected

selectedIDs - set of currently selected IDs (subset of all IDs)

naturalOrder - if naturalOrder is true, IDs will be ordered according to their natural ordering; else, no ordering is imposed on the IDs

Throws:

NullPointerException - if allIDs or selectedIDs are null or contain any null elements

IllegalArgumentException - if allIDs is empty or selectedIDs is not a subset of allIDs

SubsetSolution

public SubsetSolution(Set<Integer> allIDs,
                      Comparator<Integer> orderOfIDs)

Creates a new subset solution given the set of all IDs, each corresponding to an underlying entity, from which a subset is to be selected. Initially, no IDs are selected. Note: IDs are copied to the internal data structures of the subset solution; no reference is stored to the set given at construction. If orderOfIDs is not null, the sets of selected, unselected and all IDs are represented as navigable sorted sets ordered according to this comparator; else, no ordering is imposed.

Parameters:

allIDs - set of all IDs from which a subset is to be selected

orderOfIDs - comparator according to which IDs are ordered, allowed to be null in which case no order is imposed

Throws:

NullPointerException - if allIDs is null or contains any null elements

IllegalArgumentException - if allIDs is empty

SubsetSolution

public SubsetSolution(Set<Integer> allIDs,
                      Set<Integer> selectedIDs,
                      Comparator<Integer> orderOfIDs)

Creates a new subset solution given the set of all IDs, and the set of currently selected IDs. Note: IDs are copied to the internal data structures of the subset solution; no reference is stored to the sets given at construction. If orderOfIDs is not null, the sets of selected, unselected and all IDs are represented as navigable sorted sets ordered according to this comparator; else, no ordering is imposed.

Parameters:

allIDs - set of all IDs from which a subset is to be selected

selectedIDs - set of currently selected IDs (subset of all IDs)

orderOfIDs - comparator according to which IDs are ordered, allowed to be null in which case no order is imposed

Throws:

NullPointerException - if allIDs or selectedIDs are null or contain any null elements

IllegalArgumentException - if allIDs is empty or selectedIDs is not a subset of allIDs

SubsetSolution

public SubsetSolution(SubsetSolution sol)

Copy constructor. Creates a new subset solution which is identical to the given solution, but does not have any reference to any data structures contained within the given solution (deep copy). The obtained subset solution will have exactly the same selected/unselected IDs as the given solution, and will impose the same ordering on the IDs (if any).

Parameters:

sol - solution to copy (deep copy)

Method Detail

copy

public SubsetSolution copy()

Create a deep copy of this subset solution, obtained through the copy constructor.

Specified by:

copy in class Solution

Returns:

deep copy of this subset solution

getOrderOfIDs

public Comparator<Integer> getOrderOfIDs()

Get the comparator according to which the IDs are ordered, as specified at construction. May return null which means that no order has been imposed.

Returns:

comparator according to which IDs are ordered, may be null

select

public boolean select(int ID)

Select the given ID. If there is no entity with the given ID, a SolutionModificationException is thrown. If the ID is currently already selected, the subset solution is not modified and false is returned. Finally, true is returned if the ID has been successfully selected.

Parameters:

ID - ID to be selected

Returns:

true if the ID has been successfully selected, false if it was already selected

Throws:

SolutionModificationException - if there is no entity with this ID

deselect

public boolean deselect(int ID)

Deselect the given ID. If there is no entity with the given ID, a SolutionModificationException is thrown. If the ID is currently not selected, the subset solution is not modified and false is returned. Finally, true is returned if the ID has been successfully deselected.

Parameters:

ID - ID to be deselected

Returns:

true if the ID has been successfully deselected, false if it is currently not selected

Throws:

SolutionModificationException - if there is no entity with this ID

selectAll

public boolean selectAll(Collection<Integer> IDs)

Select all IDs contained in the given collection. Returns true if the subset solution was modified by this operation, i.e. if at least one previously unselected ID has been selected.

Parameters:

IDs - collection of IDs to be selected

Returns:

true if the subset solution was modified

Throws:

SolutionModificationException - if the given collection contains at least one ID which does not correspond to an entity

NullPointerException - if null is passed or the given collection contains at least one null element

deselectAll

public boolean deselectAll(Collection<Integer> IDs)

Deselect all IDs contained in the given collection. Returns true if the subset solution was modified by this operation, i.e. if at least one previously selected ID has been deselected.

Parameters:

IDs - collection of IDs to be deselected

Returns:

true if the subset solution was modified

Throws:

SolutionModificationException - if the given collection contains at least one ID which does not correspond to an entity

NullPointerException - if null is passed or the given collection contains at least one null element

selectAll

public void selectAll()

Select all IDs.

deselectAll

public void deselectAll()

Deselect all IDs.

getSelectedIDs

public Set<Integer> getSelectedIDs()

Returns an unmodifiable view of the set of currently selected IDs. Any attempt to modify the returned set will result in an UnsupportedOperationException. If the IDs are ordered (see getOrderOfIDs()), it is safe to cast the returned view to the NavigableSet subtype.

Returns:

unmodifiable view of currently selected IDs

getUnselectedIDs

public Set<Integer> getUnselectedIDs()

Returns an unmodifiable view of the set of currently non selected IDs. Any attempt to modify the returned set will result in an UnsupportedOperationException. If the IDs are ordered (see getOrderOfIDs()), it is safe to cast the returned view to the NavigableSet subtype.

Returns:

unmodifiable view of currently non selected IDs

getAllIDs

public Set<Integer> getAllIDs()

Returns an unmodifiable view of the set of all IDs. Any attempt to modify the returned set will result in an UnsupportedOperationException. If the IDs are ordered (see getOrderOfIDs()), it is safe to cast the returned view to the NavigableSet subtype. This set will always be equal to the union of getSelectedIDs() and getUnselectedIDs().

Returns:

unmodifiable view of all IDs

getNumSelectedIDs

public int getNumSelectedIDs()

Get the number of IDs which are currently selected. Corresponds to the size of the selected subset.

Returns:

number of selected IDs

getNumUnselectedIDs

public int getNumUnselectedIDs()

Get the number of IDs which are currently unselected.

Returns:

number of unselected IDs

getTotalNumIDs

public int getTotalNumIDs()

Get the total number of IDs. The returned number will always be equal to the sum of getNumSelectedIDs() and getNumUnselectedIDs().

Returns:

total number of IDs

equals

public boolean equals(Object other)

Checks whether the given other object represents the same subset solution. Subset solutions are considered equal if and only if they contain exactly the same selected and unselected IDs.

Specified by:

equals in class Solution

Parameters:

other - other object to check for equality

Returns:

true if the other object is also a subset solution and contains exactly the same selected and unselected IDs as this solution

hashCode

public int hashCode()

Computes a hash code that is consistent with the implementation of equals(Object) meaning that the same hash code is returned for equal subset solutions. The computed hash code is a linear combination of the hash codes of both the set of selected and unselected IDs, added to a constant.

Specified by:

hashCode in class Solution

Returns:

hash code of this subset solution

toString

public String toString()

Creates a formatted string containing the selected IDs.

Overrides:

toString in class Object

Returns:

formatted string