Package net.ontopia.topicmaps.utils

This package provides topic map utility classes, which are a toolkit for working with the topic map model provided by the core interfaces.

See:
Description

Interface Summary

AssociationWalkerListenerIF

PUBLIC: This interface defines a listener to the AssociationWalker.

Class Summary

ApplicableInContextDecider	INTERNAL: Decider that decides whether the ScopedIF's scope is applicable in the user context.
AssociationBuilder	PUBLIC: A helper class that makes it easier to build associations.
AssociationWalker	PUBLIC: Computes the transitive closure of a relation characterized by two specific roles within a specific association type.
BaseNameComparator	Deprecated. Use TopicNameComparator instead.
BaseNameGrabber	Deprecated. use TopicNameGrabber instead.
CharacteristicUtils	INTERNAL: Characteristic processing utilities.
ClassInstanceUtils	INTERNAL: Utilities for working with class-instance relationships.
CopyUtils	INTERNAL: Utilities for copying topic map data.
DisplayNameGrabber	Deprecated. Since 1.1.
DuplicateSuppressionUtils	PUBLIC: A helper class that can remove duplicate objects from a topic map.
IdentityUtils	INTERNAL: Utilities for working with identities of topic map objects.
ImportExportUtils	PUBLIC: Utilities for importing and exporting topic maps.
IntersectionOfContextDecider	INTERNAL: Decider that decides whether the ScopedIF's scope is an intersection of the user context or not.
KeyGenerator	PUBLIC: Utilities for generating keys from complex topic map objects.
MergeReference	INTERNAL: A topic map reference that uses a TopicMapRepositoryIF to retrieve a list of topic maps and create a new merged topic map from them.
MergeUtils	PUBLIC: Utilities for merging topics and topic maps.
NameGrabber	INTERNAL: Grabber that grabs the most suitable name from a topic, measured by whether it contains a particular theme in its scope.
NameStringifier	INTERNAL: Stringifier that stringifies TopicNameIFs and VariantNameIFs by calling their getValue() method.
NoFollowTopicRefExternalReferenceHandler	PUBLIC: An implementation of ExternalReferenceHandlerIF that prevents the traversal of external topic references.
NullResolvingExternalReferenceHandler	PUBLIC: An implementation of ExternalReferenceHandlerIF that prevents the traversal of external references by returning null from all methods.
ObjectIdComparator	INTERNAL: Comparator that compares object ids of TMObjectIF objects.
ObjectIdGrabber	INTERNAL: Grabber that grabs the object id of the TMObjectIF given to it.
ObjectIdStringifier	INTERNAL: Stringifier that returns the object id of a topic map object.
ObjectTopicIdStringifier	INTERNAL: Stringifier that returns the object id of the topic that belongs to this tmobject.
PSI	INTERNAL: This class collects core PSIs in a single place as a convenience for topic map developers.
QNameLookup	PUBLIC: A utility class for producing full URIs from QNames.
QNameRegistry	PUBLIC: A utility class for producing full URIs from QNames.
RolePlayerGrabber	INTERNAL: Grabber that grabs the topic that plays the role in the association role.
RolesGrabber	INTERNAL: Grabber that grabs the association roles of an association.
SameStoreFactory	PUBLIC: A store factory that always returns the store given to it via its constructor.
ScopedIFComparator	INTERNAL: Comparator that compares ScopedIF objects based on their applicability in the specified scope.
ScopeUtils	INTERNAL: Scope processing utilities.
SubjectIdentityDecider	INTERNAL: Decider that decides whether the object is an instance of a topic with the given subject identifier.
SubsetOfContextDecider	INTERNAL: Decider that decides whether the ScopedIF's scope is a subset of the user context or not.
SupersetOfContextDecider	INTERNAL: Decider that decides whether the ScopedIF's scope is a superset of the user context or not.
TMDeciderUtils	INTERNAL: Utility class for creating topic map-based deciders.
TopicCharacteristicGrabbers	INTERNAL: A convenience class for creating grabbers that grab specific topic characteristics, using various criteria, including scope.
TopicComparators	INTERNAL: A collection of topic related comparators.
TopicComparators.CaseInsensitiveStringifierComparator	INTERNAL: Case in-sensitive string comparator that is able to handle null values.
TopicMapSynchronizer	PUBLIC: Implementation of the TMSync algorithm.
TopicNameComparator	INTERNAL: Comparator that first sorts by type then by scope, where untyped base names are ordered before typed ones.
TopicNameGrabber	INTERNAL: Grabber that grabs the most appropriate basename from a topic.
TopicStringifiers	PUBLIC: Creates stringifiers that extract strings representing names from topics, according to various criteria, including scope.
TopicStringifiers.FastSortNameStringifier
TopicTreeBuilder	EXPERIMENTAL.
TopicTreeNode	EXPERIMENTAL.
TopicTreeRendrer	EXPERIMENTAL.
TopicVariantNameGrabber	INTERNAL: Grabber that grabs the most highest ranked variant name by scope from a topic, ignoring the scope of the base names.
TypedIFComparator	INTERNAL: Comparator that grabs the type of the comparable objects using TypedIF.getType() , and passes those two topics to it's subcomparator.
TypedIFGrabber	INTERNAL: Grabber that grabs the type property of the TypedIF object given to it.
TypedIFStringifier	INTERNAL: Stringifier that generates a string representation of the type property of the object given to it.
TypeHierarchyUtils	INTERNAL: This class provides utility functions for traversing class hierarchies which are expressed using the Published Subject Indicators (PSIs) defined by the XTM 1.0 Specification.
UnconstrainedScopeDecider	INTERNAL: This decider accepts all objects in the unconstrained scope, letting a sub-decider rule for object not in the unconstrained scope.
VariantNameGrabber	INTERNAL: Grabber that grabs the most highest ranked variant name by scope from a basename.

