org.tm4j.topicmap
Interface Topic

All Superinterfaces:

TopicMapObject

All Known Implementing Classes:

UnifiedTopic

public interface Topic

extends TopicMapObject

This interface describes a topic in a Topic Map. The Topic is perhaps the single most important construct among all those that may occur in a Topic Map. From XTM 1.0:

“A topic is a resource that acts as a proxy for some subject; it is the topic map system's representation of that subject. The relationship between a topic and its subject is defined to be one of reification. Reification of a subject allows topic characteristics to be assigned to the topic that reifies it.”

[...]

“A subject is anything that can be spoken about or conceived of by a human being. In the most generic sense, a subject is anything whatsoever, regardless of whether it exists or has any other specific characteristics, about which anything whatsoever may be asserted by any means whatsoever. In particular, it is anything on which the author of a topic map chooses to discourse.”

The characteristics that topics are usually assigned include BaseNames and Occurrences, both of which may be constrained by a scope, which is defined by a set of Topics. Topics may be typed, and effectively support mechanisms equivalent to multiple inheritance by allowing more than one typing topic. Topics may also be subject to merging under certain circumstances, that is, two or more topics which share particular traits effectively become one whose characteristics are the sum of the original topics'. This interface provides a number of methods which deal with results of merging, and which provide access to the topics that, at some point during processing, merged with the current topic.

Author:

Kal Ahmed

Method Summary

void	addMergedTopic(Topic t) Adds the specified topic to the set of merged topics.
void	addName(BaseName name) Adds another name to the set of names of this Topic.
void	addOccurrence(Occurrence occurs) Adds an occurrence to this Topic.
void	addSubjectIndicator(Locator subjectIndicator) Adds a subject indicator to this topic.
void	addType(Topic type) Adds a new topic into the set of those defining the type of this topic.
BaseName	createName(java.lang.String id) Creates a new BaseName as a child of this Topic.
BaseName	createName(java.lang.String id, java.lang.String nameString) Creates a new BaseName as a child of this Topic
BaseName	createName(java.lang.String id, java.lang.String nameString, Topic[] scope) Creates a new BaseName as a child of this Topic
Occurrence	createOccurrence(java.lang.String id) Creates a new Occurrence as a child of this Topic.
Occurrence	createOccurrence(java.lang.String id, Locator resourceLocator, Topic type, Locator ref, Topic[] themes)
Occurrence	createOccurrence(java.lang.String id, Locator resourceLocator, Topic type, java.lang.String data, Topic[] themes)
Topic	getBaseTopic() Gets the topic with which this topic is merged if any.
java.util.Collection	getMergedTopics() Returns a collection of all of the other topics which were merged with this topic due to identity matches or topic map naming constraints.
java.util.Collection	getNames() Retrieves a collection of the base names of this topic and any merged topics.
java.util.Collection	getNames(boolean includeMergedTopics) Retrieves the collection of the base names of this topic and, if so specified, of any merged topics.
java.util.Collection	getOccurrences() Returns the occurrences for this topic and any merged topics.
java.util.Collection	getOccurrences(boolean includeMergedTopics) Returns the occurrences for this topic and, if so specified, of any merged topics.
TopicMap	getParent() Returns the TopicMap object which contains this Topic object.
java.util.Collection	getRolesPlayed() Gets the Member objects which define roles played by this topic in associations.
java.util.Collection	getRolesPlayed(boolean includeMergedTopics) Gets the Member objects which define roles played by this topic in associations.
java.util.Collection	getScopedNames() Generates a list of all names of the topic and all merged topics, qualified by the scope of the names and of the topic itself.
java.util.Collection	getScopedNames(boolean includeMergedTopics) Generates a list of all names of the topic, qualified by the scope of the names and of the topic itself.
Locator	getSubject() Retrieves the reference to the resource which is the subject of this topic.
Locator	getSubject(boolean includeMergedTopics) Retrieves the reference to the resource which is the subject of this topic.
java.util.Collection	getSubjectIndicators() Returns the subject indicators for this topic and all merged topics.
java.util.Collection	getSubjectIndicators(boolean includeMergedTopics) Returns the subject indicators for this topic and, optionally, for all merged topics.
java.util.Collection	getTypes() Returns the Topics defining the type of this topic and all merged topics.
java.util.Collection	getTypes(boolean includeMergedTopics) Returns the Topics defining the type of this topic and, optionally, of all merged topics.
boolean	isOfType(Locator subjectOrIndicator) Determines whether this topic is typed by a topic whose subject is or whose subject is indicated by subjectOrIndicator.
boolean	isOfType(Topic type) Determines whether the specified topic is one of the types of this topic.
void	setNames(BaseName[] names) Sets the names of this Topic.
void	setOccurrences(Occurrence[] occurs) Sets the list of occurrences for this Topic.
void	setSubject(Locator subject) Sets the reference to the subject of this topic.
void	setSubjectIndicators(Locator[] indicators) Sets the collection of subject indicators for this topic.
void	setTypes(Topic[] types) Defines the type of this topic.

