Sun中国技术社区- Sun Developer Network (SDN) Home

在最近的一期文章中，我们介绍了如何应用 JSFTemplating 编写 JavaServer Faces 组件。这篇文章提供了一种开发 JavaServer Faces 组件呈现器的简单方法，可以将 Java 代码中的组件标记移至一个模板文件并显著改善组件清晰度和可维护性。

本文讨论的方法虽然实用，但是无法解决 JavaServer Faces 组件创建过程中遇到的其他众多问题。例如，您仍然需要编写 JavaServer Pages (JSP) 标记处理程序、JSP TLD 文件、faces-config.xml 文件，并且还可能需要 Facelets taglib.xml 文件。此外，还必须通过某种方式打包并处理与组件有关的资源。

本文对上篇文章进行了扩展，展示了一种更简单的方法来解决其余的组件创建问题。通过遵循本文介绍的策略，JavaServer Faces 组件创建将变得轻而易举。

除 GlassFish 应用服务器外，本文还将用到其他两个 GlassFish 开源项目的成果：Templating for JavaServer Faces Technology (JSFTemplating) 和 Woodstock。

借助这两个项目，只需使用两个文件即可编写一个 JavaServer Faces 组件：一个经过注释的 UIComponent Java 文件和一个模板文件。没错 — 只需要两个文件！

