konhon

<taglib>的子元素

Element
Description

tlib-version
Tag庫的版本

jsp-version
Tag庫所需要的jsp的版本

short-name
助記符，tag的一個(gè)別名（可選）

uri
用于確定一個(gè)唯一的tag庫

display-name
被可視化工具（諸如Jbuilder）用來顯示的名稱（可選）

small-icon
被可視化工具（諸如Jbuilder）用來顯示的小圖標(biāo)（可選）

large-icon
被可視化工具（諸如Jbuilder）用來顯示的大圖標(biāo)（可選）

description
對(duì)tag庫的描述（可選）

listener
參見下面listener元素

tag
參見下面tag 元素

Listener元素

一個(gè)tag庫可能定義一些類做為它的事件偵聽類，這些類在TLD中被稱為listener 元素，jsp服務(wù)器將會(huì)實(shí)例化這些偵聽類，并且注冊(cè)它們。Listener元素中有一個(gè)叫l(wèi)istener-class的子元素，這個(gè)元素的值必須是該偵聽類的完整類名。

Tag元素

每個(gè)tag元素在tag庫中都要指出它的名字、類名、腳本變量、tag的屬性。其中腳本變量的值可以直接在TLD中定義或通過tag附加信息的類來取得。每個(gè)屬性描述了這個(gè)屬性是否可以省略，它的值是否可以通過<%= …%>這樣的JSP語法來獲得，以及屬性的類型。

每一個(gè)tag在TLD中對(duì)應(yīng)一個(gè)tag元素，下表是tag元素的子元素：

Tag元素的子元素

元素名稱
描述

name
獨(dú)一無二的元素名

tag-class
Tag標(biāo)簽對(duì)應(yīng)的tag處理類

tei-class
javax.servlet.jsp.tagext.TagExtraInfo的子類，用于表達(dá)腳本變量（可選）

body-content
Tag標(biāo)簽body的類型

display-name
被可視化工具（諸如Jbuilder）用來顯示的名稱（可選）

small-icon
被可視化工具（諸如Jbuilder）用來顯示的小圖標(biāo)（可選）

large-icon
被可視化工具（諸如Jbuilder）用來顯示的大圖標(biāo)（可選）

description
此tag標(biāo)簽的描述

variable
提供腳本變量的信息（同tei-class）(可選)

attribute
Tag標(biāo)簽的屬性名

以下章節(jié)介紹對(duì)于不同類型的tag，如何具體地實(shí)現(xiàn)它們。

簡單的tag

tag處理類

簡單的tag處理類必須實(shí)現(xiàn)Tag接口的doStartTag和doEndTag方法。當(dāng)jsp引擎碰到tag標(biāo)簽的開頭時(shí)，doStartTag被調(diào)用，因?yàn)楹唵蔚膖ag沒有body，所以此方法將返回 SKIP_BODY。當(dāng)jsp引擎碰到tag標(biāo)簽的結(jié)尾時(shí)，doEndTag被調(diào)用，如果余下的頁面還要被計(jì)算，那它將返回EVAL_PAGE,否則將會(huì)返回SKIP_PAGE。

以下是例子：對(duì)于標(biāo)簽 <tt:simple /> ，它的tag處理類實(shí)現(xiàn)如下：

public SimpleTag extends TagSupport

{

public int doStartTag() throws JspException

{

try{

pageContext.getOut().print(“Hello.”);

}catch(Exception e){

throw new JspTagException(“SimpleTag: “ + e.getMessage());

}

return SKIP_BODY;

}

public int doEndTag()

{

return EVAL_PAGE;

}

}

注意：如果tag標(biāo)簽沒有內(nèi)容的話，那必須定義body-content元素為空，例如

<body-content>empty</body-content>

帶屬性的tag標(biāo)簽

tag處理類

對(duì)于tag標(biāo)簽的每個(gè)屬性，你必須依照J(rèn)avaBeans規(guī)范來定義其屬性，以及get和set方法。以struts的logic:present 標(biāo)簽為例，

<logic:present parameter=”Clear”>

與此相應(yīng)，此tag處理類應(yīng)有如下方法和定義：

protected String parameter = null;

public String getParameter()

{

return this.parameter;

}

public void setParameter(String parameter)

{

this.parameter = parameter;

}

