Jigsaw Frequently asked questions

# Jigsaw Frequently Answered Questions

### What is Jigsaw ?

- What's the purpose of Jigsaw, why yet another server ?
- Where can I get Jigsaw ?
- Why is Jigsaw written in Java ?
- Jigsaw is written in Java, it must be really slow...

### Using Jigsaw

- What's this indexing thing all about ?
- What are all these information in the form based resource editor ?
- How do I setup authentication ?
- How do I tie a resource to a directory not under my server root? [Sirilyan sirilyan@io.com]
- How do I setup a CGI script ?
- How do I setup Jigsaw as a proxy ?

### Technical stuff

- How can I extend Jigsaw ?
- Why does Jigsaw implements its own persistence mechanism ?
- How can I use HotJava on top of your HTTP client API ?
- Running Jigsaw on port 80 under UNIX
- Chrooting Jigsaw under UNIX

### Using Servlets

- What are servlets ?
- How do I compile jigsaw to use the servlets ?
- How do I install a servlet ?
- How does Jigsaw load local servlet classes ?
- How can I load remote servlets ?

You think your question about Jigsaw is worth entering this list, you have a better formulation for some of the answers ? Mail to jigsaw@w3.org !

### What's the purpose of Jigsaw ?

Jigsaw is the new W3C reference server. Its main purpose is to demonstrate new protocol features as they are defined (such as HTTP/1.1 or PICS), and to provide the basis for experimentations in the field of server software (such as the provided MUX prototypical implementation).

### Where can I get Jigsaw ?

You can download Jigsaw distribution file in various formats, and using either ftp or http:

Windows zip files (1.5Mo)

- FTP
- HTTP

UNIX gzip tar file (700Ko)

- FTP
- HTTP

### Why is Jigsaw written in Java ?

Java has a number of advantages that fit well with our purposes. It provides portable threads and garbage collection, allows for a very dynamic server architecture. It's ability to move code around may be use in future development to experiment with the mobile code concept.

### Jigsaw is written in Java, it must be really slow...

No so true ! Check out the performance evaluation of Jigsaw, which indicates that it performs at least as well as the CERN server.

### What is this indexing thing all about ?

To a normal HTTP web-admin, Jigsaw's configuration process might look really strange...Jigsaw's design emphasis two different processing stage in serving documents:

Indexing stage
  When documents enter the Web
Serving stage
  When documents are served to clients

In short the rationale for separating these two stages is to make the serving stage as efficient as possible, by having the indexing stage prepare as much as possible the work. A document enter the WEB space the first time Jigsaw serves it; this happen behind the scene most of the time, and consist in creating a resource for the document to be served by querying a resource factory. The current resource factory can be configured to create various kind of resources based either on the file name extensions, or (in case of a directory) based on its name.

However, once a resource is created, it no longer reflects the settings of the resource factory (available resp. as `/Admin/Extensions` and `/Admin/Directories`); in some sense the information gets compiled so that at serving time, processing overhead is reduced as much as possible.

### What are all these information in the form based resource editor ?

The current version of the generic resource editor is rather terse. At this point, the resource editor will present all the declared resource attribute values and some ways to edit them. All the attributes are declared in each resource reference manual.

Resource editors is an area in which you can expect big improvement in the next release. Right now, it is recommended that you use two browser windows, one displaying the form based editor, and the other one displaying the appropriate reference manual for the resource being edited (which described all the attributes semantics).

### How do I setup authentication ?

Setting up authentication through the form based interface requires you to run through the following stages:

1. Create an authentication realm, if required. This is done through the Realms resource, usually available as `/Admin/Realms`. You can of course reuse authentication realms to protect different areas of the server.
2. Setup an authentication filter on the appropriate resource. The target of the filter can be either a directory resource (in which case the filter will protect all the area defined by the sub-resources of this directory resource), or any other filtered resource (hence allowing you to protect a single resource). Setting up an authentication filter is done by editing the target resource, through the generic resource editor. If you want to protect, say the `/protected` directory resource, then you have to bring up its editor, which will usually be available as `/Admin/Editor/protected`.
3. Setup the authentication filter parameters. Once the filter is plugged in, you can edit its attribute by clicking on the appropriate link in the bottom of the target resource editor.

