info.aduna.gee.spectacle.gee
Class NavigationTree

java.lang.Object
  info.aduna.gee.spectacle.gee.NavigationTree

public class NavigationTree
extends Object

Class NavigationTree: the instantiation of a navigation specification.

The virtual navigation space through a set of objects (e.g. travels, books, documents) is specified by the NavigationSpecification. The paths that are really taken (and 'remembered') in this virtual navigation space are reified by NavigationTree. It's really all about performance and memory footprint in this class.

Field Summary

static int	NAVIGATION_BY_CONTENT There are only content steps at the current node.
static int	NAVIGATION_BY_CONTENT_AND_META There are only both content and meta steps at the current node.
static int	NAVIGATION_BY_META There are only meta steps at the current node.
static int	NAVIGATION_BY_NONE There are no steps at the current node.

Constructor Summary

NavigationTree(Collection entities, NavigationSpecification navigationSpecification, SectionRenderer renderer)
Construct a tree for a set of entities, a navigation specification and a renderer.

Method Summary

boolean	equals(Object other)
void	gc() Garbage collect the tree.
Map	getAlternativeSizes(MetaValueList mvl, int index) Return a map of the alternative branches/their sizes (String,Integer) for the index position.
NavigationTree	getBranch(String name, boolean remember) Get a branch of the current node (or null if non-existent).
Map	getBranches() This is an expensive call, don't use it, unless you really have to.
Map	getBranches(boolean remember) Get the non-null branches of the current node with their names.
Set	getBranchNames(String name) Get the names of all children of the named child.
Map	getBranchSizes(Collection names) Get the sizes of all children of the named children.
Map	getBranchSizes(String name) Get the sizes of all children of the named child.
Map	getBranchSizes(String name, Collection subnames) Get the sizes of a selected collection of children of the named child.
Set	getChildLabels() The set that is returned can be non-empty only for nodes whose node type is meta.
Map	getClusters(Collection allMPVs) Get all clusters as they occur by viewing the collection of MetaPlusValues.
List	getEntities()
int	getEntitiesSize()
List	getIntersection(String label)
MetaValueList	getMetaParts(PathString path) Split a tree in its Meta + Value(s) parts.
MetaValueList	getMetaParts(String path)
String	getName()
int	getNavigationType() Get the type of navigation at this node, i.e.
int	getNodeType() Get the type of this node, i.e.
Set	getOccurringLabels() Don't use this call anymore, although it's still supported, it's obsoleted.
Collection	getPotentialBranches() Get the names of all potential branches.
Set	getSharedLabels() Note: it is important that the result is a Set.
List	getSharedLabelsList() Note: it is important that the result is a List.
NavigationTree	getTree(MetaValueList mvl, boolean remember)
NavigationTree	getTree(PathString path, boolean remember) Get the tree that corresponds to a path or null (for non-existing paths).
NavigationTree	getTree(String path, boolean remember)
int	numberOfPotentialBranches() Get the potential number of branches.
void	removeBranch(String name) Remove a named branch.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NAVIGATION_BY_NONE

public static int NAVIGATION_BY_NONE

There are no steps at the current node.

NAVIGATION_BY_CONTENT

public static int NAVIGATION_BY_CONTENT

There are only content steps at the current node. Also used as: you have arrived at this node by a content step.

NAVIGATION_BY_META

public static int NAVIGATION_BY_META

There are only meta steps at the current node. Also used as: you have arrived at this node by a meta step.

NAVIGATION_BY_CONTENT_AND_META

public static int NAVIGATION_BY_CONTENT_AND_META

There are only both content and meta steps at the current node.

Constructor Detail

NavigationTree

public NavigationTree(Collection entities,
                      NavigationSpecification navigationSpecification,
                      SectionRenderer renderer)

Construct a tree for a set of entities, a navigation specification and a renderer.

Parameters:

entities - the collection of objects

navigationSpecification - the navigation specification (the virtual navigation space)

renderer - the renderer (passed for its properties only, not for rendering)

Method Detail

