Java 11+용 기존 번들 서비스에 액세스

이 페이지에서는 App Engine 표준 환경에서 지원되는 최신 Java 버전으로 번들 서비스를 설치하고 사용하는 방법을 설명합니다. 앱은 App Engine API JAR을 통해 번들 서비스에 액세스할 수 있습니다.

시작하기 전에

App Engine API JAR 설치

지원되는 최신 Java 앱에서 기존 번들 서비스를 사용하려면 app.yaml 파일 대신 appengine-web.xml 파일을 사용하여 앱을 구성해야 합니다.

다음 예시에서는 EE10 버전 21 이상(기본값), EE8 버전 21 및 버전 17 이하의 appengine-web.xml에 구성 설정을 추가하는 방법을 보여 줍니다. 기본 구성에서 지원되는 최신 버전을 사용하려면 Jakarta 네임스페이스를 포함하도록 애플리케이션 서블릿 및 종속 항목을 업데이트해야 합니다. 구성 옵션에 대한 자세한 내용은 기존 애플리케이션 업그레이드를 참조하세요.

Java 버전에 따라 appengine-web.xml 파일에 다음 설정을 추가합니다.

v21 이상(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 이하

<?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>

기존 번들 서비스를 종속 항목으로 지정하려면 pom.xml 파일에 다음 줄을 추가합니다.

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

앱에서 web.xml 파일을 사용하는 경우 <app-engine-apis> 요소를 추가하고 이를 true로 설정해야 합니다.

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

Java 21 앱을 배포하려면 컴파일되고 스테이징된 웹 애플리케이션에서 mvn appengine:deploy 명령어 또는 gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml 명령어를 실행합니다.

Java 21에 사용되는 기본 진입점

Java 21 앱은 웹 앱용 JVM을 시작할 때 추가 사용자 구성을 이용할 수 있습니다.

JVM 부팅에 사용되는 기본 진입점은 App Engine 빌드 팩으로 생성됩니다. 기본적으로 appengine-web.xml 파일에서 이 진입점을 정의하는 것은 동일합니다. 예를 들면 다음과 같습니다.

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

메모리 설정은 인스턴스 유형(F1, F2, F4) 및 사용 가능한 메모리를 기반으로 계산되므로 이 기본 진입점을 변경하지 않는 것이 좋습니다.

기본적으로 --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED를 사용하여 필요한 JDK API를 엽니다.

진입점 기능

appengine-web.xml 구성 파일에 추가된 사용자 정의된 환경 변수를 사용하여 2세대 Java 버전의 진입점을 맞춤설정할 수 있습니다.

다음 표에서는 기능을 사용 설정/사용 중지/구성하는 데 사용할 수 있는 환경 변수와 기본값이 설정되지 않은 경우의 기본값을 나타냅니다.

환경 변수 설명 유형 기본값
CPROF_ENABLE Stackdriver Profiler 부울 false
GAE_MEMORY_MB 사용 가능한 메모리 크기 App Engine 또는 /proc/meminfo-400M에서 설정
HEAP_SIZE_RATIO 힙용 메모리 퍼센트 80
HEAP_SIZE_MB 사용 가능한 힙 크기 ${GAE_MEMORY_MB}${HEAP_SIZE_RATIO}%
JAVA_HEAP_OPTS JVM 힙 인수 JVM 인수 -Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M
JAVA_GC_OPTS JVM GC 인수 JVM 인수 -XX:+UseG1GC 및 구성
JAVA_USER_OPTS JVM 기타 인수 JVM 인수
JAVA_OPTS JVM 인수 JVM 인수 아래 참조

JAVA_OPTS를 명시적으로 설정하지 않으면 다음 기본값이 적용됩니다.

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

CPROF_ENABLE이 true이면 기본 진입점이 PROFILER_AGENT를 다음과 같이 추가합니다.

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

예를 들어 애플리케이션 코드에 -add-opens 플래그가 더 필요하면 appengine-web.xml 파일에 정의된 JAVA_USER_OPTS 환경 변수를 사용할 수 있습니다.

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

마이그레이션 고려사항

2세대 Java 런타임으로 마이그레이션할 때 그리고 앱에 기존 번들 서비스가 사용되는 경우에는 다음 고려사항에 주의해야 합니다.s:

  • 2세대 Java 앱에서 기존 번들 서비스 기능을 테스트하려면 로컬 개발 서버를 사용하면 됩니다.
  • Java 8 런타임과 달리 2세대 Java 런타임에는 JVM이 인스턴스 메모리의 일부로 포함됩니다. 로그에 메모리 관련 오류가 표시되면 appengine-web.xml 파일에서 인스턴스 클래스 크기를 늘리는 것이 좋습니다.
  • 2세대 Java 런타임에서 사용 설정되지 않은 API를 애플리케이션에서 호출하려고 하면 com.google.apphosting.api.ApiProxy$FeatureNotEnabledException 오류가 발생합니다.
  • 모든 앱은 2세대 Java 런타임에서 스레드 안전으로 간주됩니다. Java 11 이상 런타임으로 업그레이드할 때 app.yaml 또는 appengine-web.xml 파일에서 threadsafe 요소를 삭제해야 합니다.

예시(Datastore)

Datastore 모드(Datastore)에서 Firestore를 사용하는 방법의 예시는 Java 11용 기존 번들 서비스에 대한 GitHub 코드 샘플을 참조하세요.