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 si 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 options de compilation dans le fichier pom.xml de manière à spécifier l'utilisation du bytecode Java 8.
    <properties>
      <maven.compiler.source>1.8</maven.compiler.source>
      <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

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 Cloud

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

  1. Utilisez Google Cloud Console pour créer et configurer votre projet Cloud :

    Accéder à App Engine

    1. Sélectionnez ou créez un projet Cloud.
    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 dans 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.89</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 exploite 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 et 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 un élément 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.89 -Djava8=true -DCloudSDK_Tooling=false -Dapplication-id=your-app-id -Dfilter=com.google.appengine.archetypes:
    

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

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

    Définissez l'option -DCloudSDK_Tooling=false pour utiliser le 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 et les fichiers de projet requis : 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

    • Vous allez ajouter vos propres classes Java d'application à src/main/java/....
    • Vous allez configurer votre application à l'aide du fichier src/main/webapp/WEB-INF/appengine-web.xml.
    • Vous allez configurer le déploiement de votre application à l'aide du fichier src/main/webapp/WEB-INF/web.xml.
  12. Créez vos classes Java d'application et ajoutez-les à src/main/java/.../. Pour en savoir plus, consultez la page Construire 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 Documentation de référence sur appengine-web.xml.

  15. Modifiez le fichier src/main/webapp/WEB-INF/web.xml pour mapper les URL aux gestionnaires d'applications, spécifier l'authentification, les filtres, etc. Ce processus est décrit en détail sur la page 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. Définissez le répertoire sur le 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 remplacer 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). Par exemple, nous spécifions le port et l'adresse dans l'entrée <plugin> suivante dans <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.89</version>
     <configuration>
         <enableJarClasses>false</enableJarClasses>
         <port>8181</port>
         <address>0.0.0.0</address>
     </configuration>
 </plugin>

Notez que <port> définit ici le port sur 8181, et que l'adresse 0.0.0.0 est spécifiée, ce qui signifie que le serveur de développement écoute 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 appengine-web.xml a changé. Le cas échéant, le serveur effectue un rechargement à chaud de l'application. Cela signifie que vous n'avez pas besoin d'arrêter et de redémarrer votre application en raison des modifications apportées à 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'option <fullScanSeconds> est définie 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é conjointement 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 d'une mise à jour en cours 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

Résoudre 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 ~, recherchez un fichier nommé .appcfg_oauth2_tokens_java et renommez-le. Ensuite, essayez à nouveau d'effectuer la mise à jour.