Jigsaw

# 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 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 ?
- Upgrading my resources from 1.0alpha to 1.0alpha3

You think your question about Jigsaw is worth entering this list ? Mail it 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 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 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 ?

Jigsaw supports CGI script through a the w3c.jigsaw.forms.CgiResource resource class. Let's say your script's path relative to the server root is `WWW/data/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/data/ directory resource. Click the Add resource link, and enter the name under which you wish your screen 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.

### 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 (here `w3c.jigsaw.proxy.ProxyDirectory`).
  At this point, you may want to edit some of this resource's attributes (in particular, you should set the `local-root` attribute to the old root resource (ie `root` under the default configuration). This will make sure that requests targeted to the proxy itself will be served through 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 editing the the root resource's name property - `w3c.jigsaw.root.name` - found in /Admin/Properties/general, and setting it to `proxy`. Then save the properties, and restart the server.
- Jigsaw is now running as a proxy, it does not yet do caching. To enable caching, you have to configure the HTTP client API of Jigsaw. Go to `/Admin/properties`, select the proxy properties link, and make sure the filters attribute contains:`
  w3c.www.protocol.http.cache.CacheFilter`

Restart Jigsaw again, it is now running as an HTTP/1.1 compliant caching proxy !

### 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.jigsaw.resource` 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 !

### Upgrading my resources from 1.0alpha to 1.0alpha3

Here are some of the things one might encounter when converting software written for an early version of Jigsaw to run with the current version (these notes are from converting a medium-sized application which integrates Jigsaw with an ODBC database and does some HTML generation of database results):

- Several classes have been moved to different packages. For example, w3c.jigsaw.http.HTTP is now w3c.www.http.HTTP, all of w3c.mime is now w3c.www.mime, etc.
- Some class names are spelled differently. For example, MIMEType is now MimeType.
- Some functions have different names. For example, getField of the class Request is now getValue, whose use is recommended only for getting headers not defined by 1.1 (all 1.1 headers now have specific accessors).
- Some functions' parameter signature is now different. For example, getMethod (of class Request) no longer takes any arguments, makeReply (of Request) no longer takes Integer but int (result codes in HTTP have been changed accordingly).

Anselm Baird-Smith
$Id: FAQ.html,v 1.9 1996/10/04 13:59:23 abaird Exp $