本文构建的组件将封装一个来自 Yahoo! 的滑块部件,从而完善 UIInput JavaServer Faces 组件的功能。除组件本身需要的两个源文件外，还需要使用一些资源文件(JavaScript 文件、映像等等）。对资源功用的讨论超出了本文的范围；然而，本文将简要介绍资源文件的绑定和处理方式，从而为 JavaServer Faces 组件创建提供完整的解决方案。

要查看组件的运行情况，请参见下图，其中展示了示例应用程序组件的屏幕截图。

该图显示了两个滑块组件。每个滑块组件具有两个输入框，在滑块移动时由 JavaScript 代码更新。输入框的作用是演示滑块组件的功能。它们不属于滑块组件，并且不需要保持滑块组件的值—滑块组件本身就是一种输入组件。例如，水平滑块的标记及其相关输入框如下所示：

单击此处下载 ezcomp 示例应用程序的压缩文件。解压缩该文件并阅读 README.txt 文件，该文件描述组件需要的源文件以及创建所需的构建环境。

查看该 JavaServer Faces 组件（或其他组件）的主要类 UIComponment，开始对组件进行分析。本文所述方法需要使用来自 JSFTemplating 的一个基类来帮助查找相关的模板文件。由于滑块是一种输入组件，它使用 TemplateInputComponentBase 提供基本的功能。更多细节，请参考 javadoc。

滑块的 UIComponent 使用的 Java 代码如下所示：要获得该文件，可通过以下位置访问示例 Java 归档文件（jar 文件）：src/java/main/com/sun/faces/mojarra/component/YuiSlider.java。

package com.sun.faces.mojarra.component;

import com.sun.faces.annotation.Component;
import com.sun.faces.annotation.Property;
import com.sun.jsftemplating.annotation.Handler;
import com.sun.jsftemplating.annotation.HandlerInput;
import com.sun.jsftemplating.component.TemplateInputComponentBase;
import com.sun.jsftemplating.layout.descriptors.handler.HandlerContext;

import javax.faces.context.FacesContext;
import javax.faces.component.UIComponent;

/**
 * @author Jason Lee
 */

@Component(rendererClass = "com.sun.jsftemplating.renderer.TemplateRenderer", 
           tagRendererType = YuiSlider.RENDERER_TYPE, 
           type = YuiSlider.COMPONENT_FAMILY, 
           family = YuiSlider.COMPONENT_FAMILY,
           displayName = "Slider", 
           tagName = "slider")

public class YuiSlider extends TemplateInputComponentBase {

    /**
     * <p>The standard component orientation for this component.  </p>
     */
    public static final String COMPONENT_FAMILY = "com.sun.faces.mojarra.YuiSlider";

    /**
     * <p>The standard component family for this component.</p>

     */
    public static final String RENDERER_TYPE = "com.sun.faces.mojarra.YuiSliderRenderer";

    private Boolean animate = Boolean.TRUE;
    private double animationDuration = 0.2;
    private Boolean backgroundEnabled = Boolean.TRUE;
    private int min = 0;
    private Boolean enableKeys = Boolean.TRUE;
    private int keyIncrement = 10;
    private double scaleFactor = 1.0;
    private int max = 100;
    private int tick = 1;
    private String orientation = "horizontal";
    private String forField;
    private Object[] _state = null;

    public YuiSlider() {
        super();
       
setRendererType(RENDERER_TYPE);
       
setLayoutDefinitionKey("templates/slider.xhtml");
    }

    public String getFamily() {
        return COMPONENT_FAMILY;
    }

    public Boolean getAnimate() {
        return getPropertyValue(animate, "animate", Boolean.TRUE);
    }

    public double getAnimationDuration() {
        return getPropertyValue(animationDuration, "animationDuration", 0.2);
    }

    public Boolean getBackgroundEnabled() {
        return getPropertyValue(backgroundEnabled, "backgroundEnabled", Boolean.TRUE);
    }

    public int getMin() {
        return getPropertyValue(min, "min", 0);
    }

    public Boolean getEnableKeys() {
        return getPropertyValue(enableKeys, "enableKeys", Boolean.TRUE);
    }

    public int getKeyIncrement() {
        return getPropertyValue(keyIncrement, "keyIncrement", 10);
    }

    public double getScaleFactor() {
        return getPropertyValue(scaleFactor, "scaleFactor", 1.0);
    }

    public int getMax() {
        return getPropertyValue(max, "max", 100);
    }

    public int getTick() {
        return getPropertyValue(tick, "tick", 1);
    }

    public String getOrientation() {
        return getPropertyValue(orientation, "orientation", "horizontal");
    }

    public String getFor() {
        return getPropertyValue(forField, "for", null);
    }

    @Property(name = "animate")
    public void setAnimate(Boolean animate) {
        this.animate = animate;
    }

    @Property(name = "animationDuration")
    public void setAnimationDuration(double animationDuration) {
        this.animationDuration = animationDuration;
    }

    @Property(name = "backgroundEnabled")
    public void setBackgroundEnabled(Boolean backgroundEnabled) {
        this.backgroundEnabled = backgroundEnabled;
    }

    @Property(name = "min")
    public void setMin(int limit) {
        this.min = limit;
    }

    @Property(name = "enableKeys")
    public void setEnableKeys(Boolean enableKeys) {
        this.enableKeys = enableKeys;
    }

    @Property(name = "keyIncrement")
    public void setKeyIncrement(int keyIncrement) {
        this.keyIncrement = keyIncrement;
    }

    @Property(name = "scaleFactor")
    public void setScaleFactor(double scaleFactor) {
        this.scaleFactor = scaleFactor;
    }

    @Property(name = "max")
    public void setMax(int limit) {
        this.max = limit;
    }

    @Property(name = "tick")
    public void setTick(int tick) {
        this.tick = tick;
    }

    /**
     *    If the orientation starts with a 'v' or 'V', 
     *    set the orientation to 'vertical'.
     *    Otherwise, default to 'horizontal'.
     */
    @Property(name = "orientation")
    public void setOrientation(String orientation) {
        if ((orientation.charAt(0) == 'v') || (orientation.charAt(0) == 'V')) {
           this.orientation = "vertical";
        } else {
           this.orientation = "horizontal";
        }
    }

    @Property(name = "for")
    public void setFor(String forField) {
        this.forField = forField;
    }

    public void restoreState(FacesContext _context, Object _state) {
        this._state = (Object[]) _state;
        super.restoreState(_context, this._state[0]);
        animate = (Boolean) this._state[1];
        animationDuration = (Double) this._state[2];
        backgroundEnabled = (Boolean) this._state[3];
        min = (Integer) this._state[4];
        enableKeys = (Boolean) this._state[5];
        keyIncrement = (Integer) this._state[6];
        scaleFactor = (Double) this._state[7];
        max = (Integer) this._state[8];
        tick = (Integer) this._state[9];
        orientation = (String) this._state[10];
        forField = (String) this._state[11];
    }

    public Object saveState(FacesContext _context) {
        if (_state == null) {
            _state = new Object[12];
        }
        _state[0] = super.saveState(_context);
        _state[1] = animate;
        _state[2] = animationDuration;
        _state[3] = backgroundEnabled;
        _state[4] = min;
        _state[5] = enableKeys;
        _state[6] = keyIncrement;
        _state[7] = scaleFactor;
        _state[8] = max;
        _state[9] = tick;
        _state[10] = orientation;
        _state[11] = forField;
        return _state;
    }

}

如果曾经编写过 JavaServer Faces 组件，那么应该对这些代码很熟悉：然而，需要注意三个不同之处：

该文件还包含了典型的 UIComponent 代码。如果不需要组件支持，可以删除组件中的属性并使用 JavaServer Faces 属性图 — 从此处查阅使用该方法的文章。如果使用 JavaServer Faces 属性图，那么就不需要用到文件的其余内容 — 状态保存代码以及所有 getter 和 setter 方法。

本节将描述第二个也是最后一个必需文件，即模板文件。示例组件将演示 JSFTemplating 功能以使用 Facelets 语法。很多人（包括模板文件的作者 Jason Lee）都非常熟悉这种语法。

上一节描述的 UIComponent 文件指定了模板文件的位置：templates/slider.xhtml。您应该能够在示例 jar 文件中找到它，该文件应该类似于以下代码示例。

注意，示例应用程序中的“page”也称为 slider.xhtml 并且位于 docroot 中 — 这是另一个文件！

<html xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:f="http://java.sun.com/jsf/core" >

     <ui:event type="decode" >
    ezcomp.decode(value="$requestParameter{$this{clientId}}");
     </ui:event >

     <ui:composition >

     <ui:include src="templates/init.xhtml"/ >
     <link rel="stylesheet" type="text/css"
        href="#{baseUrl}yui/container/assets/container.css"/ >
     <script type="text/javascript" src="#{baseUrl}yui/slider/slider-min.js" > </script >
     <script src="#{baseUrl}yui/animation/animation-min.js" > </script >
     <script src="#{baseUrl}yui/container/container-min.js" > </script >

     <ui:include src="templates/cssOverrides.xhtml"/ >

     <span class="yui-skin-sam" >
         <input type="hidden" id="$this{clientId}" name="$this{clientId}" value="$property{value}" / >
         <div id="$this{clientId}_slider" style="background-color: #990000;
        background:url('#{baseUrl}scales/img/slider-bg-$property{orientation}.gif');
        background-repeat: repeat-#{'$property{orientation}' == 'horizontal' ? 'x' : 'y'};
        #{'$property{orientation}' == 'horizontal' ? 'height' : 'width'}: 28px;
        #{'$property{orientation}' == 'horizontal' ? 'width' : 'height'}: #{($property{max} - $property{min}) * $property{scaleFactor} + 14}px;" >
         <div id="$this{clientId}_sliderthumb" >

             <img src="#{baseUrl}scales/img/slider-thumb-$property{orientation}.gif"/ >
         </div >
         </div >
         <script type="text/javascript" >
        YAHOO.util.Event.onDOMReady(function() {
                var slider_$this{id} = YAHOO.widget.Slider.get#{'$property{orientation}' == 'horizontal' ? 'Horiz' : 'Vert'}Slider(
                    "$this{clientId}_slider", "$this{clientId}_sliderthumb",
                    $property{min}, $property{max}, $property{tick});
                slider_$this{id}.getRealValue = function() {
                    return Math.round(this.getValue() * $property{scaleFactor});
                }

                // Subscribe to the onChange event to capture the new value from the slider
                slider_$this{id}.subscribe("change", function(offsetFromStart) {
                    YAHOO.util.Dom.get('$this{clientId}').value = this.getRealValue(); // update hidden field
                    YAHOO.util.Dom.get('$this{clientId}_slider').title = this.getRealValue(); // Update the slider's div's title

                    // Update any input fields that might be tied to this slider
                    //var elems = YAHOO.util.Dom.getElementsByClassName('bd', 'div', "slider_$this{id}_tooltip");
            //elems[0].innerHTML = slider_$this{id}.getRealValue();
                    for(var i=0;i != this.ids.length;i++) {
                        var elem = YAHOO.util.Dom.get(this.ids[i]);
                        if (elem != null) {
                            elem.value = this.getRealValue();
                        }
                    }
        }, slider_$this{id}, true);
                slider_$this{id}.setValue($property{value});

                // If the "for" property was specified, spilt the value on the comman
                // and store the array on the slider object
                var fields="$property{for}";
                if (fields != null) {
                    if (fields.length != 0) {
                        slider_$this{id}.ids = fields.split(",");
                    }
                }
            });
         </script >
     </span >

 </ui:composition >
 </html >

