Java Servlet API中文說明文檔(1)

　　這份文檔描述了Java Servlet API的最新版本2.1版.所以,這本書對於Servlet的開發者及servlet引擎的開發者同樣適用.

　　Java Servlet API的組成

　　Java Servlet API由兩個軟體包組成：一個是對應HTTP的軟體包,另一個是不對應HTTP的通用的軟體包.這兩個軟體包的同時存在是的Java Servlet API能夠適應將來的其他請求-響應的協議.

　　這份文檔以及剛才提及的Javadoc格式的文檔都描述了這兩個軟體包,Javadoc格式的文檔還描述了你應該如何使用這兩個軟體包中的所有方法.

　　有關規範

　　你也許對下面的這些Internet規範感興趣,這些規範將直接影響到Servlet API的發展和執行.你可以從http: //info.internet.isi.edu/7c/in-notes/rfc/.cache 找到下面提到的所有這些RFC規範.

　　RFC 1738 統一資源定位器(URL)

　　RFC 1808 相關統一資源定位器

　　RFC 1945 超文本傳輸協議--HTTP/1.0

　　RFC 2045 多用途Internet郵件擴展(多用途網際郵件擴充協議(MIME))第一部分:Internet信息體格式

　　RFC 2046 多用途Internet郵件擴展(多用途網際郵件擴充協議(MIME))第二部分:媒體類型

　　RFC 2047 多用途網際郵件擴充協議(MIME)(多用途Internet郵件擴展)第三部分:信息標題擴展用於非ASCII文本

　　RFC 2048 多用途Internet郵件擴展(多用途網際郵件擴充協議(MIME))第四部分: 註冊步驟

　　RFC 2049 多用途Internet郵件擴展(多用途網際郵件擴充協議(MIME))第五部分:一致性標準和例子

　　RFC 2068 超文本傳輸協議 -- HTTP/1.1

　　RFC 2069 一個擴展HTTP:摘要訪問鑒定

　　RFC 2109 HTTP狀態管理機制

　　RFC 2145 HTTP 版本號的使用和解釋

　　RFC 2324 超文本Coffee Pot控制協議 (HTCPCP/1.0)

　　萬維網協會（http://www.w3.org）管理著這些協議的規範和執行.

　　有關Java Servlets

　　JavaTM servlets 是一個不受平台約束的Java小程序,它可以被用來通過多種方法擴充一個Web伺服器的功能.你可以把Servlet理解成Server上的 applets,它被編譯成位元組碼,這樣它就可以被動態地載入並用效地擴展主機的處理能力.

　　Servlet與applets不同的地方是,它不運行在Web瀏覽器或其他圖形化的用戶界面上.Servlet通過servlet引擎運行在Web伺服器中,以執行請求和響應,請求、響應的典型範例是HTTP協議.

　　一個客戶端程序,可以是一個Web瀏覽器,或者是非其他的可以連接上Internet的程序,它會訪問Web伺服器併發出請求.這個請求被運行在Web伺服器上的Servlet引擎處理,並返迴響應到Servlet.Servlet通過HTTP將這個響應轉發到客戶端.

　　在功能上,Servlet與CGI、NSAPI有點類似,但是,與他們不同的是：Servlet具有平台無關性.

　　Java Servlet概論

　　Servlet與其他普通的server擴展機制有以下進步：

　　它採用了不同的進程處理模式,所以它比CGI更快.

　　它使用了許多Web伺服器都支持的標準的API.

　　它繼承了Java的所有優勢,包括易升級以及平台無關性.

　　它可以調用Java所提供的大量的API的功能模塊.

　　這份文檔說明了Java Servlet API的類和介面的方法.有關更多的信息,請參看下面的API說明.

　　Servlet的生命周期

　　一個Java servlet具有一個生命周期,這個生命周期定義了一個Servlet如何被載入並被初始化,如何接收請求並作出對請求的響應,如何被從服務中清除.Servlet的生命周期被javax.servlet.Servlet這個介面所定義.

　　所有的Java Servlet都會直接地或間接地執行javax.servlet.Servlet介面,這樣它才能在一個Servlet引擎中運行. Servlet引擎是Web 伺服器按照Java Servlet API定製的擴展.Servlet引擎提供網路服務,能夠理解MIME請求,並提供一個運行Servlet的容器.

