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 compatible de Java pour 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 appengine-web.xml fichier 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 différentes versions de Java. 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. Cet exemple permet à votre application d'utiliser uniquement les services groupés Datastore et 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>

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.31</version> <!-- or later-->
  </dependency>

Si votre application utilise un fichier web.xml, configurez l'élément <app-engine-bundled-service>. Pour les paramètres de configuration app_engine_bundled_services, consultez la web.xml référence du fichier.

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

Pour déployer votre application Java 25, exécutez la mvn appengine:deploy ou la 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 pour Java 25

Les applications Java 25 bénéficient 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 Java de deuxième génération 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 Tas 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 la 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 les environnements d'exécution Java de deuxième génération, elle recevra 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 dans votre fichier app.yaml ou appengine-web.xml lorsque vous migrez de Java 8 vers le dernier environnement d'exécution Java.

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.