org.ceryle.tm
Class TopicMapProcessor

java.lang.Object
  org.ceryle.tm.TopicMapProcessor

public class TopicMapProcessor
extends Object

Defines a processor for topic map events generated by a parser (i.e., a topic map engine), providing access to a consistent TopicMap object and individual objects within. This also makes available a number of static and non-static utility methods for querying and modifying the TopicMap. The latter makes this a rather large class, but for convenience' sake this seems a better approach than breaking off a utility class that would exist in memory anyway.

Speaking of which, there are several utility interfaces and classes that will generally be included with a TopicMapProcessor: Inferencer, PSIUtils, TopicLocatorPool, TopicMapBuilder, TopicNameIndex, plus all the utility classes that are part of TM4J.

Notes

• Up until upgrading from TM4J 0.8.3 to 0.9.7, this class implemented the TopicMapManager interface. It currently does not fully implement the API at this time. Some of the existing notes in the class still pertain to the API and these are not being altered because the plan is to eventually re-implement it.
• This class uses only one TopicMapProvider for all topic maps, hence TopicMapManager's getProvider(TopicMap) will always return the same object, and calling registerProvider(String,Properties) will cause an exception to be thrown. Also, this class maintains a link to the "current" or most recently-created TopicMap, obtained via getTopicMap(). This is the TopicMap operated upon by any TopicMap-modifying methods whose parameters do not include a Locator reference. This is also noted in their documentation (i.e., as the "current" TopicMap).
• If the Ceryle property http://purl.org/ceryle/#tm-ceryleLTMProcessor has either not been set, or is set to "true", the processor will default to using the org.ceryle.tm.LTMProcessor class, otherwise the TM4J org.tm4j.topicmap.utils.LTMBuilder will be used.
• If the Ceryle property http://purl.org/ceryle/prop/#tm-consistentTopicMap has either not been set, or is set to "true", the processor will default to post-processing the TopicMap for consistency, as defined in the XTM 1.0 Specification.
• If the Ceryle property http://purl.org/ceryle/prop/#tm-reflexiveTO is either "true" or unset, reflexive relations are considered as two "To" roles, otherwise as two "From" roles. This corresponds to the same feature in GraphEdge.
• The System property org.tm4j.topicmap.idGenerator is set internally to "org.ceryle.util.IDFactory". This can be changed to a different implementation of TM4J's IDGenerator if a different form of ID is desired.

Since:

JDK1.3

Version:

$Id: TopicMapProcessor.java,v 3.38 2007-06-15 12:09:33 altheim Exp $

Author:

Murray Altheim

See Also:

TopicMap, TopicMapFactory, TopicMapProvider

Field Summary

static boolean	exportImpliedIDs When true, exported topic maps include implied IDs.
static boolean	exportResourceIDs When true, exported topic maps include resource IDs.
static String	idPrefix IDGenerator prefix for all auto-created IDs.
static String	PROP_REFLEXIVE_TO The base URI for the property determining if reflexive relations are represented as two "To" (value="true") or two "From" (value="false", or unset) roles.
static int	PROVIDER_HIBERNATE Indicator constant for Hibernate DB provider implementation.
static int	PROVIDER_MEMORY Indicator constant for in-memory provider implementation.
static int	PROVIDER_OZONE Indicator constant for Ozone DB provider implementation.
protected boolean	useCeryleLTMProcessor When true, uses Ceryle's LTM processor rather than TM4J's.

Constructor Summary

protected

TopicMapProcessor(int backend) Constructor with an int backend indicating which backend the processor should use to store topic map information.

Method Summary