That's it ! For more information, you may want to read through the configuration tutorial.

### How do I tie a resource to a directory not under my server root?
Contributed by Sirilyan <sirilyan@io.com>

CERN server implemented this through the Pass directive, which let you map a server path to an absolute path on your file system. Jigsaw uses the w3c.jigsaw.resources.PassDirectory resource.

COOKBOOK METHOD: Create a new resource with Add resources in the Editor at the location you want the new server path to exist. Assign whatever name you desire to the new resource, and assign w3c.jigsaw.resources.PassDirectory for the class. Edit this new resource to change the pass-target attribute to the absolute path to the directory you want to serve.

You may want to change the name attribute of the 'index' file in that directory to Overview.html. name and filename are two separate attributes in Jigsaw; this is also a poor man's (or a Win95/NT user's) symlink.

Serving directories outside your server root may be a security risk.

### How do I setup CGI scripts ?

They are two ways to setup CGI scripts. The manual way requires that you describe each script to the server. Let's say your script's path relative to the server root is `WWW/cgi-bin/myscript`. You will first have to create an appropriate w3c.jigsaw.forms.CgiResource instance to wrap your script, by pointing your browser to the /Admin/Editor/cgi-bin/ directory resource. Click the Add resource link, and enter the name under which you wish your script to be seen, and the w3c.jigsaw.forms.CgiResource as the resource class.

Then edit the newly created resource, and setup it's command line (the command line the server will use to run your script). Each line of the text field should represent one argument, the first one being the script full path.

You can also register files of a given extension as scripts, by using the `/Admin/Extensions` extension editor. Say you want to have all `.pl` files to be exported as perl scripts. Register the extension, and map it to the w3c.jigsaw.forms.CgiResource; when required, you can even specify the interpreter to be run to execute the script (for example, under Windows 95, or NT).

### How do I setup Jigsaw as a proxy ?

Running Jigsaw as a proxy involves the following steps:

- Create an instance of the `w3c.jigsaw.proxy.ProxyDirectory` resource in the root resource store, by pointing your browser to /Admin/Editor and selecting the Add resource link. Type in the name of the resource (ie `proxy`), and its class (`w3c.jigsaw.proxy.ProxyDirectory`).
  At this point, you will need to edit this resource's attributes. To do so, select the Existing Resources link which will display a list of resources including the newly created proxy. Follow the proxy link to display an editable list of attributes of the proxy resource. You should set the `local-root` attribute to the old root resource (ie `root` under the default configuration) and select OK. This will make sure that requests targeted to the proxy itself will be served by the normal server, allowing for access to the configuration.
- Once the new resource is created, set it as the root resource of your server, by pointing your browser to /Admin/Properties/general and setting the root resource's name property (`w3c.jigsaw.root.name`) to proxy. Then select OK.
  Now point your browser to /Admin/Properties and select the Save Properties link.
- Jigsaw is now running as a proxy reconfigure your browser to run it...and have fun !

### How can I extend Jigsaw ?

Jigsaw can be extended in a number of ways. Here are just three possible things you can play with, from the simplest to the complex ones:

- Writing new resource classes: you may want to read the tutorial on this subject before getting any further. You can think of this as being a n efficient replacement for CGI scripts, although this is a much more powerful environment to extend the server.
- Writing new filter classes: if you want to experiment with specific authentication needs, or if you require special logging formats. A tutorial on writing new filters is also available.
- Hacking Jigsaw. Right now you can just override any of the Jigsaw classes to replace its implementation. In the future, most of the interesting things that you can do this way will be turned into specific interfaces (as is already the case for logging right now).

### Why does Jigsaw implement its own persistence mechanism

Jigsaw implements its own persistence mechanism while RMI already provides a way to serialize objects, why is it so, will it change ? What Jigsaw implements in the `w3c.tools.store` package is more then persistence. It provides both a way of serializing objects and a way of describing what and how the object will be dumped. The available meta-description of objects (that you can obtain through the `getAttributes` method of resources), is a central part of Jigsaw architecture, since it offers the ability to create generic resource editors. This is not likely to disappear.

