6953 mpconfig context param

doc/release-notes/6953-dev-jsf-settings.md

@@ -0,0 +1,4 @@
+### Dynamic Java Server Faces Configuration Options
+
+This release includes a new way to easily change JSF settings via MicroProfile Config, especially useful during development.
+See the [development guide on "Debugging"](https://guides.dataverse.org/en/latest/developers/debugging.html).

doc/sphinx-guides/source/developers/debugging.rst

@@ -10,6 +10,60 @@ Logging
 
 By default, the app server logs at the "INFO" level but logging can be increased to "FINE" on the fly with (for example) ``./asadmin set-log-levels edu.harvard.iq.dataverse.api.Datasets=FINE``. Running ``./asadmin list-log-levels`` will show the current logging levels.
 
+.. _jsf-config:
+
+Java Server Faces (JSF) Configuration Options
+---------------------------------------------
+
+Some JSF options can be easily changed via MicroProfile Config (using environment variables, system properties, etc.)
+during development without recompiling. Changing the options will require at least a redeployment, obviously depending
+how you get these options in. (Variable substitution only happens during deployment and when using system properties
+or environment variables, you'll need to pass these into the domain, which usually will require an app server restart.)
+
+Please note that since Payara 5.2021.1 supporting MicroProfile Config 2.0, you can
+`use profiles <https://download.eclipse.org/microprofile/microprofile-config-2.0/microprofile-config-spec-2.0.html#configprofile>`_
+to maintain your settings more easily for different environments.
+
+.. list-table::
+ :widths: 15 15 60 10
+ :header-rows: 1
+ :align: left
+
+ * - JSF Option
+ - MPCONFIG Key
+ - Description
+ - Default
+ * - javax.faces.PROJECT_STAGE
+ - dataverse.jsf.project-stage
+ - Switch to different levels to make JSF more verbose, disable caches etc.
+ Read more `at <https://www.ibm.com/support/pages/changes-xhtml-and-java-sources-jsf-20-web-project-not-refreshed-publish-was-v8-server>`_
+ `various <https://docs.oracle.com/javaee/6/tutorial/doc/bnaxj.html#giqxl>`_ `places <https://javaee.github.io/tutorial/jsf-facelets003.html>`_.
+ - ``Production``
+ * - javax.faces.INTERPRET_EMPTY
+ _STRING_SUBMITTED_VALUES_AS_NULL
+ - dataverse.jsf.empty-string-null
+ - See `Jakarta Server Faces 3.0 Spec`_
+ - ``true``
+ * - javax.faces.FACELETS_SKIP_COMMENTS
+ - dataverse.jsf.skip-comments
+ - See `Jakarta Server Faces 3.0 Spec`_
+ - ``true``
+ * - javax.faces.FACELETS_BUFFER_SIZE
+ - dataverse.jsf.buffer-size
+ - See `Jakarta Server Faces 3.0 Spec`_
+ - ``102400`` (100 KB)
+ * - javax.faces.FACELETS_REFRESH_PERIOD
+ - dataverse.jsf.refresh-period
+ - See `Jakarta Server Faces 3.0 Spec`_
+ - ``-1``
+ * - primefaces.THEME
+ - dataverse.jsf.primefaces.theme
+ - See `PrimeFaces Configuration Docs`_
+ - ``bootstrap``
+
+.. _Jakarta Server Faces 3.0 Spec: https://jakarta.ee/specifications/faces/3.0/jakarta-faces-3.0.html#a6088
+.. _PrimeFaces Configuration Docs: https://primefaces.github.io/primefaces/8_0/#/gettingstarted/configuration
+
 ----
 
 Previous: :doc:`documentation` | Next: :doc:`coding-style`

doc/sphinx-guides/source/developers/dev-environment.rst

@@ -192,6 +192,17 @@ Run the following command:
 
 This will disable DOI registration by using a fake (in-code) DOI provider. Please note that this feature is only available in Dataverse Software 4.10+ and that at present, the UI will give no indication that the DOIs thus minted are fake.
 
+Configure Your Development Environment for GUI Edits
+----------------------------------------------------
+
+Out of the box, a JSF setting is configured for production use and prevents edits to the GUI (xhtml files) from being visible unless you do a full deployment.
+
+It is recommended that you run the following command so that simply saving the xhtml file in Netbeans is enough for the change to show up.
+
+``asadmin create-system-properties "dataverse.jsf.refresh-period=1"``
+
+For more on JSF settings like this, see :ref:`jsf-config`.
+
 Next Steps
 ----------
 

scripts/dev/dev-rebuild.sh

@@ -57,6 +57,10 @@ psql -U $DB_USER $DB_NAME -f doc/sphinx-guides/source/_static/util/createsequenc
 
 echo "Setting DOI provider to \"FAKE\"..." 
 curl http://localhost:8080/api/admin/settings/:DoiProvider -X PUT -d FAKE
+
+echo "Allowing GUI edits to be visible without redeploy..."
+$PAYARA_DIR/glassfish/bin/asadmin create-system-properties "dataverse.jsf.refresh-period=1"
+
 export API_TOKEN=`cat /tmp/setup-all.sh.out | grep apiToken| jq .data.apiToken | tr -d \"`
 
 echo "Publishing root dataverse..."

src/main/resources/META-INF/microprofile-config.properties

@@ -1,3 +1,4 @@
+# DATABASE
 dataverse.db.host=localhost
 dataverse.db.port=5432
 dataverse.db.user=dataverse

src/main/webapp/WEB-INF/web.xml

@@ -22,16 +22,19 @@
  <param-name>org.jboss.weld.context.conversation.lazy</param-name>
  <param-value>false</param-value>
  </context-param>
- <!-- UI warnings that can be enabled setting to Develop or another level. 
- See https://docs.oracle.com/javaee/6/tutorial/doc/bnaxj.html#giqxl -->
+ <!--
+ The following parameters can be changed quickly using MicroProfile Config API.
+ See also dev guide: https://guides.dataverse.org/en/latest/developers/debugging.html
+ -->
  <context-param>
  <param-name>javax.faces.PROJECT_STAGE</param-name>
-<!--  <param-value>Development</param-value>-->
- <param-value>Production</param-value>
+ <!-- Uses Microprofile Config to replace at runtime. Not standardized, Payara App Server specific. -->
+ <param-value>${MPCONFIG=dataverse.jsf.project-stage:Production}</param-value>
  </context-param>
  <context-param>
  <param-name>primefaces.THEME</param-name>
- <param-value>bootstrap</param-value>
+ <!-- Uses Microprofile Config to replace at runtime. Not standardized, Payara App Server specific. -->
+ <param-value>${MPCONFIG=dataverse.jsf.primefaces.theme:bootstrap}</param-value>
  </context-param>
  <!-- example of a hard-coded PrimePush configuration: -->
  <!-- context-param -->
@@ -42,19 +45,23 @@
  <param-name>
  javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL
  </param-name>
- <param-value>true</param-value>
+ <!-- Uses Microprofile Config to replace at runtime. Not standardized, Payara App Server specific. -->
+ <param-value>${MPCONFIG=dataverse.jsf.empty-string-null:true}</param-value>
  </context-param>
  <context-param>
  <param-name>javax.faces.FACELETS_SKIP_COMMENTS</param-name>
- <param-value>true</param-value>
+ <!-- Uses Microprofile Config to replace at runtime. Not standardized, Payara App Server specific. -->
+ <param-value>${MPCONFIG=dataverse.jsf.skip-comments:true}</param-value>
  </context-param>
  <context-param>
  <param-name>javax.faces.FACELETS_BUFFER_SIZE</param-name>
- <param-value>102400</param-value>
+ <!-- Uses Microprofile Config to replace at runtime. Not standardized, Payara App Server specific. -->
+ <param-value>${MPCONFIG=dataverse.jsf.buffer-size:102400}</param-value>
  </context-param>
  <context-param>
  <param-name>javax.faces.FACELETS_REFRESH_PERIOD</param-name>
- <param-value>-1</param-value>
+ <!-- Uses Microprofile Config to replace at runtime. Not standardized, Payara App Server specific. -->
+ <param-value>${MPCONFIG=dataverse.jsf.refresh-period:-1}</param-value>
  </context-param>
  <!-- JSF mapping -->
  <filter>