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

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

시작하기 전에

지원되는 최신 Java 버전에서 호출할 수 있는 기존 번들 서비스 API 목록을 참조하세요.
이 페이지에서 앱은 Java 11 이상 버전을 실행해야 합니다. 1세대 런타임에서 2세대 런타임으로 앱을 마이그레이션하려면 자바 8과 자바 11+ 간의 차이점과 마이그레이션 고려사항 섹션을 검토하세요.
기존 번들 서비스를 사용하고 자바 21로 업그레이드하려는 경우 구성 옵션에 대한 자세한 내용은 기존 애플리케이션 업그레이드를 참조하세요.

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 코드 샘플을 참조하세요.