This README documents the Sun Reference implementation (RI) for 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.0 release

Sun RI Changes

* Tag Library Validation in the html_basic taglib is disabled by
  default.  To enable it set the
  "com.sun.faces.enableHtmlTagLibValidator" ServletContext init param to
  true in your web.xml, like this:

    <context-param>
        <param-name>com.sun.faces.enableHtmlTagLibValidator</param-name>
        <param-value>true</param-value>
    </context-param>

* Correctly handle how none scoped beans can not refer to other none
  scoped beans.

* Remove compile time dependencies on servlet API classes in our custom
  tags.

* Correctly implement scope protection rules in section 5.3.1.3 of the
  spec.  

* Correctly implement the cyclical bean reference prohibition.

* Error message enhancements.

   - Provide in the error message the component id, if present, of the
     component that caused the error.

   - if you happen to leave out your <h:form> tag, you'll see a more
     sensible error message.  

   - if the ctor of a managed-bean throws an exception, the exception is
     no longer swallowed.

* Fixed bug where a user providing their own ApplicationFactory would
  not be able to leverage any of the default Application instance
  functionality.  It is now possible to provide a decorator
  ApplicationFactory that provides a decorated Application instance that
  can call through to as many or as few methods on the default
  Application instance as it likes.  Here's how you'd do this.

  1. Declare your ApplicationFactory in your faces-config.xml file:

  <factory>
    <application-factory>org.NewApplicationFactory</application-factory>
  </factory>

  2. Give the NewApplicationFactory a ctor that takes ApplicationFactory:

    public NewApplicationFactory(ApplicationFactory yourOldFactory) {
	oldFactory = yourOldFactory;
    }

  3. Give the NewApplicationFactory a getApplication() method that
     returns a wrapped application.

    public Application getApplication() {
	if (null == newApp) {
	    newApp = new NewApplication(oldFactory.getApplication());
	}
	return newApp;
    }

  4. Author your NewApplication instance so that it can leverage the old
     Application.

     // ... other methods

    public VariableResolver getVariableResolver() {
        if (someSpecialConditionIsTrue) {
          return yourCustomVariableResolver;
        }
	return oldApp.getVariableResolver();
    }

* Fixed bug where providing your own factory classes in a <factory>
  element in your faces-config.xml file didn't work.

* Fixed bug where managed bean properties were not getting set in the
  order in which they appeared in the config file.

* Be more strict about enforcing the component id uniqueness constraint.
  With this constraint being more strict, it's a good idea if you're
  programmatically adding components into the tree that you give them an
  id explicitly before adding them.

* Allow a UIComponentTag that are nested inside of UIComponentBodyTag to
  have doAfterBody() methods that return EVAL_BODY_AGAIN if the
  UIComponentTag has an explicitly defined id.

* Expression Language engine performance enhancements:

  - reduce String creation

  - reduce temporary Object instance creation 

General Spec changes

  New 1.1 version of the DTD, backwards compatible with the 1.0
  version. The only difference is that components and renderers can
  declare what facets they support. Please See Section 10.3.3
  "Application Configuration Resource Format".

  Introduce the concept of "no value" for SelectOne and
  SelectMany. class com.sun.faces.component.UIInput:

    modify isEmpty() method to consider values that are zero length array
    or List instances to be empty.

  Refactor validation implementation in class
  com.sun.faces.component.UIInput to prevent spurious ValueChangeEvent
  instances from being fired from UISelectOne and UISelectMany
  classes. See the javadocs for UIInput.validate().

  Method com.sun.faces.component.UIViewRoot.getRenderKitId() now returns
  null unless the setter has been explicitly called. See the javadocs
  for that method.  DoubleRangeValidator, Lengthvalidator, and
  LongRangeValidator now require that any validation parameters passed
  to the validation error message be converted by the javax.faces.Number
  converter.

  The JavaDocs description ResultSetDataModel.getRowData() specifies
  that the returned Map must use a case-insensitive Comparator.
  DataModelEvent.getRowIndex() now returns -1 to indicate that no row is
  selected.

  Fix the JavaDoc description of the defaults for showDetail and
  showSummary for UIMessage to match the code.

  Fix JavaDoc description of EditableValueHoldergetSubmittedValue() to
  correctly say when this method is called.

  Fix JavaDoc for UIComponentTag.setProperties() to correctly describe
  which parameters are set.

  The implementation now allows nesting <h:dataTable> tags. Previously
  this didn't work.

  Fix bug where multiple action events could be generated in the case of
  multiple <h:commandLink> tags on page that is visited as a result of
  going "back" in the browser history.
 