　　javax.servlet.Servlet介面定義了在Servlet的生命周期中特定時間以及特定順序被調用的方法.

　　Servlet的解析和載入

　　Servlet引擎解析並載入一個Servlet,這個過程可以發生在引擎啟動時,需要一個Servlet去響應請求時,以及在此之間的任何時候.

　　Servlet引擎利用Java類載入工具載入一個Servlet,Servlet引擎可以從一個本地的文件系統、一個遠程的文件系統以及網路載入Servlet.

　　Servlet的初始化

　　Servlet引擎載入Servlet后,Servlet引擎必須對Servlet進行初始化,在這一過程中,你可以讀取一些固定存儲的數據、初始化JDBC的連接以及建立與其他資源的連接.

　　在初始化過程中,javax.servlet.Servlet介面的init()方法提供了Servlet的初始化信息.這樣,Servlet可以對自己進行配置.

　　init()方法獲得了一個Servlet配置對象（ServletConfig）.這個對象在Servlet引擎中執行,並允許Servlet通過它獲處相關參數.這個對象是的Servlet能夠訪問ServletContext對象.

　　Servlet處理請求

　　Servlet被初始化之後,它已經可以處理來自客戶端的請求,每一個來自客戶端的請求都被描述成一個ServletRequest對象,Servlet的響應被描述成一個ServletResponse對象.

　　當客戶端發出請求時,Servlet引擎傳遞給Servlet一個ServletRequest對象和一個ServletResponse對象,這兩個對象作為參數傳遞到service()方法中.

　　Servlet 也可以執行ServletRequest介面和ServletResponse介面.ServletRequest介面是的Servlet有權使用客戶端發出的請求.Servlet可以通過ServletInputStream對象讀取請求信息.

　　ServletResponse介面允許Servlet建立響應頭和狀態代碼.通過執行這個介面,Servlet有權使用ServletOutputStream類來向客戶端返回數據.

　　多線程和映射

　　在多線程的環境下,Servlet必須能處理許多同時發生的請求.例外的情況是這個Servlet執行了SingleThreadModel介面,如果是那樣的話,Servlet只能同時處理一個請求.

　　Servlet依照Servlet引擎的映射來響應客戶端的請求.一個映射對包括一個Servlet實例以及一個Servlet返回數據的URL,例如：HelloServlet with /hello/index.html.

　　然而,一個映射可能是由一個URL和許多Servlet實例組成,例如：一個分散式的Servlet引擎可能運行在不止一個的伺服器中,這樣的話,每一個伺服器中都可能有一個Servlet實例,以平衡進程的載入.作為一個Servlet的開發者,你不能假定一個Servlet只有一個實例.

　　Servlet的卸載

　　Servlet引擎並不必需保證一個Servlet在任何時候或在服務開啟的任何時候都被載入.Servlet引擎可以自由的在任何時候使用或清除一個Servlet.因此,我們不能依賴一個類或實例來存儲重要的信息.

　　當Servlet引擎決定卸載一個Servlet時（例如,如果這個引擎被關閉或者需要讓資源）,這個引擎必須允許Servlet釋放正在使用的資源並存儲有關資料.為了完成以上工作,引擎會調用Servlet的destroy()方法.

　　在卸載一個Servlet之前,Servlet引擎必須等待所有的service()方法完成或超時結束（Servlet引擎會對超時作出定義）.當一個 Servlet被卸載時,引擎將不能給Servlet發送任何請求.引擎必須釋放Servlet並完成無用存儲單元的收集

　　Servlet映射技術

　　作為一個Servlet引擎的開發者,你必須對於如何映射客戶端的請求到Servlet有大量的適應性.這份說明文檔不規定映射如何發生.但是,你必須能夠自由地運用下面的所有技術：

　　映射一個Servlet到一個URL

　　例如,你可以指定一個特殊的Servlet它僅被來自/feedback/index.html的請求調用.

　　映射一個Servlet到以一個指定的目錄名開始的所有URL

　　例如,你可以映射一個Servlet到/catalog,這樣來自/catalog/、 /catalog/garden和 /catalog/housewares/index.html的請求都會被映射到這個Servlet.但是來自/catalogtwo 或 /catalog.html的請求沒被映射.

