From 41bb69937ef5369c12e78324bf893d950ff82887 Mon Sep 17 00:00:00 2001 From: "Niels Erik G. Nielsen" Date: Thu, 6 Jun 2013 13:14:49 -0400 Subject: [PATCH] Javadoc --- .../com/indexdata/mkjsf/config/package-info.java | 97 ++++++++++++++++++++ .../com/indexdata/mkjsf/pazpar2/Pz2Service.java | 6 +- 2 files changed, 100 insertions(+), 3 deletions(-) create mode 100644 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 index 0000000..a131afc --- /dev/null +++ b/src/main/java/com/indexdata/mkjsf/config/package-info.java @@ -0,0 +1,97 @@ +/** + * The library comes with two alternative mechanisms for configuration of an application, but it is + * possible to apply a custom scheme too or not use the configurations at all. + *

The library does require that a configuration scheme is chosen - in beans.xml as described below.

+ *

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

+ * + *

The built-in configuration schemes are:

+ * + * + *

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:

+ * + * 
+ * <beans xmlns="http://java.sun.com/xml/ns/javaee"
+ *         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ *         xsi:schemaLocation="
+ *     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>
+ *        <!-- Options                      Mk2ConfigReader     -->
+ *        <!--                              WebXmlConfigReader  -->        
+ *     </alternatives>          
+ * </beans>
+ *
+ * + *

For the web.xml configuration scheme (choosing WebXmlConfigReader in beans.xml) + * to pre-define the URL of the Pazpar2 to use, the configuration could be:

+ * + * 
+ *  <context-param>
+ *   <param-name>PAZPAR2_URL</param-name>
+ *   <param-value>http://localhost:8004/</param-value>
+ *  </context-param>
+ *
+ * + *

For the Mk2ConfigReader scheme to work, the web.xml must then contain pointers to the configuration directory + * and properties file. + * 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.

+ * 
+ * <context-param>
+ *  <param-name>MASTERKEY_ROOT_CONFIG_DIR</param-name>
+ *  <param-value>war://testconfig</param-value>
+ * </context-param>
+ * <context-param>
+ *  <description>
+ *   The sub directory to hold config file(s) for this Masterkey component.
+ *  </description>
+ *  <param-name>MASTERKEY_COMPONENT_CONFIG_DIR</param-name>
+ *  <param-value>/jsfdemo</param-value>
+ * </context-param>
+ * <context-param>
+ *  <param-name>MASTERKEY_CONFIG_FILE_NAME</param-name>
+ *  <param-value>jsfdemo.properties</param-value>
+ * </context-param>
+ * <context-param>
+ *  <description>
+ *   Defines the lifespan of configuration parameters as retrieved
+ *   from the file pointed to by MASTERKEY_CONFIG_FILE_NAME.
+ *   Can be SERVLET (cached) or REQUEST (read for every request).
+ *   Will default to SERVLET.
+ *  </description>
+ *  <param-name>MASTERKEY_CONFIG_LIFE_TIME</param-name>
+ *  <param-value>REQUEST</param-value>
+ * </context-param>
+ *
+ * + *

The jsfdemo.properties file might look like this for running against a + * local Pazpar2 service:

+ * + * pz2client.PAZPAR2_URL = http://localhost:8004/ + * + *

Some of the other know parameters in this format could be:

+ * + * 
+ * service.TYPE = SP              
+ * proxyclient.SERVICE_PROXY_URL = http://localhost:8080/service-proxy/
+ *
+ * + *

It's possible to implement a custom configuration scheme by either ignoring whatever scheme is + * injected and then applying the required values otherwise, OR by extending the ConfigurationReader + * and inject that class in beans.xml instead of any of the two predefined options. The extended + * class must construct a Configuration object -- which is basically a set of key-value pairs -- + * and then set the desired values and hand it off to the Configurable (currently Pz2Service, Pz2Client, + * ServiceProxyClient

+ * + *

Finally it's possible to set the URL runtime even from the UI pages.

+ * + */ +package com.indexdata.mkjsf.config; \ No newline at end of file diff --git a/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java b/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java index fea4a44..efbcfe3 100644 --- a/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java +++ b/src/main/java/com/indexdata/mkjsf/pazpar2/Pz2Service.java @@ -45,9 +45,9 @@ import com.indexdata.mkjsf.utils.Utils; * transparent to the UI that they are retrieved through this object. *

*

- * Pz2Service is exposed to the UI as 'pz2'. However, if the service is pre-configured, - * the Faces pages might never need to reference 'pz2' explicitly. Indirectly they UI will, - * though, if the polling mechanism in the tag <pz2utils:pz2watch> is used. + * Pz2Service is exposed to the UI as pz2. However, if the service is pre-configured, + * the Faces pages might never need to reference pz2 explicitly. Indirectly they will, + * though, if the polling mechanism in the tag <pz2utils:pz2watch> is used. * * **/ -- 1.7.10.4