/**\r
- * The library comes with two alternative mechanisms for configuration of an application, but it is\r
- * possible to apply a custom scheme too or not use the configurations at all.\r
- * <p>The library does require that a configuration scheme is chosen - in beans.xml as described below.</p>\r
- * <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
+ * The library comes with two alternative mechanisms for configuration of an application. It is\r
+ * possible, however, to apply a custom scheme or not to use configurations at all.\r
+ * <p>The library does require that a configuration scheme is chosen - in beans.xml as described below, but the library \r
+ * does NOT impose any mandatory parameters in order to initialize. The library <i>does</i> know of certain parameters, \r
+ * 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 (the controller), Pz2Client, and ServiceProxyClient. Some currently \r
+ * acknowledged parameters are TYPE (service type) PAZPAR2_URL, SERVICE_ID (see Pazpar2 documentation for an explanation of \r
+ * 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 albeit 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
* http://java.sun.com/xml/ns/javaee \r
* http://java.sun.com/xml/ns/javaee/beans_1_0.xsd"> \r
* <alternatives> \r
- * <class>com.indexdata.mkjsf.config.Mk2ConfigReader</class>\r
+ * <class>com.indexdata.mkjsf.config.WebXmlConfigReader</class>\r
* <!-- Options Mk2ConfigReader -->\r
* <!-- WebXmlConfigReader --> \r
* </alternatives> \r
* </beans>\r
* </pre>\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, the configuration could be:</p>\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>Using the web.xml configuration scheme (choosing WebXmlConfigReader in beans.xml)\r
+ * you can configure you application to use a locally installed Pazpar2 server like this:</p>\r
* \r
* <pre>\r
* <context-param>\r
* <param-name>PAZPAR2_URL</param-name>\r
* <param-value>http://localhost:8004/</param-value>\r
* </context-param>\r
+ * <context-param>\r
+ * <description>Service type. Possible values: SP, PZ2, TBD</description>\r
+ * <param-name>TYPE</param-name>\r
+ * <param-value>PZ2</param-value> \r
+ * </context-param>\r
* </pre>\r
* \r
- * <p>For the Mk2ConfigReader scheme to work, the web.xml must then contain pointers to the configuration directory \r
- * and properties file. \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
+ * Likewise you could configure your application to use our hosted Pazpar2 service with these settings:\r
+ *\r
+ * <pre>\r
+ * <context-param>\r
+ * <param-name>SERVICE_PROXY_URL</param-name>\r
+ * <param-value>http://mkc.indexdata.com:9009/service-proxy/</param-value>\r
+ * </context-param>\r
+ * <context-param>\r
+ * <description>Service type. Possible values: SP, PZ2, TBD</description>\r
+ * <param-name>TYPE</param-name>\r
+ * <param-value>SP</param-value> \r
+ * </context-param>\r
+ * </pre>\r
+ * \r
+ * \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). Usually it \r
+ * would probably be somewhere else in your file system.</p> \r
* <pre>\r
* <context-param>\r
* <param-name>MASTERKEY_ROOT_CONFIG_DIR</param-name>\r
* <p>The jsfdemo.properties file might look like this for running against a \r
* local Pazpar2 service:</p>\r
* \r
- * <code>pz2client.PAZPAR2_URL = http://localhost:8004/</code>\r
+ * <pre>\r
+ * service.TYPE = pz2\r
+ * pz2client.PAZPAR2_URL = http://localhost:8004/\r
+ * </pre>\r
* \r
* <p>Some of the other known parameters in this format could be:</p>\r
* \r
* 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
projects / mkjsf-moved-to-github.git / blobdiff