# IsaViz: Installation Instructions

Important Note

Several people have encountered difficulties importing local RDF files in IsaViz 1.2 (and might encounter the same problem if upgrading from 1.0 or 1.1 to 2.0 or 2.1): the model is not loaded, and the following error message is generated:

RDFErrorHandler.error: com.hp.hpl.jena.rdf.arp.MalformedURIException: No scheme found in URI.

The source of this error is a bad Defaut Base URI in your preferences (e.g. "online"). To correct this, select Edit/Preferences, and set the Default Base URI value to blank or to the well-formed URI of your choice.

## 1. Quick Instructions

The following components are required to run IsaViz:

- A Java Virtual Machine version 1.3.0 or later (1.4 strongly recommended - see Known problems)
- A distribution of IsaViz, which contains the following Java JAR files:
  - IsaViz itself (isaviz.jar)
  - Zoomable Visual Transformation Machine (zvtm.jar)
  - Jena 2.1 for IsaViz 2.1, Jena 1.6.1 for IsaViz 1.2
  - Xerces-J version 2 (xercesImpl.jar,xmlParserAPIs.jar) for IsaViz 2, Xerces 1.4.4 for IsaViz 1.2
- GraphViz from AT&T version 1.8.9 or later (version 1.7.x is no longer supported in IsaViz 2, and has actually only been tested with version 1.9). Note: some instances of version 1.10.0 had a bug that produced incomplete SVG files, but it has been corrected in subsequent releases (newer versions can be obtained on the graphviz.org site).

More detailed information is available in the following sections.

## 2. Requirements

### 2.1. Java Virtual Machine (JVM)

IsaViz is written in Java. The GUI is built on ZVTM, a ZUI toolkit that heavily relies on Java2D. This basically means that you will need a JVM version 1.3.0 or later.

IsaViz has only been tested with Sun's JVM, which can be found at:
http://java.sun.com/j2se/1.4/
http://java.sun.com/j2se/1.3/

A JVM 1.4.0 or later is strongly recommended since Java2D performances have been noticeably improved from 1.3 to 1.4 (read also Known problems). If you want to compile IsaViz, a JDK 1.4.x is required (IsaViz uses the ImageIO API for the PNG export feature).

### 2.2. ZVTM (Zoomable Visual Transformation Machine)

ZVTM is the ZUI (Zoomable User Interface) toolkit on which IsaViz's GUI is based. It is included in this distribution (zvtm.jar). More information is available at http://zvtm.sourceforge.net. The version that ships with IsaViz 2 is 0.9.0.

### 2.3. Graphviz/dot

AT&T's GraphViz/dot is a tool for making hierarchical layouts of directed graphs. It is used only to compute the initial layout of imported RDF models and when the user wants IsaViz to suggest a new layout for an existing graph. It is therefore not required in order to run IsaViz, but major features will not be available if you do not install it.

