## org.eclipse.jetty.policy.loader
Class PolicyFileScanner

    java.lang.Object
      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-2010 Mort Bay Consulting. All Rights Reserved.