This README documents the Sun Reference implementation (RI) for JSR 127, JavaServer (tm) Faces. jsf-api cvs tag for this implementation: JSF_API_20030519 jsf-api-spec for this implementation: JSF_SPEC_PRD2.pdf 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 . 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 . 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: ======================================= * Application Configuration Resources (the faces-config.xml file) JavaServer Faces, v 1.0 EA4 defines a portable configuration resource format (as an XML document) for configuring resources required at application startup time. In previous releases, these resources had to be configured programmatically. The configurable resources include: custom components, renderers, converters, and validators; render kits; navigation rules; and model beans. This new feature eliminates the need for: an ApplicationHandler to define navigation; and a ServletContextListener to register converters, validators, renderers, render kits, and messages. The runtime RenderKit inspection APIs have been removed in favor of the data they exposed being codified in the faces-config.xml file. This means the following API have disappeared. class javax.faces.component.AttributeDescriptor methods javax.faces.render.Renderer.getAttributeDescriptor() javax.faces.render.Renderer.supportsComponentType() Please see section 10.3 of the spec. * Navigation Handling mechanism. This new feature is closely tied to the Application Configuration Resources feature described above. In previous releases, navigation rules were defined programmatically in the ApplicationHandler. For this release, navigation rules are defined in the portable configuration resource, described in the previous section. Please see section 7.4 of the spec. * Object Management This new feature is also tied to the Application Configuration Resources feature. In previous releases, JavaServer Faces technology enabled you to create model objects that encapsulated data and business logic separately from UI component objects. This release fully specifies how these objects are created and managed. This release also provides a Managed Bean Creation facility, which creates new model objects and stores them in scope. This facility is also configured using the Application Configuration Resource. Please see section 10.3 of the spec. * New class javax.faces.application.Application: Application represents a per-web-application singleton object where applications based on JavaServer Faces (or implementations wishing to provide extended functionality) can register application-wide singletons that provide functionality required by JavaServer Faces. This class is accessible through the existing FactoryFinder mechanism. Application serves as an abstract factory for several other faces classes. It has subsumed the responsibilities of the former javax.faces.convert.ConverterFactory and javax.faces.context.MessageResourcesFactory classes; thus Application currently vends instances of ValueBinding UIComponent Converter MessageResources Validator Please see Chapter 7 of the spec. * Removal of "built-in-rendering" in UIComponent classes Instead of all the components having built-in-rendering, each component now has a default rendererType property value which maps to a Renderer in the mandatory standard Render Kit. Please see section 8.4 of the spec. * Removal of componentType property for UIComponent and all subclasses. This property has been moved outside of the UIComponent instance. In the JSP case, this property resides on the tag handler that corresponds to the UIComponent. The componentType is used as a key to the UIComponent factory method on Application. Please see section 7.1.6 of the spec. * UIComponent hierarchy shuffling. Here is an ASCII inheritance diagram, where indentation represents inheritance. UIComponent UICommand UIForm UINamingContainer UIOutput UIGraphic UIPanel UIInput UISelectBase UISelectMany UISelectOne UISelectBoolean UIParameter UISelectItem UISelectItems Please see chapter 4 of the spec. * New valueRef and actionRef mechanism The valueRef property on UIOutput takes the place of modelReference. In addition, the actionRef property on UICommand provides a hook into the Navigation System. All of the modelReference methods have left FacesContext and are now part of the new ValueBinding system. Briefly, you ask the Application for a ValueBinding for a given valueRef. The returned ValueBinding has all of the old modelReference methods. This new feature includes the ability to plug in your own classes for resolving variables and properties in the valueRef and actionRef expressions. Please see chapter 5 of the spec. * Portlet compatibility. To allow faces to run inside of portlets, all of the compile-time dependencies on the servlet API have been removed. Semantically, all Servlet API dependencies have been converted to type Object and moved to the new ExternalContext class, which shares the lifetime of the FacesContext. Please see section 6.1.1 of the spec * javax.faces.webapp.{FacesTag,FacesBodyTag} are now javax.faces.webapp.{UIComponentTag,UIComponentBodyTag}. Because the purpose of this tag is to represent a UIComponent instance in the page, it has been renamed. The old classes will continue to work, but have been deprecated. Please see chapter 9 for more information. Per-class changes ================= javax.faces.FactoryFinder.java - Addition of APPLICATION_FACTORY - Removal of MESSAGE_RESOURCES_FACTORY, and CONVERTER_FACTORY javax.faces.component.AttributeDescriptor.java - This class has been removed, since its functionality is now present in the Application Configuration Resources mechanism. javax/faces/component/UICommand.java - addition of actionRef. - removal of default encode/decode. javax/faces/component/UIComponent.java - removal of modelReference property, in favor of valueRef property on UIOutput. - removal of FACET_PARENT attribute, in favor of setParent() method. src/javax/faces/component/UIComponentBase.java - change getClientId() logic to use the renderer's getClientId() to set the clientId instance variable. - removal of getComponentType method. - removal of modelReference property - performance enhancement, use ivars for common properties, instead of HashMap storage. javax/faces/component/UIForm.java javax/faces/component/UIGraphic.java javax/faces/component/UIInput.java javax/faces/component/UINamingContainer.java - extend UIOutput instead of UIComponentBase - removal of getComponentType method. - removal of default encode/decode. javax/faces/component/UINamingContainer.java - removal of getComponentType method. javax/faces/component/UIOutput.java - add valueRef property - removal of getComponentType method. - removal of default encode/decode. javax/faces/component/UIParameter.java - removal of getComponentType method. - removal of default encode/decode. javax/faces/component/UISelectBase.java - bugfix in getSelectItems(). - removed unused utilitiy methods. javax/faces/component/UISelectBoolean.java javax/faces/component/UISelectOne.java javax/faces/component/UISelectItems.java - removal of getComponentType method. - removal of default encode/decode. javax/faces/component/UISelectItem.java javax/faces/component/UISelectMany.java - performance enhancement, use ivars for common properties, instead of HashMap storage. - removal of getComponentType method. - removal of default encode/decode. javax/faces/context/FacesContext.java - Removal of request attribute for storing FacesContext. Replaced with static method that utilizes ThreadLocal, FacesContext.getCurrentInstance(). - Removal of deprecated methods: public abstract Iterator getApplicationEvents(); public abstract int getApplicationEventsCount(); public abstract ApplicationHandler getApplicationHandler(); public abstract void addApplicationEvent(ApplicationEvent event); functionality taken over by navigation system. - Servlet API methods moved in type neutral fashion to new class ExternalContext public abstract HttpSession getHttpSession(); public abstract ServletContext getServletContext(); public abstract ServletRequest getServletRequest(); public abstract ServletResponse getServletResponse(); - getViewHandler() is redundant with the one in Lifecycle. This one was removed. - modelReference methods moved to ValueBinding - new accessor for ExternalContext javax/faces/context/FacesContextFactory.java - Take Object instead of Servlet API classes to getFacesContext(). javax/faces/context/MessageResourcesFactory.java javax/faces/convert/ConverterFactory.java - Moved into Application interface javax/faces/context/Message.java javax/faces/context/MessageImpl.java - Moved into application package javax/faces/event/PhaseId.java - Add phaseName to toString() method for debugging purposes. javax/faces/lifecycle/Phase.java - removed, not necessary in API. javax/faces/lifecycle/Lifecycle.java - removed ApplicationHandler, replaced by Navigation system. - removed executePhase(), not necessary in API javax/faces/lifecycle/ViewHandler.java - renderView throws FacesException instead of ServletException javax/faces/render/RenderKit.java - removal of methods made unnecessary by faces-config.xml public abstract void addComponentClass(Class componentClass); public abstract Iterator getComponentClasses(); - removal of methods that only make sense at design time public abstract Iterator getRendererTypes(); public abstract Iterator getRendererTypes(String componentType); public abstract Iterator getRendererTypes(UIComponent component); javax/faces/render/Renderer.java - removal of methods that only make sense at design time public abstract AttributeDescriptor getAttributeDescriptor(UIComponent component, String name); public abstract AttributeDescriptor getAttributeDescriptor(String componentType, String name); public abstract Iterator getAttributeNames(String componentType); public abstract Iterator getAttributeNames(String componentType); public abstract boolean supportsComponentType(UIComponent component); public abstract boolean supportsComponentType(String componentType); javax/faces/validator/DoubleRangeValidator.java javax/faces/validator/LengthValidator.java javax/faces/validator/LongRangeValidator.java javax/faces/validator/StringRangeValidator.java - changes to deal with new UIComponent hierarchy. - changes to deal with new package for Message. javax/faces/validator/ValidatorBase.java - Leverage the Application's MessageResources/Message facility javax/faces/webapp/AttributeTag.java javax/faces/webapp/FacetTag.java - Deal with name change of FacesTag to UIComponentTag. javax/faces/webapp/FacesBodyTag.java - Name change, to UIComponentBodyTag. javax/faces/webapp/FacesServlet.java - Don't cache the FacesContext in a request attribute. javax/faces/webapp/FacesTag.java - Name change, to UIComponentTag. Known Issues With This Release ============================== * The current implementation does not support adding custom render kits from the Application Configuration Resources file. The workaround for this is to use a ServletContextListener, obtain a reference to the RenderKitFactory, and manually add the render kit to the factory. * When using graphic_image, make sure to start your "url" attribute with a "/" to cause the proper context path to be prepended to your image. * When saving tree in session, we don't support multiple concurrent requests to faces app from one client. * SaveState in page option cannot be used if your web app has event handlers and validators because they are not serializable currently. * Additionally, in the areas of functionality released in the EA, there are already significant changes in progress in the specification. Therefore, only experimental code should be developed against this release since it will not be compatabile with subsequent releases. Legal Notice ============ Copyright © 2002 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 © 2002 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.