Como usar o Apache Maven e o plug-in do App Engine (baseado no SDK do App Engine)

Nesta página, você aprende a gerenciar um projeto do App Engine usando o Apache Maven, uma ferramenta de gerenciamento e compreensão de projetos de software. É capaz de criar arquivos WAR para implantação no App Engine. O Google fornece um plug-in e arquétipos do Maven, que estão incluídos no Maven 3.5.

Quando você usa o Maven, não é necessário fazer o download manual das bibliotecas Java a partir do SDK do App Engine. O Maven faz o download automático das bibliotecas necessárias quando necessário. Você também pode usar o Maven para testar o aplicativo localmente e implantá-lo no App Engine de produção.

Como configurar o Maven

Como configurar o Java

  1. Se você não tem o Java, faça o download, a instalação e a configuração dele.
  2. Defina as sinalizações do compilador no pom.xml para especificar o bytecode do Java 8.
    <properties>
      <maven.compiler.source>1.8</maven.compiler.source>
      <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

Como instalar o Maven 3.5

Para determinar se o Maven está instalado e qual versão você tem, chame o seguinte comando:

 mvn -v

Se você não tiver a versão apropriada do Maven instalada:

  1. Faça o download do Maven 3.5 no site do Maven.
  2. Instale o Maven 3.5 na máquina local.

Como configurar e validar seu projeto do Cloud

Você precisa configurar seu projeto do Cloud e instalar o SDK do App Engine.

  1. Use o Console do Google Cloud para criar e configurar seu projeto do Cloud:

    Acessar o App Engine

    1. Selecione ou crie um novo projeto do Cloud.
    2. Para criar um aplicativo do App Engine para o projeto, será enviada uma solicitação para selecionar a região em que o aplicativo ficará localizado.
    3. O Painel será aberto depois que o aplicativo for criado no projeto.
  2. Instale o SDK do App Engine para Java e adicione o diretório ao PATH.

Como usar o Maven

Como adicionar o plug-in do App Engine a um projeto existente (opcional)

Para adicionar o plug-in do Maven do Google App Engine a um projeto existente do Maven, adicione as seguintes informações à seção plugins do arquivo pom.xml do projeto:

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

Como escolher um arquétipo

Os arquétipos do Maven permitem aos usuários criar projetos Maven usando modelos que abordam cenários comuns. O App Engine aproveita esse recurso do Maven para fornecer alguns arquétipos úteis do App Engine no Maven Central. Selecione um arquétipo do App Engine apropriado para o aplicativo:

Tipo de aplicativo Artefato Descrição
Aplicativo do App Engine guestbook-archetype Gera a amostra de demonstração de livro de visitas, completa e pronta para execução e teste.
Aplicativo do App Engine appengine-skeleton-archetype Gera um novo projeto vazio do App Engine pronto para suas próprias classes e recursos, mas com os arquivos e diretórios obrigatórios.

Como criar um novo projeto

Durante a criação do projeto, o Maven solicita que você forneça groupId, artifactId, version e package para o projeto.

Termo Significado
groupId Um namespace dentro do Maven para rastrear os artefatos. Quando as pessoas consumirem o projeto nos próprios projetos Maven, ele funcionará como um atributo da dependência que vão especificar.
artifactId O nome do projeto dentro do Maven. Também é especificado pelos consumidores do projeto quando dependem de você nos próprios projetos Maven.
version A versão inicial do Maven com que gerar o projeto. É uma boa ideia ter version com sufixo -SNAPSHOT, porque isso fornecerá suporte no plug-in de lançamento do Maven para versões que estão em desenvolvimento. Para mais informações, consulte o guia do Maven para usar o plug-in da versão.
package Pacote Java criado durante a geração.

O procedimento a seguir descreve como usar os arquétipos do Maven do App Engine para criar um aplicativo do App Engine.

