W3C PICS

PICS/DSig Standard Library


PICS/DSig Standard Library in Java -- Documentation

Installation

NOTE: The PICS/DSig Standard Library requires a Java 1.1 Virtual Machine, such as Sun's JDK 1.1.x.

To install the PICS/DSig Standard Library:

  1. Download the source code (US Version / Non-US Version)

  2. 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 library
    installdir/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.

  3. 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;

  4. 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

  5. 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.DSigDemo installdir/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:

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.parserClass filename

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:

Note: These grammar files were compiled with JavaCC version 0.7. They will not work properly with version of JavaCC before 0.7.

Reporting Bugs

Be sure to read the Known Bugs / What's New Page. It will be updated as bugs are discovered and fixed and as new features are added to the library.

dshapiro@w3.org
15 May 98