2 * The library comes with two alternative mechanisms for configuration of an application, but it is
\r
3 * possible to apply a custom scheme too or not use the configurations at all.
\r
4 * <p>The library does require that a configuration scheme is chosen - in beans.xml as described below.</p>
\r
5 * <p>But the library does NOT impose any mandatory parameters in order to start up (except for those required for
\r
6 * bootstrapping the configuration). The library <i>does</i> know of certain parameters, if it encounters them.
\r
8 * <p>Following classes can be configured: Pz2Service (controller), Pz2Client, and ServiceProxyClient. Some currently
\r
9 * acknowledged parameters are TYPE (service type) PAZPAR2_URL, SERVICE_ID, and SERVICE_PROXY_URL</p>
\r
11 * <h3>Selecting a configuration scheme</h3>
\r
13 * <p>The built-in configuration schemes are:</p>
\r
15 * <li>Configuration by context parameters in web.xml, this is the simple though less flexible choice</li>
\r
16 * <li>The configuration scheme Index Data uses for other MasterKey applications, Mk2Config, this is the more versatile option</li>
\r
19 * <p>It must be determined deploy-time what configuration scheme to use, by selecting the preferred
\r
20 * mechanism in the application's beans.xml. In this example the MasterKey configuration scheme is injected:</p>
\r
23 * <beans xmlns="http://java.sun.com/xml/ns/javaee"
\r
24 * xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
\r
25 * xsi:schemaLocation="
\r
26 * http://java.sun.com/xml/ns/javaee
\r
27 * http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
\r
28 * <alternatives>
\r
29 * <class>com.indexdata.mkjsf.config.WebXmlConfigReader</class>
\r
30 * <!-- Options Mk2ConfigReader -->
\r
31 * <!-- WebXmlConfigReader -->
\r
32 * </alternatives>
\r
36 * 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
37 * 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
38 * meaning it would have to be re-applied with every update of new versions of mkjsf.
\r
40 * <h3>Configuring the service using web.xml only</h3>
\r
42 * <p>For the web.xml configuration scheme (choosing WebXmlConfigReader in beans.xml)
\r
43 * to pre-define the URL of the Pazpar2 to use and choose Pazpar2 as the selected
\r
44 * service type, the configuration could be:</p>
\r
47 * <context-param>
\r
48 * <param-name>PAZPAR2_URL</param-name>
\r
49 * <param-value>http://localhost:8004/</param-value>
\r
50 * </context-param>
\r
51 * <context-param>
\r
52 * <description>Service type. Possible values: SP, PZ2, TBD</description>
\r
53 * <param-name>TYPE</param-name>
\r
54 * <param-value>PZ2</param-value>
\r
55 * </context-param>
\r
58 * <h3>Configuring the service using 'Mk2Config' scheme</h3>
\r
60 * <p>The Mk2ConfigReader scheme allows the configuration to exist outside of the web application archive.
\r
61 * It supports name spaces for different parts of the application (as opposed to the web.xml scheme) and it
\r
62 * supports different configurations for different virtual hosts using the same web application deployment.</p>
\r
63 * <p>For the Mk2ConfigReader scheme to work, the web.xml must contain pointers to the configuration directory
\r
64 * and properties file. The specific configuration itself would be in those files then.
\r
65 * In this example the configuration directory is in the web application itself (war://testconfig). Usually it
\r
66 * would probably be somewhere else in your file system.</p>
\r
68 * <context-param>
\r
69 * <param-name>MASTERKEY_ROOT_CONFIG_DIR</param-name>
\r
70 * <param-value>war://testconfig</param-value>
\r
71 * </context-param>
\r
72 * <context-param>
\r
73 * <description>
\r
74 * The sub directory to hold config file(s) for this Masterkey component.
\r
75 * </description>
\r
76 * <param-name>MASTERKEY_COMPONENT_CONFIG_DIR</param-name>
\r
77 * <param-value>/jsfdemo</param-value>
\r
78 * </context-param>
\r
79 * <context-param>
\r
80 * <param-name>MASTERKEY_CONFIG_FILE_NAME</param-name>
\r
81 * <param-value>jsfdemo.properties</param-value>
\r
82 * </context-param>
\r
83 * <context-param>
\r
84 * <description>
\r
85 * Defines the lifespan of configuration parameters as retrieved
\r
86 * from the file pointed to by MASTERKEY_CONFIG_FILE_NAME.
\r
87 * Can be SERVLET (cached) or REQUEST (read for every request).
\r
88 * Will default to SERVLET.
\r
89 * </description>
\r
90 * <param-name>MASTERKEY_CONFIG_LIFE_TIME</param-name>
\r
91 * <param-value>REQUEST</param-value>
\r
92 * </context-param>
\r
95 * <p>The jsfdemo.properties file might look like this for running against a
\r
96 * local Pazpar2 service:</p>
\r
98 * <code>pz2client.PAZPAR2_URL = http://localhost:8004/</code>
\r
100 * <p>Some of the other known parameters in this format could be:</p>
\r
103 * service.TYPE = SP
\r
104 * proxyclient.SERVICE_PROXY_URL = http://localhost:8080/service-proxy/
\r
107 * <p>It's possible to implement a custom configuration scheme by either ignoring whatever scheme is
\r
108 * injected and then applying the required values otherwise, OR by extending the ConfigurationReader
\r
109 * and inject that class in beans.xml instead of any of the two predefined options. The extended
\r
110 * class must construct a Configuration object -- which is basically a set of key-value pairs --
\r
111 * and then set the desired values and hand it off to the Configurable (currently Pz2Service, Pz2Client,
\r
112 * and ServiceProxyClient)</p>
\r
114 * <p>It would also be easy enough to simply set the URL runtime from the UI pages, using methods on
\r
115 * Pz2Service (named 'pz2').</p>
\r
118 package com.indexdata.mkjsf.config;
projects / mkjsf-moved-to-github.git / blob