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

En esta página se explica cómo administrar un proyecto de App Engine con Apache Maven, una herramienta de administración y comprensión de proyectos de software. Es capaz de compilar archivos WAR para la implementación en App Engine. Google proporciona un complemento y arquetipos de Maven que se incluyen en Maven 3.5.

Cuando usas Maven, no necesitas descargar manualmente las bibliotecas de Java desde el SDK de App Engine. Maven descarga automáticamente las bibliotecas apropiadas cuando es necesario. También puedes usar Maven para probar tu app de forma local y luego implementarla en la producción de App Engine.

Configura Maven

Configura Java

  1. Si no tienes Java, debes descargarlo, instalarlo y configurarlo.
  2. Establece los indicadores del compilador en pom.xml para especificar el código de bytes de Java 8.
    <properties>
      <maven.compiler.source>1.8</maven.compiler.source>
      <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

Instala Maven 3.5

Para determinar si Maven está instalado y qué versión tienes, invoca el siguiente comando:

 mvn -v

Si no tienes instalada la versión correcta de Maven:

  1. Descarga Maven 3.5 del sitio web de Maven.
  2. Instala Maven 3.5 en tu equipo local.

Configura y valida tu proyecto de Cloud

Debes configurar tu proyecto de Cloud e instalar el SDK de App Engine:

  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, se te solicitará que selecciones la región donde quieres que se ubique tu app de App Engine.
    3. El Panel se abrirá luego de que se cree tu aplicación de App Engine en tu proyecto.
  2. Instala el SDK de App Engine para Java y agrega el directorio a tu PATH.

Usa Maven

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

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

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

Elige un arquetipo

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

Tipo de aplicación Artefacto Descripción
App de App Engine guestbook-archetype Genera la muestra de demostración del libro de visitas, lista para ejecutarla y realizar pruebas.
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.

Crea un proyecto nuevo

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.

El siguiente procedimiento describe cómo usar los arquetipos de Maven de App Engine para crear una aplicación de App Engine.

Para crear una app de App Engine, sigue estos pasos:

  1. Cambia el directorio a uno donde desees compilar el proyecto.

  2. Invoca el siguiente comando de Maven:

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

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

    Configura -Djava8=true para implementar el proyecto en el entorno de ejecución de Java 8.

    Configura -DCloudSDK_Tooling=false a fin de usar las herramientas del SDK de App Engine para Java.

  3. Cuando se solicite elegir un arquetipo, elige el valor 2 para el arquetipo de App Engine. Esto crea un proyecto vacío que contiene la estructura de directorio y los archivos requeridos.

  4. Cuando se solicite la versión, presiona INTRO para seleccionar la versión predeterminada más reciente.

  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 crear los directorios y archivos necesarios. A continuación, vaya al nuevo directorio del proyecto, por ejemplo, myapp/.

    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: 2017-06-04T16:18:24-07:00
    [INFO] Final Memory: 16M/228M
    [INFO] --------------------------------------------------
    
  11. Antes de comenzar a codificar tus propias clases para la app, familiarízate con el diseño básico del proyecto y completa los archivos de proyecto requeridos: 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

    • Agregará sus propias clases de Java para aplicaciones a src/main/java/...
    • Configurará su aplicación con el archivo src/main/webapp/WEB-INF/appengine-web.xml.
    • Configurará la implementación de su aplicación con el archivo src/main/webapp/WEB-INF/web.xml.
  12. Crea las clases Java de tu aplicación y agrégalas a src/main/java/.... Para obtener más información, consulta Compila una aplicación en App Engine.

  13. Agrega la IU que deseas proporcionar a los usuarios de tu app. Para obtener más información, consulta Maneja datos de formulario.

  14. El artefacto que usaste para crear el proyecto realizó la configuración src/main/webapp/WEB-INF/appengine-web.xml básica por ti. 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.

  15. 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 un proyecto de Maven

Crea y compila tu proyecto

Para compilar una app creada con los arquetipos de Maven de App Engine, realiza los siguientes pasos:

  1. Cambia el directorio al directorio principal de tu proyecto, por ejemplo, guestbook/
  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: Thur Jul 04 14:50:06 PST 2017
     Final Memory: 24M/213M
    
  4. También puedes probar la aplicación con el procedimiento siguiente.

Prueba tu app con el servidor de desarrollo

Durante la fase de desarrollo, puedes ejecutar y probar tu app en cualquier momento en el servidor de desarrollo con el complemento de Maven de App Engine. El procedimiento varía ligeramente según el artefacto utilizado para crear el proyecto.

Para probar tu app, haz lo siguiente:

  1. Compila tu aplicación (mvn clean package) si aún no lo has hecho.

  2. Cambia el directorio al nivel superior de tu proyecto (por ejemplo, a myapp) e invoca Maven:

    mvn appengine:devserver
    

    Espera a que inicie el servidor. Cuando el servidor se inicie por completo con la app en ejecución, verás un mensaje similar al siguiente:

    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. Usa tu navegador para visitar http://localhost:8080/ y acceder a tu app.

  4. Cierra la app y el servidor de desarrollo con Control+C en la ventana de terminal de Windows o Linux donde lo iniciaste, o CMD+C en Mac.