boolean	addType(Topic topic, Topic type) Add the typing Topic to the Topic, returning true if successful.
void	clearTemplates() Clears any existing Association templates from the cache.
static Topic[]	convertScopeToArray(Set scope) Converts a Set of Topics into an array used as a Scope.
static Set	convertScopeToSet(Topic[] scope) Converts an array of Topics (comprising a Scope) into a Set used as a Scope.
Association	createBinaryAssociation(Topic type, Topic[] scope, Topic role1, Topic player1, Topic role2, Topic player2) Creates a binary association between the two players having two roles, a type and optional scope.
Topic	createFacet(Topic faceted, Topic[] facetScope, Topic facetType, Topic facetConstraint, String facetValue) Creates a new facet for the Topic faceted.
TopicMap	createTopicMap(Locator locator) Creates a new, empty TopicMap provided a base Locator.
TopicMap	createTopicMap(TypedInputSource source) Parses a topic map document (in XTM, LTM, or AsTMa= notation), specified by the system identifier (URI) systemId, returning the TopicMap object.
void	deregisterProvider(String id) Deregisters the provider whose ID is id.
String	generateID() Uses the existing IDGenerator to return a unique ID.
String	generateID(TopicMap topicmap) Uses the existing IDGenerator to return a unique ID within the provided TopicMap topicmap.
String	generateID(TopicMap topicmap, String prefix) Uses the existing IDGenerator to return a unique ID within the provided TopicMap topicmap, prefixed with the String prefix.
String	generateIDFromName(TopicMap topicmap, String name) Uses the existing IDGenerator to return a unique ID within the provided TopicMap topicmap based on the String name.
Topic	getAboutTopic(TopicMap topicmap, boolean create) Returns the 'about' Topic of TopicMap topicmap, creating it if it does not yet exist, if the boolean create is true.
Association	getBinaryAssociation(Topic type, Topic topic1, Topic topic2) Returns the first found (existing) Association having type between Topic topic1 and topic2 (paying no attention to which role each plays).
String	getDescription(Topic topic) Returns a textual description of the supplied Topic topic, considered the first encountered Occurrence of a type matching the Ceryle 'description' PSI http://purl.org/ceryle/psi/ceryle/#Description.
String	getDisplayName(Topic topic, Topic[] scope) Returns a String which may be used as a display name in the specified scope.
String	getID() Returns a unique identifying String for this TopicMapProcessor, based on a timestamp.
static String	getIdentifier(TopicMap topicmap) Returns a String identifier for the provided TopicMap topicmap, its name if available, otherwise, its base locator address.
IDFactory	getIDFactory() Returns the existing IDFactory.
String	getIDofTopicType(TopicMap tm, Topic type) Returns the ID of the first-encounted Topic having the given type.
Inferencer	getInferencer() Return a lazily-created Inferencer.
String	getLabel(Association assoc) Returns a label for the provided Association assoc by using its typing topic's display name, one of its base names, or its ID.
String	getLabel(Topic topic) A convenience method that calls getLabel(Topic,Topic[]) with a null Scope parameter.
String	getLabel(Topic topic, Topic[] scope) Returns a label for the provided Topic topic in the optional Topic[] scope, in order of availability.
int	getOccurrenceCount(Topic topic, boolean ignoreUtility) Returns the number of Occurrences.
Occurrence	getOccurrenceOfType(Topic topic, Topic type) Returns the first encountered occurrence in the supplied Topic topic, of an occurrence whose type matches type.
Collection	getOccurrences(Topic topic, boolean ignoreDescription) Returns the Occurrences of Topic topic as a Set.
Topic[]	getOrderedRolesForTemplate(Topic type) Returns the two player Topics of the Association template matching the Topic type, based on the directedness of the Association.
Set	getPlayersOfRoleInTypedAssociation(Topic topic, Topic topicType, Topic assocType, Topic role, Set set) Returns all Topics playing role in associations with the Topic topic.
TopicLocatorPool	getPool() Returns the TopicLocatorPool used by this TopicMapProcessor.
TopicMapProvider	getProvider() A functional synonym for getTopicMapProvider(TopicMap).
TopicMapProvider	getProvider(TopicMap topicmap) Returns the TopicMapProvider for the TopicMap topicmap.
Map	getProviders() Returns a map containing the TopicMapProviders with their IDs as keys.
PSIUtils	getPSI() Returns the PSIUtils used by this TopicMapProcessor.
Vector	getPublicationMetadata(TopicMap topicmap) Returns the publication metadata as a Vector of sorted Occurrences, an empty Vector if none are available.
String	getScopedBaseName(Topic topic, Topic[] scope) Returns a base name String from the Topic topic, giving preference to one in the optional Topic[] scope.
Occurrence	getSelectedOccurrence(Topic topic, boolean acceptAny) Returns the selected occurrence of the provided Topic using the PSI Selected as indicator.
String	getSortName(Topic topic, Topic[] scope) Returns a String which may be used as a sort name in the specified scope.
int	getTemplateCount(TopicMap topicmap) Returns the number of Association templates for the given TopicMap, from the cache.
Association	getTemplateForType(Topic type) Returns the Association used as the template for the provided Topic if it matches any of the available Association Template typing Topics.
String	getTemplateLabel(Topic topic) Returns an appropriate label (display name) for a Topic used as an association template.
Set	getTemplates(TopicMap topicmap) Returns any "association templates" for TopicMap topicmap.
Topic	getTopicByID(TopicMap topicmap, String id) Return the Topic matching the ID id, null if it does not exist.
Topic	getTopicByName(TopicMap tm, String label, boolean create) Returns a Topic with a base name in the XTM 'Display' scope of label, throwing a TopicMapException if unable to locate and/or create the Topic.
TopicMap	getTopicMap(Locator locator) Returns the TopicMap specified by the Locator loc, null if no match is found.
Collection	getTopicMapBaseLocators() Returns a Collection of the base locators of all TopicMap objects currently available from this TopicMapProcessor.
Topic	getTopicMapIdentifier(TopicMap topicmap) Returns a Topic whose subject is its parent TopicMap.
Collection	getTopicMapProviders() Returns the TopicMapProvider for the TopicMap topicmap as a Collection.
Collection	getTopicMaps() Returns a Collection view of the TopicMap objects created by this TopicMapProcessor, an empty set (not null) if none exist.
Set	getTopicProperties(Topic topic, String baseURI) Returns all properties (i.e., Occurrences in the scope of the 'facet' PSI) of the supplied Topic topic having a type whose subject domain starts with the String baseURI.
String	getTopicProperty(Topic topic, Topic type) Returns a property of the supplied Topic topic as an Occurrence having a type.
Collection	getTopicsOfType(TopicMap tm, Topic type) Returns a Collection containing all Topics having the given type.
BaseName	hasLabel(Topic topic, String label, Set scope) A check to see if the Topic already has the label.
Occurrence	hasOccurrence(Topic topic, Topic type, Locator locator) Provided with a Topic topic, returns the Occurrence containing the Locator locator as a data locator (not inline).
Occurrence	hasOccurrence(Topic topic, Topic type, String data) Provided with a Topic topic, returns the Occurrence containing the String data as a data locator (inline).
static boolean	hasSubject(Topic topic, Locator subject) Returns true if the supplied Topic topic has as one of its subject indicators the Locator subject.
static boolean	hasSubject(Topic topic, String uri) Returns true if the supplied Topic topic has as one of its subject indicators a Locator whose address is the URI uri.
boolean	hasTemplateForType(Topic type) Returns true if the provided Topic matches any of the available Association Template typing Topics.
boolean	hasTopicMap(Locator locator) Returns true if the provider contains a TopicMap with the base Locator locator.
boolean	isEditableType(Topic type) Returns true if either the type is null, or it is not one of the standard, non-editable typing Topics.
boolean	isInSubjectDomain(Topic topic, String baseURI) Similar to hasSubject(), returns true if the Topic has a subject matching the base URI part of the supplied Locator.
Locator	isProvidedAs(TopicMap topicmap) Checks to see if the TopicMap topicmap is provided by the provider, returning the Locator by which it is identified.
boolean	isProvidedTopicMap(Locator locator) Returns true if the TopicMap having Locator locator is provided by the TopicMapProvider.
boolean	isProvidedTopicMap(TopicMap topicmap) Returns true if the TopicMap topicmap is provided by the TopicMapProvider (comparing using object equality).
boolean	isSelected(Occurrence occur) Returns true if the provided Occurrence is the selected occurrence of its parent Topic.
boolean	isTemplate(Association assoc) Returns true if the provided Association assoc is an association template, that is, has a scope matching the PSI Template.
boolean	isUtilityOccurrence(Occurrence occur) For lack of a better term, "utility" occurrences are those whose purpose is not meant to be seen (to the user) as an occurrence, such as the Topic color, location, or description.
void	listTemplates(TopicMap topicmap) Prints the list of association templates for the TopicMap topicmap to System.err.
void	listTopicMaps() Prints the current list of stored TopicMaps to the MessageHandler.
void	listTopics(String desc, Collection c) Prints the current list of Topics in the provided Collection to System.err, including the description String.
TopicMap	makeConsistent(TopicMap topicmap) Calls the static XTMUtils method of the same name to process the provided TopicMap topicmap into a consistent topic map as according to the XTM 1.0 Specification.
boolean	matchesSubject(Topic topic, Set topics) Returns true if any of the subject identifiers of topic match any of the subject identifiers of any of the Topics in Set topics.
boolean	matchesTemplate(Topic type, Topic fromRole, Topic toRole) Returns true if the provided parameters match an existing Association template (which must be in the scope of the PSI Template).
void	mergeTopicMap(TopicMap baseTM, Locator mergeLocator) Merges the Topic Map document located at Locator mergeLoc with the base Topic Map baseTM.
Topic	mergeTopics(Set topics) Manually merges the Set of Topics, eliminating duplicate names, occurrences, and subject indicators, returning the merged Topic.
TopicMapProvider	registerProvider(String providerFactoryClassName, Properties props) Registers a new TopicMapProvider with the manager (unimplemented).
TopicMapProvider	registerProvider(String id, String providerFactoryClassName, Properties props) Registers a new provider with the manager.
boolean	removeAssociation(Association assoc) Removes Association assoc, returning true if successful.
Set	removeAssociationsOfType(TopicMap tm, Topic type) Remove all Associations having a type matching the Topic type, as well as the TG ANode and connected GraphEdges.
boolean	removeFacets(Topic faceted, Topic type) Removes any facets of the Topic faceted having typing Topic type.
boolean	removeName(Topic topic, BaseName basename) Remove the BaseName from the Topic, returning true if successful.
boolean	removeOccurrence(Topic topic, Occurrence occur) Removes Occurrence occur from Topic topic, returning true if successful.
boolean	removeTopic(Topic topic) Removes Topic topic, returning true if successful.
boolean	removeTopicMap(Locator locator) Permanently removes the TopicMap having the base locator locator from the provider.
boolean	removeType(Topic topic, Topic type) Remove the typing Topic from the Topic, returning true if successful.
void	reset() Resets the TopicMapProcessor, removing any previously-processed TopicMap objects.
Locator	resolveEntity(Locator source) Attempts to resolve the system identifier in the provided Locator source using the catalog resolver.
void	resolveMergeMaps(TopicMap baseTM) Resolves any mergeMap directives in the provided TopicMap baseTM.
Association	returnAssociationWithID(TopicMap topicmap, String id) Returns either the existing Association whose ID is id, or a new Association if a matching one is not already available.
Locator	returnLocator(String uriref) Returns a Locator whose address is uri.
Locator	returnLocator(TopicMap topicmap, String uriref) Returns a Locator whose address is uri.
Topic	returnTopicByID(TopicMap topicmap, String id) Returns either the existing Topic whose ID is id, or a new Topic if a matching one is not already available.
Topic	returnTopicByLocator(TopicMap topicmap, String id, Locator locator) Returns a Topic having a subject defined by a PSI (a URI, in this case as a Locator), returning null if for some reason the Topic cannot be created.
Topic	returnTopicByURI(TopicMap topicmap, String uri) Returns a Topic having a subject defined by an ID or PSI (a URI), returning null if for some reason the Topic cannot be created.
Topic	returnTopicWithPSI(TopicMap topicmap, String id, String uri) If a Topic having a subject matching the PSI exists, it is returned (note that the supplied ID is ignored in this case).
Set	searchOnLabel(TopicMap topicmap, String searchString, boolean strict, boolean caseSensitive) Search the TopicMap by label (display name), either as a strict or contains match.
Occurrence	setDescription(Topic topic, String id, String text) Sets the textual description of the supplied Topic topic as an Occurrence whose type is the PSI http://purl.org/ceryle/psi/ceryle/#Description, with a required ID value id.
BaseName	setDisplayName(Topic topic, String name, Set scope) A convenience method that sets a variant name String name on the provided Topic topic.
BaseName	setLabel(Topic topic, String label) A convenience method that calls setLabel(Topic,String,Set) with a null Scope parameter.
BaseName	setLabel(Topic topic, String label, Set scope) Sets a label for this Topic to the string label, as a Variant whose parameter (scope) is XTM 1.0's "display".
Occurrence	setOccurrence(Topic topic, String id, Object value, Topic type, Topic[] scope) Sets an occurrence of the supplied Topic topic with an optional typing Topic type and optional Topic[] scope, with a required ID value id.
void	setSelected(Occurrence occur, boolean selected) When selected is true, sets the provided Occurrence as the selected Occurrence of its parent Topic, removing the "Selected PSI" theme from all other Occurrences of the Topic.
Occurrence	setTopicProperty(Topic topic, Topic type, String value) Sets a property of the supplied Topic topic as an Occurrence having a type.
boolean	topicExists(TopicMap topicmap, String id) A convenience method that returns true if a Topic whose ID is id exists.
Set	traverse(Topic topic, int direction, int depth, boolean taxonomic) Traverses the parent TopicMap beginning with Topic topic, in the direction set by the int direction to a depth of depth.
void	writeTopicMap(TopicMap topicmap, File file) A convenience method that serializes the provided TopicMap object to the File file.
void	writeTopicMap(TopicMap topicmap, OutputStream outputstream) Serializes the provided TopicMap object to the OutputStream os.
void	writeTopicMap(TopicMap topicmap, Writer writer) Deprecated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROP_REFLEXIVE_TO

