org.apache.river.api.security

Class DefaultPolicyScanner

java.lang.Object

org.apache.river.api.security.DefaultPolicyScanner

class DefaultPolicyScanner
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 the default policy description.
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).

See Also:

DefaultPolicyParser

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	DefaultPolicyScanner.GrantEntry Compound token representing grant clause.
static class	DefaultPolicyScanner.InvalidFormatException Specific exception class to signal policy file syntax error.
(package private) static class	DefaultPolicyScanner.KeystoreEntry Compound token representing keystore clause.
(package private) static class	DefaultPolicyScanner.PermissionEntry Compound token representing permission entry of a grant clause.
(package private) static class	DefaultPolicyScanner.PrincipalEntry Compound token representing principal entry of a grant clause.

Constructor Summary

Constructors

Constructor and Description
DefaultPolicyScanner()

Method Summary

Modifier and Type	Method and Description
(package private) String	composeStatus(StreamTokenizer st) Formats a detailed description of tokenizer status: current token, current line number, etc.
(package private) StreamTokenizer	configure(StreamTokenizer st) Configures passed tokenizer accordingly to supported syntax.
(package private) void	handleUnexpectedToken(StreamTokenizer st) Throws InvalidFormatException with error status: which token is unexpected on which line.
(package private) void	handleUnexpectedToken(StreamTokenizer st, String message) Throws InvalidFormatException with detailed diagnostics.
(package private) DefaultPolicyScanner.GrantEntry	readGrantEntry(StreamTokenizer st) Tries to read grant clause.
(package private) DefaultPolicyScanner.KeystoreEntry	readKeystoreEntry(StreamTokenizer st) Tries to read keystore clause fields.
(package private) Collection<DefaultPolicyScanner.PermissionEntry>	readPermissionEntries(StreamTokenizer st) Tries to read a list of permission entries.
(package private) DefaultPolicyScanner.PrincipalEntry	readPrincipalEntry(StreamTokenizer st) Tries to read Principal entry fields.
(package private) void	scanStream(Reader r, Collection<DefaultPolicyScanner.GrantEntry> grantEntries, List<DefaultPolicyScanner.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

DefaultPolicyScanner

DefaultPolicyScanner()

Method Detail

configure

StreamTokenizer configure(StreamTokenizer st)

Configures passed tokenizer accordingly to supported syntax.

scanStream

void scanStream(Reader r,
                Collection<DefaultPolicyScanner.GrantEntry> grantEntries,
                List<DefaultPolicyScanner.KeystoreEntry> keystoreEntries)
         throws IOException,
                DefaultPolicyScanner.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

DefaultPolicyScanner.InvalidFormatException - if unexpected or unknown token encountered

readKeystoreEntry

DefaultPolicyScanner.KeystoreEntry readKeystoreEntry(StreamTokenizer st)
                                              throws IOException,
                                                     DefaultPolicyScanner.InvalidFormatException

Tries to read keystore clause fields. The expected syntax is

 
     "some_keystore_url"[, "keystore_type"];
  
 

Returns:

successfully parsed KeystoreEntry

Throws:

IOException - if stream reading failed

DefaultPolicyScanner.InvalidFormatException - if unexpected or unknown token encountered

readGrantEntry

DefaultPolicyScanner.GrantEntry readGrantEntry(StreamTokenizer st)
                                        throws IOException,
                                               DefaultPolicyScanner.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 readPrincipalEntry() method, obtained PrincipalEntries are accumulated.
The expected syntax is

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

Returns:

successfully parsed GrantEntry

Throws:

IOException - if stream reading failed

DefaultPolicyScanner.InvalidFormatException - if unexpected or unknown token encountered

readPrincipalEntry

DefaultPolicyScanner.PrincipalEntry readPrincipalEntry(StreamTokenizer st)
                                                throws IOException,
                                                       DefaultPolicyScanner.InvalidFormatException

Tries to read Principal entry 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 PrincipalEntry

Throws:

IOException - if stream reading failed

DefaultPolicyScanner.InvalidFormatException - if unexpected or unknown token encountered

readPermissionEntries

Collection<DefaultPolicyScanner.PermissionEntry> readPermissionEntries(StreamTokenizer st)
                                                                throws IOException,
                                                                       DefaultPolicyScanner.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

DefaultPolicyScanner.InvalidFormatException - if unexpected or unknown token encountered

composeStatus

String composeStatus(StreamTokenizer st)

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

handleUnexpectedToken

final void handleUnexpectedToken(StreamTokenizer st,
                                 String message)
                          throws DefaultPolicyScanner.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:

DefaultPolicyScanner.InvalidFormatException

handleUnexpectedToken

final void handleUnexpectedToken(StreamTokenizer st)
                          throws DefaultPolicyScanner.InvalidFormatException

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

Parameters:

st - a tokenizer holding the erroneous token

Throws:

DefaultPolicyScanner.InvalidFormatException