# Jigsaw on Macintosh

( This installation tutorial and suggestion list is based on my personal experiences with Jigsaw, Metrowerks Java, Sun Java SDK and the Macintosh. The standard disclaimer applies: neither Macalot Software or myself will be responsible in any way for problems resulting from the use of these instructions and suggestions, your mileage may vary. )

Getting the Jigsaw Archive

If you have not already done so, download the current Jigsaw source which at the time of this writing (11/10/96) is at version 1.0a3. The archive is available in both a TAR or GZIP TAR format. The GZIPed version will be the smallest, so thats the archive I'd recommend downloading.The GZIP format archive is available here via ftp or http.

Uncompress the Archive
The next step is to uncompress the Jigsaw zip archive. To do this you will need both a GNUzip extractor and a TAR extractor, both of which can be aquired at the following URL:

http://ww w.javaworld.com/javaworld/common/jw.resources.toc.html

You will use MacGzip to unzip the archive. Make sure you have the option to convert LF's to CR's turned off in MacGzip. This isvery important. Once the file has been unzipped you will have a file named Jigsaw.tar. This resulting TAR file must be uncompressed next with the TAR extractor. There are many files in this archive that must be treated as binary files and cannot have LF's converted to CR's. I found that regardless of the state of the checkbox in Aladdin's Stuffit Deluxe version 4.0, LF to CR translation still took place. This caused me a great deal of headaches, I therefore suggest unarchiving with MacTar or a similar application that you are certain won't translate LF's.

Uncompressing a UNIX TAR archive on Macintosh is usually no big task, but I'm afraid it is here for one reason. There are many files in this archive with longer than 31 character file names. Some 260 of them to be exact. When MacTar encounters a file with a long file name it just skips over it. While at least all of these skipped files are documentation files and not source files, this will still be a pain since you will have to manually dismiss a warning alert each time a long file name is encountered in the archive. While the loss of these files is a major problem, there is no easy solution at this time. Alternately you may want to uncompress the /User/api and /User/Reference directories using Stuffit Deluxe. Stuffit simply truncates these long file names, permitting you to go into these directories and rename these files manually, in order to review the api and reference documentation. Regardless, you do however loose the nice feature of online help, available on other platforms supporting 64 character file names.

It has been suggested by Anselm that these directories could be left in TAR archive format and a filter resource written that translates them on the fly. This would probably be the best solution to the problem on platforms with file systems limited to 31 character file names, although no work has yet been done in this regard.

Choosing a Development Environment

The SUN Java SDK 1.0.2 for Macintosh has a hopelessly flawed Socket class and is therefore unusable as far as Jigsaw is concerned. I am not aware of a later fixed version from SUN, if anyone is, please let me know. I have not tested with Apple's new MacOS Runtime for Java that is currently at beta 1. Again, anyone wishing to contribute feedback as to the successes/failures attributed with it's use, or any other Java runtime for Macintosh, I'll be glad to add your comments to this page.

For the sake of this 'recipe' however, I'll stick with using the Metrowerks CW10 IDE and Metrowerks Java runtime. I have been building Jigsaw under Metrowerks Java since version 1.0a1 and CW9 . I have witnessed many runtime bug fixes and some very radical changes to the Jigsaw internal architecture over that period. While there are still a few bugs remaining in the current Merowerks 1.0.2 runtime, it appears reasonably stable. The Jigsaw code is extremely stable at this point. There have been a few bug fixes and patches added since the 1.0a3 release.

Jigsaw the Easy Way
I think it's really important to point out here, that you don't have to compile all of the 300+ Jigsaw source files in order to use Jigsaw on Macintosh. The archive comes with a pre-compiled binary zip file that you can link against.

