com.facetmap.simple
Class SimpleFacetmap

java.lang.Object
  extended by com.facetmap.simple.SimpleFacetmap
All Implemented Interfaces:
Facetmap
Direct Known Subclasses:
SqlFacetmap

public class SimpleFacetmap
extends java.lang.Object
implements Facetmap

SimpleFacetmap stores all facetmap data as internal object state, and provides Facetmap reference implementations which basically query internal state a lot. This makes the class well-suited to representing (and passing around) the data in a Facetmap, and also to doing queries on small facetmaps or prototypes.

It isn't so good for production environments, but it makes a good base class upon which to write higher-performance Facetmap code.


Field Summary
protected  FacetSpace facetSpace
           
static java.lang.String INFO
           
protected  RefCodec refCodec
           
protected  ResourceSpace resourceSpace
           
protected  java.util.Properties selectionProps
           
protected  java.lang.String title
           
 
Constructor Summary
protected SimpleFacetmap()
           
  SimpleFacetmap(java.lang.String title, ResourceSpace resourceSpace)
          Quick construction of SimpleFacetmap.
  SimpleFacetmap(java.lang.String title, ResourceSpace resourceSpace, java.util.Properties defaultSelectionProperties)
          Quick construction of SimpleFacetmap.
 
Method Summary
 void applyHeadingsToSelection(SelectionData selection, Heading[] headings)
           
 void applyHeadingsToSelection(SelectionData selection, java.util.Set[] headingSets)
           
 void applyPropertiesToSelection(SelectionData selection, java.util.Properties props)
           
static boolean booleanProperty(java.util.Properties props, java.lang.String propKey)
          The boolean returned represents the value true if the property value is not null and is equal, ignoring case, to the string "true".
 void defineBackwardSelections(SelectionData selectionData, int facetIndex)
          Creates all backward selections in a single facet, and sets their headings, but no other information (e.g.
 void defineForwardSelections(SelectionData selectionData, int facetIndex)
          Creates all forward selections in a single facet, and sets their headings, but no other information (e.g.
 Heading getCommonAncestor(java.util.Collection headings)
          Returns the heading that is the closest (most specific) ancestor of all the input headings.
 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 props)
          Caches root selection for the life of the SimpleFacetmap object, which underscores the intended immutability of SimpleFacetmap.
 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 props)
          This is the basic getSelection call.
 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.util.Properties getSelectionProps()
           
 java.lang.String getTitle()
          A descriptive title for this Facetmap instance.
 boolean headingIsAncestorOfHeading(Heading ancestor, Heading child)
           
static int intProperty(java.util.Properties props, java.lang.String propKey, int defaultValue)
           
 boolean isSelectedInFacet(Heading heading, SelectionData selection, java.util.Set subselections)
          Determines whether the Heading is selected (either matched or contained) in the specified Selection.
 void removeEmptySelections(SelectionData selection)
           
 void setResourceSpace(ResourceSpace resourceSpace)
           
 void setSelectionProps(java.util.Properties selectionProps)
           
 void setTitle(java.lang.String title)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

INFO

public static java.lang.String INFO

title

protected java.lang.String title

facetSpace

protected FacetSpace facetSpace

resourceSpace

protected ResourceSpace resourceSpace

selectionProps

protected java.util.Properties selectionProps

refCodec

protected RefCodec refCodec
Constructor Detail

SimpleFacetmap

protected SimpleFacetmap()

SimpleFacetmap

public SimpleFacetmap(java.lang.String title,
                      ResourceSpace resourceSpace,
                      java.util.Properties defaultSelectionProperties)
Quick construction of SimpleFacetmap.


SimpleFacetmap

public SimpleFacetmap(java.lang.String title,
                      ResourceSpace resourceSpace)
Quick construction of SimpleFacetmap.

Method Detail

applyHeadingsToSelection

public void applyHeadingsToSelection(SelectionData selection,
                                     Heading[] headings)

applyHeadingsToSelection

public void applyHeadingsToSelection(SelectionData selection,
                                     java.util.Set[] headingSets)

applyPropertiesToSelection

public void applyPropertiesToSelection(SelectionData selection,
                                       java.util.Properties props)

defineBackwardSelections

public void defineBackwardSelections(SelectionData selectionData,
                                     int facetIndex)
Creates all backward selections in a single facet, and sets their headings, but no other information (e.g. no selected resources, no superselections of their own).

SimpleFacetmap's implementation produces the first backward selection based on the common ancestor of all headings in the facet for this selection. Other backward selections are based on the ancestors of the first.


getCommonAncestor

