Usa Apache Maven y el complemento de App Engine (basado en el SDK de Cloud)

Esta página explica cómo administrar un proyecto de App Engine con Apache Maven, una herramienta de administración y comprensión de proyectos de software. Esta herramienta puede compilar archivos de app web (WAR) para la implementación en App Engine. Google proporciona un complemento y arquetipos de Maven que son compatibles con Maven 3.5 o versiones posteriores.

Maven descarga las bibliotecas Java del SDK de App Engine. Puedes usar Maven para probar tu aplicación de manera local y, también, implementarla en App Engine.

Antes de comenzar

  1. Usa Google Cloud Console para crear y configurar tu proyecto de Cloud:
    Ir a App Engine
    1. Selecciona o crea un proyecto de Cloud nuevo.
    2. Si necesitas crear una aplicación de App Engine para tu proyecto, sigue las indicaciones y selecciona la región donde quieres ubicar tu aplicación de App Engine.
  2. Si no tienes Java, debes descargarlo, instalarlo y configurarlo.
  3. Configura las marcas del compilador de Java en el pom.xml de tu proyecto para especificar el código de bytes de Java 8:
    Java 8
    <properties>
      <maven.compiler.source>1.8</maven.compiler.source>
      <maven.compiler.target>1.8</maven.compiler.target>
    </properties>
  4. Debe tener instalado Maven 3.5 o una versión posterior. Para comprobar si se instaló Maven 3.5 o una versión posterior, ejecuta el siguiente comando:
     mvn -v
  5. Si no tienes instalado Maven 3.5 o una versión más reciente:
    1. Descarga Maven 3.5 o una versión posterior desde el sitio web de Maven.
    2. Instala Maven 3.5 o una versión más reciente en tu máquina local.

      Nota: Es posible que los usuarios de Linux necesiten descargar Maven en lugar de usar apt-get install para instalar Maven 3.5 o una versión más reciente.

  6. No es necesario que instales el SDK de Cloud porque el complemento lo instala de manera automática cuando es necesario.

Agrega el complemento App Engine Maven a un proyecto existente (opcional)

Para usar el complemento de Maven de Google App Engine en un proyecto de Maven existente, agrega lo siguiente a la sección plugins del proyecto pom.xml:

<plugin>
   <groupId>com.google.cloud.tools</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>2.2.0</version>
</plugin>

Elige un arquetipo de App Engine

Los arquetipos de Maven permiten a los usuarios crear proyectos de Maven con plantillas que abarcan situaciones comunes. App Engine aprovecha esta característica de Maven para proporcionar algunos arquetipos de App Engine útiles en Maven Central. Selecciona un arquetipo de App Engine adecuado para tu aplicación:

Tipo de aplicación Artefacto Descripción
App de App Engine appengine-skeleton-archetype Genera un proyecto de App Engine nuevo, vacío y listo para tus propias clases y recursos, pero con archivos y directorios obligatorios.
App de App Engine appengine-standard-archetype Genera una aplicación de Java básica para el entorno estándar de App Engine.
App de App Engine appengine-flexible-archetype Genera una aplicación de Java básica para el entorno flexible de App Engine.

Crea un proyecto nuevo con Maven

Durante la creación del proyecto, Maven solicita que proporciones groupId, artifactId, version y package para el proyecto.

Término Significado
groupId Un espacio de nombres en Maven para hacer un seguimiento de tus artefactos. Cuando las personas consumen tu proyecto en su propio proyecto de Maven, tu proyecto servirá como atributo de la dependencia que especificarán.
artifactId El nombre de tu proyecto en Maven. Los consumidores de tu proyecto también lo especifican cuando dependen de tí en sus propios proyectos de Maven.
version La versión inicial de Maven con la que deseas generar tu proyecto. Se recomienda usar version con el sufijo -SNAPSHOT, ya que esto proporcionará compatibilidad para el complemento de actualización de Maven para las versiones que están en desarrollo. Para obtener más información, consulta la guía de Maven que explica cómo usar el complemento de actualización.
package El paquete de Java creado durante la generación.