　　映射一個Servlet到所有以一個特定的欄位結尾的所有URL

　　例如,你可以映射一個來自於所有以in.thtml結尾的請求到一個特定的Servlet.

　　映射一個Servlet到一個特殊的URL /servlet/servlet_name.

　　例如,如果你建立了一個名叫listattributes的Servlet,你可以通過使用/servlet/listattributes來訪問這個Servlet.

　　通過類名調用Servlet

　　例如,如果Servlet引擎接收了來自/servlet/com.foo.servlet.MailServlet的請求,Servlet引擎會載入這個com.foo.servlet.MailServlet類,建立實例,並通過這個Servlet來處理請求.

　　Servlet環境

　　ServletContext 介面定義了一個Servlet環境對象,這個對象定義了一個在Servlet引擎上的Servlet的視圖.通過使用這個對象,Servlet可以記錄事件、得到資源並得到來自Servlet引擎的類（例如RequestDispatcher對象）.一個Servlet只能運行在一個Servlet環境中,但是不同的Servlet可以在Servlet引擎上有不同的視圖.

　　如果Servlet引擎支持虛擬主機,每個虛擬主機有一個Servlet環境.一個Servlet環境不能在虛擬主機之間共享.

　　Servlet引擎能夠允許一個Servlet環境有它自己的活動範圍.

　　例如,一個Servlet環境是屬於bank應用的,它將被映射到/bank目錄下.在這種情況下,一個對getContext方法的調用會返回/bank的Servlet環境.

　　HTTP會話

　　HTTP是一個沒有狀態的協議.要建立一個有效的Web服務應用,你必須能夠識別一個連續的來自遠端的客戶機的唯一的請求.隨著時間的過去,發展了許多會話跟蹤的技術,但是使用起來都比較麻煩.

　　Java Servlet API提供了一個簡單的介面,通過這個介面,Servlet引擎可以有效地跟蹤用戶的會話.

　　建立Session

　　HTTP是一個請求-響應協議,一個會話在客戶機加入之前會被認為是一個新的會話.加入的意思是返回會話跟蹤信息到伺服器中,指出會話已被建立.在客戶端加入之前,我們不能判斷下一個客戶端請求是目前會話的一部分.

　　在下面的情況下,Session會被認為是新的Session.

　　客戶端的Session在此之前還不知道

　　客戶端選擇不加入Session,例如,如果客戶端拒絕接收來自伺服器的cookie

　　作為一個Servlet的開發者,你必須決定你的Web應用是否處理客戶機不加入或不能加入Session.伺服器會在Web伺服器或Servlet規定的時間內維持一個Session對象.當Session終止時,伺服器會釋放Session對象以及所有綁定在Session上的對象.

　　綁定對象到Session中

　　如果有助於你處理應用的數據需求,你也許需要綁定對象到Session中,你可以通過一個唯一的名字綁定任何的對象到Session中,這時,你需要使用 HttpSession對象.任何綁定到Session上的對象都可以被處理同一會話的Servlet調用.

　　有些對象可能需要你知道什麼時候會被放置到Session中或從Session中移開.你可以通過使用HttpSessionBindingListener介面獲得這些信息.當你的應用存儲數據到Session中,或從Session中清除數據,Servlet都會通過HttpSessionBindingListener檢杳什麼類被綁定或被取消綁定.這個介面的方法會通報被綁定或被取消綁定的對象.

　　API對象的說明

　　這一部分包含了對Java Servlet API的全部類和介面的詳細說明.這個說明與Javadoc API差不多,但是這份文檔提供了更多的信息.

　　API包含了兩個軟體包,十二個介面和九個類.

　　軟體包：javax.servlet

　　所包含的介面：RequestDispatcher；Servlet；ServletConfig；ServletContext；ServletRequest；ServletResponse；SingleThreadModel.

　　所包含的類：GenericServlet；ServletInputStream；ServletOutputStream；ServletException；UnavailableException.

　　一、RequestDispatcher介面：

　　定義：

　　public interface RequestDispatcher;

　　定義一個對象,從客戶端接收請求,然後將它發給伺服器的可用資源（例如Servlet、CGI、HTML文件、JSP文件）.Servlet引擎創建request dispatcher對象,用於封裝由一個特定的URL定義的伺服器資源.

