net.ontopia.topicmaps.core

Interface TopicIF

All Superinterfaces:

TMObjectIF

All Known Subinterfaces:

MFlatTopic, MTopic

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.

Field Summary

Fields

Modifier and Type	Field and Description
static String	EVENT_ADD_OCCURRENCE
static String	EVENT_ADD_SUBJECTIDENTIFIER
static String	EVENT_ADD_SUBJECTLOCATOR
static String	EVENT_ADD_TOPICNAME
static String	EVENT_ADD_TYPE
static String	EVENT_ADDED
static String	EVENT_MODIFIED
static String	EVENT_REMOVE_OCCURRENCE
static String	EVENT_REMOVE_SUBJECTIDENTIFIER
static String	EVENT_REMOVE_SUBJECTLOCATOR
static String	EVENT_REMOVE_TOPICNAME
static String	EVENT_REMOVE_TYPE
static String	EVENT_REMOVED

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

EVENT_ADD_ITEMIDENTIFIER, EVENT_REMOVE_ITEMIDENTIFIER, MSG_NULL_ARGUMENT

Method Summary

Modifier and Type	Method and Description
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.
Collection<AssociationIF>	getAssociations() PUBLIC: Gets the associations that have roles played by this topic.
Collection<AssociationIF>	getAssociationsByType(TopicIF type) PUBLIC: Gets the associations that have roles played by this topic, where the association is of specified type.
Collection<OccurrenceIF>	getOccurrences() PUBLIC: Gets the occurrences of this topic.
Collection<OccurrenceIF>	getOccurrencesByType(TopicIF type) PUBLIC: Gets the occurrences of this topic with a specified type.
ReifiableIF	getReified() PUBLIC: Returns the topic map object that this topic reifies.
Collection<AssociationRoleIF>	getRoles() PUBLIC: Gets the association roles played by this topic.
Collection<AssociationRoleIF>	getRolesByType(TopicIF roletype) PUBLIC: Gets the association roles of the specifed type played by this topic.
Collection<AssociationRoleIF>	getRolesByType(TopicIF roletype, TopicIF assoc_type) PUBLIC: Gets the association roles of the specifed type played by this topic.
Collection<LocatorIF>	getSubjectIdentifiers() PUBLIC: Gets the subject identitifers of this topic.
Collection<LocatorIF>	getSubjectLocators() PUBLIC: Gets the subject locators of this topic.
Collection<TopicNameIF>	getTopicNames() PUBLIC: Gets the names of this topic.
Collection<TopicNameIF>	getTopicNamesByType(TopicIF type) PUBLIC: Gets the topic names of this topic with a specified type.
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

Field Detail

EVENT_ADDED

static final String EVENT_ADDED

See Also:

Constant Field Values

EVENT_MODIFIED

static final String EVENT_MODIFIED

See Also:

Constant Field Values

EVENT_REMOVED

static final String EVENT_REMOVED

See Also:

Constant Field Values

EVENT_ADD_TYPE

static final String EVENT_ADD_TYPE

See Also:

Constant Field Values

EVENT_REMOVE_TYPE

static final String EVENT_REMOVE_TYPE

See Also:

Constant Field Values

EVENT_ADD_SUBJECTLOCATOR

static final String EVENT_ADD_SUBJECTLOCATOR

See Also:

Constant Field Values

EVENT_REMOVE_SUBJECTLOCATOR

static final String EVENT_REMOVE_SUBJECTLOCATOR

See Also:

Constant Field Values

EVENT_ADD_SUBJECTIDENTIFIER

static final String EVENT_ADD_SUBJECTIDENTIFIER

See Also:

Constant Field Values

EVENT_REMOVE_SUBJECTIDENTIFIER

static final String EVENT_REMOVE_SUBJECTIDENTIFIER

See Also:

Constant Field Values

EVENT_ADD_TOPICNAME

static final String EVENT_ADD_TOPICNAME

See Also:

Constant Field Values

EVENT_REMOVE_TOPICNAME

static final String EVENT_REMOVE_TOPICNAME

See Also:

Constant Field Values

EVENT_ADD_OCCURRENCE

static final String EVENT_ADD_OCCURRENCE

See Also:

Constant Field Values

EVENT_REMOVE_OCCURRENCE

static final String EVENT_REMOVE_OCCURRENCE

See Also:

Constant Field Values

Method Detail

getSubjectLocators

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

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

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

Collection<TopicNameIF> getTopicNames()

PUBLIC: Gets the names of this topic.

Returns:

A collection of TopicNameIF objects.

getTopicNamesByType

Collection<TopicNameIF> getTopicNamesByType(TopicIF type)

PUBLIC: Gets the topic names of this topic with a specified type.

Returns:

A collection of TopicNameIF objects typed by specified type.

getOccurrences

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.

getOccurrencesByType

Collection<OccurrenceIF> getOccurrencesByType(TopicIF type)

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

Returns:

A collection of OccurrenceIF objects typed by specified type.

getRoles

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

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

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

getAssociations

Collection<AssociationIF> getAssociations()

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

Returns:

A collection of AssociationIF objects.

getAssociationsByType

Collection<AssociationIF> getAssociationsByType(TopicIF type)

PUBLIC: Gets the associations that have roles played by this topic, where the association is of specified type. There is no guarantee as to the order these are returned in.

Returns:

A collection of AssociationIF objects.

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