Java 應用程式設定

除了 web.xml 部署描述元之外，「應用服務引擎 Java」應用程式會使用 appengine-web.xml 設定檔來指定應用程式的註冊應用程式 ID 和最新程式碼的版本識別碼，以及識別應用程式 WAR 裡面的靜態檔案 (例如影像) 和應用程式所使用的資源檔案。上傳應用程式時，AppCfg 命令會使用這個資訊。

• 關於 appengine-web.xml
• 靜態檔案和資源檔案
• 系統屬性和環境變數
• 啟用安全 URL (SSL)
• 啟用工作階段

關於 appengine-web.xml

「應用服務引擎」的 Java 應用程式在 WAR 的 WEB-INF/ 目錄中，必須擁有一個名稱為 appengine-web.xml 的檔案。這是一個 XML 檔案，其根元素為 <appengine-web-app>。下方為一個迷你檔案範例，這個檔案指定應用程式 ID 與版本識別碼，卻沒有指定靜態檔案或資源檔案：

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>application-id</application>
  <version>1</version>
</appengine-web-app>

<application> 元素包含應用程式的 ID。這是您在「管理控制台」建立應用程式時所註冊的應用程式 ID。當您上傳應用程式時，AppCfg 會從這個檔案取得應用程式 ID。

<version> 元素包含應用程式碼最新版本的版本識別碼。版本識別碼可以是任何字串。AppCfg 上傳應用程式時會使用版本識別碼，並指示「應用服務引擎」使用這個識別碼建立應用程式的新版本，或取代應用程式的現有版本 (如果版本已經存在)。您可以使用 URL (例如 http://version-id.latest.application-id.appspot.com) 測試應用程式的新版本。在「管理控制台」中，您可以選取要顯示的應用程式版本，也就是「預設」版本。

<static-files> 和 <resource-files> 元素會在下一章節中另外説明。

您可以在 SDK 的 docs/ 目錄中找到這個檔案的 DTD 和結構描述規格。

靜態檔案和資源檔案

許多網路應用程式的檔案會直接提供給使用者的瀏覽器，例如影像、CSS 樣式表或瀏覽器 JavaScript 程式碼。這些檔案稱為「靜態檔案」，因為它們不會變更，而且在靜態內容專屬的網頁伺服器中佔有優勢。「應用服務引擎」會從專屬伺服器和快取提供靜態檔案。

應用程式碼使用檔案系統即可存取的檔案稱為 resource files。這些檔案和應用程式一起儲存在應用程式伺服器中。

按照預設，WAR 的所有檔案均被視為靜態檔案和資源檔案，但是 JSP 檔案和 WEB-INF/ 目錄的檔案除外；JSP 檔案會被編譯成 servlet 類別並對應至 URL 路徑，而 <code>WEB-INF/</code> 目錄的檔案永遠只能做為資源檔案提供應用程式使用。

您可以使用 appengine-web.xml 檔案中的元素，調整靜態檔案和資源檔案的檔案歸類。<static-files> 元素會指定各種模式，如果檔案路徑符合指定模式，將納入靜態檔案清單或從靜態檔案清單排除，以修正預設行為。同樣地，<resource-files> 元素會指定要歸類為資源檔案的檔案。

路徑模式是使用零或多個 <include>and<exclude> 元素加以指定的。在其中一種模式中，* 代表檔案或目錄名稱中的零或多個字元，而 ** 代表路徑中的零或多個目錄。

<include> 元素會覆寫納入所有檔案的預設行為。<exclude> 元素必須在所有 <include> 模式 (包括預設值，如未明確提供 <include>) 執行之後才能套用。

舉例來說，如果要將檔案名稱結尾為 .png 的所有檔案指定為靜態檔案 (包括 WEB-INF/ 中的檔案)，但是必須排除 data/ 目錄和所有子目錄中的檔案：

    <static-files>
        <include path="/**.png" />
        <exclude path="/data/**.png" />
    </static-files>

同樣地，如果要將檔案名稱結尾為 .xml 的所有檔案指定為資源檔案 (包括 WEB-INF/ 以外的檔案)，但是必須排除 feeds/ 目錄和所有子目錄中的檔案：

    <resource-files>
        <include path="/**.xml" />
        <exclude path="/feeds/**.xml" />
    </resource-files>

靜態檔案的提供類型是根據副檔名所選取的 MIME 類型。如要提供一個自訂 MIME 類型的檔案，請將檔案變更為資源檔案，再建立一個 servlet 以提供自訂 MIME 類型的資料。

系統屬性和環境變數

appengine-web.xml 檔案可以定義應用程式執行時所設定的系統屬性和環境變數。

    <system-properties>
        <property name="myapp.maximum-message-length" value="140" />
        <property name="myapp.notify-every-n-signups" value="1000" />
        <property name="myapp.notify-url" value="http://www.example.com/signupnotify" />
    </system-properties>

    <env-variables>
        <env-var name="DEFAULT_ENCODING" value="UTF-8" />
    </env-variables>

啟用安全 URL (SSL)

如果您的應用程式使用安全 URL (SSL，例如 https://...)，則您必須在 appengine-web.xml 檔案中啟用應用程式的 SSL。如要啟用 SSL，請在檔案中加上一個 <ssl-enabled> 元素。

    <ssl-enabled>true</ssl-enabled>

如需進一步瞭解如何定義安全 URL，請參閱「部署描述元：安全 URL」。

啟用工作階段

「應用服務引擎」透過 servlet 工作階段介面，納入一個工作階段實作。這個實作會使用「應用服務引擎」資料存放區和記憶體快取來儲存工作階段資料。

這個功能預設為關閉。如要啟動這個功能，請在 appengine-web.xml 中加上下列字串：

    <sessions-enabled>true</sessions-enabled>

這個實作會建立 _ah_SESSION 種類的資料存放區實體，並使用前置字元為 _ahs 的金鑰建立記憶體快取項目。