Package net.ontopia.topicmaps.utils Description

This package provides topic map utility classes, which are a toolkit for working with the topic map model provided by the core interfaces. Note that these are supplementary to the core interfaces, and more likely to change in the future.

Note: In the doc comments, "iff" means "if and only if".

The "experimental" utilities are not (yet) fully doc-commented.

Package Specification

Utilities for interacting with topic maps and topic map objects. The design strategy of this package is to provide similar methods for similar facilites wherever possible; also, to provide similar ranges of facilities for similar objects.
These utilities use the core interfaces as their only interface with topic maps.

Class and Interface Summaries

AssociationWalker

The AssociationWalker class allows an application to treat a proper part of the topic map as a transitive binary relation between topics. This is done by computing the transitive closure of a relation characterized by two specific roles within a specific association type; this closure is then available as an object, which represents the resulting transitive binary relation between topics. The paths traversed within the topic map in order to find these topics are also retained, if required.

AssociationWalkerListenerIF

An interface implemented by objects which "listen" to the progess of an AssociationWalker. The listener is "told" each time a topic, association, associated-topic structure, with the appropriate association-type and rolespecs, is found by the walker. Event processing controlling the termination of the walk can be implemented using this interface.

CharacteristicUtils

Utilities for getting characteristics of topics (names. occurrences and association roles). Some are included only for completeness - the main value of this class is in the methods to get characteristics from given collections (rather than single objects), and also the handling of nested variant names.

ConflictingSubjectHandlerIF

An interface which is used by MergeUtils (see below); this interface is implemented by objects which can resolve subject identity conflicts on topics.

DeletionUtils

Utilities supporting the deletion of topicmap objects from a topic map.
The utilities in this class are of two kinds: for each kind of topicmap object, there is a method for determining whether it is "removable"; and a method for removing it. These are not interdependent; if you ask for an object to be removed after finding out that it is not "removeable", it will still be removed.
Removing a topic removes all uses of that topic in the topic map. See the Developers Guide for further discussion of topic deletion.

