Revised: 20040817

The purpose of this release is to provide a reference implementation of the JavaServer Faces framework.

This FCS release of JavaServer Faces technology provides a final version of the JSF technology which was developed under the Java Community Process(SM) ("JCP(SM)") as JSR127.

 Contents

• Supported Operating Systems
• Required Software
• What This Release Includes
• What's New in This Release
• Migrating from 1.0 to 1.1
• Logging Support And Configuration Steps
  
• Known Issues

Supported Operating Systems

• Solaris 8
• Solaris 9
• Windows 2000
• Windows XP
• GNU/Linux (Red Hat 7.2)

Required Software

What This Release Includes

 
• html_basic.tld: A JSP custom tag library for building JavaServer Faces applications that render to an HTML client.
• jsf_core.tld: A JSP custom tag library for representing core actions independent of a particular RenderKit.
• An API and reference implementation that provide user interface components, model object management, pluggable rendering, server side validation, data conversion, event processing, page flow management, and custom extensibility for all of these things.
• A set of demos in the samples directory. Please note that these demos are provided as a proof-of-concept rather than a best-practices guide for writing JavaServer Faces applications.

What's New in This Release

• In order to reduce the number of bytes sent to the client in the state saving client mode, state can be optionally compressed before it is encoded and written as a hidden field. This is turned on by default.  You can turn off this feature by setting the ServletContext  Init Parameter "com.sun.faces.COMPRESS_STATE"  to false in your web deployment descriptor (web.xml) file.

• Removed explicit casts and dependencies to ServletContext.  Important for Portlet environments.

• Configuration system correctly recognizes application default locale.

• Fixed client state saving bug where components were not rendered on postback for jsp pages containing verbatim tags.  This was due to an "allignment" problem between state saving and restoration (client mode).

• Fixed bug where SelectManyCheckboxListRenderer  was rendering a "border" attribute as part of the HTML "input" element.  "border" is not a valid HTML attribute of "input" element.

• Fixed bug where OutputMessageRenderer  was not rendering the "id" attribute as part of the HTML "span" element.

• Fixed bug where RadioRenderer  was rendering a "border" attribute as part of the HTML "input" element.  "border" is not a valid HTML attribute of "input" element.

• Performance Enhancements:
• Improved the rendering performance of large DataTable(s) by replacing String concatenation mechanism with a nested HashMap data structure in RenderKitImpl.

•  Avoid synchronization issues by loading UIComponentBase  property descriptor information in the constructor which guarantees readonly access.  To further optimize look up, the saved map of descriptors is keyed by "name" instead of array of property descriptors.

• Improved the performance of checking whether a component's rendering should be suppressed in UIComponentTag.

• Improved the performance of configuration file processing by parsing one merged configuration file (merged from standard-html-renderkit.xml and jsf-ri-config.xml).
  

• Fixed bug where an exception would be thrown if you had a managed bean property referencing a non managed bean.  ManageBeanFactory  threw an exception because it didn't know the scope of the referenced non managed bean.

• Fixed bug where managed bean Map (and List) properties (that were were not created, but retrieved) were being set.

• Fixed bug where MenuRenderer  generated non-compliant XHTML.

• Fixed bug where HtmlSelectManyCheckbox  and HtmlSelectOneRadio  handled the "style" attribute incorrectly.

• Fixed server side state saving to support failover. Instead of saving the view in session (since the UIComponent instances are not serializable), the SerializedView (result of calling getTreeStructureToSave() and getTreeStateToSave()) is saved  in the session.  This can be enabled by using the ServletContext  Init Parameter "com.sun.faces.enableHigh Availability"

• Removed component id from error messages.

• Fixed bug where command link components across multiple forms was not working.

• Removed erroneous "back slash" characters from messages files.

• Fixed bug where "required=true" was not working for UISelectOne component.

• Fixed bug where DateTimeConverter  was not properly throwing an "IllegalArgumentException".
  

• JDK 1.3 compatability changes.
  

Migrating From 1.1 to 1.1_01

This implementation is 100% compatible with the 1.1 implementation, but many bugs have been fixed. If your application dependend on one of these bugs, it will need to be changed. Please see the What's New In this Release section.

Logging Support And Configuration Steps