public static final String PROP_REFLEXIVE_TO

The base URI for the property determining if reflexive relations are represented as two "To" (value="true") or two "From" (value="false", or unset) roles. The value is "http://purl.org/ceryle/prop/#tm-reflexiveTO".

See Also:

Constant Field Values

PROVIDER_MEMORY

public static final int PROVIDER_MEMORY

Indicator constant for in-memory provider implementation.

See Also:

Constant Field Values

PROVIDER_OZONE

public static final int PROVIDER_OZONE

Indicator constant for Ozone DB provider implementation.

See Also:

Constant Field Values

PROVIDER_HIBERNATE

public static final int PROVIDER_HIBERNATE

Indicator constant for Hibernate DB provider implementation.

See Also:

Constant Field Values

exportResourceIDs

public static boolean exportResourceIDs

When true, exported topic maps include resource IDs.

exportImpliedIDs

public static boolean exportImpliedIDs

When true, exported topic maps include implied IDs.

idPrefix

public static String idPrefix

IDGenerator prefix for all auto-created IDs.

useCeryleLTMProcessor

protected boolean useCeryleLTMProcessor

When true, uses Ceryle's LTM processor rather than TM4J's. Default true.

Constructor Detail

TopicMapProcessor

protected TopicMapProcessor(int backend)
                     throws TopicMapException

Constructor with an int backend indicating which backend the processor should use to store topic map information.

Allowed values include:

• In-memory (PROVIDER_MEMORY);
• Ozone/OODBMS (PROVIDER_OZONE); or
• Hibernate/JDBC (PROVIDER_HIBERNATE).

This has a protected constructor, as TopicMapProcessor objects should be obtained from the TopicMapServices implementation, TopicMapServices.

Throws:

TopicMapException - if unable to create the provider

Method Detail

getID

public String getID()

Returns a unique identifying String for this TopicMapProcessor, based on a timestamp.

getProviders

public Map getProviders()

Returns a map containing the TopicMapProviders with their IDs as keys.

getProvider

public TopicMapProvider getProvider()

A functional synonym for getTopicMapProvider(TopicMap). Since this class only uses one provider, the TopicMap parameter of the original TopicMapManager API method is ignored.

