# HG changeset patch # User Frank Sachsenheim # Date 1502979623 -7200 # Node ID 7310735dd5b559ab5c6e1cb591b2c9c3da68b786 # Parent 3972535c1146ebfb4619eb99daab73a656bdb534 Refactoring of the configuration docs diff -r 3972535c1146 -r 7310735dd5b5 doc/src/site/markdown/digilib-config.md --- a/doc/src/site/markdown/digilib-config.md Mon Jun 12 16:02:44 2017 +0200 +++ b/doc/src/site/markdown/digilib-config.md Thu Aug 17 16:20:23 2017 +0200 @@ -1,100 +1,269 @@ # Configuring digilib -## digilib-config.xml +The main configuration for *digilib* is the XML file `digilib-config.xml` in the +`WEB-INF` directory of the webapp or a Java properties file `digilib.properties` +somewhere in the classpath. +(If you really need a different location for the XML file you can define it in +the `config-file` init-parameter to the Servlet. **TODO** add an example) -The main configuration for digilib is the XML file `digilib-config.xml` in the `WEB-INF` -directory in the webapp or a Java properties file `digilib.properties` somewhere in the classpath. -(If you really need a different location for the XML file you can define it in the `config-file` -init-parameter to the Servlet.) +In the configuration file you can set lots of paths and options. *digilib* uses +default values for all configuration settings that meet most requirements. +Hence you have to configure only the settings that you want to change. The +**`basedir-list`** parameter however is **mandatory** unless you want to serve +the contributed example images for an evaluation. -In the configuration file you can set lots of paths and options. digilib uses -default values for all configuration settings that meet most requirements -so you have to configure only the settings that you want to change. +All options are defined as `parameter` elements with the attributes `name` and +`value` that are wrapped in the root element `digilib-config`. A minimal +configuration looks like this: -You have to adjust the **`basedir-list`** parameter to the directories -where your images are installed. The directory path has to be an absolute -path following the conventions of your operating system (a relative path -is taken to be relative to the web application directory). +```xml + + + + +``` -You need only one directory if you don't want to provide pre-scaled low resolution -versions of your images. If you have pre-scaled images the directory with the -high-resolution images must be the first entry in the list. +A more extensive example is included in the sources as +[digilib-config.xml.template](https://github.com/robcast/digilib/blob/master/webapp/src/main/webapp/WEB-INF/digilib-config.xml.template). + + +## Available parameters -Documentation on the directory layout and on using pre-scaled images is -[here](image-directories.html). +The documented parameter values below are the defaults. + +If relative paths are provided as file locations, these will be resolved with +the web application's directory as base. -A minimal configuration looks like this: +You can inspect a summary of your running digilib configuration at the URL +`/server/dlConfig.jsp`. + +### Image locations + +```xml + +``` - - - - - - -A more customized configuration may look like the following -(for another commented example see -[digilib-config.xml.template](https://sourceforge.net/p/digilib/code/ci/default/tree/webapp/src/main/webapp/WEB-INF/digilib-config.xml.template), -for a full list of -configuration options and their default values use the source: -[DigilibConfiguration](https://sourceforge.net/p/digilib/code/ci/default/tree/common/src/main/java/digilib/conf/DigilibConfiguration.java), -[DigilibServletConfiguration](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet/src/main/java/digilib/conf/DigilibServletConfiguration.java), -[DigilibServlet3Configuration](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet3/src/main/java/digilib/conf/DigilibServlet3Configuration.java) -): +A list of directories where images are searched. See +[this document](image-directories.html) for details. + +```xml + +``` + +This image is sent to indicate an authorization failure. + +```xml + +``` + +This image is sent to indicate a general failure. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +```xml + +``` + +This image to sent to indicate an undiscoverable image. + +```xml + +``` + +Enables the mapping of 'virtual directories' to actual directories in the +filesystem. + +```xml + +``` + +The location of the mapping file. Refer to +[this template](https://sourceforge.net/p/digilib/code/ci/default/tree/webapp/src/main/webapp/WEB-INF/digilib-map.xml.template) +for an example. **TODO** elaborate `link` and `dir` attribute or the whole file structure. + + +### Image processing options + +```xml + +``` -You can supply your own icons for the "error" and "access denied" -messages by the servlet. Standard images will be used if these -parameters are not defined. +The default interpolation quality (`0` is worst). + +**TODO** document valid value range + +```xml + +``` + +The maximum size of delivered images, `0` means no limit. + +**TODO** mention measurement unit explicitly -If you need authorization set `use-authorization` to true and read the +```xml + +``` + +Defines whether requests with `mo=file` as parameter are allowed (see +[Scaler API](scaler-api.html)). + +```xml + +``` + +Degree of subsampling on image load. **TODO** valid / recommended value range + + +### Authentication and authorization + +Details are provided in the [documentation on authentication and authorization](auth.html). -You can see a summary of your running digilib configuration at the URL -[http://localhost:8080/digitallibrary/server/dlConfig.jsp](http://localhost:8080/digitallibrary/server/dlConfig.jsp) +```xml + +``` + +Configuration file for authentication and authorization. + +```xml + +``` + +This part of the URL indicates authorized access. **TODO** clarify by example? + +```xml + +``` + +The name of the cookie that holds the authentication token. + +```xml + +``` + +The class to handle authentication. + +```xml + +``` + +The class to handle authorization. + +```xml + +``` + +Enables authorization. + + +### IIIF API options + +The options configure the [IIIF](iiif-api) interface. + +```xml + +``` + +The supported IIIF API version. **FIXME**? shouldn't that be set programmatically? + +```xml + +``` + +Enables the `Cross-Origin Resource Sharing` header in IIIF info requests. + +```xml + +``` + +Enables the `Cross-Origin Resource Sharing` header in IIIF image requests. + +```xml + +``` + +The prefix (after `Scaler`) that leads to the IIIF API. + +```xml + +``` + +The character that replaces a slash in IIIF requests. + + +### Threading options - \ No newline at end of file +```xml + +``` + +The number of waiting requests in the queue. + +```xml + +``` + +The number of working threads. + +```xml + +``` + +Timeout for worker threads in milliseconds. + + +### Assorted options + +```xml + +``` + +Defines how errors are represented. Allowed values are `code`, `image` and +`text`. + +```xml + +``` + +Enables the use of a disk cache for the image toolkit. +**TODO** elaborate dis-/advantages. + +```xml + +``` + +Location of the logging configuration. + +**TODO** amend a link to a useful, elaborative resource + + +### Unknown category + +**TODO** move items to appropriate sections + +```xml + +``` + +Class for **TODO**. + +```xml + +``` + +Class for **TODO**. + +```xml + +``` + +Class for the `DocuImage` instance, **TODO** elaborate intended use + +```xml + +``` + +**TODO** elaborate + +```xml + +``` +Class for **TODO**.