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

Questa pagina descrive come installare e utilizzare i servizi in bundle con l'ultima versione Java 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

Installare il JAR dell'API App Engine

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

L'esempio seguente mostra come aggiungere le impostazioni di configurazione nel file appengine-web.xml per le diverse versioni Java. 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 a seconda della versione Java. Questo esempio consente alla tua applicazione di utilizzare solo i servizi in bundle Datastore e Memcache:

Java 25 (EE 11) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java25</runtime>
      <system-properties>
        <property name="appengine.use.EE11" value="true"/>
      </system-properties>
      <app-engine-bundled-services>
        <api>datastore_v3</api>
        <api>memcache</api>
        <!-- LIST YOUR SERVICES -->
      </app-engine-bundled-services>
  </appengine-web-app>

Java 21 (EE 10) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java21</runtime>
      <system-properties>
        <property name="appengine.use.EE10" value="true"/>
      </system-properties>
      <app-engine-bundled-services>
        <api>datastore_v3</api>
        <api>memcache</api>
        <!-- LIST YOUR SERVICES -->
      </app-engine-bundled-services>
  </appengine-web-app>

Java 17 (EE 8) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java17</runtime>
      <system-properties>
        <property name="appengine.use.EE8" value="true"/>
      </system-properties>
      <app-engine-bundled-services>
        <api>datastore_v3</api>
        <api>memcache</api>
        <!-- LIST YOUR SERVICES -->
      </app-engine-bundled-services>
  </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.31</version> <!-- or later-->
  </dependency>

Se la tua app utilizza un file web.xml, configura l'elemento <app-engine-bundled-service>. Per le impostazioni di configurazione app_engine_bundled_services, consulta il web.xml riferimento al file.

<app-engine-bundled-services>
  <api>memcache</api>
  <api>datastore_v3</api>
  <api>modules</api>
  <api>search</api>
  <api><!-- LIST YOUR SERVICES --></api>
</app-engine-bundled-services>

Per eseguire il deployment dell'app Java 25, esegui il mvn appengine:deploy comando o il gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml comando su un'applicazione web compilata e sottoposta a staging.

Punto di ingresso predefinito per Java 25

Le applicazioni Java 25 usufruiscono di una configurazione utente aggiuntiva all'avvio della JVM per le applicazioni web.

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

Non è consigliabile modificare questo punto di ingresso predefinito, poiché 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à del punto di ingresso

Il punto di ingresso per le versioni Java di seconda generazione può essere personalizzato con le 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-400M
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 -XX:+UseG1GC più configurazione
JAVA_USER_OPTS Altri argomenti JVM Argomenti JVM
JAVA_OPTS Argomenti JVM Argomenti JVM Vedi di seguito

Se non è impostato in modo esplicito, JAVA_OPTS è impostato per impostazione predefinita su:

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

Quando 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

Se esegui la migrazione a un runtime Java di seconda generazione e la tua app utilizza i servizi in bundle legacy, devi tenere presente le seguenti considerazioni:

Esempio (Datastore)

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