However, Jigsaw persistence mechanism may be merged in the future to the RMI interface, just by providing an implementation of the `readObject` and `writeObject` method through its existing mechanism.

### How can I use HotJava on top of Jigsaw's HTTP client API ?

HotJava is Sun's Java based browser. If you want to experience an HTTP/1.1 compliant browser, you can run this browser on top of Jigsaw's HTTP/1.1 compliant HTTP client API. To do so, you need to define the `java.protocol.handler.pkgs` property to `w3c.www.protocol` before launching HotJava. The best way to do so is to edit the HotJava property files.

Jigsaw's HTTP client API defines a number of other properties, if you are planing to use this setting, you should read the HttpManager documentation to get the complete list of available properties. These will allow you to add caching, authentication, proxying and more to HotJava !

### Running Jigsaw on port 80 under UNIX

As of release 1.0alpha5, Jigsaw can now run on port 80, without running as the root user. To implement that you need to install the relevant piece of native code. This C code has been compiled and tested under Solaris, porting it to a different platform/architecture should be pretty easy.

Follow the normal installation procedure, and try to run Jigsaw on a port greater than 1024. Once this work, stop Jigsaw (through `/Admin/Exit`), Make sure your LD_LIBRARY_PATH variable includes the directory containing `libUnix.so` (this is the `Jigsaw/lib` directory under the standard release).

Select the user and group you want Jigsaw to run as. Make sure that user has read/write access to the entire `config` directory. Then, you just need to run Jigsaw through that special command line:

`java w3c.jigsaw.Main -user user -group group <other-options>`

Where user and group should provide (resp.) the user and the group you want Jigsaw to run as.

Warning: As the underlying UNIX process will change personnality right after acquiring the socket, the form based restart button (available from the properties editor) will no longer work, since the process will no longer be able to allocate a socket on port 80.
Under such a setting, the only way to restart Jigsaw is to kill it (through `/Admin/Exit`) and restart it manually.

### Chrooting Jigsaw under UNIX

As of release 1.0alpha5, Jigsaw can now - under UNIX - be chroot'ed. If you try to do so, you are supposed to have some experiences with chroot'ing programs. We will assume that you already have a correct root to run a standard HTTP server and that you have read and understood the Running Jigsaw on port 80 FAQ entry.

You need to install Java in that root (using whatever prefered way you want). To install Jigsaw, I would recommend using the following directory structure:

/usr/local/jigsaw/classes
  Should contain Jigsaw's current distribution jigsaw.zip class file
/usr/local/jigsaw/extensions
  Is used to add extensions to the server while running, and should be included in your CLASSPATH, before you start Jigsaw.
/usr/local/jigsaw/lib
  Should contain Jigsaw's native code support - ie libUnix.so -(to make the appropriate UNIX system calls)

Given that (don't forget to symlink the real `/usr/local/jigsaw` to the chroot'ed one), you should be able to reuse that script:

     #!/bin/sh
    # Jigsaw
    # $Id: FAQ.html,v 1.28 1998/05/27 13:00:32 yves Exp $
    # Jigsaw launcher

    # LD_LIBRARY_PATH will be set to work *only* before chroot, by the java script
    # We add here, support for PATH as they appear to be after the chroot

    CR_LD_LIBRARY_PATH=/usr/local/jigsaw/lib:/usr/local/java/lib/sparc:/usr/lib:/lib
    LD_LIBRARY_PATH=$CR_LD_LIBRARY_PATH:$LD_LIBRARY_PATH
    export LD_LIBRARY_PATH

    # CLASSPATH needs two hacks: one to include jigsaw.zip before chroot, and
    # an other one to include everything after chroot

    CLASSPATH=/0/w3c/abaird/sbroot/usr/local/jigsaw/classes/jigsaw.zip:/0/w3c/abaird
    /sbroot/usr/local/jigsaw/classes/servlet.zip:/0/w3c/abaird/sbroot/usr/local/jigs
    aw/classes/plus.zip:/0/w3c/abaird/sbroot/usr/local/jigsaw/extensions
    export CLASSPATH
    CR_CLASSPATH=/usr/local/jigsaw/classes/jigsaw.zip:/usr/local/jigsaw/classes/serv
    let.zip:/usr/local/jigsaw/classes/plus.zip:/usr/local/jigsaw/extensions
    CLASSPATH=$CR_CLASSPATH:$CLASSPATH
    export CLASSPATH

    # Ready to run jigsaw, now:

    cd /0/w3c/abaird/sbroot/jigsaw
    exec /usr/local/java/bin/java w3c.jigsaw.daemon.ServerHandlerManager $* -group n
    obody -user nobody -chroot /0/w3c/abaird/sbroot -root /jigsaw

