存取 Java 11 以上版本的舊版套裝組合服務

本頁說明如何使用 App Engine 標準環境的最新支援 Java 版本，安裝及使用隨附的服務。應用程式可透過 App Engine API JAR 存取套裝組合服務。

事前準備

安裝 App Engine API JAR

如要在最新支援的 Java 應用程式中使用舊版綁定服務，您必須使用 appengine-web.xml 檔案設定應用程式 (而非 app.yaml 檔案)。

以下範例說明如何在不同 Java 版本的 appengine-web.xml 中新增設定。如要在預設設定中使用最新支援版本，您必須更新應用程式 Servlet 和依附元件，加入 Jakarta 命名空間。如要進一步瞭解設定選項，請參閱「升級現有應用程式」。

請視 Java 版本，在 appengine-web.xml 檔案中新增下列設定：

Java 25 (預先發布版，EE 11) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java25</runtime>
      <system-properties>
        <property name="appengine.use.EE11" value="true"/>
      </system-properties>
      <app-engine-apis>true</app-engine-apis>
  </appengine-web-app>

Java 21 (EE 10) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java21</runtime>
      <system-properties>
        <property name="appengine.use.EE10" value="true"/>
      </system-properties>
      <app-engine-apis>true</app-engine-apis>
  </appengine-web-app>

Java 17 (EE 8) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java17</runtime>
      <system-properties>
        <property name="appengine.use.EE8" value="true"/>
      </system-properties>
      <app-engine-apis>true</app-engine-apis>
  </appengine-web-app>

如要將舊版套裝服務指定為依附元件，請在 pom.xml 檔案中新增下列程式碼：

 <dependency>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-api-1.0-sdk</artifactId>
    <version>2.0.31</version> <!-- or later-->
  </dependency>

如果應用程式使用 web.xml 檔案，您必須新增 <app-engine-apis> 元素並將其設為 true：

  <app-engine-apis>true</app-engine-apis>

如要部署 Java 25 (搶先版) 應用程式，請執行 mvn appengine:deploy 指令，或對已編譯及暫存的網頁應用程式執行 gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml 指令。

Java 25 (預先發布版) 的預設進入點

啟動 Java 25 (搶先版) 應用程式的 JVM 時，可為網頁應用程式提供額外的使用者設定。

App Engine 建構套件會產生用於啟動 JVM 的預設進入點。基本上，這等同於在 appengine-web.xml 檔案中定義這個進入點。例如：

java --add-opens java.base/java.lang=ALL-UNNAMED  --add-opens java.base/java.nio.charset=ALL-UNNAMED -showversion -Xms32M -Xmx204M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags -Dclasspath.runtimebase=/base/java_runtime -Djava.class.path=/base/java_runtime/runtime-main.jar -Djava.library.path=/base/java_runtime: com/google/apphosting/runtime/JavaRuntimeMainWithDefaults --fixed_application_path=/workspace /base/java_runtime

我們不建議變更這個預設進入點，因為記憶體設定是根據執行個體類型 (F1、F2、F4) 和可用記憶體計算而得。

根據預設，我們會使用 --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED 開啟部分必要的 JDK API。

進入點功能

您可以在 appengine-web.xml 設定檔中加入使用者定義的環境變數，自訂第二代 Java 版本的進入點。

下表列出可用於啟用/停用/設定功能的環境變數，以及未設定時的預設值：

環境變數 說明 類型 預設
CPROF_ENABLE Stackdriver Profiler 布林值 false
GAE_MEMORY_MB 可用的記憶體 大小 由 App Engine 設定或為 /proc/meminfo-400M
HEAP_SIZE_RATIO 堆積的記憶體 百分比 80
HEAP_SIZE_MB 可用的堆積 大小 ${GAE_MEMORY_MB} 的 ${HEAP_SIZE_RATIO}%
JAVA_HEAP_OPTS JVM heap 引數 JVM 引數 -Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M
JAVA_GC_OPTS JVM GC 引數 JVM 引數 -XX:+UseG1GC 加上設定
JAVA_USER_OPTS JVM 其他引數 JVM 引數
JAVA_OPTS JVM 引數 JVM 引數 詳情請見下方

如果沒有明確設定，JAVA_OPTS 會預設為：

   JAVA_OPTS:=-showversion \
              $JAVA_HEAP_OPTS \
              $JAVA_GC_OPTS \
              $JAVA_USER_OPTS

如果 CPROF_ENABLE 為 true，預設進入點會將 PROFILER_AGENT 新增為：

-agentpath:/opt/cprof/profiler_java_agent.so=--logtostderr

舉例來說，如果應用程式程式碼需要更多 -add-opens 標記，您可以使用 appengine-web.xml 檔案中定義的 JAVA_USER_OPTS 環境變數：

    <env-variables>
       <env-var name="JAVA_USER_OPTS" value="--add-opens java.base/java.util=ALL-UNNAMED" />
     </env-variables>

遷移注意事項

如果您要遷移至第二代 Java 執行階段，且應用程式使用舊版套裝服務，請注意下列事項：

  • 如要在第二代 Java 應用程式中測試舊版套裝服務功能，可以使用本機開發伺服器。
  • 與 Java 8 執行階段不同，第二代 Java 執行階段會將 JVM 納入執行個體記憶體。如果記錄檔中顯示記憶體相關錯誤，請考慮在 appengine-web.xml 檔案中增加執行個體類別大小。
  • 如果應用程式嘗試呼叫第二代 Java 執行階段未啟用的 API，就會收到 com.google.apphosting.api.ApiProxy$FeatureNotEnabledException 錯誤。
  • 在第二代 Java 執行階段中，系統會假設所有應用程式皆具備執行緒安全特性。從 Java 8 遷移至最新 Java 執行階段時，您必須移除 app.yaml 或 appengine-web.xml 檔案中的 threadsafe 元素。

範例 (Datastore)

如要瞭解如何使用 Datastore 模式 (Datastore) 的 Firestore，請參閱 GitHub 上的 Java 11 舊版套裝服務程式碼範例。