getProvider

public TopicMapProvider getProvider(TopicMap topicmap)

Returns the TopicMapProvider for the TopicMap topicmap. Because this TopicMapProcessor only uses one provider, the TopicMap parameter value is ignored. The provider is lazily-created; if it hasn't already been created, a call to this method instantiates the TopicMapProvider with the backend determined by the int parameter in the constructor. If for any reason the provider is closed (and nullified), calling this method will re-create it.

This method is part of an implementation of the TopicMapManager interface.

hasTopicMap

public boolean hasTopicMap(Locator locator)
                    throws TopicMapException

Returns true if the provider contains a TopicMap with the base Locator locator.

Throws:

TopicMapException

getTopicMap

public TopicMap getTopicMap(Locator locator)

Returns the TopicMap specified by the Locator loc, null if no match is found. This throws no exceptions on not locating the TopicMap.

This method is part of an implementation of the TopicMapManager interface.

createTopicMap

public TopicMap createTopicMap(Locator locator)
                        throws TopicMapException

Creates a new, empty TopicMap provided a base Locator.

Throws:

TopicMapException - if the TopicMap already exists or can't be created.

createTopicMap

public TopicMap createTopicMap(TypedInputSource source)
                        throws TopicMapException

Parses a topic map document (in XTM, LTM, or AsTMa= notation), specified by the system identifier (URI) systemId, returning the TopicMap object.

NOTE: support for AsTMa= notation is not available in post 1.0alpha11 versions.

Throws:

TopicMapException

removeTopicMap

public boolean removeTopicMap(Locator locator)
                       throws TopicMapException

Permanently removes the TopicMap having the base locator locator from the provider.

Returns:

true if the TopicMap was removed.

Throws:

TopicMapException

mergeTopics

public Topic mergeTopics(Set topics)
                  throws TopicMapException

Manually merges the Set of Topics, eliminating duplicate names, occurrences, and subject indicators, returning the merged Topic. If the Set is empty, null is returned. If the Set contains only one Topic, any duplicates will be removed in it.

Throws:

TopicMapException

resolveEntity

public Locator resolveEntity(Locator source)

Attempts to resolve the system identifier in the provided Locator source using the catalog resolver. If the catalog resolves either reference to a different system identifier, a new Locator will be returned, otherwise the original is simply returned.

resolveMergeMaps

public void resolveMergeMaps(TopicMap baseTM)
                      throws TopicMapProviderException

Resolves any mergeMap directives in the provided TopicMap baseTM.

Throws:

TopicMapProviderException

mergeTopicMap

public void mergeTopicMap(TopicMap baseTM,
                          Locator mergeLocator)
                   throws TopicMapProviderException

Merges the Topic Map document located at Locator mergeLoc with the base Topic Map baseTM.

Throws:

TopicMapProviderException

isProvidedAs

public Locator isProvidedAs(TopicMap topicmap)

Checks to see if the TopicMap topicmap is provided by the provider, returning the Locator by which it is identified. If the TopicMap is not provided at all by the provider, null is returned.

getTopicByName

public Topic getTopicByName(TopicMap tm,
                            String label,
                            boolean create)
                     throws TopicMapException

Returns a Topic with a base name in the XTM 'Display' scope of label, throwing a TopicMapException if unable to locate and/or create the Topic.

Note that this is not optimized as it does not use an index.

Parameters:

tm - the parent TopicMap

label - the label of the returned Topic

create - if true, the Topic will be created if it does not exist

Throws:

TopicMapException - if unable to locate and/or create the Topic

IllegalStateException - if this method is called prior to creation of the TopicMap

removeTopic

public boolean removeTopic(Topic topic)
                    throws TopicMapException

Removes Topic topic, returning true if successful. This will not succeed if the Topic has membership in any associations.

Throws:

TopicMapException

getInferencer

public Inferencer getInferencer()

Return a lazily-created Inferencer.

See Also:

Inferencer, InferencerImpl

convertScopeToArray

public static Topic[] convertScopeToArray(Set scope)

Converts a Set of Topics into an array used as a Scope. This never returns a null, even if the provided Set is null. This is a convenience method.

convertScopeToSet

public static Set convertScopeToSet(Topic[] scope)

Converts an array of Topics (comprising a Scope) into a Set used as a Scope. This never returns a null, even if the provided array is null. This is a convenience method.

getIdentifier

public static String getIdentifier(TopicMap topicmap)

Returns a String identifier for the provided TopicMap topicmap, its name if available, otherwise, its base locator address.

getIDFactory

public IDFactory getIDFactory()

Returns the existing IDFactory. If the IDGenerator is not backed by an IDFactory, returns null.

generateID

public String generateID(TopicMap topicmap)

Uses the existing IDGenerator to return a unique ID within the provided TopicMap topicmap.

generateIDFromName

public String generateIDFromName(TopicMap topicmap,
                                 String name)

Uses the existing IDGenerator to return a unique ID within the provided TopicMap topicmap based on the String name.

generateID

public String generateID(TopicMap topicmap,
                         String prefix)

Uses the existing IDGenerator to return a unique ID within the provided TopicMap topicmap, prefixed with the String prefix. If the IDGenerator instance is not org.ceryle.util.IDFactory, this will ignore the prefix (as it is not supported by the IDGenerator API).

generateID

public String generateID()

Uses the existing IDGenerator to return a unique ID. This is not guaranteed to be unique within any specific TopicMap, only within the IDGenerator itself.

reset

public void reset()

Resets the TopicMapProcessor, removing any previously-processed TopicMap objects. If an error occurs while resetting the TopicMapProvider, it is closed, nullified, and garbage collection is suggested.

getPool

public TopicLocatorPool getPool()

Returns the TopicLocatorPool used by this TopicMapProcessor. This provides a Topic and Locator creation service.

See Also:

TopicLocatorPool

getPSI

public PSIUtils getPSI()

Returns the PSIUtils used by this TopicMapProcessor. This provides a core set of Topic and Locators.

See Also:

TopicLocatorPool

getTopicMapBaseLocators

public Collection getTopicMapBaseLocators()

Returns a Collection of the base locators of all TopicMap objects currently available from this TopicMapProcessor. This returns an empty Collection (not null) if none are available.

This method is part of an implementation of the TopicMapManager interface.

getTopicMapProviders

public Collection getTopicMapProviders()

Returns the TopicMapProvider for the TopicMap topicmap as a Collection. Because this TopicMapProcessor always uses the same Provider, the Collection will always contain just this one object.

This method is part of an implementation of the TopicMapManager interface.

getTopicMaps

public Collection getTopicMaps()

Returns a Collection view of the TopicMap objects created by this TopicMapProcessor, an empty set (not null) if none exist.

This method is part of an implementation of the TopicMapManager interface.

