JSF自定义组件开发

http://www.blogjava.net/huliqing/archive/2008/03/14/186343.html


详细分析一个JSF组件的制作过程
以下是一个JSF组件所需的几个文件，涉及约5(包括js文件)个文件，主要文件两个（针对JSF1.2）
1.UIComponent 用于渲染组件自身，简单一点就是渲染html代码。（也可以使用Renderer类进行独立渲染）
2.UIComponentTag 组件的jsp标签处理程序类，主要用于指示组件在页面的显示及相关的属性等。
3.Javascript文件(可有可无） 如果你的组件要使用到较多的javascript，还是建议单独作为一个文件存在，可以使用一个servlet加载该js

4.tld文件(很简单) 这是一个标签库描述符文件,主要用于注册该组件所用到的属性，如:id,rendered，binding等
5.faces-config.xml（很简单）主要是用于注册你的组件


实际上制作一个JSF组件，基本上你只要处理好UIComponent及UIComponentTag即可，重点就是这两个，其它文件只是简单的收尾工作。
下面以我制作的一个实现双联动的选择框组件(Htmllinkage)为例进行说明,该组件在页面渲染了两个select,并可进行双联动选择，使用方法及效果在我的上一篇文章中 http://www.blogjava.net/huliqing/archive/2008/03/06/184315.html#184353
这里是介绍并分析隐藏在组件背后的默默无闻的代码，篇幅会较长，如果你对组件原理不感兴趣，那么你也可以只知道如何简单使用它就可以。看代码需要耐心，特别是看他人的代码,还要学会分析，分析代码给他人看也是一个锻炼逻辑思维能力的过程。

开始进入正题，下面是HtmlLinkage组件所需文件所对应的各个部分：
1.UIComponent -> biz.tbuy.share.components.linkage.HtmlLinkage;
2.UIComponentTag -> biz.tbuy.share.components.linkage.HtmlLinkageTag;
3.Javascript -> biz/tbuy/share/components/linkage/linkage.js; (js文件放在了同一个包中)
4.tld文件 -> Tcoco.tld
5.faces-config.xml -> faces-config.xml (最好以这一个名称命名,当你打为jar包后，JSF会自动加载jar内以faces-config.xml命名的文件)



================================================== 第一部分(UIComponent):HtmlLinkage
package biz.tbuy.share.components.linkage;

import biz.tbuy.share.components.TbuyExtensionsFilter;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Set;
import javax.faces.component.UIInput;
import javax.faces.context.FacesContext;
import javax.faces.context.ResponseWriter;

/**
*
* @author huliqing
*/
public class HtmlLinkage extends UIInput{

    // 当前文件所在的包路径，及相关的资源文件，如图片，JS等。以便于加载这些资源
    private static final String _PATH = "biz/tbuy/share/components/linkage/";
    private static final String _SCRIPT = "linkage.js";

    public HtmlLinkage() {

        setRendererType(null); // 因为组件自身渲染html代码，所以不需要外部renderer

    }

    // ------------------------------------------------------------ encode

    // 覆盖父类的渲染方法,这里就是渲染该组件在页面中所显示的html代码了
    // 实际上就是将本来在JSP中显示的代码搬到了这里来。
    @Override
    public void encodeEnd(FacesContext fc) throws IOException {

        ResponseWriter rw = fc.getResponseWriter();
        String clientId = getClientId(fc);
        encodeScript(fc); // 渲染javascript请求,你可以使用自定义的servlet处理该js请求,
        encodeSelectA(rw, clientId, fc); // 渲染第一个选择框
        encodeSelectB(rw, clientId, fc); // 渲染第二个选择框
        encodeHidden(rw, clientId); // 泻染一个隐藏的input框,后面说明
        encodeOnload(rw, clientId); // 主要用于初始化组件的状态

    }


    // 渲染第一个选择框
    private void encodeSelectA(ResponseWriter rw, String clientId, FacesContext fc)
    throws IOException {

        String id = clientId + ":selectA"; // 第一个select的名称及id
        String value = (String) getAttributes().get("param1");

        rw.startElement("select", this);
        rw.writeAttribute("name", id, null);
        rw.writeAttribute("id", id, null);
        if (value != null) rw.writeAttribute("value", value, null);
        rw.writeAttribute("onchange", "javascript:tbuy_linkage_select(this.value);", null);
        rw.writeAttribute("size", "1", null);
        rw.startElement("option", this);
        if (value != null) {

            rw.writeAttribute("value", value, null);
            rw.writeAttribute("selected", Boolean.TRUE, null);
            rw.writeText(value, null);

        }
        rw.endElement("option");
        rw.endElement("select");

    }

    // 渲染第二个选择框
    private void encodeSelectB(ResponseWriter rw, String clientId, FacesContext fc)
    throws IOException {

        String id = clientId + ":selectB"; // 第二个select的名称及id
        String value = (String) getAttributes().get("param2");

        rw.startElement("select", this);
        rw.writeAttribute("name", id, null);
        rw.writeAttribute("id", id, null);
        if (value != null) rw.writeAttribute("value", value, null);
        rw.writeAttribute("size", "1", null);
        rw.writeAttribute("style", "margin-left:5px;", null);
        rw.startElement("option", this);
        if (value != null) {

            rw.writeAttribute("value", value, null);
            rw.writeAttribute("selected", Boolean.TRUE, null);
            rw.writeText(value, null);

        }
        rw.endElement("option");
        rw.endElement("select");

    }

    // 渲染一个隐藏字段，该隐藏字段主要用于在页面存放所有可选项(有规律的字符串),
    // 即是将所有可用的选项组织成了一个有规律的字符串，存放于隐藏域中，以便js进行分析,最后的字符串的形式像这样(objStr)
    //aa,aa==aa_1,aa_1;aa_2,aa_2;aa_3,aa_3;@@bb,bb==bb_1,bb_1;bb_2,bb_2;bb_3,bb_3;@@cc,cc==cc_1,cc_1;cc_2,cc_2;cc_3,cc_3;

    private void encodeHidden(ResponseWriter rw, String clientId) throws IOException {

        // 将页面中绑定的Map类型的所有选顶转化为字符串形式,页面中的组件使用像是这样的：
        // <hu:linkage ... obj="#{TestBean.val2}"/>
        Object obj = this.getAttributes().get("obj"); // 也就是获取组件的obj属性所绑定的值
        String objStr = getAsString(obj); // 将obj转化为字符串形式存放于隐藏域中

        rw.startElement("input", this);
        rw.writeAttribute("id", clientId + ":obj", null);
        rw.writeAttribute("name", clientId + ":obj", null);
        rw.writeAttribute("type", "hidden", null);
        rw.writeAttribute("value", objStr, null);
        rw.endElement("input");

    }

    // 渲染一个js函数调用，在该组件渲染完毕之后调用tbuy_linkage_init对组件进行初始化
    private void encodeOnload(ResponseWriter rw, String clientId) throws IOException {

        rw.startElement("script", this);
        rw.writeAttribute("type", "text/javascript", null);
        rw.writeText("tbuy_linkage_init('" + clientId + "')", null);
        rw.endElement("script");

    }

    // 渲染一个JS文件的请求，实际上你也可以直接渲染所有js代码，但那样会很麻烦。
    private void encodeScript(FacesContext fc) throws IOException {

        ResponseWriter rw = fc.getResponseWriter();
        String contentPath = fc.getExternalContext().getRequestContextPath();
        rw.startElement("script", this);
        rw.writeAttribute("type", "text/javascript", null);
        rw.writeAttribute("src", contentPath +
        TbuyExtensionsFilter.TBUY_EXT_ID +
        TbuyExtensionsFilter.REQUEST_SCRIPT + "=" +
        _PATH + _SCRIPT, null);
        rw.endElement("script");

    }

    // -------------------------------------------------- process

    // 该方法主要是将组件的obj属性所绑定的值(所有可选项)转化为字符串,转化后的字符串像是这样的
    //aa,aa==aa_1,aa_1;aa_2,aa_2;aa_3,aa_3;@@bb,bb==bb_1,bb_1;bb_2,bb_2;bb_3,bb_3;@@cc,cc==cc_1,cc_1;cc_2,cc_2;cc_3,cc_3;
    private String getAsString(Object obj) {

        StringBuilder str = new StringBuilder();
        if (obj instanceof Map) {

            Map objm = (Map) obj;
            Set keys = objm.keySet();
            Iterator iter = keys.iterator();
            while (iter.hasNext()) {

                Object temp = iter.next();
                String[] keyArr = getAsStringArr(temp); // 处理第一维选顶,一律转为String[]
                str.append(keyArr[0] + "," + keyArr[1] + "==");
                Object valueObj = objm.get(temp);
                List<String[]> values = getAsList(valueObj);// 处理第二维
                for (String[] val : values) {

                    str.append(val[0] + "," + val[1] + ";");

                }
                str.append("@@");

            }

        }
        return str.toString();

    }

    // 这里相当于一个适配器，将String数组或String类型都转化成String数组返回
    private String[] getAsStringArr(Object obj) {

        if (obj instanceof String[]) {

            return ((String[]) obj);

        } else if (obj instanceof String) {

            String tt = (String) obj;
            return (new String[]{tt,tt});

        }
        return null;

    }

    // 参照上面
    private List<String[]> getAsList(Object obj) {

        List<String[]> strArr = new ArrayList<String[]>();
        if (obj instanceof List) {

            List temp = (List) obj;
            Iterator iter = temp.iterator();
            while (iter.hasNext()) {

                Object tt = iter.next();
                String[] val = getAsStringArr(tt);
                strArr.add(val);

            }
            return strArr;

        }
        return null;

    }

    // -------------------------------------------------- decode

    // 组件的解码,该方法在页面有回传（比如提交了表单form）的时候才会执行。
    @Override
    public void decode(FacesContext fc) {

        String clientId = getClientId(fc);// 获取当前组件的页面id
        Map<String, String> values = fc.getExternalContext().getRequestParameterMap();
        Map<String, String> val = new HashMap<String, String>(2);
        String valA = values.get(clientId + ":selectA"); // 获取两个select的当前所选的值
        String valB = values.get(clientId + ":selectB");
        this.setSubmittedValue(val);
        this.getValueExpression("param1").setValue(fc.getELContext(), valA);// 将值绑定到param1所绑定的后台bean的属性
        this.getValueExpression("param2").setValue(fc.getELContext(), valB);// 同上

    }

}


================================================== 第二部分(UIComponentTag):HtmlLinkageTag

HtmlLinkageTag类主要用于指定并绑定组件的各个属性,并关联到组件的核心类,如:HtmlLinkage

package biz.tbuy.share.components.linkage;

import javax.el.ValueExpression;
import javax.faces.component.UIComponent;
import javax.faces.webapp.UIComponentELTag;

/**
*
* @author huliqing
*/
public class HtmlLinkageTag extends UIComponentELTag{ // JSF1.2的时候建议扩展自UIComponentTag

    private ValueExpression param1; // 这里是组件在jsp页面中的三个自定义属性
    private ValueExpression param2;
    private ValueExpression obj;

    @Override
    public String getComponentType() {

        return "HtmlLinkage"; // 返回组件的类型，关联到了上面的HtmlLinkage

    }

    @Override
    public String getRendererType() {

        return null; // 因为组件自身渲染自己,所以不需要外部渲染器

    }

    @Override
    protected void setProperties(UIComponent ui) {

        super.setProperties(ui); // 先调用父类处理组件的已有属性如id,binding,redered...
        setValueBinding(ui, "param1", param1); // 处理并将三个自定义属性绑定到组件的attribute中
        setValueBinding(ui, "param2", param2);
        setValueBinding(ui, "obj", obj);

    }

    private void setValueBinding(UIComponent ui, String displayName, ValueExpression value) {

        if (value != null) {

            ui.setValueExpression(displayName, value); // 绑定属性

        }

    }

    // ------------------------------------------------------------ setter

    // 这几个方法是必须的,否则你的jsp页面中就无法使用相应的属性，
    // 会出现找不到setter方法的错误。
    public void setParam1(ValueExpression param1) {

        this.param1 = param1;

    }

    public void setParam2(ValueExpression param2) {

        this.param2 = param2;

    }

    public void setObj(ValueExpression obj) {

        this.obj = obj;

    }

    @Override
    public void release() {

        super.release(); // 释放资源
        this.param1 = null;
        this.param2 = null;
        this.obj = null;

    }


}

================================================== 第三部分(Javascript):linkage.js
这里是我的组件所用到的javascript,如果你的组件没有用到javascript.就没有必要这个部分了,
另一个关于javascript及可能用到的图片资源的装载问题，我使用的是一个servlet进行处理：
biz.tbuy.share.components.TbuyExtensionsFilter
类似myfaces的扩展过滤器，该类主要用将请求的js或图片资源处理并write到客户端,如果直接在组件
中渲染js会非常麻烦，也不容易修改。

var tbuy_linkage_clientId;// 组件id,为了不与其它组件的变量冲突，我都把变量名取得较长
var tbuy_linkage_selectA; // 第一个选择框
var tbuy_linkage_selectB; // 第二个选择框
var tbuy_linkage_params = new Array(); // 这里用于存放分析后的各个可选项

function tbuy_linkage_init(clientId) { // 初始化各个选项

    if (tbuy_linkage_clientId == null) {

        tbuy_linkage_clientId = clientId;
        // 获取隐藏域的值,该隐藏域在上面已经有说明,存放所有可选项的字符串
        var str = document.getElementById(tbuy_linkage_clientId + ":obj").value;
        // 获取页面中的两个select
        tbuy_linkage_selectA = document.getElementById(tbuy_linkage_clientId + ":selectA");
        tbuy_linkage_selectB = document.getElementById(tbuy_linkage_clientId + ":selectB");
        // 分析字符串,并存放于tbuy_linkage_params中
        tbuy_linkage_parse(str);
        var valueA = tbuy_linkage_selectA.value; // 原始值A
        var valueB = tbuy_linkage_selectB.value; // 原始值B
        tbuy_linkage_clearSelectA(); // 清除A框
        tbuy_linkage_setSelectA(); // 重设A框
        // 如果页面经过了回传请求，则需要将selectA的值设置回上一次所选择的值，否则每一次请求都会重置
        if (valueA != null) {

            tbuy_linkage_selectA.value = valueA;

        }
        // 根椐selectA框的值设置selectB框的值。
        tbuy_linkage_select(document.getElementById(tbuy_linkage_clientId + ":selectA").value);
        if (valueB != null) tbuy_linkage_selectB.value = valueB; // 同上

    }

}

// 初始化A选择框的各选项
function tbuy_linkage_setSelectA() {

    for (var i = 0; i < tbuy_linkage_params.length; i++) {

        var temp = tbuy_linkage_params[i];
        var opt = new Option();
        opt.value = temp.value;
        opt.text = temp.text;
        tbuy_linkage_selectA.options.add(opt);

    }

}

// 选择selectA框后根据其值设置selectB的值
function tbuy_linkage_select(val) {

    for (var i = 0; i < tbuy_linkage_params.length; i++) {

        var selA = tbuy_linkage_params[i];
        if (selA.value == val) {

            tbuy_linkage_clearSelectB(); // 清除selectB的值并重设
            tbuy_linkage_setSelectB(selA.objArr);

        }

    }

}

// 该方法用于清除selectA的所有选项,用于重设A框时所用
function tbuy_linkage_clearSelectA() {

    while (tbuy_linkage_selectA.hasChildNodes()) {

        tbuy_linkage_selectA.removeChild(tbuy_linkage_selectA.firstChild);

    }

}

// 同上
function tbuy_linkage_clearSelectB() {

    while (tbuy_linkage_selectB.hasChildNodes()) {

        tbuy_linkage_selectB.removeChild(tbuy_linkage_selectB.firstChild);

    }

}

// 设置selectB的各个选项
function tbuy_linkage_setSelectB(objArr) {

    for (var i = 0; i < objArr.length; i++) {

        var obj = objArr[i];
        var opt = new Option();
        opt.value = obj.value;
        opt.text = obj.text;
        tbuy_linkage_selectB.options.add(opt);

    }

}

// 该方法用于分析隐藏域中的值，即所有可选类型的字符串形式.字符串规律像是这样（可参照核心类HtmlLinkage中隐藏域的渲染）:
//aa,aa==aa_1,aa_1;aa_2,aa_2;aa_3,aa_3;@@bb,bb==bb_1,bb_1;bb_2,bb_2;bb_3,bb_3;@@cc,cc==cc_1,cc_1;cc_2,cc_2;cc_3,cc_3;@@
function tbuy_linkage_parse(str) {

    var strArr = new Array();
    strArr = str.split("@@");
    for (var i = 0; i < strArr.length - 1; i++) {

        var lineArr = strArr[i].split("==");
        var objKVArr = lineArr[0].split(",");
        var param = new Object();
        param.value = objKVArr[0];
        param.text = objKVArr[1];
        // 分析"=="号后面的子选项,即第二维的选项
        param.objArr = tbuy_linkage_getAsArray(lineArr[1]);
        tbuy_linkage_params[i] = param;

    }

}
// 配合上面的分析
function tbuy_linkage_getAsArray(valueStr) {

    var objArr = new Array();
    var valArr = new Array();
    valArr = valueStr.split(";");
    for (var i = 0; i < valArr.length - 1; i++) {

        var selArr = valArr[i].split(",");
        var param = new Object();
        param.value = selArr[0];
        param.text = selArr[1];
        objArr[i] = param;

    }
    return objArr;

}
================================================== 第四部分(tld文件):Tcoco.tld
为了让组件能在jsp页面中使用，还需要一个tld标签描述符，下面是我的组件的标签描述符，
实际上只是简单指明了该组件可用的属性.对应了HtmlLinkageTag中的各个属性(JSF1.2)

<?xml version="1.0" encoding="UTF-8"?>
<taglib xsi:schemaLocation="http://java.sun.com/xml/ns/javaee webjsptaglibrary_2_1.xsd"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.1">

    <description>This is the jsp tag library for my components Tcoco</description>

    <!-- 给自己指定一个组件库名称 -->
    <display-name>Tcoco</display-name>
    <short-name>Tcoco</short-name>

    <!-- 给组件库指定一个版本 -->
    <tlib-version>0.9.1</tlib-version>

    <!-- 指定一个uri,该uri指定了使用该组件库所需要引入到jsp页面中的标签,你可以指定其它的，
    但在jsp页面中的uri必须与这里匹配,如：
    <%@taglib prefix="coco" uri="http://www.tbuy.biz/Tcoco"%>
    <%@taglib prefix="f" uri="http://java.sun.com/jsf/core"%>
    <%@taglib prefix="h" uri="http://java.sun.com/jsf/html"%>
    -->
    <uri>http://www.tbuy.biz/Tcoco</uri>

    <tag>

        <description>
        组件的名称、所关联的Tag类的全限定类名及各个可用属性，
        只有在这里注册了的属性，在JSP页面中才可以使用
        </description>
        <name>linkage</name>
        <tag-class>

            biz.tbuy.share.components.linkage.HtmlLinkageTag

        </tag-class>
        <attribute>

            <name>id</name>

        </attribute>
        <attribute>

            <name>binding</name>

        </attribute>
        <attribute>

            <name>rendered</name>

        </attribute>
        <attribute>

            <name>param1</name>
            <deferred-value>

                <type>java.lang.String</type>

            </deferred-value>

        </attribute>
        <attribute>

            <name>param2</name>
            <deferred-value>

                <type>java.lang.String</type>

            </deferred-value>

        </attribute>
        <attribute>

            <name>obj</name>
            <deferred-value>

                <type>java.lang.Object</type>

            </deferred-value>

        </attribute>

    </tag>

</taglib>
================================================== 第五部分(faces-config.xml文件):faces-config.xml
将组件注册到faces-config.xml中,以下是faces-config.xml文件的1.2形式

<?xml version='1.0' encoding='UTF-8'?>
<faces-config version="1.2"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd">

    <!-- 主要就是将你的组件的核心类声明一下就可以了，与tld文件同样都是比较简单的 -->
    <component>

        <component-type>HtmlLinkage</component-type>
        <component-class>

            biz.tbuy.share.components.linkage.HtmlLinkage

        </component-class>

    </component>

</faces-config>

--------------------------------------------------------------------

好了，以上就是制作一个组件所需要用到的各个部分，也是一个完整示例，针对于JSF1.2。
因为加入了一些javascript,所以看起来复杂了一些，可能还有一些说得不够清楚的，暂时这样吧，有需要再补充。
关于组件的使用示例，可以查看我的其它文章。
现在制作一些JSF组件还是比较繁琐麻烦的，不过JSF2.0之后可能有较大简化。期待吧！