1. If you are using Tomcat or JWSDP as your container, you can set the following property to tell the container what logging implementation you are using as well as the location of your logging configuration file.  Set   CATALINA_OPTS=-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Jdk14Logger -Djava.util.logging.config.file=D:\Files_2k\j2sdk1.4.1_03\jre\lib\jsf-log.properties
2.  We have shown a sample logging configuration file below that is configured to get logging output when you are running a JavaServer Faces application.  The default JDK 1.4 logging configuration file is  "$JAVA_HOME}/jre/lib/logging.properties". You can either manipulate that as per directions below, in which case it's global to all Java apps that you run or you can create a jsf.log properties as illustrated below. You can change the "java.util.logging.FileHandler.pattern" property to control where your logging information is written.
   

Known Issues With This Release

• You can add a "title" attribute to <h:message*>  but it won't appear. "title" gets rendered with the value of the "summary" attribute.  Refer to the standard renderer docs for more information. "title" will be deprecated from the list of supported attributes for <h:message*> in the 1.2 release.

• The standard renderer docs need to be clarified with regards to the rendering of the "span" element. The "span" element should be rendered if any pass through attributes are present (not just "style" and "styleClass").

• The standard renderer docs specify "accesskey" as an attribute of the "select" family of components, which is not in accordance with the HTML specification.  "accesskey" will be deprecated from the "select" family of components in the next release.

• If your page includes <h:outputLabel> components that occur before the components they label, both the label and the form must reside within the same <h:form>.

• Content is not ordered as expected when mixing template text with JSF tags. For example this jsp code:

  <h:commandLink action="foo"> Not the link text. </h:commandLink>

  outputs the string Not the link text. before the link. The workaround for this is to enclose the nested text in an <f:verbatim> tag, like this:

  <h:commandLink action="foo"> <f:verbatim>Not the link text.</f:verbatim> </h:commandLink>

• Do not enclose JavaServer Faces component tags inside of iterating JSP tags, such as JSTL's <c:forEach> tag. The primary reason for this restriction is that Faces cannot know how many times the loop will execute and therefore the number of components placed in the tree by this tag is undetermined. This breaks the entire id to component matching scheme required by UIComponentTag to match tags to UIComponent instances.

• The Map returned by the UIComponent.getAttributes() method implements get() so that if you ask for a key that is implemented as a property, you get the property value. However, if you call iterator() on the Map, you will get an Iterator that iterates over the "real" attributes only, not the properties.

• the value of javax.faces.component.NamingContainer.SEPARATOR_CHAR is ':'. This means that the client id for components will be something like "form:checkbox1". The use of the ':' character in the id causes problems for CSS stylesheets that try to apply style to components using their id. The workaround is to use the CSS "class" concept to apply style to a component.

• When saving state on the server, there is no way for the server to know that a view has expired. Thus, if the JSP page changes between requests, it's possible there will be inconsistencies between the restored tree and the JSP page. Therefore, if you change the JSP page, you need to re-start the browser so that the session is lost.

  In related news, the number of views saved in the session when the application is configured to save state in the server is configurable by the RI init context parameter "com.sun.faces.NUMBER_OF_VIEWS_IN_SESSION" without quotes. This is a non-standard feature, so don't count on it.

• Don't use the '.' character in ResourceBundle keys for use in Faces. This character is a reserved character in the JSF EL.

• When deploying on a non-JWSDP container, you must include all the dependent jars in your webapp's WEB-INF/lib directory. It's possible it may work without doing this, but this is not a supported configuration.

• If you're using a SunOne Application Server 7.x, Tomcat 4 series container, or any container that strictly conforms to JSP 1.2, Servlet 2.3, you must use JSTL 1.0 instead of JSTL 1.1.

• There is a known issue in S1AS 7.x, Tomcat 4.x, and Tomcat 5.x where security constraints are applied to welcome files. The bug number for this S1AS 7.x issue is #5004853.

  This bug is problematic for the jsf-cardemo application since the security constraint is applied to the index.jsp welcome file. Since this container applies the security constraint to the welcome file, the container displays an error page when an attempt to access the application is made. On older versions of S1AS 7.x that error code is incorrectly reported as 500. This has since been fixed to be the correct number 403.

  To get around this problem either:

  • Access the initial CarDemo page directly:
    http://<SERVER>:<PORT>/jsf-cardemo/chooseLocale.faces
  • Modify the security constraint in the web.xml welcome file to exclude the index.jsp page.

  The Java Systems Application Server 8.0 and JWSDP 1.3 do not have this problem and properly exclude welcome files from the security constraints.