Scope Utilities

The Scope utilites are in classes ScopeUtils, ScopedIFComparator, InIdenticalScopeDecider, InNarrowScopeDecider, InBroadScopeDecider, InRelatedScopeDecider.
The overall purpose of these utilites is to provide facilites for handling scopes on topic charactersitics. Details of each utility function are provided in the doc comments. Note that the empty scope is the most general scope ("unconstrained") - rather like "ace high" in a pack of playing cards.
The decider classes all implement DeciderIF in net.ontopia.utils; they provide simple interfaces to scope comparison logic on individual scoped objects, implemented in ScopeUtils. ScopeUtils makes use of methods provided by ScopedIF in net.ontopia.topicmaps.core, and also provides methods for ranking and filtering collections of scoped objects by scope.
ScopedIFComparator is used by ScopeUtils; it makes use of methods in ScopedIF, to implement a comparator which can be used to sort scoped objects by their applicability in a given scope.

KeyGenerator

Makes a key for either an occurrence or base name - these keys use internal object IDs in their construction. These keys are used in MergeUtils to detect duplicate characteristics on merged topics.

MergeUtils

Utilites for merging topic maps. This area is still under development; these utilities are prototypes.

Grabber utilities

All these utilities clothe logic to access data, as GrabberIF objects, see net.ontopia.utils.

BaseNameGrabber

Selects and returns one basename for a given topic, selected according to a comparator which is determined when an instance of this class is created. This comparator may be given (as a parameter which is a Comparator), or alternatively, a scope may be given (i.e. a collection of topics serving as a scope in the topicmap) - in which case, an instanceof ScopedIFComparator (see below) is created and used.

DisplayNameGrabber

Selects & returns a name to display for a topic. This is a display name, if available, otherwise a base name. See doc comments for details.

VariantNameGrabber

Selects and returns a variant name for a base name. The comparator used is determined as in BaseNameGrabber above.

ObjectIdGrabber

Returns the internal object id of an arbitrary topicmap object. Do not use this to get round the core interface restrictions on how you access topicmap objects.

RoleGrabber

Returns all the association roles of a given association, as a collection.

RolePlayerGrabber

Returns the topic which is playing the role in a given association role.

TypedIFGrabber

Returns the topic which is the type of a given (singly) typed topic map object.

Stringifier utilities

These generate string representations of topic map objects, which are used by various other classes.
NameStringifier and ObjectIdStringifier define stringifier classes directly; TopicStringifiers provides methods to get stringifier objects which stringify topics according to a given scope. All these stringifiers implement StringifierIF in net.ontopia.utils.

PSI (Public Subject Identifiers)

This class provides a local reference for the PSIs defined in the XTM 1.0 spec. Each PSI is available as a string and as a locator.

SameStoreFactory.java

This is a class providing a utility implementation of TopicMapStoreFactoryIF; a sameStoreFactory always returns the same topicmap store, which is the store given to its constructor.

Serialization utilities

Experimental utilites using java serialization.

Subject utilities

The subject utilities are in classes SubjectUtils and SubjectIdentityDecider. SubjectUtils provides methods for determining whether given topic map objects are related to given subjects.
SubjectIdentityDecider provides a simple interface to logic in SubjectUtils which determines whether an object has a given subject identity.

Comparator utilities

ObjectIdComparator

Compares the internally generated object ids of two topic map objects.

Topic Comparators

Experimental utilites concerning topic comparison.

TypedIFComparator

Compares the types of two typed topic map objects.

TopicMapBuilder

This is the default implementation for TopicMapBuilderIF in net.ontopia.topicmaps.core.

TypeHierarchyUtils

Utilites to collect supertypes and subtypes for topic map objects.

Related Documentation

Ontopia Topic Map Engine Developers Guide.