# Jigsaw properties

Jigsaw properties can be split into the following groups

- General properties
- Connection properties
- Shuffler properties
- Logging properties

## General properties

The set of general properties include:

- w3c.jigsaw.host
- w3c.jigsaw.space
- w3c.jigsaw.host
- w3c.jigsaw.port
- w3c.jigsaw.root.store
- w3c.jigsaw.root.name
- w3c.jigsaw.trace

### w3c.jigsaw.root

This property should provide the top directory of the server. This property, by itself, is only used to get defaults value for other properties. A typical top directory for a server will contain the following sub directories:

config
  Which will contain the required configuration files, among which:
  httpd.props
    Will be the file containing the Jigsaw properties,
  jindex.cfg
    Will be the file containing the default settings for the indexer,
logs
  Which will contain the log files.
WWW
  Which will contain the actual entities to be exported, along with their description.
bin
  Will optionally contain some scripts to run the binaries associated with Jigsaw.

This property has no defaults, and is required.

### w3c.jigsaw.space

The directory hosting the information space to be exported by Jigsaw.

If this property isn't defined, it will default to <w3c.jigsaw.root>/WWW.

### w3c.jigsaw.host

This property should provide the full name (including the domain name) of the machine that hosts the server. Don't forget to provide the host's domain-name along with its name, otherwise, all urls dynamically generated by the server will fail when trigered from a machine outside the server's domain.

This property defaults to the machine on which the server runs.

### w3c.jigsaw.port

The port on which the server will listen for client connections. Unless you run the server as root, you won't be able to run the server on a port lesser than 1024. This will be fixed in future releases.

This defaults to port 8001.

### w3c.jigsaw.root.store

The name of the store repository to be used for the space directory.

This defaults to .jigidx.

### w3c.jigsaw.root.name

The name of the resource to be used as the server's root resource. This name should be a valid resource name within the scope of the space directory resource store (see above). This property is used, for example, to turn the server into a proxy (by giving the name of some ProxyDirectory resource, instead of the default name of the DirectoryResource for the space directory).

This defaults to root.

### w3c.jigsaw.trace

Turn the server in trace mode. This flag wil lmake the server emit various traces into the logger trace file, along with some debugging information to the server's standard output stream. This flag has to be turned on for clients trace flag to be effective.

This defaults to false.

## Client properties

The set of clients properties include:

- w3c.jigsaw.keep_alive
- w3c.jigsaw.client.priority
- w3c.jigsaw.client.bufsize
- w3c.jigsaw.client.debug
- w3c.jigsaw.client.keep_alive.timeout
- w3c.jigsaw.request.timeout
- w3c.jigsaw.client.max
- w3c.jigsaw.client.min

### w3c.jigsaw.keep_alive

Should the server try to keep client connections alive. This boolean property, when true will make the server try to keep client connections alive, when possible.

Client connections are candidate to be kept alive iff:

- The client has generated the appropriate headers,
- The server is configured to keep connections alive,
- The content length (if any) of the reply body is known,
- The target entity hasn't prohibited the use of keep-alive.

This property defaults to true.

### w3c.jigsaw.client.priority

This properties indicate the priority for client threads. Each client object is repsonsible for running a connection from its starting point (right after the accept) to its ending point (right before the connection is closed). For this duration, the client objects runs in its own thread of control, whose pririty can be indicated by this property.

This property defaults to 5 and shouldn't be changed, unless you know what you are doing.

### w3c.jigsaw.client.bufsize

The size (in bytes) of the buffer to use to send back data to clients. This can improve/decrease the performance of your server; it should be at least big enough to hold small HTML documents (i.e., at least 4kb).

This property defaults to 8192.

### w3c.jigsaw.client.debug

When set to true this property will make client objects emit some traces to the trace log while processing the request. This is usefull for debugging server-side entities.

This property defaults to false.

### w3c.jigsaw.client.keep-alive.timeout

How long should the client remain active while the connection is idle? This property gives, in milliseconds, the amount of time that the server will wait for an incomming request on connections. Once this duration has expired, the server will close the connection, in order to keep the number of TCP resources of the server small.

This property defaults to 10000.

### w3c.jigsaw.client.request.timeout

What is the maximum duration of a request in the server? Once a request is received and parsed, and before it gets processed, the server starts a request timer. When this timer expires, the request is aborted. This property gives the number of milliseconds allowed for processing any request.

This property defaults to 1200000 (or 20 minutes).

### w3c.jigsaw.client.max

The server maintains a `ClientPool` object, which is responsible for providing a free client to handle an incoming connection. This object acts as a kind of factory for clients. It can implement any stratgey. The current implementation of the client pool maintains two water-marks: the maximum number of allowed clients is the number of clients that can run simultaneously. It can be set through this property.

This property defaults to 100.

### w3c.jigsaw.client.min

As said above, the ClientPool keep a certain number of client threads running (and idle), to be prepared for next connections. This property indicates the number of idle client objects to keep alive.

This property defaults to 50.

## Shuffler properties

The shuffler is an external process to be used to send data back to the clients. It is an optional package, and is available only for Solaris. If you are not running Jigsaw on solaris, you should skip this section, and keep the listed properties undefined. The shuffler uses the following properties:

- w3c.jigsaw.shuffler
- w3c.jigsaw.shuffler.path

### w3c.jigsaw.shuffler

The path of the shuffler process. This property has no defaults: if undefined, the external shuffler won't be used. If set, this property should give the full path of the shuffler daemon (see your distribution, in `src/lib`).

### w3c.jigsaw.shuffler.path

The UNIX directory in which to store socket path, to use for communicating with the shuffler. The given directory should exist, if you want the shuffler to run (it will not create it).

This property defaults to /tmp/shuffler.

##

Logging properties

Jigsaw logging is implemented in a very flexible way: you can just define your own logger class and define it to log whatever information you want to. Logging customization is based on the following properties:

- w3c.jigsaw.logger
- w3c.jigsaw.logger.logname
- w3c.jigsaw.logger.errlogname
- w3c.jigsaw.logger.tracelogname

### w3c.jigsaw.logger

This property gives the name of the logger class to use. The logger class can be any class that implements the logger interface. Right now, the only implemented logger is the CommonLogger. If undefined, Jigsaw will not log any requests, and emit a warning at startup time.

This property has no defaults.

### w3c.jigsaw.logger.logname

This property should give the name of the log file to which the logging record will be emited. Note that this property is a property of the CommonLogger (and any of its subclasses), rather than a property of the logging system as a whole.

If not defined, this property will default to <w3c.jigsaw.root>/logs/log

### w3c.jigsaw.logger.errlogname

This property should give the name of the error log file. The error log file is used when some abnormal situation is encoutered inside the server. Abnormal, here, means a situation that the server can't cope with (i.e., implementation bugs), rather than just HTTP errors (which are logged in the above log file).

This file is also used by the server to trace important configuration actions.

If not defined, this property defaults to <w3c.jigsaw.root>/logs/errlog

### w3c.jigsaw.logger.tracelogname

This property should provide the name of the trace log. The trace log is used to output debugging information when the server is turned into debug mode. To turn the server into debug mode, two properties have to be turned to true (depending on what part of the server you want to debug):

w3c.jigsaw.trace
  Make the core server emit traces.
w3c.jigsaw.client.debug
  Make every clients emit traces.

This property defaults to <w3c.jigsaw.root>/logs/tracelog

Anselm Baird-Smith
$Id: properties.html,v 1.2 1996/06/24 01:54:49 anto Exp $