Crea una nueva aplicación de App Engine

En el siguiente procedimiento, se describe cómo usar appengine-skeleton-archetype para crear una aplicación de App Engine.

Para usar los arquetipos de Maven de App Engine con el propósito de crear una aplicación de App Engine, sigue estos pasos:

  1. Cambia al directorio donde deseas compilar el proyecto.

  2. Invoca el siguiente comando de Maven:

    mvn archetype:generate -Dappengine-version=1.9.59 -Dapplication-id=[YOUR-PROJECT-ID] -Dfilter=com.google.appengine.archetypes:
    

    Configura -Dappengine-version en la versión más reciente del SDK de App Engine para Java y application-id en el ID de tu proyecto de Cloud.

  3. Para crear un proyecto vacío que contenga la estructura de directorios y los archivos necesarios, para tus propias clases, proporciona el número correspondiente a com.google.appengine.archetypes:appengine-skeleton-archetype.

  4. Selecciona la versión más reciente de la lista que se muestra de las versiones de arquetipo disponibles aceptando el valor predeterminado.

  5. Cuando debas configurar Define value for property 'groupId', proporciona el espacio de nombres que desees para tu aplicación, por ejemplo, com.mycompany.myapp.

  6. Cuando debas configurar Define value for property 'artifactId', ingresa el nombre del proyecto, por ejemplo, myapp.

  7. Cuando debas configurar Define value for property 'version', acepta el valor predeterminado.

  8. Cuando debas configurar Define value for property 'package', proporciona tu nombre de paquete preferido (o acepta el predeterminado). Los archivos de Java generados tendrán el nombre de paquete que especifiques aquí.

  9. Cuando se solicite confirmar tus elecciones, acepta el valor predeterminado (Y).

  10. Espera a que el proyecto termine de generarse y, luego, cambia de directorio al directorio del proyecto nuevo, por ejemplo, myapp/.

  11. Compila el proyecto invocando

        mvn clean package
    
  12. Espera a que se compile el proyecto. Cuando el proyecto se complete con éxito, verás un mensaje similar a este:

        [INFO] --------------------------------------------------
        [INFO] BUILD SUCCESS
        [INFO] --------------------------------------------------
        [INFO] Total time: 1:16.656s
        [INFO] Finished at: 2016-08-04T16:18:24-07:00
        [INFO] Final Memory: 16M/228M
        [INFO] --------------------------------------------------
    
  13. Si creaste una app nueva y vacía con el artefacto appengine-skeleton-archetype:

    1. Antes de comenzar a codificar tus propias clases para la app, familiarízate con el diseño básico del proyecto y los archivos necesarios del proyecto. Dentro del directorio donde creaste el proyecto, tendrás un subdirectorio llamado myapp, que contiene un archivo pom.xml, el subdirectorio src/main/java, y el subdirectorio src/main/webapp/WEB-INF:

      Diseño de proyecto de Maven

      • Agrega las clases Java de tu propia aplicación a src/main/java/...
      • Configura tu aplicación con el archivo src/main/webapp/WEB-INF/appengine-web.xml
      • Configura la implementación de tu aplicación con el archivo src/main/webapp/WEB-INF/web.xml
    2. Crea las clases Java de tu aplicación y agrégalas a src/main/java/.... Para obtener más información, consulta Cómo comenzar.

    3. Agrega la IU que deseas proporcionar a los usuarios de tu app. Para obtener más información, consulta cómo agregar el código de aplicación y la IU.

    4. El artefacto que usaste para crear el proyecto realizó la configuración básica de src/main/webapp/WEB-INF/appengine-web.xml. Sin embargo, para una configuración más avanzada, es posible que debas editar este archivo. Para obtener más información, consulta Configura con appengine-web.xml.

    5. Edita el archivo src/main/webapp/WEB-INF/web.xml para asignar las URL a tus controladores de aplicaciones, especificar la autenticación, los filtros y demás. Esto se describe de forma detallada en El descriptor de implementación.

