Mengakses layanan lama paket untuk Java 11+

Halaman ini menjelaskan cara menginstal dan menggunakan layanan yang dipaketkan dengan versi Java terbaru yang didukung untuk lingkungan standar App Engine. Aplikasi Anda dapat mengakses layanan yang dipaketkan melalui App Engine API JAR.

Sebelum memulai

Menginstal App Engine API JAR

Untuk menggunakan layanan lama yang dipaketkan dalam aplikasi Java terbaru yang didukung, Anda harus menggunakan file appengine-web.xml untuk mengonfigurasi aplikasi (bukan file app.yaml).

Contoh berikut menunjukkan cara menambahkan setelan konfigurasi di appengine-web.xml untuk versi 21 dan yang lebih baru di EE10 (default), versi 21 di EE8, serta versi 17 dan yang lebih lama. Untuk menggunakan versi terbaru yang didukung pada konfigurasi default, Anda harus mengupdate servlet dan dependensi aplikasi agar menyertakan namespace Jakarta. Untuk mempelajari opsi konfigurasi lebih lanjut, lihat Mengupgrade aplikasi yang sudah ada.

Tambahkan setelan berikut di file appengine-web.xml Anda, bergantung pada versi Java:

v21 dan yang lebih baru (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 dan yang lebih lama 

<?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>

Untuk menentukan layanan paket lama sebagai dependensi, tambahkan baris berikut di file pom.xml Anda:

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

Jika aplikasi menggunakan file web.xml, Anda harus menambahkan elemen <app-engine-apis> dan menetapkannya ke true:

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

Untuk men-deploy aplikasi Java 21, jalankan perintah mvn appengine:deploy, atau perintah gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml pada aplikasi web yang dikompilasi dan ditahapkan.

Titik entri default yang digunakan oleh Java 21

Aplikasi Java 21 dapat memanfaatkan konfigurasi pengguna tambahan saat memulai JVM untuk aplikasi web.

Titik entri default yang digunakan untuk mem-booting JVM dihasilkan oleh buildpack App Engine. Pada dasarnya, cara ini setara dengan menentukan titik entri ini dalam file appengine-web.xml. Contoh:

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

Kami tidak menyarankan mengubah titik entri default ini karena setelan memori dihitung berdasarkan jenis instance (F1, F2, F4) dan memori yang tersedia.

Secara default, kami menggunakan --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED untuk membuka beberapa JDK API yang diperlukan.

Fitur Titik Entri

Titik entri untuk versi Java generasi kedua dapat disesuaikan dengan variabel lingkungan yang ditentukan pengguna yang ditambahkan dalam file konfigurasi appengine-web.xml.

Tabel berikut menunjukkan variabel lingkungan yang dapat digunakan untuk mengaktifkan/menonaktifkan/mengonfigurasi fitur, dan nilai default jika tidak ditetapkan:

Env Var Deskripsi Jenis Default
CPROF_ENABLE Stackdriver Profiler boolean false
GAE_MEMORY_MB Memori yang tersedia ukuran Ditetapkan oleh App Engine atau /proc/meminfo-400M
HEAP_SIZE_RATIO Memori untuk heap persen 80
HEAP_SIZE_MB Heap yang tersedia ukuran ${HEAP_SIZE_RATIO}% dari ${GAE_MEMORY_MB}
JAVA_HEAP_OPTS JVM heap args JVM args -Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M
JAVA_GC_OPTS JVM GC args JVM args -XX:+UseG1GC plus konfigurasi
JAVA_USER_OPTS JVM other args JVM args
JAVA_OPTS JVM args JVM args Lihat di bawah

Jika tidak ditetapkan secara eksplisit, JAVA_OPTS akan disetel default ke:

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

Jika CPROF_ENABLE bernilai benar, titik entri default akan menambahkan PROFILER_AGENT sebagai:

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

Misalnya, jika kode aplikasi Anda memerlukan lebih banyak tanda -add-opens, Anda dapat menggunakan variabel lingkungan JAVA_USER_OPTS yang ditentukan dalam file appengine-web.xml:

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

Pertimbangan migrasi

Anda harus mengetahui pertimbangan berikut jika bermigrasi ke runtime Java generasi kedua dan aplikasi menggunakan layanan paket lama:

  • Untuk menguji kemampuan layanan lama yang dipaketkan di aplikasi Java generasi kedua, Anda dapat menggunakan server pengembangan lokal.
  • Tidak seperti runtime Java 8, runtime Java generasi kedua menyertakan JVM sebagai bagian dari memori instance. Jika Anda melihat error terkait memori dalam log, pertimbangkan untuk meningkatkan ukuran class instance dalam file appengine-web.xml.
  • Jika aplikasi Anda mencoba memanggil API yang tidak diaktifkan untuk runtime Java generasi kedua, aplikasi akan menerima error com.google.apphosting.api.ApiProxy$FeatureNotEnabledException.
  • Semua aplikasi dianggap aman untuk thread di runtime Java generasi kedua. Anda harus menghapus elemen threadsafe dalam file app.yaml atau appengine-web.xml saat mengupgrade ke runtime Java 11+.

Contoh (Datastore)

Untuk mengetahui contoh cara menggunakan Firestore dalam mode Datastore (Datastore), lihat layanan paket lama untuk contoh kode Java 11 di GitHub.