Documents configuration schemes in more detail

[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
index aec5200..60dc2f5 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/config/package-info.java
+++ b/src/main/java/com/indexdata/mkjsf/config/package-info.java
@@ -5,13 +5,16 @@
  * <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
+ * <p>Following classes can be configured: Pz2Service (controller), Pz2Client, and ServiceProxyClient. Some currently \r
+ * acknowledged parameters are TYPE (service type) PAZPAR2_URL, SERVICE_ID, and SERVICE_PROXY_URL</p>\r
+ * \r
+ * <h3>Selecting a configuration scheme</h3>\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
+ * <ol>\r
+ *  <li>Configuration by context parameters in web.xml, this is the simple though less flexible choice</li>\r
+ *  <li>The configuration scheme Index Data uses for other MasterKey applications, Mk2Config, this is the more versatile option</li>\r
+ * </ol> \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
@@ -23,13 +26,19 @@
  *     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;class>com.indexdata.mkjsf.config.WebXmlConfigReader&lt;/class&gt;\r
  *        &lt;!-- Options                      Mk2ConfigReader     --&gt;\r
  *        &lt;!--                              WebXmlConfigReader  --&gt;        \r
  *     &lt;/alternatives&gt;          \r
  * &lt;/beans&gt;\r
  * </pre>\r
  * \r
+ * 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
+ * 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
+ * meaning it would have to be re-applied with every update of new versions of mkjsf.  \r
+ * \r
+ * <h3>Configuring the service using web.xml only</h3>\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 and choose Pazpar2 as the selected\r
  * service type, the configuration could be:</p>\r
@@ -46,10 +55,15 @@
  *  &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
+ * <h3>Configuring the service using 'Mk2Config' scheme</h3>\r
+ * \r
+ * <p>The Mk2ConfigReader scheme allows the configuration to exist outside of the web application archive. \r
+ * It supports name spaces for different parts of the application (as opposed to the web.xml scheme) and it \r
+ * supports different configurations for different virtual hosts using the same web application deployment.</p> \r
+ * <p>For the Mk2ConfigReader scheme to work, the web.xml must contain pointers to the configuration directory \r
  * and properties file. The specific configuration itself would be in those files then.\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
+ * In this example the configuration directory is in the web application itself (war://testconfig). Usually it \r
+ * would probably be somewhere else in your file system.</p> \r
  * <pre>\r
  * &lt;context-param&gt;\r
  *  &lt;param-name&gt;MASTERKEY_ROOT_CONFIG_DIR&lt;/param-name&gt;\r
@@ -97,7 +111,8 @@
  * 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
+ * <p>It would also be easy enough to simply set the URL runtime from the UI pages, using methods on \r
+ * Pz2Service (named 'pz2').</p> \r
  * \r
  */\r
 package com.indexdata.mkjsf.config;
\ No newline at end of file