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. Note
that these are supplementary to the core interfaces, and more likely to
change in the future.
These utilities use the core interfaces as their only interface with topic maps.
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.
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
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.
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
SubjectIdentityDecider provides a simple interface to logic in SubjectUtils which determines whether an object has a given subject identity.
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, seenet.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 innet.ontopia.topicmaps.core.
TypeHierarchyUtils
Utilites to collect supertypes and subtypes for topic map objects.Related Documentation
Ontopia Topic Map Engine Developers Guide.-
Interface Summary Interface Description AssociationWalkerListenerIF PUBLIC: This interface defines a listener to the AssociationWalker.ImportExportServiceIF Service definition for services that provide format reader and writers. -
Class Summary Class Description 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.CharacteristicUtils INTERNAL: Characteristic processing utilities.ClassInstanceUtils INTERNAL: Utilities for working with class-instance relationships.CopyUtils INTERNAL: Utilities for copying topic map data.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<S extends ScopedIF> 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.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.SameStoreFactory PUBLIC: A store factory that always returns the store given to it via its constructor.ScopedIFComparator<T extends ScopedIF> INTERNAL: Comparator that compares ScopedIF objects based on their applicability in the specified scope.ScopeUtils INTERNAL: Scope processing utilities.SubjectIdentityDecider<T extends TMObjectIF> 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.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.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 TopicTreeNode 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<T extends TypedIF> INTERNAL: Grabber that grabs the type property of the TypedIF 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.VariantNameGrabber INTERNAL: Grabber that grabs the most highest ranked variant name by scope from a basename.