# IsaViz: Installation Instructions

Important Note

Several people have encountered difficulties importing local RDF files in IsaViz 1.2 (this will also be true for version 2.0): 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 version 1.6.x (jena.jar, icu4j.jar, antlr.debug.jar) or Jena 2 preview 2 for IsaViz 2.0
  - Xerces-J version 1.4.4 (xerces.jar) or version 2 (xercesImpl.jar,xmlParserAPIs.jar) for IsaViz 2.0
- GraphViz from AT&T version 1.8.x or later (version 1.7.x is no longer supported in IsaViz 2)

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 is based IsaViz's GUI. It is included in this distribution (zvtm.jar). More information is available at http://zvtm.sourceforge.net

### 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/

You must download version 1.7.6 (with support for SVG) or later. IsaViz only requires the DOT program. 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 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

Apache's Xerces-J 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 IsaViz.zip 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)
|
|
---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 uses Jena and Xerces-J (included in the distribution). You might want to use versions of these other than the ones included. The requirements are:

- for Jena, version 1.6.x (version included in this package: 1.6.1) - (Jena 2 preview 2 for IsaViz 2.0 alpha 1)
- for Xerces-Java 1, version 1.4.x (version included in this package: 1.4.4 ; Jena 1.6.x will not work with Xerces 2) - (Xerces 2 for IsaViz 2.0 alpha 1)

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 (even beta or candidate release) strongly recommended: Known problems)
- GraphViz 1.7.6 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 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
  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

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. You should point the font directory to the one containing the font you want to use for the Graph (see tab Rendering in the Preferences window).

By default, IsaViz 1.x is configured for GraphViz 1.7.11 or later (IsaViz 2.0 does not offer any choice as it requires GraphViz 1.8 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).

Note: if you want to add IsaViz to your CLASSPATH, you need the following entries
(IsaViz 1.x):

- lib\isaviz.jar
- lib\zvtm.jar
- lib\jena.jar
- lib\xerces.jar
- lib\icu4j.jar
- lib\antlr.debug.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

## 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 project in the projects directory.

| Emmanuel Pietriga Last modified: Mon May 12 13:20:51 Eastern Daylight Time 2003