This page describes how to setup the Jigsaw server for PICS support. For general administration issues, you should read the Administration guide. Jigsaw PICS support can be handled in two ways:
Both approaches deal with the following objects:
There's two implementations available in jigsaw for PICS, the sample implementation and the database implementation.
We describe here the setting for the sample implementation, which is made of the SampleLabelBureau, SampleLabelService and SampleLabel. These objects use a simple database, whose implementation relies on the underlying file system:. To each sample label bureau, is associated a home directory. To look for labels on a given URL U rated by service whose identifier is SURL it parses it into the following components:
Out of these components, it builds a file name:
If the port equals 80 (the normal http port), it is omited. The label bureau directory is a parameter of the sample label bureau implementation. As an example, if the label bureau directory is www/labels and we are looking for generic labels for http://www.w3.org/pub/WWW by the service http://www.rating.com, the sample implementation will check for a file named www/labels//http/www.rating.com/http/www.w3.org/pub/WWW.gen. If such a file exists, it should contain a label representation, in a format decribed below.
The rest of this document answers the following questions:
Jigsaw uses the PICSFilter to implement this part of the PICS specification (if you are not familiar with filters, you may want to have a look at the global Administration guide.). This filter will process each outgoing reply by adding to it the appropriate PICS headers. It takes one parameter, named bureau which will be passed to the label bureau factory when the server needs to access the label bureau. In the two implementations of label bureau, this should be a string giving the absolute path of the label bureau database.
Upon each request crossing the labeled directory, the PICS filter will examine both the request, and the original reply (as built by the target resource). If PICS labels are requested, it will query the label bureau (whose home directory is given through the bureau parameter), and add to the reply the additional PICS headers.
Jigsaw can also be used as a label bureau. This is fearly easy to setup: the label bureau itself is implemented as a specific resource, which will decode requests, make the appropriate queries to its bureau implementation, and send back the automatically generated PICS document.
To register a label bureau resource within your server space, follow the normal configuration steps (see the Administration guide for more informations).
Editing labels, right now, is done by editing the label files, as described in the first section of this document. These files have a very simple format:
lines = line lines | <empty> line = <attribute> '=' <value> attribute = <Any char except '='> value = <Any char except EOL>
The following attributes are mandatory:
The following file, is a valid label file for the http://www.w3.org/pub/WWW/Overview.html provided the label bureau home directory is /usr/www/labels:
# /usr/www/labels/http/www24.w3.org/8888/http/www.w3.org/pub/WWW/Overview.html ratings=(age 12) by="abaird@w3.org" generic=false
This section describes a full example of PICS setting. We will use the following terms:
When ever you encounter these italized tokens, you should replace them with your own value.
We will first set-up a label bureau. For this we need to assign a directory to it, let's use root/labels for this purpose. We create this directory, empty:
mkdir root/labels
Than we need to define some service. Let's say we want to create the www.rating.com service, which will use the http protocol. Its identifier URL will be http://www.rating.com, so we need to create the following directories:
mkdir -p root/labels/http/www.rating.com
Now, lets make a label for http://www.w3.org/PICS by this service. This label will be generic (so it will apply to anything below this url), and will be locate in the following file:
root/labels/http/www.rating.com/http/www.w3.org/pub/WWW/PICS.gen
What should we put in this file ? This depends on the category the rating service defines. For the sake of simplicity, lets say that it defines only one category, namely the minimal age the surfer should be. Note that we need not be concerned by the service description here, as this is the role of the maintainer of this service (ie www.rating.com), here we just want to distribute labels for this service. Given all this, we can write our label file PICS.gen:
mkdir -p root/labels/http/www.rating.com/http/www.w3.org/pub/WWW/ cd root/labels/http/www.rating.com/http/www.w3.org/pub/WWW/ cat > PICS.gen at=1995.2.29T14:10+0300 by=abaird@w3.org for=http://www.w3.org/pub/WWW/PICS generic=true ratings=(age 10) ^D
The set of attributes for this label can include any of the attributes defined by the PICS labels specification. Our ratings attribute here, state that the reader should be at least 10 to be able the PICS specification (this will prevent kids from understanding PICS, so that they can't hack it ;-). All these attributes will be send as is (in the appropriate syntax, though) to any clients requesting the http://www.w3.org/pub/WWW/PICS generic label.
Here, we focus on providing labels (by our www.rating.com service) for part of our exported space. Let's say we export a labeled-space in our top directory root/WWW, that contains stuff to be labeled. To handle PICS in this space, we will need to set it up through the PICS filter. Use the directory resource editor to hook this filter on it (the editor is available as /Admin/Editor/labeled-space).
Our labeled-space is all set, we now need to install some documents in it, and label them. Let's say we have a hello.html document in this directory that we want to label with a specific label. The label will conform to our fake www.rating.com service, we want the reader to be at least 1 year:
mkdir -p root/labels/http/www.rating.com/http/host/port/labeled-space cd root/labels/http/www.rating.com/http/host/port/labeled-space cat > hello.html generic=false for=http://host:port/labeled-space/hello.html by=abaird@w3.org ratings=(age 1)
We can now ask for the labeled document, and we will get the appropriate labels.
Now let's turn Jigsaw into a label bureau. You will first need to define the label bureau database, as stated above. The label bureau is implemented as a special resource whose class is w3c.jigsaw.pics.LabelBureauResource .The first thing you will need to do is to hook up an instance of this resource in the appropriate place of your exported space. You can do this by poping the appropriate directory resource editor, for example by pointing your browser to /Admin/Editor. Select the AddResource link, and give the label's bureau name (e.g. ratings), and its class (which will always be w3c.jigsaw.pics.LabelBureauResource). Then go and edit its bureau parameter, you're all set.
Now, the http://host:port/ratings will handle the incoming queries for label.
We describe here the setting for the implementation which use a fancy database to store labels. Instead of SampleLabelBureau and SampleLabelService, this implementation use DataBaseBureau and DataBaseService.
Configuring a DataBaseBureau is the same than configuring a SampleLabelBureau. The only difference is that the DataBaseBureau directory must have ".db" as extension. This directory must contains two files named dbs.props and dbb.props witch gives informations about the databases used.Take a look at these files : dbs.props & dbb.props. Here is a description of the two databases :
| bureau | service |
| (char) | (char) |
| service | label | gen |
| (char) | (char) | (int 0 or 1) |
The label format in the database is the same than the label file format of the sample implementation.
The rest of this document answers the following questions:
Editing labels is done by sending a PUT request to the label bureau (in a HTML form or an Applet). Here is the detailed specification of the PUT request :
service=service url&
url=the url to label&
label=the label in the jigsaw alternative format&
generic=[true | false]&
overwrite=[true | false]&
createservice=[true | false]
('&' is a separator)
DETAILS :
The reply can have the followings http codes values :
lines = line lines | <empty> line = <attribute> '=' <value> attribute = <Any char except '='> value = <Any char except EOL>
The following attributes are mandatory:
For all labels:
ratings : The actual ratings for the labeled document
For generic labels:
Examples :
The following example is a valid generic label for http://www.example.com
on="1997.03.01T00-7000" for="http://www.example.com" by="bmahe@sophia.inria.fr" generic=true ratings=(s 1 v 0 l 2)
The next one is a non generic label for http://www.example.com
on="1997.03.01T00-7000" by="bmahe@sophia.inria.fr" ratings=(s 1 v 0 l 2)
NOTE : Jigsaw use this format, and not the regular one, because when this part of jigsaw was implemented, there was no Pics parser available and this format is easy to parse. In the future, we will use the Pics Parser.
A PUT request sample :
The following example is a complete PUT request on the label bureau http://www43.inria.fr:8007/DataBaseBureau for the url http://www.movies.com with the rating service http://www.rsac.org. The label added is a non generic one.
PUT http://www43.inria.fr:8007/DataBaseBureau HTTP1.1
service=http://www.rsac.org&url=http://www.movies.com&label=on="1997.03.01T00-7000"
by="bmahe@sophia.inria.fr"
ratings=(s 1 v 0 l
2)&generic=false&overwrite=true&createservice=false
This section describes a full example of PICS setting. We will use the following terms:
When ever you encounter this italized token, you should replace it with your own value.
We will setup a label bureau. For this we need to assign a directory to it, let's use root/labels.db for this purpose. We create this directory, empty:
mkdir root/labels.db
Now we need to create the two databases and we have to install JDBC drivers to access it.
Then we need to create the files dbb.props and dbs.props in this directory.
Then we need to define some service. Let's say we want to create the www.rating.com service, which will use the http protocol. Its identifier URL will be http://www.rating.com, so we need to send the following request to the label bureau:
HTTP1.1 /PUT service=http://www.rating.com&create=true
Now, lets make a label for http://www.w3.org/PICS by this service. This label will be generic (so it will apply to anything below this url)
HTTP1.1 /PUT
service=http://www.rating.com&url=http://www.w3.org/PICS&label=on="1995.2.29T14:10+0300"
by="abaird@w3.org"
for="http://www.w3.org/PICS"
generic=true
rating=(age 10)&generic=true
The ends of lines are importants, because now, the database implementation use the same parser than the sample implementation.
Now let's turn Jigsaw into a label bureau. You will first need to define the label bureau database, as stated above. The label bureau is implemented as a special resource whose class is w3c.jigsaw.pics.DataBaseBureauResource.The first thing you will need to do is to hook up an instance of this resource in the appropriate place of your exported space. You can do this by poping the appropriate directory resource editor, for example by pointing your browser to /Admin/Editor. Select the AddResource link, and give the label's bureau name (e.g. ratings), and its class (which will always be w3c.jigsaw.pics.DataBaseBureauResource). Then go and edit its bureau parameter, you're all set.
Now, the http://host:port/ratings will handle the incoming queries for label.
Jigsaw Team
$Id: pics.html,v 1.17 1998/05/27 09:32:19 yves Exp $