Standard HTML RenderKit changes

  Made the "for" attribute no longer required for the outputLabel
  tag. This is necessary when tools want to allow the user to stick the
  label on the page before associating the component with it.  RenderKit
  changes for SelectManyMenu, SelectManyList, SelectOneRadio,
  SelectManyCheckboxlist

  Remove span around "select" tags in SelectManyMenu, SelectManyList,
  SelectOneMenu and SelectOneList.  Remove span around SelectOne radio
  buttons and SelectMany checkboxes. Render "id", "style", "styleclass"
  as part of outer table.

  The SelectManyCheckbox and SelectOneRadio renderers now do not render
  a "for" attribute on their nested <label> elements.  The
  SelectOneRadio renderer description is more explicit about the use of
  the <label> element.

  The description of the "size" attribute in the SelectMany renderers is
  more correct with respect to the actual attributes exposed.  The
  OutputLabel renderer is now able to handle the case where the compnent
  to which this label points hasnt been created yet, as long as the
  component and the label are both in the same form.

  The enabledClass and disabledClass attributes are now specified for
  all select* renderers.

Spec document changes

  2.5.2.4 LIMIT messages not used, remove LIMIT messages.

  5.2 Table 5.1, modify action method signature to return String, not
  void.

  5.3.1.3

  In the section describing how to set a list-entries property, added a
  step describing what to do if the property is an array, yet the
  property getter had returned null.

  Assign scopes to the implicit variables, so we can determine if a bean
  is able to refer to an implicit variable, dependeng on its scope.  For
  example, a session scoped bean cannot refer to something in request
  scope.  Add a rule dealing with the net scope of mixed expressions:
  The net scope of mixed expressions is considered to be the scope of
  the narrowest expression in the mixed expression, excluding
  expressions with the none scope.

  5.3.1.13

  clarify that errors described in this section occurr at runtime, not
  deploytime.

  9.4.3 Data type for "timeZone".

  The "timeZone" attribute for <f:convertDateTime> in 9.4.3 is described
  to only accept a TimeZone instance, but must also accepts a String.
  The "locale" attribute for <f:convertDateTime> and <f:convertNumber>
  in 9.4.3 and 9.4.4 is described to only accept a Locale instance, but
  must also accepts a String.

  9.4.12 - 9.4.14 Correct validator and converter IDs

  9.4.9 Incorrect data type for "itemValue"

  The attributes table for <f:selectItem> in 9.4.9 states that the
  "itemValue" attribute takes a String but it should be Object to match
  the type of the UISelectItem property.  The syntax section in 9.4.9
  for <f:selectItem> is missing a couple of right square brackets to
  mark the end for optional attributes.

  9.4.10 contains a number of errors: The description of the
  getComponentType() return value omits the "javax.faces" prefix. The
  list of acceptable data types for the "value" attribute doesn't match
  the data type for UISelectItems.

  9.4.8 <f:param> syntax section missing "binding"

  10.2.6.1 Correct classnames for LifecycleFactory and RenderKitFactory.


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
==============================

* 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.

* Standard error messages associated with conversion/validation errros 
  have been updated to include componentId in the error message only for the 
  English locale. For other locales, the workaround is to override the 
  standard error messages to include the componentId parameter. The last 
  parameter in the error message corresponds to componentId. The messages 
  have been formulated in such a way that if "id" is not specified  an empty 
  string is displayed in its place. Thats why we have the last parameter 
  at the front, and the parameter doesn't have any extra characters on 
  either side of it.

* 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 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.


Legal Notice
============

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 rservs.

Sun Microsystems, Inc. a les droits de proprit intellectuels relatants
 la technologie incorpore dans ce produit. En particulier, et sans la
limitation, ces droits de proprit intellectuels peuvent inclure un ou
plus des brevets amricains numrs  http://www.sun.com/patents et un
ou les brevets plus supplmentaires ou les applications de brevet en
attente dans les Etats - Unis et les autres pays.

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

Le logiciel dtenu par des tiers, et qui comprend la technologie
relative aux polices de caractres, est protg 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 dposes de Sun
Microsystems, Inc. aux Etats-Unis et dans d'autres pays.
