src/main/java/com/indexdata/mkjsf/config/package-info.java

   1 /**\r
   2  * The library comes with two alternative mechanisms for configuration of an application, but it is\r
   3  * possible to apply a custom scheme too or not use the configurations at all.\r
   4  * <p>The library does require that a configuration scheme is chosen - in beans.xml as described below.</p>\r
   5  * <p>But the library does NOT impose any mandatory parameters in order to start up (except for those required for \r
   6  * bootstrapping the configuration). The library <i>does</i> know of certain parameters, if it encounters them.\r
   7  *\r
   8  * <p>The known parameters are TYPE (service type) PAZPAR2_URL, SERVICE_ID, and SERVICE_PROXY_URL</p>\r
   9  * \r
  10  * <p>The built-in configuration schemes are:</p>\r
  11  * <ul>\r
  12  *  <li>Configuration by context parameters in web.xml</li>\r
  13  *  <li>The configuration scheme Index Data uses for other MasterKey applications</li>\r
  14  * </ul> \r
  15  * \r
  16  * <p>It must be determined deploy-time what configuration scheme to use, by selecting the preferred \r
  17  * mechanism in the application's beans.xml. In this example the MasterKey configuration scheme is injected:</p> \r
  18  * \r
  19  * <pre>\r
  20  * &lt;beans xmlns="http://java.sun.com/xml/ns/javaee"\r
  21  *         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"\r
  22  *         xsi:schemaLocation="\r
  23  *     http://java.sun.com/xml/ns/javaee \r
  24  *     http://java.sun.com/xml/ns/javaee/beans_1_0.xsd"&gt;  \r
  25  *     &lt;alternatives>         \r
  26  *        &lt;class>com.indexdata.mkjsf.config.Mk2ConfigReader&lt;/class&gt;\r
  27  *        &lt;!-- Options                      Mk2ConfigReader     --&gt;\r
  28  *        &lt;!--                              WebXmlConfigReader  --&gt;        \r
  29  *     &lt;/alternatives&gt;          \r
  30  * &lt;/beans&gt;\r
  31  * </pre>\r
  32  * \r
  33  * <p>For the web.xml configuration scheme (choosing WebXmlConfigReader in beans.xml)\r
  34  * to pre-define the URL of the Pazpar2 to use, the configuration could be:</p>\r
  35  * \r
  36  * <pre>\r
  37  *  &lt;context-param&gt;\r
  38  *   &lt;param-name&gt;PAZPAR2_URL&lt;/param-name&gt;\r
  39  *   &lt;param-value&gt;http://localhost:8004/&lt;/param-value&gt;\r
  40  *  &lt;/context-param&gt;\r
  41  * </pre>\r
  42  * \r
  43  * <p>For the Mk2ConfigReader scheme to work, the web.xml must then contain pointers to the configuration directory \r
  44  * and properties file. \r
  45  * In this example the configuration directory is in the web application itself (war://testconfig). A more regular \r
  46  * example would put it in a separate directory to not have it overwritten by each deployment of the war.</p> \r
  47  * <pre>\r
  48  * &lt;context-param&gt;\r
  49  *  &lt;param-name&gt;MASTERKEY_ROOT_CONFIG_DIR&lt;/param-name&gt;\r
  50  *  &lt;param-value&gt;war://testconfig&lt;/param-value&gt;\r
  51  * &lt;/context-param&gt;\r
  52  * &lt;context-param&gt;\r
  53  *  &lt;description&gt;\r
  54  *   The sub directory to hold config file(s) for this Masterkey component.\r
  55  *  &lt;/description&gt;\r
  56  *  &lt;param-name&gt;MASTERKEY_COMPONENT_CONFIG_DIR&lt;/param-name&gt;\r
  57  *  &lt;param-value&gt;/jsfdemo&lt;/param-value&gt;\r
  58  * &lt;/context-param&gt;\r
  59  * &lt;context-param&gt;\r
  60  *  &lt;param-name&gt;MASTERKEY_CONFIG_FILE_NAME&lt;/param-name&gt;\r
  61  *  &lt;param-value>jsfdemo.properties&lt;/param-value&gt;\r
  62  * &lt;/context-param&gt;\r
  63  * &lt;context-param&gt;\r
  64  *  &lt;description&gt;\r
  65  *   Defines the lifespan of configuration parameters as retrieved\r
  66  *   from the file pointed to by MASTERKEY_CONFIG_FILE_NAME.\r
  67  *   Can be SERVLET (cached) or REQUEST (read for every request).\r
  68  *   Will default to SERVLET.\r
  69  *  &lt;/description&gt;\r
  70  *  &lt;param-name&gt;MASTERKEY_CONFIG_LIFE_TIME&lt;/param-name&gt;\r
  71  *  &lt;param-value&gt;REQUEST&lt;/param-value&gt;\r
  72  * &lt;/context-param&gt;\r
  73  * </pre>\r
  74  * \r
  75  * <p>The jsfdemo.properties file might look like this for running against a \r
  76  * local Pazpar2 service:</p>\r
  77  * \r
  78  * <code>pz2client.PAZPAR2_URL = http://localhost:8004/</code>\r
  79  * \r
  80  * <p>Some of the other know parameters in this format could be:</p>\r
  81  * \r
  82  * <pre>\r
  83  * service.TYPE = SP              \r
  84  * proxyclient.SERVICE_PROXY_URL = http://localhost:8080/service-proxy/\r
  85  * </pre> \r
  86  * \r
  87  * <p>It's possible to implement a custom configuration scheme by either ignoring whatever scheme is \r
  88  * injected and then applying the required values otherwise, OR by extending the ConfigurationReader\r
  89  * and inject that class in beans.xml instead of any of the two predefined options. The extended\r
  90  * class must construct a Configuration object -- which is basically a set of key-value pairs -- \r
  91  * and then set the desired values and hand it off to the Configurable (currently Pz2Service, Pz2Client, \r
  92  * ServiceProxyClient</p> \r
  93  * \r
  94  * <p>Finally it's possible to set the URL runtime even from the UI pages.</p> \r
  95  * \r
  96  */\r
  97 package com.indexdata.mkjsf.config;