In short, unless you want to make changes to the code, all you need to do to build and run a Jigsaw httpd server is to link against the Jigsaw zip file contained in the classes folder. Here is how to do this, using the Metrowerks CW10 environment:
In the folder named "src", create a new Metrowerks project named "Jigsaw.µ" using the Java Library stationary. Immediately open the preferences for the project (using the Edit menu choice Project Settings...) and change the project type in the popup menu to "Runnable Zip File" and specify the Main Class as: w3c.jigsaw.http.httpd Add the file "Jigsaw.zip" to the project (and remove any placeholder files), then choose Make. Move the resulting "Jigsaw.out" file into the Jigsaw folder containing the WWW (space) directory and double-click to execute. That's it. It's that simple!

Jigsaw the Harder Way

While linking against the supplied zip file is fine for getting your feet wet, eventually you'll want to apply some of the bug fix patches to the source and probably want to extend Jigsaw by adding your own resource types. To do this, you will have to compile all of the 300+ Jigsaw source files contained in the 31 different packages that make up the Jigsaw httpd server. There are a few gotchas however, that you should be aware of before you start.

Know Bugs and Work Arounds

a) Do not attempt to build Jigsaw under Metrowerks CW9. Do yourself a favor and update to CW10. There are just too many bugs in CW9 and the 1.0 and 1.01 versions of the runtime to work through. Workaround: Save your sanity, update to CW10.

b) Java, from the standpoint of a development environment, permits the programmer to have like named source files, provided they occur in different packages. The Metrowerks IDE however does not permit this behavior, therefore, to build Jigsaw under MW you must create two seperate projects. The first project creates a zip file which is subsequently included in the second project. Workaround: Download the Jigsaw projects for Metrowerks self-extracting archive containing the two necessary projects and an AppleScript used to automate the build of Jigsaw.

c) Metrowerks IDE uses aliases to maintain the location of files in a Java project. When a project is imported to a different machine than the one it was created on, these aliases will not resolve, since the dirID's will be invalid. The IDE upon recognizing this, will subsequently search for the project files in a descending order, begining at the classes directory and searching subsequent directories alphabetically until the first matching file name is found. As mentioned previously, there are like named files in some of the Jigsaw packages and most of the time the IDE will find the wrong file. If you have problems compiling Jigsaw using the supplied Jigsaw projects for Metrowerks, suspect this problem first. Workaround: Use an option-click on each of the file names in the project window to verify they are the correct files. If they are incorrect, remove the file and then re-add the correct file to the package. This will be the case in the following packages:

Project: Jigsaw Part1.µ

    w3c.www.http - look for incorrect HTTP.java source
    file

Project: Jigsaw.µ

    w3c.www.protocol.http  - Request.java, Reply.java
    and perhaps others.
    w3c.www.protocol.http.auth  - look for incorrect
    AuthFilter.java
    w3c.www.protocol.http.cache  - many, probably best to
    remove all and re-add
    w3c.tools.forms - many, probably best to remove all and
    re-add

    Sorry I'm doing this from memory, there could be
    others!

d) There are some problems in the current CW10 Metrowerks Java compiler and in the IDE in regards to the way the project data base is searched for class dependancies. I have experienced times when you could remove binaries from a Java project and yet could still not recompile after changing base classes. Some of these problems are corrected in the MW Java compiler I am testing, but there are still some problem yet remaining. Workaround: If after verifying the files contained in the project are correct and after removing binaries the project still won't compile, try closing and then re-opening the project, this will usually correct the situation.

e) The 68K version of the Metrowerks 1.0.2 runtime has both a broken Threads class and a broken Sockets class. Metrowerks has these problems fixed in an upcomming 1.0.3 release and you should see a patch soon, but for now you cannot run Jigsaw sucessfully under 68K. Workaround: none, wait for 1.0.3 update.

