Accéder aux anciens services groupés pour Java 11+

Cette page explique comment installer et utiliser les services groupés avec la dernière version de Java compatible avec l'environnement standard App Engine. Votre application peut accéder aux services groupés à l'aide du fichier JAR de l'API App Engine.

Avant de commencer

Installer le fichier JAR de l'API App Engine

Pour utiliser les anciens services groupés dans votre dernière application Java compatible, vous devez utiliser un fichier appengine-web.xml pour configurer votre application (et non un fichier app.yaml).

L'exemple suivant montre comment ajouter des paramètres de configuration dans votre fichier appengine-web.xml pour les versions 21 et ultérieures sur EE10 (par défaut), la version 21 sur EE8, et les versions 17 et antérieures. Pour utiliser la dernière version compatible sur la configuration par défaut, vous devez mettre à jour les servlets et les dépendances de votre application afin d'inclure l'espace de noms Jakarta. Pour en savoir plus sur les options de configuration, consultez la page Mettre à niveau une application existante.

Ajoutez les paramètres suivants à votre fichier appengine-web.xml en fonction de la version de Java :

versions 21 et ultérieures (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>

v7.3 et versions précédentes

<?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>

Pour spécifier les anciens services groupés en tant que dépendance, ajoutez les lignes suivantes dans votre fichier pom.xml :

 <dependency>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-api-1.0-sdk</artifactId>
    <version>2.0.4</version> <!-- or later-->
  </dependency>

Si votre application utilise un fichier web.xml, vous devez ajouter l'élément <app-engine-apis> et le définir sur true :

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

Pour déployer votre application Java 21, exécutez la commande mvn appengine:deploy ou la commande gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml sur une application Web compilée et en préproduction.

Point d'entrée par défaut utilisé par Java 21

Les applications Java 21 peuvent bénéficier d'une configuration utilisateur supplémentaire lors du démarrage de la JVM pour les applications Web.

Le point d'entrée par défaut utilisé pour démarrer la JVM est généré par App Engine Buildpacks. En bref, il est équivalent de définir ce point d'entrée dans le fichier appengine-web.xml. Par exemple :

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

Nous vous déconseillons de modifier ce point d'entrée par défaut, car les paramètres de mémoire sont calculés en fonction du type d'instance (F1, F2, F4) et de la mémoire disponible.

Par défaut, nous utilisons --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED pour ouvrir certaines API de JDK nécessaires.

Fonctionnalités des points d'entrée

Le point d'entrée des versions de deuxième génération Java peut être personnalisé avec des variables d'environnement définies par l'utilisateur ajoutées dans le fichier de configuration appengine-web.xml.

Le tableau suivant indique les variables d'environnement pouvant être utilisées pour activer/désactiver/configurer les fonctionnalités, et les valeurs par défaut si elles ne sont pas définies:

Var. env. Description Type Par défaut
CPROF_ENABLE Stackdriver Profiler boolean false
GAE_MEMORY_MB Mémoire disponible taille Défini par App Engine ou /proc/meminfo-400M
HEAP_SIZE_RATIO Mémoire pour le segment de mémoire pourcentage 80
HEAP_SIZE_MB Segment de mémoire disponible taille ${HEAP_SIZE_RATIO} % sur ${GAE_MEMORY_MB}
JAVA_HEAP_OPTS Arguments JVM du tas de mémoire arguments JVM -Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M
JAVA_GC_OPTS Arguments JVM de Google Cloud Arguments JVM -XX:+UseG1GC plus configuration
JAVA_USER_OPTS Autres arguments JVM arguments JVM
JAVA_OPTS Arguments JVM arguments JVM Voir ci-dessous

Si ces variables ne sont pas définies explicitement, JAVA_OPTS est défini par défaut sur la valeur suivante :

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

Lorsque CPROF_ENABLE a la valeur "true", le point d'entrée par défaut ajoute PROFILER_AGENT comme suit :

-agentpath:/opt/cprof/profiler_java_agent.so=--logtostderr

Par exemple, si le code de votre application nécessite davantage d'options -add-opens, vous pouvez utiliser la variable d'environnement JAVA_USER_OPTS définie dans le fichier appengine-web.xml :

    <env-variables>
       <env-var name="JAVA_USER_OPTS" value="--add-opens java.base/java.util=ALL-UNNAMED" />
     </env-variables>

Considérations sur la migration

Tenez compte des considérations suivantes si vous effectuez une migration vers un environnement d'exécution Java de deuxième génération et que votre application utilise des anciens services groupés :

  • Pour tester les fonctionnalités des anciens services groupés dans votre application Java de deuxième génération, vous pouvez utiliser le serveur de développement local.
  • Contrairement à l'environnement d'exécution Java 8, les environnements d'exécution Java de deuxième génération incluent JVM dans la mémoire de l'instance. Si vous voyez des erreurs liées à la mémoire dans les journaux, envisagez d'augmenter la taille de la classe d'instance dans votre fichier appengine-web.xml.
  • Si votre application tente d'appeler une API qui n'est pas activée pour l'environnement d'exécution Java de deuxième génération, elle reçoit une erreur com.google.apphosting.api.ApiProxy$FeatureNotEnabledException.
  • Toutes les applications sont supposées être "thread-safe" dans les environnements d'exécution Java de deuxième génération. Vous devez supprimer l'élément threadsafe de votre fichier app.yaml ou appengine-web.xml lors de la mise à niveau vers les environnements d'exécution Java 11+.

Exemple (Datastore)

Pour découvrir un exemple d'utilisation de Firestore en mode Datastore (Datastore), consultez l'exemple de code GitHub des anciens services groupés pour Java 11.