现在，已经完成了 JavaServer Faces 组件的定义。但是，您仍然需要编译组件以便编译 Java 文件并处理注释。使用本文介绍的方法，不需要动手编写就可以生成所有编译内容。示例应用程序的 ant build.xml 文件定义了编译流程：

该文件要求 ant 1.7 处理 <apt> 任务定义。总体来讲，文件逻辑非常简单：编译代码，然后完成。有关将类归档到 jar 文件并创建 war 文件等其他目标，请查看 build.xml 文件。这些内容不在本文讨论范围之内。

现在理解了 build.xml 文件之后，可以通过输入 ant 命令执行该文件 — 假设您遵循本文开始部分提及的 README.txt 文件中的说明。README.txt 文件说明如何编辑 build.properties 文件以适合您的环境。如果一切设置正确，将在几秒之内完成任务。

现在可以开始部署应用程序了。如果对应用程序执行“字典部署”，那么可以直接编辑源文件并在浏览器中即时查看。要在 asadmin 命令行界面中使用 GlassFish 进行字典部署，输入以下命令：

其中，glassfish-home 是 GlassFish 的安装目录，而 path-to-directory 是 ezcomp 示例应用程序的路径。

您还可以通过 GlassFish Admin Console 执行应用程序字典部署，如下图所示。

