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
Consulta la lista de API de servicios agrupados en paquetes heredados que puedes llamar en la última versión de Java compatible.
Esta página requiere que la app ejecute una versión compatible de Java. Para migrar tu app de los entornos de ejecución de primera generación a los de segunda generación, consulta Migra desde Java 8 al entorno de ejecución de Java más reciente y la sección Consideraciones de migración.
Si usas servicios agrupados en paquetes heredados y deseas actualizar a Java 21, consulta Actualiza una aplicación existente para obtener más información sobre tus opciones de configuración.
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.31</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
threadsafeen el archivoapp.yamloappengine-web.xmlcuando migres desde Java 8 al entorno de ejecución de Java más reciente.
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.