Mercurial > hg > digilib
diff digilib-config.html @ 1659:fe8300fdcd9d
Creating site for 2.5-SNAPSHOT
| author | Robert Casties <casties@mpiwg-berlin.mpg.de> |
|---|---|
| date | Mon, 20 Nov 2017 20:24:00 +0000 |
| parents | 636e7342b1b6 |
| children | 1beeb9319d78 |
line wrap: on
line diff
--- a/digilib-config.html Tue Aug 22 18:46:51 2017 +0000 +++ b/digilib-config.html Mon Nov 20 20:24:00 2017 +0000 @@ -1,13 +1,13 @@ <!DOCTYPE html> <!-- - | Generated by Apache Maven Doxia at 2017-08-22 + | Generated by Apache Maven Doxia at 2017-11-20 | Rendered using Apache Maven Fluido Skin 1.3.0 --> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta name="Date-Revision-yyyymmdd" content="20170822" /> + <meta name="Date-Revision-yyyymmdd" content="20171120" /> <meta http-equiv="Content-Language" content="en" /> <title>digilib - The Digital Image Library – Configuring digilib</title> <link rel="stylesheet" href="./css/apache-maven-fluido-1.3.0.min.css" /> @@ -41,7 +41,7 @@ <ul class="breadcrumb"> - <li id="publishDate">Last Published: 2017-08-22</li> + <li id="publishDate">Last Published: 2017-11-20</li> <li class="divider">|</li> <li id="projectVersion">Version: 2.5-SNAPSHOT</li> @@ -90,6 +90,13 @@ <li> + <a href="build-maven.html" title="Building digilib"> + <i class="none"></i> + Building digilib</a> + </li> + + <li> + <a href="install-digilib.html" title="Installing digilib"> <i class="none"></i> Installing digilib</a> @@ -97,9 +104,9 @@ <li> - <a href="build-maven.html" title="Building digilib"> + <a href="server-setups.html" title="Server setups"> <i class="none"></i> - Building digilib</a> + Server setups</a> </li> <li class="nav-header">Configuration</li> @@ -178,7 +185,7 @@ <a href="http://maven.apache.org/" title="Built by Maven" class="builtBy"> <img class="builtBy" alt="Built by Maven" src="https://maven.apache.org/images/logos/maven-feather.png" /> </a> - <a href="https://github.com/" title="Hosted by GitHub" class="builtBy"> + <a href="../../" title="Hosted by GitHub" class="builtBy"> <img class="builtBy" alt="Hosted by GitHub" src="https://assets-cdn.github.com/images/modules/logos_page/GitHub-Logo.png" width="200px" /> </a> <a href="http://www.sourceforge.net/" title="Hosted by SourceForge" class="builtBy"> @@ -192,76 +199,245 @@ <div id="bodyColumn" class="span9" > <h1>Configuring digilib</h1> +<p>The main configuration for <i>digilib</i> is the XML file <tt>digilib-config.xml</tt> in the <tt>WEB-INF</tt> directory of the webapp. Alternatively you can also use a Java properties file <tt>digilib.properties</tt> somewhere in the classpath. (If you really need a different location for the XML file you can define it in the <tt>config-file</tt> init-parameter to the Servlet. <b>TODO</b> add an example)</p> +<p>In the configuration file you can set lots of paths and options. <i>digilib</i> 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 <b><tt>basedir-list</tt></b> parameter however is <b>mandatory</b> unless you only want to serve the contributed example images for an evaluation.</p> +<p>All options are defined as <tt>parameter</tt> elements with the attributes <tt>name</tt> and <tt>value</tt> that are wrapped in the root element <tt>digilib-config</tt>. A minimal configuration looks like this:</p> + +<div class="source"> +<div class="source"> +<pre><?xml version="1.0" encoding="UTF-8"?> +<digilib-config> + <parameter name="basedir-list" value="/usr/local/images" /> +</digilib-config> +</pre></div></div> +<p>A more extensive example is included in the sources as <a class="externalLink" href="https://github.com/robcast/digilib/blob/master/webapp/src/main/webapp/WEB-INF/digilib-config.xml.template">digilib-config.xml.template</a>.</p> <div class="section"> -<h2><a name="digilib-config.xml"></a>digilib-config.xml</h2> -<p>The main configuration for digilib is the XML file <tt>digilib-config.xml</tt> in the <tt>WEB-INF</tt> directory in the webapp or a Java properties file <tt>digilib.properties</tt> somewhere in the classpath. (If you really need a different location for the XML file you can define it in the <tt>config-file</tt> init-parameter to the Servlet.)</p> -<p>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.</p> -<p>You have to adjust the <b><tt>basedir-list</tt></b> 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).</p> -<p>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.</p> -<p>Documentation on the directory layout and on using pre-scaled images is <a href="image-directories.html">here</a>.</p> -<p>A minimal configuration looks like this:</p> +<h2><a name="Available_parameters"></a>Available parameters</h2> +<p>The documented parameter values below are the defaults.</p> +<p>If relative paths are provided as file locations, these will be resolved with the web application’s directory as base.</p> +<p>You can inspect a summary of your running digilib configuration at the URL <tt><base_url>/server/dlConfig.jsp</tt>.</p> +<div class="section"> +<h3><a name="Image_locations"></a>Image locations</h3> + +<div class="source"> +<div class="source"> +<pre><parameter name="basedir-list" value="sample-images" /> +</pre></div></div> +<p>A list of directories where images are searched. See <a href="image-directories.html">this document</a> for details.</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="denied-image" value="img/digilib-denied.png" /> +</pre></div></div> +<p>This image is sent to indicate an authorization failure.</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="error-image" value="img/digilib-error.png" /> +</pre></div></div> +<p>This image is sent to indicate a general failure.</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="notfound-image" value="img/digilib-notfound.png" /> +</pre></div></div> +<p>This image to sent to indicate that the requested image does not exist or could not be read.</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="use-mapping" value="false" /> +</pre></div></div> +<p>Enables the mapping of ‘virtual directories’ to actual directories in the filesystem using a mapping file.</p> <div class="source"> <div class="source"> -<pre><!-- Digilib servlet config file --> -<digilib-config> - <!-- List of directories where images are searched. - The authoritative directory with the high-resolution images - is first in list. --> - <parameter name="basedir-list" value="/docuserver/images" /> -</digilib-config> +<pre><parameter name="mapping-file" value="digilib-map.xml" /> +</pre></div></div> +<p>The location of the mapping file. Refer to <a class="externalLink" href="https://github.com/robcast/digilib/blob/master/webapp/src/main/webapp/WEB-INF/digilib-map.xml.template">digilib-map.xml.template</a> for an example. </p> +<p>The file contains <tt>mapping</tt> elements with a <tt>link</tt> attribute containing a ‘virtual directory’ name that is mapped to the directory given in the <tt>dir</tt> attribute.</p></div> +<div class="section"> +<h3><a name="Image_processing_options"></a>Image processing options</h3> + +<div class="source"> +<div class="source"> +<pre><parameter name="default-quality" value="2" /> +</pre></div></div> +<p>The default interpolation quality.</p> + +<ul> + +<li><tt>0</tt>: do not use interpolation (worst),</li> + +<li><tt>1</tt>: use linear interpolation,</li> + +<li><tt>2</tt>: use bilinear interpolation and blur-before-scale (best).</li> +</ul> + +<div class="source"> +<div class="source"> +<pre><parameter name="max-image-size" value="0" /> </pre></div></div> -<p>A more customized configuration may look like the following (for another commented example see <a class="externalLink" href="https://sourceforge.net/p/digilib/code/ci/default/tree/webapp/src/main/webapp/WEB-INF/digilib-config.xml.template">digilib-config.xml.template</a>, for a full list of configuration options and their default values use the source: <a class="externalLink" href="https://sourceforge.net/p/digilib/code/ci/default/tree/common/src/main/java/digilib/conf/DigilibConfiguration.java">DigilibConfiguration</a>, <a class="externalLink" href="https://sourceforge.net/p/digilib/code/ci/default/tree/servlet/src/main/java/digilib/conf/DigilibServletConfiguration.java">DigilibServletConfiguration</a>, <a class="externalLink" href="https://sourceforge.net/p/digilib/code/ci/default/tree/servlet3/src/main/java/digilib/conf/DigilibServlet3Configuration.java">DigilibServlet3Configuration</a> ):</p> +<p>The maximum size of delivered images as pixel area, <tt>40000</tt> means up to 200x200 or 100x400, <tt>0</tt> means no limit.</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="sendfile-allowed" value="true" /> +</pre></div></div> +<p>Defines whether requests with <tt>mo=file</tt> or <tt>mo=rawfile</tt> as parameter are allowed to download files (see <a href="scaler-api.html">Scaler API</a>).</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="subsample-minimum" value="2.0" /> +</pre></div></div> +<p>Degree of subsampling on image load. This is the minimum factor that is scaled by interpolation and not by subsampling, i.e. by skipping pixels.</p></div> +<div class="section"> +<h3><a name="Authentication_and_authorization"></a>Authentication and authorization</h3> +<p>Details are provided in the <a href="auth.html">documentation on authentication and authorization</a>.</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="auth-file" value="digilib-auth.xml" /> +</pre></div></div> +<p>Configuration file for authentication and authorization. The format and content of the configuration file is determined by the chosen authentication and authorization classes. </p> + +<div class="source"> +<div class="source"> +<pre><parameter name="authn-token-cookie" value="id_token" /> +</pre></div></div> +<p>The name of the cookie that holds the authentication token for <tt>digilib.auth.OpenIdAuthnOps</tt>.</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="authnops-class" value="digilib.auth.IpAuthnOps" /> +</pre></div></div> +<p>The class to handle authentication.</p> <div class="source"> <div class="source"> -<pre><!-- Digilib servlet config file --> -<digilib-config> - <!-- Image to be sent to indicate general failure. --> - <parameter name="error-image" value="/docuserver/images/icons/broken.gif" /> +<pre><parameter name="authzops-class" value="digilib.auth.PathAuthzOps" /> +</pre></div></div> +<p>The class to handle authorization.</p> - <!-- Image to be sent to indicate authorization failure. --> - <parameter name="denied-image" value="/docuserver/images/icons/alert.red.gif" /> +<div class="source"> +<div class="source"> +<pre><parameter name="use-authorization" value="false" /> +</pre></div></div> +<p>Enable or disable all authorization. If <tt>use-authorization</tt> is <tt>true</tt> it also needs to be configured using <tt>authnops-class</tt> and <tt>authzops-class</tt> and the <tt>auth-file</tt>.</p></div> +<div class="section"> +<h3><a name="IIIF_API_options"></a>IIIF API options</h3> +<p>The options configure the IIIF interface. For more information see the <a href="iiif-api">digilib IIIF documentation</a></p> - <!-- Image to be sent to indicate file-not-found. --> - <parameter name="notfound-image" value="/docuserver/images/icons/notfound.gif" /> +<div class="source"> +<div class="source"> +<pre><parameter name="iiif-api-version" value="2.1" /> +</pre></div></div> +<p>The IIIF API version for the generated <tt>info.json</tt> information response. </p> + +<div class="source"> +<div class="source"> +<pre><parameter name="iiif-info-cors" value="true" /> +</pre></div></div> +<p>Enables the <tt>Cross-Origin Resource Sharing</tt> header in IIIF info requests.</p> - <!-- List of directories where images are searched. - The authoritative directory with the high-resolution images - is first in list. --> - <parameter name="basedir-list" value="/docuserver/images:/docuserver/scaled/small" /> +<div class="source"> +<div class="source"> +<pre><parameter name="iiif-image-cors" value="true" /> +</pre></div></div> +<p>Enables the <tt>Cross-Origin Resource Sharing</tt> header in IIIF image requests.</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="iiif-prefix" value="IIIF" /> +</pre></div></div> +<p>The prefix (after <tt>Scaler</tt>) that leads to the IIIF API.</p> - <!-- default interpolation quality (0=worst) --> - <parameter name="default-quality" value="2"/> +<div class="source"> +<div class="source"> +<pre><parameter name="iiif-slash-replacement" value="!" /> +</pre></div></div> +<p>The character that replaces a slash in the identifier of IIIF requests.</p></div> +<div class="section"> +<h3><a name="Threading_options"></a>Threading options</h3> - <!-- is sending whole image files with mo=file allowed? --> - <parameter name="sendfile-allowed" value="true" /> +<div class="source"> +<div class="source"> +<pre><parameter name="max-waiting-threads" value="20" /> +</pre></div></div> +<p>The maximum number of requests waiting in the queue before sending “service unavailable”.</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="worker-threads" value="2" /> +</pre></div></div> +<p>The maximum number of concurrently working threads.</p> - <!-- the a maximum size of any sent image. (0 means no limit) --> - <parameter name="max-image-size" value="0" /> +<div class="source"> +<div class="source"> +<pre><parameter name="worker-timeout" value="60000" /> +</pre></div></div> +<p>Timeout for worker threads in milliseconds.</p></div> +<div class="section"> +<h3><a name="Assorted_options"></a>Assorted options</h3> - <!-- number of working threads --> - <parameter name="worker-threads" value="2" /> +<div class="source"> +<div class="source"> +<pre><parameter name="default-errmsg-type" value="image" /> +</pre></div></div> +<p>Defines how errors are presented to the user. Allowed values are <tt>code</tt>, <tt>image</tt> and <tt>text</tt>.</p> - <!-- number of waiting requests in queue --> - <parameter name="max-waiting-threads" value="20" /> +<ul> + +<li><tt>image</tt> sends an error-image as error code (see <tt>denied-image</tt>, <tt>error-image</tt>, <tt>notfound-image</tt> parameters).</li> + +<li><tt>code</tt> sends an HTTP error code, which may result in a broken image display in the browser.</li> + +<li><tt>text</tt> sends a plain-text error message, which may result in a broken image display in the browser.</li> +</ul> - <!-- Restrict access to authorized users --> - <parameter name="use-authorization" value="false"/> +<div class="source"> +<div class="source"> +<pre><parameter name="img-diskcache-allowed" value="false" /> +</pre></div></div> +<p>Enables the use of a disk cache for the image toolkit. Using the disk cache may leak file handles and lead to resource issues if digilib runs for a long time.</p> - <!-- use mapping of "virtual directories" to real directories on the server --> - <parameter name="use-mapping" value="true"/> +<div class="source"> +<div class="source"> +<pre><parameter name="log-config-file" value="log4j-config.xml" /> +</pre></div></div> +<p>Location of the logging configuration file. The current logger is <a class="externalLink" href="https://logging.apache.org/log4j/1.2/manual.html">Log4J 1.2</a>.</p></div> +<div class="section"> +<h3><a name="Unknown_category"></a>Unknown category</h3> +<p><b>TODO</b> move items to appropriate sections</p> - <!-- location of XML name mapping file --> - <parameter name="mapping-file" value="digilib-map.xml"/> +<div class="source"> +<div class="source"> +<pre><parameter name="dirmeta-class" value="digilib.meta.IndexMetaDirMeta" /> +</pre></div></div> +<p>Class for <b>TODO</b>.</p> - <!-- location of logger config file --> - <parameter name="log-config-file" value="log4j-config.xml"/> -</digilib-config> +<div class="source"> +<div class="source"> +<pre><parameter name="docudirectory-class" value="digilib.io.BaseDirDocuDirectory" /> +</pre></div></div> +<p>Class for <b>TODO</b>.</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="docuimage-class" value="digilib.image.ImageLoaderDocuImage" /> </pre></div></div> -<p>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.</p> -<p>If you need authorization set <tt>use-authorization</tt> to true and read the <a href="auth.html">documentation on authentication and authorization</a>.</p> -<p>You can see a summary of your running digilib configuration at the URL <a class="externalLink" href="http://localhost:8080/digitallibrary/server/dlConfig.jsp">http://localhost:8080/digitallibrary/server/dlConfig.jsp</a></p></div> +<p>Class for the <tt>DocuImage</tt> instance, <b>TODO</b> elaborate intended use</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="docuimage-hacks" value="" /> +</pre></div></div> +<p><b>TODO</b> elaborate</p> + +<div class="source"> +<div class="source"> +<pre><parameter name="filemeta-class" value="digilib.meta.IndexMetaFileMeta" /> +</pre></div></div> +<p>Class for <b>TODO</b>.</p></div></div> </div> </div> </div> @@ -271,7 +447,7 @@ <footer> <div class="container-fluid"> <div class="row span12">Copyright © 2001-2017 - <a href="https://github.com/robcast/digilib">digilib Community</a>. + <a href="https://robcast.github.io/digilib/">digilib Community</a>. All Rights Reserved. </div>