Especifica un puerto para pruebas locales

Cuando ejecutas tu app en el servidor de desarrollo local, el puerto predeterminado es 8080. Puedes cambiar este valor predeterminado si modificas la entrada del complemento para appengine-maven-plugin (o la agregas si no existe). Por ejemplo, especificamos el puerto y la dirección en la siguiente entrada <plugin> dentro de <plugins> dentro del archivo pom.xml del directorio principal de la app (myapp/pom.xml ):

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

Ten en cuenta que <port> establece el puerto aquí como 8181 como se muestra, y especifica la dirección 0.0.0.0, lo que significa que el servidor de desarrollo escuchará las solicitudes provenientes de la red local.

Implementa tu app

Consulta la guía Implementa tu app.

Referencia: objetivos disponibles

Una vez que el complemento de App Engine Maven se agrega al archivo pom.xml del proyecto, hay varios objetivos de Maven específicos de App Engine disponibles. Para ver todos los objetivos disponibles, invoca el comando:

 mvn help:describe -Dplugin=appengine

Los objetivos del complemento de Maven de App Engine se pueden clasificar como objetivos del servidor de desarrollo, objetivos de administración de proyectos y aplicaciones, y objetivos de Endpoints.

Objetivos del servidor de desarrollo

Estos son los objetivos del servidor de desarrollo:

appengine:devserver

Ejecuta el servidor de desarrollo de App Engine. Cuando el servidor se está ejecutando, comprueba continuamente si appengine-web.xml cambió. Si es así, el servidor vuelve a cargar la aplicación en caliente. Esto significa que no necesitas detener y reiniciar tu aplicación debido a los cambios en appengine-web.xml. Están disponibles los siguientes parámetros:

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

Por ejemplo, para habilitar la ejecución del servidor en modo de depuración en el puerto 8000 sin suspender en el inicio, puedes usar las siguientes marcas:

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

De forma predeterminada, la marca <fullScanSeconds> se establece en 5 segundos, lo que significa que el servidor comprueba cada 5 segundos los cambios en los archivos de la aplicación web y vuelve a cargar la aplicación automáticamente. Esto es útil con IDE que admiten la función compilar cuando se guarda, como NetBeans. Para usar esta función, debes configurar la sección <build>:

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

Realiza un inicio asíncrono para el servidor de desarrollo y luego regresa a la línea de comandos. Cuando se ejecuta este objetivo, el comportamiento es el mismo que el objetivo devserver, con la diferencia de que Maven continúa procesando objetivos y se cierra después de que el servidor esté en funcionamiento.

appengine:devserver_stop

Detiene el servidor de desarrollo. Disponible solo si iniciaste el servidor de desarrollo con appengine:devserver_start.

Objetivos de administración de aplicaciones

Para la administración de aplicaciones y proyectos, los objetivos son los que figuran en la siguiente tabla:

Objetivo Descripción Comando gcloud correspondiente
appengine:backends_stop De esta forma, se detendrá cualquier servidor de desarrollo en ejecución que esté escuchando en el puerto como se configuró en tu archivo pom.xml. Este objetivo se puede usar junto con el comando devserver_start para realizar pruebas de integración con el complemento Maven.
appengine:backends_configure Configura el backend especificado.
appengine:backends_delete Borra el backend especificado.
appengine:backends_rollback Revierte una actualización que estaba en progreso.
appengine:backends_start Inicia el backend especificado.
appengine:backends_update Actualiza el backend especificado o (si no se especifica ninguno) todos los backends.
appengine:enhance Ejecuta el optimizador de JDO de Datanucleus para App Engine.
appengine:rollback Revertir una actualización en curso. gcloud app versions start, gcloud app versions stop
appengine:set_default_version Configurar la versión de la aplicación predeterminada gcloud app services set-traffic
appengine:update Crea o actualiza una versión de la app. gcloud app deploy
appengine:update_cron Actualiza los trabajos cron en curso. gcloud app deploy
appengine:update_dispatch Actualiza la configuración de despacho de la aplicación. gcloud app deploy
appengine:update_dos Actualiza la configuración de protección contra DoS de la aplicación. gcloud app deploy
appengine:update_indexes Actualiza los índices de la aplicación. gcloud datastore create-indexes [INDEX_YAML]
appengine:update_queues Actualiza las definiciones de la lista de tareas en cola de la aplicación. gcloud app deploy
appengine:vacuum_indexes Borra los índices sin uso de la aplicación. gcloud datastore cleanup-indexes [INDEX_YAML]
appengine:start_module_version Inicia la versión especificada del módulo. gcloud app versions start
appengine:stop_module_version Detiene la versión especificada del módulo. gcloud app versions stop

Soluciona errores de carga

Si usas el objetivo de actualización, tu intento de actualización puede fallar con un mensaje similar a este: 404 Not Found This application does not exist (app_id=u'your-app-ID'). Este error se producirá si tienes varias Cuentas de Google y usas la cuenta incorrecta para realizar la actualización.

Para resolver este problema, cambia los directorios a ~, busca un archivo llamado .appcfg_oauth2_tokens_java y cámbiale el nombre. Luego, intenta actualizar de nuevo.