Installation

Uncompress the file in a directory on your local machine, let's call it
installdir. You should now have the following directory structure:

installdir/bin --
contains a Win32 version of an ECC (elliptic curve algorithm) reference
implementation (eccw3c.dll)installdir/classes --
contains ZIP file(s) with all of the Java classes.installdir/demo --
contains sample PICS and DSig label files.installdir/javadocs --
contains the javadocs for the library.installdir/src --
contains all of the source files for the libraryinstalldir/COPYRIGHT.html --
contains copyright information on this reference code.installdir/dsigapi.html --
contains an overview of the DSig implementation and API.installdir/History --
contains thre revision history of the DSig portion of the code.installdir/Readme --
contains a information relevant to running the DSig portion of the code.

Add the following three zip files to your Java CLASSPATH:installdir/classes/dsig.zip;installdir/classes/jsafe_rsa.zip;installdir/jce1_1/lib/jce.zip;

If you have a Win32 machine, and would like to use ECDSS (Elliptic Curve
Algorithm with Digital Signature Standard), you need to add the following
directory to your PATH variable: installdir\bin

You should now be ready to go!

DSigDemo

The class w3c.pics.parser.DSigDemo is a test program that will demonstrate
the use of the DSig reference code. To invoke it, type: java
w3c.pics.parser.DSigDemoinstalldir/demo/labelfile. Where
labelfile is the name of a file containing a PICS label.

The PICSParser

The PICSParser class provides a command-line interface to all of the features
of the w3c.pics.parser package. To run the PICSParser type:

java w3c.pics.parser.PICSParser

The exact command will differ slightly if you are using a Java VM other than
the JDK.

There is one command-line flag that PICSParser recognizes: -debug
. If it is present, then extra debugging information will be printed out when
using the process command.

The PICSParser offers the following commands:

help : displays this help information

testsuite URLfileprofile: Checks each URL in URLfile against profile, requesting labels from a label bureau as
specified in profile. Currently not checking for embedded labels
even if profile specifies that.

filter htmlfileprofile: filters the HTML in
htmlfile according to the labels in its header and the profile in
profile

parse service filename: parses the service contained in the file
filename

process labelfileprofile: Runs the label(s) from
labelfile against the profile in profile

quit : quits the program

After choosing any of the parse commands, the program, if it successfully
parses the input, will call .toString() on the resulting Java object, and
print the results out to the console.

The process command will indicate which labels passed the profile and
which did not. If the -debug flag was used to run the program, it will also
display a list of the policy clause types, in order, to show which clause
caused the label to be passed/blocked.

Running a parser stand-alone

Each of the three parsers can also be run directly from the command-line:

java w3c.pics.parser.parserClassfilename

where parserClass is one of the three parser class names:
LabelParser, ServiceParser, or ProfileParser.

Custom use of parsers

The main() methods of the parsers, as well as the commands implemented in
PICSParser, simply call a parser, get back a Java object, and call toString()
on it. Developers using the library are encouraged to make use of the parsers
and incorporate the standard Java objects for labels, services and profiles,
into their own applications. The
API for the objects
enumerates the useful methods of each class.

It should be known that partial parsing of input can be accomplished with these
parsers. The top-level production of the grammar for a particular parser need
not be the method called to begin parsing. Parsing can start from any
production in the parser. (For more on grammar files, see below). For
example, you can call a method in the LabelParser so that you can just
input an extension clause, and parse just that information.

Modifying the grammars

The three primary grammar files are ProfileParser.jjt, ServiceParser.jj and
LabelParser.jj. The DSigParser.jj file is used by the DSig portion of the
library to parse DSig extensions. Anyone interested in modifying these
grammars will need
javacc, and is STRONGLY encouraged to read the
javacc documentation before
changing anything. Note that ProfileParser.jjt is a JJTree grammar file,
which must be run through jjtree before javacc.

Each production in the grammar corresponds to a method in the javacc
generated .java file. Thus, if you want to start parsing from a specific
production in a grammar, call the parser with that method.

JJDoc is a tool that is included with JavaCC. It produces HTML files for
JavaCC grammar files: