# HG changeset patch
# User robcast
# Date 1448819594 -3600
# Node ID c36f00af6bb94268cde50853643e2639ec283532
# Parent  0d22e54092ae1b1594a457db25ea5d065aa9bbff
more documentation for AuthOps implementations.

diff -r 0d22e54092ae -r c36f00af6bb9 servlet/src/main/java/digilib/auth/MetaAccessServletAuthOps.java
--- a/servlet/src/main/java/digilib/auth/MetaAccessServletAuthOps.java	Tue Nov 17 16:20:20 2015 +0100
+++ b/servlet/src/main/java/digilib/auth/MetaAccessServletAuthOps.java	Sun Nov 29 18:53:14 2015 +0100
@@ -42,7 +42,6 @@
 import digilib.io.DocuDirCache;
 import digilib.io.DocuDirent;
 import digilib.io.FileOpException;
-import digilib.io.FileOps;
 import digilib.meta.MetadataMap;
 import digilib.util.HashTree;
 import digilib.util.XMLListLoader;
@@ -50,9 +49,28 @@
 /**
  * Implementation of AuthOps using "access" information from file metadata and
  * roles mapped to IP-number ranges defined in an XML config file.
+ * <p/>
+ * Tags "digilib-access" and "digilib-adresses" are read from the configuration file:
+ * <pre>
+ * {@code
+ * <digilib-access>
+ *   <access type="group:mpiwg" role="user"/>
+ * </digilib-access>
+ * }
+ * </pre>
+ * A user must supply one of the roles under "role" to access any object with the metadata "access" type of "type".
+ * Roles under "role" must be separated by comma only (no spaces).
+ * <pre>  
+ * {@code
+ * <digilib-addresses>
+ *   <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
+ *   <address ip="130.92.151" role="ALL" />
+ * </digilib-addresses>
+ * }
+ * </pre>
+ * A computer with an ip address that matches "ip" is automatically granted all roles under "role".
+ * The ip address is matched from the left (in full quads). Roles under "role" must be separated by comma only (no spaces). 
  * 
- * The configuration file is read by an XMLListLoader into HashTree objects for
- * IP numbers.
  */
 public class MetaAccessServletAuthOps extends ServletAuthOpsImpl {
 
@@ -74,9 +92,10 @@
     }
 
     /**
-     * Initialize.
+     * Initialize authentication operations.
      * 
-     * Read configuration files and setup authorization arrays.
+     * Reads tags "digilib-access" and "digilib-adresses" from configuration file 
+     * and sets up authentication arrays.
      * 
      * @throws AuthOpException
      *             Exception thrown on error.
@@ -136,7 +155,7 @@
                 // try to get image file from DirCache
                 DigilibConfiguration config = dlRequest.getDigilibConfig();
                 DocuDirCache cache = (DocuDirCache) config.getValue(DigilibServletConfiguration.DIR_CACHE_KEY);
-                imgs = cache.getFile(dlRequest.getFilePath(), dlRequest.getAsInt("pn"), FileOps.FileClass.IMAGE);
+                imgs = cache.getFile(dlRequest.getFilePath(), dlRequest.getAsInt("pn"));
             }
         } catch (FileOpException e) {
             throw new AuthOpException("No file for auth check!");
diff -r 0d22e54092ae -r c36f00af6bb9 servlet/src/main/java/digilib/auth/PathServletAuthOps.java
--- a/servlet/src/main/java/digilib/auth/PathServletAuthOps.java	Tue Nov 17 16:20:20 2015 +0100
+++ b/servlet/src/main/java/digilib/auth/PathServletAuthOps.java	Sun Nov 29 18:53:14 2015 +0100
@@ -37,10 +37,29 @@
 import digilib.util.XMLListLoader;
 
 /**
- * Implementation of AuthOps using paths defined in an XML config file.
+ * Implements AuthOps using paths defined in an XML config file.
+ * <p/>
+ * Tags "digilib-paths" and "digilib-adresses" are read from the configuration file:
+ * <pre>
+ * {@code
+ * <digilib-paths>
+ *   <path name="histast/eastwood-collection" role="eastwood-coll" />
+ * </digilib-paths>
+ * }
+ * </pre>
+ * A user must supply one of the roles under "role" to access the directory "name".
+ * Roles under "role" must be separated by comma only (no spaces).
+ * <pre>  
+ * {@code
+ * <digilib-addresses>
+ *   <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
+ *   <address ip="130.92.151" role="ALL" />
+ * </digilib-addresses>
+ * }
+ * </pre>
+ * A computer with an ip address that matches "ip" is automatically granted all roles under "role".
+ * The ip address is matched from the left (in full quads). Roles under "role" must be separated by comma only (no spaces). 
  * 
- * The configuration file is read by an XMLListLoader into HashTree objects for
- * authentication paths and IP numbers.
  */
 public class PathServletAuthOps extends ServletAuthOpsImpl {
 
@@ -62,9 +81,10 @@
     }
 
     /**
-     * Initialize.
+     * Initialize authentication operations.
      * 
-     * Read configuration files and setup authentication arrays.
+     * Reads tags "digilib-paths" and "digilib-adresses" from configuration file 
+     * and sets up authentication arrays.
      * 
      * @throws AuthOpException
      *             Exception thrown on error.
@@ -95,15 +115,13 @@
     /**
      * Return authorization roles needed for request.
      * 
-     * Returns the list of authorization roles that are needed to access the
+     * Returns the list of authorization roles that are required to access the
      * specified path. No list means the path is free.
      * 
-     * The location information of the request is also considered.
+     * The location information of the request is determined by ServletRequest.getRemoteAddr().
      * 
-     * @param filepath
-     *            filepath to be accessed.
-     * @param request
-     *            ServletRequest with address information.
+     * @param dlRequest
+     *            DigilibServletRequest with image path and remote address information.
      * @throws AuthOpException
      *             Exception thrown on error.
      * @return List of Strings with role names.