中文web-app_2_3.dtd (轉)

中文web-app_2_3.dtd (轉)[@more@]

<!--
為了學習需要把這個文件翻譯了一遍，裡面的詞語和語法可能很不標準，而且也可能和原文相去甚
遠。但是對於我自己的理解確是有益的。覺得它對其他人也許有用，所以冒昧把它共享出來，希望
能對大家有用。要是由於我的錯誤翻譯而使使用者曲解了原文的意思，那麼我也只能深表遺憾了，
至於責任我是不負的。但是希望你能把錯誤指出來，由我來修改，或者是你自己加以改進，並共享
出來。

第一次字面翻譯這種型別的文件，錯誤和難讀之處估計很多，尤其是我對除了和之外
的知識所知甚少。然而大牛們是不屑於翻譯這種文件的（或者是我孤陋寡聞了），而我等無能之輩
只能勉而為之了。

說明：
()裡面的是原文,（）裡面的是原文中()裡面的內容

感謝： to:gaojunbo@csdn.expert">gaojunbo@csdn.expert提供的對於fully-qualified的理解。

">justfly@cnpoems.net
.1.31 2:03完稿。
--&gt

<!--
Sun Microsystems,Inc.2000-2001 版權所有。901 San Antonio Road, Palo Alto,
CA 94303,U.S.A. 保留所有權利.

這個產品或者文件在使用，複製，分發上受到了copyright and distributed的許可證限制保
護。在沒有得到任何形式的上的Sun和它的許可證頒發者的授權下，任何人或組織不可以以任何形
式reproduced(複製，再生)本產品或文件的任何部分。

第三方，包括字型技術，已經得到Sun的供應者的授權和許可。

Sun, Sun Microsystems, the Sun Logo, , , JavaServer Pages,
Java Naming and Directory Interface, JC, , JavaMail 和
Enterprise JavaBeans 在美國和其他國家已經註冊為Sun Microsystems, Inc的商標。

所有的SPARC商標得到SPARC International, Inc在美國和其他國家的使用許可和商標使用權
的授予。和SPARC商標有關的產品是以Sun Microsystems, Inc. 開發的一個體繫結構為基礎
的。

PostScript 是Adoe Systems, Inc.的一個註冊商標。

聯合收購： 商業軟體－政府服從標準的許可證期限和條件.
(Federal Acquisitions: Commercial Software - Government Users Subject to
Standard License Terms and Conditions. 這句話翻譯得不好)

除了根據法律無法拒絕的情況下,本文件不因任何任何明確的或者隱含的條件,請求,理由, 包括任
何含蓄的可做商品性的,因為特殊的目的或者非侵犯性的的理由而做修改。
--&gt

<!--
這是一個Servlet 2.3 描述器的 DTD。所有的Servlet 2.3 配置描述器(deployment
descriptor) 必須包含一個如下形式的DOCTYPE:
  /A>-app PUBLIC
 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 ">

--&gt

<!--
下面的這些約定將用於所有的描述器元素，除非有額外說明。

-在包含有PCDA他的元素(elements)中，在資料中頭部和尾部的空格可以忽略。

-值為“列舉型別(enumerated)”的元素中，其值是區分大小寫的。

-在同一個JAR file裡指明瞭一個的路徑名的元素中，相對方式的的檔名（不是用“/”開始
的路徑名）都被認為是相對於該JAR 檔案名稱空間的根()的。絕對形式的檔名（以“/”開始
的）也是指定了以該JAR檔案的根為起點的的名字。一般情況下，相對形式的檔名是首選的。也有
一個例外，為了servlet 的一致性,在.war檔案中,絕對形式的檔名是首選的。
--&gt

<!--
web-app元素是一個web應用的配置描述器的根。
--&gt
context-param*, filter*, filter-map*, listener*, servlet*,
servlet-mapping*, session-config?, mime-mapping*, welcome-file-list?,
error-page*, *, re-env-ref*, resource-ref*, security-constraint*,
login-config?, security-role*, env-entry*, -ref*,  ejb-local-ref*)>

