com.facetmap
Interface Selection

All Known Implementing Classes:

SelectionData, SqlSelection

public interface Selection

Encapsulates the available navigation options as well as the current result set of Resources. A Selection is similar to a category that resources fit into -- except that, because it's a permutation of multiple Headings, it's not generally predefined as a category.

By using the forward and backward navigation logic contained in its Headings, the Selection can generate new Selections as browsing suggestions for the user.

It is possible that the Selection will provide a Heading that is not identical to the Heading provided by the source FacetSpace. That is, if

 Selection selection;
 Heading A = selection.getHeading[0];
 Heading B = selection.getFacetmap().getFacetSpace().getFacet(0).getHeading(A.getId());
 

then it is possible for A not to be the same object as, or an object that equals, B. The Selection should deliver the data that was in the original Heading, unless, say, compilation has erased certain superficial data. More significantly, the Selection may add extra data.

The reigning example of this is: if A is the root heading of a SpectrumFacet, and the root heading did not specify a minimum and maximum, the Selection may set the minimum and maximum according to the headings actually set on the resources in the ResourceSpace. This is clearly a useful trick that requires the Facetmap's interplay between FacetSpace and ResourceSpace, and other such tricks may prove useful too, so we allow it.

The Facetmap v1 methods Selection.getContainedResources() and Selection.getMatchedResources() (and a few similar methods) have been removed entirely -- they don't fit in the v2 API. getContainedResources() is now Selection's default behavior, and you can force the behavior of getMatchedResources() by setting property com.facetmap.Selection.omitForwardMatches during your call to Facetmap.getSelection() .

Method Summary

java.util.Iterator	getBackwardSelections(Facet facet) An Enumeration of the Selections that represent "backtracking" in navigation along the given dimension of facetspace.
java.util.Iterator	getBackwardSelections(int index) An array-oriented version of getHeadings(Facet) .
int	getFacetCount()
Facetmap	getFacetmap()
java.util.Iterator	getForwardSelections(Facet facet) An Enumeration of the Selections that are the possible "next steps" in navigation along the given dimension of facetspace.
java.util.Iterator	getForwardSelections(int index) An array-oriented version of getHeadings(Facet) .
Heading[]	getHeadings(Facet facet) Returns the Heading(s) of this selection in a specified facet.
Heading[]	getHeadings(int index) An array-oriented version of getHeadings(Facet) .
java.util.Properties	getProperties() The properties that were used in the creation of this Selection.
java.lang.String	getRef() Returns a String ID (known as a reference or "ref") that uniquely identifies the Headings used to construct this Selection.
int	getResourceCount() The number of Resources specified by the Headings in this Selection (regardless of any maximum specified by property com.facetmap.Selection.resultLimit).
SelectedResourceIterator	getResources() Return an Iterator containing all Resources specified by this Selection, or the first N Resources specified by this Selection where N is the value of com.facetmap.Selection.resultLimit .
boolean	isMasterRoot() Returns true if each of this Selection's Headings is the root Heading of its Facet.

Method Detail

getFacetmap

Facetmap getFacetmap()

getFacetCount

int getFacetCount()

isMasterRoot

boolean isMasterRoot()

Returns true if each of this Selection's Headings is the root Heading of its Facet.

See Also:

Facet.getRootHeading()

getRef

java.lang.String getRef()

Returns a String ID (known as a reference or "ref") that uniquely identifies the Headings used to construct this Selection. Consumers may use this ref string to implement their own serialization.

The reference does not contain information about the Properties used in this selection. If desired, those must be serialized separately.

getHeadings

Heading[] getHeadings(int index)
                      throws java.lang.ArrayIndexOutOfBoundsException

An array-oriented version of getHeadings(Facet) . Provide the ordinal index number of the Facet within the FacetSpace, instead of the Facet itself.

Throws:

java.lang.ArrayIndexOutOfBoundsException

getHeadings

Heading[] getHeadings(Facet facet)
                      throws java.lang.ArrayIndexOutOfBoundsException

Returns the Heading(s) of this selection in a specified facet. The returned array always contains at least one Heading -- if no Heading from the specified facet was used to create this Selection, then the root Heading is returned. In other words, it's always safe to reference getHeading(facet)[0] as a non-null Heading.

Note that the return value, because it is an array, can be modified. However, modifying it does not change the state of this underlying Selection. Implementors of Selection should take care that this rule is enforced.

Throws:

java.lang.ArrayIndexOutOfBoundsException

getProperties

java.util.Properties getProperties()

The properties that were used in the creation of this Selection. This set of properties can be different from the set that was specified in Facetmap.getSelection() because the facetmap may not recognize or honor all properties; see that method for details.

See Also:

Facetmap.getSelection(Heading[], Properties)

getResources

SelectedResourceIterator getResources()
                                      throws InternalException

Return an Iterator containing all Resources specified by this Selection, or the first N Resources specified by this Selection where N is the value of com.facetmap.Selection.resultLimit .

Throws:

InternalException

getResourceCount

int getResourceCount()
                     throws InternalException

The number of Resources specified by the Headings in this Selection (regardless of any maximum specified by property com.facetmap.Selection.resultLimit).

This could be regarded as just a special case of getResourceWeight() , but of course it's by far the most common and we want a method that returns an int.

Throws:

InternalException

getForwardSelections

java.util.Iterator getForwardSelections(Facet facet)
                                        throws InternalException,
                                               java.lang.ArrayIndexOutOfBoundsException

An Enumeration of the Selections that are the possible "next steps" in navigation along the given dimension of facetspace.

If property com.facetmap.Selection.autoSelectOnlyChild is set true, then this method may not return exactly one Selection (an "only child"). If it would ordinarily return an only child, it must return the forward selections of that child (and act recursively until the size of the result set is not one).

If property com.facetmap.Selection.showEmptySelections is set true, this method will return all possible forward Selections in the Facet, even those that contain no resources (as defined by getContainedResources). Otherwise, Selections with no contained resources must not appear in the result.

Throws:

InternalException

java.lang.ArrayIndexOutOfBoundsException

getForwardSelections

java.util.Iterator getForwardSelections(int index)
                                        throws InternalException,
                                               java.lang.ArrayIndexOutOfBoundsException

An array-oriented version of getHeadings(Facet) . Provide the ordinal index number of the Facet within the FacetSpace, instead of the Facet itself.

Throws:

InternalException

java.lang.ArrayIndexOutOfBoundsException

getBackwardSelections

java.util.Iterator getBackwardSelections(Facet facet)
                                         throws InternalException,
                                                java.lang.ArrayIndexOutOfBoundsException

An Enumeration of the Selections that represent "backtracking" in navigation along the given dimension of facetspace. Exactly what "backtracking" entails is a little dependent on the type of Facet used in this dimension. It is never required that a returned Selection be a Selection already visited by the user; see the notes on directionality in Facet.

Throws:

InternalException

java.lang.ArrayIndexOutOfBoundsException

See Also:

Facet

getBackwardSelections

java.util.Iterator getBackwardSelections(int index)
                                         throws InternalException,
                                                java.lang.ArrayIndexOutOfBoundsException

An array-oriented version of getHeadings(Facet) . Provide the ordinal index number of the Facet within the FacetSpace, instead of the Facet itself.

Throws:

InternalException

java.lang.ArrayIndexOutOfBoundsException