Como usar o Apache Maven e o plug-in do App Engine (baseado na Google Cloud CLI)

Nesta página, você verá como gerenciar um projeto do App Engine para a API do Cloud Endpoints Frameworks usando o Apache Maven. O Apache Maven é uma ferramenta de gerenciamento e compreensão de projetos de software capaz de criar arquivos WAR (Web Application Archive) para implantação no App Engine. O Google fornece um plug-in e arquétipos do Maven compatíveis com o Maven 3.3.9 ou versões posteriores.

O Maven faz o download das bibliotecas Java do SDK do App Engine. É possível usar o Maven para testar o aplicativo localmente e implantá-lo no App Engine.

Antes de começar

Use o console do Google Cloud para criar e configurar seu projeto do Google Cloud:

Acessar o App Engine
1. Selecione ou crie um projeto do Google Cloud.
2. Se precisar criar um aplicativo do App Engine para o projeto, siga os prompts para selecionar a região em que o aplicativo do App Engine ficará localizado.
Faça o download e instale a CLI gcloud e, em seguida, inicialize a Google Cloud CLI.
Se você já tem a Google Cloud CLI instalada e quer configurá-la para usar um ID do projeto do Google Cloud diferente do inicial, consulte Como gerenciar configurações da CLI gcloud.
Instale o componente app-engine-java da CLI gcloud:
```
gcloud components install app-engine-java
```
Observação:para garantir que você tenha a versão mais recente da CLI gcloud para Java, execute gcloud components update.
Se você não tem o Java, faça o download, a instalação e a configuração dele.

Defina as sinalizações do compilador Java no pom.xml do projeto para especificar o código Java de 8 bytes:

<properties>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
</properties>

É necessário ter instalado o Apache Maven 3.3.9 ou versão posterior. Para saber a versão do Maven, execute o seguinte comando:
```
 mvn -v
```
Se você não tiver a versão correta do Maven instalada:
1. Faça o download (em inglês) do Maven versão 3.3.9, ou mais recente, no site do Maven.
2. Instale (em inglês) o Maven na sua máquina local.
  Observação: pode ser que usuários do Linux tenham que fazer o download do Maven em vez de usar o apt-get install.

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

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

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

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
Endpoints Frameworks para App Engine	`endpoints-skeleton-archetype`	Gera um projeto novo e vazio projeto de API de back-end do Endpoints Frameworks para App Engine, pronto para suas próprias classes e recursos, com os arquivos e diretórios necessários.
Endpoints Frameworks para App Engine	`hello-endpoints-archetype`	Gera um projeto inicial de API de back-end do Endpoints Frameworks para App Engine, pronto para criação e execução.

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 usada para gerar o projeto. É uma boa ideia adicionar `version` como sufixo de `-SNAPSHOT`, porque isso oferece 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`	O pacote Java criado durante a geração.

Como criar um novo aplicativo do Endpoints Frameworks

Nesta seção, você aprende a criar um novo projeto da versão 2.0 do Endpoints Frameworks.

O hello-endpoints-archetype fornece um exemplo de uso de plug-ins, incluindo o plug-in do Maven para App Engine e o plug-in do Maven para Endpoints Frameworks.

O hello-endpoints-archetype gera um exemplo de API Greetings usando o Endpoints Frameworks versão 2.0. Ele também funciona como um exemplo para migrar os aplicativos da versão 1.0 para a 2.0 do Endpoints Frameworks.

O README.md que é gerado com o arquétipo fornece informações sobre o local em que a migração ocorreu.

Para criar um projeto de arquétipo de API de back-end do Endpoints Frameworks para App Engine:

Altere o diretório para onde o projeto será criado.
Execute o seguinte comando Maven:
```
mvn archetype:generate -Dgoogle-cloud-project=[YOUR-PROJECT-ID] -Dappengine-plugin=2.7.0 -Dendpoints-frameworks=2.1.0 -Dendpoints-plugin=1.0.2 -Dappengine-sdk=1.9.98 -Dfilter=com.google.appengine.archetypes:
```
Em que:
- -Dgoogle-cloud-project é definido como o ID do projeto.
- -Dappengine-plugin é definido para a versão mais recente do plug-in do Maven para App Engine.
- -Dendpoints-frameworks é definido para a versão mais recente do Endpoints Frameworks para App Engine nas dependências do Maven.
- -Dendpoints-plugin é definido para a versão mais recente do Endpoints Frameworks para o plug-in do Maven para App Engine.
Observação :os arquétipos do Endpoints Frameworks para App Engine são compatíveis com o Gradle e usam a versão mais recente de cada dependência.
Forneça o número correspondente a hello-endpoints-archetype.

Observação: para criar um projeto vazio contendo a estrutura de diretório e os arquivos necessários prontos para suas próprias classes, forneça o número correspondente a endpoints-skeleton-archetype.
Selecione a versão mais recente na lista exibida de versões disponíveis de arquétipos.
Quando solicitado a Define value for property 'groupId', forneça o namespace para seu aplicativo. Por exemplo, forneça o valor com.example.helloendpoints.
Quando solicitado a Define value for property 'artifactId', forneça o nome do projeto. Por exemplo, forneça o valor helloendpoints.
Quando solicitado a Define value for property 'version', aceite o valor padrão.
Quando solicitado a Define value for property 'package', aceite o valor padrão.
Quando for solicitada a confirmação das opções escolhidas, aceite o valor padrão digitando Y.
Aguarde a conclusão da geração do projeto. Em seguida, mude os diretórios para o novo diretório do projeto, por exemplo, helloendpoints/.
Crie o projeto.
```
mvn clean package
```

Aguarde a criação do projeto. Quando ela for concluída com sucesso, será exibida uma mensagem parecida com esta:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.062 s
[INFO] Finished at: 2017-02-28T00:28:03-08:00
[INFO] Final Memory: 27M/485M
[INFO] ------------------------------------------------------------------------

Para testar localmente e implantar o projeto no ambiente padrão do App Engine, consulte Como gerenciar, testar e implantar um projeto Maven.
Além disso, é possível gerar bibliotecas de cliente Java para a API Greeting usando o plug-in do Maven do Endpoints Frameworks:
```
mvn endpoints-framework:clientLibs
```

No diagrama a seguir, é possível ver o layout básico do projeto da API Greetings:

Layout de projeto Maven

README.md contém informações sobre o exemplo gerado.
Greetings.java contém uma definição de API para uma API Greetings de exemplo.
Constants.java contém constantes usadas na API Greetings de exemplo.
HelloGreeting.java contém um contêiner de mensagens recebidas e enviadas a partir da API Greetings de exemplo.
index.html contém uma IU simples para chamar a API Greetings de back-end.
base.js contém o JavaScript necessário para a IU fazer solicitações de back-end.
Quando build.gradle é gerado, o exemplo também suporta Gradle, e mais informações sobre essa funcionalidade em README.md.

Como compilar e criar o aplicativo

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

Altere para o diretório principal do seu projeto, como guestbook/.
Execute o Maven:
```
mvn clean package
```
Aguarde a criação do projeto. Quando ela for concluída com sucesso, será exibida uma mensagem parecida com esta:
```
BUILD SUCCESS
 Total time: 10.724s
 Finished at: 2016-08-04T16:18:24-07:00
 Final Memory: 24M/213M
