Understanding the basics...

How do I install Jigsaw?

Get the appropriate package (see FAQ).Then read the README file from the documentation!

Follow the installation instructions (i.e. run the installation script).

Jigsaw works with a JDK >= 1.2 (since Jigsaw 2.1.0). We recommend the use of a JDK version >= .3 for Jigsaw 2.2.* even if it works with 1.2, otherwise some non-critical functionalities may be available.

Be sure that your CLASSPATH is set up correctly.

Troubleshooting:

  1. If you get an error indicating that a class is not found (java.lang.NoClassDefFoundError), you probably have a wrong CLASSPATH.
  2. Windows users: if you get an "out of environment space" error, you should increase the DOS environment space (see Microsoft knowledge base).

What if I want to compile Jigsaw?

First, be sure that recompilation is really what you want.

Set the appropriate CLASSPATH to use the classes instead of the jar from the package.

CLASSPATH = <instdir>/Jigsaw/src/classes/:...

instead of

CLASSPATH = <instdir>/Jigsaw/classes/jigsaw.jar:...

Of course be sure to add all the external jars needed by your version of Jigsaw, servlet.jar, sax.jar and xp.jar. Some sources may require additional packages like jakarta-oro and jtidy.

Then you can use make in any directory under<instdir>/Jigsaw/src/classes. Another way if you want to compile everything faster, see this:

cd <instdir>/Jigsaw/src/classes && javac -O `find . -name \*.java`

(Windows Users will uses \ instead of / in paths).

Let's start running Jigsaw...

Just type in the following command:

cd <instdir>/Jigsaw/Jigsaw
java org.w3c.jigsaw.Main -host host -root <instdir>/Jigsaw/Jigsaw

(Windows Users will uses \ instead of / in paths).

Jigsaw should be running, and will probably have emited a message like:

jigsaw Sample/Jigsaw> java org.w3c.jigsaw.Main
loading properties from:
/0/w3c/cbournez/Jigsaw/Jigsaw/config/server.props
*** Warning : JigAdmin[2.2.2]: no logger specified, not logging.
JigAdmin[2.2.2]: serving at http://ender.inria.fr:8009/
Jigsaw[2.2.2]: serving at http://ender.inria.fr:8001/

Where are the server configuration files?

Be careful. All the configuration is not handled by plain text configuration files. There is a slight difference between what is server Configuration and what is Administration. Configuration includes definition of basic server properties (such as server root, port, keep alive, logging,...). All these properties are set in Jigsaw/config/http-server.props. Administration, on the other side, deals with the way the resources are served. Jigsaw includes an Administration server, which has it self properties (inJigsaw/config/admin-server.props). It allows to configure ressources served throught JigAdmin. Most of the usual tasks on the server can be completed through the admin server and JigAdmin. Note that JigAdmin also allows to perform the admin-server administration tasks as well.

http-server and admin-server

But what is a resource?

You can find a designer-friendly description of what a resource is here. All what you need to know is that a resource is an object you may want to serve with your Jigsaw server. It can be many kinds of objects but it is usually a static file or a dynamically generated content. Here is a summarized list of resources:

Standard resources are basic resources that you expect any server to support (files, directories)
Extension resources are mainly dynamic content objects (e.g. servlets, ZIP archives, directory listing).
Admin resources are special resources that allow Jigsaw's administration.
Property resources are wrappers to subsets of Jigsaw properties, that allow to edit these properties.

According to the type of resource, the server will use an appropriate mean to serve it, which is described by a frame. You can find also a designer-friendly documentation about frames. However, here is a summarized view of frames existing in Jigsaw:

Standard frames are HTTP-related frames. They allow the server to serve basic resources but also handle redirection, virtual hosting and content negotiation.
Extension frames are mainly designed to serve dynamic content (CGI, servlets,...) but also special resources like CVS or ZIP resources.
Filter frames allow you to filter the requests and replies (many different usages, e.g. authentication, log, HTTP errors, cache).
Proxy frames are relative to the proxy features of Jigsaw.
Admin frames are related to Jigsaw's administration (see Admin resources).
Specific frames can be attached only to specific resources (there is an explicit combination between a resource and a frame, a specific frame won't work with any other resource than the one it is made for).
Metadata frames are used to serve and/or store metadata.

Do I really need to attach a frame to each resource I want to serve?

Of course the answer is no. The server has a default behaviour which allows to automagically "configure" the resources with appropriate frames. This is done by an indexer. Of course, you can override or tune this behaviour by changing the default indexer. For example, you could choose among the various existing indexers (ContentTypeIndexer, SampleResourceIndexer...). Moreover, you can choose differents indexers for different subdirectories in your resources repository. It does not prevent from configuring manually resources and frames, even in an indexer's scope. An indexer always leave untouched manual configurations.

To summarize: the default root for the Jigsaw resource tree is Jigsaw/WWW/.(Note that in a freshly installed Jigsaw, it is not empty). If you simply add an HTML file in this directory, the default indexer will automatically configure a FileResource with an attached HTTPFrame the first time you will request this file to the server.