Error Handling

TM4J defines a number of exception types all of which are subclassed from the class org.tm4j.topicmap.TopicMapProcessingException. The following table shows the exceptions which are derived from this base class.

Table 3.7. TM4J Exceptions derived from TopicMapProcessingException

ExceptionWhen Raised
DuplicateObjectIDException If an attempt is made to create a TopicMapObject with an ID property value which is already assigned to another TopicMapObject.
DuplicateResourceLocatorExceptionIf an attempt is made to add a new topic map object with the same resource location as another object already in the topic map.
DuplicateTopicException If an attempt is made to create a Topic with an ID property value which is already assigned to another Topic in the TopicMap.

Note

This exception has been superceeded by DuplicateObjectIDException.

IntegrityViolationException
  • If an attempt is made to use a topic from one TopicMap for typing or specifying a scope theme in another TopicMap.
  • If an attempt is made to remove an object from a TopicMap which is referenced from some other object. E.g. an attempt to remove a Topic which is used as a type of another Topic, Association or Occurrence or used as the roleSpec of a Member or as a theme in a Scope will result in this exception being raised.
MergedTopicSubjectClashException When the merging process attempts to merge two topics but finds that they have different subject-constituting resources (as defined by the subject property of the Topic interface).
ProviderTransactionException An error raised while trying to establish a new transaction or to commit or rollback and existing transacation.
TopicNotFoundException When an attempt is made to remove a topic from a topic map when that topic is not a part of the topic map.
UnifiedTopicMapException If an attempt is made to add a TopicMap to a UnifiedTopicMap where the TopicMap being added does not support all of the TM4J basic indexes. See Chapter 10, Unified Topic Maps for more information.

In addition to the exceptions described above, TM4J provides a subclass of the Java RuntimeException class, org.tm4j.topicmap.TopicMapRuntimeException. This exception class is used to wrap other exceptions and system errors and pass them out of a function without requiring the exception to be explicitly handled or declared to be thrown by the caller. The most common use of this is when parsing XTM files and when handling property change events. Application developers should be aware that a TopicMapRuntimeException may be thrown from parsing and property change events and should ensure that their application catches and handles these exceptions.

The TopicMapProvider and TopicMapProviderFactory interface methods may throw an instance of the class org.tm4j.topicmap.TopicMapProviderException . This exception is typically only raised if a connection cannot be established to the back-end storage.

The TopicMapProviderFactory class method newInstance may raise an instance of the class org.tm4j.topicmap.TopicMapProviderFactoryConfigurationError if the runtime configuration of the concrete TopicMapProviderFactory class failed.

Further exception classes are defined by the org.tm4j.net package for locator handling (described in the section called “Locators”); the org.tm4j.tolog package for the tolog query engine (described in Chapter 8, Tolog Query Engine; and the org.tm4j.topicmap.index package for indexing and index lookup (see Chapter 6, TM4J Indexing Subsystem)