Java Servlet API說明

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引擎的名字和版本號。 12、log public void log(String msg); public void log(String msg, Throwable t); public void log(Exception exception, String msg); // 這種用法將被取消寫指定的信息到一個Servlet環境對象的log文件中。被寫入的log文件由Servlet引擎指定，但是通常這是一個事件log。當這個方法被一個異常調用時，log中將包括堆棧跟蹤。 13、setAttribute public void setAttribute(String name, Object o); 給予Servlet環境對象中你所指定的對象一個名稱。 14、removeAttribute public void removeAttribute(String name); 從指定的Servlet環境對象中刪除一個屬性。注：以下幾個方法將被取消 15、getServlet public Servlet getServlet(String name) throws ServletException; 最初用來返回一個指定名稱的Servlet，如果沒找到就返回一個空值。如果這個Servlet能夠返回，這就意味着它已經被初始化，而且已經可以接受service請求。這是一個危險的方法。當調用這個方法時，可能並不知道Servlet的狀態，這就可能導致有關服務器狀態的問題。而允許一個Servlet訪問其他Servlet的這個方法也同樣的危險。現在這個方法返回一個空值，爲了保持和以前版本的兼容性，現在這個方法還沒有被取消。在以後的API版本中，該方法將被取消。 16、getServletNames public Enumeration getServletNames(); 最初用來返回一個String對象的列表，該列表表示了在這個Servlet環境下所有已知的Servlet對象名。這個列表總是包含這個Servlet自身。基於與上一個方法同樣的理由，這也是一個危險的方法。現在這個方法返回一個空的列表。爲了保持和以前版本的兼容性，現在這個方法還沒有被取消。在以後的API版本中，該方法將被取消。 17、getServlets public Enumeration getServlets(); 最初用來返回在這個Servelet環境下所有已知的Servlet對象的列表。這個列表總是包含這個Servlet自身。基於與getServlet方法同樣的理由，這也是一個危險的方法。現在這個方法返回一個空的列表。爲了保持和以前版本的兼容性，現在這個方法還沒有被取消。在以後的API版本中，該方法將被取消。 五、ServletRequest接口定義 public interface ServletRequest 定義一個Servlet引擎產生的對象，通過這個對象，Servlet可以獲得客戶端請求的數據。這個對象通過讀取請求體的數據提供包括參數的名稱、值和屬性以及輸入流的所有數據。方法 1、getAttribute public Object getAttribute(String name); 返回請求中指定屬性的值，如果這個屬性不存在，就返回一個空值。這個方法允許訪問一些不提供給這個接口中其他方法的請求信息以及其他Servlet放置在這個請求對象內的數據。 2、getAttributeNames public Enumeration getAttributeNames(); 返回包含在這個請求中的所有屬性名的列表。 3、getCharacterEncoding public String getCharacterEncoding(); 返回請求中輸入內容的字符編碼類型，如果沒有定義字符編碼類型就返回空值。 4、getContentLength public int getContentLength(); 請求內容的長度，如果長度未知就返回-1。 5、getContentType public String getContentType(); 返回請求數據體的MIME類型，如果類型未知返回空值。 6、getInputStream public ServletInputStream getInputStream() throws IOException; 返回一個輸入流用來從請求體讀取二進制數據。如果在此之前已經通過getReader方法獲得了要讀取的結果，這個方法會拋出一個IllegalStateException。 7、getParameter public String getParameter(String name); 以一個String返回指定的參數的值，如果這個參數不存在返回空值。例如，在一個HTTP Servlet中，這個方法會返回一個指定的查詢語句產生的參數的值或一個被提交的表單中的參數值。如果一個參數名對應着幾個參數值，這個方法只能返回通過getParameterValues方法返回的數組中的第一個值。因此，如果這個參數有（或者可能有）多個值，你只能使用getParameterValues方法。 8、getParameterNames public Enumeration getParameterNames(); 返回所有參數名的String對象列表，如果沒有輸入參數，該方法返回一個空值。 9、getParameterValues public String[] getParameterValues(String name); 通過一個String對象的數組返回指定參數的值，如果這個參數不存在，該方法返回一個空值。 10、getProtocol public String getProtocol(); 返回這個請求所用的協議，其形式是協議/主版本號.次版本號。例如對於一個HTTP1.0的請求，該方法返回HTTP/1.0。 11、getReader public BufferedReader getReader() throws IOException; 這個方法返回一個buffered reader用來讀取請求體的實體，其編碼方式依照請求數據的編碼方式。如果這個請求的輸入流已經被getInputStream調用獲得，這個方法會拋出一個IllegalStateException。 12、getRemoteAddr public String getRemoteAddr(); 返回發送請求者的IP地址。 13、getRemoteHost public String getRemoteHost(); 返回發送請求者的主機名稱。如果引擎不能或者選擇不解析主機名（爲了改善性能），這個方法會直接返回IP地址。 14、getScheme public String getScheme(); 返回請求所使用的URL的模式。例如，對於一個HTTP請求，這個模式就是http。 15、getServerName public String getServerName(); 返回接收請求的服務器的主機名。 16、getServerPort public int getServerPort(); 返回接收請求的端口號。 17、setAttribute public void setAttribute(String name, Object object); 這個方法在請求中添加一個屬性，這個屬性可以被其他可以訪問這個請求對象的對象（例如一個嵌套的Servlet）使用。注：以下方法將被取消 getRealPath public String getRealPath(String path); 返回與虛擬路徑相對應的真實路徑，如果因爲某種原因，這一過程不能進行，該方法將返回一個空值。這個方法和ServletContext接口中的getRealPath方法重複。在2.1版中，ServletContext接口將闡明一個Servlet所能用的所有的路徑的映射。該方法執行的結果將會與ServletContext中getRealPath方法的結果完全一樣。 六、ServletResponse接口定義 public interface ServletResponse 定義一個Servlet引擎產生的對象，通過這個對象，Servlet對客戶端的請求作出響應。這個響應應該是一個MIME實體，可能是一個HTML頁、圖象數據或其他MIME的格式。方法 1、getCharacterEncoding public String getCharacterEncoding(); 返回MIME實體的字符編碼。這個字符編碼可以是指定的類型，也可以是與請求頭域所反映的客戶端所能接受的字符編碼最匹配的類型。在HTTP協議中，這個信息被通過Accept-Charset傳送到Servlet引擎。有關字符編碼和MIME的更多信息請參看RFC 2047。 2、getOutputStream public ServletOutputStream getOutputStream() throws IOException; 返回一個記錄二進制的響應數據的輸出流。如果這個響應對象已經調用getWriter，將會拋出IllegalStateException。 3、getWriter public PrintWriter getWriter throws IOException; 這個方法返回一個PringWriter對象用來記錄格式化的響應實體。如果要反映使用的字符編碼，必須修改響應的MIME類型。在調用這個方法之前，必須設定響應的content類型。如果沒有提供這樣的編碼類型，會拋出一個UnsupportedEncodingException，如果這個響應對象已調用getOutputStream，會拋出一個getOutputStream。 4、setContentLength public void setContentLength(int length); 設置響應的內容的長度，這個方法會覆蓋以前對內容長度的設定。爲了保證成功地設定響應頭的內容長度，在響應被提交到輸出流之前必須調用這個方法。 5、setContentType public void setContentType(String type); 這個方法用來設定響應的content類型。這個類型以後可能會在另外的一些情況下被隱式地修改，這裏所說的另外的情況可能當服務器發現有必要的情況下對MIME的字符設置。爲了保證成功地設定響應頭的content類型，在響應被提交到輸出流之前必須調用這個方法。 七、SingleThreadModel接口定義 public interface SingleThreadModel; 這是一個空接口，它指定了系統如何處理對同一個Servlet的調用。如果一個Servlet被這個接口指定，那麼在這個Servlet中的service方法中將不會有兩個線程被同時執行。 Servlet可以通過維持一個各自獨立的Servlet實例池，或者通過只讓Servlet的service中只有一個線程的方法來實現這個保證。 八、GenericServlet類 public abstract class GenericServlet implements Servlet, ServletConfig, Serializable; 這個類的存在使得編寫Servlet更加方便。它提供了一個簡單的方案，這個方案用來執行有關Servlet生命週期的方法以及在初始化時對ServletConfig對象和ServletContext對象進行說明。方法 1、destroy public void destroy(); 在這裏destroy方法不做任何其他的工作。 2、getInitParameter public String getInitParameter(String name); 這是一個簡便的途徑，它將會調用ServletConfig對象的同名的方法。 3、getInitParameterNames public Enumeration getInitParameterNames(); 這是一個簡便的途徑，它將會調用ServletConfig對象的同名的方法。 4、getServletConfig public ServletConfig getServletConfig(); 返回一個通過這個類的init方法產生的ServletConfig對象的說明。 5、getServletContext public ServletContext getServletContext(); 這是一個簡便的途徑，它將會調用ServletConfig對象的同名的方法。 6、getServletInfo public String getServletInfo(); 返回一個反映Servlet版本的String。 7、init public void init() throws ServletException; public void init(ServletConfig config) throws ServletException; init(ServletConfig config)方法是一個對這個Servlet的生命週期進行初始化的簡便的途徑。 init()方法是用來讓你對GenericServlet類進行擴充的，使用這個方法時，你不需要存儲config對象，也不需要調用super.init(config)。 init(ServletConfig config)方法會存儲config對象然後調用init()。如果你重載了這個方法，你必須調用super.init(config)，這樣GenericServlet類的其他方法才能正常工作。 8、log public void log(String msg); public void log(String msg, Throwable cause); 通過Servlet content對象將Servlet的類名和給定的信息寫入log文件中。 9、service public abstract void service(ServletRequest request, ServletResponse response) throws ServletException, IOException; 這是一個抽象的方法，當你擴展這個類時，爲了執行網絡請求，你必須執行它。 九、ServletInputStream類定義 public abstract class ServletInputStream extends InputStream 這個類定義了一個用來讀取客戶端的請求信息的輸入流。這是一個Servlet引擎提供的抽象類。一個Servlet通過使用ServletRequest接口獲得了對一個ServletInputStream對象的說明。這個類的子類必須提供一個從InputStream接口讀取有關信息的方法。方法 1、readLine public int readLine(byte[] b, int off, int len) throws IOException; 從輸入流的指定的偏移量開始將指定長度的字節讀入到指定的數組中。如果該行所有請求的內容都已被讀取，這個讀取的過程將結束。如果是遇到了新的一行，新的一行的首個字符也將被讀入到數組中。 十、ServletOutputStream類定義 public abstract class ServletOutputStream extends OutputStream 這是一個由Servlet引擎使用的抽象類。Servlet通過使用ServletResponse接口的使用獲得了對一個這種類型的對象的說明。利用這個輸出流可以將數據返回到客戶端。這個類的子類必須提供一個向OutputStream接口寫入有關信息的方法。在這個接口中，當一個刷新或關閉的方法被調用時。所有數據緩衝區的信息將會被髮送到客戶端，也就是說響應被提交了。請注意，關閉這種類型的對象時不一定要關閉隱含的socket流。方法 1、print public void print(String s) throws IOException; public void print(boolean b) throws IOException; public void print(char c) throws IOException; public void print(int i) throws IOException; public void print(long l) throws IOException; public void print(float f) throws IOException; public void print(double d) throws IOException; 輸出變量到輸出流中 2、println public void println() throws IOException; public void println(String s) throws IOException; public void println(boolean b) throws IOException; public void println(char c) throws IOException; public void println(int i) throws IOException; public void println(long l) throws IOException; public void println(float f) throws IOException; public void println(double d) throws IOException; 輸出變量到輸出流中，並增加一個回車換行符 十一、ServletException類定義 public class ServletException extends Exception 當Servlet遇到問題時拋出的一個異常。構造函數 public ServletException(); public ServletException(String message); public ServletException(String message, Throwable cause); public ServletException(Throwable cause); 構造一個新的ServletException，如果這個構造函數包括一個Throwable參數，這個Throwable對象將被作爲可能拋出這個異常的原因。方法 1、getRootCause public Throwable getRootCause(); 如果配置了拋出這個異常的原因，這個方法將返回這個原因，否則返回一個空值。 十二、UnavailableException類定義 public class UnavailableException extends ServletException 不論一個Servlet是永久地還是臨時地無效，都會拋出這個異常。Servlet會記錄這個異常以及Servlet引擎所要採取的相應措施。臨時的無效是指Servlet在某一時間由於一個臨時的問題而不能處理請求。例如，在另一個不同的應用層的服務（可能是數據庫）無法使用。這個問題可能會自行糾正或者需要採取其他的糾正措施。永久的無效是指除非管理員採取措施，這個Servlet將不能處理客戶端的請求。例如，這個Servlet配置信息丟失或Servlet的狀態被破壞。 Servlet引擎可以安全地處理包括永久無效在內的這兩種異常，但是對臨時無效的正常處理可以使得Servlet引擎更健壯。特別的，這時對Servlet的請求只是被阻止（或者是被延期）一段時間，這顯然要比在service自己重新啓動前完全拒絕請求更爲科學。構造函數 public UnavailableException(Servlet servlet, String message); public UnavailableException(int seconds, Servlet servlet, String message); 構造一個包含指定的描述信息的新的異常。如果這個構造函數有一個關於秒數的參數，這將給出Servlet發生臨時無效後，能夠重新處理請求的估計時間。如果不包含這個參數，這意味着這個Servlet永久無效。方法 1、getServlet public Servlet getServlet(); 返回報告無效的Servlet。這被Servlet引擎用來識別受到影響的Servlet。 2、getUnavailableSeconds public int getUnavailableSeconds(); 返回Servlet預期的無效時間，如果這個Servlet是永久無效，返回-1。 3、isPermanent public boolean isPermanent(); 如果這個Servlet永久無效，返回布爾值true，指示必須採取一些管理行動以使得這個Servlet可用。