# JavaServerTM Faces Technology, version 1.2
Release Notes

For an updated, online version of these release notes, see Release Notes

Revised: 20050818

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

This release of JavaServer Faces technology was developed under the Java Community Process(SM) ("JCP(SM)") as JSR252.

# Contents

- Supported Operating Systems
- Required Software
- What This Release Includes
- What's New in This Release
- Migrating from 1.1_01 to 1.2
- Known Issues

# Supported Operating Systems

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

# Required Software

This release requires that you install the software listed in the following table. Only those versions listed in the table have been tested and are supported.

TABLE 1 Required Software
Software | Version
--- | ---
Java Development Kit (JDK) | version 5.0 or later
Sun Java System Application Server | version 9.0
Microsoft Internet Explorer or Netscape Navigator | version 6 (IE) version 7 (Netscape)

# 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

This snapshot of JavaServer Faces Reference implementation includes the bug fixes and implementation of issues listed under the General Changes section of the JavaServer Faces technology 1.2 PFD access draft plus the bug fixes listed in the following table.

Table 2: List of Bugs Fixed in this Release
Issue/Bug Number | Summary
Issue 10 | target property on commandLink does not work
Issue 13 | Taglib generator enhancements
Issue 26 | Hidden Field - FormRenderer - Renderer Dependencies
Issue 42 | Message list (HtmlMessages) does not correctly handle style attribute
Issue 43 | MessagesRenderer Bug Fixes
Issue 49 | attribute/property transparency: really slow
Issue 53 | verbatim tag trims whitespace
Issue 55 | commandButton image attr don't add context path
Issue 56 | Fail to validate select one menu in a table, if its rendered is false
Issue 63 | Use of Browser's back-button causes multiple ActionEvents to pile up
Issue 64 | column component metadata missing facets
Issue 62 | nested datatable with commandLink
Issue 66 | Possible optimization regarding execution of PhaseListeners
Issue 67 | Usability of JSF RI Exceptions and Stack Traces
Issue 68 | Concurrency issue with CommandLinkRenderer
Issue 70 | HtmlTaglib Generates Release Methods
Issue 71 | Allow JavaScirpt User Event Support
Issue 73 | Using {0} in the Key/Value pair of the resource bundle does not work
Issue 80 | LifecycleImple.reload() not sufficient for all cases
Issue 82 | h:inputText and immediate="true" not flushing cached backing
Issue 83 | DataTable rendering of columnClasses doesn't work in the header
Issue 84 | Implement 2-StateSavingSecurity
Issue 85 | ApplicationImpl.createConverter() does not throw FacesException
Issue 87 | Unexpected behaviour with disabled selectOneMenu
Issue 89 | HtmlResponseWriter.writeAttribute() throws NPE for null values
Issue 91 | Don't swallow exceptions inside JspExceptions or FacesExceptions
Issue 92 | MessagesRenderer Does Not Handle layout="list"
Issue 95 | RestoreViewPhase.isPostback() not good to determine restore view
Issue 96 | Remove compile time dependency on commons-logging
Issue 97 | Several classes don't include definition for hashCode
Issue 98 | Redundant comparison to null in two instances of jsf-impl
Issue 99 | Serializable classes don't declare serialVersionUID
Issue 101 | Mutable static fields not final
Issue 102 | Memory wastage using new instances of java.land.Boolean and
Issue 103 | Inner classes with no use of creating class reference could
Issue 104 | Instance final field could be static
Issue 106 | Unread fields
Issue 107 | Unused fields
Issue 108 | Validator API classes define equals but not hashcode
Issue 109 | UISelectOne/UISelectMany methods: possible null pointer dere
Issue 110 | UIComponentBase may have possible redundant null comparison
Issue 113 | API performance: inner classes not using creating class refe
Issue 114 | Unread fields in API classes
Issue 115 | API performance: use entrySet, rather than keySet, iterator
Issue 116 | Colon's not allowed in javascript function name
Issue 121 | Store Session States on a per window and viewid basis
Issue 122 | redirect attribute dissappeared from inputSecret
Issue 123 | ConfigureListener within non JSP 2.1
Issue 124 | Setting a method binding action listener via constructor cau
Issue 125 | Memory issues
Issue 127 | FacesContext: message Iterators should be order-preserving
Issue 128 | UIData does not restoreDescendantState for descendant facets
Issue 129 | Please check that application.set{Property,Variable}Resolver
Issue 131 | add new passthru attribute "autocomplete"
Issue 133 | Add extension elements to schema
Issue 134 | Optimisations to managed bean creation facility
Issue 135 | RuntimeException thrown in decode() swallowed
Issue 136 | JSF 1.2 Runs outside of JSP 2.1
Issue 138 | NullPointerException when Restoring Server ViewState
Issue 139 | Call converter on null value
Issue 143 | input request ignored after repeated use of one view
Issue 144 | CommandLink Renderer and XHTML
Issue 146 | NPE in ExternalContextImpl.dispatch() when file not present
Issue 148 | MethodExpressionValidator Exception Management
Issue 149 | FacesContext, ViewHandler & ResponseWriter
Issue 151 | Swallowed exception in ResopnseStateManagerImpl.getTreeStruc
Issue 152 | UIData preserving request attributes
Issue 153 | Enable resource injection in managed bean creation facility
Issue 154 | Faces ELResolver usage at design time
Issue 157 | Artifact in UIViewRoot from pre TCCI days
Issue 158 | Application.getExpressionFactory returns Null
Issue 159 | Nested DataTable expressions resolve wrong
| Fix for ClassCastException that happens when two portlets are deployed
Issue 162 | Application.createComponent(ValueExpression, FacesContext, S
Issue 163 | Custom ResponseStateManager Does Not Work With RI
Issue 164 | Write a systest that tests the new c:forEach feature
Issue 165 | ViewHandlerImpl Calls StateManagerImpl Deprecated Methods On
Issue 166 | implement c:forEach support.
Issue 167 | Terrible error message on type mismatch.

# Migrating From 1.1_01 to 1.2

This implementation is 100% compatible with the 1.1_01 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.

One of the primary changes in this release is that JavaServer Faces technology utilizes the new unified expression language (unified EL) , which is essentially an amalgamation of the JSP EL and the JavaServer Faces 1.1_01 EL. The rest of this section describes how to migrate your JavaServer Faces 1.1_01 applications to use the unified EL.

## Migrating to the Unified EL

For those of you who already have applications that use the JavaServer Faces EL, you can be assured that your applications are completely backward compatible. You don't need to make any changes to run your applications with the latest version of JavaServer Faces technology.
If you plan to modify your current applications to use the unified EL, however, there are some things you need to do, which this section explains.

### Using the Unified EL in Existing Applications

For the page author and application developer, there is nothing that you need to do differently in JavaServer Faces technology 1.2 applications vs. JavaServer Faces technology 1.1_01 or earlier applications. The component writer and the application architect do have some changes to make, which include:

- Editing custom component classes to use the new APIs
- Editing custom component tag handlers to use the new APIs
- Updating the TLD defining the custom component tags with the new version number and the new deferred-value or deferred-method elements

#### Making Changes to the Custom Component Classes

JavaServer Faces technology 1.1_01 and earlier versions used the ValueBinding and MethodBinding classes to represent value expressions and method expressions, respectively. These classes are still available in JavaServer Faces technology 1.2 for those who want to continue using them. If you want your components to use the unified EL, however, you need to change all instances of `ValueBinding` to ValueExpression and all instances of MethodBinding to MethodExpression. The ValueExpression and MethodExpression APIs are part of the unified EL specification. The following component method shows the JavaServer Faces technology 1.1_01 version of a value-binding enabled component property.

    public boolean someProperty() {
      if (this.someProperty) {
          return (this.someProperty);
      }
      ValueBinding vb = getValueBinding("someProperty");
      if (vb != null) {
        Boolean value = (Boolean) vb.getValue(getFacesContext());
        return (value.booleanValue());
      } else {
          return (this.someProperty);
      }
    }

The following code shows this method converted to use the new APIs.

    public boolean someProperty() {
    	if (this.someProperty) {
    		return (this.someProperty);
    	}
    	ValueExpression ve = getValueExpression("someProperty");
    	if (ve != null) {
    		Boolean value = (Boolean)
    		ve.getValue(getFacesContext().getELContext());
    		return (value.booleanValue());
    	} else {
    		return (this.someProperty);
    	}
    }

#### Making Changes to the Custom Component Tag Handlers

To migrate your tag handler class, you need to do the following:

- Make the class extend UIComponentELTag instead of UIComponentTag
- Change ValueBinding to ValueExpression and MethodBinding to MethodExpression
- Simplify the setProperties method by removing the check for if the property is value-expression enabled

Here are the relevant pieces of a tag handler class using the version 1.1_01 APIs:

    public class SimpleComponentTag extends UIComponentTag {

    	String someProperty;
    	String validator;

    	public void setSomeProperty(String someProperty) {
    	   this.someProperty = someProperty;
    	}
    	public void setValidator(String validator) {
    	   this.validator = validator;
    	}
    	...
    	protected void setProperties(UIComponent component) {
    	   super.setProperties(component);
    		if (someProperty != null) {
    		   if (isValueReference(someProperty)) {
    		   	ValueBinding vb = FacesContext.getCurrentInstance().
    					getApplication().createValueBinding(someProperty);
    			component.setValueBinding(“someProperty”, vb);
    		   } else {
    		   	component.getAttributes().put(“someProperty”, someProperty);
    		   }
    		}
    	   	if(validator != null) {
    		   if (isValueReference(validator)) {
    			Class args[] = { FacesContext.class, UIComponent.class,
    				Object.class };
    			MethodBinding vb = FacesContext.getCurrentInstance().
    			   getApplication().createMethodBinding(validator, args);
    			input.setValidator(vb);
    		   } else {
    			throw new  FacesException(“Invalid Expression”);
    		   }
    		}
    	}

    }

And here is the same tag handler class converted to use the 1.2 APIs:

    public class SimpleComponentTag extends UIComponentELTag {

    	ValueExpression someProperty;
    	MethodExpression validator;

    	public void setSomeProperty(ValueExpression someProperty) {
    	   this.someProperty = someProperty;
    	}

    	public void setValidator(MethodExpression validator) {
    	   this.validator = validator;
    	}
    	...

    	protected void setProperties(UIComponent component) {
    	   super.setProperties(component);
    	   if (someProperty != null) {
    		if (!someProperty.isLiteralText()) {
    		   component.setValueExpression(“someProperty”, someProperty);
    		} else {
    		   component.getAttributes().put(“someProperty”,
    			someProperty.getExpressionString());
    		}
    	   }
    	   if(validator != null) {
    		component.addValidator(new MethodExpressionValidator(validator));
    	   }
    	}
    }

Notice that the new setProperties method does not have to do the work of getting the expression from the Application instance and converting a String to a value binding or method binding. Instead, the JSP container manages the ValueExpression and MethodExpression objects and passes them to the tag handler. Also, setProperties does not have to check if the property is value-expression or method-expression enabled because this information is already in the TLD, which we show in the next section.

#### Making Changes to the Custom Tag TLD

To migrate your TLD files to use the new expression language, you need to do the following:

- Change the JSP version number to 2.1.
- Remove the rtexprvalue element and replace it with either deferred-value or deferred-method, depending on whether the corresponding property accepts value expressions or method expressions.

The following TLD defines a custom component tag based on version 1.1_01:

    <taglib>
       <!-- ============== Tag Library Description Elements ============= -->
       <tlib-version>1.0</tlib-version>
       <jsp-version>1.2</jsp-version>
       <short-name>Demo Taglib</short-name>
       <tag>
    	<name>simple</name>
    	<tag-class>example.SimpleComponentTag</tag-class>
    	<body-content>JSP</body-content>
    	<attribute>
    		<name>someProperty</name>
    		<required>true</required>
    		<rtexprvalue>false</rtexprvalue>
    	</attribute>
    	<attribute>
    		<name>validator</name>
    		<required>false</required>
    		<rtexprvalue>false</rtexprvalue>
    	</attribute>
       </tag>
    </taglib>

The following TLD defines the same custom component tag for JavaServer Faces technology 1.2:

    <taglib>
       <!-- ============== Tag Library Description Elements ============= -->
       <tlib-version>1.1</tlib-version>
       <jsp-version>2.1</jsp-version>
       <short-name>Demo Taglib</short-name>
       <tag>
    	<name>simple</name>
    	<tag-class>example.SimpleComponentTag</tag-class>
    	<body-content>JSP</body-content>
    	<attribute>
    	   <name>someProperty</name>
    	   <required>true</required>
    	   <deferred-value>
    	   	<type>java.lang.String</type>
    	   </deferred-value>
    	</attribute>
    	<attribute>
    	   <name>validator</name>
    	   <required>false</required>
    	   <deferred-method>
    		<method-signature>
    		   void validate(javax.faces.context.FacesContext,
    			javax.faces.component.UIComponent, java.lang.Object)
    		</method-signature>
    	   </deferred-method>
    	</attribute>
       </tag>
    </taglib>

Note that the jsp-version element is now 2.1. This indicates to the JSP 2.1 container whether or it should try to create a ValueExpression or MethodExpression instance and pass it to the tag handler or pass an expression string as a literal value to the tag handler. If the version number is 2.1, it does the former.
The other change is that rtexprvalue has been replaced with the deferred-value element for the someProperty property and with deferred-method for the validator property. The deferred-value element tells the JSP container that the property accepts deferred value expressions. The deferred-method element tells the JSP container that the validator property accepts method expressions. Therefore, the container creates a ValueExpression object for someProperty and a MethodExpression object for the validator property and passes these objects to the tag handler. The type subelement of deferred-value indicates the type to which the expression must evaluate. The method-signature subelement of deferred-method specifies the signature required for the corresponding method.

# Known Issues With This Release

As stated in section Migrating from 1.1_01 to 1.2, your JavaServer Faces technology, version 1.1_01 applications can run on JavaServer Faces technology 1.2. However, there are a few corner cases in which backwards-compatibility breaks. Please see the section Breakages in Backwards Compatibility in the JavaServer Faces technology 1.2 PFD specification.

Copyright © 2005 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 © 2005 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.