This README documents the Sun's implementation of JSR 127, JavaServer (tm) Faces. Installation Notes ================== JavaServer (tm) Faces is intended to run in a Servlet 2.3, JSP 1.2 web container, such as that distributed with Java Web Services Developer Pack <http://java.sun.com/webservices/webservicespack.html>. Please follow the instructions for your container and have it working well in your environment before continuing with these installation notes. To use JavaServer (tm) Faces in your own webapp, you need to follow the online documentation at <http://java.sun.com/j2ee/javaserverfaces/>. Make sure to include all the jars in the lib directory of this distribution in your WEB-INF/lib directory in your webapp. Major changes/features in this release: ======================================= Here are the changes since the 1.1_01 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 off by default. You can turn this feature off by setting the ServletContext Init Paramter "com.sun.faces.COMPRESS_STATE" to false in your web deployment descriptor (web.xml) file. Sun RI changes * Several performance enhancements - Most of these involved improving synchornization usage * Improved several error messages to be more concise in order to help diagnose development issues * Corrected a specification compliance issue where the Application implementation didn't throw a required Exception. * Corrected an i18n problem when the default locale of the server was not english. * Support for 'all media' (*/*) content type * Corrected an exception in the implementation of ExternalContext.dispatch() when the target of the dispatch operation does not exist. * NumberConverter.getAsObject() will now properly handle currency symbol changes. * The ResponseStateManager implementation no longer swallows exceptions in the getTreeStructureToRestore() method. * Corrected a specification compliance issue where FacesContext.setViewRoot() failed to throw an exception if a null value was passed. * JSF will now work properly in a Portlet environment that renders Portlets in parallel. * Enhanced server side state saving to be more robust. - It handles back button and multi-frame applications much better than the previous release. - It now supports session failover by default. * Corrected several rendering issues. General Spec changes -- There were no spec changes for this release. Standard HTML RenderKit changes -- There were no Standard HTML RenderKit changes for this release. Spec document changes -- There were no specification document changes for this release. Logging support and configuration steps ======================================= JavaServer Faces Reference Implementation in this release leverages the Jakarta Commons logging API to provide logging functionality. We have followed the guidelines recommended by http://jakarta.apache.org/commons/logging/userguide.html. JavaServer Faces Reference Implementation can be configured to provide logging information using the steps below. step 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 step 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. Here's the jsf-log.properties ############################################################ # Default Logging Configuration File # http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html#1.2 # You can use a different file by specifying a filename # with the java.util.logging.config.file system property. # For example java -Djava.util.logging.config.file=myfile ############################################################ ############################################################ # Global properties ############################################################ # "handlers" specifies a comma separated list of log Handler # classes. These handlers will be installed during VM startup. # Note that these classes must be on the system classpath. # By default we only configure a ConsoleHandler, which will only # show messages at the INFO and above levels. # To also add the FileHandler, use the following line instead. handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler # Default global logging level. # This specifies which kinds of events are logged across # all loggers. For any given facility this global level # can be overriden by a facility specific level # Note that the ConsoleHandler also has a separate level # setting to limit messages printed to the console. #.level= INFO .level= INFO ############################################################ # Handler specific properties. # Describes specific configuration info for Handlers. ############################################################ # default file output is in user's home directory. java.util.logging.FileHandler.pattern = %h/java%u.log java.util.logging.FileHandler.limit = 50000 java.util.logging.FileHandler.count = 1 java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter # Limit the message that are printed on the console to INFO and above. java.util.logging.ConsoleHandler.level = INFO java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter ############################################################ # Facility specific properties. # Provides extra control for each logger. ############################################################ # For example, set the com.xyz.foo logger to only log SEVERE # messages: com.xyz.foo.level = SEVERE com.sun.faces.level = ALL If you use the ConsoleHandler ( which would direct all the output to catalina.out in the case of standalone Tomcat or launcher.server.log in the case of JWSDP ) please make sure that the detail level for ConsoleHandler can handle the level set for individual packages. For example say you have set the level for "com.sun.faces.el" package to "FINEST" as below. "com.sun.faces.el.level = FINEST" You won't see any trace or debug messages unless you also set ConsoleHandler.level = FINEST. ConsoleHandler.level caps the detail level to the console, no matter what the underlying loggers are set for. In this release, the Reference Implementation provides logging support for the following packges. * com.sun.faces.application * com.sun.faces.el * com.sun.faces.lifecycle The logging messages are not localized. Localisation as well as logging for rest of the RI will be done in a future release. 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*> for 1.2. * 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 for 1.2. * 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 values returned by Map from ExternalContext.getRequestHeaderValuesMap() are currently Enumeration objects instead of String arrays. This will be fixed in the next version. * The default ViewHandler implementation of createView() doesn't use the factory method on Application to create UIViewRoot instances. Because of this, any specialized UIViewRoot implementations will not be used by the ViewHandler implementation. To work around this issue you'll need to use the JSF configuration facility to decorate the default ViewHandler implementation with a custom UIViewRoot that overrides createView(). This will be fixed in the next version. * 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, state in the server is configurable by the RI init context parameters "com.sun.faces.NUMBER_OF_VIEWS_IN_SESSION" and "com.sun.faces.NUMBER_OF_VIEWS_IN_LOGICAL_VIEW_IN_SESSION" without quotes. NUMBER_OF_VIEWS_IN_SESSION controls the number of top-level views that will be stored in the session. NUMBER_OF_VIEWS_IN_LOGICAL_VIEW_IN_SESSION controls the max number of "sub-views" (in an LRU fashion) that will be associated with the top level view. A "sub-view" in this case, could be a frameset or a user browsing with multiple windows. 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 or SJSAS 8.x 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 tomcat 4 series container, or any container that strictly conforms to JSP1.1, Servlet 2.3, you must use JSTL 1.0 instead of JSTL 1.1. * The non-jsp demo does not deploy under tomcat 4.1.29. * Some web containers (Notably BEA WebLogic Server) don't follow the JSP 1.2 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.
javaee/javaserverfaces
PLEASE NOTE: This project has moved to Eclipse Foundation and will be archived under the JavaEE GitHub Organization. After Feb. 1, 2021, the new location will be github.com/javaee/javaserverfaces-web
HTMLNOASSERTION