Methods inherited from interface org.tm4j.topicmap.TopicMapObject

addMultiValuePropertyChangeListener, addMultiValuePropertyChangeListener, addPropertyChangeListener, addPropertyChangeListener, addSourceLocator, addVetoableChangeListener, destroy, fireMultiValuePropertyChange, fireMultiValuePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getID, getResourceLocator, getSourceLocators, getTopicMap, removeMultiValuePropertyChangeListener, removePropertyChangeListener, removePropertyChangeListener, removeSourceLocator, removeVetoableChangeListener, setID, setResourceLocator

Method Detail

getSubject

public Locator getSubject()

Retrieves the reference to the resource which is the subject of this topic.

Returns:

The resource reference as a Locator, or null if no resource represents the subject which this topic reifies.

getSubject

public Locator getSubject(boolean includeMergedTopics)

Retrieves the reference to the resource which is the subject of this topic.

Parameters:

includeMergedTopics - if true, then the subject defined by any one of the topics merged with this topic will be returned, otherwise a value will only be returned if it was specified on this Topic instance.

Returns:

the resource reference as a Locator or null if there is no subject locator.

setSubject

public void setSubject(Locator subject)
                throws java.beans.PropertyVetoException

Sets the reference to the subject of this topic.

Parameters:

subject - The locator of the resource that is the subject which this topic reifies.

Throws:

java.beans.PropertyVetoException

getSubjectIndicators

public java.util.Collection getSubjectIndicators()

Returns the subject indicators for this topic and all merged topics. This method is a shorthand for getSubjectIndicators(true).

Returns:

An unmodifiable collection of Locators representing the subject indicators for this topic. If no subject indicators are currently defined on this topic (or merged topics), the returned collection is empty; it is never null.

getSubjectIndicators

public java.util.Collection getSubjectIndicators(boolean includeMergedTopics)

Returns the subject indicators for this topic and, optionally, for all merged topics.

Parameters:

includeMergedTopics - if true, then the subject indicators of all merged topics are included in the returned collection, otherwise only the subject indicators of this topic are returned.

Returns:

An unmodifiable collection of Locators representing the subject indicators for this topic. If no subject indicators are currently defined on this topic (or merged topics), the returned collection is empty; it is never null.

addSubjectIndicator

public void addSubjectIndicator(Locator subjectIndicator)
                         throws java.beans.PropertyVetoException

Adds a subject indicator to this topic.

Parameters:

subjectIndicator - the subject indicator reference to be added.

Throws:

java.beans.PropertyVetoException

setSubjectIndicators

public void setSubjectIndicators(Locator[] indicators)
                          throws java.beans.PropertyVetoException

Sets the collection of subject indicators for this topic.

Parameters:

indicators - the subject indicator references, as an array of Locators.

Throws:

java.beans.PropertyVetoException

getTypes

public java.util.Collection getTypes()

Returns the Topics defining the type of this topic and all merged topics. This method is shorthand for getTypes(true).

Returns:

An unmodifiable Collection of the Topics defining the type of this topic and all merged topics. If no types are currently defined on this topic (or merged topics), the returned collection is empty; it is never null.

getTypes

public java.util.Collection getTypes(boolean includeMergedTopics)

Returns the Topics defining the type of this topic and, optionally, of all merged topics.

Parameters:

includeMergedTopics - If true then the types of all merged topics are included in the returned collection, otherwise, only the typing topics defined on this topic are returned.

Returns:

An unmodifiable Collection of the Topics defining the type of this topic and, if includeMergedTopics is set to true, of all merged topics. If no subject indicators are currently defined on this topic (or merged topics), the returned collection is empty; it is never null.

setTypes

public void setTypes(Topic[] types)
              throws java.beans.PropertyVetoException

Defines the type of this topic.

Parameters:

types - the new set of topics to define the type of this topic. If this is null, all the existing typing topics of this topic are removed.

Throws:

java.beans.PropertyVetoException

addType

public void addType(Topic type)
             throws java.beans.PropertyVetoException

Adds a new topic into the set of those defining the type of this topic.

Parameters:

type - The typing topic to be added.

Throws:

java.beans.PropertyVetoException

isOfType

public boolean isOfType(Topic type)

Determines whether the specified topic is one of the types of this topic.

Parameters:

type - the topic to be compared to this topic's typing topics.

Returns:

