org.eclipse.jetty.policy.loader

Class PolicyFileScanner

java.lang.Object

org.eclipse.jetty.policy.loader.PolicyFileScanner

public class PolicyFileScanner
extends java.lang.Object

This is a basic high-level tokenizer of policy files. It takes in a stream, analyzes data read from it and returns a set of structured tokens.
This implementation recognizes text files, consisting of clauses with the following syntax:

 
     keystore "some_keystore_url", "keystore_type";
 
 

 
     grant [SignedBy "signer_names"] [, CodeBase "URL"]
      [, Principal [principal_class_name] "principal_name"]
      [, Principal [principal_class_name] "principal_name"] ... {
      permission permission_class_name [ "target_name" ] [, "action"] 
      [, SignedBy "signer_names"];
      permission ...
      };
 
 

For semantical details of this format, see org.apache.harmony.security.DefaultPolicy javadoc.
Keywords are case-insensitive in contrast to quoted string literals. Comma-separation rule is quite forgiving, most commas may be just omitted. Whitespaces, line- and block comments are ignored. Symbol-level tokenization is delegated to java.io.StreamTokenizer.

This implementation is effectively thread-safe, as it has no field references to data being processed (that is, passes all the data as method parameters). This implementation is a bit more strict in enforcing format then the default policy scanner as implemented in the sun jdk.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PolicyFileScanner.InvalidFormatException Specific exception class to signal policy file syntax error.

Constructor Summary

Constructors

Constructor and Description
PolicyFileScanner()

Method Summary

Methods

Modifier and Type	Method and Description
protected java.lang.String	composeStatus(java.io.StreamTokenizer st) Formats a detailed description of tokenizer status: current token, current line number, etc.
protected java.io.StreamTokenizer	configure(java.io.StreamTokenizer st) Configures passed tokenizer accordingly to supported syntax.
protected void	handleUnexpectedToken(java.io.StreamTokenizer st) Throws InvalidFormatException with error status: which token is unexpected on which line.
protected void	handleUnexpectedToken(java.io.StreamTokenizer st, java.lang.String message) Throws InvalidFormatException with detailed diagnostics.
protected GrantEntry	readGrantNode(java.io.StreamTokenizer st) Tries to read grant clause.
protected KeystoreEntry	readKeystoreNode(java.io.StreamTokenizer st) Tries to read keystore clause fields.
protected java.util.Collection<PermissionEntry>	readPermissionEntries(java.io.StreamTokenizer st) Tries to read a list of permission entries.
protected PrincipalEntry	readPrincipalNode(java.io.StreamTokenizer st) Tries to read Principal Node fields.
void	scanStream(java.io.Reader r, java.util.Collection<GrantEntry> grantEntries, java.util.List<KeystoreEntry> keystoreEntries) Performs the main parsing loop.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PolicyFileScanner

public PolicyFileScanner()

Method Detail

configure

protected java.io.StreamTokenizer configure(java.io.StreamTokenizer st)

Configures passed tokenizer accordingly to supported syntax.

scanStream

public void scanStream(java.io.Reader r,
              java.util.Collection<GrantEntry> grantEntries,
              java.util.List<KeystoreEntry> keystoreEntries)
                throws java.io.IOException,
                       PolicyFileScanner.InvalidFormatException

Performs the main parsing loop. Starts with creating and configuring a StreamTokenizer instance; then tries to recognize keystore or grant keyword. When found, invokes read method corresponding to the clause and collects result to the passed collection.

Parameters:

r - policy stream reader

grantEntries - a collection to accumulate parsed GrantEntries

keystoreEntries - a collection to accumulate parsed KeystoreEntries

Throws:

java.io.IOException - if stream reading failed

PolicyFileScanner.InvalidFormatException - if unexpected or unknown token encountered

readKeystoreNode

protected KeystoreEntry readKeystoreNode(java.io.StreamTokenizer st)
                                  throws java.io.IOException,
                                         PolicyFileScanner.InvalidFormatException

Tries to read keystore clause fields. The expected syntax is

 
     "some_keystore_url"[, "keystore_type"];
 
 

Returns:

successfully parsed KeystoreNode

Throws:

java.io.IOException - if stream reading failed

PolicyFileScanner.InvalidFormatException - if unexpected or unknown token encountered

readGrantNode

protected GrantEntry readGrantNode(java.io.StreamTokenizer st)
                            throws java.io.IOException,
                                   PolicyFileScanner.InvalidFormatException

Tries to read grant clause.
First, it reads codebase , signedby , principal entries till the '{' (opening curly brace) symbol. Then it calls readPermissionEntries() method to read the permissions of this clause.
Principal entries (if any) are read by invoking readPrincipalNode() method, obtained PrincipalEntries are accumulated.
The expected syntax is

 
     [ [codebase "url"] | [signedby "name1,...,nameN"] | 
          principal ...] ]* { ... }
 
 

Returns:

successfully parsed GrantNode

Throws:

java.io.IOException - if stream reading failed

PolicyFileScanner.InvalidFormatException - if unexpected or unknown token encountered

readPrincipalNode

protected PrincipalEntry readPrincipalNode(java.io.StreamTokenizer st)
                                    throws java.io.IOException,
                                           PolicyFileScanner.InvalidFormatException

Tries to read Principal Node fields. The expected syntax is

 
     [ principal_class_name ] "principal_name"
 
 

Both class and name may be wildcards, wildcard names should not surrounded by quotes.

Returns:

successfully parsed PrincipalNode

Throws:

java.io.IOException - if stream reading failed

PolicyFileScanner.InvalidFormatException - if unexpected or unknown token encountered

readPermissionEntries

protected java.util.Collection<PermissionEntry> readPermissionEntries(java.io.StreamTokenizer st)
                                                               throws java.io.IOException,
                                                                      PolicyFileScanner.InvalidFormatException

Tries to read a list of permission entries. The expected syntax is

 
     permission permission_class_name
          [ "target_name" ] [, "action_list"]
          [, signedby "name1,name2,..."];
 
 

List is terminated by '}' (closing curly brace) symbol.

Returns:

collection of successfully parsed PermissionEntries

Throws:

java.io.IOException - if stream reading failed

PolicyFileScanner.InvalidFormatException - if unexpected or unknown token encountered

composeStatus

protected java.lang.String composeStatus(java.io.StreamTokenizer st)

Formats a detailed description of tokenizer status: current token, current line number, etc.

handleUnexpectedToken

protected final void handleUnexpectedToken(java.io.StreamTokenizer st,
                         java.lang.String message)
                                    throws PolicyFileScanner.InvalidFormatException

Throws InvalidFormatException with detailed diagnostics.

Parameters:

st - a tokenizer holding the erroneous token

message - a user-friendly comment, probably explaining expected syntax. Should not be null- use the overloaded single-parameter method instead.

Throws:

PolicyFileScanner.InvalidFormatException

handleUnexpectedToken

protected final void handleUnexpectedToken(java.io.StreamTokenizer st)
                                    throws PolicyFileScanner.InvalidFormatException

Throws InvalidFormatException with error status: which token is unexpected on which line.

Parameters:

st - a tokenizer holding the erroneous token

Throws:

PolicyFileScanner.InvalidFormatException