• The Non-JSP demo does not deploy under tomcat 4.1.29.
  

• Some versions of some web containers, such as Resin and Oracle App Server, don't follow the Servlet 2.3 Spec rule of calling ServletContextListeners listeners defined in tld files in the META-INF directory of a jar. Running a faces webapp in such a container requires you to manually declare the ServletContextListener. The listener-class you need to specify is com.sun.faces.config.ConfigureListener

• If you're using component bindings pointing to beans stored in session scope with values initialized from the JSP page, you may run into some difficulties in the "edit-compile-debug" cycle.

  Consider this JSP fragment:

  <h:commandButton binding="#{backingBean.button1}" value="press me" />

  Let's say that "backingBean" is stored in session scope. The first time the browser views this page, backingBean gets instantiated, and initialized with the value "press me". Now, let's say the web-app is being authored in place, on the web container. In other words, any changes made to the JSP are seen "live" on the server. If you change the JSP to alter the value of the button to be different, say like this:

  <h:commandButton binding="#{backingBean.button1}" value="click me" />

  and save the page, then re-load the page in the browser, you'll see that the button still shows up with the old label, "press me". This is because the spec is designed to only initialize the backing bean with a value the first time the page is loaded, and the bean is still sitting in the session with the old value. There are several workarounds to this problem.

  1. use "request" or "none" scope for your backing bean

  2. use java code to push the value into the bean, rather than JSP

  3. ask the user to re-start their browser after modifying the JSP page.

  4. find a way to invalidate the session when the JSP page has changed.

• When installing newer versions of JSF sample applications be sure to clear your client cache as well as your web container's cached files. You may run into consistency problems if you do not clear out the cached files.
  

Copyright © 2004 Sun Microsystems, Inc., 4150 Network Circle, Santa
Clara, California 95054, U.S.A. All rights reserved.

Sun Microsystems, Inc. has intellectual property rights relating to
technology embodied in this product. In particular, and without
limitation, these intellectual property rights may include one or more
of the U.S. patents listed at http://www.sun.com/patents and one or more
additional patents or pending patent applications in the U.S. and other
countries.

This product is distributed under licenses restricting its use, copying
distribution, and decompilation. No part of this product may be
reproduced in any form by any means without prior written authorization
of Sun and its licensors, if any.

Third-party software, including font technology, is copyrighted and
licensed from Sun suppliers.

Sun, Sun Microsystems, the Sun logo, the Java Coffee Cup logo,
JavaServer, and Java are trademarks or registered trademarks of Sun
Microsystems, Inc. in the U.S. and other countries.

Federal Acquisitions: Commercial Software - Government Users Subject to
Standard License Terms and Conditions.

Copyright © 2004 Sun Microsystems, Inc., 4150 Network Circle,
Santa Clara, California 95054, Etats-Unis. Tous droits réservés.

Sun Microsystems, Inc. a les droits de propriété intellectuels relatants
à la technologie incorporée dans ce produit. En particulier, et sans la
limitation, ces droits de propriété intellectuels peuvent inclure un ou
plus des brevets américains énumérés à http://www.sun.com/patents et un
ou les brevets plus supplémentaires ou les applications de brevet en
attente dans les Etats - Unis et les autres pays.

Ce produit ou document est protégé par un copyright et distribué avec
des licences qui en restreignent l'utilisation, la copie, la
distribution, et la décompilation. Aucune partie de ce produit ou
document ne peut être reproduite sous aucune forme, par quelque moyen
que ce soit, sans l'autorisation préalable et écrite de Sun et de ses
bailleurs de licence, s'il y ena.

Le logiciel détenu par des tiers, et qui comprend la technologie
relative aux polices de caractères, est protégé par un copyright et
licencié par des fournisseurs de Sun.

Sun, Sun Microsystems, le logo Sun, le logo Java Coffee Cup, JavaServer,
et Java sont des marques de fabrique ou des marques déposées de Sun
Microsystems, Inc. aux Etats-Unis et dans d'autres pays.