应用程序部署完毕后，将浏览器导航到 http://localhost:8080/ezcomp 进行试验。应该能够看到如下图所示的页面：

该页面提供了两种选择：使用 JSFTemplating 或 Facelets 运行 slider.xhtml 页面。该选项说明：即使页面其他位置没有使用 JSFTemplating，您也可以使用 JSFTemplating 组件 — 该组件可以在任何 JavaServer Faces 环境中运行。示例应用程序首页提供的这两种选择都可以访问磁盘中的文件，但是，应用程序配置了两种不同的扩展，因此可以同时运行 JSFTemplating 和 Facelets. 不论单击哪个链接，都将看到类似图 1 所示的页面。

请记住，您可以在磁盘上修改页面或组件 xhtml 文件并在浏览器中即时查看修改。警告：提交表单后，将从表单（或会话）中恢复修改状态，而不是从磁盘恢复。要重新加载页面，最安全的方法是单击浏览器地址栏中的 Go To Address 按钮。

现在，您已经完成了组件部署，可以开始进行打包并与其他人分享。对组件进行打包非常简单：只需将所有编译过的类文件、模板、组件资源等全部包含到 jar 文件中，然后将生成的 faces-config.xml 放到 jar 文件根目录下的 META-INF 目录。尽管对资源进行打包比较简单，但是将组件所需的资源（例如映像、Javascript 文件和 css 文件）提供给浏览器就较为复杂。

要解决资源供给问题，有若干解决方案可供选择。JSFTemplating 提供了一个非常高效的 FileStreamer 服务（参见 javadoc），它提供了使用 JSF ViewHandler 的资源。Shale Remoting 提供了类似的功能，但是使用了阶段侦听器。一些方法使用了一个 servlet，但是 servelet 需要一个 web.xml 入口，这一点并不理想。其他项目使用其他方式解决这一问题。

在本文的示例中，Jason Lee 决定使用他以前编写的阶段侦听器，从而代替 Ken Paulsen 的 JSFTemplating 方法,该侦听器曾在他的其他组件中使用过。可通过位于 src/java/main/com/sun/faces/mojarra/util/StaticResourcePhaseListener.java 的源代码树找到这个阶段侦听器。. 模板文件中为每个资源指定的 URL 就是专门针对这个阶段侦听器，因此可以快速从 jar 文件中提取资源，而不是将请求作为普通的 JavaServer Faces 请求进行处理。

在本文中，您了解了如何使用 GlassFish JSFTemplating 和 Project Woodstock 提供的解决方案简化 JavaServer Faces 组件的开发。希望 Project Scales 在未来能够托管更多此类型的组件。访问该项目并贡献您自己的开源组件。