org.wandora.topicmap.layered

Class LayeredTopic

java.lang.Object

org.wandora.topicmap.Topic

org.wandora.topicmap.layered.LayeredTopic

public class LayeredTopic
extends Topic

A LayeredTopic is a collection of topics in different layers that together merge with each other. Note that the collection may contain two topics which do not directly merge with each other but with the addition to some other topics, they all merge together. These topics are stored in an ordered collection with topics of top layers first and bottom layers last. Topics of same layer are ordered according to the smallest (lexicographically) subject identifier. This is somewhat arbitrary but will give a consistent ordering instead of random order.

When information is queried, the collection with all the individual topics is iterated and depending on the data being queried, either the first non null value is restored or all values are combined. Example of the former case is getting the base name and example for the latter case is getting subject identifiers. In general methods that return a collection of something combine the results from all individual topics (removing duplicates) and methods that return a single value return the first non null value encountered. Because topics are ordered in the topic collection, information from top layers is returned before information of bottom layers when only one non null value is returned.

Methods that modify a LayeredTopic actually modify one of the individual topics. The topic to be modified is chosen to be a topic of the selected layer of the layer stack. If such a topic does not exist one is generated in the layer. In case there are several such topics, one of them is chosen. Also the parameters to the modifying methods might not exist in the layer, in which case stubs of them are automatically generated.

Author:

olli

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) class	LayeredTopic.LayerOrderComparator Comparator used to order the topics LayeredTopic consists of.
static class	LayeredTopic.TopicKeyMaker

Field Summary

Fields

Modifier and Type	Field and Description
private int	hashCode
protected LayerStack	layerStack The layer stack for this topic
protected java.util.Vector<Topic>	topics The topics this LayeredTopic consists of

Constructor Summary

Constructors

Constructor and Description
LayeredTopic(java.util.Collection<Topic> topics, LayerStack layerStack) Creates a new instance of LayeredTopic.
LayeredTopic(Topic t, LayerStack layerStack) Creates a new instance of LayeredTopic.

Method Summary

