net.ontopia.topicmaps.core
Interface TopicIF

All Superinterfaces:

TMObjectIF

All Known Implementing Classes:

ReadOnlyTopic, RemoteTopic, SnapshotTopic, Topic, Topic

public interface TopicIF
extends TMObjectIF

PUBLIC: This interface is implemented by objects representing topics in the topic map model.

Note that topic identity is a difficult area, since it depends on the availability of information from outside the topic map. In a nutshell, topics represent addressable subjects, but addressable subjects may be the same even if their locators are very different.

In general, the determination of equality between addressable subjects cannot be fully guaranteed, and applications using this API will need to be aware of their limitations and capabilities in this respect - and that other topic map applications they communicate with may have lesser or greater powers to determine subject identity.

Method Summary

void	addSubjectIdentifier(LocatorIF subject_identifier) PUBLIC: Adds the given subject identifier to the set of subject identifiers for this topic.
void	addSubjectLocator(LocatorIF subject_locator) PUBLIC: Adds the given subject locator to the set of subject locators for this topic.
void	addType(TopicIF type) PUBLIC: Adds a type to this topic.
java.util.Collection<OccurrenceIF>	getOccurrences() PUBLIC: Gets the occurrences of this topic.
ReifiableIF	getReified() PUBLIC: Returns the topic map object that this topic reifies.
java.util.Collection<AssociationRoleIF>	getRoles() PUBLIC: Gets the association roles played by this topic.
java.util.Collection<AssociationRoleIF>	getRolesByType(TopicIF roletype) PUBLIC: Gets the association roles of the specifed type played by this topic.
java.util.Collection<AssociationRoleIF>	getRolesByType(TopicIF roletype, TopicIF assoc_type) PUBLIC: Gets the association roles of the specifed type played by this topic.
java.util.Collection<LocatorIF>	getSubjectIdentifiers() PUBLIC: Gets the subject identitifers of this topic.
java.util.Collection<LocatorIF>	getSubjectLocators() PUBLIC: Gets the subject locators of this topic.
java.util.Collection<TopicNameIF>	getTopicNames() PUBLIC: Gets the names of this topic.
java.util.Collection<TopicIF>	getTypes() PUBLIC: Gets the types that this topic is an instance of.
void	merge(TopicIF topic) EXPERIMENTAL: Merges the characteristics of one topic into another topic.
void	removeSubjectIdentifier(LocatorIF subject_identifier) PUBLIC: Removes the given subject identifier from the set of subject identifiers for this topic.
void	removeSubjectLocator(LocatorIF subject_locator) PUBLIC: Removes the given subject locator from the set of subject locators for this topic.
void	removeType(TopicIF type) PUBLIC: Removes a type from this topic.

Methods inherited from interface net.ontopia.topicmaps.core.TMObjectIF

addItemIdentifier, getItemIdentifiers, getObjectId, getTopicMap, isReadOnly, remove, removeItemIdentifier

Method Detail

getSubjectLocators

java.util.Collection<LocatorIF> getSubjectLocators()

PUBLIC: Gets the subject locators of this topic. These are locators for resources that directly address the subject of this topic. Such a resource is also called an addressable subject. The subject locators are not guaranteed to have any specific order within the returned collection.

Returns:

A collection of LocatorIF objects serving as subject locators.

Since:

4.0

addSubjectLocator

void addSubjectLocator(LocatorIF subject_locator)
                       throws ConstraintViolationException

PUBLIC: Adds the given subject locator to the set of subject locators for this topic.

Parameters:

subject_locator - A locator for the subject locator to be added; an object implementing LocatorIF.

Throws:

ConstraintViolationException - Thrown if the topic map already has a topic with this subject locator.

Since:

4.0

removeSubjectLocator

void removeSubjectLocator(LocatorIF subject_locator)

PUBLIC: Removes the given subject locator from the set of subject locators for this topic. If the topic does not have the given subject locator then this method has no effect.

