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 and choose Pazpar2 as the selected\r
  35  * service type, the configuration could be:</p>\r
  36  * \r
  37  * <pre>\r
  38  *  &lt;context-param&gt;\r
  39  *   &lt;param-name&gt;PAZPAR2_URL&lt;/param-name&gt;\r
  40  *   &lt;param-value&gt;http://localhost:8004/&lt;/param-value&gt;\r
  41  *  &lt;/context-param&gt;\r
  42  *  &lt;context-param&gt;\r
  43  *   &lt;description&gt;Service type. Possible values: SP, PZ2, TBD&lt;/description&gt;\r
  44  *   &lt;param-name&gt;TYPE&lt;/param-name&gt;\r
  45  *   &lt;param-value&gt;PZ2&lt;/param-value&gt;  \r
  46  *  &lt;/context-param&gt;\r
  47  * </pre>\r
  48  * \r
  49  * <p>For the Mk2ConfigReader scheme to work, the web.xml must then contain pointers to the configuration directory \r
  50  * and properties file. The specific configuration itself would be in those files then.\r
  51  * In this example the configuration directory is in the web application itself (war://testconfig). A more regular \r
  52  * example would put it in a separate directory to not have it overwritten by each deployment of the war.</p> \r
  53  * <pre>\r
  54  * &lt;context-param&gt;\r
  55  *  &lt;param-name&gt;MASTERKEY_ROOT_CONFIG_DIR&lt;/param-name&gt;\r
  56  *  &lt;param-value&gt;war://testconfig&lt;/param-value&gt;\r
  57  * &lt;/context-param&gt;\r
  58  * &lt;context-param&gt;\r
  59  *  &lt;description&gt;\r
  60  *   The sub directory to hold config file(s) for this Masterkey component.\r
  61  *  &lt;/description&gt;\r
  62  *  &lt;param-name&gt;MASTERKEY_COMPONENT_CONFIG_DIR&lt;/param-name&gt;\r
  63  *  &lt;param-value&gt;/jsfdemo&lt;/param-value&gt;\r
  64  * &lt;/context-param&gt;\r
  65  * &lt;context-param&gt;\r
  66  *  &lt;param-name&gt;MASTERKEY_CONFIG_FILE_NAME&lt;/param-name&gt;\r
  67  *  &lt;param-value>jsfdemo.properties&lt;/param-value&gt;\r
  68  * &lt;/context-param&gt;\r
  69  * &lt;context-param&gt;\r
  70  *  &lt;description&gt;\r
  71  *   Defines the lifespan of configuration parameters as retrieved\r
  72  *   from the file pointed to by MASTERKEY_CONFIG_FILE_NAME.\r
  73  *   Can be SERVLET (cached) or REQUEST (read for every request).\r
  74  *   Will default to SERVLET.\r
  75  *  &lt;/description&gt;\r
  76  *  &lt;param-name&gt;MASTERKEY_CONFIG_LIFE_TIME&lt;/param-name&gt;\r
  77  *  &lt;param-value&gt;REQUEST&lt;/param-value&gt;\r
  78  * &lt;/context-param&gt;\r
  79  * </pre>\r
  80  * \r
  81  * <p>The jsfdemo.properties file might look like this for running against a \r
  82  * local Pazpar2 service:</p>\r
  83  * \r
  84  * <code>pz2client.PAZPAR2_URL = http://localhost:8004/</code>\r
  85  * \r
  86  * <p>Some of the other known parameters in this format could be:</p>\r
  87  * \r
  88  * <pre>\r
  89  * service.TYPE = SP              \r
  90  * proxyclient.SERVICE_PROXY_URL = http://localhost:8080/service-proxy/\r
  91  * </pre> \r
  92  * \r
  93  * <p>It's possible to implement a custom configuration scheme by either ignoring whatever scheme is \r
  94  * injected and then applying the required values otherwise, OR by extending the ConfigurationReader\r
  95  * and inject that class in beans.xml instead of any of the two predefined options. The extended\r
  96  * class must construct a Configuration object -- which is basically a set of key-value pairs -- \r
  97  * and then set the desired values and hand it off to the Configurable (currently Pz2Service, Pz2Client, \r
  98  * and ServiceProxyClient)</p> \r
  99  * \r
 100  * <p>Finally it's possible to set the URL runtime even from the UI pages.</p> \r
 101  * \r
 102  */\r
 103 package com.indexdata.mkjsf.config;