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

Nesta página, explicamos como gerenciar um projeto do App Engine usando o Apache Maven, uma ferramenta de gerenciamento e compreensão de projetos de software. Ele é capaz de criar arquivos do aplicativo da Web (WAR, na sigla em inglês) para implantação no App Engine. O Google fornece um plug-in e os arquétipos do Maven compatíveis com o Maven 3.5 ou mais recente.

O Maven faz o download das bibliotecas Java a partir do SDK do App Engine. O Maven pode ser usado para testar o aplicativo localmente e para implantá-lo no App Engine.

Antes de começar

  1. Use o Console do Google Cloud para criar e configurar seu projeto do Cloud:
    Acesse o App Engine
    1. Selecione ou crie um novo projeto do Cloud.
    2. Se for necessário criar um aplicativo do App Engine para o projeto, siga as instruções para selecionar a região em que o aplicativo do App Engine ficará localizado.
  2. Se você não tem o Java, faça o download, a instalação e a configuração dele.
  3. Defina as sinalizações do compilador Java no pom.xml do projeto para especificar o código Java de 8 bytes:
    Java 8
    <properties>
      <maven.compiler.source>1.8</maven.compiler.source>
      <maven.compiler.target>1.8</maven.compiler.target>
    </properties>
  4. É necessário ter o Maven 3.5 ou mais recente instalado. Para ver se o Maven 3.5 ou mais recente está instalado, execute:
     mvn -v
  5. Se você não tiver o Maven 3.5 ou mais recente instalado:
    1. Faça download (em inglês) do Maven 3.5 ou mais recente no site do Maven.
    2. Instale o Maven 3.5 ou mais recente no seu computador.

      Observação: usuários do Linux podem precisar fazer download do Maven em vez de usar apt-get install para instalar o Maven 3.5 ou posterior.

  6. Você não precisa instalar o SDK do Cloud, o plug-in fará isso automaticamente quando for necessário.

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

Para usar o plug-in Maven do Google App Engine (em inglês) em um projeto atual do Maven, adicione o seguinte na seção plugins no projeto pom.xml do arquivo:

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

Como escolher um arquétipo do App Engine

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 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.
Aplicativo do App Engine appengine-standard-archetype Gera um aplicativo Java básico para o ambiente padrão do App Engine.
Aplicativo do App Engine appengine-flexible-archetype Gera um aplicativo Java básico para o ambiente flexível do App Engine.

Como criar um novo projeto usando o Maven

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.

Como criar um novo aplicativo do App Engine

O procedimento a seguir descreve como usar o appengine-skeleton-archetype para criar um aplicativo do App Engine.

Se você quiser usar os arquétipos Maven do App Engine para criar um aplicativo do App Engine, faça o seguinte:

  1. Altere para o diretório onde você quer criar o projeto.

  2. Invoque o seguinte comando do Maven:

    mvn archetype:generate -Dappengine-version=1.9.59 -Dapplication-id=[YOUR-PROJECT-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.

  3. Para criar um projeto vazio que contenha a estrutura de diretório e os arquivos necessários, prontos para suas próprias classes, forneça o número correspondente a com.google.appengine.archetypes:appengine-skeleton-archetype.

  4. Selecione a versão mais recente na lista exibida de versões de arquétipo disponíveis e aceite o padrão.

  5. Quando solicitado a Define value for property 'groupId', forneça o namespace pretendido para seu aplicativo. 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 a conclusão da geração do projeto. Em seguida, substitua o diretório pelo novo diretório do projeto, por exemplo, myapp/.

  11. Crie o projeto invocando

        mvn clean package
    
  12. Espere o projeto ser criado. 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: 2016-08-04T16:18:24-07:00
        [INFO] Final Memory: 16M/228M
        [INFO] --------------------------------------------------
    
  13. Se você tiver criado um novo aplicativo vazio usando o artefato appengine-skeleton-archetype:

    1. Antes de começar a codificar suas próprias classes para o aplicativo, familiarize-se com o layout básico do projeto e os arquivos necessários: dentro do diretório em que você criou o projeto, terá um subdiretório myapp, que contém o arquivo pom.xml, o subdiretório src/main/java e o subdiretório src/main/webapp/WEB-INF:

      Layout de projeto Maven

      • Adicionar suas próprias classes Java de aplicativo a src/main/java/...
      • Configurar seu aplicativo usando o arquivo src/main/webapp/WEB-INF/appengine-web.xml
      • Configure a implantação do seu aplicativo usando o arquivo src/main/webapp/WEB-INF/web.xml
    2. Crie suas classes Java de aplicativo e adicione-as a src/main/java/.... Para mais informações, consulte Primeiros passos.

    3. Adicione a IU que será fornecida aos usuários do app. Para mais informações, consulte Como adicionar código de aplicativo e IU.

    4. 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.

    5. Edite o arquivo src/main/webapp/WEB-INF/web.xml para mapear URLs para os gerenciadores de aplicativos, especificar autenticação, filtros e assim por diante. Isso é descrito com mais detalhes em Descritor de implantação.

Como gerenciar, testar e implantar um projeto do Maven

Como compilar e criar o projeto

Para desenvolver um aplicativo criado com os arquétipos do Maven do App Engine, faça o seguinte:

  1. Mude para o diretório principal do seu projeto.

  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: 2016-08-04T16:18:24-07:00
     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, execute e teste o aplicativo a qualquer momento no servidor de desenvolvimento invocando o plug-in Maven do App Engine.

Para testar o app do App Engine:

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

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

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

  4. Desligue o aplicativo e o servidor de desenvolvimento pressionando Control-C.

Como especificar uma porta para teste local

Quando você executa o aplicativo no servidor de desenvolvimento local, a porta padrão é 8080. É possível alterar esse padrão modificando a entrada do plug-in de appengine-maven-plugin. Por exemplo, é possível especificar a porta e o endereço no arquivo pom.xml do diretório do aplicativo:

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

Neste exemplo, o <devserver.port> define a porta como 8181 em vez do padrão, e o endereço 0.0.0.0 é especificado, o que significa que o servidor de desenvolvimento detectará solicitações provenientes da rede local.

O prefixo devserver é opcional. É possível substituir por <port>8181</port>.

Como depurar no servidor de desenvolvimento

Para depurar um aplicativo executado localmente, defina jvmFlags na configuração do plug-in de modo a permitir a depuração na JVM subjacente. Por exemplo:

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

Implantar o aplicativo

Para implantar o aplicativo:

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

Substitua PROJECT_ID pelo ID do projeto do Cloud. Se o arquivo pom.xmlespecificar o ID do projeto, não será necessário incluir a propriedade -Dapp.deploy.projectId no comando executado.

A meta appengine:deploy e todas as outras metas no plug-in do Maven do App Engine têm parâmetros associados disponíveis para uso. Para ver uma lista completa de metas e parâmetros, consulte Metas e parâmetros do plug-in Maven do App Engine.

A seguir