registerProvider

public TopicMapProvider registerProvider(String providerFactoryClassName,
                                         Properties props)
                                  throws TopicMapProviderException

Registers a new TopicMapProvider with the manager (unimplemented). Because this TopicMapProcessor always uses the same Provider, calling this method will throw a TopicMapProviderException whose message states this unimplemented status.

This method is part of an implementation of the TopicMapManager interface.

Throws:

TopicMapProviderException

registerProvider

public TopicMapProvider registerProvider(String id,
                                         String providerFactoryClassName,
                                         Properties props)
                                  throws TopicMapProviderException

Registers a new provider with the manager.

Throws:

TopicMapProviderException

deregisterProvider

public void deregisterProvider(String id)
                        throws TopicMapProviderException

Deregisters the provider whose ID is id.

Throws:

TopicMapProviderException

removeName

public boolean removeName(Topic topic,
                          BaseName basename)
                   throws TopicMapException

Remove the BaseName from the Topic, returning true if successful.

Returns:

true if the name was removed or wasn't a child of the provided Topic

Throws:

TopicMapException

getTopicsOfType

public Collection getTopicsOfType(TopicMap tm,
                                  Topic type)

Returns a Collection containing all Topics having the given type. Returns null if none match.

removeType

public boolean removeType(Topic topic,
                          Topic type)
                   throws TopicMapException

Remove the typing Topic from the Topic, returning true if successful.

Returns:

true if the type was removed or didn't exist to begin with

Throws:

TopicMapException

addType

public boolean addType(Topic topic,
                       Topic type)
                throws TopicMapException

Add the typing Topic to the Topic, returning true if successful. If the Topic already includes the type, nothing happens, but returns true.

Returns:

true if the type was removed or didn't exist to begin with

Throws:

TopicMapException

getIDofTopicType

public String getIDofTopicType(TopicMap tm,
                               Topic type)

Returns the ID of the first-encounted Topic having the given type. This is for situations where there is only expected to be one topic of a given type.

returnTopicByID

public Topic returnTopicByID(TopicMap topicmap,
                             String id)
                      throws TopicMapException

Returns either the existing Topic whose ID is id, or a new Topic if a matching one is not already available. This is different than org.tm4j.topicmap.TopicMap.getTopicByID(String), as it will create and return a new topic if one does not exist. If the provided String id is null, a unique value will be created. If the provided TopicMap topicmap is null, null is returned.

Parameters:

topicmap - a reference to the topic map to be queried

id - the ID to be searched for

Throws:

DuplicateObjectIDException - if the ID specifies an identifier already assigned to a non-Topic object

TopicMapException

returnTopicByLocator

public Topic returnTopicByLocator(TopicMap topicmap,
                                  String id,
                                  Locator locator)

Returns a Topic having a subject defined by a PSI (a URI, in this case as a Locator), returning null if for some reason the Topic cannot be created. If the provided String uri is null, null is returned.

returnTopicByURI

public Topic returnTopicByURI(TopicMap topicmap,
                              String uri)

Returns a Topic having a subject defined by an ID or PSI (a URI), returning null if for some reason the Topic cannot be created. If the provided String uri is an XML Name, it will be treated as an ID, otherwise as a URI. If the provided String uri is null, null is returned.

returnAssociationWithID

public Association returnAssociationWithID(TopicMap topicmap,
                                           String id)
                                    throws TopicMapException

Returns either the existing Association whose ID is id, or a new Association if a matching one is not already available. If the provided String id is null, a unique value will be created. If the provided TopicMap topicmap is null, null is returned.

Parameters:

topicmap - a reference to the topic map to be queried

id - the ID to be searched for

Throws:

DuplicateObjectIDException - if the ID specifies an identifier already assigned to a non-Association object

TopicMapException

getTopicByID

public Topic getTopicByID(TopicMap topicmap,
                          String id)
                   throws TopicMapException

Return the Topic matching the ID id, null if it does not exist. This is different than returnTopicByID(TopicMap,String), as it will return null rather than create a new Topic. If the provided String id is null, null is returned. If the provided TopicMap topicmap is null, null is returned.

Parameters:

topicmap - a reference to the topic map to be queried

id - the ID identifier used as a query.

Returns:

the Topic whose ID matches the provided 'id', null if no match is found.

Throws:

TopicMapException - if the node matching the ID is not a Topic object.

hasOccurrence

public Occurrence hasOccurrence(Topic topic,
                                Topic type,
                                Locator locator)

Provided with a Topic topic, returns the Occurrence containing the Locator locator as a data locator (not inline). If the optional Topic type is included, it acts as a filter on acceptable Occurrences. If no Occurrence matches, null is returned.

hasOccurrence

public Occurrence hasOccurrence(Topic topic,
                                Topic type,
                                String data)

Provided with a Topic topic, returns the Occurrence containing the String data as a data locator (inline). If the optional Topic type is included, it acts as a filter on acceptable Occurrences. If no Occurrence matches, null is returned.

topicExists

public boolean topicExists(TopicMap topicmap,
                           String id)

A convenience method that returns true if a Topic whose ID is id exists.

searchOnLabel

public Set searchOnLabel(TopicMap topicmap,
                         String searchString,
                         boolean strict,
                         boolean caseSensitive)

Search the TopicMap by label (display name), either as a strict or contains match. Returns the Set of Topics, an empty Set if no matches.

makeConsistent

public TopicMap makeConsistent(TopicMap topicmap)

Calls the static XTMUtils method of the same name to process the provided TopicMap topicmap into a consistent topic map as according to the XTM 1.0 Specification.

Returns:

the provided TopicMap

See Also:

XTMUtils

hasSubject

public static boolean hasSubject(Topic topic,
                                 String uri)

Returns true if the supplied Topic topic has as one of its subject indicators a Locator whose address is the URI uri. This is a convenience method for hasSubject(Topic,Locator), returning false if any exception occurs during Locator creation.

hasSubject

public static boolean hasSubject(Topic topic,
                                 Locator subject)

Returns true if the supplied Topic topic has as one of its subject indicators the Locator subject. This includes the subjects of all merged topics.

matchesSubject

public boolean matchesSubject(Topic topic,
                              Set topics)
                       throws TopicMapException

Returns true if any of the subject identifiers of topic match any of the subject identifiers of any of the Topics in Set topics.

Throws:

TopicMapException

isInSubjectDomain

public boolean isInSubjectDomain(Topic topic,
                                 String baseURI)

