com.facetmap
Interface Facetmap

All Known Implementing Classes:

SimpleFacetmap, SqlFacetmap

public interface Facetmap

The connection from the Resource information to the Facet information, and the new information that emerges when those two domains are combined. Controls browsing in multiple facets simultaneously.

The main job of the Facetmap is to generate Selection objects from a set of selected Headings, in the context of a FacetSpace and a ResourceSpace. The Selection contains data for further browsing and also contains the set of Resources which are classified such that they are contained by the Selection's combination of Headings.

Consumers have some control over how the Selections are generated, via a Properties object passed into the getSelection() methods. Each implementation of Facetmap determines which properties it will recognize, and is free to define its own custom properties. Some common properties are:

• com.facetmap.Selection.resultLimit - maximum number of Resources to return in Selection.getResources
• com.facetmap.Selection.showEmptySelections - whether to return Selections with no Resources in Selection.getForwardSelections()
• com.facetmap.Selection.omitForwardMatches - whether Selection.getResources should only return Resources that exactly match the selected Headings, not their forward Headings [this replaces the distinction in Facetmap v1 between Selection.getContainedResources() and Selection.getMatchedResources() ]

See Also:

getSelection(Heading[], Properties), Selection

Method Summary

FacetSpace	getFacetSpace()
java.lang.String	getInfo() Implementation-specific string for this Facetmap class.
ResourceSpace	getResourceSpace()
Selection	getRootSelection() Produce a root Selection, a starting point for browsing this Facetmap.
Selection	getRootSelection(java.util.Properties properties) Gets the root selection for browsing this Facetmap, subject to special restrictions.
Selection	getSelection(Heading[] headingList) Generate a Selection that contains Resources which match the specified Headings, according to the following logic.
Selection	getSelection(Heading[] headingList, java.util.Properties properties) Get a Selection subject to special restrictions, indicated by the Properties argument.
Selection	getSelection(java.lang.String ref) Get a Selection defined by string ref.
Selection	getSelection(java.lang.String ref, java.util.Properties properties) Get a Selection defined by string ref and subject to special restrictions in properties.
java.lang.String	getTitle() A descriptive title for this Facetmap instance.

Method Detail

getTitle

java.lang.String getTitle()

A descriptive title for this Facetmap instance.

getInfo

java.lang.String getInfo()

Implementation-specific string for this Facetmap class.

getFacetSpace

FacetSpace getFacetSpace()

getResourceSpace

ResourceSpace getResourceSpace()

getSelection

Selection getSelection(Heading[] headingList)
                       throws DataException,
                              InternalException

Generate a Selection that contains Resources which match the specified Headings, according to the following logic.

1. If each Heading is from a different Facet (the usual case, and also the case handled by earlier versions of Facetmap), then each contained Resource is mapped to each Heading (or a forward Heading in the Heading's Facet).

2. If there are multiple Headings from the same Facet, then each contained Resource only needs to be mapped to at least one of the specified Headings (or their forward Headings) from the same Facet.

In essence, Headings from the same Facet are combined with OR, and then Headings from different Facets are combined with AND. This corresponds to the needs of a typical browsing user. e.g.

 Heading a1 = facetmap.getTaxonomy("A").getHeading("a1");
 Heading a2 = facetmap.getTaxonomy("A").getHeading("a2");
 Heading a3 = facetmap.getTaxonomy("A").getHeading("a3");
 Heading b1 = facetmap.getSpectrum("B").getHeading(0,100);
 Heading c1 = facetmap.getKeywordFacet("C").getHeading("foo");
 Selection selection = facetmap.getSelection( new Heading[5] {
   a1,a2,a3,b1,c1
 } );
 .... will produce ....
 a selection that contains all Resources r for which: (
   ( r is classified in facet A under a1 OR a2 OR a3 OR a child of those )
   AND
   ( r is classified in facet B between 0 and 100 )
   AND
   ( r contains keyword "foo" )
 )
 

Throws:

DataException

InternalException

getSelection

Selection getSelection(Heading[] headingList,
                       java.util.Properties properties)
                       throws DataException,
                              InternalException

Get a Selection subject to special restrictions, indicated by the Properties argument. Because it is impossible for all Facetmap implementations to know what properties are used by all other implementations, the Facetmap may silently ignore any property it doesn't recognize.

Throws:

DataException

InternalException

See Also:

getSelection(Heading[])

getSelection

Selection getSelection(java.lang.String ref)
                       throws InternalException,
                              UnknownReferenceException

Get a Selection defined by string ref. The ref string is assumed to have been generated by a Selection from this Facetmap; otherwise unpredictable results can occur.

We expose this method separately in the Facetmap interface because a ref string could potentially contain more than simply a set of Headings (e.g. a facetmap hash code for integrity checking). It is therefore preferred over getSelection(Heading[]) in cases where the desired Selection is based on the previous Selection (but the previous Selection object itself is unavailable). In those cases, you'd be serializing a Selection reference anyway, so the String ref is the natural choice.

Throws:

InternalException

UnknownReferenceException

getSelection

Selection getSelection(java.lang.String ref,
                       java.util.Properties properties)
                       throws InternalException,
                              UnknownReferenceException

Get a Selection defined by string ref and subject to special restrictions in properties. Note that selection properties are not conveyed by the ref string.

Throws:

InternalException

UnknownReferenceException

getRootSelection

Selection getRootSelection()
                           throws InternalException

Produce a root Selection, a starting point for browsing this Facetmap. The returned Selection should have no backward Selections of its own.

Throws:

InternalException

getRootSelection

Selection getRootSelection(java.util.Properties properties)
                           throws InternalException

Gets the root selection for browsing this Facetmap, subject to special restrictions.

Throws:

InternalException

See Also:

getSelection(Heading[], Properties)