Utiliser Apache Maven et le plug-in App Engine (basé sur le SDK App Engine)

Cette page explique comment gérer un projet App Engine à l'aide d'Apache Maven, un outil de gestion et de compréhension des projets logiciels capable de créer des fichiers WAR à déployer dans App Engine. Google fournit un plugin et des archétypes Maven qui sont inclus avec Maven 3.5.

Lorsque vous utilisez Maven, vous n'avez pas besoin de télécharger manuellement les bibliothèques Java à partir du SDK App Engine. Maven télécharge automatiquement les bibliothèques appropriées lorsque cela est nécessaire. Vous pouvez également utiliser Maven pour tester votre application localement et la déployer dans l'environnement de production App Engine.

Configurer Maven

Configurer Java

  1. Si vous n'avez pas encore Java, téléchargez, installez et configurez Java.
  2. Définissez les indicateurs de compilation dans le fichier pom.xml pour spécifier l'utilisation du bytecode Java 7 ou Java 8. Reportez-vous aux paragraphes correspondants ci-dessous pour découvrir les paramètres. Notez que l'environnement d'exécution App Engine Java 7 nécessite le bytecode Java 7.

Installer Maven 3.5

Pour déterminer si Maven est installé et de quelle version vous disposez, utilisez la commande suivante :

 mvn -v

Si la version installée de Maven ne convient pas :

  1. Téléchargez Maven 3.5 depuis le site Web Maven.
  2. Installez Maven 3.5 sur votre ordinateur local.

Configurer et valider votre projet GCP

Vous devez configurer votre projet GCP et installer le SDK App Engine :

  1. Utilisez la console Google Cloud Platform pour créer et configurer votre projet GCP :

    Accéder à App Engine

    1. Sélectionnez ou créez un projet GCP.
    2. Si vous devez créer une application App Engine pour votre projet, vous êtes invité à sélectionner la région dans laquelle vous souhaitez placer cette application.
    3. Le tableau de bord s'ouvre une fois l'application App Engine créée dans votre projet.
  2. Installez le SDK App Engine pour Java et ajoutez le répertoire à votre variable PATH.

Utiliser Maven

Ajouter le plug-in App Engine à un projet existant (facultatif)

Pour ajouter le plug-in Google App Engine Maven à un projet Maven existant, ajoutez les éléments suivants dans la section plugins du fichier pom.xml du projet :

<plugin>
   <groupId>com.google.appengine</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>1.9.76</version>
</plugin>

Choisir un archétype

Les archétypes Maven permettent aux utilisateurs de créer des projets Maven à l'aide de modèles couvrant des scénarios courants. App Engine tire parti de cette fonctionnalité Maven pour fournir des archétypes App Engine utiles dans le dépôt central de Maven. Sélectionnez un archétype App Engine adapté à votre application :

Type d'application Artefact Description
Application App Engine guestbook-archetype Génère l’exemple de démonstration du livre d'or, complet et prêt à être exécuté et testé.
Application App Engine appengine-skeleton-archetype Génère un nouveau projet App Engine vide et prêt pour accueillir vos propres classes et ressources, mais avec l'ensemble des fichiers et répertoires requis.

Créer un projet

Lors de la création d'un projet, Maven vous invite à fournir les éléments suivants : groupId, artifactId, version ainsi que le package.

Terme Signification
groupId Espace de noms au sein de Maven permettant le suivi vos artefacts. Lorsque des personnes utilisent votre projet dans leur propre projet Maven, cet espace de noms servira d'attribut de la dépendance qu'elles devront spécifier.
artifactId Nom de votre projet au sein de Maven. Celui-ci est également spécifié par les utilisateurs de votre projet lorsque leurs propres projets Maven en dépendent.
version Version initiale de Maven à partir de laquelle vous souhaitez générer votre projet. Il est recommandé de choisir une version dont le suffixe est -SNAPSHOT, car cela garantit la compatibilité de votre plug-in Maven avec les versions en cours de développement. Pour plus d'informations, consultez le guide Maven sur l'utilisation de la dernière version du plug-in.
package Package Java créé lors de la génération du projet.

La procédure suivante explique comment utiliser les archétypes App Engine Maven pour créer une application App Engine.

Pour créer une application App Engine :

  1. Remplacez le répertoire actuel par celui dans lequel vous voulez créer le projet.

  2. Appelez la commande Maven suivante :

     mvn archetype:generate -Dappengine-version=1.9.76 -Djava8=true -DCloudSDK_Tooling=false -Dapplication-id=your-app-id -Dfilter=com.google.appengine.archetypes:
    

    Définissez -Dappengine-version sur la version la plus récente du SDK App Engine pour Java, et application-id sur l'ID du projet GCP.

    Définissez -Djava8=false pour déployer le projet dans l'environnement d'exécution Java 7.

    Définissez -Djava8=true pour déployer le projet dans l'environnement d'exécution Java 8.

    Définissez -DCloudSDK_Tooling=false pour utiliser les outils SDK App Engine pour Java.

  3. Lorsque vous êtes invité à choisir un archétype, choisissez la valeur 2 pour l'archétype du squelette App Engine. Cela crée un projet vide contenant la structure de répertoire et les fichiers requis.

  4. Lorsque vous êtes invité à indiquer la version, appuyez sur Entrée pour sélectionner la version la plus récente par défaut.

  5. Lorsque l'invite Define value for property 'groupId' s'affiche, indiquez l'espace de noms souhaité pour l'application, par exemple com.mycompany.myapp.

  6. Lorsque l'invite Define value for property 'artifactId' s'affiche, indiquez le nom du projet, par exemple myapp.

  7. Lorsque l'invite Define value for property 'version' s'affiche, acceptez la valeur par défaut.

  8. Lorsque l'invite Define value for property 'package' s'affiche, indiquez le nom du package souhaité (ou acceptez le nom par défaut). Les fichiers Java générés portent le nom du package que vous spécifiez ici.

  9. Lorsque vous êtes invité à confirmer vos choix, acceptez la valeur par défaut (Y).

  10. Attendez que le projet ait fini de créer les répertoires et les fichiers nécessaires. Accédez ensuite au nouveau répertoire du projet, par exemple myapp/.

    Un message semblable à celui-ci s'affiche alors :

    [INFO] --------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] --------------------------------------------------
    [INFO] Total time: 1:16.656s
    [INFO] Finished at: 2017-06-04T16:18:24-07:00
    [INFO] Final Memory: 16M/228M
    [INFO] --------------------------------------------------
    
  11. Avant de commencer à coder vos propres classes pour l’application, familiarisez-vous avec la structure de base du projet. Les fichiers de projet requis sont terminés : dans le répertoire où vous avez créé le projet se trouvent un sous-répertoire nommé myapp contenant un fichier pom.xml, le sous-répertoire src/main/java et le sous-répertoire src/main/webapp/WEB-INF.

    Arborescence projet de Maven

    • Ajoutez vos propres classes Java dans src/main/java/...
    • Configurez votre application avec le fichier src/main/webapp/WEB-INF/appengine-web.xml
    • Configurez le déploiement de votre application avec le fichier src/main/webapp/WEB-INF/web.xml
  12. Créez les classes Java pour votre application et ajoutez-les à src/main/java/.../ Pour en savoir plus, consultez la page Créer une application sur App Engine.

  13. Ajoutez l'UI que vous souhaitez fournir aux utilisateurs de l'application. Pour en savoir plus, consultez la page Gérer les données de formulaire.

  14. L'artefact que vous avez utilisé pour créer le projet a effectué la configuration src/main/webapp/WEB-INF/appengine-web.xml de base. Toutefois, pour une configuration plus avancée, vous devrez peut-être modifier ce fichier. Pour en savoir plus, consultez la page Référence appengine-web.xml.

  15. Modifiez le fichier src/main/webapp/WEB-INF/web.xml pour mapper les URL aux gestionnaires de vos applications, spécifier l’authentification, les filtres, etc. Ce processus est décrit en détail dans Descripteur de déploiement.

