Questa pagina descrive come installare e utilizzare i servizi in bundle con la versione Java più recente supportata per l'ambiente standard di App Engine. La tua app può accedere ai servizi in bundle tramite il JAR dell'API App Engine.
Prima di iniziare
Consulta l'elenco delle API dei servizi in bundle legacy che puoi chiamare nell'ultima versione di Java supportata.
Questa pagina richiede che nella tua app sia in esecuzione una versione di Java 11 o versioni successive. Per eseguire la migrazione della tua app dai runtime di prima generazione a quelli di seconda generazione, esamina le differenze tra Java 8 e Java 11 e versioni successive e la sezione Considerazioni sulla migrazione.
Se utilizzi servizi in bundle legacy e vuoi eseguire l'upgrade a Java 21, consulta Eseguire l'upgrade di un'applicazione esistente per scoprire di più sulle opzioni di configurazione.
Installa il JAR dell'API App Engine
Per utilizzare i servizi in bundle legacy nella tua più recente app Java supportata, devi utilizzare un file appengine-web.xml
per configurare l'app (anziché un file app.yaml
).
L'esempio seguente mostra come aggiungere le impostazioni di configurazione in
appengine-web.xml
per la versione 21 e successive su EE10 (impostazione predefinita), la versione
21 su EE8 e la versione 17 e precedenti. Per utilizzare l'ultima versione supportata nella configurazione predefinita, devi aggiornare i servlet e le dipendenze dell'applicazione in modo da includere lo spazio dei nomi Jakarta
. Per scoprire di più sulle opzioni di configurazione, consulta Eseguire l'upgrade di un'applicazione esistente.
Aggiungi le seguenti impostazioni nel file appengine-web.xml
in base alla versione Java:
v21 e successive (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>
Versione 21 (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 e precedenti
<?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>
Per specificare i servizi in bundle legacy come dipendenza, aggiungi le seguenti righe nel file pom.xml
:
<dependency>
<groupId>com.google.appengine</groupId>
<artifactId>appengine-api-1.0-sdk</artifactId>
<version>2.0.4</version> <!-- or later-->
</dependency>
Se la tua app utilizza un file web.xml
, devi aggiungere l'elemento <app-engine-apis>
e impostarlo su true
:
<app-engine-apis>true</app-engine-apis>
Per eseguire il deployment della tua app Java 21, esegui il comando mvn appengine:deploy
o gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml
su un'applicazione web compilata e graduale.
Punto di ingresso predefinito utilizzato da Java 21
Le app Java 21 possono trarre vantaggio da una configurazione utente aggiuntiva quando viene avviata la JVM per app web.
L'entry point predefinito utilizzato per l'avvio della JVM viene generato dai buildpack App Engine.
Essenzialmente, equivale a definire questo punto di ingresso nel file appengine-web.xml
. Ad esempio:
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
Sconsigliamo di modificare questo punto di ingresso predefinito perché le impostazioni di memoria vengono calcolate in base al tipo di istanza (F1, F2, F4) e alla memoria disponibile.
Per impostazione predefinita, utilizziamo --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED
per aprire alcune API JDK necessarie.
Funzionalità dei punti di ingresso
Il punto di ingresso per le versioni Java di seconda generazione può essere personalizzato con variabili di ambiente definite dall'utente aggiunte nel file di configurazione appengine-web.xml
.
La tabella seguente indica le variabili di ambiente che possono essere utilizzate per abilitare/disabilitare/configurare le funzionalità e i valori predefiniti se non sono impostati:
Var. amb. | Descrizione | Tipo | Valore predefinito |
---|---|---|---|
CPROF_ENABLE |
Stackdriver Profiler | boolean | false |
GAE_MEMORY_MB |
Memoria disponibile | dimensioni | Impostato da App Engine o /proc/meminfo -400 Mln |
HEAP_SIZE_RATIO |
Memoria per l'heap | percentuale | 80 |
HEAP_SIZE_MB |
Heap disponibile | dimensioni | ${HEAP_SIZE_RATIO} % di ${GAE_MEMORY_MB} |
JAVA_HEAP_OPTS |
argomenti heap JVM | Argomenti JVM | -Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M |
JAVA_GC_OPTS |
Argomenti GC JVM | Argomenti JVM | Configurazione più di -XX:+UseG1GC |
JAVA_USER_OPTS |
Altri argomenti JVM | Argomenti JVM | |
JAVA_OPTS |
Argomenti JVM | Argomenti JVM | Vedi di seguito |
Se non viene configurato esplicitamente, il valore predefinito per JAVA_OPTS
è:
JAVA_OPTS:=-showversion \
$JAVA_HEAP_OPTS \
$JAVA_GC_OPTS \
$JAVA_USER_OPTS
Se CPROF_ENABLE
è true, il punto di ingresso predefinito aggiunge PROFILER_AGENT
come:
-agentpath:/opt/cprof/profiler_java_agent.so=--logtostderr
Ad esempio, se il codice dell'applicazione richiede più flag -add-opens
, puoi utilizzare la variabile di ambiente JAVA_USER_OPTS
definita nel file appengine-web.xml
:
<env-variables>
<env-var name="JAVA_USER_OPTS" value="--add-opens java.base/java.util=ALL-UNNAMED" />
</env-variables>
Considerazioni sulla migrazione
Tieni presente le seguenti considerazioni se esegui la migrazione a un runtime Java di seconda generazione e la tua app utilizza servizi in bundle legacy:
- Per testare le funzionalità dei servizi in bundle legacy nella tua app Java di seconda generazione, puoi utilizzare il server di sviluppo locale.
- A differenza del runtime Java 8, i runtime Java di seconda generazione includono JVM come parte della memoria dell'istanza. Se vedi errori relativi alla memoria nei log, valuta la possibilità di aumentare la dimensione della classe dell'istanza nel file
appengine-web.xml
. - Se la tua applicazione sta tentando di chiamare un'API che non è abilitata per i runtime Java di seconda generazione, riceverà un errore
com.google.apphosting.api.ApiProxy$FeatureNotEnabledException
. - Si presume che tutte le app siano sicure per i thread nei runtime Java di seconda generazione. Devi rimuovere l'elemento
threadsafe
nel fileapp.yaml
oappengine-web.xml
durante l'upgrade ai runtime Java 11 e versioni successive.
Esempio (Datastore)
Per un esempio di come utilizzare Firestore in modalità Datastore (Datastore), consulta i servizi in bundle legacy per Java 11 esempio di codice in GitHub.