访问适用于 Java 11+ 的旧版捆绑服务

本页面介绍了如何安装捆绑服务并将其与适用于 App Engine 标准环境的最新支持的 Java 版本搭配使用。应用可以通过 App Engine API JAR 访问捆绑服务。

须知事项

请参阅您可以在最新支持的 Java 版本中调用的旧版捆绑服务 API 列表。
本页面要求您的应用运行 Java 11 或更高版本。如需将您的应用从第一代运行时迁移到第二代运行时，请查看 Java 8 和 Java 11+ 之间的区别以及迁移注意事项部分。
如果您使用的是旧版捆绑服务并且想要升级到 Java 21，请参阅升级现有应用以详细了解配置选项。

安装 App Engine API JAR

如需在受支持的最新 Java 应用中使用旧版捆绑服务，您必须使用 appengine-web.xml 文件（而不是 app.yaml 文件）来配置您的应用。

以下示例演示了如何针对 EE10 上的版本 21 及更高版本（默认）、EE8 上的版本 21 和版本 17 及更低版本在 appengine-web.xml 中添加配置设置。如需在默认配置上使用受支持的最新版本，您必须更新应用 servlet 和依赖项以包含 Jakarta 命名空间。如需详细了解配置选项，请参阅升级现有应用。

根据 Java 版本在 appengine-web.xml 文件中添加以下设置：

v21 及更高版本 (EE10)

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <runtime>java21</runtime> <!-- or another supported version -->
  <app-engine-apis>true</app-engine-apis>
</appengine-web-app>

v21 (EE8)

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

v17 及更低版本

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <runtime>java17</runtime> <!-- or another supported version -->
  <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.4</version> <!-- or later-->
  </dependency>

如果您的应用使用 web.xml 文件，您必须添加 <app-engine-apis> 元素并将其设置为 true：

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

如需部署 Java 21 应用，请在已编译的预演 Web 应用上运行 mvn appengine:deploy 命令或 gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml 命令。

Java 21 使用的默认入口点

在启动 Web 应用的 JVM 时，Java 21 应用可以从额外的用户配置受益。

用于启动 JVM 的默认入口点由 App Engine Buildpack 生成。从本质上讲，这相当于在 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。

入口点特性

第二代 Java 版本的入口点可通过在 appengine-web.xml 配置文件中添加的用户定义环境变量进行自定义。

下表列出了可用于启用/停用/配置功能的环境变量以及默认值：

环境变量	说明	类型	默认值
`CPROF_ENABLE`	Stackdriver Profiler	布尔值	`false`
`GAE_MEMORY_MB`	可用内存	size	由 App Engine 或 `/proc/meminfo`-400M 设置
`HEAP_SIZE_RATIO`	堆内存	百分比	80
`HEAP_SIZE_MB`	可用堆	size	`${GAE_MEMORY_MB}` 的 `${HEAP_SIZE_RATIO}`%
`JAVA_HEAP_OPTS`	JVM 堆参数	JVM 参数	`-Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M`
`JAVA_GC_OPTS`	JVM GC 参数	JVM 参数	`-XX:+UseG1GC` plus 配置
`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 11+ 运行时时，您必须移除 app.yaml 或 appengine-web.xml 文件中的 threadsafe 元素。

示例 (Datastore)

如需查看如何使用 Datastore 模式的 Firestore (Datastore) 的示例，请参阅 GitHub 中适用于 Java 11 的旧版捆绑服务的代码示例。