<!--
auth-constraint元素標明瞭允許使用該資源集合的使用者角色。role-name(角色名)必須對應為
該web應用程式所定義的一個security－role元素中的role－name，或者是“*”,“*”是一個專門
保留的role-name,它是一個用來標明web應用程式的所有角色的語法符號。如果“*”和角色名同時
出現了，那麼容器就會認為它可以擔任所有的角色。如果沒有定義任何角色，則任何使用者都無法使
用該web應用程式中所包含的security-constraint描述的部分。噹噹決定是否有使用時，
容器對角色名是大小寫敏感的。

在security-constraint中使用
--&gt

<!--
auth-method元素用來定義web容器的鑑定機制。為了獲得對任何受授權保護的web資源的使
用許可權，使用者必須按照所本元素定義的機制來透過鑑證。本元素可選值為:"BASIC","DIGEST",
"FORM","CLIENT-CERT"。

在login-config中使用。
--&gt

<!--
context-param元素包含了web應用程式的servlet上下文（servlet context）的初始化引數
的宣告。
--&gt

<!--
description元素用來為其父元素提供文字說明。該元素用來提供所有web應用程式war檔案生產者
想要提供給web應用程式war檔案使用者（比如Deployer(配置器)）所需要的資訊。典型情況下，
web應用程式war檔案使用者所使用的工具在處理該description元素的父元素時會顯示該
description元素所提供的文字說明。

在auth-constraint, context-param, ejb-local-ref, ejb-ref,env-entry, filter,
init-param, resource-env-ref, resource-ref, run-as,security-role,
security-role-ref, servlet, user-data-constraint,web-app,
web-resource-collection中使用。
--&gt

<!--
display-name元素包含一個用來給工具顯示用的短名。該元素的值沒有唯一性要求。

在filter, security-constraint, servlet, web-app中使用

Example:

Employee Self Service
--&gt

<!--
distributable元素在一個web應用程式配置描述器中的出現標明瞭該web應用程式
可以配置到分散式的servlet容器中。

在web-app中使用
--&gt

<!--
ejb-link元素用來標明一個EJB引用(EJB reference)是連線到一個enterprise bean的。
ejb-link元素裡的名字由一個包含了所引用的ejb的ejb-jar檔案的路徑名和所應用的ejb名組成，
ejb名在ejb-jar路徑名之後，中間用一個"#"隔開。該路徑名是相對於引用了該
enterprise bean的web應用程式所在的war檔案的。這個元素允許多個enterprise beans用同
個ejb－name來唯一鑑別。(This allows multiple enterprise beans with the same
ejb-name to be uniquely ntified.)

在 ejb-local-ref, ejb-ref中使用

Examples:

 EmployeeRecord

 ../products/product.jar#ProductEJB

--&gt

<!--
ejb-local-ref元素是用來宣告一個對enterprise bean的本地 home的引用。該宣告由以下幾
部分組成：
  - 一個可選的說明(description)
  - 在引用了該enterprise bean的web應用程式的程式碼中所使用的該EJB的引用名。
  - 所引用的enterprise bean所期望的型別。(the expected type of the
  referenced enterprise bean)
  - 所期望的所引用的enterprise bean的本地 home和本地介面。(the expected local
  home and local interfaces of the referenced enterprise bean)
  - 可選的ejb-link資訊，用來標明所引用的enterprise bean。

在 web-app中使用
--&gt
 local-home, local, ejb-link?)>

<!--
ejb-ref元素是用來宣告一個對enterprise bean的home的引用。該宣告由以下幾部分組成：
  - 一個可選的說明(description)
  - 在引用了該enterprise bean的web應用程式的程式碼中所使用的該EJB的引用名。
  - 所引用的enterprise bean所期望的型別。(the expected type of the
  referenced enterprise bean)
  - 所期望的所引用的enterprise bean的home和介面。(the expected home and
  remote interfaces of the referenced enterprise bean)
  - 可選的ejb-link資訊，用來標明所引用的enterprise bean。

