org.tmapi.core
Interface Topic

All Superinterfaces:
TopicMapObject

public interface Topic
extends TopicMapObject

Represents the topic map topic construct.


Method Summary
 void addSourceLocator(Locator sourceLocator)
          Adds a Locator to the set of source locators for this Topic.
 void addSubjectIdentifier(Locator subjectIdentifier)
          Adds the specified locator to the set of locators that reference the subject-indicating resources of this topic.
 void addSubjectLocator(Locator subjectLocator)
          Adds the specified locator to the set of locators that reference the subject-constituting resources of this topic.
 void addType(Topic type)
          Adds a type to this topic.
 Occurrence createOccurrence(Locator resource, Topic type, java.util.Collection scope)
          Creates a new occurrence as a contained object in this topic.
 Occurrence createOccurrence(java.lang.String value, Topic type, java.util.Collection scope)
          Creates a new occurrence as a contained object in this topic.
 TopicName createTopicName(java.lang.String value, java.util.Collection scope)
          Creates a new TopicName for this topic.
 TopicName createTopicName(java.lang.String value, Topic type, java.util.Collection scope)
          OPTIONAL: Creates a new typed TopicName for this topic.
 java.util.Set getOccurrences()
          Returns the occurrences defined for this topic.
 java.util.Set getReified()
          Returns a Set of TopicMapObject instances that are subject of this Topic.
 java.util.Set getRolesPlayed()
          Returns the association roles in which this topic is a player.
 java.util.Set getSubjectIdentifiers()
          Returns the Locators which reference the subject-indicating resources of this topic.
 java.util.Set getSubjectLocators()
          Returns Locator instances which reference the subject-constituting resources of this topic.
 java.util.Set getTopicNames()
          Returns the TopicNames defined for this topic.
 java.util.Set getTypes()
          Returns the topics which define the types of this topic.
 void mergeIn(Topic other)
          Merges another Topic into this Topic.
 void remove()
          Removes this object from the collection of Topics managed by the parent TopicMap.
 void removeSubjectIdentifier(Locator subjectIdentifier)
          Removes the specified locator from the set of locators that reference the subject-indicating resources of this topic.
 void removeSubjectLocator(Locator subjectLocator)
          Removes the specified locator from the set of locators that reference the subject-constituting resources of this topic.
 void removeType(Topic type)
          Removes a type from this topic.
 
Methods inherited from interface org.tmapi.core.TopicMapObject
equals, getObjectId, getSourceLocators, getTopicMap, hashCode, removeSourceLocator
 

Method Detail

getTopicNames

public java.util.Set getTopicNames()
Returns the TopicNames defined for this topic. The return value may be an empty Set, but is never null.

Returns:
An unmodifiable Set of TopicName objects.

createTopicName

public TopicName createTopicName(java.lang.String value,
                                 java.util.Collection scope)
                          throws MergeException
Creates a new TopicName for this topic.

Parameters:
value - The string value of the TopicName. Pass null to create a TopicName with no name value.
scope - A Collection of Topic objects. If null, the TopicName will be in the unconstrained scope.
Returns:
the newly created TopicName instance
Throws:
MergeException - if the processor detects that a merge is required and either automerge is disabled or automerge is enabled but the merge cannot be completed for some other reason. NOTE: This method will not raise this exception if the XTM 1.1 model is enabled, as untyped names do not cause merging under XTM 1.1.

createTopicName

public TopicName createTopicName(java.lang.String value,
                                 Topic type,
                                 java.util.Collection scope)
                          throws java.lang.UnsupportedOperationException,
                                 MergeException
OPTIONAL: Creates a new typed TopicName for this topic.
This method reflects the XTM 1.1 model. A processor which does not implement support for XTM 1.1 (or if the feature "http://tmapi.org/features/model/xtm.1.1" is disabled) MUST throw an UnsupportedOperationException.

Parameters:
value - The string value of the TopicName. Pass null to create a TopicName with no name value.
type - A Topic instance or null
scope - A Collection of Topic objects. If null, the TopicName will be in the unconstrained scope.
Returns:
the newly created TopicName instance
Throws:
java.lang.UnsupportedOperationException - if the processor does not support the XTM 1.1 model.
MergeException - if the processor detects that a merge is required and either automerge is disabled or automerge is enabled but the merge cannot be completed for some other reason.

createOccurrence

public Occurrence createOccurrence(java.lang.String value,
                                   Topic type,
                                   java.util.Collection scope)
Creates a new occurrence as a contained object in this topic.

Parameters:
value - The occurrence data.
type - The occurrence type. If null, then the occurrence will be untyped.
scope - A Collection of Topic objects. If null, the occurrence will be in the unconstrained scope.
Returns:
the newly created Occurrence instance.

createOccurrence

public Occurrence createOccurrence(Locator resource,
                                   Topic type,
                                   java.util.Collection scope)
Creates a new occurrence as a contained object in this topic.