f) The File class lastModified() method returns an incorrect (usually negative) time stamp for a file or directory's modification date. This causes Jigsaw to fail to index files and directories properly. (i.e., if you add a file or directory it won't show up). Again, this is now fixed in both the 68K and PPC runtime, but if you wish to use Jigsaw before this patch is publicly available you must modify the Jigsaw source as per the following. Workaround: Search for all occurances of File.lastModified() and enclose them in Math.abs() wrappers in both FileResource.java and DirectoryResource.java. For example in DirectoryResource.java

    public synchronized Enumeration
    enumerateResourceIdentifiers() {
    	// Check that our children repository is still
    valid:
    	acquireChildren() ;
    	// If extensible, update if needed:
    	if ( getExtensibleFlag() ) {
    	    File directory = getDirectory() ;
    	    if ( directory != null ) {
    		long dirstamp  =
    directory.lastModified();
    		dirstamp = Math.abs(dirstamp);	// <----
    Added JTD
    	....

While this is not an absolute fix, it will work reasonably well. Be sure to remove these wrappers when the 1.0.3 update is used. Since this bug is now fixed.

g) Java projects can be built as seperate class files (in the case of Jigsaw over 400) or as a single zip file containing all of the classes. I don't particularly recommend building Jigsaw as seperate classes. A single executable is better for a number of reasons, not the least of which are, use of much less disk space, less directory clutter, and easier execution of the resulting application. (i.e., you just double-click on the resulting .out file to execute it, rather than having to issue a javai command containing a working directory, classpath, main class).

Now with all that said, you can move on to the next step of creating the necessary two projects and adding the source files to the project. Alternately, you may want to download a self extracting archive containing the preconfigured Jigsaw projects for Metrowerks, if you have not already done so. If you'd like instead to create your own project files, the section to follow will explain how to create both projects.

Create the Jigsaw Projects
In the folder named "src" (within the Jigsaw folder), create a new Metrowerks project named "Jigsaw.µ" using the Java Library stationary. Immediately open the preferences for the project (using the Edit menu choice Project Settings...) and change the project type in the popup menu to "Runnable Zip File" and specify the Main Class as: w3c.jigsaw.http.httpd

Next, also in the "src" folder, create a new Metrowerks project named `Jigsaw Part1.µ` using the Java Library stationary. Add all of the files in the following directories. It is wise to add each package as a seperate group, naming the group the same as the package.

    w3c.cvs
    w3c.mux
    w3c.util
    w3c.jigsaw.auth
    w3c.jigsaw.config
    w3c.jigsaw.contrib
    w3c.jigsaw.daemon
    w3c.jigsaw.filters
    w3c.jigsaw.formedit
    w3c.jigsaw.forms
    w3c.jigsaw.html
    w3c.jigsaw.http
    w3c.jigsaw.indexer
    w3c.jigsaw.map
    w3c.jigsaw.pics
    w3c.jigsaw.resources
    w3c.jigsaw.ssi
    w3c.jigsaw.status
    w3c.jigsaw.tests
    w3c.tools.codec
    w3v.tools.crypt
    w3c.tools.dbm
    w3c.tools.sorter
    w3c.tools.timers
    w3c.www.mime
    w3c.www.http
    classes.zip

Once you have all the files added to the project, select Make from the Project menu. The compile can take anywhere from 10 minutes to an hour, depending on the state of file sharing, hard disk speed and HP of your particular machine. Perhaps even longer on 68K Macs. When the compile is complete, switch back to the Jigsaw.µ project, add the resulting `Jigsaw Part1.zip` file to the project, then add the files from the remaining packages below.

    w3c.www.protocol.http
    w3c.www.protocol.http.auth
    w3c.www.protocol.http.cache
    w3c.tools.forms
    w3c.jigsaw.cvs
    w3c.jigsaw.proxy
    Jigsaw Part1.zip
    classes.zip

Finally, select Make from the Project menu. When this compile is complete, move the resulting `Jigsaw.out` file into the sub-folder named Jigsaw (i.e., in to the directory containing the config directory), and double-click to execute Jigsaw. From their you should be able to access the Overview.html file. Have Fun! sinc, - Jeff Dripps

Last Updated - November 13, 1996 3:58PM EST
All contents of these WWW pages are (c) Macalot Software 1986-1996.