在web-app中使用
--&gt
 home, remote, ejb-link?)>

<!--
ejb-ref-name元素包含了一個EJB引用的名字。EJB引用是該web應用程式環境中的一個實體並且
是和java:comp/env上下文(context)關聯的。在該wen應用程式中，該名字必須是唯一的。

推薦在名字前面加上一個“ejb/”的字首。

在ejb-local-ref, ejb-ref中使用。

Example:

ejb/Payroll
--&gt

<!--
ejb-ref-type 元素包含了所引用enterprise bean的期望型別

它必須是以下之一
 Entity
 Session

在ejb-local-ref,ejb-ref中使用
--&gt

<!--
env-entry元素的內容是一個web應用程式的環境入口(environment entry)的宣告。該宣告由
一個可選的描述，該環境入口的名字，和一個可選的值組成。如果值沒有指定，則必須在配置的時
候提供一個。
--&gt
env-entry-type)>

<!--
env-entry-name 元素的內容是一個web應用程式的環境入口的名字。該名字是一個和
java:comp/env 上下文(context)相關的JNDI名字。該名字在一個web應用程式中必須是唯一
的。

Example:

minAmount

在 env-entry中使用
--&gt

<!--
env-entry-type 元素的內容是該web應用程式程式碼所期望的環境入口的值的完全形式
(fully-qualified)的Java型別。

其可選值有以下幾個：

 java.lang.Boolean
 java.lang.Byte
 java.lang.Character
 java.lang.String
 java.lang.Short
 java.lang.Integer
 java.lang.Long
 java.lang.Float
 java.lang.Double

在env－entry中使用
--&gt

<!--
env-entry-value元素的內容是一個web應用程式的環境入口的值。該值必須是能滿足所指定的
型別的只需要一個String引數的構造器的有效的String，或者是一個單獨的字元，這個時候所指
定的型別為必須java.lang.Character。

Example:

100.00

在 env-entry中使用
--&gt

<!--
error-code元素的內容是一個HTTP錯誤字，比如：404

在error-page中使用

<!--
error-page元素的內容是一個錯誤程式碼或者例外型別和該web應用程式裡面的一個資源的路徑的
對映。

在web-app中使用
--&gt

<!--
exception-type元素的內容是一個Java 例外型別的完全形式的類名。

在error-page中使用
--&gt

<!--
extension元素的內容是一個描述了一個副檔名的字串。比如：“txt”

在mime-mapping中使用
--&gt

<!--
filter 元素宣告瞭web應用程式裡的一個filter。透過filter-name的值作為引用，在
filter-mapping元素裡，filter被對映到一個Servlet或者是一個URL正規化上。透過
FilterConfig介面，filter可以使用配置描述器所宣告的初始化引數。

在web-app中使用
--&gt
filter-class,init-param*)>

<!--
filter-class的內容是該filter的類名的全稱。

在filter中使用
--&gt

<!--
filter-mapping元素宣告瞭在wen應用程式裡面的filter對映。容器根據filter－mapping聲
明來決定哪些filter按照什麼順序應用於一個請求上。容器匹配按照正常方式訪問一個Servlet的
請求URI。然後根據所有filter-mapping的servlet-name或者是url-pattern來決定哪個
filter可以應用到該URI之上。決定filter順序的是適合該URI的filter－mapping列表中
的filter順序。filter-name的值必須得是該配置描述器裡面的filter宣告的子元素
filter－name的值。

在web-app中使用
--&gt

<!--
filter的邏輯名。這個名字是用來對映filter的，在web應用程式裡各個filter-name是唯一的。

在filter,filter-mapping中使用
--&gt

<!--
form-error-page 元素定義了在web應用程式裡能找到登陸失敗時所顯示的錯誤頁面的位置。路
徑名的形式是相對於該WAR檔案的根以/打頭。

在form-login-config中使用
--&gt