Parameters:
resource - The occurrence resource locator.
type - The occurrence type. If null, then the occurrence will be untyped.
scope - A Collection of Topic objects. If null, the occurrence will be in the unconstrained scope.
Returns:
the newly created Occurrence instance.

getOccurrences

public java.util.Set getOccurrences()
Returns the occurrences defined for this topic. The return value may be an empty Set, but is never null.

Returns:
An unmodifiable Set of Occurrence objects.

getSubjectLocators

public java.util.Set getSubjectLocators()
Returns Locator instances which reference the subject-constituting resources of this topic. The return value may be an empty Set, but is never null.

Returns:
An unmodifiable Set of Locator objects.

addSubjectLocator

public void addSubjectLocator(Locator subjectLocator)
                       throws MergeException,
                              ModelConstraintException
Adds the specified locator to the set of locators that reference the subject-constituting resources of this topic.

Parameters:
subjectLocator - The locator of the new subject constituting resource for this topic.
Throws:
MergeException - if the processor detects that a merge is required and either automerge is disabled or automerge is enabled but the merge cannot be completed for some other reason.
ModelConstraintException - if the XTM 1.0 processor model is enabled and this Topic already has one Locator in the subjectLocator set.

removeSubjectLocator

public void removeSubjectLocator(Locator subjectLocator)
Removes the specified locator from the set of locators that reference the subject-constituting resources of this topic.

Parameters:
subjectLocator - the Locator to be removed from the set of subject-constituting resources for this topic.

getSubjectIdentifiers

public java.util.Set getSubjectIdentifiers()
Returns the Locators which reference the subject-indicating resources of this topic. The return value may be an empty Set, but is never null.

Returns:
An unmodifiable Set of Locator objects.

addSubjectIdentifier

public void addSubjectIdentifier(Locator subjectIdentifier)
                          throws MergeException
Adds the specified locator to the set of locators that reference the subject-indicating resources of this topic.

Parameters:
subjectIdentifier - The locator to be added.
Throws:
MergeException - if the processor detects that a merge is required and either automerge is disabled or automerge is enabled but the merge cannot be completed for some other reason.

removeSubjectIdentifier

public void removeSubjectIdentifier(Locator subjectIdentifier)
Removes the specified locator from the set of locators that reference the subject-indicating resources of this topic.

Parameters:
subjectIdentifier - The locator to be removed.

getTypes

public java.util.Set getTypes()
Returns the topics which define the types of this topic. The return value may be an empty Set, but is never null.

Returns:
An unmodifiable Set of Topic objects.

addType

public void addType(Topic type)
Adds a type to this topic.

Parameters:
type - The type-defining topic to be added.

removeType

public void removeType(Topic type)
Removes a type from this topic.

Parameters:
type - The type-defining topic to be removed.

getRolesPlayed

public java.util.Set getRolesPlayed()
Returns the association roles in which this topic is a player. The return value may be an empty Set, but is never null.

Returns:
An unmodifiable Set of AssociationRole objects.

remove

public void remove()
            throws TopicInUseException
Removes this object from the collection of Topics managed by the parent TopicMap. This method must also remove all contained TopicName and Occurrence objects.

Specified by:
remove in interface TopicMapObject
Throws:
TopicInUseException - If this Topic is currently used as a type of another topic, occurrence, or association; or if this topic is as association role type; a member of a scope; or a role player in an association.

mergeIn

public void mergeIn(Topic other)
             throws MergeException
Merges another Topic into this Topic. Merging a Topic into this Topic causes this Topic to gain all of the characteristics of the other Topic and to replace the other Topic wherever it is used as a typing or scoping topic. After this method completes, other will have been removed from the TopicMap. NOTE: The other Topic MUST belong to the same TopicMap instance as this Topic!

Parameters:
other - the other Topic to be merged into this Topic
Throws:
SubjectLocatorClashException - if this topic and other have different, non-null values for the subjectLocator property and the XTM 1.0 processing model is enabled.
MergeException

getReified

public java.util.Set getReified()
Returns a Set of TopicMapObject instances that are subject of this Topic. The return value may be an empty Set, but is never null.

Returns:
An unmodifiable Set of TopicMapObject instances.

addSourceLocator

public void addSourceLocator(Locator sourceLocator)
                      throws DuplicateSourceLocatorException,
                             MergeException
Adds a Locator to the set of source locators for this Topic. It is not allowed to have two TopicMapObjects in the same TopicMap with the same source locator. If the two objects are Topic objects, then they must be merged. If at least one of the two objects is not a Topic object, a DuplicateSourceLocatorException must be reported.

Specified by:
addSourceLocator in interface TopicMapObject
Parameters:
sourceLocator - the Locator to be added
Throws:
DuplicateSourceLocatorException - if there is already a TopicMapObject that is not a Topic with this source Locator.
MergeException - if another Topic with this source locator alreday exists in the same TopicMap, and either the feature http://tmapi.org/features/automerge is disabled or the merge cannot be completed for some reason.
See Also:
TopicMapObject.getSourceLocators()