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
Consultez la liste des API des anciens services groupés que vous pouvez appeler dans la dernière version compatible de Java.
Cette page nécessite que votre application exécute Java 11 ou une version ultérieure. Pour migrer votre application de l'environnement d'exécution de première génération vers les environnements d'exécution de deuxième génération, examinez les différences entre Java 8 et Java 11 et versions ultérieures et les considérations sur la migration.
Si vous utilisez d'anciens services groupés et que vous souhaitez passer à Java 21, consultez la page Mettre à niveau une application existante pour en savoir plus sur les options de configuration.
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 fichierapp.yaml
ouappengine-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.