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 parámetros de configuración en tu archivo appengine-web.xml para diferentes versiones de Java. 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:

Java 25 (versión preliminar, EE 11) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java25</runtime>
      <system-properties>
        <property name="appengine.use.EE11" value="true"/>
      </system-properties>
      <app-engine-apis>true</app-engine-apis>
  </appengine-web-app>

Java 21 (EE 10) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java21</runtime>
      <system-properties>
        <property name="appengine.use.EE10" value="true"/>
      </system-properties>
      <app-engine-apis>true</app-engine-apis>
  </appengine-web-app>

Java 17 (EE 8) 

  <?xml version="1.0" encoding="utf-8"?>
  <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
      <runtime>java17</runtime>
      <system-properties>
        <property name="appengine.use.EE8" value="true"/>
      </system-properties>
      <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 25 (vista previa), 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 para Java 25 (vista previa)

Las aplicaciones de Java 25 (vista previa) se benefician de una configuración adicional del usuario cuando se inicia la JVM para aplicaciones 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 aplicaciones son seguras para usar en 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 migres de 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.