Accede a servicios agrupados en paquetes heredados para Java 11+

En esta página, se describe cómo instalar y usar los servicios agrupados en paquetes con la versión de Java compatible más reciente para el entorno estándar de App Engine. Tu aplicación puede acceder a los servicios en paquetes a través del JAR de la API de App Engine.

Antes de comenzar

Instala el JAR de la API de App Engine

Para usar servicios agrupados en paquetes heredados en tu última app de Java compatible, debes usar un archivo appengine-web.xml para configurar tu app (en lugar de un archivo app.yaml).

En el siguiente ejemplo, se muestra cómo agregar ajustes de configuración en appengine-web.xml para la versión 21 y versiones posteriores en EE10 (predeterminado), la versión 21 en EE8 y la versión 17 y anteriores. Para usar la última versión compatible en la configuración predeterminada, debes actualizar los servlets y las dependencias de tu aplicación para incluir el espacio de nombres Jakarta. Para obtener más información sobre tus opciones de configuración, consulta Actualiza una aplicación existente.

Agrega la siguiente configuración a tu archivo appengine-web.xml según la versión de Java:

v21 y posteriores (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 y 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 los servicios agrupados en paquetes heredados como una dependencia, agrega las siguientes líneas a tu archivo pom.xml:

 <dependency>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-api-1.0-sdk</artifactId>
    <version>2.0.4</version> <!-- or later-->
  </dependency>

Si la app usa un archivo web.xml, debes agregar el elemento <app-engine-apis> y configurarlo como true:

  <app-engine-apis>true</app-engine-apis>

Para implementar tu app de Java 21, ejecuta el comando mvn appengine:deploy o el comando gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml en una aplicación web compilada y publicada en etapa de pruebas.

Punto de entrada predeterminado que usa Java 21

Las apps de Java 21 pueden beneficiarse de una configuración adicional de los usuarios cuando se inicia la JVM para apps web.

Los puntos de compilación de App Engine generan el punto de entrada predeterminado que se usa para iniciar la JVM. En esencia, es equivalente a definir este punto de entrada en el archivo appengine-web.xml. Por ejemplo:

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

No recomendamos cambiar este punto de entrada predeterminado, ya que la configuración de la memoria se calcula en función del tipo de instancia (F1, F2, F4) y la memoria disponible.

De forma predeterminada, usamos --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED para abrir algunas API de JDK necesarias.

Funciones de los puntos de entrada

El punto de entrada para las versiones de Java de segunda generación se puede personalizar con variables de entorno definidas por el usuario que se agregan en el archivo de configuración appengine-web.xml.

En la siguiente tabla, se indican las variables de entorno que se pueden usar para habilitar, inhabilitar o configurar funciones y los valores predeterminados si no están configurados:

Variable del entorno Descripción Tipo Predeterminado
CPROF_ENABLE Stackdriver Profiler booleano false
GAE_MEMORY_MB Memoria disponible tamaño Establecido por App Engine o /proc/meminfo-400M
HEAP_SIZE_RATIO Memoria para el montón porcentaje 80
HEAP_SIZE_MB Montón disponible tamaño ${HEAP_SIZE_RATIO}% de ${GAE_MEMORY_MB}
JAVA_HEAP_OPTS Argumentos del montón de JVM argumentos de JVM -Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M
JAVA_GC_OPTS Argumentos de JVM GC argumentos de JVM -XX:+UseG1GC más la configuración
JAVA_USER_OPTS Otros argumentos de JVM argumentos de JVM
JAVA_OPTS argumentos de JVM argumentos de JVM Ver a continuación

Si no se establece de forma explícita, el valor predeterminado de JAVA_OPTS es el siguiente:

   JAVA_OPTS:=-showversion \
              $JAVA_HEAP_OPTS \
              $JAVA_GC_OPTS \
              $JAVA_USER_OPTS

Cuando CPROF_ENABLE es verdadero, el punto de entrada predeterminado agrega PROFILER_AGENT de la siguiente manera:

-agentpath:/opt/cprof/profiler_java_agent.so=--logtostderr

Por ejemplo, si el código de tu aplicación necesita más marcas -add-opens, puedes usar la variable de entorno JAVA_USER_OPTS definida en el archivo appengine-web.xml:

    <env-variables>
       <env-var name="JAVA_USER_OPTS" value="--add-opens java.base/java.util=ALL-UNNAMED" />
     </env-variables>

Consideraciones sobre la migración

Debes tener en cuenta las siguientes consideraciones si migras al entorno de ejecución de Java de segunda generación y tu app usa los servicios agrupados en paquetes heredados:

  • Para probar las capacidades de servicios agrupados en paquetes heredados en tu aplicación Java de segunda generación, puedes usar el servidor de desarrollo local.
  • A diferencia del entorno de ejecución de Java 8, los entornos de ejecución de Java de segunda generación incluyen JVM como parte de la memoria de la instancia. Si ves errores relacionados con la memoria en los registros, considera aumentar el tamaño de la clase de instancia en tu archivo appengine-web.xml.
  • Si tu aplicación intenta llamar a una API que aún no está habilitada para el entorno de ejecución de Java de segunda generación, recibirá un error com.google.apphosting.api.ApiProxy$FeatureNotEnabledException.
  • Se supone que todas las apps cuentan con protección de subprocesos en los entornos de ejecución de Java de segunda generación. Debes quitar el elemento threadsafe en el archivo app.yaml o appengine-web.xml cuando actualices a los entornos de ejecución de versiones posteriores de Java 11.

Ejemplo (Datastore)

Para ver un ejemplo de cómo usar Firestore en modo Datastore (Datastore), consulta la muestra de código de GitHub sobre los servicios agrupados en paquetes heredados para Java 11.