|
![]() |
This is a guide to installing and getting started with using Ontopia. It is assumed that the reader is familiar with the basics of the host platform and of Java development. See the What's new in this release? document for information about this release.
The most important requirement is that you must have the Java 2 Software Development Kit (SDK) version 1.5 or newer. There should be no platform dependencies in the code, so the software should run on all operating systems for which there is a supported JDK available.
We have verified that the Navigator Framework runs in Tomcat versions 3.3, 4.1, 5.0, and 5.5, Oracle9i AS 9.0.3, WebLogic 7.0, and WebSphere versions 4.0 and 5.0. It is quite likely that the framework also works in other application servers than these, but this has not been verified.
The RDBMS backend has been verified to work with Oracle 8.1.7, 9i, and 10g, PostgreSQL 8.1, 8.2 and 8.3, MySQL 5.0, H2 Database 1.0.74 and Microsoft SQL Server 2005.
Ontopia has the following components:
The Ontopia Topic Maps Engine
Full-text Integration
Query Engine
Schema Tools
The Ontopia Navigator Framework
TMRAP
The Ontopia Web Editor Framework
The Ontopia Vizigator
DB2TM
The Ontopia RDBMS Backend Connector, with SQL implementation of Query Engine
The Ontopia Omnigator
The Ontopoly Topic Maps Editor
The first step in the installation is to uncompress the distribution file, which you have presumably already done, since you are reading this document. The topmost directory created by uncompressing the distribution, the file called ontopia-X.X.X.zip , will from now on be referred to as basedir.
If you want to use the Ontopia APIs to write Java software, or just run the test suite, you will have to set up the CLASSPATH environment variable. If you only want to run the Navigator Framework this is not necessary, and you can skip this section.
To set up the CLASSPATH, put the ${basedir}/lib/ontopia.jar file in your CLASSPATH. If this does not work, or you want more detailed control over the jar files being used, please see appendix A.
The jar-file automatically includes the other required jar-files for you via its manifest. In practice this means that you normally need not put the other jar-files on your CLASSPATH explicitly, but they all have to be located in the same directory for this to work.
There may be some Java Virtual Machines out there that do not support the new CLASSPATH jar-file manifest header. If that is the case you'll have to add all the individual jar-files to your CLASSPATH.
Now that you've set up your CLASSPATH environment variable you can verify it by issuing the following command:
java net.ontopia.Ontopia
It will run and produce the following output if it can find all the classes required:
Ontopia Topic Maps Engine [version] Success: All required classes found.
If it fails you will get output similar to the following:
Ontopia Topic Maps Engine [version] Class 'org.apache.log4j.BasicConfigurator' not found. Please add log4j.jar to your CLASSPATH.
The message is hopefully self-explanatory.
Once you've set up your CLASSPATH environment variable you can check that Ontopia is indeed working correctly on your system. This step is optional.
Ontopia comes with a set of test suites, so you can check that it is working correctly on your system. Each test suite is a set of JUnit test cases that exercise most aspects of Ontopia to verify that it works as it should. This includes testing all engine policies, all engine methods, testing import and export of topic map documents and so on. Running the test suite is therefore the best and quickest way to test whether it has been installed correctly or not.
You need to add the ${basedir}/lib/ontopia-tests.jar jar-file to your CLASSPATH to run the test suite, as well as ${basedir}/apache-tomcat/common/lib/: servlet-api.jar, jsp-api.jar, jstl.jar, and standard.jar required by the Navigator and Web Editor Frameworks. Note that you only need these extra jar-files when running the test suite. They are not required when you are using Ontopia.
You can now run the test suite by following the instructions below:
You should see the following output:
Ontopia Topic Maps Engine [version] License: [license info] Success: All required classes found. Running tests ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... ......................................... .. Time: 10.367 OK (1109 tests) Asserts: 12905
The test should end with OK (xxx tests). If it does not and running the tests produces any kind of error the engine might not be working correctly on your system. In that case please report an issue at Google Code including:
a brief description of what you have done,
the output from the test run,
your entire CLASSPATH when you ran the tests,
what platform you ran the test on,
the output from the command java -version, and
the output from the command java net.ontopia.Ontopia.
If the test runs without errors, as it should do, you can be confident that you have a working version of the Ontopia Topic Maps Engine.
The tests for the RDBMS backend have been separated out, since they require a database to be set up and configured, and so require quite a bit of initial setup. To run these tests set up your database (as described further down), then run tests\runtests-rdbms.bat or tests/runtests-rdbms.sh.
See the The RDBMS Backend Connector - Installation Guide document for information about how to install and setup the relational database backend. Note that it's possible to run Ontopia and the web applications without using the RDBMS backend.
Following is a short introduction to the end-user applications that come with Ontopia.
For more information about developing with Ontopia you can find a complete list of developer documentation here.
The engine consists of an SDK and some command-line utilities, and so there is little that can be done with it apart from developing applications on top of it.
To get started with application development we recommend that you start by reading the developer's guide. Once you have read that we recommend that you use the javadocs in ${basedir}/doc/api to learn the details of the APIs.
You can find example topic maps in the ${basedir}/apache-tomcat/webapps/omnigator/WEB-INF/topicmaps directory, which contains topic maps in the XTM 1.0, 2.0, CTM, and LTM formats.
The engine comes with a collection of command-line utilities, which can be used to perform various tasks on topic maps. The command-line options of the utilities are not given here, but explanations can be had by running the utilities with no arguments.
This application reads in a topic map and creates a canonical representation of it using CXTM. CXTM has the property that logically equivalent topic maps will always have byte-by-byte identical canonical representations.
For more information on CXTM, see the home page.
Ontopia comes with a number of useful web applications built with Ontopia already set up and configured in a Tomcat installation. The main applications are:
Ontopoly: The Ontopia Topic Map Editor, the user's guide to which can be found in${basedir}/apache-tomcat/webapps/ontopoly/doc/user-guide.html
Ontopia Omnigator, the user's guide to which can be found in${basedir}/apache-tomcat/webapps/omnigator/docs/navigator/userguide.html
Try out these web applications by following these steps:
Locate the ${basedir}/apache-tomcat/bin directory in Windows Explorer.
Double-click on the startup.bat file.
Change directory to ${basedir}/apache-tomcat.
Execute the bin/startup.sh script.
After starting the application server it will take a few seconds before the server is initialized and ready to answer requests.
If the application server fails to start correctly you may have to set the JAVA_HOME environment variable to point to the directory where the Java Runtime Environment is installed. This can be done either at the command-line before running the tomcat startup script, or by editing the script to insert a line setting it. See appendix C for details.
To try out Ontopia you can use any of the applications listed below. The first time you're accessing a page it may take some time since the web application server needs to compile the JavaServer Pages. If you are able to see the front page of the application then the installation is successful. Congratulations!
Internet Explorer Users: Please note that IE 5.0 may not be able to connect to the application server if you are working 'Offline'.
This link takes you to an Ontopia Overview Page, which can be very useful for getting started.
The Omnigator is a Navigator application which can display any topic map in a user-friendly fashion. Use this application to learn more about topic maps, to explore the example topic maps, and also to check your own topic maps. See The Ontopia Omnigator - User's Guide for information on how to use this application.
Ontopoly is a user-friendly Topic Maps editor, which can be used to create and populate an ontology.
This is a web application written specifically for the i18n.ltm topic map, to show how the Navigator Framework can be used to create ontology-specific web applications. This application is very useful for learning to use the tag libraries.
This is the beginnings of a web application for the 'Free XML Tools' topic map. It is used as an example in the navigator developer's guide. The application is not complete, but you may find it instructive to complete it on your own.
Change directory to ${basedir}/apache-tomcat.
Execute the bin/shutdown.sh script.
This section contains answers to frequently asked questions about Ontopia.
If you get an error message saying Not Found (404) followed by Original request: /navigator/models/index.jsp and Not found request: /navigator/views/template_no_frames.jsp when accessing the Omnigator you have used a decompression tool that truncates file names when unpacking files.
We have confirmed that WinZip version 6.3 and earlier have this problem, as does WinRar 2.90. WinAce may also have this problem. We have confirmed that WinZip 8.0 and later do not have this problem.
The solution to the problem is simply to install a newer version of the decompression tool and unpacking the distribution again.
There are two things you can do. If you've created an icon to start the server you can go into the properties of the icon, under the "Program" tab, and unset the "Close on exit" option. This will make the window stay around after the server exits, and give you time to read any error messages that may appear. (If you're just starting it by double-clicking startup.bat, then either make an icon and set it up as described above, or try the option below.)
The other approach is to change the startup.bat so that the line near that end that now reads:
call "%EXECUTABLE%" start %CMD_LINE_ARGS%
is changed to:
call "%EXECUTABLE%" run %CMD_LINE_ARGS%
This will keep Tomcat from opening a new window, so if you run startup.bat from the command-line you should get the error messages there.
The server log is in ${basedir}/apache-tomcat/logs/localhost_log.<date>.txt, and it is likely to contain much detail information on errors. You can try to decipher this file to find the cause of the problem, or if that is difficult, you can just send the file to us at support@ontopia.net, and we will try to help. Note that if the file doesn't exist it means the server has been unable to start and you should try one of the two options above to find out why.
To install the Omnigator in another Tomcat instance than the one which comes with Ontopia, follow these steps:
Copy all the .jar files, except ontopia-tests.jar and junit.jar, from ${basedir}/lib to ${tomcat.home}/common/lib.
Copy ${basedir}/apache-tomcat/webapps/omnigator to the other Tomcat installation.
Ontopia has the following jar-file dependencies. The files can be found in the ${basedir}/lib directory.
Topic Map Engine:
crimson.jar, version 1.1.3, (Apache XML - Crimson)
getopt.jar, version 1.0.9, (GNU Java getopt)
slf4j-api.jar, slf4j-log4j12.jar, jcl-over-slf4j.jar version 1.5.8, (Simple Logging Facade for Java (SLF4J))
log4j.jar, version 1.2.14, (Apache log4J)
antlr.jar, version 2.7.7, (ANTLR parser generator)
commons-collections.jar, version 3.2.1, (Apache Commons Collections)
oro.jar, version 2.0.8, (Apache Jakarta ORO)
jing.jar, version 2003-01-31, (Jing - A RELAX NG validator in Java)
xerces.jar, version 2.7.1, (Apache Xerces2 Java Parser)
jena.jar, version 2.3, (Jena - A Semantic Web Framework for Java)
icu4j.jar, version 3.4.4, (International Components for Unicode for Java)
concurrent.jar, version 1.3.4, (util.concurrent)
trove.jar, version 2.0.4, (GNU Trove)
backport-util-concurrent.jar, version 3.1, (backport-util-concurrent, a backport of JSR 166)
tmapi.jar, version 2.0 a2, (TMAPI - Common Topic Maps Application Programming Interface)
Vizigator:
touchgraph.jar, built from source with patches, (TouchGraph)
Web Editor Framework:
velocity.jar, version 1.3, (Apache Velocity)
commons-fileupload.jar, version 1.1, (Apache Commons FileUpload)
Full-text Integration:
lucene.jar, version 1.4.3, (Apache Lucene)
DB2TM:
opencsv.jar, version 1.8, (opencsv)
TMRAP (AXIS+SOAP support):
Ontopia uses AXIS2 version 1.2, (Apache Web Services - Axis), to provide support for SOAP. The jar files used can be found in ${basedir}/apache-tomcat/webapps/tmrap/WEB-INF/lib.
RDBMS Backend Connector:
commons-pool.jar, version 1.3, (Apache Commons Pool)
commons-dbcp.jar, version 1.2.2, (Apache Commons DBCP)
jgroups-all.jar, version 2.6.10 GA, (JGroups - A Toolkit for Reliable Multicast Communication)
The Query Engine and the Schema Tools require no jar files beyond the ones needed for the Topic Map Engine.
Java system properties are set by using a command-line argument to the java command when it is run. The command java -D<prop>=<value> ... will set Java system property <prop> to <value>.
Tomcat is usually started using the Tomcat startup scripts, and so one needs to modify these in order to be able to pass command-line arguments to the Java runtime. Below is explained how to do this on Windows and Unix:
Edit the ${basedir}/apache-tomcat/bin/catalina.bat file and insert the line below near the top of it.
set CATALINA_OPTS="-D<prop>=<value>"
Edit the ${basedir}/apache-tomcat/bin/catalina.sh file and insert the line below near the top of it.
CATALINA_OPTS="-D=<prop>=<value>"
Note that by default there should be no need to specify any system properties to get Ontopia working.
This section explains how to set the JAVA_HOME environment variable on Windows.
If you start tomcat from the command-line you can give the command set JAVA_HOME=c:\path\to\java before starting the application server. Please replace c:\path\to\java with the path to your Java installation (for example c:\jdk1.5.0_13), make sure that you have not accidentally put the bin sub directory into the JAVA_HOME environment variable.
On Windows NT, 2000, and XP you can also go into the control panel, select 'System', then click the 'Advanced' tab, then click 'Environment variables'. This gives you a window where you can enter a new environment variable named 'JAVA_HOME', the value of which must be the directory where you installed Java.
On Windows 95/98/ME you can also edit the AUTOEXEC.BAT file in the root directory of your startup drive (usually C:) and insert a line like the following into it: set JAVA_HOME=c:\path\to\java. You will then need to reboot your computer before the change takes effect.