注意：如果你的屬性名為id，而且你的tag處理類是從TagSupport類繼承的，那你就不需要定義它的屬性和set和get方法,因?yàn)樗麄冊(cè)缫言赥agSupport被定義過了。

Attribute元素

對(duì)于tag標(biāo)簽的每個(gè)屬性，你必須定義它是否必須的，它的值是否可以用諸如<%= …%>的表達(dá)式來獲得，以及它的類型（可選），如果不指定它的類型，那就默認(rèn)為是java.lang.String類型。如果rtexprvalue元素被定義為true或yes，那么在type元素中就定義了attribute的返回類型。

<attribute>

<name>attr1</name>

<required>true|false|yes|no</required>

<rtexprvalue>true|false|yes|no</rtexprvalue>

<type>attribute的返回類型（只用當(dāng)rtexprvalue為真是才有效）</type>

</attribute>

如果tag的某個(gè)屬性不是必須的，那tag處理類會(huì)自動(dòng)提供一個(gè)缺省值。

例如，在logic:present這個(gè)tag標(biāo)簽中定義了一個(gè)屬性叫parameter，但它不是必須的，而且它可以被諸如<%= …%>的表達(dá)式來賦值。

<tag>

<name>present</name>

<tag-class>org.apache.struts.taglib.logic.PresentTag</tag-class>

<body-content>JSP</body-content>

…

<attribute>

<name>parameter</name>

<required>false</required>

<rtexprvalue>true</rtexprvalue>

</attribute>

…

</tag>

屬性元素的校驗(yàn)

有關(guān)于tag標(biāo)簽的有效值可以從tag庫的說明文檔中獲得，當(dāng)JSP頁面被編譯時(shí)，jsp引擎會(huì)強(qiáng)制性地參照TLD中定義的規(guī)則進(jìn)行檢查。

還有一個(gè)方法也可以進(jìn)行屬性元素的校驗(yàn)，就是先繼承類TagExtraInfo，然后調(diào)用它的isValid方法。這個(gè)類同時(shí)也起到提供tag中定義的腳本變量信息的作用。

IsValid方法通過TagData對(duì)象來傳遞屬性信息，它包括著tag的所有的屬性名－值的信息。由于校驗(yàn)發(fā)生在運(yùn)行時(shí)刻，因此這個(gè)屬性的值將被賦值為TagData.REQUEST_TIME_VALUE。

例如tag標(biāo)簽<tt:twa attr1=”value1” />在TLD中定義如下：

<attribute>

<name>attr1</name>

<required>true</required>

<rtexprvalue>true</rtexprvalue>

</attribute>

這個(gè)定義說明了attr1能在運(yùn)行期間被賦值。

以下的isValid方法檢查attr1屬性的值是否屬于Boolean類型。注意由于attr1能在運(yùn)行刻被賦值，那么isValid方法必須檢查tag用戶是否對(duì)此tag進(jìn)行了運(yùn)行時(shí)刻賦值。

Public class TwaTEI extends TagExtraInfo

{

public boolean isValid(Tagdata data)

{

Object o = data.getAttribute(“attr1”);

If(o != null && o != TagData.REQUEST_TIME_VALUE)

{

if( ( (String)o).toLowerCase().equals(“true”) || 

((String)o).toLowerCase().equals(“false”) )

return true;

else

return false;

}

else

return true;

}

}

帶body的tag

tag處理類

如果tag標(biāo)簽含有內(nèi)容，那處理方式會(huì)略微有些不同，而且還要視tag處理類是否要與body交互的情況而定。如果要與body交互，那我們認(rèn)為tag處理類要可能要對(duì)body進(jìn)行操作。

Tag處理類不與body交互

如果tag處理類不與body交互，tag處理類應(yīng)該實(shí)現(xiàn)Tag接口或從TagSupport中派生，如果body要被計(jì)算，那么doStartTag方法應(yīng)返回 EVAL_BODY_INCLUDE，否則應(yīng)返回SKIP_BODY。

如果tag處理類要對(duì)body反復(fù)運(yùn)算，則它應(yīng)該實(shí)現(xiàn)IterationTag或從TagSupport中派生。如果tag處理類認(rèn)為body還未計(jì)算完的話，那它的doStartTag方法和doAfterBody方法必須返回EVAL_BODY_AGAIN。