true if type is among the topics defining this topic's type, false otherwise.

isOfType

public boolean isOfType(Locator subjectOrIndicator)

Determines whether this topic is typed by a topic whose subject is or whose subject is indicated by subjectOrIndicator.

This method will return true if one of the following conditions hold:

• A subject indicator of a typing topic of this topic, or
• the actual subject of a typing topic of this topic.

Returns:

true if subjectOrIndicator meets the above conditions, false otherwise.

getNames

public java.util.Collection getNames()

Retrieves a collection of the base names of this topic and any merged topics. This function is shorthand for getNames(true).

Returns:

An unmodifiable collection of BaseNames defined on this topic and any merged topics. If no base names are currently defined on this topic (or merged topics), the returned collection is empty; it is never null.

getNames

public java.util.Collection getNames(boolean includeMergedTopics)

Retrieves the collection of the base names of this topic and, if so specified, of any merged topics.

Parameters:

includeMergedTopics - If true, the names of all merged topics are included in the returned collection. Otherwise, the collection contains only the names defined specifically on this topic.

Returns:

An unmodifiable collection of BaseNames defined on this topic and, optionally, any merged topics. If no base names are currently defined on this topic (or merged topics), the returned collection is empty; it is never null.

setNames

public void setNames(BaseName[] names)
              throws java.beans.PropertyVetoException

Sets the names of this Topic.

Parameters:

names - the new set of names to be assigned to this topic. If this is null, all the existing names of this topic are removed.

Throws:

java.beans.PropertyVetoException

addName

public void addName(BaseName name)
             throws java.beans.PropertyVetoException

Adds another name to the set of names of this Topic.

Parameters:

name - the name to be added.

Throws:

java.beans.PropertyVetoException

createName

public BaseName createName(java.lang.String id)
                    throws DuplicateObjectIDException,
                           java.beans.PropertyVetoException

Creates a new BaseName as a child of this Topic.

Parameters:

id - the unique object id to be assigned to the new BaseName object. If this parameter is null, the back-end will assign an ID to the newly created object.

Throws:

DuplicateObjectIDException - if id specifies and identifier value already used in the containing TopicMap.

java.beans.PropertyVetoException - if to create a new name for this Topic would violate a constraint imposed by a VetoableChangeListener assigned to this TopicMap.

createName

public BaseName createName(java.lang.String id,
                           java.lang.String nameString)
                    throws DuplicateObjectIDException,
                           java.beans.PropertyVetoException

Creates a new BaseName as a child of this Topic

Parameters:

id - the unique object id to be assigned to the new BaseName object. If this parameter is null, the back-end will assign an ID to the newly created object.

nameString - the string to be assigned to the new BaseName as content.

Returns:

a new BaseName object.

Throws:

DuplicateObjectIDException - if id specifies and identifier value already used in the containing TopicMap.

java.beans.PropertyVetoException - if to create a new name for this Topic would violate a constraint imposed by a VetoableChangeListener assigned to this TopicMap.

createName

public BaseName createName(java.lang.String id,
                           java.lang.String nameString,
                           Topic[] scope)
                    throws DuplicateObjectIDException,
                           java.beans.PropertyVetoException

Creates a new BaseName as a child of this Topic

Parameters:

id - the unique object id to be assigned to the new BaseName object. If this parameter is null, the back-end will assign an ID to the newly created object.

nameString - the string to be assigned to the new BaseName as content.

scope - the topics to be assigned to the scope of the new BaseName.

Returns:

a new BaseName object.

Throws:

DuplicateObjectIDException - if id specifies and identifier value already used in the containing TopicMap.

java.beans.PropertyVetoException - if to create a new name for this Topic would violate a constraint imposed by a VetoableChangeListener assigned to this TopicMap.

getOccurrences

public java.util.Collection getOccurrences()

Returns the occurrences for this topic and any merged topics. This function is shorthand for getOccurrences(true).

Returns:

A collection of the Occurrences for this topic and for any merged topics. The returned collection is a copy of the internal set of occurrences of the topic — modifying the collection has no effect on the occurrence set of the Topic. If no occurrences are currently defined on this topic (or merged topics), the returned collection is empty; it is never null.

getOccurrences

public java.util.Collection getOccurrences(boolean includeMergedTopics)

Returns the occurrences for this topic and, if so specified, of any merged topics.

Parameters:

includeMergedTopics - if true, then the occurrences of all merged topics are included in the returned collection. Otherwise, the collection contains only the occurrences defined specifically for this topic.

Returns:

A collection of the Occurrences for this topic and for any merged topics. The returned collection is a copy of the internal set of occurrences of the topic — modifying the collection has no effect on the occurrence set of the Topic. If no occurrences are currently defined on this topic (or merged topics), the returned collection is empty; it is never null.

