Acessar serviços incluídos legados no Java 11+

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

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 arquivo app.yaml ou appengine-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.