Installing TMBrowse

Pre-Installation Requirements

TMBrowse is a servlet-based application. To install it you will require a servlet container such as Apache's Tomcat to run the application. Currently, TMBrowse has been tested against only the following servlet containers:

Table 1. Servlet Containers Tested With TMBrowse

Servlet Container Version(s)
Jakarta Tomcat 4.1.27

Installation

TMBrowse is distributed as a WAR file. For most servlet containers, installation should be as simple as placing the tmbrowse.war file in the webapps directory of the servlet container where it will be automatically expanded by the servlet container to create a directory named tmbrowse.

Note

You may need to restart the servlet container for the new WAR file to be recognised and expanded.

The default TMBrowse installation contains some topic maps to get you started. So once the WAR file is expanded, you should be able to access those topic maps through TMBrowse by pointing your browser to http://url_to_servlet_container/tmbrowse/. For example, with the default Tomcat installation, the servlet container runs on the port 8080, so to access TMBrowse from the machine running the servlet container, you would use the URL http://localhost:8080/tmbrowse/.

At this stage, if you do not get to an initial splashscreen page, the most likely causes are:

  1. The servlet container is not running.
  2. The TMBrowse installation failed.

The former cause can be verified by trying to connect to another web application on the servlet container that you know works. For a Tomcat installation, we recommend that you try to connect just to the root directory e.g. http://localhost:8080/. If you do not see a Tomcat welcome screen, then the servlet container is not running. Check the log files for the servlet container to determine the cause of this failure.

The latter case can be caused by a failed expansion of the WAR file (e.g. because of a corrupt WAR file or lack of disk space); or because further configuration is required on your servlet container (this should not be the case with Tomcat, but may be necessary for other configurations); or, finally, because of a bug. If you do have problems getting TMBrowse started, please report this error (see the section called “Reporting Errors”), giving as much detail about your installation as possible and if you can, providing the appropriate parts of the server log files (please don't send the whole log file!).

Configuring The Topic Map List

The list of topic maps displayed by TMBrowse is configured by the file WEB-INF/config.xml in the TMBrowse web application directory. The topic maps are provided either by reading XTM or LTM files into memory or by connecting to one of TM4J's supported persistent storage backends. The default TMBrowse installation supports only the use of XTM/LTM files parsed into memory. For details of configuring support for storing topic maps in a relational or object-oriented database, please refer to the section called “Running TMBrowse Over TM4J Persistent Stores”.

The configuration file is split into two main sections. The first section is contained by the element <velocity> and specifies runtime configuration properties for the Jakarta Velocity templating engine used by TMBrowse. Refer to the section called “Configuring the Velocity Engine” for more details on this section. The second section is a list of <provider> elements, one for each source of topic maps listed by the TMBrowse application. Each provider element defines the name of the provider and the name of the factory class that is used to initialise the provider in the name and factory attributes respectively. A file-based topic map source uses the in-memory provider factory which has the name org.tm4j.topicmap.memory.TopicMapProviderFactoryImpl.

Every provider element has as its first child a provider-properties element within which is contained a list of property elements. Each property element specifies a runtime configuration parameter for the topic map provider. For the in-memory provider the following properties are recognised.

Table 2. Provider Configuration Properties for the in-memory Provider

Property Name Description
tm4j.noDefaultListeners A boolean property. If the value of this property is 'true', then the internal change event notification system of TM4J is disabled. The setting of this property has little impact on TMBrowse as the event notifications are only generated by updates to a topic map and TMBrowse is a read-only system.
TBC... TBC...

The list of topic maps that are available through an in-memory source may be configured in one of two ways. Either you can add one topicmap element for each separate topic map to be made available as a child of the provider element, or you can add a single topicmaps element as a child of the provider element, which refers to a directory containing the topic maps to be loaded.

Entry-Per-Topic-Map Configuration

To configure topic maps one-by-one, create a topicmap element for each topic map to be listed. The topicmap element has the following attributes:

name
The identifier to be used as a short reference to this topic map. This must be a unique name amongst all topic maps listed by TMBrowse.
src
The path to the XTM or LTM file to be loaded. This path is first resolved relative to the web application directory and then, if no file is found at that location is resolved relative to the JVM base directory. You are recommended to only use either full file path names or path names relative to the web application directory.
template
The name of the Velocity template used to render the topic map's main page. This is the template that will render the page that the user is taken to when selecting this topic map from TMBrowse's list of topic maps.

In addition to those attributes, the following elements may appear as children of the topicmap element.

title
If present, the content of this element will be used as the display name of the topic map in TMBrowse's topic map list.
topic-config
If present, this element defines the template and/or custom extractor class used to render particular topics or all topics of a particular type in a topic map. Please refer to the section called “Customising the template for a topic or class of topics” for more details.

Entry Per Directory Configuration

The topicmaps element allows you to specify a single configuration to be applied to all files in a specific directory. This element is an empty element with just two attributes:

dir
REQUIRED - the directory containing the topic maps to be loaded. The value of this attribute must be the path to the directory in question. The path should be either an absolute path (including drive name for Windows), or a path relative to the web application directory.
template
The name of the Velocity template to be used to render the main page for the topic map. This is the page that the user is taken to when they select the topic map from the list of topic maps presented by TMBrowse.