Similar to hasSubject(), returns true if the Topic has a subject matching the base URI part of the supplied Locator. I.e., if any of the subject indicator URIs of the Topic match character-for-character with the supplied URI (using java.lang.String.startsWith(String).

setLabel

public BaseName setLabel(Topic topic,
                         String label)
                  throws TopicMapException

A convenience method that calls setLabel(Topic,String,Set) with a null Scope parameter.

Throws:

TopicMapException

setLabel

public BaseName setLabel(Topic topic,
                         String label,
                         Set scope)
                  throws TopicMapException

Sets a label for this Topic to the string label, as a Variant whose parameter (scope) is XTM 1.0's "display". If the Topic already has this particular label the method is ignored.

NOTE: This first locates any existing base names having a "display" variant name, eliminates those base names, and sets this as the only one. This is necessarily ignoring scoping on the base name itself, and is a bit dangerous if the base name itself if valuable. The problem with only removing the variant is we end up with a bunch of basenames whose only purpose was to provide a display name.

If the Scope is specified, it will be added to the resulting basename. This also allows for multiple display names on the same Topic.

Parameters:

topic - the Topic on which to set the name/label

label - the String used as the label

scope - an optional scope (as a Set of Topics) on the name/label

Returns:

the created BaseName (which has a display variant containing the value)

Throws:

TopicMapException

hasLabel

public BaseName hasLabel(Topic topic,
                         String label,
                         Set scope)
                  throws TopicMapException

A check to see if the Topic already has the label. If scope is specified, the BaseName must be in the specified Scope in addition to being a display variant.

Parameters:

topic - the Topic to check

label - the label to check for

scope - the optional Scope of the BaseName; if present, it must match

Throws:

TopicMapException - if anything goes wrong

setDisplayName

public BaseName setDisplayName(Topic topic,
                               String name,
                               Set scope)
                        throws TopicMapException

A convenience method that sets a variant name String name on the provided Topic topic. The optional Topic[] scope is used to provide individual Topic parameters on the display variant (In XTM, scope and parameters on variants are semantically identical). This necessarily creates a new BaseName as its parent container.

Returns:

the created BaseName (which has a display variant containing the value)

Throws:

TopicMapException

getDisplayName

public String getDisplayName(Topic topic,
                             Topic[] scope)

Returns a String which may be used as a display name in the specified scope.

getSortName

public String getSortName(Topic topic,
                          Topic[] scope)

Returns a String which may be used as a sort name in the specified scope.

getLabel

public String getLabel(Topic topic)

A convenience method that calls getLabel(Topic,Topic[]) with a null Scope parameter.

getLabel

public String getLabel(Topic topic,
                       Topic[] scope)

Returns a label for the provided Topic topic in the optional Topic[] scope, in order of availability. This is prioritized as:

1. its display name in the provided scope
2. a base name in the provided scope
3. any of its base names
4. or finally, its topic ID

If for some reason the supplied Topic is null, a '?' is returned.

See Also:

getDisplayName(Topic,Topic[])

getLabel

public String getLabel(Association assoc)

Returns a label for the provided Association assoc by using its typing topic's display name, one of its base names, or its ID. If the Association has no typing topic, its own ID is used. Failing that, a generic association String is used.

getTemplateLabel

public String getTemplateLabel(Topic topic)

Returns an appropriate label (display name) for a Topic used as an association template. This is the base name of the Topic scoped by the Ceryle Template PSI. If the Topic does not contain a name in the Template scope, the normal getLabel(Topic) method is used. This is a convenience method.

getScopedBaseName

public String getScopedBaseName(Topic topic,
                                Topic[] scope)

Returns a base name String from the Topic topic, giving preference to one in the optional Topic[] scope. Returns null if unable to find a base name in the scope, if the scope if provided.

createBinaryAssociation

public Association createBinaryAssociation(Topic type,
                                           Topic[] scope,
                                           Topic role1,
                                           Topic player1,
                                           Topic role2,
                                           Topic player2)
                                    throws TopicMapException

Creates a binary association between the two players having two roles, a type and optional scope. Returns the created Association.

Throws:

TopicMapException

removeAssociationsOfType

public Set removeAssociationsOfType(TopicMap tm,
                                    Topic type)

Remove all Associations having a type matching the Topic type, as well as the TG ANode and connected GraphEdges.

Returns:

a Set containing all the player Topics encountered

removeAssociation

public boolean removeAssociation(Association assoc)

Removes Association assoc, returning true if successful.

getBinaryAssociation

public Association getBinaryAssociation(Topic type,
                                        Topic topic1,
                                        Topic topic2)

Returns the first found (existing) Association having type between Topic topic1 and topic2 (paying no attention to which role each plays). If type is null this will return the first Association returned by the Iterator. This returns null if no Association is found between the two Topics.

getPlayersOfRoleInTypedAssociation

public Set getPlayersOfRoleInTypedAssociation(Topic topic,
                                              Topic topicType,
                                              Topic assocType,
                                              Topic role,
                                              Set set)
                                       throws TopicMapException

Returns all Topics playing role in associations with the Topic topic. If assocType is included, it acts as an Association type filter. If the optional Topic topicType is included, this acts as an additional filter, returning only topics matching that type. If the optional set is supplied, it will be used as the returned container, otherwise a new Set will be created.

Parameters:

topic - the provided Topic connected via associations

topicType - the optional type filter on acceptable Topics

assocType - the optional type filter on acceptable associations

role - the role that the returned Topics must play

set - the optionally-supplied Set container for the result

Returns:

matching topics, or an empty Set (rather than null) if there is no match.

Throws:

TopicMapException

createFacet

public Topic createFacet(Topic faceted,
                         Topic[] facetScope,
                         Topic facetType,
                         Topic facetConstraint,
                         String facetValue)
                  throws TopicMapException

Creates a new facet for the Topic faceted. The facet is a Topic having a typing Topic type, and a 'facet' property identifier for a property-value (occurrence). If the facetValue is supplied (i.e., non-null), a facet property (an Occurrence) of type 'facetValue" is created, otherwise only the facet Topic is created.

Parameters:

faceted - the Topic receiving the facet (required)

facetScope - optional scope on facet association

facetType - the class that the facet will be an instance of (required)

facetConstraint - the facet constraint or occurrence type (optional; facetValue PSI assumed if null)

facetValue - optional String value (if non-null, it is stored as the facet property 'facetValue')

Returns:

the created facet Topic

Throws:

TopicMapException - if any problems occur during facet creation

removeFacets

public boolean removeFacets(Topic faceted,
                            Topic type)
                     throws TopicMapException

Removes any facets of the Topic faceted having typing Topic type. unimplemented

Parameters:

faceted - the Topic to have the facet removed

type - the facet type to remove

Returns:

true if any facets were removed

Throws:

TopicMapException

setDescription

public Occurrence setDescription(Topic topic,
                                 String id,
                                 String text)
                          throws TopicMapException

Sets the textual description of the supplied Topic topic as an Occurrence whose type is the PSI http://purl.org/ceryle/psi/ceryle/#Description, with a required ID value id.

This replaces any previous Occurrence used as a description. Any references to the previous description's resource ID may then be invalid. If the supplied ID value is null, removes any existing description. If the supplied ID value is null, a value will be supplied.

Returns:

the new Occurrence, null if the supplied value is null

Throws:

TopicMapException

setTopicProperty

public Occurrence setTopicProperty(Topic topic,
                                   Topic type,
                                   String value)
                            throws TopicMapException

Sets a property of the supplied Topic topic as an Occurrence having a type. Setting it to null removes the property.

The Scope used for this is derived from the Ceryle Facet PSI, considered as a monadic predicate, adding a simple 'facet' to the Topic occurrence.

Returns:

the ID of the new Occurrence, null if any original property is removed

Throws:

TopicMapException

getTopicProperty

public String getTopicProperty(Topic topic,
                               Topic type)
                        throws TopicMapException

Returns a property of the supplied Topic topic as an Occurrence having a type. Note that even if this method discovers more than one matching Occurrence, only the first is returned (with no other notification). Responsibility for multiple properties must be handled elsewhere.

The Scope used for this is derived from the Ceryle Facet PSI, considered as a monadic predicate, adding a simple 'facet' to the Topic occurrence.

Returns:

the value of the property as a String, or null if no such property is set.

Throws:

TopicMapException

getTopicProperties

public Set getTopicProperties(Topic topic,
                              String baseURI)
                       throws TopicMapException

Returns all properties (i.e., Occurrences in the scope of the 'facet' PSI) of the supplied Topic topic having a type whose subject domain starts with the String baseURI.

The Scope used for this is derived from the Ceryle Facet PSI, considered as a monadic predicate, adding a simple 'facet' to the Topic occurrence.

Returns:

the Set of matching Occurrences, an empty Set if no matches

Throws:

TopicMapException

isSelected

public boolean isSelected(Occurrence occur)

Returns true if the provided Occurrence is the selected occurrence of its parent Topic. This is true if: (a) there is only one Occurrence in the Topic; or (b) the supplied Occurrence has a scope including the PSI "Selected".

setSelected

public void setSelected(Occurrence occur,
                        boolean selected)
                 throws TopicMapException

When selected is true, sets the provided Occurrence as the selected Occurrence of its parent Topic, removing the "Selected PSI" theme from all other Occurrences of the Topic. When selected is false, removes the "Selected PSI" theme from the provided Occurrence. Note that this may leave no Occurrence selected. (Occurrence selection is used primarily for automatic inclusion of one of a Topic's occurrences as part of text auto-generation.)

Throws:

TopicMapException

getSelectedOccurrence

public Occurrence getSelectedOccurrence(Topic topic,
                                        boolean acceptAny)
                                 throws TopicMapException

Returns the selected occurrence of the provided Topic using the PSI Selected as indicator. If none of the Occurrences are marked as such and either acceptAny is true or there is only one Occurrence, returns the first returned by the iterator, otherwise null. If the Topic has no Occurrences, returns null. Note that this method will not return "utility" occurrences (description, node location or color).

Throws:

TopicMapException

setOccurrence

public Occurrence setOccurrence(Topic topic,
                                String id,
                                Object value,
                                Topic type,
                                Topic[] scope)
                         throws TopicMapException

Sets an occurrence of the supplied Topic topic with an optional typing Topic type and optional Topic[] scope, with a required ID value id. This replaces any previous Occurrence of the same type and scope. Any references to the previous description's resource ID may then be invalid. If the supplied value is null, removes any existing occurrence of the same type and scope (without creating any new occurrence). If the supplied ID value is null, a value will be created.

Parameters:

topic - the Topic receiving the new occurrence

id - the ID value of the occurrence

value - the value of the occurrence, either a String or Locator

type - the optional type of the occurrence

scope - the optional scope on the occurrence

Returns:

the new Occurrence, null if the supplied value is null

Throws:

TopicMapException

getOccurrenceOfType

public Occurrence getOccurrenceOfType(Topic topic,
                                      Topic type)

Returns the first encountered occurrence in the supplied Topic topic, of an occurrence whose type matches type. Returns null if no matching occurrence is found.

getDescription

public String getDescription(Topic topic)

Returns a textual description of the supplied Topic topic, considered the first encountered Occurrence of a type matching the Ceryle 'description' PSI http://purl.org/ceryle/psi/ceryle/#Description. If no description is available or its value is null, empty or composed of only whitespace, null is returned. This does assume that the data is inline.

The returned string is whitespace normalized.

getOccurrences

public Collection getOccurrences(Topic topic,
                                 boolean ignoreDescription)
                          throws TopicMapException

Returns the Occurrences of Topic topic as a Set. If ignoreDescription is true, does not include the topic description or location (which are types of Occurrences).

Returns:

the Set of occurrences of Topic, absent the description when 'ignoreDescription' is true.

Throws:

TopicMapException

getOccurrenceCount

public int getOccurrenceCount(Topic topic,
                              boolean ignoreUtility)

Returns the number of Occurrences. If ignoreUtility is true, ignores (i.e., does not count) the presence of the topic description, node location and color (which are types of Occurrences). Rather than throw an exception on obtaining the PSI topics, this method quietly returns 0 on error.

Returns:

an int indicating the number of Occurrences.

isUtilityOccurrence

public boolean isUtilityOccurrence(Occurrence occur)
                            throws TopicMapException

For lack of a better term, "utility" occurrences are those whose purpose is not meant to be seen (to the user) as an occurrence, such as the Topic color, location, or description. These are checked via their associated PSIs.

Throws:

TopicMapException

removeOccurrence

public boolean removeOccurrence(Topic topic,
                                Occurrence occur)
                         throws TopicMapException

Removes Occurrence occur from Topic topic, returning true if successful. This will not succeed if anything is linked to the Occurrence.

Throws:

TopicMapException

writeTopicMap

public void writeTopicMap(TopicMap topicmap,
                          File file)

A convenience method that serializes the provided TopicMap object to the File file.

writeTopicMap

public void writeTopicMap(TopicMap topicmap,
                          OutputStream outputstream)

Serializes the provided TopicMap object to the OutputStream os.

writeTopicMap

public void writeTopicMap(TopicMap topicmap,
                          Writer writer)

Deprecated.

Serializes the provided TopicMap object to the Writer writer.

getAboutTopic

public Topic getAboutTopic(TopicMap topicmap,
                           boolean create)
                    throws TopicMapException

Returns the 'about' Topic of TopicMap topicmap, creating it if it does not yet exist, if the boolean create is true. The "about" Topic is a Topic whose subject is the parent TopicMap containing the about Topic, used as a metadata container for the document. This doesn't use a <resourceRef> pointing to the system identifier of the XTM document, as this may change over time, or due to multiple-document merging. This is considered a stable container for any metadata about the TopicMap itself. A TopicMapException is thrown if there are more than one Topic of type 'About' (a Ceryle PSI).

Throws:

TopicMapException

getPublicationMetadata

public Vector getPublicationMetadata(TopicMap topicmap)
                              throws TopicMapException

Returns the publication metadata as a Vector of sorted Occurrences, an empty Vector if none are available. The Occurrences returned are all in the Scope of the "About" PSI (others will be ignored), and have types indicating Dublin Core or related publication metadata (e.g., title, description, creator, creation date, etc.). They will be returned in the order intended for publication (as in the PSI publication metadata block).

Throws:

TopicMapException

clearTemplates

public void clearTemplates()

Clears any existing Association templates from the cache.

matchesTemplate

public boolean matchesTemplate(Topic type,
                               Topic fromRole,
                               Topic toRole)

Returns true if the provided parameters match an existing Association template (which must be in the scope of the PSI Template). This method allows and returns false for any parameter being null to simplify calls. An Association Template is defined here by way of an LTM example:

     type([fromRole] : PSIfrom, [toRole] : PSIto ) / Template
 

Note that reflexive relations have two 'To' role types (rather than two 'From' role types.

getOrderedRolesForTemplate

public Topic[] getOrderedRolesForTemplate(Topic type)

Returns the two player Topics of the Association template matching the Topic type, based on the directedness of the Association. The order will be (from,to) for directed relations, and an arbitrary order for either reflexive or undirected relations. For templates that are typed as assertions, this will use (subject,object) rather than (from,to).

If there isn't an Association template for the provided Topic, null is returned. For example, getOrderedRolesForTemplate(SuperclassSubclass) ("kind of") would return { Subclass, Superclass } in (subject,object) sentence order.

hasTemplateForType

public boolean hasTemplateForType(Topic type)

Returns true if the provided Topic matches any of the available Association Template typing Topics. This only matches the Association type and pays no attention to the roles, though the match must be in the scope of the PSI Template (i.e., how templates are discerned from other Associations). This method allows and returns false for either a null parameter or the Topic not having a parent TopicMap.

isTemplate

public boolean isTemplate(Association assoc)
                   throws TopicMapException

Returns true if the provided Association assoc is an association template, that is, has a scope matching the PSI Template.

Throws:

TopicMapException

getTemplateForType

public Association getTemplateForType(Topic type)

Returns the Association used as the template for the provided Topic if it matches any of the available Association Template typing Topics.

getTemplateCount

public int getTemplateCount(TopicMap topicmap)

Returns the number of Association templates for the given TopicMap, from the cache. If the TopicMap has not been processed previously it is not in the cache and the method returns -1.

getTemplates

public Set getTemplates(TopicMap topicmap)

Returns any "association templates" for TopicMap topicmap. These are Associations scoped by the "Template" PSI, used to determine edge direction in the displayed graph. Unless cleared, the Association templates are maintained as a Set.

Since this method is often called repeatedly (e.g., during visualization), the TopicMaps used as parameters for this method are kept in a cache (a Hashtable) and returned using the TopicMap as a key.

The cache is cleared with clearTemplates().

Parameters:

topicmap - the TopicMap to query for templates

isEditableType

public boolean isEditableType(Topic type)

Returns true if either the type is null, or it is not one of the standard, non-editable typing Topics. These include the XTM class-instance and superclass-subclass relations, and the hasFacet relation. This is a convenience method.

traverse

public Set traverse(Topic topic,
                    int direction,
                    int depth,
                    boolean taxonomic)

Traverses the parent TopicMap beginning with Topic topic, in the direction set by the int direction to a depth of depth. When the boolean taxonomic is true, traverses associations based on the association roles having a subject of "superclass" and "subclass". When false, traverses based on the roles being a subclass of the Ceryle PSIs "From" and "To" (which may be used to type any role-playing topics).

The direction value may be Traverse.TRAVERSE_TO ("in the direction of graph arrows"), Traverse.TRAVERSE_FROM ("against the direction of graph arrows"), or TRAVERSE_ANY (ignoring direction).

Parameters:

topic - the starting point of the traversal

direction - traversal direction

depth - depth of traversal (in levels of Associations)

taxonomic - for directed traversals, only traverse superclass-subclass relations

Returns:

the set of Topics encountered during traversal, an empty set if none

returnLocator

public Locator returnLocator(String uriref)
                      throws TopicMapException

Returns a Locator whose address is uri.

Note that this method is unlike returnLocator(TopicMap,String) in that the returned Locator is not associated with any TopicMap object.

Parameters:

uriref - the String used as the locator address

Throws:

TopicMapException

returnLocator

public Locator returnLocator(TopicMap topicmap,
                             String uriref)
                      throws TopicMapException

Returns a Locator whose address is uri.

This is a convenience method that calls TopicLocatorPool.returnLocator(TopicMap,String).

Parameters:

topicmap - a reference to the topic map to be queried

uriref - the String used as the locator address

Throws:

TopicMapException

returnTopicWithPSI

public Topic returnTopicWithPSI(TopicMap topicmap,
                                String id,
                                String uri)
                         throws TopicMapException

If a Topic having a subject matching the PSI exists, it is returned (note that the supplied ID is ignored in this case). Otherwise, creates a Topic whose ID is id and adds a subject indicator with the String uri considered as a PSI.

This is a convenience method that calls TopicLocatorPool.returnTopicWithPSI(TopicMap,String,String).

Parameters:

topicmap - a reference to the topic map to be queried

id - the ID to be used for the new Topic

uri - the String used as the locator address

Throws:

TopicMapException

getTopicMapIdentifier

public Topic getTopicMapIdentifier(TopicMap topicmap)
                            throws TopicMapException

Returns a Topic whose subject is its parent TopicMap. The returned Topic has a type of XXX and a <subjectIdentity> containing a resourceRef pointing to the TopicMap. This is a convenience method. (FIXME unimplemented)

Throws:

TopicMapException

isProvidedTopicMap

public boolean isProvidedTopicMap(Locator locator)

Returns true if the TopicMap having Locator locator is provided by the TopicMapProvider.

isProvidedTopicMap

public boolean isProvidedTopicMap(TopicMap topicmap)

Returns true if the TopicMap topicmap is provided by the TopicMapProvider (comparing using object equality).

listTopics

public void listTopics(String desc,
                       Collection c)

Prints the current list of Topics in the provided Collection to System.err, including the description String.

listTopicMaps

public void listTopicMaps()

Prints the current list of stored TopicMaps to the MessageHandler.

listTemplates

public void listTemplates(TopicMap topicmap)

Prints the list of association templates for the TopicMap topicmap to System.err.