setOccurrences

public void setOccurrences(Occurrence[] occurs)
                    throws java.beans.PropertyVetoException

Sets the list of occurrences for this Topic.

Parameters:

occurs - the new set of occurrences to be associated with this topic. If this is null, all the existing occurrences of this topic are removed.

Throws:

java.beans.PropertyVetoException

addOccurrence

public void addOccurrence(Occurrence occurs)
                   throws java.beans.PropertyVetoException

Adds an occurrence to this Topic.

Parameters:

occurs - The Occurrence to be added.

Throws:

java.beans.PropertyVetoException

createOccurrence

public Occurrence createOccurrence(java.lang.String id)
                            throws DuplicateObjectIDException,
                                   java.beans.PropertyVetoException

Creates a new Occurrence as a child of this Topic.

Parameters:

id - the unique object id to be assigned to the new Occurrence object. If this parameter is null, the back-end will assign an ID to the newly created object.

Throws:

DuplicateObjectIDException - if id specifies and identifier value already used in the containing TopicMap.

java.beans.PropertyVetoException - if to create a new Occurrence for this Topic would violate a constraint imposed by a VetoableChangeListener assigned to this TopicMap.

createOccurrence

public Occurrence createOccurrence(java.lang.String id,
                                   Locator resourceLocator,
                                   Topic type,
                                   Locator ref,
                                   Topic[] themes)
                            throws DuplicateObjectIDException,
                                   DuplicateResourceLocatorException,
                                   java.beans.PropertyVetoException

Throws:

DuplicateObjectIDException

DuplicateResourceLocatorException

java.beans.PropertyVetoException

createOccurrence

public Occurrence createOccurrence(java.lang.String id,
                                   Locator resourceLocator,
                                   Topic type,
                                   java.lang.String data,
                                   Topic[] themes)
                            throws DuplicateObjectIDException,
                                   DuplicateResourceLocatorException,
                                   java.beans.PropertyVetoException

Throws:

DuplicateObjectIDException

DuplicateResourceLocatorException

java.beans.PropertyVetoException

getRolesPlayed

public java.util.Collection getRolesPlayed()

Gets the Member objects which define roles played by this topic in associations. The roles played by all merged topics are also included. This function is shorthand for getRolesPlayed(true).

Returns:

A Collection of the Member objects representing roles played by this Topic in Associations.

getRolesPlayed

public java.util.Collection getRolesPlayed(boolean includeMergedTopics)

Gets the Member objects which define roles played by this topic in associations.

Parameters:

includeMergedTopics - If true then the roles played by all merged topics are included in the returned collection.

addMergedTopic

public void addMergedTopic(Topic t)
                    throws MergedTopicSubjectClashException

Adds the specified topic to the set of merged topics.

Parameters:

t - the topic to be added to the merge set.

Throws:

MergedTopicSubjectClashException

getMergedTopics

public java.util.Collection getMergedTopics()

Returns a collection of all of the other topics which were merged with this topic due to identity matches or topic map naming constraints.

Returns:

An unmodifiable collection of original Topics that were topic merged with this topic. If no topics were merged with this topic, the returned collection is empty; it is never null.

getBaseTopic

public Topic getBaseTopic()

Gets the topic with which this topic is merged if any.

Returns:

The topic that this topic is merged with, or null if the topic has not merged with any other.

getScopedNames

public java.util.Collection getScopedNames(boolean includeMergedTopics)

Generates a list of all names of the topic, qualified by the scope of the names and of the topic itself. Each qualified name is generated as follows:

    <sorted-scope-list>.<name-string>

Where <sorted-scope-list> is a list of all themes SGML identifiers sorted in ascending alphabetical order, with a period separator between each identifier.

Parameters:

includeMergedTopics - If true, the scoped names of all topics merged with this topic are returned. Otherwise, only the scoped names of this topic are returned.

Returns:

A collection of strings containing the scoped names, as described above. If no names are currently defined on this topic (or merged topics), the returned collection is empty; it is never null.

getScopedNames

public java.util.Collection getScopedNames()

Generates a list of all names of the topic and all merged topics, qualified by the scope of the names and of the topic itself. This is equivalent to getScopedNames(true). Each qualified name is generated as follows:

    <sorted-scope-list>.<name-string>

Where <sorted-scope-list> is a list of all themes SGML identifiers sorted in ascending alphabetical order, with a period separator between each identifier.

Returns:

A collection of strings containing the scoped names, as described above. If no names are currently defined on this topic (or merged topics), the returned collection is empty; it is never null.

getParent

public TopicMap getParent()

Returns the TopicMap object which contains this Topic object.

Returns:

The topic map that this topic is contained in.