<!--
form-login-config元素定義了以form方式的鑑定機制所需要使用的登陸和錯誤頁面。如果沒有
使用以form為基礎形式的鑑定機制，則該元素會被忽略。

在login-config中使用
--&gt

<!--
form-login-page元素定義了在該web應用程式的能找到登陸頁面可以的位置。路徑名的形式是相
對於該WAR檔案的根以/打頭。

在form-login-config中使用
--&gt

<!--
home元素的內容是enterprise beans的home 介面的完全形式的名字。

在ejb-ref中使用

Example:

com.aardvark.payroll.PayrollHome
--&gt

<!--
http-method元素的內容是一個HTTP方法（GET|POST|...）。

在web-resource-coloction中使用
--&gt

<!--
icon元素的內容是用來在GUI工具裡代表其父元素的，指定檔名字的小的和大的，GIF或者JPEG
icon圖片的small-icon和large-icon元素。

在filter,servlet,web-app中使用
--&gt

<!--
init-param元素的內容是一個作為servlet的初始化引數的名值對。

在filter,servlet中使用
--&gt

<!--
jsp-file元素的內容是一個以/打頭的指向該web應用程式裡的一個JSP檔案的完整路徑。

在servlet中使用
--&gt

<!--
large-icon元素的內容是一個32x32畫素的icon圖片檔案的檔名。該檔名是一個相對於該
web應用程式的war檔案的路徑名。

該圖片檔案可以是JPEG格式，也可以是GIF格式。它是由圖形工具使用的。

在icon中使用

Example:

employee-service-icon32x32.jpg
--&gt

<!--
listener元素標明瞭一個web應用程式的listener bean的配置屬性。

在web-app中使用
--&gt

<!--
listener-class宣告瞭該應用程式裡一個必須要註冊為該web應用程式listener bean的一個
類。其值為該listener類的完全形式的類名。

在listener中使用
--&gt

<!--
load-on-startup元素標明瞭該servlet必須得在該web應用程式開始執行的時候被裝入（初始
化一個，並呼叫該servlet的init()方法）。其值為一個可選的整數，標明瞭該servlet被
載入的次序。如果值為一個負整數或者該元素不出現的話，則容器可以在其選定的任何時候載入該
servlet。如果該值是一個正整數或者是零，則容器必須在啟動該應用程式的時候載入並初始化該
servlet。容器必須保證用小的整數標明的servlet比用大的整數標明的servlet先載入。容器可
以在用同個整數標明的servlet中自由的選擇載入次序。

在srvlet中使用
--&gt

<!--
local元素的內容是該enterprise bean的本地介面的完全形式的名字。

在ejb-local-ref中使用

--&gt

<!--
local-home元素的內容是該enterprise bean的本地home介面的完全形式的名字。

在ejb-local-ref中使用
--&gt

<!--
location元素的內容是該web應用程式裡的資源的位置，該位置是一個以“/”打頭的相對於該web
應用程式的根的相對路徑。

在error-page中使用
--&gt

<!--
login-config 元素的作用是配置該應用程式中應該使用什麼身份鑑定方法，所使用的域名
(realm name)，還有form登陸機制所需要的一些屬性。

在web-app中使用
--&gt

<!--
mime-mapping 元素定義了一個在字尾名和mime型別之間的對映。

在web-app中使用
--&gt

<!--
mime-type元素的內容是一個規定了的mime型別。比如：“text/plain”。
--&gt

<!--
param-name元素的內容是一個引數的名字。每個引數名字在該wenb應用程式中必須是唯一的。

在context-param,init-param中使用
--&gt

<!--
param-value元素的內容是該引數的值。

在context-param,init-param中使用
--&gt

<!--
realm-name元素指定了以HTTP為基礎的身份鑑定中所用的域名。

在login-config中使用
--&gt

<!--
remote元素的內容是該enterprise bean的遠端介面的完全形式的名字。
Example:

com.wombat.empl.EmployeeService
--&gt

