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

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

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

Using the Unified EL in Existing Applications

• 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

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);
      


  }
      


}
      


       


    

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

• 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
  

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”);  
      
       
        


                       }  
      
            
        


                   }  
      
        
        


              }
      


       


}
    

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));  
      
      
        


             }
      


        }
      


}
      
         


         


      
    

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>
    

Known Issues With This Release

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.