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. + *
  3. The configuration scheme Index Data uses for other MasterKey applications, Mk2Config, this is the more versatile option
  4. + *
* *

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