Grappa / FAQ    Last updated: Tue May 10 10:01:08 EDT 2005

• Installation
  1. How do I install Grappa?
  2. How do I build from the source?
  3. Is there a demo I can look at?
• Licensing
  1. How to I license Grappa?
• Miscellany
  1. Is there a mailing list or message group?
  2. How do I report a bug?
• Usage
  1. How come all my nodes and edges draw on top of each other at the same place?
  2. Does Grappa work with JDK1.4?
  3. Does Grappa work with JDK5.0 (a.k.a., JDK1.5)?
  4. How do I trigger actions when I click on elements in the graph?
  5. The javadoc documentation is OK, but what else do you have?
  6. Can I use Grappa to generate GIF or JPEG images?

Installation  ^(top)

1. How do I install Grappa?
   First download the Grappa gzipped-tar file and unpack it any number of ways, such as the WinZip tool or the Linux command-line:

     gunzip < grappa.tgz | tar xvf -
   

   Then, look in the archives folder for the package file of your choice (usually grappa1_2.jar) and place that file somewhere in your Java CLASSPATH (any basic Java book will explain what that means) and you are ready to make use of the Grappa package in your Java programs by simply adding a

     import att.grappa.*;
   

   statement in your source files.
   ^(top)

2. How do I build from the source?
   Assuming you want to build the Grappa 1.2 source and that you have either JDK1.2 or JDK1.3 or JDK1.4 installed, you may proceed as follows (Note: these are Linux style directions, modify with backslashes instead of slashes as appropriate for Windows):
   • First you will need to compile the JavaCup runtime package. The JavaCup runtime package is distributed with Grappa. The entire JavaCup tool, which you would need if you plan to modify the 'dot' parser supplied with Grappa, is available at http://www.cs.princeton.edu/~appel/modern/java/CUP/ . To compile the JavaCup runtime package, get into src/jdk1.2/java_cup/runtime and run:

       javac *.java
     

   • Next, you need to compile the Grappa source, so get into src/jdk1.2/att/grappa and run:

       javac -classpath ../.. *.java
     

   • Finally, put src/jdk1.2 in your CLASSPATH. Note that it is probably preferrable to keep your class files in a folder separate from your Java source files, which can be accomplished by using the '-d' option to javac or by moving the class files after you compile. Java books can help with these basics. Also, some hokey shell scripts (Korn Shell) are in the src directory, but they are not really meant for the general public and will require modification. Nonetheless, it is possible that some will find them useful.
   
   ^(top)

3. Is there a demo I can look at?
   Yes, graph files and some crude demo applications are provided in the DEMO folder. The jdk1.2 folder within DEMO is probably of most interest. Assuming that the Grappa package is in your CLASSPATH and also that the current folder is in your CLASSPATH as well, then in the jdk1.2 demo folder, you can try running:

     java Demo12 ../sample.dot
   

   Note that the graph in the sample.dot file already has layout information contained in it (by means of the pos element attribute). Pressing the right mouse button provides a popup-menu. Pressing the left mouse button selects elements (either individually or by sweeping). Pressing the control-key and the left mouse button on an element lets you select additional elements without clearing the previously selected elements. Pressing the shift-key and the left mouse button on a piece of blank graph creates a new node while doing the same in an existing node and dragging to another existing node creates an edge. Pressing the labelled "Layout" button to the left of the demo panel first tries to call a local layout script (formatDemo) and then, if that fails, which it almost certainly will, it will try to contact our web server to perform the layout. This latter should work as long as you have a live connection to the internet.
   ^(top)

Licensing  ^(top)

1. How to I license Grappa?
   Grappa is licensed under the same arrangements as are used for graphviz, which is essentially Open Source. Refer to the graphviz download page for additional information.
   ^(top)

Miscellany  ^(top)

1. Is there a mailing list or message group?
   There is no specific mailing list for Grappa setup. The graphviz list can field Grappa questions (refer to the graphviz pages for information about that message group) or you questions can be sent directly to the author .
   ^(top)

2. How do I report a bug?
   You can use the graphviz bug form or send reports directly to the author .
   ^(top)

Usage  ^(top)

1. How come all my nodes and edges draw on top of each other at the same place?
   Grappa does not do layout, though it provides a convenience method (GrappaSupport.filterGraph(...)) to make using an external layout engine simpler. Moreover, since Grappa stores graph structure information and provides several methods for traversing graphs and retrieving elements, it simplifies the task of coding your own layout engine directly in Java.
   ^(top)

2. Does Grappa work with JDK1.4?
   Yes, the Grappa 1.2 works with both JDK1.2, JDK1.3 and JDK1.4. Demo12.java, however, contains a deprecated method that can be easily updated if you do not like getting the deprecation warning.
   ^(top)

3. Does Grappa work with JDK5.0 (a.k.a., JDK1.5)?
   Almost. Some minor tweaks to the source are needed, but I'd like to wait until the point one release before I worry about it. I am content with 1.4. Early adopters can easily perform the source tweaks themselves.
   ^(top)

4. How do I trigger actions when I click on elements in the graph?
   Grappa defines a GrappaListener interface and methods in GrappaPanel for adding and removing a listener. By default, there is no listener. However, Grappa does supply an extensible GrappaAdapter class which provides one implementation of a GrappaListener as a convenience. The demo application demonstrates how it can be added to a GrappaPanel.
   ^(top)

5. The javadoc documentation is OK, but what else do you have?
   Although there is an early paper (Grappa: A GRAPh PAckage in Java by Naser S. Barghouti, John M. Mocenigo and Wenke Lee at pages 336 - 343 in the Proceedings of the 5th International Symposium on Graph Drawing in Rome, 1997 and published by Springer-Verlag [ISBN: 3-540-63938-1]), it is rather out-of-date and only introductory in its depth. So, for all practical purposes, the javadoc documentation is it.
   ^(top)

6. Can I use Grappa to generate GIF or JPEG images?
   Grappa is intended for interactive display of graphs (zooming in, deleting/adding elements, displaying an updated layout, etc). While you can access Java's print classes to print a graph, the default behavior Grappa uses is to shrink the graph to the size of the paper. This behavior might still be OK if you are generating a PDF that will be viewed on another computer, but most graphs get fairly illegible quickly unless you are printing on one of those HP Plotters (the things with rolls of 3' or 4' wide paper).

   If all you want is to generate a GIF or JPEG, you need only use dot, neato or the other graphviz layout tools directly, they take options to generate such output.

   You can also go the hybrid route, namely, use Grappa for interactive display and then when a user wants a GIF/JPEG snapshot, use the GrappaSupport.filterGraph() method to send the graph over to a server running, for example, dot (or send it to a local dot executable) and have it generate the image which can then be saved by the user.
   ^(top)