org.tmapi.core
Interface TopicName

All Superinterfaces:

ScopedObject, TopicMapObject

public interface TopicName

extends ScopedObject

Represents the topic map topic name construct. In XTM, this construct is represented by the <baseName> element.

Method Summary

void	addScopingTopic(Topic topic) Adds the scoping topic topic to the collection of Topics that define the scope of this name.
Variant	createVariant(Locator resource, java.util.Collection scope) Creates a variant of this topic name with the specified external resource locator and scopes.
Variant	createVariant(java.lang.String value, java.util.Collection scope) Creates a variant of this topic name with the specified inline data string and scopes.
Topic	getReifier() Returns the Topic that reifies this topic name.
Topic	getTopic() Returns the Topic which contains this TopicName.
Topic	getType() OPTIONAL: Returns the Topic that defines the type of this topic name.
java.lang.String	getValue() Returns the name string of the TopicName
java.util.Set	getVariants() Returns the variants defined for this TopicName.
void	remove() Removes this TopicName from the collection of TopicNames managed by the parent Topic.
void	removeScopingTopic(Topic topic) Removes a topic from the set which defines the scope/parameters for this object.
void	setType(Topic type) OPTIONAL: Sets the Topic that defines the type of this topic name.
void	setValue(java.lang.String value) Define the name string for this TopicName.

Methods inherited from interface org.tmapi.core.ScopedObject

getScope

Methods inherited from interface org.tmapi.core.TopicMapObject

addSourceLocator, equals, getObjectId, getSourceLocators, getTopicMap, hashCode, removeSourceLocator

Method Detail

getTopic

public Topic getTopic()

Returns the Topic which contains this TopicName.

getValue

public java.lang.String getValue()

Returns the name string of the TopicName

Returns:

The name string or null if this TopicName has no value.

setValue

public void setValue(java.lang.String value)
              throws MergeException

Define the name string for this TopicName. A new value will replace any existing value. A null value indicates that there is no name string for this TopicName.

Parameters:

value - The name string to be assigned to the TopicName.

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.

getVariants

public java.util.Set getVariants()

Returns the variants defined for this TopicName. The return value may be an empty Set, but is never null.

Returns:

An unmodifiable Set of Variant objects.

createVariant

public Variant createVariant(java.lang.String value,
                             java.util.Collection scope)

Creates a variant of this topic name with the specified inline data string and scopes.

Parameters:

value - The inline data string for the variant. Pass null for no string.

scope - The scope for the Variant to be created. Must be a collection of Topic objects.

Returns:

the newly created Variant object.

createVariant

public Variant createVariant(Locator resource,
                             java.util.Collection scope)

Creates a variant of this topic name with the specified external resource locator and scopes.

Parameters:

resource - The locator of the external resource for the variant. Pass null for no reference.

scope - The scope for the Variant to be created. Must be a collection of Topic objects.

Returns:

the newly created Variant object.

getReifier

public Topic getReifier()

Returns the Topic that reifies this topic name.

Returns:

A Topic instance or null if the topic name is not reified.

getType

public Topic getType()

OPTIONAL: Returns the Topic that defines the type of this topic name.
This method reflects the XTM 1.1 model. A processor which does not implement support for XTM 1.1 MUST return null

Returns:

A Topic instance or null if the topic name does not have a type specified.

setType

public void setType(Topic type)
             throws java.lang.UnsupportedOperationException,
                    MergeException

OPTIONAL: Sets the Topic that defines the type of this topic name.
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/xtm1.1" is disabled) MUST throw an UnsupportedOperationException. Overwrites any existing type information.

Parameters:

type - A Topic instance or null to remove any existing type.

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.

remove

public void remove()
            throws TMAPIException

Removes this TopicName from the collection of TopicNames managed by the parent Topic. This method removes all contained Variant objects.

Specified by:

remove in interface TopicMapObject

Throws:

TMAPIException - if the object cannot be removed from the container. Derived interfaces may define specific circumstances under which a subclass of TMAPIException must be raised. Implementations MUST NOT use a TMAPIException to wrap a failure raised in the underlying engine - such errors must always be wrapped in a TMAPIRuntimeException.

addScopingTopic

public void addScopingTopic(Topic topic)
                     throws MergeException

Adds the scoping topic topic to the collection of Topics that define the scope of this name.

Specified by:

addScopingTopic in interface ScopedObject

Parameters:

topic - the scoping topic to be added to the scope of this name.

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.

removeScopingTopic

public void removeScopingTopic(Topic topic)
                        throws MergeException

Removes a topic from the set which defines the scope/parameters for this object.

Specified by:

removeScopingTopic in interface ScopedObject

Parameters:

topic - The topic to be remove from the set.

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.