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.