Tag處理類與body交互

如果tag處理類與body交互，那tag處理類應(yīng)實(shí)現(xiàn)BodyTag接口或從BodyTagSupport中派生。這種tag處理類一般要實(shí)現(xiàn)doInitBody和doAfterBody方法。

Body允許一些方法來讀寫它的內(nèi)容。Tag處理類可以調(diào)用body內(nèi)容的getString或getReader方法來從body中提取信息，也可用 writeOut(out) 方法來將body的內(nèi)容寫入到out對(duì)象中。其中out對(duì)象通過tag處理類的getPreviousOut方法來獲得。

如果body的內(nèi)容需要被計(jì)算，那么doStartTag方法必須返回EVAL_BODY_BUFFERED，否則，它將返回 SKIP_BODY。

doInitBody 方法

此方法在body內(nèi)容已經(jīng)設(shè)好，但未被計(jì)算之前被調(diào)用。你可以根據(jù)不同的body內(nèi)容來制定初始化策略。

doAfterBody方法

此方法在body內(nèi)容已被計(jì)算后進(jìn)行調(diào)用。

和doStartTag方法一樣，doAfterBody方法返回一個(gè)指示符指示是否要繼續(xù)計(jì)算body，如果要繼續(xù)計(jì)算，則doAfterBody應(yīng)返回EVAL_BODY_BUFFERED，否則，它應(yīng)返回SKIP_BODY。

release 方法

tag處理類調(diào)用此方法將它的狀態(tài)重置為初始狀態(tài)，并釋放所有的私有資源。

以下的例子讀取body的內(nèi)容（其中含有一條sql語句），然后將它傳遞給一個(gè)對(duì)象，讓它進(jìn)行查詢。由于此處body不須重新計(jì)算，所以doAfterBody會(huì)返回SKIP_BODY。

Public class QueryTag extends BodyTagSupport

{

public int doAfterBody() throws JspTagException

{

BodyContent bc = getBodyContent();

//將body的內(nèi)容以字符串的格式提取出來

String query = bc.getString();

//清除body

bc.clearBody();

try{

Statement stmt = connection.createStatement();

Result result = stmt.executeQuery(query);

}catch(SQLException e){

throw new JspTagException(“queryTag: “ + e.getMessage() );

return SKIP_BODY;

}

}

body-content元素

由于tag可能會(huì)有body，你必須用body-content元素來指定body內(nèi)容的類型：

<body-content>JSP|tagdependent</body-content>

如果body的內(nèi)容是定制的或內(nèi)部的tag、腳本元素、或HTML廣本，則歸類為JSP類型。其他的類型，比如上面代碼所述的?D?D將sql statement類傳給 query tag的這種類型應(yīng)該標(biāo)為tagdependent。

注意：實(shí)際上body-content的值并不影響tag處理類對(duì)body內(nèi)容的處理，它僅僅是被tag編輯工具用來描述此body的內(nèi)容。

用tags定義腳本變量

tag處理類

tag處理類負(fù)責(zé)創(chuàng)建或設(shè)置頁面中定義的腳本變量，用pageContext.setAttribute(name,value,scope)或pageContext.setAttribute(name,value)方法來實(shí)現(xiàn)。一般來說，tag處理類通過腳本變量的名稱來獲取它，腳本變量的名稱一般可用get方法來獲得。

如果腳本變量的值依賴于tag處理類中的上下文中某一對(duì)象，那它可用pageContext.getAttribute(name,scope)方法來找到那個(gè)對(duì)象。一般的處理過程是tag處理類先找到腳本變量，再對(duì)其進(jìn)行處理，然后用pageContext.setAttribute(name,object)的方法來設(shè)置它的新值。

對(duì)象的生存周期(scope)如下表：

對(duì)象的生存周期表

名字
可訪問范圍
生存周期

page
當(dāng)前頁面
一直有效，除非頁面向客戶提交響應(yīng)或重定向到一個(gè)新頁面

request
當(dāng)前頁面或當(dāng)前頁面重定向到的頁面
一直有效，除非頁面向客戶提交響應(yīng)

session
當(dāng)前頁面或在同一瀏覽器窗口中的頁面
一直有效,除非關(guān)閉當(dāng)前瀏覽器、超時(shí)、網(wǎng)絡(luò)故障

application
整個(gè)web應(yīng)用程序的所有請(qǐng)求
一直有效，除非發(fā)生網(wǎng)絡(luò)故障、服務(wù)器故障

提供關(guān)于腳本變量的信息

以下示例定義了一個(gè)名為“book”的腳本變量，用來訪問程序中關(guān)于書的信息：

<bean:define id=”book” name=”bookDB” property=”bookDetails” type=”database.BookDetails” />

<font color=”red” size=”+2” >

<%= messages.getString(“CartRemoved”) %>

<strong><jsp:getProperty name=”book” property=”title” /></strong>

</font>

當(dāng)包含此tag的JSP頁面被編譯時(shí)，jsp引擎會(huì)自動(dòng)生成關(guān)于此book的同步的代碼（同步可以避免幾個(gè)客戶同時(shí)訪問此book時(shí)造成的沖突），要生成同步代碼，jsp引擎需要知道此腳本變量的如下信息：

· 腳本變量名稱

· 腳本變量所屬的類

· 此腳本變量是否引用了一個(gè)新的或已存在的對(duì)象

· 此腳本變量的有效性

有兩種辦法可以向jsp引擎提供關(guān)于腳本變量的信息：在TLD中定義variable子元素，或用tei-class子元素定義一個(gè)額外tag信息類。用variable最簡單，但可能降低了一些靈活性。

Variable元素

Variable元素有如下子元素：

· name-given ?D?D 給出的名字，是一個(gè)常量

· name-from-attribute?D?D 屬性名，在編譯時(shí)給出的屬性名

name-given或name-from-attribute兩者必須選一，但以下子元素是可選的：

· variable-class?D?D變量的類型，缺省為java.lang.String。

· declare?D?D此腳本變量是否引用了一個(gè)新對(duì)象，缺省為True。

· scope?D?D腳本變量的范圍，缺省為NESTED。下表描述了scope的幾種類型：

腳本變量的有效范圍

值
有效性
方法

NESTED
在tag標(biāo)簽的開始和結(jié)束之間
如果tag處理類實(shí)現(xiàn)BodyTag接口，則在doInitBody和doAfterBody中調(diào)用，否則在doStartTag中調(diào)用

AT_BEGIN
從tag標(biāo)簽的開始一直到頁面結(jié)束
如果tag處理類實(shí)現(xiàn)BodyTag接口，則在doInitBody、doAfterBody和doEndTag中調(diào)用，否則在doStartTag和doEndTag中調(diào)用

AT_END
從tag標(biāo)簽的結(jié)束一直到頁面結(jié)束
在doEndTag中調(diào)用

以struts為例，它的bean:define標(biāo)簽的實(shí)現(xiàn)遵循JSP1.1規(guī)范，此規(guī)范要求使用額外tag信息類來定義腳本變量。Variable元素是JSP1.2規(guī)范中加入的。以bean:define標(biāo)簽為例，你可以定義如下variable元素：

<tag>

<variable>

<name-from-attribute>id</name-from-attribute>

<variable-class>database.BookDetails</variable-class>

<declare>true</declare>

<scope>AT_BEGIN</scope>

</variable>

</tag>

額外tag信息類

如果要定義一個(gè)額外tag信息類，你要繼承javax.servlet.jsp.TagExtraInfo類。一個(gè)TagExtraInfo類必須實(shí)現(xiàn)getVariableInfo方法，此方法返回一個(gè)叫VariableInfo的數(shù)組類，它包括如下信息：

· 變量名

· 變量所屬類名

· 此變量是否引用了一個(gè)新對(duì)象

· 此變量的有效范圍

jsp引擎將一個(gè)名為data的參數(shù)傳給getVariableInfo方法，data中包括tag標(biāo)簽中的所有“屬性名?D?D屬性值”對(duì)。它可以用來向VariableInfo對(duì)象提供腳本變量的名字和類名。

以struts為例，它在bean:define標(biāo)簽中定義了一個(gè)名為DefineTei的額外tag信息類，用來向腳本變量提供信息。由于腳本變量的名稱（book）和類名（database.BookDetails）是通過tag標(biāo)簽的屬性來傳遞的，它們一般定義在VariableInfo的構(gòu)建代碼中，并且可用data.getAttributeString方法來得到這些信息。如果要允許book腳本變量能在從tag開始直到整個(gè)JSP頁面結(jié)束的范圍內(nèi)都可用的話，那它的范圍應(yīng)設(shè)為AT_BEGIN。如下所示：

public class DefineTei extends TagExtraInfo

{

public VariableInfo[] getVariableInfo(TagData data)

{

String type = data.getAttributeString(“type”);

If( type == null)

type = “java.lang.Object”;

return new VariableInfo[] {

new VariableInfo(data.getAttributeString(“id”), 

type,

true,

VariableInfo.AT_BEGIN)

};

}

}

注意：關(guān)于額外tag信息類的類名必須要在TLD中的tag標(biāo)簽下的tei-class子元素中定義。因此，DefineTei的tei-class中的定義看起來如下：
<tei-class>
org.apache.struts.taglib.bean.DefineTagTei
</tei-class>

具有協(xié)作關(guān)系的tag

tag通過共享對(duì)象來進(jìn)行協(xié)作，JSP技術(shù)支持2種方式的對(duì)象共享。

第一種方法是使用pageContext對(duì)象進(jìn)行對(duì)象的共享（可支持JSP頁面和tag處理類之間的共享），如果在一個(gè)tag處理類中要調(diào)用由另一個(gè)tag處理類創(chuàng)建的對(duì)象，可調(diào)用pageContext.getAttribute(name, scope)方法。

第二各方式的共享是對(duì)于tag之間有嵌套關(guān)系而言的，外層的tag所創(chuàng)建的對(duì)象對(duì)于內(nèi)層的tag來說是可以共用的。這種形式的共享的好處是減少了可能存在的重名沖突。

要訪問一個(gè)嵌套tag創(chuàng)建的對(duì)象，tag處理類必須先找到此嵌套tag對(duì)象，可用TagSupport的靜態(tài)方法 TagSupport.findAncestorWithClass(from, class)或TagSupport.getParent方法。前者在當(dāng)不確定此tag是否為嵌套tag對(duì)象時(shí)使用。一旦它的父類被找到，它就能訪問其所有動(dòng)態(tài)或靜態(tài)創(chuàng)建的對(duì)象。靜態(tài)創(chuàng)建的對(duì)象是父類的成員，而動(dòng)態(tài)創(chuàng)建的對(duì)象可能是父類的私有對(duì)象。諸如此類的對(duì)象可以用tag處理類的setValue方法來保存，用getValue方法來獲得。

下例闡述了以上兩種共享對(duì)象的方法。在這個(gè)例子當(dāng)中，一個(gè)查詢tag檢查一個(gè)名為connection的屬性名是否在doStartTag中被設(shè)置。如果connection屬性被設(shè)置，tag處理類從pageContext中得到這個(gè)connection對(duì)象。否則，此tag處理類先找到它的父tag處理類，然后從它的父tag處理類中找到connection對(duì)象。

public class QueryTag extends BodyTagSupport

{

private String connectionId;

public int doStartTag() throws JspException

{

String cid = getConnection();

if(cid != null)

{

//存在一個(gè)connection id，使用它。

connection = (Connection) pageContext.getAttribute(cid);

}

else

{

ConnectionTag ancestorTag = (ConnectionTag)findAncestorWithClass(this, 

ConnectionTag.class);

if(ancestorTag == null)

{

throw new JspTagException(“一個(gè)沒有connection屬性的查詢標(biāo)簽必須被一個(gè)connection標(biāo)記嵌套。”);

}

connection = ancestorTag.getConnection();

}

}

} 

此查詢標(biāo)簽在JSP頁面中的調(diào)用形式可以從以下2種定義中任選一種：

<tt:connection id=”con01” ...> ... </tt:connection>

<tt:query id=”balances” connection=”con01” >

SELECT account, balance FROM acct_table

where customer_num = <%= request.getCustno() %>

</tt:query>

或

<tt:connection ...>

<x:query id=”balances”>

SELECT account, balance FROM acct_table

where customer_num = <%= request.getCustno() %>

</x:query>

</tt:connection>

與此同時(shí)，在TLD中必須指定connection屬性為可選的，定義如下：

<tag>

...

<attribute>

<name>connection</name>

<required>false</required>

</attribute>

</tag>