org.tm4j.topicmap
Interface TopicMap

All Superinterfaces:
TopicMapObject
All Known Implementing Classes:
UnifiedTopicMap

public interface TopicMap
extends TopicMapObject

This interface defines the whole Topic Map construct.

Author:
Kal Ahmed, Harald Kuhn (getProvider)

Method Summary
 void addAddedTheme(Topic theme)
          Adds an added theme to the topic map.
 void addExternalRef(Locator topicRef)
          Adds an external reference from this topic map to another topic map.
 void addMergeMap(Locator mapLocator, Topic[] addedThemes)
          Adds a new mergeMap directive to this topic map.
 Association createAssociation(java.lang.String id)
          Creates a new Association in this TopicMap.
 Association createAssociation(java.lang.String id, Locator resourceLocator, Topic type, Topic[] themes)
          Creates a new Association in this topic map
 Topic createTopic(java.lang.String id)
          Creates a new Topic in this TopicMap.
 java.util.Collection getAddedThemes()
          Get a list of the Topic objects defining the added themes of the topic map.
 java.util.Collection getAssociations()
          Get a list of the Associations contained in the topic map.
 java.util.Iterator getAssociationsIterator()
          Get an iterator over all of the Associations in the topic map.
 Locator getBaseLocator()
          Returns the Locator for the address of the source which generated the topic map.
 java.util.Set getExternalRefs()
          Returns all of the unresolved external references from this topic map.
 TopicMapFactory getFactory()
          Get the concrete implementation of the TopicMapFactory interface which partners with the concrete implementation of this interface.
 IndexManager getIndexManager()
          Returns the IndexManager object which handles access to all of the indexes for this topic map.
 LocatorFactory getLocatorFactory()
          Get the concrete implementation of the LocatorFactory interface which partners with the concrete implementation of this interface.
 java.util.Set getMergeMapAddedThemes(Locator mapLocator)
          Returns the collection of themes to be added to the external topic map resource when it is merged with this map.
 java.util.Collection getMergeMapLocators()
          Returns an unmodifiable Map of the unresolved mergeMap directives contained within this topic map.
 java.lang.String getName()
          getName Get the name of the topic map.
 TopicMapObject getObjectByID(java.lang.String id)
          Gets the object with the specified unique identifier.
 TopicMapObject getObjectByResourceLocator(Locator resourceLocator)
          Deprecated. from 0.9.0 this method is renamed getObjectBySourceLocator(Locator)
 TopicMapObject getObjectBySourceLocator(Locator resourceLocator)
          Gets the TopicMapObject which was generated from the specified resource.
 java.util.Collection getObjects()
          Gets all the objects in the topic map.
 java.lang.Boolean getProperty(java.lang.String propertyName)
          Returns the value of a configuration property set for this topic map
 TopicMapProvider getProvider()
          Returns the TopicMapProvider implementation which provides this TopicMap
 Topic getTopicByID(java.lang.String id)
          Gets the topic with the specified unique identifier
 Topic getTopicBySubject(Locator subjectLocator)
          Get the topic which is bound to the specified subject
 Topic getTopicBySubjectIndicator(Locator subjectIndicatorLocator)
          Get the topic which is bound to the subject indicated by the specified resource.
 int getTopicCount()
          Get a count of the number of topics in the topic map
 java.util.Set getTopics()
          Get the Topics in this topic map
 java.util.Iterator getTopicsIterator()
          Get an Iterator over the Topics in this map.
 TopicMapUtils getUtils()
          Get the concrete implementation of the TopicMapUtils interface which partners with the concrete implementation of this interface.
 boolean hasMergeMap(Locator mapLocator)
          Determine whether or not the specified resource is listed in an unresolved mergeMap directive for this topic map.
 void removeExternalRef(Locator externalReference)
          Removes a resource from the list of external references of this topic map.
 void removeMergeMap(Locator mapLocator)
          Removes an unresolved mergeMap directive from this topic map.
 void setBaseLocator(Locator base)
          Sets the Locator of the source which generated this topic map.
 void setName(java.lang.String name)
          setName Set the name of the topic map.
 
Methods inherited from interface org.tm4j.topicmap.TopicMapObject
addMultiValuePropertyChangeListener, addMultiValuePropertyChangeListener, addPropertyChangeListener, addPropertyChangeListener, addSourceLocator, addVetoableChangeListener, destroy, fireMultiValuePropertyChange, fireMultiValuePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getID, getResourceLocator, getSourceLocators, getTopicMap, removeMultiValuePropertyChangeListener, removePropertyChangeListener, removePropertyChangeListener, removeSourceLocator, removeVetoableChangeListener, setID, setResourceLocator
 

Method Detail

addAddedTheme

public void addAddedTheme(Topic theme)
Adds an added theme to the topic map.


createAssociation

public Association createAssociation(java.lang.String id)
                              throws DuplicateObjectIDException,
                                     java.beans.PropertyVetoException
Creates a new Association in this TopicMap.

