Example file

<?xml version="1.0"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
  <!-- Enable debug output -->
  <debug-output>true</debug-output>

  <!-- Pick accessibility options based on a per-user managed bean -->
  <accessibility-mode>#{user.accessibilityMode}</accessibility-mode>

  <!-- A silly use of EL: English users get one appearance, -->
  <!-- others get another -->
  <skin-family>
    #{view.locale.language=='en' ?  'minimal' : 'customSkin'}
  </skin-family>
</trinidad-config>

Definition of subelements

All trinidad-config.xml files must begin with an <trinidad-config> element in the http://myfaces.apache.org/trinidad/config XML namespace. The order of elements inside of <trinidad-config> doesn't matter.

  <!-- Enable both high-contrast and large-fonts content -->
  <accessibility-profile>high-contrast large-fonts</accessibility-profile>

     <h:outputLink value="#{requestContext.helpTopic.someTopicID}">
       <h:outputText value="Get Help"/>
     </h:outputLink>

org.apache.myfaces.trinidad.CACHE_VIEW_ROOT

Enables or disables UIViewRoot caching; defaults to true.

When "token" client-side state saving is enabled, Trinidad applies an additional optimization by caching an entire UIViewRoot tree with each token. (Care has been taken to ensure that this does not affect thread safety or session failover.) This is a major optimization for AJAX-intensive systems, as postbacks can be processed far more rapidly without the need to reinstantiate the UIViewRoot tree. However, it is known to interfere with some other JSF technologies. In particular, the Apache MyFaces Tomahawk saveState component does not work, and template text in Facelets may appear in duplicate. This optimization can be disabled by setting this context parameter to false.

org.apache.myfaces.trinidad.CLIENT_STATE_METHOD

Chooses the type of client-side state saving used when client-side state saving is enabled (with the JSF standard javax.faces.STATE_SAVING_METHOD parameter). Two values are accepted:

• "token": the default, which stores page state in the session, but persists a token to the client that lets Apache Trinidad disambiguate the same page appearing multiple times. Failover is supported.
• "all": stores all state in the client in a (potentially large) hidden form field. This matches the default behavior of the JSF reference implementation, and can be useful for developers avoiding any use of HttpSession.

org.apache.myfaces.trinidad.CLIENT_STATE_MAX_TOKENS

In "token"-based client-side state saving, chooses how many tokens should be preserved at any one time. The default value is 15. When this is exceeded, state will have effectively been "forgotten" for the least recently viewed pages, which can impact users that actively use the Back button or that have multiple windows open simultaneously. Developers building HTML applications that rely heavily on frames will likely need to increase this value.

org.apache.myfaces.trinidad.USE_APPLICATION_VIEW_CACHE

This configuration option enables an optimized strategy for caching some view state at an application level, which significantly improves scalability. However, it makes it harder to develop (updates to pages will not be noticed until the server is restarted), and in some rare cases cannot be used for some pages. See below for more information about this option.

org.apache.myfaces.trinidad.DEBUG_JAVASCRIPT

Apache Trinidad by default obfuscates the Javascript it delivers to the client, as well as stripping comments and whitespace. This dramatically reduces the size of our Javascript download, but also makes it tricky to debug the Javascript. This flag can be set to true to turn off the obfuscation.

org.apache.myfaces.trinidad.DISABLE_CONTENT_COMPRESSION

Apache Trinidad by default compresses the style class names inside the css that is generated on the server. However, when developing custom Trinidad skins, it is much easier to work with the non-compressed style class names, which much more directly relate to those used in the skin css file. This flag can be set to turn off automatic compression of style class names.

org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION

If this parameter is enabled by setting to "true", Apache Trinidad will automatically check the modification date of your JSPs and skinning CSS files, and discard saved state when they change; this makes development easier, but adds overhead that should be avoided when your application is deployed.

org.apache.myfaces.trinidad.ENABLE_LIGHTWEIGHT_DIALOGS

Trinidad supports two dialog implementations. The default implementation pops a new browser window, but may be subject to popup blocking issues depending on the browser. The alternative lightweight implementation uses a skinnable modal iframe that hovers over the existing page. This flag can be set to turn on lightweight dialogs.

File upload configuration

For options affecting Apache Trinidad support of file uploads, please see the Configuration section of the "Processing file uploads" document .

The Application View Cache

Apache Trinidad supports a special Application View Cache feature that can increase scalability significantly. However, it can, in some unusual cases, break an otherwise functioning application, so it is important to understand how it works to understand whether it can be enabled for your pages.

In conventional JSF state saving, a page's UI state is saved the same way every time it is used. It doesn't matter if state is being saved for an initial render of a page, or if state is being saved after a user has posted back to that page. No two postbacks are necessarily the same - the user may have entered entirely different data, navigated to a different set of rows in the table, etc. So, it is extremely difficult to share state among postback requests.

