This is the core package of TM4J. It contains the interface definitions that are supported by each of the back-end storage models. By coding your application to the interfaces in this package, you can create applications that are portable between back-end storage models.

The different backend storage modules that are currently part of TM4J are each provided by a separate package in the distribution. The current set of packages providing backend storage modules are:

The org.tm4j.net package defines a set of interfaces for creating, manipulating and resolving network addresses (represented by the interface org.tm4j.net.Locator). Again, there are different implementations of these interfaces for the different storage models, these implementations can be found in the packages org.tm4j.net.memory; org.tm4j.net.ozone and org.tm4j.topicmap.hibernate. At the time of writing, no implementation of the org.tm4j.net package is available for the DOM storage model. The interface definitions are contained in tm4j.jar and the implementations are found in the same JAR file as the core interface implementations for the specific back-end.

Additional API-level utilities can be found in the package org.tm4j.topicmap.utils. The utilities contained in this package are all independent of the storage model. These utilities include classes for serialising and parsing XTM files; for traversing a topic map; and for filtering and sorting collections of objects. This package is implemented in tm4j.jar.

This package contains an implementation of the proposed Topic Maps API (TMAPI). TMAPI is a proposed standard API for topic map engines. Although currently support in the community for TMAPI is somewhat lacking, it is hoped that as the API develops more commercial topic map engines will implement support for the API. The implementation of this package is contained in tm4j-tmapi.jar.

This guide does not cover the use of TMAPI. For details on TMAPI, please refer to the Javadoc and to the TMAPI project site.

The Tolog query engine is implemented in the package org.tm4j.tolog. This implementation has been tested with the in-memory implementation and the Ozone database implementation. It is expected that this implementation will also work with the Hibernate implementation, but it is likely to be inefficient. A more efficient Hibernate-specific implementation is planned for a future release. The tolog query engine is implemented in tm4j-tolog.jar. You can read more about the Tolog query implementation in Chapter 8, Tolog Query Engine

This package consists of a collection of command line utilities At the time of writing four utilities are provided - Compress (makes an input topic map or collection of topic maps into a single 'consistent' topic map as defined by the XTM specification); Merge (merge two or more topic maps together and output the result); Stats (generate some basic statistical measures of a topic map or set of merged topic maps); and Fragment (extract a small topic map centered on one specific topic from a larger topic map or set of merged topic maps). Contributions of other utilities are welcome!

For more details on running the command line applications, please see the tool documentation (docs/tools/index.html).

All of the command-line application classes are contained in the tm4j.jar JAR file.

This package provides an abstraction of a source of topic map data. This abstraction encapsulates both the data source and the processing that converts the data source into a topic map. There is a default implementation of this abstraction which uses XTM and LTM files as the data source and encapsulates the parsing of those files to populate topic maps. This package is implemented as part of tm4j.jar. For more details on the use of the this package, please refer to the section called “Parsing Topic Maps From File”.

The JNDI package allows a persistent store or an in-memory store to be shared between different J2EE applications using the JNDI mechanism. This allows multiple applications (such as different web applications) to simultaneously access the same topic maps.

For more details on the JNDI package, please refer to Chapter 11, Sharing Providers through JNDI.

As well as the TM4J JAR files, the TM4J distribution includes a number of 3rd party JAR files which are also required. To make it easier to distinguish between the JAR files you need and those you do not, the lib directory has two subdirectories. The directory lib/hibernate contains the additional JAR files you need to use the Hibernate backend to connect to a JDBC datasource ^[1] . The directory lib/ozone contains the additional JAR files you need to use the Ozone backend.

Of the files contained direcly inside the lib directory, some are needed only if you plan to use particular features of TM4J. In most cases, we recommend that you include all of these files, but if you need to slim down your distribution, the following table lists the optional JARs and what facility they provide or are used in conjunction with.

All JAR files contained in the lib directory which are not listed above are mandatory for correct operation of TM4J. All JAR files contained in the hibernate and ozone sub-directories are mandatory for the use of those back-end implementations of TM4J.