Parameters:
id - the unique identifier to be assigned to the new Association. If this parameter is null, then the Association will be assigned a unique identifier by the back-end implementation.
Returns:
The new Association object.
Throws:
DuplicateObjectIDException - if id specifies an identifier which is already assigned to some other object in this TopicMap.
java.beans.PropertyVetoException - if some listener to the TopicMap vetoes the creation of this object.

createAssociation

public Association createAssociation(java.lang.String id,
                                     Locator resourceLocator,
                                     Topic type,
                                     Topic[] themes)
                              throws DuplicateObjectIDException,
                                     DuplicateResourceLocatorException,
                                     java.beans.PropertyVetoException
Creates a new Association in this topic map

Parameters:
id - the unique identifier to be assigned to the new Association. If this parameter is null, then the Association will be assigned a unique identifier by the back-end implementation.
resourceLocator - the address of the syntactic item which describes this Association (e.g. the address of the XTM association element). This parameter may be NULL for Associations not created from a syntactic item with an address.
type - the topic which defines the class of associations to which the new Association instance belongs. This parameter may be NULL for untyped associations.
themes - the topics which define the scope of the new Association. This parameter may be NULL for Associations created in the unconstrained scope.
Returns:
the new Association object.
Throws:
DuplicateObjectIDException - if id is already assigned to some other object in this TopicMap.
DuplicateResourceLocatorException - if resourceLocator is the address of some other object in this TopicMap.
java.beans.PropertyVetoException - if a listener to the TopicMap vetoes the creation of this Association.

createTopic

public Topic createTopic(java.lang.String id)
                  throws DuplicateObjectIDException,
                         java.beans.PropertyVetoException
Creates a new Topic in this TopicMap.

Parameters:
id - the unique identifier to be assigned to the new Topic. If this parameter is null, then the Topic will be assigned a unique identifier by the back-end implementation.
Returns:
The new Topic object.
Throws:
DuplicateObjectIDException - if id specifies an identifier which is already assigned to some other object in this TopicMap.
java.beans.PropertyVetoException - if some listener to the TopicMap vetoes the creation of this object.

getTopics

public java.util.Set getTopics()
Get the Topics in this topic map

Returns:
An unmodifiable Set of all the topics in the topic map.

getTopicsIterator

public java.util.Iterator getTopicsIterator()
Get an Iterator over the Topics in this map. The iterator returned may be more efficiently implemented than calling getTopics().iterator(). The Iterator returned must be treated as read-only and should not allow delete() operations. The Iterator returned is not guarunteed to be immune to ConcurrentModificationExceptions if the topic map is modified in some way during the course of the iteration.

Returns:
An iterator of Topic objects.

getTopicCount

public int getTopicCount()
Get a count of the number of topics in the topic map

Returns:
The number of topics in the topic map

getTopicByID

public Topic getTopicByID(java.lang.String id)
Gets the topic with the specified unique identifier

Parameters:
id - The identifier of the topic to be retrieved.
Returns:
The topic or null if no match is found

getObjects

public java.util.Collection getObjects()
Gets all the objects in the topic map.

Returns:
A Collection of all of the TopicMapObjects in the topic map.

getObjectByID

public TopicMapObject getObjectByID(java.lang.String id)
Gets the object with the specified unique identifier.

Parameters:
id - The unique identifier of the object to be retrieved.
Returns:
The topic map object which has the specified identifier or null if no match is found.

getObjectByResourceLocator

public TopicMapObject getObjectByResourceLocator(Locator resourceLocator)
Deprecated. from 0.9.0 this method is renamed getObjectBySourceLocator(Locator)

Gets the TopicMapObject which was generated from the specified resource.

Parameters:
resourceLocator - The Locator of the resource to look for.
Returns:
The topic map object which was created to represent the resource identified by locator

getObjectBySourceLocator

public TopicMapObject getObjectBySourceLocator(Locator resourceLocator)
Gets the TopicMapObject which was generated from the specified resource.

Parameters:
resourceLocator - The Locator of the resource to look for.
Returns:
The topic map object which was created to represent the resource identified by locator

getTopicBySubject

public Topic getTopicBySubject(Locator subjectLocator)
Get the topic which is bound to the specified subject

Parameters:
subjectLocator - The locator of the subject to which the topic is bound
Returns:
The topic bound to the specified subject or null if no match is found.

getTopicBySubjectIndicator

public Topic getTopicBySubjectIndicator(Locator subjectIndicatorLocator)
Get the topic which is bound to the subject indicated by the specified resource.

Parameters:
subjectIndicatorLocator - The locator of a resource which indicates the subject of the topic.
Returns:
The topic bound to the specified subject or null if no match is found.

getAddedThemes

public java.util.Collection getAddedThemes()
Get a list of the Topic objects defining the added themes of the topic map.

Returns:
An unmodifiable Collection of the Topic objects defining the added themes of the topic map.
See Also:
Topic

getAssociations

public java.util.Collection getAssociations()
Get a list of the Associations contained in the topic map.

