Nesta página, descrevemos como instalar e usar os serviços incluídos com a versão Java mais recente compatível com o ambiente padrão do App Engine. O aplicativo pode acessar os serviços incluídos usando o JAR da API do App Engine.
Antes de começar
Consulte a lista de APIs de serviços incluídos legados que podem ser chamadas na versão Java compatível mais recente.
Esta página exige que seu app esteja executando o Java 11 ou uma versão mais recente. Para migrar seu app da primeira geração para os ambientes de execução da segunda, analise as diferenças entre o Java 8 e o Java 11+ e a seção Considerações sobre a migração.
Se você usa serviços agrupados legados e quer fazer upgrade para o Java 21, consulte Fazer upgrade de um aplicativo atual para saber mais sobre suas opções de configuração.
Instalar o JAR da API do App Engine
Para usar serviços agrupados legados no app Java com suporte mais recente, use
um arquivo appengine-web.xml
para configurar o app, em vez de um arquivo app.yaml
.
O exemplo a seguir demonstra como adicionar definições de configuração em
appengine-web.xml
para a versão 21 e as versões mais recentes no EE10 (padrão), a versão
21 no EE8 e a versão 17 e versões anteriores. Para usar a versão com suporte mais recente na
configuração padrão, é preciso atualizar os servlets e
as dependências do aplicativo para incluir o namespace Jakarta
. Para saber mais sobre as opções de configuração,
consulte Fazer upgrade de um aplicativo atual.
Adicione as seguintes configurações ao arquivo appengine-web.xml
, de acordo com a versão do Java:
v21 e mais recentes (EE10)
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<runtime>java21</runtime> <!-- or another supported version -->
<app-engine-apis>true</app-engine-apis>
</appengine-web-app>
v21 (EE8)
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<runtime>java21</runtime>
<system-properties> <!-- run your apps on EE8 -->
<property name="appengine.use.EE8" value="true"/>
</system-properties>
<app-engine-apis>true</app-engine-apis>
</appengine-web-app>
v17 e anteriores
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<runtime>java17</runtime> <!-- or another supported version -->
<app-engine-apis>true</app-engine-apis>
</appengine-web-app>
Para especificar os serviços agrupados legados como dependência, adicione as seguintes
linhas ao arquivo pom.xml
:
<dependency>
<groupId>com.google.appengine</groupId>
<artifactId>appengine-api-1.0-sdk</artifactId>
<version>2.0.4</version> <!-- or later-->
</dependency>
Se o app usa um arquivo web.xml
, é necessário adicionar o elemento <app-engine-apis>
e defini-lo como true
:
<app-engine-apis>true</app-engine-apis>
Para implantar o aplicativo Java 21, execute o comando
mvn appengine:deploy
ou
gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml
em um aplicativo da Web compilado e preparado.
Ponto de entrada padrão usado pelo Java 21
Os apps Java 17 podem se beneficiar da configuração extra do usuário ao iniciar a JVM para apps da Web.
O ponto de entrada padrão usado para inicializar a JVM é gerado pelos pacotes de criação do App Engine.
Basicamente, é equivalente definir esse ponto de entrada no arquivo appengine-web.xml
. Por exemplo:
java --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED -showversion -Xms32M -Xmx204M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags -Dclasspath.runtimebase=/base/java_runtime -Djava.class.path=/base/java_runtime/runtime-main.jar -Djava.library.path=/base/java_runtime: com/google/apphosting/runtime/JavaRuntimeMainWithDefaults --fixed_application_path=/workspace /base/java_runtime
Não recomendamos mudar esse ponto de entrada padrão, porque as configurações de memória são calculadas com base no tipo de instância (F1, F2, F4) e na memória disponível.
Por padrão, usamos --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED
para abrir algumas APIs JDK necessárias.
Recursos do ponto de entrada
O ponto de entrada das versões Java de segunda geração pode ser personalizado com variáveis de ambiente definidas pelo usuário adicionadas ao arquivo de configuração appengine-web.xml
.
A tabela a seguir indica as variáveis de ambiente que podem ser usadas para ativar/desativar/configurar recursos e os valores padrão, se não estiverem definidos:
Variável de ambiente | Descrição | Tipo | Padrão |
---|---|---|---|
CPROF_ENABLE |
Stackdriver Profiler | boolean | false |
GAE_MEMORY_MB |
Memória disponível | tamanho | Definido pelo App Engine ou /proc/meminfo - 400 milhões |
HEAP_SIZE_RATIO |
Memória da pilha | porcentagem | 80 |
HEAP_SIZE_MB |
Pilha disponível | tamanho | ${HEAP_SIZE_RATIO} % de ${GAE_MEMORY_MB} |
JAVA_HEAP_OPTS |
Argumentos de pilha do JVM | Argumentos do JVM | -Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M |
JAVA_GC_OPTS |
Argumentos GC do JVM | Argumentos do JVM | -XX:+UseG1GC mais a configuração |
JAVA_USER_OPTS |
Outros argumentos do JVM | Argumentos do JVM | |
JAVA_OPTS |
Argumentos do JVM | Argumentos do JVM | Consulte abaixo |
Se não estiver definido explicitamente, JAVA_OPTS
assumirá como padrão:
JAVA_OPTS:=-showversion \
$JAVA_HEAP_OPTS \
$JAVA_GC_OPTS \
$JAVA_USER_OPTS
Quando CPROF_ENABLE
for verdadeiro, o ponto de entrada padrão adicionará o PROFILER_AGENT
como:
-agentpath:/opt/cprof/profiler_java_agent.so=--logtostderr
Por exemplo, se o código do aplicativo precisar de mais sinalizações -add-opens
, use a variável de ambiente JAVA_USER_OPTS
definida no arquivo appengine-web.xml
:
<env-variables>
<env-var name="JAVA_USER_OPTS" value="--add-opens java.base/java.util=ALL-UNNAMED" />
</env-variables>
Considerações sobre a migração
Esteja ciente das seguintes considerações se você estiver migrando para um ambiente de execução Java de segunda geração e seu aplicativo usar serviços incluídos legados:
- Para testar os recursos de serviços incluídos legados no seu aplicativo Java de segunda geração, use o servidor de desenvolvimento local.
- Ao contrário do ambiente de execução do Java 8, os ambientes de execução Java de segunda geração
incluem JVM como parte da memória da instância. Se você vir erros relacionados à memória nos registros, considere
aumentar o tamanho da classe da instância no
arquivo
appengine-web.xml
. - Se o aplicativo estiver tentando chamar uma API que não está
ativada para os ambientes de execução Java de segunda geração, ele receberá um
erro
com.google.apphosting.api.ApiProxy$FeatureNotEnabledException
. - Todos os apps são considerados de concorrência segura nos ambientes de execução Java
de segunda geração. É necessário remover o elemento
threadsafe
no arquivoapp.yaml
ouappengine-web.xml
ao fazer upgrade para os ambientes de execução do Java 11+.
Exemplo (Datastore)
Para ver um exemplo de como usar o Firestore no modo Datastore, consulte os pacotes de serviços legados para o Java 11 no GitHub.