org.eclipse.jetty.policy.loader
Class PolicyFileScanner

java.lang.Object
  extended by org.eclipse.jetty.policy.loader.PolicyFileScanner

public class PolicyFileScanner
extends 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
static class PolicyFileScanner.InvalidFormatException
          Specific exception class to signal policy file syntax error.
 
Constructor Summary
PolicyFileScanner()
           
 
Method Summary
protected  String composeStatus(StreamTokenizer st)
          Formats a detailed description of tokenizer status: current token, current line number, etc.
protected  StreamTokenizer configure(StreamTokenizer st)
          Configures passed tokenizer accordingly to supported syntax.
protected  void handleUnexpectedToken(StreamTokenizer st)
          Throws InvalidFormatException with error status: which token is unexpected on which line.
protected  void handleUnexpectedToken(StreamTokenizer st, String message)
          Throws InvalidFormatException with detailed diagnostics.
protected  GrantEntry readGrantNode(StreamTokenizer st)
          Tries to read grant clause.
protected  KeystoreEntry readKeystoreNode(StreamTokenizer st)
          Tries to read keystore clause fields.
protected  Collection<PermissionEntry> readPermissionEntries(StreamTokenizer st)
          Tries to read a list of permission entries.
protected  PrincipalEntry readPrincipalNode(StreamTokenizer st)
          Tries to read Principal Node fields.
 void scanStream(Reader r, Collection<GrantEntry> grantEntries, 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 StreamTokenizer configure(StreamTokenizer st)
Configures passed tokenizer accordingly to supported syntax.


scanStream

public void scanStream(Reader r,
                       Collection<GrantEntry> grantEntries,
                       List<KeystoreEntry> keystoreEntries)
                throws 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:
IOException - if stream reading failed
PolicyFileScanner.InvalidFormatException - if unexpected or unknown token encountered

readKeystoreNode

protected KeystoreEntry readKeystoreNode(StreamTokenizer st)
                                  throws IOException,
                                         PolicyFileScanner.InvalidFormatException
Tries to read keystore clause fields. The expected syntax is
 
     "some_keystore_url"[, "keystore_type"];
 
 

Returns:
successfully parsed KeystoreNode
Throws:
IOException - if stream reading failed
PolicyFileScanner.InvalidFormatException - if unexpected or unknown token encountered

readGrantNode

protected GrantEntry readGrantNode(StreamTokenizer st)
                            throws 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:
IOException - if stream reading failed
PolicyFileScanner.InvalidFormatException - if unexpected or unknown token encountered

readPrincipalNode

protected PrincipalEntry readPrincipalNode(StreamTokenizer st)
                                    throws 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:
IOException - if stream reading failed
PolicyFileScanner.InvalidFormatException - if unexpected or unknown token encountered

readPermissionEntries

protected Collection<PermissionEntry> readPermissionEntries(StreamTokenizer st)
                                                     throws 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:
IOException - if stream reading failed
PolicyFileScanner.InvalidFormatException - if unexpected or unknown token encountered

composeStatus

protected String composeStatus(StreamTokenizer st)
Formats a detailed description of tokenizer status: current token, current line number, etc.


handleUnexpectedToken

protected final void handleUnexpectedToken(StreamTokenizer st,
                                           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(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


Copyright © 1995-2011 Mort Bay Consulting. All Rights Reserved.