Acceder a servicios agrupados antiguos para Java 11 o versiones posteriores

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

Antes de empezar

Instalar el archivo JAR de la API de App Engine

Para usar los servicios empaquetados antiguos en tu aplicación Java más reciente compatible, debes usar un archivo appengine-web.xml para configurar tu aplicación (en lugar de un archivo app.yaml).

En el siguiente ejemplo se muestra cómo añadir ajustes de configuración en tu archivo appengine-web.xml para la versión 21 y posteriores en EE10 (predeterminada), la versión 21 en EE8 y la versión 17 y anteriores. Para usar la versión compatible más reciente 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 las opciones de configuración, consulta Actualizar una aplicación.

Añade los siguientes ajustes en tu archivo appengine-web.xml en función de la versión de Java:

v21 y versiones 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 versiones 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 antiguos como dependencia, añade las siguientes líneas al archivo pom.xml:

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

Si tu aplicación usa un archivo web.xml, debes añadir el elemento <app-engine-apis> y asignarle el valor true:

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

Para desplegar tu aplicación 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 almacenada provisionalmente.

Punto de entrada predeterminado usado por Java 21

Las aplicaciones Java 21 pueden beneficiarse de una configuración de usuario adicional al iniciar la JVM para aplicaciones web.

El punto de entrada predeterminado que se usa para iniciar la JVM lo generan los buildpacks de App Engine. Esencialmente, es lo mismo que 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 memoria se calcula en función del tipo de instancia (F1, F2 o F4) y de 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 APIs de JDK necesarias.

Funciones de punto de entrada

El punto de entrada de las versiones de Java de segunda generación se puede personalizar con variables de entorno definidas por el usuario que se añaden 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, así como los valores predeterminados si no se definen:

Variable de entorno Descripción Tipo Predeterminado
CPROF_ENABLE Stackdriver Profiler booleano false
GAE_MEMORY_MB Memoria disponible size Definido por App Engine o /proc/meminfo-400M
HEAP_SIZE_RATIO Memoria del montículo porcentaje 80
HEAP_SIZE_MB Montículo disponible size ${HEAP_SIZE_RATIO}% de ${GAE_MEMORY_MB}
JAVA_HEAP_OPTS Argumentos de la pila de JVM Argumentos de JVM -Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M
JAVA_GC_OPTS Argumentos de GC de JVM Argumentos de JVM Configuración de -XX:+UseG1GC
JAVA_USER_OPTS Otros argumentos de JVM Argumentos de JVM
JAVA_OPTS Argumentos de JVM Argumentos de JVM Vea abajo

Si no se define de forma explícita, JAVA_OPTS se asigna de forma predeterminada:

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

Si CPROF_ENABLE es true, el punto de entrada predeterminado añade PROFILER_AGENT de la siguiente forma:

-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 lo siguiente si vas a migrar a un tiempo de ejecución de Java de segunda generación y tu aplicación usa servicios empaquetados antiguos:

  • Para probar las funciones de los servicios empaquetados antiguos 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 la JVM como parte de la memoria de la instancia. Si ve errores relacionados con la memoria en los registros, considere la posibilidad de aumentar el tamaño de la clase de instancia en el archivo appengine-web.xml.
  • Si tu aplicación intenta llamar a una API que no está habilitada para los tiempos de ejecución de Java de segunda generación, recibirá un error com.google.apphosting.api.ApiProxy$FeatureNotEnabledException.
  • Se presupone que todas las aplicaciones son seguras para subprocesos en los tiempos de ejecución de Java de segunda generación. Debes eliminar el elemento threadsafe de tu archivo app.yaml o appengine-web.xml cuando migres de Java 8 al tiempo de ejecución de Java más reciente.

Ejemplo (Datastore)

Para ver un ejemplo de cómo usar Firestore en modo Datastore (Datastore), consulta el código de muestra de servicios empaquetados antiguos para Java 11 en GitHub.