public Heading getCommonAncestor(java.util.Collection headings)
                          throws DataException
Returns the heading that is the closest (most specific) ancestor of all the input headings. This method will never return any of the input headings themselves (A heading is not its own ancestor). Usually the root heading, if nothing else, can be returned from this method, but some cases can return null (e.g. if the root heading is one of the inputs, or if there are no inputs).

Throws:
DataException - if headings are from different facets.

headingIsAncestorOfHeading

public boolean headingIsAncestorOfHeading(Heading ancestor,
                                          Heading child)

defineForwardSelections

public void defineForwardSelections(SelectionData selectionData,
                                    int facetIndex)
Creates all forward selections in a single facet, and sets their headings, but no other information (e.g. no selected resources, no forward selections of their own).

If there are multiple headings selected in this facet, we create forward selections from each of those headings (and throw out the other headings). For example, in wine, the forward selections of red|white@foo would be merlot@foo, cabernet@foo, chardonnay@foo, etc. They would _not_ be merlot|white@foo, red|chardonnay@foo, etc.


isSelectedInFacet

public boolean isSelectedInFacet(Heading heading,
                                 SelectionData selection,
                                 java.util.Set subselections)
                          throws InternalException
Determines whether the Heading is selected (either matched or contained) in the specified Selection. If it is contained in a subselection, subselections will include that subselection; otherwise it won't. It will not be used at all if it's null, or if this function returns false.

Throws:
InternalException

removeEmptySelections

public void removeEmptySelections(SelectionData selection)
                           throws InternalException
Throws:
InternalException

getFacetSpace

public FacetSpace getFacetSpace()
Specified by:
getFacetSpace in interface Facetmap

getResourceSpace

public ResourceSpace getResourceSpace()
Specified by:
getResourceSpace in interface Facetmap

setResourceSpace

public void setResourceSpace(ResourceSpace resourceSpace)

getTitle

public java.lang.String getTitle()
Description copied from interface: Facetmap
A descriptive title for this Facetmap instance.

Specified by:
getTitle in interface Facetmap

setTitle

public void setTitle(java.lang.String title)

getSelectionProps

public java.util.Properties getSelectionProps()

setSelectionProps

public void setSelectionProps(java.util.Properties selectionProps)

getSelection

public Selection getSelection(java.lang.String ref)
                       throws InternalException,
                              UnknownReferenceException
Description copied from interface: Facetmap
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.

Specified by:
getSelection in interface Facetmap
Throws:
InternalException
UnknownReferenceException

getSelection

public Selection getSelection(Heading[] headingList,
                              java.util.Properties props)
                       throws DataException,
                              InternalException
This is the basic getSelection call. Other getSelection methods in this class eventually call this one, so this is the one you need to rewrite if you're writing your own getSelection code.

Specified by:
getSelection in interface Facetmap
Throws:
DataException
InternalException
See Also:
Facetmap.getSelection(Heading[])

getRootSelection

public Selection getRootSelection()
                           throws InternalException
Description copied from interface: Facetmap
Produce a root Selection, a starting point for browsing this Facetmap. The returned Selection should have no backward Selections of its own.

Specified by:
getRootSelection in interface Facetmap
Throws:
InternalException

getSelection

public Selection getSelection(Heading[] headingList)
                       throws DataException,
                              InternalException
Description copied from interface: Facetmap
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" )
 )
 

Specified by:
getSelection in interface Facetmap
Throws:
DataException
InternalException

getSelection

public Selection getSelection(java.lang.String ref,
                              java.util.Properties properties)
                       throws InternalException,
                              UnknownReferenceException
Description copied from interface: Facetmap
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.

Specified by:
getSelection in interface Facetmap
Throws:
InternalException
UnknownReferenceException

getRootSelection

public Selection getRootSelection(java.util.Properties props)
                           throws InternalException
Caches root selection for the life of the SimpleFacetmap object, which underscores the intended immutability of SimpleFacetmap.

Specified by:
getRootSelection in interface Facetmap
Throws:
InternalException
See Also:
Facetmap.getSelection(Heading[], Properties)

getInfo

public java.lang.String getInfo()
Implementation-specific string for this FacetMap class.

Specified by:
getInfo in interface Facetmap

booleanProperty

public static boolean booleanProperty(java.util.Properties props,
                                      java.lang.String propKey)
The boolean returned represents the value true if the property value is not null and is equal, ignoring case, to the string "true". This is identical to java 1.5's Boolean.parseBoolean() logic.


intProperty

public static int intProperty(java.util.Properties props,
                              java.lang.String propKey,
                              int defaultValue)