getName

public String getName()

Returns:

the name of this node

getSharedLabels

public Set getSharedLabels()

Note: it is important that the result is a Set. In a lot of cases, the sequence of the labels should be ignored.

Returns:

set of labels shared by all the Entities at this node or below.

getSharedLabelsList

public List getSharedLabelsList()

Note: it is important that the result is a List. In some cases, the sequence of the labels should not be ignored.

Returns:

list of labels shared by all the Entities at this node or below.

getOccurringLabels

public Set getOccurringLabels()

Don't use this call anymore, although it's still supported, it's obsoleted.

Returns:

the set of labels that occur in all the Entities at this node

getChildLabels

public Set getChildLabels()

The set that is returned can be non-empty only for nodes whose node type is meta. I.e. the node is arrived at by a meta step.

By default, no selection is applied to the objects of such a node. I.e. the node contains the same set of objects as its direct parent node.

However, the categorization of the current 'facet' may be in-complete. I.e. one or more objects do not comply to any of the facet-values of the current node.

For some (rare!) applications it is required that under those circumstances, the meta-node contains only the objects that occur in at least 1 child branch. Only for this type of nodes, this method will return a non-empty result.

Returns:

the set of labels shared by all children of this node

See Also:

MetaNavigationStep.setContentType(int)

getEntities

public List getEntities()

Returns:

the list of Entities that occur at this node

getEntitiesSize

public int getEntitiesSize()

Returns:

the number of Entities that occur at this node

getNavigationType

public int getNavigationType()

Get the type of navigation at this node, i.e. the types of steps that are available at this node.

Returns:

one of NAVIGATION_BY_NONE, NAVIGATION_BY_CONTENT, NAVIGATION_BY_META, NAVIGATION_BY_CONTENT_AND_META

getNodeType

public int getNodeType()

Get the type of this node, i.e. how did you arrive at this node, by a content or by a meta step ?

Returns:

one of NAVIGATION_BY_CONTENT, NAVIGATION_BY_META

equals

public final boolean equals(Object other)

Overrides:

equals in class Object

getBranch

public NavigationTree getBranch(String name,
                                boolean remember)

Get a branch of the current node (or null if non-existent).

Parameters:

name - the name of the branch requested

remember - if true, you must remember the branch for its state, if false, you may remember the branch for performance

Returns:

the requested branch or null

removeBranch

public void removeBranch(String name)

Remove a named branch.

Can be used by JitSectionRenderers to prune the tree on the fly. There is no other use for this method.

But even for JitSectionRenderers you should really be careful with this method, since its consequences are non-trivial. If you just need to hide a branch for the end-users, just don't include it in the user-interface that is generated. There is no real need to remove it from the NavigationTree.

getBranches

public Map getBranches()

This is an expensive call, don't use it, unless you really have to.

See Also:

getBranches(boolean)

getBranches

public Map getBranches(boolean remember)

Get the non-null branches of the current node with their names. This is an expensive call, don't use it, unless you really have to.

The fact that you want to know the branches, or even their sizes, are no good reasons.

There are a number of alternative methods, which are orders of magnitude faster.

Parameters:

remember - if true, you must remember the branches for its state, if false, you may remember the branches for performance

Returns:

a map names and non-null branches.

See Also:

getBranchNames(String), getBranchSizes(String), getBranchSizes(Collection), getBranchSizes(String, Collection), getAlternativeSizes(MetaValueList, int)

numberOfPotentialBranches

public int numberOfPotentialBranches()

Get the potential number of branches. It is a maximum, that may prove to be a lot lower due to empty branches or branches that do no match other criteria such as a minimum selection rate.

getTree

public NavigationTree getTree(PathString path,
                              boolean remember)

Get the tree that corresponds to a path or null (for non-existing paths). Note: this method is normally applied to the root node only!

Parameters:

path - the path

remember - if true the resulting tree should be persistent (to keep track of state)

getTree

public NavigationTree getTree(String path,
                              boolean remember)

See Also:

getTree(PathString, boolean)

