( 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.