　　這個介面是專用於封裝Servlet的,但是一個Servlet引擎可以創建request dispatcher對象用於封裝任何類型的資源.

　　request dispatcher對象是由Servlet引擎建立的,而不是由Servlet開發者建立的.

　　方法

　　1、forward

　　public void forward(ServletRequest request, ServletReponse response)

　　throws ServletException, IOException;

　　被用來從這個Servlet向其它伺服器資源傳遞請求.當一個Servlet對響應作了初步的處理,並要求其它的對象對此作出響應時,可以使用這個方法.

　　當request對象被傳遞到目標對象時,請求的URL路徑和其他路徑參數會被調整為反映目標對象的目標URL路徑.

　　如果已經通過響應返回了一個ServletOutputStream對象或PrintWriter對象,這個方法將不能使用,否則,這個方法會拋出一個IllegalStateException.

　　2、include

　　public void include(ServletRequest request, ServletResponse response)

　　throws ServletException, IOException

　　用來包括發送給其他伺服器資源的響應的內容.本質上來說,這個方法反映了伺服器端的內容.

　　請求對象傳到目標對象後會反映調用請求的請求URL路徑和路徑信息.這個響應對象只能調用這個Servlet的ServletOutputStream對象和PrintWriter對象.

　　一個調用include的Servlet不能設置頭域,如果這個Servlet調用了必須設置頭域的方法（例如cookie）,這個方法將不能保證正常使用.作為一個Servlet開發者,你必須妥善地解決那些可能直接存儲頭域的方法.例如,即使你使用會話跟蹤,為了保證session的正常工作,你必須在一個調用include的Servlet之外開始你的session

　　二、Servlet介面.

　　定義

　　public interface Servlet

　　這個介面定義了一個Servlet：一個在Web伺服器上繼承了這個功能的Java類.

　　方法

　　1、init

　　public void init(ServletConfig config) throws ServletException;

　　Servlet引擎會在Servlet實例化之後,置入服務之前精確地調用init方法.在調用service方法之前,init方法必須成功退出.

　　如果init方法拋出一個ServletException,你不能將這個Servlet置入服務中,如果init方法在超時範圍內沒完成,我們也可以假定這個Servlet是不具備功能的,也不能置入服務中.

　　2、service

　　public void service(ServletRequest request, ServletResponse response)

　　throws ServletException, IOException;

　　Servlet引擎調用這個方法以允許Servlet響應請求.這個方法在Servlet未成功初始化之前無法調用.在Servlet被初始化之前,Servlet引擎能夠封鎖未決的請求.

　　在一個Servlet對象被卸載后,直到一個新的Servelt被初始化,Servlet引擎不能調用這個方法

　　3、destroy

　　public void destroy();

　　當一個Servlet被從服務中去除時,Servlet引擎調用這個方法.在這個對象的service方法所有線程未全部退出或者沒被引擎認為發生超時操作時,destroy方法不能被調用.

　　4、getServletConfig

　　public ServletConfig getServletConfig();

　　返回一個ServletConfig對象,作為一個Servlet的開發者,你應該通過init方法存儲ServletConfig對象以便這個方法能返回這個對象.為了你的便利,GenericServlet在執行這個介面時,已經這樣做了.

　　5、getServletInfo

　　public String getServletInfo();

　　允許Servlet向主機的Servlet運行者提供有關它本身的信息.返回的字元串應該是純文本格式而不應有任何標誌（例如HTML,XML等）.

　　三、ServletConfig介面

　　定義

　　public interface ServletConfig

　　這個介面定義了一個對象,通過這個對象,Servlet引擎配置一個Servlet並且允許Servlet獲得一個有關它的ServletContext介面的說明.每一個ServletConfig對象對應著一個唯一的Servlet.

　　方法

　　1、getInitParameter

　　public String getInitParameter(String name);

　　這個方法返回一個包含Servlet指定的初始化參數的String.如果這個參數不存在,返加空值.

　　2、getInitParameterNames

　　public Enumeration getInitParameterNames();

　　這個方法返回一個列表String對象,該對象包括Servlet的所有初始化參數名.如果Servlet沒有初始化參數,getInitParameterNames返回一個空的列表.

