Project plan | Time usage reports | Change log | Meeting minutes | Functional specification | Technical design document | Implementation document | Testing reports | User's Manual | Final report

Software Engineering Project:
Venice

UML Visualization Tool

Implementation document

Last updated: Thursday 10.05.2001 11:10:41 EEST

Table of contents

1 Introduction

2 Implementation platform
2.1 Development environment
2.2 Required libraries

3 Build environment
3.1 Directory structure
3.2 Makefile-based build system

4 To-Do list
4.1 Main application framework
4.2 GXL model subsystem
4.3 Visualization subsystem
4.4 User interface subsystem

5 Miscellaneous notes

Appendices
A Bugfixes and enhancements made to Jazz source code.
B Instruction for setting up CVS and using it.

1 Introduction

Purpose of this document is to give information needed to continue working on Venice and maintaining it. This document describes the implementation platform and build environment of Venice. Also points for further improvements are listed.

2 Implementation platform

2.1 Development environment

Venice is developed on JAVA2 platform in Linux environment. JAVA2 Development Kit 1.3.0 or newer is required. Basic UNIX utilities such as find and rm are needed by build system.

2.2 Required libraries

Venice uses following external libraries:

3 Build environment

This chapter describes the source code directory structure and the build system which can be used to build VENICE.

3.1 Directory structure

After extracting the downloadable venice source archive, the following main directories can be found:


venice-src/
|-- jazz
`-- venice

The main level source directory (venice-src/) includes the needed external libraries and different files needed by the build system:

Directory venice/ contains the actual VENICE source code as .java-files.

Directory jazz/ contains modified source code for Jazz graphics library. Modifications are bug fixes which either VENICE or JAZZ team has done and Jazz team has adopted them and they will be included in next Jazz release. Jazz has its own build system which is described in README files in jazz-directory. See Appendix A for information on changes made to the Jazz library.

Also other changes to Jazz were made than bug fixes. Modified versions of Zoom and Selection event handlers are in venice-directory. It has not been discussed if these will be included in future Jazz releases.

3.2 Makefile-based build system

VENICE build system is based on use of UNIX make tool. The following make targets are defined in the Makefile:

TargetDescription
venice-only.jarBuild venice-only.jar which contains only the class files for venice and no class files for required libraries. Runnable using command 'java -jar venice-only.jar' if required libraries are present in the same directory.
venice.jarBuild venice.jar which contains everything in venice-only.jar PLUS all required libraries including Jazz and JAXP. Runnable using command 'java -jar venice.jar'.
javadocsBuild javadocs for the project at location specified in Makefile.
protoBuild venice.jar and copies it to location specified in Makefile for web access.
cleanCleans the build directory from compiled class files and backup files.

4 To-Do list

This sections lists points for further improvements in VENICE.

4.1 Main application framework

4.2 GXL model subsystem

4.3 Visualization subsystem

4.4 User interface subsystem

5 Miscellaneous notes

Visualization subsystem implements a debug menu. Different debug functions of visualization subsystem can be accessed through the menu. These include a scenegraph browser which can be used to analyze Jazz scenegraph structure. These functions can be accesed via the debug menu in the menubar.

Visualization components also implements a debugDump() method. When this method is called, debug information about node is printed. This method can be accessed by selecting a node in Jazz canvas and then activating the pop-up menu.

Appendix A: Changes made to Jazz library

ZNode's updateBounds()-method was modified to prevent unnecessary node events. Unnecessary node events resulted in unacceptable performance in VENICE.

Code was modified in the following way:


Index: src/edu/umd/cs/jazz/ZNode.java
===================================================================
RCS file: /home/group/venice/project/cvsroot/venice-src/jazz/src/edu/umd/cs/jazz/ZNode.java,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -r1.1.1.1 -r1.2
--- src/edu/umd/cs/jazz/ZNode.java	2001/05/03 16:50:48	1.1.1.1
+++ src/edu/umd/cs/jazz/ZNode.java	2001/05/06 14:49:19	1.2
@@ -748,9 +748,23 @@
     protected void updateBounds() {
         // XXX should check to see if our bounds actualy change, if
         // not then stop forwarding the event up the tree.
+        
+        // Checking code added, hopefully it's right
+        // Hannu Laurila, 2001-05-06
+
+        ZBounds myOldBounds = null;
+        if (bounds != null)
+            myOldBounds = new ZBounds(bounds);
+
         computeBounds();
+
+        // if bounds did not change, return without event percolation
+        if (myOldBounds != null && myOldBounds.equals(bounds))
+            return;
+
         percolateEventUpSceneGraph(ZNodeEvent.createBoundsChangedEvent(this));
         percolateEventUpSceneGraph(ZNodeEvent.createGlobalBoundsChangedEvent(this));
+        
         if (parent != null) {
             boolean hadListener = hasNodeListener;
             hasNodeListener = false;
@@ -1032,4 +1046,4 @@
         trimToSize();   // Remove extra unused array elements
         out.defaultWriteObject();
     }
-}
\ No newline at end of file
+}

repaint() calls were added to ZVisualLeaf's addVisualComponent/removeVisualComponent methods. This fix was needed for correct repainting of interface labels.

Code was modified in the following way:


Index: src/edu/umd/cs/jazz/ZVisualLeaf.java
===================================================================
RCS file: /home/group/venice/project/cvsroot/venice-src/jazz/src/edu/umd/cs/jazz/ZVisualLeaf.java,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -r1.1.1.1 -r1.2
--- src/edu/umd/cs/jazz/ZVisualLeaf.java	2001/05/03 16:51:01	1.1.1.1
+++ src/edu/umd/cs/jazz/ZVisualLeaf.java	2001/05/07 07:15:08	1.2
@@ -96,6 +96,7 @@
         visualComponent.addParent(this);
         updateVolatility();
         reshape();
+	repaint();
     }
 
     /**
@@ -137,6 +138,7 @@
         visualComponent.removeParent(this);
         updateVolatility();
         reshape();
+	repaint();
     }
 
     /**
@@ -449,4 +451,4 @@
         trimToSize();   // Remove extra unused array elements
         out.defaultWriteObject();
     }
-}
\ No newline at end of file
+}

ZLine was modified to prevent a null pointer exception on deserialization.

Code was modified in the following way:

Index: src/edu/umd/cs/jazz/component/ZLine.java
===================================================================
RCS file: /home/group/venice/project/cvsroot/venice-src/jazz/src/edu/umd/cs/jazz/component/ZLine.java,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -u -r1.1.1.1 -r1.2
--- src/edu/umd/cs/jazz/component/ZLine.java	2001/05/03 16:51:07	1.1.1.1
+++ src/edu/umd/cs/jazz/component/ZLine.java	2001/05/03 17:13:53	1.2
@@ -173,6 +173,6 @@
         x2 = in.readDouble();
         y2 = in.readDouble();
 
-        setLine(x1, y1, x2, y2);
+        getLine().setLine(x1, y1, x2, y2);
     }
-}
\ No newline at end of file
+}

Appendix B: Instructions for using CVS

In this chapter is included information on how we used CVS during the project. This information might be useful for setting up a CVS system for further development of the system.

Project Venice: Instructions for using CVS
------------------------------------------

Per-user initialization:

	Add the following line to a suitable place in your .profile
	file in your home directory:

		export CVSROOT=/home/group/venice/project/cvsroot

	If you plan to work on the project on CSL-1 machines, 
	you need also to set PATH and MANPATH because they
	don't have CVS in the default path.

		export PATH=$PATH:/opt/cvs/bin
		export MANPATH=$MANPATH:/opt/cvs/man

	IT IS RECOMMENDED TO WORK ON VENICE ONLY ON CSL-2 MACHINES!
	JAVA2 1.3 does not work on CSL-1 and also the CVS version
	installed on CSL-2 machines is more recent.

To begin working on project source code:

	1. Check out the project 'venice-src' from the repository:

		cd		# (go to your own home directory)
		cvs checkout venice-src

	2. You'll find venice source code in the venice-src directory.

	3. Muddle with the code.

	Notice that you may have multiple checkouted copies of the source
	code.

Preparing to add a file to the source code tree:

	1. Create and write the file you are going to put to the
	repository:

		cd ~/venice-src/venice
		emacs File.java

	2. Mark the file to be added on next commit:

		cvs add File.java

Removing a file from the source code tree:

	1. Delete the file from your working directory:

		cd ~/venice-src/venice
		rm File.java

	2. Mark the file to ba removed from the repository on next commit:

		cvs remove File.java

	(Same using only one command: 'cvs remove -f File.java')


Updating your working directory to have the latest stuff in the repository:

	Issue the commands:

		cd ~/venice-src
		cvs update

	Beware, that cvs will try to solve conflicts by merging 
	differences between individual files. This happens if you
	have modified locally a file for which there is now a newer
	version in the repository than the version you have modified.

	Dry-run using 'cvs -n update'.

Commiting your work to the repository:

	Your work is not visible to others before you commit it to
	the repository using the following commands:

		cd ~/venice-src
		cvs commit

	The command prompts you for a log message. Please describe
	your updates.

	NOTE: Please be sure that the version in your directory
	compiles cleanly before committing it! Preferably, first
	do a 'cvs update', then compile and now if it compiles,
	'cvs commit'.

Releasing your checkouted version:

	Issue the following commands:
	
		cd		# (go home)
		cvs release -d venice-src

	The directory will be deleted. If you have modified files
	which you have not committed, you will be warned.

	It is not necessary to release your checkouted version very often.
	But please use 'cvs release' instead of 'rm -r' so that
	cvs history and status information will be correct. 

	Please understand that this only releases your own working
	copy of the project - the files are not removed from the
	repository!

Tagging a version:

	A version can be tagged using 'cvs tag' command. The tagged
	version can later be retrieved using the tag.

	To tag current version as VENICE_M1, issue the following
	commands:

		cd ~/venice-src
		cvs tag VENICE_M1

Importing vendor sources to VENICE tree:

	The jazz sources were imported to VENICE source tree because
	we needed to do some modifications and bug fixes to them.

	CVS has features for tracking third-party sources.

	The import was done using the following command:                  

		cvs import -m "Import of JAZZ 1.1" venice-src/jazz \
			CS_UMD_EDU_DIST JAZZ_1_1

	After this, a checkouted copy was updated using 'cvs update -d'.
	Because jazz source tree includes also binary files, the following
	command was issued in ~/venice-src/jazz:

		find . -name "*.jpeg" -o -name "*.jpg" -o \
			-name "*.gif" -o -name "*.jar" \
			| xargs -n1 cvs admin -kb

	This flags the binary files in Jazz source tree so CVS knows
	about them. Because something might have got wrong already in
	the initial import, the following was done:

		cd ~/venice-src
		diff -ur jazz ~/tmp/jazz-1.1/jazz-1.1/

	No problems were found!

	More information on the matter can be found from CVS Manual:

		http://cvshome.org/docs/manual/cvs_13.html

More information:

	www.cvshome.org
	http://www.cs.helsinki.fi/u/kpalaaks/ohtu/CVS.html
	http://www.cs.helsinki.fi/group/chromos/cvsohje.html
	cvs --help 
	cvs --help-commands
	cvs --help commandname
	http://www.cvshome.org/docs/manual/index.html

Appendix A: How to repository was set up

	The repository was setup in the following way:

	1. 	Perform the per-use initialization steps 
		described in the beginning of the document.

	2.	Set up the CVS repository with good permissions:

		mkdir $CVSROOT
		chgrp venice $CVSROOT
		chmod 2770 $CVSROOT
		cvs init
	

	3.	Initial import of the sources:

		cd /home/group/venice/project/src
		cvs import venice-src DEFAULT_VENDOR DEFAULT_RELEASE


Appendix B: Working on the project remotely using ssh.

	You can work on the project on your home Linux machine
	(for other platforms, see www.cvshome.org) if you can
	access melkinpaasi.cs.helsinki.fi using SSH.

	(We can't use melkki because cvs software installed 
	at /opt/cvs does not include CVS server functionality needed 
	here).

	1. Install CVS software on your Linux machine. It is shipped
	with almost every distribution and it is usually automatically
	in the path so there is no need to set PATH or MANPATH.

	2. Put the following in your .cshrc (tcsh):

	setenv CVSROOT :ext:hlaurila@melkinpaasi.cs.helsinki.fi:/home/group/venice/project/cvsroot
	setenv CVS_RSH ssh
	setenv CVS_SERVER /usr/bin/cvs

	(substitute hlaurila with your own username)

	These commands are for tcsh. If you use BASH, use appropriate
	syntax (export VARNAME=value) and put the commands in .profile
	instead.

	3. Now use cvs like you would use at CS machines.

	If you find the continuos asking of password by SSH annoying,
	please set up your SSH connection to use RSA authentication.
	(see manual pages for ssh, ssh-keygen and ssh-agent).