Gérer un projet Maven

Compiler et créer un projet

Pour créer une application basée sur les archétypes App Engine Maven, procédez comme suit :

  1. Accédez au répertoire principal de votre projet, par exemple guestbook/.
  2. Appelez Maven :

    mvn clean package
    
  3. Attendez que le projet se crée. Un message semblable à celui-ci s'affiche alors :

    BUILD SUCCESS
     Total time: 10.724s
     Finished at: Thur Jul 04 14:50:06 PST 2017
     Final Memory: 24M/213M
    
  4. Vous pouvez également tester l'application créée en suivant la procédure décrite ci-dessous.

Tester votre application avec un serveur de développement

À tout moment pendant la phase de développement, vous pouvez exécuter et tester votre application sur le serveur de développement en appelant le plug-in App Engine Maven. La procédure varie légèrement en fonction de l'artefact utilisé pour créer le projet.

Pour tester votre application :

  1. Si ce n'est pas déjà fait, créez votre application (mvn clean package).

  2. Déplacez le répertoire au niveau supérieur de votre projet (par exemple, myapp) et appelez Maven :

    mvn appengine:devserver
    

    Attendez que le serveur démarre. Une fois le serveur complètement démarré et votre application en cours d'exécution, un message semblable à celui-ci s'affiche :

    Aug 24, 2017 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
    INFO: The server is running at http://localhost:8080/
    Aug 24, 2017 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
    INFO: The admin console is running at http://localhost:8080/_ah/admin
    
  3. Ouvrez http://localhost:8080/ dans votre navigateur pour accéder à votre application.

  4. Fermez l'application et le serveur de développement en appuyant sur Ctrl+C dans la fenêtre de terminal Windows/Linux où vous avez démarré l'application, ou CMD+C sous Mac.

Spécifier un port pour les tests locaux

Lorsque vous exécutez votre application sur un serveur de développement local, le port par défaut est 8080. Vous pouvez changer cette valeur par défaut en modifiant l'entrée du plug-in pour appengine-maven-plugin (ou en l'ajoutant si elle n'existe pas). Dans l'exemple suivant, nous spécifions le port et l'adresse dans l'entrée <plugin> de <plugins> dans le fichier pom.xml du répertoire principal de l'application (myapp/pom.xml) :

 <plugin>
     <groupId>com.google.appengine</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>1.9.76</version>
     <configuration>
         <enableJarClasses>false</enableJarClasses>
         <port>8181</port>
         <address>0.0.0.0</address>
     </configuration>
 </plugin>

Notez que dans cet exemple, <port> définit le port sur 8181 et l'adresse 0.0.0.0 est spécifiée, ce qui signifie que le serveur de développement écoutera les requêtes provenant du réseau local.

Déployer l'application

Consultez le guide Déployer votre application.

Référence : objectifs disponibles

Une fois que le plug-in App Engine Maven est ajouté au fichier pom.xml du projet, plusieurs objectifs Maven spécifiques à App Engine sont disponibles. Pour voir tous les objectifs disponibles, appelez la commande :

 mvn help:describe -Dplugin=appengine

Les objectifs du plug-in App Engine Maven sont les suivants : objectifs du serveur de développement, objectifs de gestion des applications et des projets, et objectifs des points de terminaison.

Objectifs du serveur de développement

Voici les objectifs du serveur de développement :

appengine:devserver

Exécute le serveur de développement App Engine. Lorsque le serveur est en cours d'exécution, il vérifie en permanence si le fichier appengine-web.xml a été modifié. Le cas échéant, le serveur effectue un rechargement à chaud de l'application. Ainsi, vous n'avez pas besoin d'arrêter ni de redémarrer votre application en raison des modifications apportées au fichier appengine-web.xml. Les paramètres suivants sont disponibles :

  • <fullScanSeconds>
  • <address>
  • <disableUpdateCheck>
  • <jvmFlags>
  • <port>
  • <server>

