org.tmapi.core
Interface TopicMap

All Superinterfaces:

Construct, Reifiable

public interface TopicMap
extends Reifiable

Represents a topic map item.

Version:

$Rev: 173 $ - $Date: 2010-03-10 14:02:21 +0100 (Mi, 10 Mrz 2010) $

Author:

The TMAPI Project

Method Summary

void	close() Closes use of this topic map instance.
Association	createAssociation(Topic type, java.util.Collection<Topic> scope) Creates an Association in this topic map with the specified type and scope.
Association	createAssociation(Topic type, Topic... scope) Creates an Association in this topic map with the specified type and scope.
Locator	createLocator(java.lang.String reference) Returns a Locator instance representing the specified IRI reference.
Topic	createTopic() Returns a Topic instance with an automatically generated item identifier.
Topic	createTopicByItemIdentifier(Locator itemIdentifier) Returns a Topic instance with the specified item identifier.
Topic	createTopicBySubjectIdentifier(Locator subjectIdentifier) Returns a Topic instance with the specified subject identifier.
Topic	createTopicBySubjectLocator(Locator subjectLocator) Returns a Topic instance with the specified subject locator.
java.util.Set<Association>	getAssociations() Returns all Associations contained in this topic map.
Construct	getConstructById(java.lang.String id) Returns a Construct by its (system specific) identifier.
Construct	getConstructByItemIdentifier(Locator itemIdentifier) Returns a Construct by its item identifier.
<I extends Index> I	getIndex(java.lang.Class<I> indexInterface) Returns the specified index.
Locator	getLocator() Returns the Locator that was used to create the topic map.
Construct	getParent() Returns null.
Topic	getTopicBySubjectIdentifier(Locator subjectIdentifier) Returns a topic by its subject identifier.
Topic	getTopicBySubjectLocator(Locator subjectLocator) Returns a topic by its subject locator.
java.util.Set<Topic>	getTopics() Returns all Topics contained in this topic map.
void	mergeIn(TopicMap other) Merges the topic map other into this topic map.

Methods inherited from interface org.tmapi.core.Reifiable

getReifier, setReifier

Methods inherited from interface org.tmapi.core.Construct

addItemIdentifier, equals, getId, getItemIdentifiers, getTopicMap, hashCode, remove, removeItemIdentifier

Method Detail

getParent

Construct getParent()

Returns null.

Specified by:

getParent in interface Construct

Returns:

null since topic maps do not have a parent.

getTopics

java.util.Set<Topic> getTopics()

Returns all Topics contained in this topic map. The return value may be empty but must never be null.

Returns:

An unmodifiable set of Topics.

getLocator

Locator getLocator()

Returns the Locator that was used to create the topic map.

Note: The returned locator represents the storage address of the topic map and implies no further semantics.

Returns:

A Locator, never null.

See Also:

TopicMapSystem.createTopicMap(org.tmapi.core.Locator), TopicMapSystem.getTopicMap(org.tmapi.core.Locator)

getAssociations

java.util.Set<Association> getAssociations()

Returns all Associations contained in this topic map. The return value may be empty but must never be null.

Returns:

An unmodifiable set of Associations.

getTopicBySubjectIdentifier

Topic getTopicBySubjectIdentifier(Locator subjectIdentifier)

Returns a topic by its subject identifier.

If no topic with the specified subject identifier exists, this method returns null.

Parameters:

subjectIdentifier - The subject identifier of the topic to be returned.

Returns:

A topic with the specified subject identifier or null if no such topic exists in the topic map.

getTopicBySubjectLocator

Topic getTopicBySubjectLocator(Locator subjectLocator)

Returns a topic by its subject locator.

If no topic with the specified subject locator exists, this method returns null.

Parameters:

subjectLocator - The subject locator of the topic to be returned.

Returns:

A topic with the specified subject locator or null if no such topic exists in the topic map.

getConstructByItemIdentifier

Construct getConstructByItemIdentifier(Locator itemIdentifier)

Returns a Construct by its item identifier.

Parameters:

itemIdentifier - The item identifier of the construct to be returned.

Returns:

A construct with the specified item identifier or null if no such construct exists in the topic map.

getConstructById

Construct getConstructById(java.lang.String id)

Returns a Construct by its (system specific) identifier.

Parameters:

id - The identifier of the construct to be returned.

Returns:

The construct with the specified id or null if such a construct is unknown.

createLocator

Locator createLocator(java.lang.String reference)
                      throws MalformedIRIException