Returns:
An unmodifiable list of the associations contained in the topic map.
See Also:
Association

getAssociationsIterator

public java.util.Iterator getAssociationsIterator()
Get an iterator over all of the Associations in the topic map. The iterator returned may be more efficiently implemented than calling getAssociations().getIterator(). The iterator returned must be read-only, and will not allow any deletions. The Iterator is not guarunteed to be immune to ConcurrentModificationExceptions if the topic map is modified in some way during the iteration.

Returns:
a read-only Iterator of Association objects.

getName

public java.lang.String getName()
getName Get the name of the topic map.


setName

public void setName(java.lang.String name)
setName Set the name of the topic map.

Parameters:
name - The name to be assigned to the topic map.

getUtils

public TopicMapUtils getUtils()
Get the concrete implementation of the TopicMapUtils interface which partners with the concrete implementation of this interface.


getFactory

public TopicMapFactory getFactory()
Get the concrete implementation of the TopicMapFactory interface which partners with the concrete implementation of this interface.


getLocatorFactory

public LocatorFactory getLocatorFactory()
Get the concrete implementation of the LocatorFactory interface which partners with the concrete implementation of this interface. The returned factory will produce Locator objects which may be used with TopicMapObjects in this topic map.


getBaseLocator

public Locator getBaseLocator()
Returns the Locator for the address of the source which generated the topic map. URI references withing the topic map will be resolved relative to this locator.

Returns:
The base resource locator of the topic map.

setBaseLocator

public void setBaseLocator(Locator base)
Sets the Locator of the source which generated this topic map.

Parameters:
base - The base resource locator of the topic map.
See Also:
getBaseLocator()

getMergeMapLocators

public java.util.Collection getMergeMapLocators()
Returns an unmodifiable Map of the unresolved mergeMap directives contained within this topic map. The map key is the Locator of the external topic map to be merged The map value is a Scope object which contains the additional themes to be applied to the external map when it is merged.


getProvider

public TopicMapProvider getProvider()
Returns the TopicMapProvider implementation which provides this TopicMap

Returns:
a implementation of the TopicMapProvider interface

addMergeMap

public void addMergeMap(Locator mapLocator,
                        Topic[] addedThemes)
Adds a new mergeMap directive to this topic map.

Parameters:
mapLocator - The Locator of the external topic map to be merged
addedThemes - An array of Topic objects containing the themes to be added to the topic map when it is merged. Null if there are no themes to be added.

hasMergeMap

public boolean hasMergeMap(Locator mapLocator)
Determine whether or not the specified resource is listed in an unresolved mergeMap directive for this topic map.

Parameters:
mapLocator - The Locator of the external topic map to test for
Returns:
True if the specified external resource is referenced from an unprocessed mergeMap directive, false otherwise.

getMergeMapAddedThemes

public java.util.Set getMergeMapAddedThemes(Locator mapLocator)
Returns the collection of themes to be added to the external topic map resource when it is merged with this map.

Parameters:
mapLocator - The Locator of the external topic map to be merged.
Returns:
If mapLocator specifies the locator of an external topic map to be merged into this topic map, a Set of Topic objects defining the themes to be added to the external topic map will be returned. Otherwise, null is returned.

removeMergeMap

public void removeMergeMap(Locator mapLocator)
Removes an unresolved mergeMap directive from this topic map.

Parameters:
mapLocator - The Locator of the external topic map reference to be removed.

addExternalRef

public void addExternalRef(Locator topicRef)
Adds an external reference from this topic map to another topic map. An external reference represents a element which addresses a Topic which is not contained within the resource addressed by the baseLocator property of this topic map.

Parameters:
topicRef -

The external locator to be added. If the referenced resource is already contained as an external reference or as a merge map, it will not be added. For the purposes of this check, the fragment and query parts of a URILocator are ignored, and only the reference to the complete document will be stored

For example if the reference is to http://www.tm4j.org/example.xtm#topic1, the locator which is tested for and stored will be http://www.tm4j.org/example.xtm This means that multiple references to different topics in the same external topic map will only ever create one external reference.

For other locator notations the complete address is used for this test.


getExternalRefs

public java.util.Set getExternalRefs()
Returns all of the unresolved external references from this topic map.


removeExternalRef

public void removeExternalRef(Locator externalReference)
Removes a resource from the list of external references of this topic map. Although this method is provided, applications wishing to maintain full XTM 1.0 Conformance should never call this method directly. Instead an external reference should be removed by calling TopicMapProvider.mergeTopicMap(TopicMap baseTopicMap, Locator externalTopicMap, Topic[] addedThemes)


getIndexManager

public IndexManager getIndexManager()
Returns the IndexManager object which handles access to all of the indexes for this topic map.


getProperty

public java.lang.Boolean getProperty(java.lang.String propertyName)
Returns the value of a configuration property set for this topic map

Parameters:
propertyName -
Returns:
the value of the specified property or null if this property is not set on the topic map.