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. It is\r
   3  * possible, however, to apply a custom scheme or not to use configurations at all.\r
   4  * <p>The library does require that a configuration scheme is chosen - in beans.xml as described below, but the library \r
   5  * does NOT impose any mandatory parameters in order to initialize. The library <i>does</i> know of certain parameters, \r
   6  * if it encounters them.\r
   7  *\r
   8  * <p>Following classes can be configured: Pz2Service (the controller), Pz2Client, and ServiceProxyClient. Some currently \r
   9  * acknowledged parameters are TYPE (service type) PAZPAR2_URL, SERVICE_ID (see Pazpar2 documentation for an explanation of \r
  10  * service id), and SERVICE_PROXY_URL</p>\r
  11  * \r
  12  * <h3>Selecting a configuration scheme</h3>\r
  13  * \r
  14  * <p>The built-in configuration schemes are:</p>\r
  15  * <ol>\r
  16  *  <li>Configuration by context parameters in web.xml, this is the simple albeit less flexible choice</li>\r
  17  *  <li>The configuration scheme Index Data uses for other MasterKey applications, Mk2Config, this is the more versatile option</li>\r
  18  * </ol> \r
  19  * \r
  20  * <p>It must be determined deploy-time what configuration scheme to use, by selecting the preferred \r
  21  * mechanism in the application's beans.xml. In this example the MasterKey configuration scheme is injected:</p> \r
  22  * \r
  23  * <pre>\r
  24  * &lt;beans xmlns="http://java.sun.com/xml/ns/javaee"\r
  25  *         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"\r
  26  *         xsi:schemaLocation="\r
  27  *     http://java.sun.com/xml/ns/javaee \r
  28  *     http://java.sun.com/xml/ns/javaee/beans_1_0.xsd"&gt;  \r
  29  *     &lt;alternatives>         \r
  30  *        &lt;class>com.indexdata.mkjsf.config.WebXmlConfigReader&lt;/class&gt;\r
  31  *        &lt;!-- Options                      Mk2ConfigReader     --&gt;\r
  32  *        &lt;!--                              WebXmlConfigReader  --&gt;        \r
  33  *     &lt;/alternatives&gt;          \r
  34  * &lt;/beans&gt;\r
  35  * </pre>\r
  36  * \r
  37  * Please note that with Tomcat7 this beans.xml would be the one in your application's WEB-INF, which means you can set it once and\r
  38  * for all. With Glassfish and JBoss, it would be the one in the META-INF directory of the mkjsf jar (the artifact of this project)\r
  39  * meaning it would have to be re-applied with every update of new versions of mkjsf.  \r
  40  * \r
  41  * <h3>Configuring the service using web.xml only</h3>\r
  42  * \r
  43  * <p>Using the web.xml configuration scheme (choosing WebXmlConfigReader in beans.xml)\r
  44  * you can configure you application to use a locally installed Pazpar2 server like this:</p>\r
  45  * \r
  46  * <pre>\r
  47  *  &lt;context-param&gt;\r
  48  *   &lt;param-name&gt;PAZPAR2_URL&lt;/param-name&gt;\r
  49  *   &lt;param-value&gt;http://localhost:8004/&lt;/param-value&gt;\r
  50  *  &lt;/context-param&gt;\r
  51  *  &lt;context-param&gt;\r
  52  *   &lt;description&gt;Service type. Possible values: SP, PZ2, TBD&lt;/description&gt;\r
  53  *   &lt;param-name&gt;TYPE&lt;/param-name&gt;\r
  54  *   &lt;param-value&gt;PZ2&lt;/param-value&gt;  \r
  55  *  &lt;/context-param&gt;\r
  56  * </pre>\r
  57  * \r
  58  * Likewise you could configure your application to use our hosted Pazpar2 service with these settings:\r
  59  *\r
  60  * <pre>\r
  61  *  &lt;context-param&gt;\r
  62  *   &lt;param-name&gt;SERVICE_PROXY_URL&lt;/param-name&gt;\r
  63  *   &lt;param-value&gt;http://mkc.indexdata.com:9009/service-proxy/&lt;/param-value&gt;\r
  64  *  &lt;/context-param&gt;\r
  65  *  &lt;context-param&gt;\r
  66  *   &lt;description&gt;Service type. Possible values: SP, PZ2, TBD&lt;/description&gt;\r
  67  *   &lt;param-name&gt;TYPE&lt;/param-name&gt;\r
  68  *   &lt;param-value&gt;SP&lt;/param-value&gt;  \r
  69  *  &lt;/context-param&gt;\r
  70  * </pre>\r
  71  * \r
  72  * \r
  73  * <h3>Configuring the service using 'Mk2Config' scheme</h3>\r
  74  * \r
  75  * <p>The Mk2ConfigReader scheme allows the configuration to exist outside of the web application archive. \r
  76  * It supports name spaces for different parts of the application (as opposed to the web.xml scheme) and it \r
  77  * supports different configurations for different virtual hosts using the same web application deployment.</p> \r
  78  * <p>For the Mk2ConfigReader scheme to work, the web.xml must contain pointers to the configuration directory \r
  79  * and properties file. The specific configuration itself would be in those files then.\r
  80  * In this example the configuration directory is in the web application itself (war://testconfig). Usually it \r
  81  * would probably be somewhere else in your file system.</p> \r
  82  * <pre>\r
  83  * &lt;context-param&gt;\r
  84  *  &lt;param-name&gt;MASTERKEY_ROOT_CONFIG_DIR&lt;/param-name&gt;\r
  85  *  &lt;param-value&gt;war://testconfig&lt;/param-value&gt;\r
  86  * &lt;/context-param&gt;\r
  87  * &lt;context-param&gt;\r
  88  *  &lt;description&gt;\r
  89  *   The sub directory to hold config file(s) for this Masterkey component.\r
  90  *  &lt;/description&gt;\r
  91  *  &lt;param-name&gt;MASTERKEY_COMPONENT_CONFIG_DIR&lt;/param-name&gt;\r
  92  *  &lt;param-value&gt;/jsfdemo&lt;/param-value&gt;\r
  93  * &lt;/context-param&gt;\r
  94  * &lt;context-param&gt;\r
  95  *  &lt;param-name&gt;MASTERKEY_CONFIG_FILE_NAME&lt;/param-name&gt;\r
  96  *  &lt;param-value>jsfdemo.properties&lt;/param-value&gt;\r
  97  * &lt;/context-param&gt;\r
  98  * &lt;context-param&gt;\r
  99  *  &lt;description&gt;\r
 100  *   Defines the lifespan of configuration parameters as retrieved\r
 101  *   from the file pointed to by MASTERKEY_CONFIG_FILE_NAME.\r
 102  *   Can be SERVLET (cached) or REQUEST (read for every request).\r
 103  *   Will default to SERVLET.\r
 104  *  &lt;/description&gt;\r
 105  *  &lt;param-name&gt;MASTERKEY_CONFIG_LIFE_TIME&lt;/param-name&gt;\r
 106  *  &lt;param-value&gt;REQUEST&lt;/param-value&gt;\r
 107  * &lt;/context-param&gt;\r
 108  * </pre>\r
 109  * \r
 110  * <p>The jsfdemo.properties file might look like this for running against a \r
 111  * local Pazpar2 service:</p>\r
 112  * \r
 113  * <pre>\r
 114  * service.TYPE = pz2\r
 115  * pz2client.PAZPAR2_URL = http://localhost:8004/\r
 116  * </pre>\r
 117  * \r
 118  * <p>Some of the other known parameters in this format could be:</p>\r
 119  * \r
 120  * <pre>\r
 121  * service.TYPE = SP              \r
 122  * proxyclient.SERVICE_PROXY_URL = http://localhost:8080/service-proxy/\r
 123  * </pre> \r
 124  * \r
 125  * <p>It's possible to implement a custom configuration scheme by either ignoring whatever scheme is \r
 126  * injected and then applying the required values otherwise, OR by extending the ConfigurationReader\r
 127  * and inject that class in beans.xml instead of any of the two predefined options. The extended\r
 128  * class must construct a Configuration object -- which is basically a set of key-value pairs -- \r
 129  * and then set the desired values and hand it off to the Configurable (currently Pz2Service, Pz2Client, \r
 130  * and ServiceProxyClient)</p> \r
 131  * \r
 132  * <p>It would also be easy enough to simply set the URL runtime from the UI pages, using methods on \r
 133  * Pz2Service (named 'pz2').</p> \r
 134  * \r
 135  */\r
 136 package com.indexdata.mkjsf.config;