Administra, prueba e implementa un proyecto de Maven

Crea y compila tu proyecto

Para compilar una aplicación creada con los arquetipos de App Engine Maven:

  1. Cambia al directorio principal de tu proyecto.

  2. Invoca Maven:

    mvn clean package
    
  3. Espera a que se compile el proyecto. Cuando el proyecto se complete con éxito, verás un mensaje similar a este:

    BUILD SUCCESS
     Total time: 10.724s
     Finished at: 2016-08-04T16:18:24-07:00
     Final Memory: 24M/213M
    
  4. O bien, prueba la aplicación con el siguiente procedimiento.

Prueba tu aplicación con el servidor de desarrollo

Durante la fase de desarrollo, puedes ejecutar y probar tu aplicación en cualquier momento en el servidor de desarrollo invocando el complemento App Engine Maven.

Para probar tu aplicación de App Engine:

  1. Si aún no lo hiciste, sigue estos pasos:

    mvn clean package
    
  2. Cambia el directorio al nivel superior de tu proyecto (por ejemplo, a myapp) y, luego, invoca Maven:

    mvn appengine:run
    

    Espera a que inicie el servidor. Cuando el servidor se inicie completamente con tu aplicación en ejecución, verás un mensaje similar a este:

    [INFO] GCLOUD: INFO: Module instance default is running at http://localhost:44180/
    [INFO] GCLOUD: Jul 29, 2016 9:23:55 PM com.google.appengine.tools.development.AbstractModule startup
    [INFO] GCLOUD: INFO: The admin console is running at http://localhost:44180/_ah/admin
    [INFO] GCLOUD: Jul 29, 2016 9:23:55 PM com.google.appengine.tools.development.devappserver2.DevAppServer2Impl doStart
    [INFO] GCLOUD: INFO: Dev App Server is now running
    
  3. Usa tu navegador para visitar http://localhost:8080/ y acceder a tu app.

  4. Cierra la aplicación y el servidor de desarrollo presionando Control+C.

Especifica un puerto para pruebas locales

Cuando ejecutes tu aplicación en el servidor de desarrollo local, el puerto predeterminado es 8080. Puedes modificar la entrada del complemento para appengine-maven-plugin a fin de cambiar este valor predeterminado. Por ejemplo, puedes especificar el puerto y la dirección en el archivo pom.xml del directorio de tu aplicación de la siguiente forma:

<plugins>
   <plugin>
     <groupId>com.google.cloud.tools</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>2.2.0</version>
     <configuration>
       <devserver.host>0.0.0.0</devserver.host>
       <devserver.port>8181</devserver.port>
     </configuration>
  </plugin>
</plugins>

En este ejemplo, <devserver.port> configura el puerto en 8181 en lugar de en el valor predeterminado, y se especifica la dirección 0.0.0.0, lo que significa que el servidor de desarrollo recibe solicitudes provenientes de la red local.

El prefijo devserver es opcional; puedes usar <port>8181</port> en su lugar.

Realizar la depuración en el servidor de desarrollo

Para depurar una aplicación que se ejecuta de manera local, configura jvmFlags en la configuración del complemento a fin de habilitar la depuración en la JVM subyacente, por ejemplo:

<configuration>
  <jvmFlags>
    <jvmFlag>-Xdebug</jvmFlag>
    <jvmFlag>-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005</jvmFlag>
  </jvmFlags>
</configuration>

Implementar tu aplicación

Para implementar tu aplicación:

mvn package appengine:deploy -Dapp.deploy.projectId=PROJECT_ID

Reemplaza PROJECT_ID con el ID de tu proyecto de Cloud. Si tu archivo pom.xml ya especifica tu ID del proyecto, no necesitas incluir la propiedad -Dapp.deploy.projectId en el comando que ejecutas.

El objetivo de appengine:deploy y todos los demás objetivos del complemento de Maven de App Engine tienen parámetros asociados que puedes usar. Para obtener una lista completa de objetivos y parámetros, consulta Objetivos y parámetros del complemento App Engine Maven.

Qué sigue