Merge branch 'master' of ssh://git.indexdata.com/home/git/private/mkjsf.git into...

[mkjsf-moved-to-github.git] / src / main / java / com / indexdata / mkjsf / config / package-info.java

diff --git a/src/main/java/com/indexdata/mkjsf/config/package-info.java b/src/main/java/com/indexdata/mkjsf/config/package-info.java
new file mode 100644 (file)
index 0000000..6716e66
--- /dev/null
+++ b/src/main/java/com/indexdata/mkjsf/config/package-info.java
@@ -0,0 +1,97 @@
+/**\r
+ * The library comes with two alternative mechanisms for configuration of an application, but it is\r
+ * possible to apply a custom scheme too or not use the configurations at all.\r
+ * <p>The library does require that a configuration scheme is chosen - in beans.xml as described below.</p>\r
+ * <p>But the library does NOT impose any mandatory parameters in order to start up (except for those required for \r
+ * bootstrapping the configuration). The library <i>does</i> know of certain parameters, if it encounters them.\r
+ *\r
+ * <p>The known parameters are TYPE (service type) PAZPAR2_URL, SERVICE_ID, and SERVICE_PROXY_URL</p>\r
+ * \r
+ * <p>The built-in configuration schemes are:</p>\r
+ * <ul>\r
+ *  <li>Configuration by context parameters in web.xml</li>\r
+ *  <li>The configuration scheme Index Data uses for other MasterKey applications</li>\r
+ * </ul> \r
+ * \r
+ * <p>It must be determined deploy-time what configuration scheme to use, by selecting the preferred \r
+ * mechanism in the application's beans.xml. In this example the MasterKey configuration scheme is injected:</p> \r
+ * \r
+ * <pre>\r
+ * &lt;beans xmlns="http://java.sun.com/xml/ns/javaee"\r
+ *         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"\r
+ *         xsi:schemaLocation="\r
+ *     http://java.sun.com/xml/ns/javaee \r
+ *     http://java.sun.com/xml/ns/javaee/beans_1_0.xsd"&gt;  \r
+ *     &lt;alternatives>         \r
+ *        &lt;class>com.indexdata.mkjsf.config.Mk2ConfigReader&lt;/class&gt;\r
+ *        &lt;!-- Options                      Mk2ConfigReader     --&gt;\r
+ *        &lt;!--                              WebXmlConfigReader  --&gt;        \r
+ *     &lt;/alternatives&gt;          \r
+ * &lt;/beans&gt;\r
+ * </pre>\r
+ * \r
+ * <p>For the web.xml configuration scheme (choosing WebXmlConfigReader in beans.xml)\r
+ * to pre-define the URL of the Pazpar2 to use, the configuration could be:</p>\r
+ * \r
+ * <pre>\r
+ *  &lt;context-param&gt;\r
+ *   &lt;param-name&gt;PAZPAR2_URL&lt;/param-name&gt;\r
+ *   &lt;param-value&gt;http://localhost:8004/&lt;/param-value&gt;\r
+ *  &lt;/context-param&gt;\r
+ * </pre>\r
+ * \r
+ * <p>For the Mk2ConfigReader scheme to work, the web.xml must then contain pointers to the configuration directory \r
+ * and properties file. \r
+ * In this example the configuration directory is in the web application itself (war://testconfig). A more regular \r
+ * example would put it in a separate directory to not have it overwritten by each deployment of the war.</p> \r
+ * <pre>\r
+ * &lt;context-param&gt;\r
+ *  &lt;param-name&gt;MASTERKEY_ROOT_CONFIG_DIR&lt;/param-name&gt;\r
+ *  &lt;param-value&gt;war://testconfig&lt;/param-value&gt;\r
+ * &lt;/context-param&gt;\r
+ * &lt;context-param&gt;\r
+ *  &lt;description&gt;\r
+ *   The sub directory to hold config file(s) for this Masterkey component.\r
+ *  &lt;/description&gt;\r
+ *  &lt;param-name&gt;MASTERKEY_COMPONENT_CONFIG_DIR&lt;/param-name&gt;\r
+ *  &lt;param-value&gt;/jsfdemo&lt;/param-value&gt;\r
+ * &lt;/context-param&gt;\r
+ * &lt;context-param&gt;\r
+ *  &lt;param-name&gt;MASTERKEY_CONFIG_FILE_NAME&lt;/param-name&gt;\r
+ *  &lt;param-value>jsfdemo.properties&lt;/param-value&gt;\r
+ * &lt;/context-param&gt;\r
+ * &lt;context-param&gt;\r
+ *  &lt;description&gt;\r
+ *   Defines the lifespan of configuration parameters as retrieved\r
+ *   from the file pointed to by MASTERKEY_CONFIG_FILE_NAME.\r
+ *   Can be SERVLET (cached) or REQUEST (read for every request).\r
+ *   Will default to SERVLET.\r
+ *  &lt;/description&gt;\r
+ *  &lt;param-name&gt;MASTERKEY_CONFIG_LIFE_TIME&lt;/param-name&gt;\r
+ *  &lt;param-value&gt;REQUEST&lt;/param-value&gt;\r
+ * &lt;/context-param&gt;\r
+ * </pre>\r
+ * \r
+ * <p>The jsfdemo.properties file might look like this for running against a \r
+ * local Pazpar2 service:</p>\r
+ * \r
+ * <code>pz2client.PAZPAR2_URL = http://localhost:8004/</code>\r
+ * \r
+ * <p>Some of the other known parameters in this format could be:</p>\r
+ * \r
+ * <pre>\r
+ * service.TYPE = SP              \r
+ * proxyclient.SERVICE_PROXY_URL = http://localhost:8080/service-proxy/\r
+ * </pre> \r
+ * \r
+ * <p>It's possible to implement a custom configuration scheme by either ignoring whatever scheme is \r
+ * injected and then applying the required values otherwise, OR by extending the ConfigurationReader\r
+ * and inject that class in beans.xml instead of any of the two predefined options. The extended\r
+ * class must construct a Configuration object -- which is basically a set of key-value pairs -- \r
+ * and then set the desired values and hand it off to the Configurable (currently Pz2Service, Pz2Client, \r
+ * and ServiceProxyClient)</p> \r
+ * \r
+ * <p>Finally it's possible to set the URL runtime even from the UI pages.</p> \r
+ * \r
+ */\r
+package com.indexdata.mkjsf.config;
\ No newline at end of file