From d5df0bd2f94a72c8af9bdc350e46b4c3af378ceb Mon Sep 17 00:00:00 2001 From: "Niels Erik G. Nielsen" Date: Fri, 28 Jun 2013 15:13:04 -0400 Subject: [PATCH] Documents configuration schemes in more detail --- .../com/indexdata/mkjsf/config/Configurable.java | 4 +-- .../com/indexdata/mkjsf/config/package-info.java | 35 ++++++++++++++------ .../com/indexdata/mkjsf/pazpar2/Pz2Client.java | 19 +++++++++++ .../com/indexdata/mkjsf/pazpar2/Pz2Service.java | 16 +++++++++ .../mkjsf/pazpar2/ServiceProxyClient.java | 15 ++++++++- 5 files changed, 76 insertions(+), 13 deletions(-) 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 --- 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; /** * Interface to be implemented by any part of an application that wish to - * use a ConfigurationReader for it's configuration. The Configurables that - * come with the project are a Pazpar2 client and a Service Proxy client + * use a ConfigurationReader for it's configuration. See config package info page + * for more information. * * @author Niels Erik * 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 --- 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 @@ *

But the library does NOT impose any mandatory parameters in order to start up (except for those required for * bootstrapping the configuration). The library does know of certain parameters, if it encounters them. * - *

The known parameters are TYPE (service type) PAZPAR2_URL, SERVICE_ID, and SERVICE_PROXY_URL

+ *

Following classes can be configured: Pz2Service (controller), Pz2Client, and ServiceProxyClient. Some currently + * acknowledged parameters are TYPE (service type) PAZPAR2_URL, SERVICE_ID, and SERVICE_PROXY_URL

+ * + *

Selecting a configuration scheme

* *

The built-in configuration schemes are:

- * + *
    + *
  1. Configuration by context parameters in web.xml, this is the simple though less flexible choice
    2. + *
  2. The configuration scheme Index Data uses for other MasterKey applications, Mk2Config, this is the more versatile option
    3. + *
* *

It must be determined deploy-time what configuration scheme to use, by selecting the preferred * mechanism in the application's beans.xml. In this example the MasterKey configuration scheme is injected:

@@ -23,13 +26,19 @@ * http://java.sun.com/xml/ns/javaee * http://java.sun.com/xml/ns/javaee/beans_1_0.xsd"> * <alternatives> - * <class>com.indexdata.mkjsf.config.Mk2ConfigReader</class> + * <class>com.indexdata.mkjsf.config.WebXmlConfigReader</class> * <!-- Options Mk2ConfigReader --> * <!-- WebXmlConfigReader --> * </alternatives> * </beans> * * + * 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 + * 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) + * meaning it would have to be re-applied with every update of new versions of mkjsf. + * + *

Configuring the service using web.xml only

+ * *

For the web.xml configuration scheme (choosing WebXmlConfigReader in beans.xml) * to pre-define the URL of the Pazpar2 to use and choose Pazpar2 as the selected * service type, the configuration could be:

@@ -46,10 +55,15 @@ * </context-param> * * - *

For the Mk2ConfigReader scheme to work, the web.xml must then contain pointers to the configuration directory + *

Configuring the service using 'Mk2Config' scheme

+ * + *

The Mk2ConfigReader scheme allows the configuration to exist outside of the web application archive. + * It supports name spaces for different parts of the application (as opposed to the web.xml scheme) and it + * supports different configurations for different virtual hosts using the same web application deployment.

+ *

For the Mk2ConfigReader scheme to work, the web.xml must contain pointers to the configuration directory * and properties file. The specific configuration itself would be in those files then. - * In this example the configuration directory is in the web application itself (war://testconfig). A more regular - * example would put it in a separate directory to not have it overwritten by each deployment of the war.

+ * In this example the configuration directory is in the web application itself (war://testconfig). Usually it + * would probably be somewhere else in your file system.

* 
  * <context-param>
  *  <param-name>MASTERKEY_ROOT_CONFIG_DIR</param-name>
@@ -97,7 +111,8 @@
  * and then set the desired values and hand it off to the Configurable (currently Pz2Service, Pz2Client, 
  * and ServiceProxyClient)
 
  * 
- * 
Finally it's possible to set the URL runtime even from the UI pages.
 
+ * 
It would also be easy enough to simply set the URL runtime from the UI pages, using methods on 
+ * Pz2Service (named 'pz2').
 
  * 
  */
 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
--- 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 
  * executed queries etc, so it is -- in other words -- still a mediated interaction 
  * with Pazpar2 that takes place. At least for now.
  
+ * 
+ * 
Configuration

+ *
+ * Configuration name: pz2client.
+ *  
+ * 
When configuring the client using the Mk2Config scheme, this is the prefix to
+ * use in the .properties file. When using web.xml context parameters for configuration
+ * the configuration name has no effect.
 
+ * 
+ * 
Pz2Client will acknowledge following configuration parameters:
+ * 
+ * 
 
  *  
  * @author Niels Erik
  *
@@ -48,6 +63,10 @@ public class Pz2Client implements SearchClient {
   private transient Pazpar2Client client = null;
   private Pazpar2ClientConfiguration cfg = null;
   public static final String MODULENAME = "pz2client";
+  
+  /**
+   * PAZPAR2_URL=none, PROXY_MODE=1, SERIALIZE_REQUESTS=false, STREAMBUFF_SIZE=4096, PARSE_RESPONSES=true
+   */
   public static Map DEFAULTS = new HashMap();
   Configuration config = null;  
   
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
--- 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 <pz2utils:pz2watch> is used.
  * 
  * 
+ * 
Configuration

+ *
+ * Configuration name: service
+ *  
+ * 
When configuring the client using the Mk2Config scheme, this is the prefix to
+ * use in the .properties file. When using web.xml context parameters for configuration
+ * the configuration name has no effect.
 
+ * 
+ * 
Pz2Service will acknowledge following configuration parameters:
+ * 
+ * 
    
+ *  
  • (service.)TYPE
    •   
+ * 
 
+ * 
+ * Possible values for service TYPE are: PZ2, SP, TBD. "TBD", meaning "to-be-decided runtime", is the default.
+ * 
  **/ 
 @Named("pz2") @SessionScoped
 public class Pz2Service implements StateListener, Configurable, Serializable {
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
--- 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;
 import com.indexdata.mkjsf.pazpar2.commands.Pazpar2Command;
 import com.indexdata.mkjsf.pazpar2.commands.sp.AuthCommand;
-import com.indexdata.mkjsf.pazpar2.commands.sp.ServiceProxyCommand;
 import com.indexdata.mkjsf.pazpar2.data.CommandError;
 import com.indexdata.mkjsf.utils.Utils;
 
 /**
  * Search client handling Service Proxy requests. 
  *   
+ * 
Configuration

+ *
+ * Configuration name: proxyclient
+ *  
+ * 
When configuring the client using the Mk2Config scheme, this is the prefix to
+ * use in the .properties file. When using web.xml context parameters for configuration
+ * the configuration name has no effect.
 
+ * 
+ * 
ServiceProxyClient will acknowledge following configuration parameters:
+ * 
+ * 
    
+ *  
  • (proxyclient.)SERVICE_PROXY_URL
    • 
+ * 
   
+ *   
  * @author Niels Erik
  *
  */
-- 
1.7.10.4