Mengakses layanan paket lama untuk Java 11+

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

Sebelum memulai

Menginstal JAR App Engine API

Untuk menggunakan layanan paket lama di 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, dan versi 17 dan yang lebih lama. Untuk menggunakan versi terbaru yang didukung pada konfigurasi default, Anda harus mengupdate servlet dan dependensi aplikasi untuk menyertakan namespace Jakarta. Untuk mempelajari opsi konfigurasi lebih lanjut, lihat Mengupgrade aplikasi yang ada.

Tambahkan setelan berikut dalam 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.31</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 dilakukan bertahap.

Titik entri default yang digunakan oleh Java 21

Aplikasi Java 21 dapat mendapatkan manfaat dari konfigurasi pengguna tambahan saat memulai JVM untuk aplikasi web.

Titik entri default yang digunakan untuk melakukan 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 buatan 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 Anda menggunakan layanan paket lama:

  • Untuk menguji kemampuan layanan paket lama di aplikasi Java generasi kedua, Anda dapat menggunakan server pengembangan lokal.
  • Berbeda dengan 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 pada runtime Java generasi kedua. Anda harus menghapus elemen threadsafe dalam file app.yaml atau appengine-web.xml saat Bermigrasi dari Java 8 ke runtime Java terbaru.

Contoh (Datastore)

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