Par exemple, pour activer l'exécution du serveur en mode de débogage sur le port 8000 sans suspension au moment du démarrage, vous pouvez utiliser les indicateurs suivants :

<jvmFlags>
  <jvmFlag>-Xdebug</jvmFlag>
  <jvmFlag>-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n</jvmFlag>
</jvmFlags>

Par défaut, l'indicateur <fullScanSeconds> est défini sur cinq secondes, ce qui signifie que le serveur vérifie toutes les cinq secondes les modifications apportées aux fichiers de l'application Web et actualise automatiquement l'application. Ceci est utile avec les IDE qui possèdent la fonctionnalité de compilation lors de l’enregistrement, comme NetBeans. Pour utiliser cette fonctionnalité, vous devez configurer la section <build> :

<build>
   <outputDirectory>target/${project.artifactId}-${project.version}/WEB-INF/classes</outputDirectory>
   <plugins>
      ....
   </plugins>
</build>
appengine:devserver_start

Effectue un démarrage asynchrone du serveur de développement, puis retourne à la ligne de commande. Lorsque cet objectif est exécuté, le comportement est identique à celui de l'objectif devserver, à la différence que Maven continue de traiter les objectifs et se ferme une fois que le serveur est opérationnel.

appengine:devserver_stop

Arrête le serveur de développement. Disponible uniquement si vous avez démarré le serveur de développement avec appengine:devserver_start.

Objectifs de gestion des applications

Pour la gestion des applications et des projets, les objectifs sont répertoriés dans le tableau suivant :

Objectif Description Commande gcloud correspondante
appengine:backends_stop Arrête tout serveur de développement à l'écoute sur le port tel que configuré dans le fichier pom.xml. Cet objectif peut être utilisé avec la commande devserver_start pour effectuer des tests d'intégration avec le plug-in Maven.
appengine:backends_configure Configurer le backend spécifié.
appengine:backends_delete Supprimer le backend spécifié.
appengine:backends_rollback Effectuer un rollback pour une mise à jour précédemment en cours.
appengine:backends_start Démarrer le backend spécifié.
appengine:backends_update Mettre à jour le backend spécifié ou tous les backends si aucun backend n'a été spécifié.
appengine:enhance Exécuter l'outil d'enrichissement JDO Datanucleus d'App Engine.
appengine:rollback Effectuer un rollback pour une mise à jour en cours d'exécution. gcloud app versions start, gcloud app versions stop
appengine:set_default_version Définir la version de l'application par défaut. gcloud app services set-traffic
appengine:update Créer ou mettre à jour une version de l'application. gcloud app deploy
appengine:update_cron Mettre à jour les tâches cron de l'application. gcloud app deploy
appengine:update_dispatch Mettre à jour la configuration de distribution de l'application. gcloud app deploy
appengine:update_dos Mettre à jour la configuration de la protection DoS pour l'application. gcloud app deploy
appengine:update_indexes Mettre à jour les index d'application. gcloud datastore create-indexes [INDEX_YAML]
appengine:update_queues Mettre à jour les définitions de la file d'attente des tâches d'application. gcloud app deploy
appengine:vacuum_indexes Supprimer les index non utilisés de l'application. gcloud datastore cleanup-indexes [INDEX_YAML]
appengine:start_module_version Démarrer la version de module spécifiée. gcloud app versions start
appengine:stop_module_version Arrêter la version de module spécifiée. gcloud app versions stop

Dépanner les erreurs d'importation

Si vous utilisez l'objectif de mise à jour, votre tentative de mise à jour peut échouer avec un message semblable à celui-ci : 404 Not Found This application does not exist (app_id=u'your-app-ID'). Cette erreur se produira si vous avez plusieurs comptes Google et utilisez le mauvais compte pour effectuer la mise à jour.

Pour résoudre ce problème, remplacez les répertoires par ~, cherchez un fichier nommé .appcfg_oauth2_tokens_java et renommez-le. Ensuite, essayez à nouveau d'effectuer la mise à jour.