Pics setup
This page describes how to setup the Jigsaw server for PICS support.
-
Using the server as a label bureau
-
Using the server to serve labels with document
Sample implementation configuration
We describe here the setting for the sample implementation. 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:
-
The service host name (shost),
-
The service port number (sport),
-
The optional service path (spath),
-
The target URL protocol (uproto)
-
The target URL host name (uhost),
-
The target URL port number (uport),
-
The target URL path (upath).
Out of these components, it builds a file name:
-
For generic labels
-
<bureau-home-directory>/<shost>/<sport>/<spath>/<uproto>/<uhost>/<uport>/<upath>.gen
-
For specific labels
-
<bureau-home-directory>/<shost>/<sport>/<spath>/<uproto>/<uhost>/<uport>/<upath>
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:
Serving labels with documents
Jigsaw uses the PICSFilter
to implement this part of the PICS specification . 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
implementation 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.
Label bureau
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 Resource
Configuration guide for more informations).
Editing labels
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:
-
For all labels:
-
generic
-
Wether the label is generic or not
-
ratings
-
The actual ratings for the labeled document
-
For generic labels:
-
for
-
The full URL of the labeled document
Here is the list of all attributes:
by = quotedname
generic = boolean
for = quotedURL
on = quoted-ISO-date
signature-RSA-MD5 = "base64-string"
until = quoted-ISO-date
exp = quoted-ISO-date
at = quoted-ISO-date
MIC-md5 = "base64-string"
md5 = "base64-string"
comment = quotedname
complete-label = quotedURL
full = quotedURL
extension = '(' mand/opt quotedURL data* ')'
mand/opt :: 'optional' | 'mandatory'
data :: quoted-ISO-date | quotedURL | number | quotedname | '(' data* ')'
ratings = pics-ratings
Read this for more informations about Pics labels.
Sample setting
This section describes a full example of PICS setting. We will use the
following terms:
-
root
-
The server root directory (not to be confused with its space directory,
which will usually be root/WWW).
-
host
-
The host the server is running on, as defined by your command line, or
by the org.w3c.jigsaw.host
property
-
port
-
The port the server is listening to, as defined either by your command
line, or by the org.w3c.jigsaw.port
property.
When ever you encounter these italized tokens, you should replace them
with your own value.
Setting up a label bureau database
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:
create the directory 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:
create the directory 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:
create the directory 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/
And write the following in PICS.gen
on="1995.2.29T14:10+0300"
by="bmahe@w3.org"
for="http://www.w3.org/pub/WWW/PICS"
generic=true
ratings=(age 10)
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.
Setting up a labeled space (serving labels with documents)
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 Jigadmin to hook this filter
on 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:
create root/labels/http/www.rating.com/http/host/port/labeled-space
cd root/labels/http/www.rating.com/http/host/port/labeled-space
And write the following in hello.html
generic=false
for="http://host:port/labeled-space/hello.html"
by="bmahe@w3.org"
ratings=(age 1)
We can now ask for the labeled document, and we will get the appropriate
labels.
Serving 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 org.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 with JigAdmin
by adding a LabelBureau call it LabelBureau (for example). Then
go and edit its bureau parameter, you're all set.
-
bureau: The absolute path of the database (described here)
-
services: List of the services available in this bureau. (This should
not be necessary, but some browsers doesn't send the service url in their
PICS requests)
Now, the http://host:port/LabelBureau will handle
the incoming queries for label.
Jigsaw Team
$Id: pics.html,v 1.15 1998/08/05 14:24:27 benoit Exp $