However, most of the time, all initial renders of any one page have exactly the same view state. It doesn't matter if the page is showing different data, or responding to different query parameters, and so forth, because in JSF those are conventionally accessed using the JSF expression language (EL). In JSF, what state saving remembers isn't the result of evaluating an EL expression - it's the EL expression itself. So, when you see:

  <tr:outputText value="#{mybean.value}"/>

The Application View Cache takes advantage of this, and caches the state for these initial renders at an application scope. Once the page has been viewed once, all users can reuse that same state coming and going, saving some CPU (the CPU cost of saving the state each time) and more importantly the memory overhead of keeping separate copies for each user. State saving for postback is still separated per user, but keep in mind that if the result of a postback is that you navigate to a new page, the Application View Cache is still in effect - it is only disabled when a postback remains on a page (for example, because of a validation failure).

Perhaps even more importantly, the Application View Cache enables the use of web Proxy Caches in front of your application server. Token-based client-side state saving defeats web proxy caches, because each user may have a different token for any one page, defeating cacheability. The Application View Cache uses the same token across all users.

All this should raise the question of why anyone would ever not use the Application View Cache. First, the technology currently does not invalidate itself if the page is modified; it requires a server restart. This makes it difficult to use during development. Beyond this, however, there are some JSF coding techniques that break the core assumption of the Application View Cache - the assumption that the initial view state of any one page is always the same, no matter who views it:

1. Conditional tags that may not evaluate identically for each user
2. JSF components that pull EL results into page state

The following JSP includes two potential examples of the first problem:

  <c:if test="${user.locale.language='en'}">
    <h:outputText value="You're in an English locale"/>
  </c:if>

  <tr:selectOneListbox value="#{someValue}">
    <tr:forEach var="item" items="#{model.listOfItems}">
      <tr:selectItem value="#{item.value}" text="#{item.text}"/>
    </tr:forEach>
  </tr:selectOneListbox>

    <h:outputText value="You're in an English locale"
                  rendered="#{user.locale.language == 'en'}"/>

  <tr:selectOneListbox value="#{someValue}">
    <f:selectItems value="#{model.listOfSelectItems}"/>
  </tr:selectOneListbox>

In addition to problems with non-JSF tags that manipulate the page, you can run into problems with some JSF tags that directly manipulate page state. A particular example of this is the MyFaces <x:save_state> tag. This tag will evaluate an EL expression and save it directly as part of the page's view state. This is very nice functionality, but it does directly and necessarily conflict with the technique of the Application View Cache.

At the moment, the Application View Cache can only be enabled or disabled globally. We are considering adding support for disabling (or enabling) the view cache on a page-by-page basis.

#{requestContext}

The EL expression #{requestContext} returns the RequestContext object itself.

#{requestContext.helpTopic['foo']}

The EL expression #{requestContext.helpTopic['foo']} returns an URL to the help topic "foo". Before using this, you must configure the <oracle-help-servlet-url> element in trinidad-config.xml.

#{requestContext.helpSystem['frontPage']}

The EL expression #{requestContext.helpSystem['frontPage']} returns an URL to the front page of the help system. Before using this, you must configure the <oracle-help-servlet-url> element in trinidad-config.xml. (Other subproperties of "helpSystem" may be added in the future.)

#{requestContext.colorPalette}

The EL expression #{requestContext.colorPalette} returns a Map of color palettes, each of which is an array of java.awt.Color objects. Palette names include:

• "web216": the 216 web-safe colors
• "default49": a 49 color palette, including a fully transparent entry
• "opaque49": a 49 color palette, without a transparent entry
• "default80": an 80 color palette

#{requestContext.formatter}

The EL expression #{requestContext.formatter} returns an object that can be used for applying message formatting. For example, the following EL expression:

    <h:outputText value="#{requestContext.formatter['One{0}Three']['Two']}"/>

OneTwoThree

#{requestContext.agent}

The EL expression #{requestContext.agent} returns an object that describes the client agent that is making the request and is to display the rendered output. The agent object describes the following,

• agent type: Possible values "desktop", "pda", "phone" and "unknown"
• agent name and version: Agent names include "ie", "gecko" (for all gecko based browsers including Mozilla, Firefox, and Netscape 6+ versions), "webkit" (for all webkit based browsers including safari), "netfront", "blazer"
• platform name and version: Platform names include "windows", "linux", "mac", "palm", "solaris", "ppc"
• (mobile) device make and model when available, and
• capabilities : Capability names include
  • "dom" : dom level support (possible values are "none", "level1", "level2")
  • "tables" : table layout support (possible values "basic", "advanced")
  • "frames" : frames support (boolean value, "true" or "false"
  • "iframes" : iframes support (boolean value, "true" or "false"
  • "width" and "height" : screen resolution of the (mobile) device (integer value)