Para criar um aplicativo do App Engine:

  1. Altere o diretório para um diretório no qual criar o projeto.

  2. Chame o seguinte comando do Maven:

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

    Configure -Dappengine-version com a versão mais recente do SDK do App Engine para Java e application-id com ID do seu projeto do Cloud.

    Configure -Djava8=true para implantar o projeto no ambiente de execução do Java 8.

    Configure -DCloudSDK_Tooling=false para usar o SDK do App Engine para Java.

  3. Quando solicitado a escolher um arquétipo, escolha o valor 2 para o arquétipo da estrutura do App Engine. Isso cria um projeto vazio que contém a estrutura de diretórios e os arquivos obrigatórios.

  4. Quando a versão for solicitada, pressione ENTER para selecionar a versão mais recente padrão.

  5. Quando solicitado a Define value for property 'groupId', forneça o namespace solicitado para seu app. por exemplo, com.mycompany.myapp.

  6. Quando solicitado a Define value for property 'artifactId', forneça o nome do projeto. Por exemplo, myapp.

  7. Quando solicitado a Define value for property 'version', aceite o valor padrão.

  8. Quando solicitado a Define value for property 'package', forneça o nome que preferir para o pacote ou aceite o padrão. Os arquivos do Java gerados terão o nome do pacote que você especificar aqui.

  9. Quando solicitado a confirmar as opções escolhidas, aceite o valor padrão (Y).

  10. Aguarde até que o projeto termine de criar os diretórios e arquivos necessários. Em seguida, vá para o diretório do novo projeto, por exemplo, myapp/.

    Quando o projeto for concluído com êxito, aparecerá uma mensagem semelhante a esta:

    [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 começar a codificar suas próprias classes do aplicativo, familiarize-se com o layout básico do projeto e os arquivos de projeto obrigatórios. Dentro do diretório em que você criou o projeto, haverá um subdiretório denominado myapp, que contém um arquivo pom.xml, o subdiretório src/main/java e o subdiretório src/main/webapp/WEB-INF:

    Layout de projeto Maven

    • Você adicionará suas próprias classes Java de aplicativo a src/main/java/...
    • Você configurará seu aplicativo usando o arquivo src/main/webapp/WEB-INF/appengine-web.xml
    • Você configurará a implantação do aplicativo usando o arquivo src/main/webapp/WEB-INF/web.xml
  12. Crie suas classes Java de aplicativo e adicione-as a src/main/java/.../ Para mais informações, consulte Como criar um aplicativo no App Engine

  13. Adicione a IU que será fornecida aos usuários do app. Para mais informações, consulte Como processar dados de formulário.

  14. O artefato usado para criar o projeto fez a configuração src/main/webapp/WEB-INF/appengine-web.xml básica para você. No entanto, para uma configuração mais avançada, talvez seja necessário editar esse arquivo. Para mais informações, consulte Como configurar com appengine-web.xml.

  15. Edite o arquivo src/main/webapp/WEB-INF/web.xml para mapear URLs para os gerenciadores de apps, especificar a autenticação, os filtros e assim por diante. Isso é descrito em detalhes no descritor de implantação.

Como gerenciar um projeto Maven

Como compilar e criar o projeto

Para criar um aplicativo desenvolvido com os arquétipos do Maven do App Engine:

  1. Altere para o diretório principal do seu projeto, como guestbook/.
  2. Chame o Maven:

    mvn clean package
    
  3. Espere o projeto ser criado. Quando o projeto for concluído com êxito, aparecerá uma mensagem semelhante a esta:

    BUILD SUCCESS
     Total time: 10.724s
     Finished at: Thur Jul 04 14:50:06 PST 2017
     Final Memory: 24M/213M
    
  4. Você tem a opção de testar o aplicativo usando o procedimento a seguir.

Como testar o aplicativo com o servidor de desenvolvimento

Durante a fase de desenvolvimento, é possível executar e testar o aplicativo a qualquer momento no servidor de desenvolvimento chamando o plug-in Maven do App Engine. O procedimento varia um pouco dependendo do artefato usado para criar o projeto.

Para testar o aplicativo:

  1. Se ainda não criou o aplicativo, faça isso (mvn clean package):

  2. Altere o diretório para o nível superior do projeto (por exemplo, para myapp) e invoque o Maven:

    mvn appengine:devserver
    

    Aguarde a inicialização do servidor. Quando o servidor estiver completamente iniciado com o aplicativo em execução, aparecerá uma mensagem semelhante a esta:

    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. Use seu navegador para visitar http://localhost:8080/ e acessar seu aplicativo.

  4. Encerre o aplicativo e o servidor de desenvolvimento pressionando Control + C na janela de terminal do Windows/Linux em que foram iniciados (CMD + C no Mac).

Como especificar uma porta para teste local

Quando você executa o aplicativo no servidor de desenvolvimento local, a porta padrão é 8080. Você pode alterar esse padrão modificando a entrada do plug-in para appengine-maven-plugin (ou adicionando-a, se ela não existir). Por exemplo, especificamos a porta e o endereço na seguinte entrada <plugin> em <plugins> dentro do arquivo pom.xml do diretório principal do aplicativo (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>

Observe que <port> define a porta aqui como 8181, conforme mostrado, e o endereço 0.0.0.0 é especificado, o que significa que o servidor de desenvolvimento detectará solicitações provenientes da rede local.

Implantar o app

Consulte o guia Como implantar o app.

Referência: metas disponíveis

Depois que o plug-in Maven do App Engine é adicionado ao arquivo pom.xml do projeto, várias metas do Maven específicas do App Engine são disponibilizadas. Para ver todas as metas disponíveis, chame o comando:

 mvn help:describe -Dplugin=appengine

As metas do plug-in Maven do App Engine podem ser categorizadas como metas do servidor de desenvolvimento, metas de gerenciamento de aplicativos e projetos e metas do Endpoints.

Metas do servidor de desenvolvimento

Estas são as metas do servidor de desenvolvimento:

appengine:devserver

Executa o servidor de desenvolvimento do App Engine. Quando o servidor está em execução, faz verificações contínuas para determinar se appengine-web.xml foi alterado. Se houver, o servidor fará uma atualização a quente do aplicativo. Isso significa que você não precisa parar e reiniciar o aplicativo devido a alterações em appengine-web.xml. Os seguintes parâmetros estão disponíveis:

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

Por exemplo, para permitir a execução do servidor no modo de depuração na porta 8000 sem suspender no horário de início, você pode usar as seguintes sinalizações:

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

Por padrão, a sinalização <fullScanSeconds> é definida como cinco segundos, o que significa que o servidor verifica, a cada cinco segundos, se houve alterações nos arquivos de aplicativo da Web e atualiza o aplicativo automaticamente. Isso é útil em ambientes de desenvolvimento integrado compatíveis com o recurso compilar ao salvar, como o NetBeans. Para usar esse recurso, você precisa configurar a seção <build>:

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

Executa um início assíncrono para o servidor de desenvolvimento e depois retorna à linha de comando. Quando esta meta é executada, o comportamento dela é igual ao da meta devserver. A diferença é que o Maven continua processando metas e é encerrado depois que o servidor entra em funcionamento.

appengine:devserver_stop

Para o servidor de desenvolvimento. Disponível apenas se você iniciou o servidor de desenvolvimento com appengine:devserver_start.

Metas de gerenciamento de aplicativo

Para gerenciamento de aplicativos e projetos, as metas estão listadas na tabela a seguir:

Meta Descrição Comando gcloud correspondente
appengine:backends_stop Para qualquer servidor de desenvolvimento em execução que escute na porta como configurado no arquivo pom.xml. Essa meta pode ser usada em conjunto com o comando devserver_start para fazer testes de integração com o plug-in do Maven.
appengine:backends_configure Configurar o back-end especificado.
appengine:backends_delete Excluir o back-end especificado.
appengine:backends_rollback Reverter uma atualização anterior em andamento.
appengine:backends_start Iniciar o back-end especificado.
appengine:backends_update Atualizar o back-end especificado ou (se nenhum back-end for especificado) todos os back-ends.
appengine:enhance Executar o otimizador Datanucleus JDO do App Engine.
appengine:rollback Reverter uma atualização em andamento. gcloud app versions start, gcloud app versions stop
appengine:set_default_version Definir a versão padrão do aplicativo. gcloud app services set-traffic
appengine:update Criar ou atualizar a versão de um aplicativo. gcloud app deploy
appengine:update_cron Atualizar os cron jobs do aplicativo. gcloud app deploy
appengine:update_dispatch Atualizar a configuração de expedição do aplicativo. gcloud app deploy
appengine:update_dos Atualizar a configuração de proteção DoS do aplicativo. gcloud app deploy
appengine:update_indexes Atualizar os índices do aplicativo. gcloud datastore create-indexes [INDEX_YAML]
appengine:update_queues Atualizar as definições de fila de tarefas do aplicativo. gcloud app deploy
appengine:vacuum_indexes Excluir os índices não utilizados do aplicativo. gcloud datastore cleanup-indexes [INDEX_YAML]
appengine:start_module_version Iniciar a versão de módulo especificada. gcloud app versions start
appengine:stop_module_version Parar a versão de módulo especificada. gcloud app versions stop

Solução de problemas de erros de upload

Se você usar a meta de atualização, sua tentativa de atualização poderá falhar com uma mensagem semelhante a esta: 404 Not Found This application does not exist (app_id=u'your-app-ID'). Esse erro ocorrerá se você tiver várias contas do Google e estiver usando a conta incorreta para executar a atualização.

Para resolver esse problema, altere os diretórios para ~, localize um arquivo denominado .appcfg_oauth2_tokens_java e renomeie-o. Em seguida, tente atualizar novamente.