PolicyFileHiveFactory (Hive 7.17.0 API)

java.lang.Object
- org.wicketstuff.security.hive.config.PolicyFileHiveFactory

All Implemented Interfaces:

HiveFactory
```
public class PolicyFileHiveFactory
extends Object
implements HiveFactory
```
A factory to produce Hive's based on policy files. This factory is designed to make a best effort when problems occur. Meaning any malconfiguration in the policy file is logged and then skipped. This factory accepts the following policy format
```
 grant[ principal <principal class> "name"]
 {
 permission <permission class> "name",[ "actions"];
 };
 
```
where [] denotes an optional block, <> denotes a classname.
For brevity aliases are allowed in / for classnames and permission-, principal names. An alias takes the form of ${foo} the alias (the part between {}) must be at least 1 character long and must not contain one of the following 4 characters "${} For example: permission ${ComponentPermission} "myname.${foo}", "render";
Note that:
- names and action must be quoted
- a permission statement must be on a single line and terminated by a ;
- the grant block must be terminated by a ;
- if you don't specify a principal after the grant statement, everybody will be given those permissions automagically
- using double quotes '"' is not allowed, instead use a single quote '''
- aliases may be chained but not nested, so ${foo}${bar} is valid but not ${foo${bar}}
- aliases are not allowed in actions or reserved words (grant, permission, principal)
- aliases are case sensitive
Author:

marrink

Constructor Summary

Constructors
Constructor and Description
`PolicyFileHiveFactory(org.wicketstuff.security.actions.ActionFactory actionFactory)` Constructs a new factory that builds a Hive out of one (1) or more policy files.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`addPolicyFile(URL file)` Adds a new Hive policy file to this factory.
`boolean`	`addReader(Reader input)` Adds a new Hive policy to this factory.
`boolean`	`addStream(InputStream stream)` Adds a new Hive policy to this factory.
`protected String`	`arrayToString(Object[] array)` Generates a comma (,) separated string of all the items in the array
`protected BasicHive`	`constructHive()` Changeable by subclasses to return there own hive subclass.
`Hive`	`createHive()` This method is not thread safe.
`protected org.wicketstuff.security.actions.ActionFactory`	`getActionFactory()` Gets actionFactory.
`String`	`getAlias(String key)` Returns the value of the alias.
`protected int`	`getCurrentLineNr()` The current line being read.
`protected Set<URL>`	`getPolicyFiles()` A readonly view of the policy files added to this factory.
`protected Set<Reader>`	`getReaders()` A readonly view of the readers added to this factory.
`protected Set<InputStream>`	`getStreams()` A readonly view of the streams added to this factory.
`boolean`	`isCloseInputStreams()` Gets closeInputStreams.
`boolean`	`isUsingHiveCache()` Flag indicating if caching for the `Hive` is enabled or disabled.
`protected void`	`notifyFileClose(URL file, int lineNr)` Notifies when a file is closed, either because the end of the file was reached or because an uncaught exception was thrown.
`protected void`	`notifyFileStart(URL file)` Notifies when a new file is about to be read.
`protected void`	`notifyOfPrincipal(int lineNr, Principal principal)` Notifies of a new Principal read in the policy file.
`protected void`	`notifyPermission(int lineNr, Class<? extends Permission> permissionClass, Class<?>[] args)` Notifies when a Permission could not be created because no suitable constructor was found.
`protected void`	`notifyPermission(int lineNr, Principal principal, Permission permission)` Notifies when a permission is added to a principal.
`protected void`	`notifyReaderEnd(Reader input, int lineNr)` Notifies that the `Reader` will be read no further.
`protected void`	`notifyReaderStart(Reader input)` Notifies that a reader is about to be read.
`protected void`	`notifyStreamEnd(InputStream stream, int lineNr)` Notifies that the stream will be read no further.
`protected void`	`notifyStreamStart(InputStream stream)` Notifies that a stream is about to be read.
`protected void`	`read(Reader input, BasicHive hive)` Reads principals and permissions from a `Reader` , found items are added to the hive.
`protected void`	`readInputReader(Reader input, BasicHive hive)` Reads principals and permissions from a `Reader`, found items are added to the hive.
`protected void`	`readInputStream(InputStream stream, BasicHive hive)` Reads principals and permissions from a stream, found items are added to the hive.
`protected void`	`readPolicyFile(URL file, BasicHive hive)` Reads principals and permissions from a file, found items are added to the hive.
`protected void`	`readReader(Reader input, BasicHive hive)` Reads principals and permissions from a `Reader`, found items are added to the hive.
`protected void`	`readStream(InputStream input, BasicHive hive)` Reads principals and permissions from a `InputStream` , found items are added to the hive.
`String`	`setAlias(String key, String value)` Sets the value for an alias, overwrites any existing alias with the same name
`void`	`setCloseInputStreams(boolean closeInputStreams)` Sets closeInputStreams.
`protected void`	`skipEmptyPrincipal(int lineNr, Principal principal)` Notifies when a principal is skipped because there are no permissions attached.
`protected void`	`skipIllegalPermission(int lineNr, Principal principal, Permission permission)` Notifies of permissions located outside the { and }; block statements but after a valid principal was found.
`protected void`	`skipIllegalPrincipal(int lineNr, Principal principal, Set<Permission> permissions)` Notifies when a `Principal` begins at an illegal place in the file.
`protected void`	`skipLine(int lineNr, String line)` Notifies when a line is skipped because it was not understood for any other reason.
`protected void`	`skipPermission(int lineNr, Class<?> permissionClass)` Notifies when a Class is skipped because it is not a Permission or no valid constructors could be found.
`protected void`	`skipPermission(int lineNr, Class<? extends Permission> permissionClass, Object[] argValues, Exception e)` Notified when a new instance of the permission could not be created.
`protected void`	`skipPermission(int lineNr, Principal principal, Permission permission)` Notifies of duplicate permissions for a principal.
`protected void`	`skipPermission(int lineNr, String classname, ClassNotFoundException e)` Notifies when a permission class could not be found.
`protected void`	`skipPrincipal(int lineNr, Class<? extends Principal> principalClass)` Notifies when the principal does not have an accessible constructor for a single `String` argument.
`protected void`	`skipPrincipal(int lineNr, Class<? extends Principal> principalClass, Exception e)` Notifies when a new instance of the principl could not be created.
`protected void`	`skipPrincipalClass(int lineNr, Class<?> principalClass)` Notifies when a classname is not a `Principal`.
`protected void`	`skipPrincipalClass(int lineNr, String classname, ClassNotFoundException e)` Notifies when a Principal class could not be found.
`void`	`useHiveCache(boolean useCache)` Sets useHiveCache.
`protected void`	`warnUnclosedPrincipalBlock(Principal principal, int lineNr)` Warning when the last principal of a file is not properly closed.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - PolicyFileHiveFactory
```
public PolicyFileHiveFactory(org.wicketstuff.security.actions.ActionFactory actionFactory)
```
    Constructs a new factory that builds a Hive out of one (1) or more policy files. It registers an alias for AllPermissions.
    
    Parameters:
    actionFactory - factory required to create the actions for the permissions
    
    Throws:
    
    IllegalArgumentException - if the factory is null
- Method Detail
  - addPolicyFile
```
public final boolean addPolicyFile(URL file)
```
    Adds a new Hive policy file to this factory. The file is not used until createHive() is executed. Url's are always retained for possible re-use.
    
    Parameters:
    file -
    
    Returns:
    true, if the file was added, false otherwise
  - getPolicyFiles
```
protected final Set<URL> getPolicyFiles()
```
    A readonly view of the policy files added to this factory.
    
    Returns:
    a set containing URL's
  - addStream
```
public final boolean addStream(InputStream stream)
```
    Adds a new Hive policy to this factory. The stream is not read until createHive() is executed. Depending on the state of the flag isCloseInputStreams() the stream is closed or left untouched after it is read. In all cases the stream is removed from the factory after being read. The format of the inputstream must be the same as that of a regular policy file.
    
    Parameters:
    stream -
    
    Returns:
    true, if the stream was added, false otherwise
  - getStreams
```
protected final Set<InputStream> getStreams()
```
    A readonly view of the streams added to this factory.
    
    Returns:
    a set containing InputStreams
  - addReader
```
public final boolean addReader(Reader input)
```
    Adds a new Hive policy to this factory. The reader is not read until createHive() is executed. Depending on the state of the flag isCloseInputStreams() the reader is closed or left untouched after it is read. In all cases the reader is removed from the factory after being read. The format of the inputstream must be the same as that of a regular policy file.
    
    Parameters:
    input -
    
    Returns:
    true, if the reader was added, false otherwise
  - getReaders
```
protected final Set<Reader> getReaders()
```
    A readonly view of the readers added to this factory.
    
    Returns:
    a set containing Readers
  - getAlias
```
public final String getAlias(String key)
```
    Returns the value of the alias.
    
    Parameters:
    key - the part between the ${}
    
    Returns:
    the value or null if that alias does not exist
  - setAlias
```
public final String setAlias(String key,
              String value)
```
    Sets the value for an alias, overwrites any existing alias with the same name
    
    Parameters:
    key - the part between the ${}
    value - the value the alias is replaced with at hive creation time.
    
    Returns:
    the previous value or null
  - getCurrentLineNr
```
protected final int getCurrentLineNr()
```
    The current line being read.
    
    Returns:
    the line number
  - constructHive
```
protected BasicHive constructHive()
```
    Changeable by subclasses to return there own hive subclass. Note that the actual filling with content happens in createHive(). Default implementation return either a SimpleCachingHive or a BasicHive depending on isUsingHiveCache()
    
    Returns:
    BasicHive subclass.
  - createHive
```
public final Hive createHive()
```
    This method is not thread safe.
    
    Specified by:
    
    createHive in interface HiveFactory
    
    Returns:
    the new Hive.
    See Also:
    HiveFactory.createHive()
  - readPolicyFile
```
protected final void readPolicyFile(URL file,
                  BasicHive hive)
                             throws IOException
```
    Reads principals and permissions from a file, found items are added to the hive.
    
    Parameters:
    file - the file to read
    hive - the hive where found items are appended to.
    
    Throws:
    
    IOException - if a problem occurs while reading the file
    See Also:
    readStream(InputStream, BasicHive)
  - readInputStream
```
protected final void readInputStream(InputStream stream,
                   BasicHive hive)
                              throws IOException
```
    Reads principals and permissions from a stream, found items are added to the hive. The stream is closed depending on the isCloseInputStreams() flag.
    
    Parameters:
    stream - the stream to read
    hive - the hive where found items are appended to.
    
    Throws:
    
    IOException - if a problem occurs while reading the file
    See Also:
    isCloseInputStreams(), setCloseInputStreams(boolean), readStream(InputStream, BasicHive)
  - readInputReader
```
protected final void readInputReader(Reader input,
                   BasicHive hive)
                              throws IOException
```
    Reads principals and permissions from a Reader, found items are added to the hive. The reader is closed depending on the isCloseInputStreams() flag.
    
    Parameters:
    input - the reader to read
    hive - the hive where found items are appended to.
    
    Throws:
    
    IOException - if a problem occurs while reading the file
    See Also:
    isCloseInputStreams(), setCloseInputStreams(boolean), readStream(InputStream, BasicHive)
  - readReader
```
protected void readReader(Reader input,
              BasicHive hive)
                   throws IOException
```
    Reads principals and permissions from a Reader, found items are added to the hive. Subclasses should override this method or readStream(InputStream, BasicHive) if they want do do something different from the default. No need to call the notifyMethods as that is handled by readInputReader(Reader, BasicHive) and readInputStream(InputStream, BasicHive) respectively. Default implementation is to call read(Reader, BasicHive). This method never closes the reader.
    
    Parameters:
    input -
    hive -
    
    Throws:
    
    IOException
  - notifyStreamEnd
```
protected void notifyStreamEnd(InputStream stream,
                   int lineNr)
```
    Notifies that the stream will be read no further. Typically this is because the end of the stream is reached but it is also called when an exception occurs while reading the stream.
    
    Parameters:
    stream -
    lineNr - number of lines processed
  - notifyReaderStart
```
protected void notifyReaderStart(Reader input)
```
    Notifies that a reader is about to be read.
    
    Parameters:
    input - the reader
  - notifyReaderEnd
```
protected void notifyReaderEnd(Reader input,
                   int lineNr)
```
    Notifies that the Reader will be read no further. Typically this is because the end of the stream is reached but it is also called when an exception occurs while reading the reader.
    
    Parameters:
    input -
    lineNr - number of lines processed
  - notifyStreamStart
```
protected void notifyStreamStart(InputStream stream)
```
    Notifies that a stream is about to be read.
    
    Parameters:
    stream - the stream
  - readStream
```
protected void readStream(InputStream input,
              BasicHive hive)
                   throws IOException
```
    Reads principals and permissions from a InputStream , found items are added to the hive. This method never closes the input stream.
    
    Parameters:
    input -
    hive -
    
    Throws:
    
    IOException
  - read
```
protected final void read(Reader input,
        BasicHive hive)
                   throws IOException
```
    Reads principals and permissions from a Reader , found items are added to the hive. This method never closes the reader.
    
    Parameters:
    input -
    hive -
    
    Throws:
    
    IOException
  - warnUnclosedPrincipalBlock
```
protected void warnUnclosedPrincipalBlock(Principal principal,
                              int lineNr)
```
    Warning when the last principal of a file is not properly closed. Although the principal is automatically closed the user should complete the block statement for the principal.
    
    Parameters:
    principal -
    lineNr -
  - notifyFileClose
```
protected void notifyFileClose(URL file,
                   int lineNr)
```
    Notifies when a file is closed, either because the end of the file was reached or because an uncaught exception was thrown. Default is noop.
    
    Parameters:
    file - the file
    lineNr - the last line read
  - notifyFileStart
```
protected void notifyFileStart(URL file)
```
    Notifies when a new file is about to be read. Default is noop.
    
    Parameters:
    file - the file
  - skipPermission
```
protected void skipPermission(int lineNr,
                  String classname,
                  ClassNotFoundException e)
```
    Notifies when a permission class could not be found. Default is to log the exception
    
    Parameters:
    lineNr - the faulty line
    classname - the class of the permission
    e - the exception thrown when trying to locate the class
  - notifyPermission
```
protected void notifyPermission(int lineNr,
                    Principal principal,
                    Permission permission)
```
    Notifies when a permission is added to a principal. Default is noop.
    
    Parameters:
    lineNr - the currently process line
    principal - the current principal
    permission - the permission added to the principal
  - skipPermission
```
protected void skipPermission(int lineNr,
                  Principal principal,
                  Permission permission)
```
    Notifies of duplicate permissions for a principal. Default is to log an exception. Note that the duplicates might appear in different files.
    
    Parameters:
    lineNr - the duplicate line
    principal - the principal
    permission - the duplicate permission
  - skipIllegalPermission
```
protected void skipIllegalPermission(int lineNr,
                         Principal principal,
                         Permission permission)
```
    Notifies of permissions located outside the { and }; block statements but after a valid principal was found.
    
    Parameters:
    lineNr - the line declaring the illegal permission
    principal - the declared principal
    permission - the declared permission
  - skipPrincipalClass
```
protected void skipPrincipalClass(int lineNr,
                      String classname,
                      ClassNotFoundException e)
```
    Notifies when a Principal class could not be found. Default is to log the exception.
    
    Parameters:
    lineNr - the faulty line
    classname - the class of the Principal
    e - the exception thrown when the class could not be found
  - skipPrincipal
```
protected void skipPrincipal(int lineNr,
                 Class<? extends Principal> principalClass)
```
    Notifies when the principal does not have an accessible constructor for a single String argument. Default is to log the exception.
    
    Parameters:
    lineNr - the faulty line
    principalClass - the class of the Principal
  - notifyOfPrincipal
```
protected void notifyOfPrincipal(int lineNr,
                     Principal principal)
```
    Notifies of a new Principal read in the policy file. Default is noop.
    
    Parameters:
    lineNr - the line currently processed
    principal - the principl
  - skipPrincipal
```
protected void skipPrincipal(int lineNr,
                 Class<? extends Principal> principalClass,
                 Exception e)
```
    Notifies when a new instance of the principl could not be created. Default is to log the exception.
    
    Parameters:
    lineNr - the line currently read
    principalClass - the class of the principal
    e - the exception thrown when trying to create a new instance
  - skipPrincipalClass
```
protected void skipPrincipalClass(int lineNr,
                      Class<?> principalClass)
```
    Notifies when a classname is not a Principal. Default is to log the exception.
    
    Parameters:
    lineNr - the faulty line
    principalClass - the class which is not a subclass of Principal
  - skipLine
```
protected void skipLine(int lineNr,
            String line)
```
    Notifies when a line is skipped because it was not understood for any other reason. Default is to print this debug info.
    
    Parameters:
    lineNr - the number of the line in the file
    line - the line that was skipped
  - skipPermission
```
protected void skipPermission(int lineNr,
                  Class<? extends Permission> permissionClass,
                  Object[] argValues,
                  Exception e)
```
    Notified when a new instance of the permission could not be created. Default is to log the exception
    
    Parameters:
    lineNr - the faulty line
    permissionClass - the class trying to instantiate
    argValues - the constructor argument(s)
    e - the exception thrown when trying to create a new instance
  - arrayToString
```
protected final String arrayToString(Object[] array)
```
    Generates a comma (,) separated string of all the items in the array
    
    Parameters:
    array - the input
    
    Returns:
    a comma separated string, an empty string or null if the input array has 1 or more items, zero items or is null respectively.
  - notifyPermission
```
protected void notifyPermission(int lineNr,
                    Class<? extends Permission> permissionClass,
                    Class<?>[] args)
```
    Notifies when a Permission could not be created because no suitable constructor was found. Default is to log an exception.
    
    Parameters:
    lineNr - the faulty line
    permissionClass - the class of the permission
    args - the number and type of constructor arguments
  - skipPermission
```
protected void skipPermission(int lineNr,
                  Class<?> permissionClass)
```
    Notifies when a Class is skipped because it is not a Permission or no valid constructors could be found. Default is to log an exception.
    
    Parameters:
    lineNr - the faulty line
    permissionClass - the class (if available)
  - skipEmptyPrincipal
```
protected void skipEmptyPrincipal(int lineNr,
                      Principal principal)
```
    Notifies when a principal is skipped because there are no permissions attached. Default is to log an exception.
    
    Parameters:
    lineNr - the line closing the principal.
    principal - the skipped principal
  - skipIllegalPrincipal
```
protected void skipIllegalPrincipal(int lineNr,
                        Principal principal,
                        Set<Permission> permissions)
```
    Notifies when a Principal begins at an illegal place in the file. Default is to log an exception.
    
    Parameters:
    lineNr - the faulty line
    principal - the principal we are currently working on
    permissions - the permission collected for the current principal so far.
  - isUsingHiveCache
```
public final boolean isUsingHiveCache()
```
    Flag indicating if caching for the Hive is enabled or disabled. Default is enabled.
    
    Returns:
    useHiveCache
  - useHiveCache
```
public final void useHiveCache(boolean useCache)
```
    Sets useHiveCache.
    
    Parameters:
    useCache - enable or disable caching
  - isCloseInputStreams
```
public final boolean isCloseInputStreams()
```
    Gets closeInputStreams.
    
    Returns:
    closeInputStreams
  - setCloseInputStreams
```
public final void setCloseInputStreams(boolean closeInputStreams)
```
    Sets closeInputStreams.
    
    Parameters:
    closeInputStreams - closeInputStreams
  - getActionFactory
```
protected final org.wicketstuff.security.actions.ActionFactory getActionFactory()
```
    Gets actionFactory.
    
    Returns:
    actionFactory

Class PolicyFileHiveFactory

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

PolicyFileHiveFactory

Method Detail

addPolicyFile

getPolicyFiles

addStream

getStreams

addReader

getReaders

getAlias

setAlias

getCurrentLineNr

constructHive

createHive

readPolicyFile

readInputStream

readInputReader

readReader

notifyStreamEnd

notifyReaderStart

notifyReaderEnd

notifyStreamStart

readStream

read

warnUnclosedPrincipalBlock

notifyFileClose

notifyFileStart

skipPermission

notifyPermission

skipPermission

skipIllegalPermission

skipPrincipalClass

skipPrincipal

notifyOfPrincipal

skipPrincipal

skipPrincipalClass

skipLine

skipPermission

arrayToString

notifyPermission

skipPermission

skipEmptyPrincipal

skipIllegalPrincipal

isUsingHiveCache

useHiveCache

isCloseInputStreams

setCloseInputStreams

getActionFactory