Table of Contents
The TM4J distribution consists of a number of separate, but related packages. This section describes the TM4J distribution package by package, telling you what each package contains and which JAR file of the distribution you will find the package in.
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:
At the time of writing, the org.tm4j.topicmap.dom package does not support the complete set of core TM4J interfaces. The unimplemented methods may return null or raise exceptions. If you plan to use this backend you are strongly advised to download the source distribution from the CVS server and expect to do some development work to complete the methods that you need. When you are done, please consider contributing your work back to the community.
The package org.tm4j.topicmap.unified is different from the other back-end packages in that it is not a storage mechanism but instead a "view" onto multiple storage systems. This back-end is discussed separately in Chapter 10, Unified Topic Maps.
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.
Table 3.1. JAR File Dependencies
JAR File | Is Needed For: |
---|---|
ant.jar, optional.jar | Building the sources. Using the TM4J Ant tasks. |
antlr.jar, jakarta-regexp.jar | LTM parsing. |
jargs.jar | Running the command line tools. |
junit.jar | Building and running the unit tests. |
log4j-1.2.8.jar | Recommended logging mechanism. TM4J uses the Jakarta Commons Logging API which will in turn make use of Log4J if it is present. |
lucene-1.3-final.jar | Full-text index. |
tmapi-1_0d-20020812.jar | Building and using the TMAPI implementation. |
xercesImpl.jar | Used for serialisation of XTM files. |
xmlParserAPIs.jar | Can be omitted if using JDK 1.4 or later. |
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.
All XML parsing in TM4J is done using the Java API for XML Parsing (JAXP). If you use JDK 1.4 or later, an XML parser is included in the JDK, and you can remove the xmlParserAPIs.jar file from the TM4J lib directory.
If you would prefer to use a different XML parser that supports JAXP, you can do so by including the parser JAR file on your CLASSPATH and removing the xmlParserAPIs.jar file. If you do use a different XML parser, please note that TM4J requires that the parser supports XML namespaces, but support for validation is optional.
[1] You will, of course, need the JDBC driver for the database you wish to connect to. Additionally Hibernate supports a number of pooling mechanisms not all of which are shipped with the TM4J distribution. If you want to investigate different pooling options, we advise you to download a separate Hibernate distribution and read through the user documentation.