GraphViz is not implemented in Java, but is available on a wide range of platforms (see Graphviz's web site for an up-to-date list):

- Windows
- Linux
- Solaris (x86 and Sparc)
- DEC Alpha
- HP-UX
- SGI Irix
- Mac OS X

GraphViz is not included in the IsaViz distribution, but is freely available at http://www.research.att.com/sw/tools/graphviz/ (the latest builds are available on the graphviz.org site).

You must download version 1.9 (with support for SVG) or later. Note: some instances of version 1.10.0 had a bug that produced incomplete SVG files, but it has been corrected in subsequent releases (newer versions can be obtained on the graphviz.org site). IsaViz only requires the DOT program. If you are using an old version of IsaViz (1.x), you can use older versions of GraphViz (1.7.6 or later) but I strongly suggest using version 1.8.9 or later as you may have some problems with earlier versions when trying to import some RDF files (see Known problems).

Note: GraphViz can be installed in any location. You will be able to configure it from IsaViz's Preferences window.

### 2.4. Jena 2 Semantic Web Toolkit

HP's Jena is a Java API for manipulating RDF models. It is included in this distribution. More information is available at http://www.hpl.hp.com/semweb/index.html

### 2.5. Xerces-J 2

Apache's Xerces-J version 2 is a Java XML parser. It is included in this distribution. More information is available at http://xml.apache.org/xerces2-j/index.html

## 3. Installation

The installation procedure should be fairly quick and simple. Unpack your ZIP file or tarball in any location you want. This will create a directory named IsaViz which will contain the following files and directories, among others:

IsaViz\
|
|
---isaviz.cfg (configuration files where user preferences are saved)
|
|
---export\ (default directory for RDF/N-Triple/SVG and PNG files exported from IsaViz)
|
|
---lib\ (contains all JAR files required by IsaViz)
|
|
---plugins\ (contains all plugin JAR files)
|
|
---projects\ (default directory for ISV (IsaViz project) files)
|
|
---tmp\ (default directory where are stored temporary files used to communicate with GraphViz/dot)

The top-level directory also contains launch scripts for Windows (run.bat) and POSIX systems (run.sh) that should be working immediately provided that java is in your PATH.

Note: IsaViz 2.0 uses Jena 2 and Xerces-J 2 (included in the distribution). You might want to use versions of these other than the ones included. The requirements are:

- for Jena, version 2 beta 1 or later (version included in this package: 2 beta 1)
- for Xerces-Java 2, version 2.2 (version included in this package: 2.2)

Be aware that there are version dependencies between Xerces and Jena (see the Jena Web site for more information).

Note: GraphViz can be installed in any location. You will be able to configure it from IsaViz's Preferences window.

## 4. Running IsaViz for the first time

Once you have the following installed:

- a JVM 1.3.0 or later (1.4 strongly recommended: Known problems)
- GraphViz 1.8.9 or later (only the dot program is required)
- IsaViz

you should be able to run IsaViz by either:

- using one of the available scripts (run.bat) or (run.sh)
- entering the following command line from the IsaViz directory
  IsaViz 2.0 on Windows: java -classpath lib\isaviz.jar;lib\zvtm.jar;lib\jena.jar;lib\xercesImpl.jar;lib\xmlParserAPIs.jar;lib\icu4j.jar;lib\antlr.debug.jar;lib\junit.jar;lib\log4j-1.2.7.jar;lib\jakarta-oro-2.0.5.jar org.w3c.IsaViz.Editor
  IsaViz 2.0 on POSIX: java -classpath lib/isaviz.jar:lib/zvtm.jar:lib/jena.jar:lib/xercesImpl.jar:lib/xmlParserAPIs.jar:lib/icu4j.jar:lib/antlr.debug.jar:lib/junit.jar:lib/log4j-1.2.7.jar:lib/jakarta-oro-2.0.5.jar org.w3c.IsaViz.Editor
  IsaViz 1.x on Windows: java -classpath lib\isaviz.jar;lib\zvtm.jar;lib\jena.jar;lib\xerces.jar;lib\icu4j.jar;lib\antlr.debug.jar org.w3c.IsaViz.Editor
  IsaViz 1.x on POSIX: java -classpath lib/isaviz.jar:lib/zvtm.jar:lib/jena.jar:lib/xerces.jar:lib/icu4j.jar:lib/antlr.debug.jar org.w3c.IsaViz.Editor

The main class is org.w3c.IsaViz.Editor

The last step consists in configuring some directories. Launch IsaViz, go to Edit->Preferences, choose the "Directories" tab.

You have to choose a valid directory for temporary files (e.g. IsaViz/tmp or C:\Temp).
Then you have to tell IsaViz where to find GraphViz/dot: browse to the location of the dot executable file
(e.g. C:\Program Files\ATT\GraphViz\bin\dot.exe or /usr/local/graphviz/bin/dot).

The other directories are optional. If using a Linux or UNIX system, you should point the font directory to the one containing the font(s) you want to use for the Graph (see tab Rendering in the Preferences window). Failing to do so might result in bad text width computation and, therefore, unperfect layout.

By default, IsaViz 1.x is configured for GraphViz 1.7.11 or later. If you are using an earlier version, select the other option (the SVG output format changed between both versions and IsaViz needs to know which version of GraphViz/dot it deals with). IsaViz 2.0 does not offer any choice as it requires GraphViz 1.8.9 or later.

Note: if you want to add IsaViz to your CLASSPATH, you need the following entries

(IsaViz 2.1):

- lib\isaviz.jar
- lib\zvtm.jar
- lib\jena.jar
- lib\xercesImpl.jar
- lib\xmlParserAPIs.jar
- lib\icu4j.jar
- lib\antlr.jar
- lib\junit.jar
- lib\log4j-1.2.7.jar
- lib\jakarta-oro-2.0.5.jar
- lib\concurrent.jar
- lib\commons-logging.jar

(IsaViz 2.0):

- lib\isaviz.jar
- lib\zvtm.jar
- lib\jena.jar
- lib\xercesImpl.jar
- lib\xmlParserAPIs.jar
- lib\icu4j.jar
- lib\antlr.debug.jar
- lib\junit.jar
- lib\log4j-1.2.7.jar
- lib\jakarta-oro-2.0.5.jar

(IsaViz 1.x):

- lib\isaviz.jar
- lib\zvtm.jar
- lib\jena.jar
- lib\xerces.jar
- lib\icu4j.jar
- lib\antlr.debug.jar

### Sample files

In order to test your installation, you can try to import sample RDF files located in the export directory. There is also a sample ISV/XML project in the projects directory.

## 5. Building IsaViz

If you downloaded the source distribution of IsaViz, you can build it from the source code either using Makefile or Apache/Ant. Instructions are available in BUILD.txt.

| Emmanuel Pietriga Last modified: Mon Oct 18 17:35:51 Paris, Madrid (heure d'été) 2004