<!--
res-auth元素指定了web應用程式的程式碼中是否包含有註冊到上的程式，或者指定了容
器是否可以因為web應用程式的需要而註冊到資源管理器上。如果是後者，則容器將會使用配置者
所提供的資訊。

其值必須為一下兩種之一：

 Application
 Container
在resource-ref中使用
--&gt

<!--
res-ref-name元素指定了一個資源管理器連線工廠引用的名字。這個名字是一個相對於
java:comp/env上下文(context)的JNDI名字。在一個web應用程式裡，該名字必須是唯一的。

在resource-ref中使用

<!--
res-sharing-pe元素指定了是否能共享透過資源管理器連線工廠引用得到的連線。如果指定了
該元素，則其值必須為以下兩者之一：

 Shareable
 Unshareable

預設值是 Shareable
在resource-ref中使用
--&gt

<!--
res-type 元素定義了資料來源的型別。該型別必須為可以為該資料來源所實現(be implemented)的
Java語言的類或者介面的完全形式的名字。

在resource-ref中使用
--&gt

<!--
resource-env-ref元素的內容是一個web應用程式對一個和一個web應用程式環境裡的資源聯合了
的管理物件的應用。它由以下幾個組成：一個可選的描述，該資源的環境引用的名字，和一個該web
應用程式程式碼所需要的資源環境引用型別的指明。

在web-app中使用

Example:

  /StockQueue
  javax.jms.Queue

--&gt
 resource-env-ref-type)>

<!--
resource-env-ref-name元素指定了一個資源環境引用的名字；它的值是該web應用程式程式碼中
所使用的環境實體的名字。該名字是一個和java:comp/env上下文(context)相關聯的JNDI名字，
它必須在該web應用程式中唯一。

在resource-env-ref中使用
--&gt

<!--
resource-env-ref-type元素指定了一個資源環境引用的型別。它是一個Java語言型別或者介面
的完全形式的名字。

在resource-evn-ref中使用
--&gt

<!--
resource-ref元素的內容是一個對web應用程式對一個外部資源的引用。它由一個可選的描述，一
個資源管理器連線工廠引用的名字，web應用程式程式碼中所需要的資源管理器連線工廠的型別指示，
應用程式或者容器的身份鑑證的型別和一個可選的從該資源所得連線得可共享性說明（其值為
Shareable或者是Unchareable）。

在web-app中使用

Example:

 
 /EmployeeAppDB
 javax..DataSource
 Container
 Shareable
 
--&gt
 res-sharing-scope?)>

<!--
role-link元素是一個對已定義角色得引用。該元素必須包含有在security-role元素中定義
的安全形色之一的名字。

在security-role-ref中使用
--&gt

<!--
role-name元素的內容是一個安全形色的名字。

該名字必須符合NMTOKEN詞法規則。

在auth-constraint, run-as, security-role, security-role-ref中使用
--&gt

<!--
run-as 元素指定了該web應用程式執行時所需用的執行身份。它由一個可選的描述和一個安全形色
的名字組成。

在servlet中使用
--&gt

<!--
security-constaint元素用來在聯合一個或多個web資源集合和安全約束時使用。

在web-app中使用
--&gt
auth-constraint?, user-data-constraint?)>

<!--
security-role元素定義了一個安全形色。該定義定義由一個可選的對該安全形色的說明和該安全
角色的名字組成。

在web-app中使用

Example:

 
 
  This role includes all employees who are authorized
  to access the employee service application.
 
 employee
 
--&gt

<!--
security-role-ref 元素的內容是一個該web應用程式程式碼裡的一個安全形色引用的宣告。該聲
明由一個可選的描述，程式碼中所用到的該安全形色的名字和一個可選的指向該安全形色的連結。如
果該安全形色沒有指定，則配置者必須選擇一個適當的安全形色。

role-name元素的值必須是一個在EJBContext.isCallerInrole(String roleName)方法或者
是HttpServletRequest.isUserInRole(String role)方法中的引數字串。

在servlet中使用

--&gt

<!--
servlet元素的內容是一個servlet的資料宣告。如果指定了一個jsp檔案而且load-on-startup
元素出現了，則該JSP必須被預編譯並載入。

在web-app中使用
--&gt
(servlet-class|jsp-file), init-param*, load-on-startup?, run-as?,
security-role-ref*)>

<!--
servlet-class元素的內容是該servlet類名的完全形式。

在servlet中使用
--&gt

<!--
servlet-mapping元素定義了一個在一個servlet和一個url正規化之間的對映。

在web-app中使用
--&gt

<!--
servlet-name元素的內容是該servlet的規範的名字，每個servlet名字在其所在web應用程式
中必須是唯一的。

在filter-mapping, servlet, servlet-mapping中使用
--&gt

<!--
session-config元素定義了該web應用程式的session引數。

在web-app中使用
--&gt

<!--
session-timeout元素定義了在該web應用程式中創造的session的預設超時時間間隔。該時間間
隔必須是一個以分鐘為單文的整數。如果該時間間隔是0或者更小，則容器預設為session永遠不會
超時。

在session-config中使用
--&gt

<!--
small-icon元素的內容是一個16x16畫素的icon圖片檔案的檔名。該檔名是一個相對於該
web應用程式的war檔案的路徑名。

該圖片檔案可以是JPEG格式，也可以是GIF格式。它是由圖形工具使用的。

在icon中使用

Example:

employee-service-icon16x16.jpg
--&gt

<!--
taglib元素是用來描述一個JSP標誌庫的。

在web-app中使用
--&gt

<!--
taglib-location元素的內容是一個能找到該標誌庫的描述檔案的路徑，如同一個相對於該web應
用程式的資源。

在tablib中使用
--&gt

<!--
tablib-uri元素描述了一個相對於web.xml文件位置的URI,唯一標誌著一個該web應用程式所使
用的標誌庫。

在tablib中使用
--&gt

<!--
transport-guarantee元素指定了客戶端和之間的資訊傳輸方式應該是NONE, INTEGRAL
還是CONFIDENTIAL。NONE表示該應用程式不需要任何傳輸保證。INTEGRAL表示應用程式要求在
客戶端和伺服器端的之間傳輸的資料需要在一種資料不會在傳輸過程中被修改的傳輸方式傳輸。
CONFIDENTIAL表示應用程式要求資料必須在一種防止其他實體看到傳輸的內容的方式中傳送。大
多數情況下，INTEGRAL或者CONFIDENTIAL表示需要使用。

在user-data-constraint中使用
--&gt

<!--
url-pattern元素的內容是對映的url正規化。它必須遵守Servlet API規範的11.2節所指定的規
則。

在filter-mapping,servlet-mapping,web-resource-collection中使用
--&gt

<!--
user-data-constraint元素用來指定在客戶端和容器之間的資料傳輸需要受到什麼樣的保護。

在security-constraint中使用
--&gt

<!--
web-resource-collection 元素用來識別一個安全約束在一個web應用程式裡所適用的資源和
HTTP請求方法的一個子集。如果沒有指定任何HTTP請求方法，則該安全約束對所有的HTTP請求方
法有效。

在security-constraint中使用
--&gt
url-pattern*, http-method*)>

<!--
web-resource-name元素的內容是該web資源集合的名字。

在web-resource-collection中使用
--&gt

<!--
welcome-file元素的內容是一個預設的歡迎頁面的名字，比如index.html

在welcome-file-list中使用。
--&gt

<!--
welcome-file-list的內容是welcome-file元素的序列表。

在web-app中使用
--&gt

<!--
ID機制允許用來加入額外配置資訊（在標準的配置描述器以外的資訊）的工具把非標準的資訊
在其他的檔案上，並可以很容易的從這些工具讀有的檔案上引用到標準的配置描述器上的資訊。

這些工具都不能把非標準的資訊加入到標準的配置描述器中。
--&gt