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
Lihat daftar API layanan lama yang dipaketkan yang dapat Anda panggil dalam versi Java terbaru yang didukung.
Halaman ini mengharuskan aplikasi Anda menjalankan versi Java 11 atau yang lebih baru. Untuk memigrasikan aplikasi dari runtime generasi pertama ke generasi kedua, tinjau perbedaan antara Java 8 dan Java 11+ dan bagian pertimbangan migrasi.
Jika Anda menggunakan layanan lama yang dipaketkan dan ingin mengupgrade ke Java 21, lihat Mengupgrade aplikasi yang sudah ada untuk mempelajari opsi konfigurasi lebih lanjut.
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 fileapp.yaml
atauappengine-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.