Parameters:

subject_locator - A locator for the subject locator to be removed; an object implementing LocatorIF.

Since:

4.0

getSubjectIdentifiers

java.util.Collection<LocatorIF> getSubjectIdentifiers()

PUBLIC: Gets the subject identitifers of this topic. These are locators for resources that indirectly address or otherwise indicate the subject of this topic. A subject identifier is intended as a surrogate for a subject which cannot be addressed directly. The subject identifiers are not guaranteed to have any specific order within the returned collection.

Returns:

A collection of LocatorIF objects serving as subject identifiers.

Since:

4.0

addSubjectIdentifier

void addSubjectIdentifier(LocatorIF subject_identifier)
                          throws ConstraintViolationException

PUBLIC: Adds the given subject identifier to the set of subject identifiers for this topic.

Parameters:

subject_identifier - A locator for the subject identifier to be added; an object implementing LocatorIF.

Throws:

ConstraintViolationException - Thrown if the topic map already has a topic with this addressable subject.

Since:

4.0

removeSubjectIdentifier

void removeSubjectIdentifier(LocatorIF subject_identifier)

PUBLIC: Removes the given subject identifier from the set of subject identifiers for this topic. If the topic does not have the given subject identifier then this method has no effect.

Parameters:

subject_identifier - A locator for the subject identifier to be removed; an object implementing LocatorIF.

Since:

4.0

getTypes

java.util.Collection<TopicIF> getTypes()

PUBLIC: Gets the types that this topic is an instance of. There is no guarantee as to which order these will be returned in.

Returns:

A collection of TopicIF objects.

addType

void addType(TopicIF type)

PUBLIC: Adds a type to this topic.

Parameters:

type - The additional type; an object implementing TopicIF.

removeType

void removeType(TopicIF type)

PUBLIC: Removes a type from this topic. If the given topic is not present amongst the types, then the method has no effect.

Parameters:

type - The type to be removed; an object implementing TopicIF.

getTopicNames

java.util.Collection<TopicNameIF> getTopicNames()

PUBLIC: Gets the names of this topic.

Returns:

A collection of TopicNameIF objects.

getOccurrences

java.util.Collection<OccurrenceIF> getOccurrences()

PUBLIC: Gets the occurrences of this topic. The occurrences are not guaranteed to have any specific order.

Returns:

A collection of OccurrenceIF objects.

getRoles

java.util.Collection<AssociationRoleIF> getRoles()

PUBLIC: Gets the association roles played by this topic. There is no guarantee as to the order these are returned in.

Returns:

A collection of AssociationRoleIF objects.

getRolesByType

java.util.Collection<AssociationRoleIF> getRolesByType(TopicIF roletype)

PUBLIC: Gets the association roles of the specifed type played by this topic. There is no guarantee as to the order these are returned in.

Returns:

A collection of AssociationRoleIF objects.

Since:

2.2

getRolesByType

java.util.Collection<AssociationRoleIF> getRolesByType(TopicIF roletype,
                                                       TopicIF assoc_type)

PUBLIC: Gets the association roles of the specifed type played by this topic. The association roles must be part of an association of the specified type. There is no guarantee as to the order these are returned in.

Returns:

A collection of AssociationRoleIF objects.

Since:

2.2

merge

void merge(TopicIF topic)

EXPERIMENTAL: Merges the characteristics of one topic into another topic. The source topic stripped of characteristics, all of which are moved to the target topic. Duplicate characteristics are suppressed. The topics must be in the same topic map, and the source topic is removed from the topic map.

Parameters:

topic - topicIF; the source topic. This is empty after the operation and is removed from the topic map.

Throws:

throws - ConstraintViolationException if the two topics have different values for the 'subject' property, since if they do they cannot represent the same subject. If this exception is thrown both topics remain untouched.

Since:

2.0.4

getReified

ReifiableIF getReified()

PUBLIC: Returns the topic map object that this topic reifies.

Since:

4.0