getTree

public NavigationTree getTree(MetaValueList mvl,
                              boolean remember)

See Also:

getTree(PathString, boolean)

gc

public void gc()

Garbage collect the tree.

getMetaParts

public MetaValueList getMetaParts(String path)

See Also:

getMetaParts(PathString path)

getMetaParts

public MetaValueList getMetaParts(PathString path)

Split a tree in its Meta + Value(s) parts.

Note: that MetaNames in a path are not necessarily unique.
Note: this method is normally applied to the root node only!

Parameters:

path - the path to be split

Returns:

a MetaValueList or null when the path does not exist

getPotentialBranches

public Collection getPotentialBranches()

Get the names of all potential branches.

Returns:

the collection of names of the potential branches. They may turn out to be empty, so they may not exist!

getBranchSizes

public Map getBranchSizes(String name)

Get the sizes of all children of the named child.

Note: this is normally applied to a node whose navigation type is NAVIGATION_BY_META and the parameter passed to this method is one of the meta-steps (facets).

Parameters:

name - a candidate for a branch (the branch may not exist at all, e.g. because it is empty)

Returns:

a map of the name's branches/their sizes (String,Integer)

See Also:

getBranchSizes(Collection), getBranchSizes(String, Collection)

getBranchSizes

public Map getBranchSizes(String name,
                          Collection subnames)

Get the sizes of a selected collection of children of the named child.

Note: this is normally applied to a node whose navigation type is NAVIGATION_BY_META and the parameter passed to this method is one of the meta-steps (facets). In some applications, the caller 'somehow' already knows the facet values it is interested in.

In those cases, if the number of these facet values is lot less than the total amount of potential children, this method offers a performance benefit.

Parameters:

name - a candidate for a branch (the branch may not exist at all)

subnames - a subset of the names of the candidate's branch potential children

Returns:

a map of the name's subnames/their sizes (String,Integer)

See Also:

getBranchSizes(String), getBranchSizes(Collection)

getBranchSizes

public Map getBranchSizes(Collection names)

Get the sizes of all children of the named children.

Note: this methods offers a performance benefit over a repeated call of getBranchSizes(String).

Note: this is normally applied to a node whose navigation type is NAVIGATION_BY_META and the collection passed to this method contains a subset of all possible the meta-steps (facets).

Parameters:

names - candidates for a branch (the branch may not exist at all)

Returns:

a map of name/map pairs; each map contains the name's branches/their sizes (String,Integer)

See Also:

getBranchSizes(String), getBranchSizes(String, Collection)

getBranchNames

public Set getBranchNames(String name)

Get the names of all children of the named child.

Note: this is normally applied to a node whose navigation type is NAVIGATION_BY_META and the parameter passed to this method is one of the meta-steps (facets).

Parameters:

name - a candidate for a branch (the branch may not exist at all)

Returns:

a set of the name's branches

getAlternativeSizes

public Map getAlternativeSizes(MetaValueList mvl,
                               int index)

Return a map of the alternative branches/their sizes (String,Integer) for the index position. Note: this method is normally applied to the root node only!

This function can be used on a Meta node itself too. In that case, there is no current value and this function will return all children plus their sizes.

Important note: this method is never used by the Spectacle system itself, it is a utility method that is part of the API for "JitSectionRenderers". This method ignores any minimum step selection.

In the rare case that your application uses non-zero minimum step selections, you should use the (much, much more expensive) combination of getBrachNames for the index position plus getTree() for each branch name concatenated with the current 'trailer' of steps.

Parameters:

mvl - the meta/value list

index - the position for which alternative sizes are requested

Returns:

a map of the alternative branches/their sizes (String,Integer)

See Also:

getMetaParts(PathString)

getClusters

public Map getClusters(Collection allMPVs)

Get all clusters as they occur by viewing the collection of MetaPlusValues.

Parameters:

allMPVs - a collection of MetaPlusValues

Returns:

a map of Collection-of-MPVs/Collection-of-Entities

getIntersection

public List getIntersection(String label)