README

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.