Apache Tomcat 10

• 簡介
• 安裝
• Servlet 組態
• Filter 組態
• 指令
• 變數

SSI (伺服器端包含) 是置於 HTML 頁面中的指令，並在頁面提供服務時於伺服器上評估。它們讓您將動態產生的內容新增至現有的 HTML 頁面，而無需透過 CGI 程式或其他動態技術提供整個頁面。

在使用 Tomcat 作為您的 HTTP 伺服器且您需要 SSI 支援時，可以在 Tomcat 中新增 SSI 支援。通常這是在開發期間進行，當您不想執行 Apache 等網頁伺服器時。

Tomcat SSI 支援實作與 Apache 相同的 SSI 指令。請參閱 Apache SSI 簡介，以取得有關使用 SSI 指令的資訊。

SSI 支援可作為 Servlet 和 Filter 使用。您應該使用其中一種提供 SSI 支援，但不能同時使用兩種。

使用類別 org.apache.catalina.ssi.SSIServlet 實作基於 Servlet 的 SSI 支援。傳統上，此 Servlet 會對應到 URL 模式「*.shtml」。

使用類別 org.apache.catalina.ssi.SSIFilter 實作基於 Filter 的 SSI 支援。傳統上，此 Filter 會對應到 URL 模式「*.shtml」，儘管它可以對應到「*」，因為它會根據 MIME 類型選擇性地啟用/停用 SSI 處理。contentType 初始化參數允許您將 SSI 處理套用至 JSP 頁面、JavaScript 或您想要的任何其他內容。

預設情況下，SSI 支援在 Tomcat 中已停用。

注意 - SSI 指令可用於執行 Tomcat JVM 外部的程式。如果您正在使用 Java SecurityManager，這將會繞過您在 catalina.policy 中的安全政策組態。

若要使用 SSI servlet，請移除 $CATALINA_BASE/conf/web.xml 中 SSI servlet 和 servlet-mapping 組態周圍的 XML 註解。

若要使用 SSI filter，請移除 $CATALINA_BASE/conf/web.xml 中 SSI filter 和 filter-mapping 組態周圍的 XML 註解。

只有標記為特權的 Context 可以使用 SSI 功能（請參閱 Context 元素的特權屬性）。

有幾個 servlet 初始化參數可用於組態 SSI servlet 的行為。

• buffered - 這個 servlet 的輸出應該緩衝嗎？（0=否，1=是）預設為 0（否）。
• debug - 此 servlet 記錄的訊息的偵錯詳細資料等級。預設為 0。
• expires - 具有 SSI 指令的頁面過期前的秒數。預設行為是針對每個要求評估所有 SSI 指令。
• isVirtualWebappRelative - 應該將「虛擬」SSI 指令路徑解釋為相對於 Context 根目錄，而不是伺服器根目錄嗎？預設為否。
• inputEncoding - 如果無法從資源本身確定 SSI 資源的編碼，則假設的編碼。預設為預設平台編碼。
• outputEncoding - 要用於 SSI 處理結果的編碼。預設為 UTF-8。
• allowExec - exec 指令已啟用嗎？預設為否。

有幾個 filter 初始化參數可用於組態 SSI filter 的行為。

• contentType - 在套用 SSI 處理之前必須符合的正規表示式模式。在建立您自己的模式時，別忘了 MIME 內容類型後面可能會加上「mime/type; charset=set」形式的選用字元集，您必須考慮到這一點。預設為「text/x-server-parsed-html(;.*)?」。
• debug - 此 servlet 記錄的訊息的偵錯詳細資料等級。預設為 0。
• expires - 具有 SSI 指令的頁面過期前的秒數。預設行為是針對每個要求評估所有 SSI 指令。
• isVirtualWebappRelative - 應該將「虛擬」SSI 指令路徑解釋為相對於 Context 根目錄，而不是伺服器根目錄嗎？預設為否。
• allowExec - exec 指令已啟用嗎？預設為否。

伺服器端包含會嵌入 SSI 指令在 HTML 文件中，其類型將由 SSI servlet 處理。指令採用 HTML 註解的形式。指令會在將頁面傳送給用戶端之前，以其解釋的結果取代。指令的一般形式為

<!--#directive [param=value] -->

指令為

• config - <!--#config errmsg="Error occurred" sizefmt="abbrev" timefmt="%B %Y" --> 用於設定 SSI 錯誤訊息、SSI 處理的日期和檔案大小格式。
  全部為選用，但至少必須使用一個。可用的選項如下
  errmsg - 用於 SSI 錯誤的錯誤訊息
  sizefmt - 用於 fsize 指令中大小的格式
  timefmt - 用於 flastmod 指令中時間戳記的格式
  
• echo - <!--#echo var="VARIABLE_NAME" encoding="entity" --> 將由變數的值取代。
  選用的 encoding 參數指定要使用的編碼類型。有效值為 entity (預設值)、url 或 none。注意：使用 entity 以外的編碼可能會導致安全性問題。
• exec - <!--#exec cmd="file-name" --> 用於在主機系統上執行指令。
• exec - <!--#exec cgi="file-name" --> 此動作與 include virtual 指令相同，實際上不會執行任何指令。
• include - <!--#include file="file-name" --> 插入內容。路徑會相對於使用此指令的文件進行詮釋，且並非相對於內容根目錄或伺服器根目錄的「虛擬」路徑。
• include - <!--#include virtual="file-name" --> 插入內容。路徑會詮釋為相對於內容根目錄或伺服器根目錄的「虛擬」路徑（視 isVirtualWebappRelative 參數而定）。
• flastmod - <!--#flastmod file="filename.shtml" --> 傳回檔案最後修改的時間。路徑會相對於使用此指令的文件進行詮釋，且並非相對於內容根目錄或伺服器根目錄的「虛擬」路徑。
• flastmod - <!--#flastmod virtual="filename.shtml" --> 傳回檔案最後修改的時間。路徑會詮釋為相對於內容根目錄或伺服器根目錄的「虛擬」路徑（視 isVirtualWebappRelative 參數而定）。
• fsize - <!--#fsize file="filename.shtml" --> 傳回檔案的大小。路徑會相對於使用此指令的文件進行詮釋，且並非相對於內容根目錄或伺服器根目錄的「虛擬」路徑。
• fsize - <!--#fsize virtual="filename.shtml" --> 傳回檔案大小。路徑會被解釋為「虛擬」路徑，相對於內容根目錄或伺服器根目錄（視 isVirtualWebappRelative 參數而定）。
• printenv - <!--#printenv --> 傳回所有已定義變數的清單。
• set - <!--#set var="foo" value="Bar" --> 用於將值指定給使用者定義的變數。
• if elif endif else - 用於建立條件式區段。例如

  <!--#config timefmt="%A" -->
  <!--#if expr="$DATE_LOCAL = /Monday/" -->
  <p>Meeting at 10:00 on Mondays</p>
  <!--#elif expr="$DATE_LOCAL = /Friday/" -->
  <p>Turn in your time card</p>
  <!--#else -->
  <p>Yoga class at noon.</p>
  <!--#endif -->

請參閱 Apache SSI 簡介，以取得更多有關如何使用 SSI 指令的資訊。

SSI 變數透過 jakarta.servlet.ServletRequest 物件上的要求屬性來實作，且不限於 SSI servlet。名稱以「java.」、「javax.」、「sun」或「org.apache.catalina.ssi.SSIMediator.」開頭的變數是保留的，且無法使用。

SSI servlet 目前實作下列變數