Modifier and Type	Method and Description
private void	_addAssociations(java.util.HashSet<Association> associations, KeyedHashMap<LayeredTopic,java.util.Vector<LayeredTopic>> players, java.util.Vector<LayeredTopic> roles, java.util.Vector<LayeredTopic> chosen, LayeredTopic type) Adds LayeredAssociations into associations set based on the possible players for each role given in the players map.
void	addSubjectIdentifier(Locator l) Adds a subject identifier for the topic.
void	addType(Topic type) Adds a topic type.
protected void	ambiguity(java.lang.String s)
Topic	copyStubTo(TopicMap tm) Copies a stub of this topic to the given topic map.
protected java.util.Set<Topic>	createScope(java.util.Set<Topic> layeredScope, Layer l) Creates a scope from a collection of LayeredTopics that can be used for the given layer.
protected java.util.Set<Topic>	createScope(java.util.Set<Topic> layeredScope, Layer l, boolean copyTopics) Creates a scope from a collection of LayeredTopics that can be used for the given layer.
boolean	equals(java.lang.Object o) Two LayeredTopics are equal if their topics collections are equal.
java.util.Collection<Association>	getAssociations() Returns associations of this topic.
java.util.Collection<Association>	getAssociations(Topic type) See notes in getAssociations().
java.util.Collection<Association>	getAssociations(Topic type, Topic role) See notes in getAssociations().
java.util.Collection<Association>	getAssociationsWithRole() Gets associations that have this topic as role.
java.util.Collection<Association>	getAssociationsWithType() Gets associations that have this topic as type.
java.lang.String	getBaseName() Gets the topic base name or null if no base name has been set.
Topic	getBaseNameSource() Returns the layer that is being used to get the base name for this topic.
java.util.Hashtable<Topic,java.lang.String>	getData(Topic type) Returns a Hashtable mapping data versions to data content.
java.lang.String	getData(Topic type, Topic version) Gets data with the specified type and version.
Tuples.T3<Topic,Topic,Topic>	getDataSource(Topic type, Topic version) Returns the topic that is used to get data with specified type and version and the type and version topics for the source topic layer.
java.util.Collection<Topic>	getDataTypes() Gets all used data types.
long	getDependentEditTime()
long	getEditTime()
java.lang.String	getID() Returns the id of the first topic in the topics collection with layer name hash code as prefix.
LayerStack	getLayerStack()
java.util.Set<Topic>	getScopeOfLayeredScope(Topic t, java.util.Set<Topic> layeredScope) Tries to find a variant scope in the given (non layered) topic that matches the scope consisting of LayeredTopics.
java.util.Collection<Locator>	getSubjectIdentifiers() Gets all the subject identifiers of all the topics that this layered topic consists of.
Locator	getSubjectLocator() Gets the topic subject locator or null if it has not been set.
Topic	getSubjectLocatorSource()
Topic	getTopicForLayer(Layer l) Gets one of the topics of given layer that is part of this layered topic or null if no such topic exists.
Topic	getTopicForSelectedLayer() Gets one of the topics of the selected layer that is part of this layered topic or null if no such topic exists.
TopicMap	getTopicMap() Gets the topic map this topic belongs to.
java.util.Collection<Topic>	getTopicsForAllLayers() Get all topics this layered topic consists of in the order they appear in layers.
java.util.Collection<Topic>	getTopicsForLayer(Layer l) Get all topics of the given layer that are part of this LayeredTopic.
java.util.Collection<Topic>	getTopicsForSelectedLayer() Get all topics of selected layer that are part of this LayeredTopic.
java.util.Collection<Topic>	getTopicsWithDataType() Gets topics which have data with this topic as type.
java.util.Collection<Topic>	getTopicsWithDataVersion() Gets topics which have data with this topic as version.
java.util.Collection<Topic>	getTopicsWithVariantScope() Gets topics which have variants with this topic in scope.
java.util.Collection<Topic>	getTypes() Gets all topic types.
java.lang.String	getVariant(java.util.Set<Topic> scope) Gets a variant with the specified scope.
java.util.Set<java.util.Set<Topic>>	getVariantScopes() Gets the scopes of all variant names.
Tuples.T2<Topic,java.util.Set<Topic>>	getVariantSource(java.util.Set<Topic> scope) Returns the layer that is used to get the variant for the given scope.
int	hashCode()
boolean	isDeleteAllowed() Returns true if and only if remove() can be called without it throwing TopicInUseException.
boolean	isOfType(Topic type) Checks if this topic is of the specified type.
boolean	isRemoved() Returns true if this topic has been removed from the topic map it belonged to.
private java.util.HashSet<java.lang.String>	makeKeySet(java.util.Collection<Topic> topics) Makes a set having one key for each topic in the given collection.
boolean	mergesWithTopic(Topic topic) Checks if this topic would merge with the topic given as parameter.
void	remakeLayered() Remakes the collection of topics this layered topic consists of.
void	remakeLayered(Topic t) Remake this LayeredTopic using the given topic as the base.
void	remove() Removes this topic.
void	removeData(Topic type) Removes all data with the specified type.
void	removeData(Topic type, Topic version) Removes data with specified type and version.
void	removeSubjectIdentifier(Locator l) Removes a subject identifier.
void	removeType(Topic type) Removes a topic type.
void	removeVariant(java.util.Set<Topic> scope) Removes a variant name with the specified scope.
void	reorderLayers() Sort the topics collection.
protected AmbiguityResolution	resolveAmbiguity(java.lang.String event)
protected AmbiguityResolution	resolveAmbiguity(java.lang.String event, java.lang.String msg)
void	setBaseName(java.lang.String name) Sets the topic base name.
void	setData(Topic type, java.util.Hashtable<Topic,java.lang.String> versionData) Sets several data values.
void	setData(Topic type, Topic version, java.lang.String value) Sets data with specified type and version.
void	setDependentEditTime(long time)
void	setEditTime(long time)
void	setSubjectLocator(Locator l) Sets the topic subject locator overwriting possible previous value.
void	setVariant(java.util.Set<Topic> scope, java.lang.String name) Sets the variant with the specified scope.

Methods inherited from class org.wandora.topicmap.Topic

getData, getDisplayName, getDisplayName, getFirstSubjectIdentifier, getName, getOneSubjectIdentifier, getSortName, setDisplayName, toString

Methods inherited from class java.lang.Object

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

Field Detail

topics

protected java.util.Vector<Topic> topics

The topics this LayeredTopic consists of

layerStack

protected LayerStack layerStack

The layer stack for this topic

hashCode

private int hashCode

Constructor Detail

LayeredTopic

public LayeredTopic(java.util.Collection<Topic> topics,
                    LayerStack layerStack)

Creates a new instance of LayeredTopic. This layered topic will consist of the given topics and them alone. Thus the layer stack must not contain a topic that merges with any of the topics in the collection that isn't already in the collection.

LayeredTopic

public LayeredTopic(Topic t,
                    LayerStack layerStack)

Creates a new instance of LayeredTopic. This layered topic will consist of the one given topic and that alone. Thus the layer stack must not contain a topic that merges with that topic.

Method Detail

equals

public boolean equals(java.lang.Object o)

Two LayeredTopics are equal if their topics collections are equal. Note that this largely depends on the equals check of the individual topics.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

ambiguity

protected void ambiguity(java.lang.String s)

resolveAmbiguity

protected AmbiguityResolution resolveAmbiguity(java.lang.String event)

resolveAmbiguity

protected AmbiguityResolution resolveAmbiguity(java.lang.String event,
                                               java.lang.String msg)

remakeLayered

public void remakeLayered()
                   throws TopicMapException

Remakes the collection of topics this layered topic consists of. Will use the first topic in the topics collection as the base.

Throws:

TopicMapException

See Also:

remakeLayered(Topic)

makeKeySet

private java.util.HashSet<java.lang.String> makeKeySet(java.util.Collection<Topic> topics)

Makes a set having one key for each topic in the given collection. This can be used to later compare two topic collections and see if they are the same.

remakeLayered

public void remakeLayered(Topic t)
                   throws TopicMapException

Remake this LayeredTopic using the given topic as the base. After a layered topic has been modified, the topics in topics collection might not all merge anymore. After base name, subject locator or subject identifier is changed, the layered topic must be remade. The modification may have caused a split in which case there are more than one choice what the this LayeredTopic instance may become. The parameter of this method is used to collect all other merging topics and thus decides which of the splitted topics this instance becomes. Usually there isn't any right way to choose this base topic and it is chosen arbitrarily like is done in the remakeLayered method which takes no parameters.

Throws:

TopicMapException

getTopicsForSelectedLayer

public java.util.Collection<Topic> getTopicsForSelectedLayer()

Get all topics of selected layer that are part of this LayeredTopic.

getTopicsForLayer

public java.util.Collection<Topic> getTopicsForLayer(Layer l)

Get all topics of the given layer that are part of this LayeredTopic.

getTopicsForAllLayers

public java.util.Collection<Topic> getTopicsForAllLayers()

Get all topics this layered topic consists of in the order they appear in layers. Topics of top layers will appear first in the collection.

getTopicForSelectedLayer

public Topic getTopicForSelectedLayer()

Gets one of the topics of the selected layer that is part of this layered topic or null if no such topic exists.

getTopicForLayer

public Topic getTopicForLayer(Layer l)

Gets one of the topics of given layer that is part of this layered topic or null if no such topic exists.

reorderLayers

public void reorderLayers()

Sort the topics collection. This needs to be redone in remakeLayered or after visibility or order of layers has been changed.

getID

public java.lang.String getID()
                       throws TopicMapException

Returns the id of the first topic in the topics collection with layer name hash code as prefix. Using layer name prefix makes sure that the returned ID is unique (provided that layer topic map implementations return unique IDs). Hash code is used since layer name is user specified and may contain unwanted characters. Note that the ID will change based on what layers are visible.

Specified by:

getID in class Topic

Throws:

TopicMapException

getSubjectIdentifiers

public java.util.Collection<Locator> getSubjectIdentifiers()
                                                    throws TopicMapException

Gets all the subject identifiers of all the topics that this layered topic consists of.

Specified by:

getSubjectIdentifiers in class Topic

Throws:

TopicMapException

copyStubTo

public Topic copyStubTo(TopicMap tm)
                 throws TopicMapException

Copies a stub of this topic to the given topic map. This can be used to make a stub of this topic when it is needed in a layer that doesn't have a topic for this layered topic.

Throws:

TopicMapException

addSubjectIdentifier

public void addSubjectIdentifier(Locator l)
                          throws TopicMapException

Description copied from class: Topic

Adds a subject identifier for the topic. This may cause a topic merge.

Specified by:

addSubjectIdentifier in class Topic

Throws:

TopicMapException

removeSubjectIdentifier

public void removeSubjectIdentifier(Locator l)
                             throws TopicMapException

Description copied from class: Topic

Removes a subject identifier.

Specified by:

removeSubjectIdentifier in class Topic

Throws:

TopicMapException

getBaseNameSource

public Topic getBaseNameSource()
                        throws TopicMapException

Returns the layer that is being used to get the base name for this topic. That is the first layer that contains a topic in this layered topic that has a non null base name.

Throws:

TopicMapException

getBaseName

public java.lang.String getBaseName()
                             throws TopicMapException

Description copied from class: Topic

Gets the topic base name or null if no base name has been set.

Specified by:

getBaseName in class Topic

Throws:

TopicMapException

setBaseName

public void setBaseName(java.lang.String name)
                 throws TopicMapException

Description copied from class: Topic

Sets the topic base name. This may cause a topic merge.

Specified by:

setBaseName in class Topic

Throws:

TopicMapException

getTypes

public java.util.Collection<Topic> getTypes()
                                     throws TopicMapException

Description copied from class: Topic

Gets all topic types.

Specified by:

getTypes in class Topic

Throws:

TopicMapException

addType

public void addType(Topic type)
             throws TopicMapException

Description copied from class: Topic

Adds a topic type. If topic already has that type, does nothing.

Specified by:

addType in class Topic

Throws:

TopicMapException

removeType

public void removeType(Topic type)
                throws TopicMapException

Description copied from class: Topic

Removes a topic type. If topic is not of the specified type, does nothing.

Specified by:

removeType in class Topic

Throws:

TopicMapException

isOfType

public boolean isOfType(Topic type)
                 throws TopicMapException

Description copied from class: Topic

Checks if this topic is of the specified type.

Specified by:

isOfType in class Topic

Throws:

TopicMapException

createScope

protected java.util.Set<Topic> createScope(java.util.Set<Topic> layeredScope,
                                           Layer l)
                                    throws TopicMapException

Creates a scope from a collection of LayeredTopics that can be used for the given layer. Note that the given layer might not contain all topics needed for the scope in which case this will return null.

Throws:

TopicMapException

createScope

protected java.util.Set<Topic> createScope(java.util.Set<Topic> layeredScope,
                                           Layer l,
                                           boolean copyTopics)
                                    throws TopicMapException

Creates a scope from a collection of LayeredTopics that can be used for the given layer. Note that the given layer might not contain all topics needed for the scope. If copyTopics is true then stubs of these topics are created in the layer, otherwise null is returned if any of the needed topics isn't found in the layer.

Throws:

TopicMapException

getScopeOfLayeredScope

public java.util.Set<Topic> getScopeOfLayeredScope(Topic t,
                                                   java.util.Set<Topic> layeredScope)
                                            throws TopicMapException

Tries to find a variant scope in the given (non layered) topic that matches the scope consisting of LayeredTopics. If such a scope doesn't exist null is returned. In case there are several of such scopes, one of them is returned chosen arbitrarily.

Throws:

TopicMapException

getVariantSource

public Tuples.T2<Topic,java.util.Set<Topic>> getVariantSource(java.util.Set<Topic> scope)
                                                       throws TopicMapException

Returns the layer that is used to get the variant for the given scope.

Throws:

TopicMapException

getVariant

public java.lang.String getVariant(java.util.Set<Topic> scope)
                            throws TopicMapException

Description copied from class: Topic

Gets a variant with the specified scope. The scope must be a Collection of Topics. Returns null if there is no variant with the specified scope.

Specified by:

getVariant in class Topic

Throws:

TopicMapException

setVariant

public void setVariant(java.util.Set<Topic> scope,
                       java.lang.String name)
                throws TopicMapException

Description copied from class: Topic

Sets the variant with the specified scope. Will overwrite previous value if there already is a variant name with the specified scope.

Specified by:

setVariant in class Topic

Throws:

TopicMapException

getVariantScopes

public java.util.Set<java.util.Set<Topic>> getVariantScopes()
                                                     throws TopicMapException

Description copied from class: Topic

Gets the scopes of all variant names.

Specified by:

getVariantScopes in class Topic

Throws:

TopicMapException

removeVariant

public void removeVariant(java.util.Set<Topic> scope)
                   throws TopicMapException

Description copied from class: Topic

Removes a variant name with the specified scope. If no such variant exists, does nothing.

Specified by:

removeVariant in class Topic

Throws:

TopicMapException

getDataSource

public Tuples.T3<Topic,Topic,Topic> getDataSource(Topic type,
                                                  Topic version)
                                           throws TopicMapException

Returns the topic that is used to get data with specified type and version and the type and version topics for the source topic layer.

Throws:

TopicMapException

getData

public java.lang.String getData(Topic type,
                                Topic version)
                         throws TopicMapException

Description copied from class: Topic

Gets data with the specified type and version. Returns null if data is not found.

Specified by:

getData in class Topic

Throws:

TopicMapException

getData

public java.util.Hashtable<Topic,java.lang.String> getData(Topic type)
                                                    throws TopicMapException

Description copied from class: Topic

Returns a Hashtable mapping data versions to data content.

Specified by:

getData in class Topic

Throws:

TopicMapException

getDataTypes

public java.util.Collection<Topic> getDataTypes()
                                         throws TopicMapException

Description copied from class: Topic

Gets all used data types.

Specified by:

getDataTypes in class Topic

Throws:

TopicMapException

setData

public void setData(Topic type,
                    java.util.Hashtable<Topic,java.lang.String> versionData)
             throws TopicMapException

Description copied from class: Topic

Sets several data values. Each value is set with same type, the other parameter should contain versions mapped to the actual values.

Specified by:

setData in class Topic

Throws:

TopicMapException

setData

public void setData(Topic type,
                    Topic version,
                    java.lang.String value)
             throws TopicMapException

Description copied from class: Topic

Sets data with specified type and version.

Specified by:

setData in class Topic

Throws:

TopicMapException

removeData

public void removeData(Topic type,
                       Topic version)
                throws TopicMapException

Description copied from class: Topic

Removes data with specified type and version. If no such data value is set, does nothing.

Specified by:

removeData in class Topic

Throws:

TopicMapException

removeData

public void removeData(Topic type)
                throws TopicMapException

Description copied from class: Topic

Removes all data with the specified type.

Specified by:

removeData in class Topic

Throws:

TopicMapException

getSubjectLocatorSource

public Topic getSubjectLocatorSource()
                              throws TopicMapException

Throws:

TopicMapException

getSubjectLocator

public Locator getSubjectLocator()
                          throws TopicMapException

Description copied from class: Topic

Gets the topic subject locator or null if it has not been set.

Specified by:

getSubjectLocator in class Topic

Throws:

TopicMapException

setSubjectLocator

public void setSubjectLocator(Locator l)
                       throws TopicMapException

Description copied from class: Topic

Sets the topic subject locator overwriting possible previous value.

Specified by:

setSubjectLocator in class Topic

Throws:

TopicMapException

getTopicMap

public TopicMap getTopicMap()

Description copied from class: Topic

Gets the topic map this topic belongs to.

Specified by:

getTopicMap in class Topic

getLayerStack

public LayerStack getLayerStack()

_addAssociations

private void _addAssociations(java.util.HashSet<Association> associations,
                              KeyedHashMap<LayeredTopic,java.util.Vector<LayeredTopic>> players,
                              java.util.Vector<LayeredTopic> roles,
                              java.util.Vector<LayeredTopic> chosen,
                              LayeredTopic type)
                       throws TopicMapException

Adds LayeredAssociations into associations set based on the possible players for each role given in the players map. When converting individual associations into LayeredAssociations, each role may have several possible players because roles may have been merged. This method is used to create LayeredAssociations with all possible player assignments. The getAssociations methods construct the players map and call this method with chosen and roles parameters as null and an empty associations set. When the method returns associations set will contain all possible LayeredAssociations. The method works recursively by choosing one player for each role at a time. The chosen players are stored in the chosen Vector. When one player has been chosen for each player, a LayeredAssociation is created and added to the set which is later returned.

Throws:

TopicMapException

getAssociations

public java.util.Collection<Association> getAssociations()
                                                  throws TopicMapException

Returns associations of this topic. Note that because roles may get merged, one individual association may become multiple LayeredAssociations.

Specified by:

getAssociations in class Topic

Throws:

TopicMapException

getAssociations

public java.util.Collection<Association> getAssociations(Topic type)
                                                  throws TopicMapException

See notes in getAssociations().

Specified by:

getAssociations in class Topic

Throws:

TopicMapException

getAssociations

public java.util.Collection<Association> getAssociations(Topic type,
                                                         Topic role)
                                                  throws TopicMapException

See notes in getAssociations().

Specified by:

getAssociations in class Topic

Throws:

TopicMapException

remove

public void remove()
            throws TopicMapException

Description copied from class: Topic

Removes this topic. If this topic is used in any association as the association type or role of any member or this topic is used in any topic in variant scope, data version, data type or topic type, a TopicInUseException is thrown. This topic may however be used as a player of associations. All such associations are deleted along with this topic.

Specified by:

remove in class Topic

Throws:

TopicMapException

getEditTime

public long getEditTime()
                 throws TopicMapException

Specified by:

getEditTime in class Topic

Throws:

TopicMapException

setEditTime

public void setEditTime(long time)
                 throws TopicMapException

Specified by:

setEditTime in class Topic

Throws:

TopicMapException

getDependentEditTime

public long getDependentEditTime()
                          throws TopicMapException

Specified by:

getDependentEditTime in class Topic

Throws:

TopicMapException

setDependentEditTime

public void setDependentEditTime(long time)
                          throws TopicMapException

Specified by:

setDependentEditTime in class Topic

Throws:

TopicMapException

isRemoved

public boolean isRemoved()
                  throws TopicMapException

Description copied from class: Topic

Returns true if this topic has been removed from the topic map it belonged to. Note that it might have been removed as a result of topics being merged and still exists in the topic map but as another topic object.

Specified by:

isRemoved in class Topic

Throws:

TopicMapException

isDeleteAllowed

public boolean isDeleteAllowed()
                        throws TopicMapException

Description copied from class: Topic

Returns true if and only if remove() can be called without it throwing TopicInUseException. This is exactly when this topic is not used in any association as the association type or role of any member, and this topic is not used in any topic in variant scope, data version, data type or topic type. This topic may however be used as a player of associations.

Specified by:

isDeleteAllowed in class Topic

Throws:

TopicMapException

getTopicsWithDataType

public java.util.Collection<Topic> getTopicsWithDataType()
                                                  throws TopicMapException

Description copied from class: Topic

Gets topics which have data with this topic as type.

Specified by:

getTopicsWithDataType in class Topic

Throws:

TopicMapException

getAssociationsWithType

public java.util.Collection<Association> getAssociationsWithType()
                                                          throws TopicMapException

Description copied from class: Topic

Gets associations that have this topic as type.

Specified by:

getAssociationsWithType in class Topic

Throws:

TopicMapException

getAssociationsWithRole

public java.util.Collection<Association> getAssociationsWithRole()
                                                          throws TopicMapException

Description copied from class: Topic

Gets associations that have this topic as role.

Specified by:

getAssociationsWithRole in class Topic

Throws:

TopicMapException

getTopicsWithDataVersion

public java.util.Collection<Topic> getTopicsWithDataVersion()
                                                     throws TopicMapException

Description copied from class: Topic

Gets topics which have data with this topic as version.

Specified by:

getTopicsWithDataVersion in class Topic

Throws:

TopicMapException

getTopicsWithVariantScope

public java.util.Collection<Topic> getTopicsWithVariantScope()
                                                      throws TopicMapException

Description copied from class: Topic

Gets topics which have variants with this topic in scope.

Specified by:

getTopicsWithVariantScope in class Topic

Throws:

TopicMapException

mergesWithTopic

public boolean mergesWithTopic(Topic topic)
                        throws TopicMapException

Description copied from class: Topic

Checks if this topic would merge with the topic given as parameter. The topic given as parameter may be from this or another topic map.

Overrides:

mergesWithTopic in class Topic

Throws:

TopicMapException