Returns a Locator instance representing the specified IRI reference. The specified IRI reference is assumed to be absolute.

Parameters:

reference - A string which uses the IRI notation.

Returns:

A Locator representing the IRI reference.

Throws:

java.lang.IllegalArgumentException - If reference is null.

MalformedIRIException - If the provided string cannot be used to create a valid locator.

createTopicBySubjectIdentifier

Topic createTopicBySubjectIdentifier(Locator subjectIdentifier)
                                     throws ModelConstraintException

Returns a Topic instance with the specified subject identifier.

This method returns either an existing Topic or creates a new Topic instance with the specified subject identifier.

If a topic with the specified subject identifier exists in the topic map, that topic is returned. If a topic with an item identifier equals to the specified subject identifier exists, the specified subject identifier is added to that topic and the topic is returned. If neither a topic with the specified subject identifier nor with an item identifier equals to the subject identifier exists, a topic with the subject identifier is created.

Parameters:

subjectIdentifier - The subject identifier the topic should contain.

Returns:

A Topic instance with the specified subject identifier.

Throws:

ModelConstraintException - If the subject identifier subjectIdentifier is null.

createTopicBySubjectLocator

Topic createTopicBySubjectLocator(Locator subjectLocator)
                                  throws ModelConstraintException

Returns a Topic instance with the specified subject locator.

This method returns either an existing Topic or creates a new Topic instance with the specified subject locator.

Parameters:

subjectLocator - The subject locator the topic should contain.

Returns:

A Topic instance with the specified subject locator.

Throws:

ModelConstraintException - If the subject locator subjectLocator is null.

createTopicByItemIdentifier

Topic createTopicByItemIdentifier(Locator itemIdentifier)
                                  throws IdentityConstraintException,
                                         ModelConstraintException

Returns a Topic instance with the specified item identifier.

This method returns either an existing Topic or creates a new Topic instance with the specified item identifier.

If a topic with the specified item identifier exists in the topic map, that topic is returned. If a topic with a subject identifier equals to the specified item identifier exists, the specified item identifier is added to that topic and the topic is returned. If neither a topic with the specified item identifier nor with a subject identifier equals to the subject identifier exists, a topic with the item identifier is created.

Parameters:

itemIdentifier - The item identifier the topic should contain.

Returns:

A Topic instance with the specified item identifier.

Throws:

ModelConstraintException - If the item identifier itemIdentifier is null.

IdentityConstraintException - If an other Construct with the specified item identifier exists which is not a Topic.

createTopic

Topic createTopic()

Returns a Topic instance with an automatically generated item identifier.

This method returns never an existing Topic but creates a new one with an automatically generated item identifier. How that item identifier is generated depends on the implementation.

Returns:

The newly created Topic instance with an automatically generated item identifier.

createAssociation

Association createAssociation(Topic type,
                              Topic... scope)
                              throws ModelConstraintException

Creates an Association in this topic map with the specified type and scope.

Parameters:

type - The association type, MUST NOT be null.

scope - An optional array of themes, must not be null. If the array's length is 0, the association will be in the unconstrained scope.

Returns:

The newly created Association.

Throws:

ModelConstraintException - If either the type or scope is null.

createAssociation

Association createAssociation(Topic type,
                              java.util.Collection<Topic> scope)
                              throws ModelConstraintException

Creates an Association in this topic map with the specified type and scope.

Parameters:

type - The association type, MUST NOT be null.

scope - A collection of themes or null if the association should be in the unconstrained scope.

Returns:

The newly created Association.

Throws:

ModelConstraintException - If either the type or scope is null.

close

void close()

Closes use of this topic map instance.

This method should be invoked by the application once it is finished using this topic map instance.

Implementations may release any resources required for the TopicMap instance or any of the Construct instances contained by this instance.

mergeIn

void mergeIn(TopicMap other)
             throws ModelConstraintException

Merges the topic map other into this topic map.

All Topics and Associations and all of their contents in other will be added to this topic map.

All information items in other will be merged into this topic map as defined by the Topic Maps - Data Model (TMDM) merging rules.

The merge process will not modify other in any way.

If this.equals(other) no changes are made to the topic map.

Parameters:

other - The topic map to be merged with this topic map instance; must not be null.

Throws:

ModelConstraintException - If other is null.

getIndex

<I extends Index> I getIndex(java.lang.Class<I> indexInterface)

Returns the specified index.

Parameters:

indexInterface - The index to return.

Returns:

An index.

Throws:

java.lang.UnsupportedOperationException - If the implementation does not support indices or if the specified index is unsupported.