Documents configuration schemes in more detail

diff --git a/src/main/java/com/indexdata/mkjsf/config/Configurable.java b/src/main/java/com/indexdata/mkjsf/config/Configurable.java
index fb142ea..8e94a47 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/config/Configurable.java
+++ b/src/main/java/com/indexdata/mkjsf/config/Configurable.java
@@ -7,8 +7,8 @@ import com.indexdata.mkjsf.errors.ConfigurationException;
 \r
 /**\r
  * Interface to be implemented by any part of an application that wish to\r
- * use a ConfigurationReader for it's configuration. The Configurables that\r
- * come with the project are a Pazpar2 client and a Service Proxy client\r
+ * use a ConfigurationReader for it's configuration. See config package info page\r
+ * for more information. \r
  * \r
  * @author Niels Erik\r
  *\r

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

diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Client.java b/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Client.java
index 3417a47..9e02137 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Client.java
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Client.java
@@ -37,6 +37,21 @@ import com.indexdata.mkjsf.utils.Utils;
  * types of session handling, bootstraps lost sessions, avoids repeating already \r
  * executed queries etc, so it is -- in other words -- still a mediated interaction \r
  * with Pazpar2 that takes place. At least for now.</p>  \r
+ * \r
+ * <h3>Configuration</h3>\r
+ *\r
+ * Configuration name: pz2client.\r
+ *  \r
+ * <p>When configuring the client using the Mk2Config scheme, this is the prefix to\r
+ * use in the .properties file. When using web.xml context parameters for configuration\r
+ * the configuration name has no effect.</p> \r
+ * \r
+ * <p>Pz2Client will acknowledge following configuration parameters:\r
+ * \r
+ * <ul>\r
+ *  <li>(pz2client.)PAZPAR2_URL</li>\r
+ *  <li>(pz2client.)SERVICE_ID</li>\r
+ * </ul> \r
  *  \r
  * @author Niels Erik\r
  *\r
@@ -48,6 +63,10 @@ public class Pz2Client implements SearchClient {
   private transient Pazpar2Client client = null;\r
   private Pazpar2ClientConfiguration cfg = null;\r
   public static final String MODULENAME = "pz2client";\r
+  \r
+  /**\r
+   * PAZPAR2_URL=none, PROXY_MODE=1, SERIALIZE_REQUESTS=false, STREAMBUFF_SIZE=4096, PARSE_RESPONSES=true\r
+   */\r
   public static Map<String,String> DEFAULTS = new HashMap<String,String>();\r
   Configuration config = null;  \r
   \r

diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java b/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java
index 4d6d05f..1d3024a 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java
@@ -50,6 +50,22 @@ import com.indexdata.mkjsf.utils.Utils;
  * though, if the polling mechanism in the tag <code>&lt;pz2utils:pz2watch&gt;</code> is used.\r
  * \r
  * \r
+ * <h3>Configuration</h3>\r
+ *\r
+ * Configuration name: service\r
+ *  \r
+ * <p>When configuring the client using the Mk2Config scheme, this is the prefix to\r
+ * use in the .properties file. When using web.xml context parameters for configuration\r
+ * the configuration name has no effect.</p> \r
+ * \r
+ * <p>Pz2Service will acknowledge following configuration parameters:\r
+ * \r
+ * <ul>\r
+ *  <li>(service.)TYPE</li>  \r
+ * </ul> \r
+ * \r
+ * Possible values for service TYPE are: PZ2, SP, TBD. "TBD", meaning "to-be-decided runtime", is the default.\r
+ * \r
  **/ \r
 @Named("pz2") @SessionScoped\r
 public class Pz2Service implements StateListener, Configurable, Serializable {\r

diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/ServiceProxyClient.java b/src/main/java/com/indexdata/mkjsf/pazpar2/ServiceProxyClient.java
index 26e5c9a..e5d7307 100644 (file)
--- a/src/main/java/com/indexdata/mkjsf/pazpar2/ServiceProxyClient.java
+++ b/src/main/java/com/indexdata/mkjsf/pazpar2/ServiceProxyClient.java
@@ -38,13 +38,26 @@ import com.indexdata.mkjsf.errors.MissingConfigurationContextException;
 import com.indexdata.mkjsf.pazpar2.commands.CommandParameter;\r
 import com.indexdata.mkjsf.pazpar2.commands.Pazpar2Command;\r
 import com.indexdata.mkjsf.pazpar2.commands.sp.AuthCommand;\r
-import com.indexdata.mkjsf.pazpar2.commands.sp.ServiceProxyCommand;\r
 import com.indexdata.mkjsf.pazpar2.data.CommandError;\r
 import com.indexdata.mkjsf.utils.Utils;\r
 \r
 /**\r
  * Search client handling Service Proxy requests. \r
  *   \r
+ * <h3>Configuration</h3>\r
+ *\r
+ * Configuration name: proxyclient\r
+ *  \r
+ * <p>When configuring the client using the Mk2Config scheme, this is the prefix to\r
+ * use in the .properties file. When using web.xml context parameters for configuration\r
+ * the configuration name has no effect.</p> \r
+ * \r
+ * <p>ServiceProxyClient will acknowledge following configuration parameters:\r
+ * \r
+ * <ul>\r
+ *  <li>(proxyclient.)SERVICE_PROXY_URL</li>\r
+ * </ul>   \r
+ *   \r
  * @author Niels Erik\r
  *\r
  */\r