PICS/DSig Standard Library
PICS/DSig Standard Library in Java -- Documentation
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:
- Download the source code (US Version
/ Non-US Version)
- Uncompress the file in a directory on your local machine, let's call it
installdir. You should now have the following directory structure:
contains a Win32 version of an ECC (elliptic curve algorithm) reference
contains ZIP file(s) with all of the Java classes.
contains sample PICS and DSig label files.
contains the javadocs for the library.
contains all of the source files for the library
contains copyright information on this reference code.
contains an overview of the DSig implementation and API.
contains thre revision history of the DSig portion of the code.
contains a information relevant to running the DSig portion of the code.
- Add the following three zip files to your Java CLASSPATH:
- 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!
w3c.pics.parser.DSigDemo is a test program that will demonstrate
the use of the DSig reference code. To invoke it, type:
w3c.pics.parser.DSigDemo installdir/demo/labelfile. Where
labelfile is the name of a file containing a PICS label.
The PICSParser class provides a command-line interface to all of the features
of the w3c.pics.parser package. To run the PICSParser type:
The exact command will differ slightly if you are using a Java VM other than
There is one command-line flag that PICSParser recognizes:
. 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.
- help : displays this help information
- testsuite URLfile profile: 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 htmlfile profile: filters the HTML in
htmlfile according to the labels in its header and the profile in
- find labels filename: parses the HTML file filename,
looking for labels in its header.
- parse dsiglabel filename: parses the label(s) contained in the
file filename and outputs in Dsig-ready canonicalized form
- parse label filename: parses the label(s) contained in the
- parse profile filename: parses the profile contained in the file
- parse service filename: parses the service contained in the file
- process labelfile profile: Runs the label(s) from
labelfile against the profile in profile
- quit : quits the program
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.
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.
firstname.lastname@example.org 15 May 98