```

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. Basta executar o plug-in do Maven para App Engine.

Para testar o aplicativo do Endpoints Frameworks para App Engine:

Crie o aplicativo, caso ainda não o tenha feito:
```
mvn clean package
```

Execute o exemplo localmente:

mvn appengine:run

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

[INFO] GCLOUD: INFO ### devappserver2.py:764] Skipping SDK update check.
[INFO] GCLOUD: INFO ### api_server.py:268] Starting API server at: http://localhost:34199
[INFO] GCLOUD: INFO ### dispatcher.py:199] Starting module "default" running at: http://localhost:8080
[INFO] GCLOUD: INFO ### admin_server.py:116] Starting admin server at: http://localhost:8000
[INFO] GCLOUD: ### com.google.appengine.tools.development.SystemPropertiesManager setSystemProperties

Use seu navegador para ir a http://localhost:8080/ e acessar seu aplicativo.
Encerre 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.7.0</version>
     <configuration>
       <devserver.host>0.0.0.0</devserver.host>
       <devserver.port>8181</devserver.port>
     </configuration>
  </plugin>
</plugins>

Nesse exemplo, o <devserver.port> define a porta para 8181 em vez do padrão, e o endereço 0.0.0.0 é especificado, o que significa que o servidor de desenvolvimento atende a solicitações vindas 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 appengine:deploy

A meta appengine:deploy e todas as outras metas no plug-in do Maven do App Engine têm parâmetros associados que você pode usar. Para ver uma lista completa de metas e parâmetros, consulte Metas e parâmetros do plug-in Maven do App Engine.

A seguir

Explore o código do plug-in do Maven para App Engine e relate os problemas no GitHub.
Saiba como especificar parâmetros de metas consultando Metas e parâmetros do Maven para App Engine.
Explore o código do plug-in do Maven do Endpoints Frameworks e relate os problemas no GitHub.
Saiba como especificar parâmetros para metas consultando o plug-in do Maven do Cloud Endpoints Frameworks.