### What are servlets ?

Servlets are server-side extensions programmed against the Servlet API. This interface is philosophically equivalent to the old CGI interface, but is both more powerfull and extremely more efficient. More information is available at jeeves.javasoft.com.

### How do I compile Jigsaw to use the servlets ?

NOTE: The default version of jigsaw has been compiled with servlet support, to use

Be sure to have a recent version of the servlet classes. Update your CLASSPATH to use those classes. Modify the Makefile in src/classes/w3c/jigsaw and add the servlet package at the end of the PACKAGES list, like this:

`contrib \
upgrade \
servlet`

Then, uncomment the line 144 of w3c/jigsaw/ssi/DefaultCommandRegistry.java like this:

`new w3c.jigsaw.ssi.servlets.ServletCommand()`

and adds the servlets package in the Makefile of the w3c.jigsaw.ssi package, like this:

`PACKAGES = \
jdbc \
servlets`

Now, you can recompile jigsaw.

### How do I install a servlet ?

Installing a servlet is pretty easy !

First of all, you have to choose where you want to place your servlets in your filesystem; this will usually be a single directory, typically somehting like servlets under your server's WWW directory. Once you have created the filsystem directory, create a Jigsaw w3c.jigsaw.servlet.ServletDirectory to export it. That resource will act as a context for all the servlets under it (Jigsaw can handle multiple servlet contexts within a single server). You can now add servlets into this special directory. Each servlet is managed by a w3c.jigsaw.servlet.ServletWrapper, to add a servlet you just have to create a ServletWrapper and in the servlet-class field put the class name of the servlet witch must be in the directory relative to the ServletDirectory resource.

Example :

You want to install the DateServlet in the WWW/servlets directory:

1. Create the directory servlets under WWW
2. Start the JigAdmin program and unfold all the nodes down to the space node.
3. Select the space node, and activate the Resources editor helper. Enter the ServletDirectory identifier (ie servlets) and the class of the resource (ie w3c.jigsaw.servlet.ServletDirectory)
4. Put the servlet class (ie DateServlet.class) in WWW/servlets.
5. Create a ServletWrapper to the ServletDirectory and call it DateServlet for example.
6. Set the servlet-class field of the ServletWrapper to DateServlet
7. Commit your changes

Now DateServlet is reachable at http://your-server-host/servlets/DateServlet.

### How does Jigsaw load local servlet classes ?

Jigsaw use a ServletClassLoader to load servlet classes from the ServletDirectory. If a servlet class is modified when jigsaw is running, the ClassLoader look at the last modified date of the class in memory and the class on the disk and reload the classe if its necessary.

### How can I load remote servlets ?

You can use remote servlets by using a RemoteServletWrapper instead of the ServletWrapper.

Example : Add the remote servlet http://www.servlet.com/RemoteServlet.class to jigsaw.

1. Create the RemoteServletWrapper in the ServletDirectory.
2. Set its "servlet-base" field to http://www.servlet.com
3. Set its "servlet-class" field to "RemoteServlet" (without .class)
4. Commit changes.

Note : the url http://www.servlet.com/RemoteServlet.class must be a Java compliant class file.

Jigsaw Team
$Id: FAQ.html,v 1.28 1998/05/27 13:00:32 yves Exp $