Accedere ai servizi in bundle legacy per Java 11 e versioni successive

Questa pagina descrive come installare e utilizzare i servizi in bundle con la versione Java supportata più recente per l'ambiente App Engine Standard. La tua app può accedere ai servizi in bundle tramite il JAR dell'API App Engine.

Prima di iniziare

Installa il JAR dell'API App Engine

Per utilizzare i servizi in bundle legacy nell'ultima app Java supportata, devi: usa un appengine-web.xml per configurare l'app (anziché un file app.yaml).

L'esempio seguente mostra come aggiungere le impostazioni di configurazione nel tuo appengine-web.xml per la versione 21 e successive su EE10 (impostazione predefinita), versione 21 su EE8 e versione 17 e precedenti. Per utilizzare la versione supportata più recente 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 a seconda della versione di 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 quanto segue 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 impostala su true:

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

Per eseguire il deployment della tua app Java 21, esegui mvn appengine:deploy o il comando gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml su un'applicazione web compilata e in fasi.

Punto di ingresso predefinito utilizzato da Java 21

Le app Java 21 possono trarre vantaggio da utenti aggiuntivi all'avvio della JVM per le app web.

Il punto di ingresso predefinito utilizzato per avviare la JVM viene generato dai buildpack di App Engine. Essenzialmente, è equivalente a definire questo punto di contatto 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

Ti sconsigliamo di modificare questo punto di contatto predefinito perché le impostazioni della 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à di punto di ingresso

Il punto di contatto 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 attivare/disattivare/configurare le funzionalità e i valori predefiniti se non sono impostati:

Variabile di ambiente Descrizione Tipo Predefinito
CPROF_ENABLE Stackdriver Profiler boolean false
GAE_MEMORY_MB Memoria disponibile dimensioni Impostato da App Engine o /proc/meminfo-400 M
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 di -XX:+UseG1GC Plus
JAVA_USER_OPTS Altri argomenti JVM Argomenti JVM
JAVA_OPTS Argomenti JVM Argomenti JVM Vedi di seguito

Se non impostato esplicitamente, il valore predefinito di JAVA_OPTS è:

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

Quando CPROF_ENABLE è true, il punto di contatto predefinito aggiunge PROFILER_AGENT come segue:

-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

Se esegui la migrazione a un'istanza, tieni presente quanto segue 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 seconda generazione Java, puoi utilizzare il server di sviluppo locale.
  • A differenza del runtime Java 8, i runtime Java di seconda generazione includono la JVM come parte della memoria dell'istanza. Se nei log sono presenti errori relativi alla memoria, considera aumentando le dimensioni delle classi di istanza appengine-web.xml.
  • Se la tua applicazione tenta di chiamare un'API non attivata per gli ambienti di runtime Java di seconda generazione, riceverà un errore com.google.apphosting.api.ApiProxy$FeatureNotEnabledException.
  • Si presume che tutte le app siano sicure nei thread nel Java di seconda generazione runtime. Devi rimuovere l'elemento threadsafe nel file app.yaml o appengine-web.xml quando esegui l'upgrade ai runtime Java 11 e versioni successive.

Esempio (Datastore)

Per un esempio di come utilizzare Firestore in modalità Datastore (Datastore), consulta la servizi in bundle legacy per Java 11 esempio di codice in GitHub.