| Affiliation: | Ontopia |
|---|---|
| Date: | $Date: 2001/06/27 20:02:22 $ |
| Version: | 1.1 ($Revision: 1.2 $) |
| |
This document is a guide to configuring the Ontopia Topic Map Navigator. The Navigator has a large number of configuration options, and this document explains where they can be found and what they can do. By looking in the actual configuration files you can find additional advanced configuration options not documented here.
The behavior of the Navigator is defined by the settings contained in a number of different XML configuration files. Java servlets can be configured using a standard web.xml configuration file found in the WEB-INF directory. However, the data structure allowed in web.xml is name/value only. Many of the structures required for the configuration of the Navigator are more complex and so separate configuration files are used to configure it.
The default locations for configuration files are as follows:
WEB-INF/web.xml. This file is used to tell the Navigator where to find its other configuration files. The locations listed below are only the defaults.
WEB-INF/config/application.xml. This file contain many advanced configuration options, as well as some that are documented in this document.
WEB-INF/config/topicmaps.xml. This file allows you to set the title and output encoding for each topic map..
WEB-INF/config/sources.xml. This file is used by the Navigator to find topic maps.
WEB-INF/config/log4j.txt. This is the log4j configuration file, used to configure the logging in the Navigator.
This file is part of the Java Servlet system and contains information used by the servlet system, as well as simple name/value configuration properties for individual servlet applications.
The following configuration settings are used by the Navigator:
Each topic map in the application can have configuration options set in this file. If a topic map doesn't have any information provided for it the configuration for the topic map called "default" will be used.
You can set the following configuration options for each topic map:
The default character set in most of the world today is ISO-8859-1, but the character set used by XML, topic maps and the Ontopia Knowledge Suite is Unicode. The Navigator Framework produces output in ISO 8859-1 by default, and generally this doesn't cause problems where the characters represented fall within the ISO-8859-1 range.There are many languages, however, which are not supported by ISO 8859-1 and for these one must use encodings which support these languages.
In such cases we recommend that either the UTF-8 Unicode encoding, or the usual national character encoding for that language be used. In these cases a different character encoding can be set for a topicmap. This is set as a configuration option and all output is then automatically written in this encoding by the Navigator Framework.
The Navigator uses this file to find topic maps and enter them into the topic map registry. The rest of this section explains how this file is implemented, which is useful for those using the Engine SDK. If you are not interested, you may skip to section 4.1.
The file contains entries that are used to create TopicMapSourceIF objects (see the entry package javadoc), which can find topic maps by various means and make the available to the Navigator.
In this file, each source element creates an instance of the class named in its class attribute. The class must implement the TopicMapSourceIF interface. The source elements contain param elements, which give configuration information to the source objects using Java bean introspection.
The advantage of this approach is that with this configuration file one can easily make the navigator find topic maps in the file system, in a database, or by any other imaginable means. Each section below documents some TopicMapSourceIF implementations.
Note that if you wish to use this functionality in your own applications you can use the net.ontopia.topicmaps.entry.XMLConfigSource class (requires the Ontopia Topic Map Engine SDK).
The XTMPathTopicMapSource, ISO13250PathTopicMapSource, and LTMPathTopicMapSource classes look in a specific directory of the file system for files with a particular suffix. Those found will be made available to the Navigator, which may then choose to load them. Each source class expects files with a different syntax.
Below is shown an example configuration element for this class. The path parameter tells the source what directory to look in. The $[CWD} is a variable replaced by the path of the directory where the sources.xml file was found. The suffix parameter tells the source what suffixes to look for on files.
Example configuration
<source class="net.ontopia.topicmaps.xml.XTMPathTopicMapSource">
<param name="path" value="${CWD}/../xml"/>
<param name="suffix" value=".xtm"/>
</source>
If you have the RDBMS Database Backend product you can use this class to make the Navigator find topic maps in your relational database. This source understands four parameters:
Below is shown an example configuration element.
Example configuration
<source class="net.ontopia.topicmaps.impl.rdbms.TopLinkTopicMapSource">
<param name="connectionString" value="jdbc:postgresql:larsga"/>
<param name="licensePath" value="/home/larsga/cvs-co/src/java/3rdparty/"/>
<param name="userName" value="larsga"/>
<param name="password" value=""/>
</source>
This configuration file stores the configuration for a Navigator web application, and by modifying this file it is possible to control many aspects of how the application behaves.
The Navigator uses the information in the source.xml file (section 4) to populate the topic map registry with topic map references. It does not load any of these topic maps before the user requests it through the manage page, however. The autoloads section can be used to request that some topic maps be loaded when the Navigator starts up, without the user having to explicitly request it.
Below is shown the default autoloads section:
Autoloads
<autoloads>
<autoload topicmapid="opera.iso" />
<autoload topicmapid="xmltools-tm.xtm" />
</autoloads>
The topic map IDs used here are the file names of the topic maps, including the suffix. The special ID ~all can be used to make the system automatically load all topic maps it finds.
With this section you can control what models and views are to be made available to users (including ones that you develop yourself), and you can also set the default model, view, and skin. In addition you can also tell the Navigator what directory to look for CSS skins in.
The model and view elements in the mvs element each make available a model or a view on the customize page. They can have the following attributes:
The skins element has two attributes:
In this section one can set a number of configuration options that control how the Navigator behaves. These options are all simple named string values. The ones currently in use are:
Controls whether topic maps are autoloaded when requested or not. If this property is set to true topic maps that have not previously been loaded through the manage page will be loaded automatically when someone tries to access them.
This differs from the autoload section in that topic maps listed there will be loaded when the server starts, before anyone has requested them. If this option is on any topic maps that have not been loaded, but which are requested by a user, will be loaded automatically. If this option is turned off the topic maps in the autoloads section will still be loaded on startup.
Classes of objects to be instantiated and set. The topicmap taglib makes heavy and repeated use of certain Stringifiers and Grabbers. The overhead of individual instantiation would be significant if the objects were not available in application scope. The default classes included in the configuration file should not be removed as the application will use these if no alternatives have been requested through tag attributes.
If users wish to specify their own Stringifiers and Grabbers certain rules must be followed in their signatures.
The classes must have an empty constructor. This allows the application to use one object for all requests.
Grabbers must have a (Collection scopes, String args) constructor and Stringifiers must have a (String args) constructor. This is required to satisfy the requirements of the tags.
A number of partially set components which act as templates for various topic map objects which need to be rendered. In concrete terms this means rendering information for style, class, target, onClick, onMouseover and onMouseout.
Different links on the HTML page will require different component templates depending on their type. For example, a topic link may need to fire some JavaScript when clicked. A topic component allows these differences to be handled in one place. Further, links of the same type may behave differently in different situations. For example, in a framed version of the site a resource may need to target an "info" window rather than "_self". The Components configuration allows this to be managed in one place.
Two different groups of components have been defined for the generic Navigator: "no_frames" and "frames". Within each there are seperate components for the application, topicmap, topic, resource and default.
A number of default cluster configurations which will be used by the application when none have been provided by the user. The Navigator makes information design as simple as possible by not requiring the user to enter any rendering information through cluster and display tags. In the cases where this information is not provided by the designer the clusterDefaults will be used instead.
The properties file for log4j - please see the log4j manual. You can also find a little more information on log4j and how the Ontopia Knowledge Suite uses it in the Topic Map Engine Developer's Guide.