Configuring ADF Faces for development

This post will describe how to configure your ADF Faces project for development through web.xml context parameters as well as enabling debug mode in trinidad-config.xml. It will also show how to override these settings for production deployment with a deployment plan even though the setting in trinidad-config.xml cannot be altered directly with a deployment plan.

More background information on all ADF Faces configuration parameters can be found in the appendix of the Web User Interface Developer's Guide. The ones we want to change during development are:

• org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION to true to check for source files being modified on disk while the application is running and reloading them. Be sure to clear your browser cache after changing this value to clear out any old cached versions.
• org.apache.myfaces.trinidad.resource.DEBUG to true to enable resource debugging and prevent the client from caching resources (eg javascript libraries, images, CSS, etc)
• org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION to true to disable CSS content compression and use human-readable CSS class names for skinning
• org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT to true to non-obfuscated javascript
• oracle.adf.view.rich.LOGGER_LEVEL to FINE to enable client side javascript logging. Other allowed values are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, and ALL
• oracle.adf.view.rich.ASSERT_ENABLED to true to enable client-side javascript assertions

All you have to do is copy and paste the context parameters below and add them to your WEB-INF/web.xml file:

  <context-param>
    <description>If this parameter is true, there will be an automatic check
                 of the modification date of your JSPs, and saved state will
                 be discarded when JSP's change. It will also automatically
                 check if your skinning css files have changed without you
                 having to restart the server.</description>
    <param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
    <param-value>true</param-value>
  </context-param>
  <context-param>
    <description>Set to true to have ADF Faces set HTTP response headers to
                 let the browser know that resource (such as javascript
                 files, images, and CSS) should not be cached</description>
    <param-name>org.apache.myfaces.trinidad.resource.DEBUG</param-name>
    <param-value>true</param-value>
  </context-param>
  <context-param>
    <description>Set to true to disable compression of CSS class names for
                 skinning keys and have more human readable class
                 names</description>
    <param-name>org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION</param-name>
    <param-value>true</param-value>
  </context-param>
  <context-param>
    <description>Set to true to disable obfuscation and compaction of ADF
                 javascript that also removes comments and
                 whitespace.</description>
    <param-name>org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT</param-name>
    <param-value>true</param-value>
  </context-param>
  <context-param>
    <description>Set the level of client side javascipt logging. Default is
                 OFF, other allowed values are SEVERE,WARNING,INFO,CONFIG,
                 FINE,FINER,FINEST, and ALL</description>
    <param-name>oracle.adf.view.rich.LOGGER_LEVEL</param-name>
    <param-value>FINER</param-value>
  </context-param>
  <context-param>
    <description>Set to true to enable assertions in client side 
                 javascript. This is frequently used to assert valid
                 argument types to JS methods</description>
    <param-name>oracle.adf.view.rich.ASSERT_ENABLED</param-name>
    <param-value>true</param-value>
  </context-param>

Most of these parameter have a performance impact and should not be enabled on production environments, or user acceptance and performance testing environments. This can be achieved using deployment plans. These can make changes to deployment descriptors during deployment and the WEB-INF/web.xml file is one of these deployment descriptors. Simple save the file below as plan-nodev.xml and use it during deployment to override these settings. You do need to change the application-name and module-name elements to match your application.

If you read the deployment plan you can see it defines two variables: developMode and adfJavascriptLoggerLevel that are used in the overrides to make changes to the WEB-INF/web.xml file. I opted to use a single developMode variable to change all booleans to false. You could also create individual variables for each parameter and change the override to use these separate variables. That would give you individual control over each parameter. Without further ado here is the deployment plan:

<?xml version='1.0' encoding='UTF-8'?>
<deployment-plan xmlns="http://xmlns.oracle.com/weblogic/deployment-plan" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://xmlns.oracle.com/weblogic/deployment-plan http://xmlns.oracle.com/weblogic/deployment-plan/1.0/deployment-plan.xsd"
                 global-variables="false">
  <application-name>DeploySample.ear</application-name>
  <variable-definition>
    <variable>
      <name>developMode</name>
      <value>false</value>
    </variable>
    <variable>
      <name>adfJavascriptLoggerLevel</name>
      <value>NONE</value>
    </variable>
  </variable-definition>
  <module-override>
    <module-name>DeploySample.war</module-name>
    <module-type>war</module-type>
    <module-descriptor external="false">
      <root-element>web-app</root-element>
      <uri>WEB-INF/web.xml</uri>
      <variable-assignment>
        <name>developMode</name>
        <xpath>/web-app/context-param/[param-name="org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT"]/param-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
      <variable-assignment>
        <name>developMode</name>
        <xpath>/web-app/context-param/[param-name="org.apache.myfaces.trinidad.resource.DEBUG"]/param-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
      <variable-assignment>
        <name>developMode</name>
        <xpath>/web-app/context-param/[param-name="oracle.adf.view.rich.ASSERT_ENABLED"]/param-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
      <variable-assignment>
        <name>developMode</name>
        <xpath>/web-app/context-param/[param-name="org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION"]/param-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
      <variable-assignment>
        <name>adfJavascriptLoggerLevel</name>
        <xpath>/web-app/context-param/[param-name="oracle.adf.view.rich.LOGGER_LEVEL"]/param-value</xpath>
        <operation>replace</operation>
      </variable-assignment>
    </module-descriptor>
  </module-override>
</deployment-plan>

In the intro I also promised to change a parameter in the WEB-INF/trinidad-config.xml file. You can set debug-output to true to get better human readable HTML. It will be properly indented and even have HTML comments before each component to show its full ID. This makes it much easier to look at the generated HTML or PPR responses. The problem with the WEB-INF/trinidad-config.xml file is that it is not an official JEE deployment descriptor so you cannot override its value in a deployment plan. But we most definitely don't want this debug mode in a production environment. Fortunately you can use EL expressions in this file and you can use those to refer to context parameters from the web.xml file. I have opted to simply look at the org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT parameter so we enable javascript debugging and HTML debug output with the same parameter. You could also create a separate context parameter to control this behavior. Here is the WEB-INF/trinidad-config.xml file with EL expression:

<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
  <skin-family>skyros</skin-family>
  <skin-version>v1</skin-version>
  <debug-output>#{initParam['org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT']}</debug-output>
</trinidad-config>

If, for whatever reason, the initParam expression doesn't work you can also try to use #{facesContext.externalContext.initParameterMap['org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT']}

I hope this helps you to setup your project for development while also having a proper production deployment without the need to change your sources or repackage your application.