Java 11 以降用の以前のバンドル サービスにアクセスする

このページでは、App Engine スタンダード環境用にサポートされている最新の Java バージョンで、バンドル サービスをインストールして使用する方法について説明します。アプリは、App Engine API JAR を介してバンドル サービスにアクセスできます。

準備

App Engine API JAR をインストールする

サポートされている最新の Java アプリでレガシー バンドル サービスを使用するには、app.yaml ファイルではなく、appengine-web.xml ファイルを使用してアプリを構成する必要があります。

次の例は、appengine-web.xml に EE10 ではバージョン 21 以降(デフォルト)、EE8 ではバージョン 21、それ以外はバージョン 17 以前の構成設定を追加する方法を示しています。サポートされている最新のバージョンをデフォルト構成で使用するには、アプリケーション サーブレットと依存関係を更新して、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.31</version> <!-- or later-->
  </dependency>

アプリで web.xml ファイルを使用する場合は、<app-engine-apis> 要素を追加して true に設定する必要があります。

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

Java 21 アプリをデプロイするには、コンパイルされたステージング済みのウェブ アプリケーション上で、mvn appengine:deploy コマンドまたは gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml コマンドを実行します。

Java 21 で使用されるデフォルトのエントリ ポイント

Java 21 アプリでは、ウェブアプリ用の JVM を起動する際に、追加のユーザー構成を利用できます。

JVM の起動に使用されるデフォルトのエントリポイントは、App Engine Buildpacks によって生成されます。基本的に、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 を開きます。

エントリ ポイントの特長

第 2 世代の Java バージョンのエントリ ポイントは、appengine-web.xml 構成ファイルにユーザー定義の環境変数を追加してカスタマイズできます。

次の表に、機能の有効化、無効化、構成に使用できる環境変数と、設定されていない場合のデフォルト値を示します。

環境変数 説明 Default
CPROF_ENABLE Stackdriver Profiler boolean false
GAE_MEMORY_MB 利用可能なメモリ サイズ App Engine または /proc/meminfo - 400M で設定します。
HEAP_SIZE_RATIO ヒープ用メモリ パーセント 80
HEAP_SIZE_MB 使用可能なヒープ サイズ ${HEAP_SIZE_RATIO}% / ${GAE_MEMORY_MB}
JAVA_HEAP_OPTS JVM ヒープ引数 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>

移行に関する考慮事項

第 2 世代の Java ランタイムに移行し、アプリでレガシー バンドル サービスを使用している場合は、次の考慮事項を把握しておいてください。

  • レガシー バンドル サービスの機能を第 2 世代の Java アプリでテストする際に、ローカルの開発用サーバーを使用できます。
  • Java 8 ランタイムとは異なり、第 2 世代の Java ランタイムには、インスタンス メモリの一部として JVM が含まれています。ログにメモリ関連のエラーが記録されている場合は、appengine-web.xml ファイルのインスタンス クラス サイズを拡大することを検討してください。
  • アプリケーションで第 2 世代の Java ランタイムが有効になっていない API を呼び出そうとすると、com.google.apphosting.api.ApiProxy$FeatureNotEnabledException エラーが発生します。
  • 第 2 世代の Java ランタイムでは、すべてのアプリがスレッドセーフであると想定されています。Java 8 から最新の Java ランタイムに移行する場合は、app.yaml ファイルまたは appengine-web.xml ファイルから threadsafe 要素を削除する必要があります。

例(Datastore)

Datastore モード(Datastore)で Firestore を使用する方法の例については、GitHub のコードサンプルにある Java 11 用の以前のバンドル サービスをご覧ください。