　　3、getServletContext

　　public ServletContext getServletContext();

　　返回這個Servlet的ServletContext對象.

　　四、ServletContext介面

　　定義

　　public interface ServletContext

　　定義了一個Servlet的環境對象,通過這個對象,Servlet引擎向Servlet提供環境信息.

　　一個Servlet的環境對象必須至少與它所駐留的主機是一一對應的.在一個處理多個虛擬主機的Servlet引擎中（例如,使用了HTTP1.1的主機頭域）,每一個虛擬主機必須被視為一個單獨的環境.此外,Servlet引擎還可以創建對應於一組Servlet的環境對象.

　　方法

　　1、getAttribute

　　public Object getAttribute(String name);

　　返回Servlet環境對象中指定的屬性對象.如果該屬性對象不存在,返回空值.這個方法允許訪問有關這個Servlet引擎的在該介面的其他方法中尚未提供的附加信息.

　　2、getAttributeNames

　　public Enumeration getAttributeNames();

　　返回一個Servlet環境對象中可用的屬性名的列表.

　　3、getContext

　　public ServletContext getContext(String uripath);

　　返回一個Servlet環境對象,這個對象包括了特定URI路徑的Servlets和資源,如果該路徑不存在,則返回一個空值.URI路徑格式是/dir/dir/filename.ext.

　　為了安全,如果通過這個方法訪問一個受限制的Servlet的環境對象,會返回一個空值.

　　4、getMajorVersion

　　public int getMajorVersion();

　　返回Servlet引擎支持的Servlet API的主版本號.例如對於2.1版,這個方法會返回一個整數2.

　　5、getMinorVersion

　　public int getMinorVersion();

　　返回Servlet引擎支持的Servlet API的次版本號.例如對於2.1版,這個方法會返回一個整數2.

　　6、getMimeType

　　public String getMimeType(String file);

　　返回指定文件的MIME類型,如果這種MIME類型未知,則返回一個空值.MIME類型是由Servlet引擎的配置決定的.

　　7、getRealPath

　　public String getRealPath(String path);

　　一個符合URL路徑格式的指定的虛擬路徑的格式是：/dir/dir/filename.ext.用這個方法,可以返回與一個符合該格式的虛擬路徑相對應的真實路徑的String.這個真實路徑的格式應該適合於運行這個Servlet引擎的計算機（包括其相應的路徑解析器）.

　　不管是什麼原因,如果這一從虛擬路徑轉換成實際路徑的過程不能執行,該方法將會返回一個空值.

　　8、getResource

　　public URL getResource(String uripath);

　　返回一個URL對象,該對象反映位於給定的URL地址（格式：/dir/dir/filename.ext）的Servlet環境對象已知的資源.無論 URLStreamHandlers對於訪問給定的環境是不是必須的,Servlet引擎都必須執行.如果給定的路徑的Servlet環境沒有已知的資源,該方法會返回一個空值.

　　這個方法和java.lang.Class的getResource方法不完全相同. java.lang.Class的getResource方法通過裝載類來尋找資源.而這個方法允許伺服器產生環境變數給任何資源的任何Servlet,而不必依賴於裝載類、特定區域等等.

　　9、getResourceAsStream

　　public InputStream getResourceAsStream(String uripath);

　　返回一個InputStream對象,該對象引用指定的URL的Servlet環境對象的內容.如果沒找到Servlet環境變數,就會返回空值,URL路徑應該具有這種格式：/dir/dir/filename.ext.

　　這個方法是一個通過getResource方法獲得URL對象的方便的途徑.請注意,當你使用這個方法時,meta-information（例如內容長度、內容類型）會丟失.

　　10、getRequestDispatcher

　　public RequestDispatcher getRequestDispatcher(String uripath);

　　如果這個指定的路徑下能夠找到活動的資源(例如一個Servlet,JSP頁面,CGI等等)就返回一個特定URL的RequestDispatcher 對象,否則,就返回一個空值,Servlet引擎負責用一個request dispatcher對象封裝目標路徑.這個 request dispatcher對象可以用來完全請求的傳送.

　　11、getServerInfo

　　public String getServerInfo();

　　返回一個String對象,該對象至少包括Servlet引擎的名字和版本號.

Tags: