선택 심화: 프리뷰 기능 사용법과 소스 분리
JDK 25의 프리뷰 기능이 무엇인지, 컴파일과 실행에 --enable-preview를 어떻게 붙이는지, 프리뷰 코드를 왜 정식 코드와 따로 빌드하는지 배웁니다.
이 장은 선택 심화 과정입니다. 36장까지의 기본 과정을 마친 뒤 관심이 생겼을 때 읽으면 되고, 38장을 포함한 다른 장은 이 장의 내용을 안다고 가정하지 않습니다.
JDK 25의 API 문서를 보면 java.lang 패키지에 StableValue라는 클래스가 있습니다. 그런데 이 클래스를 쓰는 코드를 평소처럼 javac로 컴파일하면 오류가 납니다. JDK 안에 분명히 들어 있는데도 그냥은 쓸 수 없는 이유는 이것이 프리뷰(preview) 기능이기 때문입니다.
이 글을 읽고 나면 다음을 할 수 있습니다.
- 프리뷰 기능을 쓰는 소스를
--enable-preview로 컴파일하고 실행합니다. - 실행할 때 옵션을 빠뜨려서 난 오류를 보고 원인을 찾습니다.
- 정식 소스와 프리뷰 소스에 줄
javac인수 목록을 만드는PreviewPathPolicy를 만듭니다.
1장부터 써 온 java-board 폴더와 JDK 25로 작업합니다. 이 장의 파일 위치와 명령은 이렇습니다. 정식 기능만 쓰는 예제는 src/에, 일부러 실패를 재현하는 예제는 lab/에 저장하고 out으로 컴파일합니다. 프리뷰 기능을 쓰는 예제는 preview/에 저장하고, 결과도 out-preview라는 다른 폴더에 만듭니다. 터미널은 java-board에서 열고 다음 두 가지 명령 모양을 씁니다.
# 정식 소스
javac --release 25 -d out src/PreviewPathPolicy.java
java -cp out PreviewPathPolicy
# 프리뷰 소스
javac --enable-preview --release 25 -Xlint:preview -d out-preview preview/StableValuePreviewProbe.java
java --enable-preview -cp out-preview StableValuePreviewProbe두 폴더를 왜 나누는지가 이 글의 마지막 절입니다. 이 장은 글마다 작은 조각을 하나씩 만들고, 마지막 글 프리뷰 실험을 이어 갈지 끝낼지 정하기에서 그 조각을 모아 '정식 결과물에 프리뷰 클래스가 섞였는지 검사하는 프로그램'을 완성합니다. 이 글의 PreviewPathPolicy가 그 첫 조각입니다.
옵션 없이 컴파일하면 생기는 일
먼저 아무 준비 없이 StableValue를 써 보겠습니다. 다음 프로그램은 비어 있는 StableValue를 만들고 orElseSet으로 값을 채운 뒤 출력합니다. 두 메서드가 하는 일은 뒤에서 봅니다.
public final class PreviewFeatureWithoutFlagFailure {
public static void main(String[] args) {
StableValue<String> value = StableValue.of();
System.out.println(value.orElseSet(() -> "preview"));
}
}javac --release 25 -d out lab/PreviewFeatureWithoutFlagFailure.java컴파일이 실패합니다. 실제 출력에는 파일 이름과 줄 번호, 문제 위치를 가리키는 표시가 함께 나오고, 메시지의 핵심은 다음 두 줄입니다.
error: StableValue is a preview API and is disabled by default.
(use --enable-preview to enable preview APIs)StableValue는 프리뷰 API이고 기본으로 꺼져 있으니 --enable-preview로 켜라는 뜻입니다. 클래스가 JDK에 들어 있다는 사실만으로 정식 API라고 판단하면 안 된다는 것을 여기서 알 수 있습니다. API 문서도 프리뷰 API에는 PREVIEW 표시와 함께 'StableValue is a preview API of the Java platform' 같은 안내를 붙여 두니, 처음 보는 클래스라면 이 표시부터 확인합니다.
프리뷰 기능이란
프리뷰 기능은 설계와 구현은 끝났지만 아직 Java SE의 영구 기능으로 확정되지 않은 언어 기능이나 API입니다. JDK 개발진은 새 기능을 한 릴리스 이상 프리뷰로 내보내 실제로 써 본 개발자들의 의견을 받고, 그 의견에 따라 다음 릴리스에서 API를 바꾸거나, 그대로 확정하거나, 아예 뺍니다. 이 절차는 JEP 12(Preview Features)에 정해져 있습니다.
바뀔 수 있는 기능이 모르는 사이에 코드에 섞이면 곤란하므로 프리뷰 기능은 기본으로 꺼져 있습니다. 개발자가 --enable-preview로 '바뀔 수 있다는 것을 알고 쓴다'고 밝혀야만 컴파일러와 JVM이 허용합니다. JDK 25에서 이 장과 관련된 기능의 상태는 다음과 같습니다.
| 기능 | 대표 API·문법 | JDK 25에서의 상태 |
|---|---|---|
| Stable Values (JEP 502) | StableValue | 프리뷰(첫 번째) |
| 구조화된 동시성 (JEP 505) | StructuredTaskScope | 프리뷰(다섯 번째) |
| 기본형 패턴 (JEP 507) | instanceof byte b, long 값의 switch | 프리뷰(세 번째) |
| PEM 인코딩 (JEP 470) | 암호 키·인증서를 PEM 텍스트와 서로 변환하는 API | 프리뷰(첫 번째) |
| Scoped Values (JEP 506) | ScopedValue | 정식 |
| 모듈 import 선언 (JEP 511) | import module java.base; | 정식 |
| 간결한 소스 파일과 인스턴스 main 메서드 (JEP 512) | void main() | 정식 |
| 유연한 생성자 본문 (JEP 513) | super(...) 앞에 문장 쓰기 | 정식 |
위쪽 네 기능은 JDK 25에서도 프리뷰이고, 아래쪽 네 기능은 앞선 릴리스들에서 프리뷰를 거쳐 JDK 25에서 정식이 되었습니다. 예를 들어 ScopedValue는 JDK 21부터 24까지 프리뷰였고, 지금은 가상 스레드와 ScopedValue에서처럼 옵션 없이 씁니다. 같은 JDK 25의 Vector API(JEP 508)는 프리뷰가 아니라 인큐베이터(incubator) 모듈이라서 --enable-preview가 아니라 --add-modules jdk.incubator.vector로 켭니다.
컴파일할 때와 실행할 때 모두 켜기
이번에는 프리뷰를 켜고 끝까지 실행해 보겠습니다. StableValue는 값을 딱 한 번만 설정할 수 있는 칸입니다. StableValue.of()는 빈 칸을 만들고, orElseSet(공급자)는 칸이 비어 있으면 공급자를 호출해 그 결과로 칸을 채운 뒤 돌려줍니다. 칸이 이미 차 있으면 공급자를 부르지 않고 저장된 값을 돌려주므로, 처음 쓸 때 한 번만 계산하는 지연 초기화(lazy initialization)에 쓸 수 있습니다.
아래 프로그램은 orElseSet을 두 번 부르면서 공급자가 실제로 몇 번 호출되는지 AtomicInteger로 셉니다.
import java.util.concurrent.atomic.AtomicInteger;
public final class StableValuePreviewProbe {
public static void main(String[] args) {
StableValue<String> value = StableValue.of();
AtomicInteger calls = new AtomicInteger();
String first = value.orElseSet(() -> "value-" + calls.incrementAndGet());
String second = value.orElseSet(() -> "value-" + calls.incrementAndGet());
System.out.println("first=" + first);
System.out.println("second=" + second);
System.out.println("initializer-calls=" + calls.get());
}
}준비물 문단의 프리뷰 소스 명령 두 줄로 컴파일하고 실행합니다. 두 명령 모두에 --enable-preview가 들어 있습니다.
first=value-1
second=value-1
initializer-calls=1첫 번째 orElseSet에서는 칸이 비어 있으므로 공급자가 호출되고, 카운터가 1이 되면서 value-1이 저장됩니다. 두 번째 호출에서는 칸이 이미 차 있으므로 공급자를 부르지 않고 value-1을 돌려줍니다. 그래서 둘째 줄도 value-1이고 호출 횟수는 1에 머뭅니다. API 문서에 따르면 공급자가 예외를 던지면 칸은 빈 채로 남아 다음 호출이 다시 시도할 수 있고, 여러 스레드가 동시에 불러도 공급자가 정상적으로 끝나는 한 한 번만 호출됩니다.
컴파일할 때 이미 켰으니 실행할 때는 --enable-preview를 빼도 되지 않을까요? java -cp out-preview StableValuePreviewProbe로 실행하면 어떻게 될지 먼저 예상해 보세요.
결과 확인하기
클래스를 불러오는 단계에서 실행이 거부됩니다. main의 첫 줄도 실행되지 않습니다.
Error: LinkageError occurred while loading main class StableValuePreviewProbe
java.lang.UnsupportedClassVersionError: Preview features are not enabled for StableValuePreviewProbe (class file version 69.65535). Try running with '--enable-preview'javac와 java는 서로 다른 프로그램이고, 컴파일할 때 고른 옵션이 실행할 때로 자동으로 넘어가지 않습니다. 대신 javac는 프리뷰 기능을 쓴 클래스 파일에 'JDK 25의 프리뷰 기능에 의존한다'는 표식을 남기고, JVM은 클래스를 불러올 때 이 표식을 검사합니다. 괄호 안의 69.65535가 그 표식입니다. 69는 Java 25 클래스 파일의 메이저 버전(major version)이고, 마이너 버전(minor version) 65535는 프리뷰 기능에 의존한다는 뜻입니다. 이 값을 직접 읽어 보는 일은 프리뷰 클래스 파일과 실행 규칙에서 합니다.
명령에 들어간 옵션 하나씩 보기
javac의 --enable-preview는 반드시 --release(또는 --source)와 함께, 지금 사용하는 JDK의 버전 번호로 지정해야 합니다. 프리뷰 기능은 그 릴리스에만 들어 있는 시험판이라서, JDK 25의 컴파일러는 JDK 25의 프리뷰 규칙만 알기 때문입니다. 버전을 빼면 --enable-preview must be used with either -source or --release, 다른 번호를 주면 preview language features are only supported for release 25라는 오류가 나고 컴파일이 시작되지 않습니다. 둘 중에서는 소스 문법, 클래스 파일 버전, 쓸 수 있는 플랫폼 API를 한꺼번에 맞춰 주는 --release를 권합니다.
-Xlint:preview는 프리뷰 기능을 쓴 위치마다 경고를 출력하게 합니다. 이 옵션이 없으면 javac는 컴파일에 성공하면서 다음과 같은 파일 단위의 안내 두 줄만 남깁니다. 파일 이름 자리는 명령에 적은 소스 경로에 따라 조금 다르게 보일 수 있습니다.
Note: StableValuePreviewProbe.java uses preview features of Java SE 25.
Note: Recompile with -Xlint:preview for details.옵션을 붙이면 warning: [preview] StableValue is a preview API and may be removed in a future release.처럼 사용 위치마다 경고가 나옵니다. 경고가 있어도 컴파일은 성공합니다. 이 경고를 끄지 않고 빌드 로그에 남겨 두면 프리뷰를 쓰는 곳이 늘어날 때 바로 눈에 띕니다.
짧게 실험할 때는 java --enable-preview preview/StableValuePreviewProbe.java처럼 .java 파일을 바로 주는 소스 파일 모드도 씁니다. JDK 25의 java 명령 문서에 따르면 이 모드에서는 --source를 생략해도 실행 중인 JDK 버전에 맞춰 적용됩니다. 오래된 자료에 --source 21이 함께 적혀 있는 것은 JDK 21에서는 이것을 생략할 수 없었기 때문입니다.
프리뷰 언어 기능도 같은 옵션으로 켭니다. 예를 들어 long 값을 switch로 고르고 case long number처럼 기본형 타입 패턴을 쓰는 코드는 옵션 없이는 컴파일되지 않습니다. 이 기능은 기본형 패턴과 switch에서 자세히 다룹니다.
여기까지가 프리뷰 기능을 켜는 방법입니다. 컴파일에도 실행에도 --enable-preview를 붙이고, javac에는 --release 25를 함께 줍니다. 쉬어 가기 좋은 지점입니다.
프리뷰 코드를 정식 코드와 나눠 빌드하기
앞의 오류가 보여 주듯이, 프리뷰 클래스를 불러오는 애플리케이션은 실행할 때 --enable-preview가 필요하고, 그 클래스는 컴파일한 릴리스인 JDK 25에서만 불러올 수 있습니다. 실험용으로 넣은 클래스 하나 때문에 애플리케이션 전체가 특정 JDK와 프리뷰 옵션에 묶이는 셈입니다. 이것을 피하는 가장 확실한 방법이 준비물 문단에서 정한 구조입니다. 프리뷰 코드는 소스 폴더부터 preview/로 따로 두고, 결과물도 out-preview에 만듭니다.
의존 방향도 한쪽으로만 둡니다. 프리뷰 실험이 정식 코드를 쓰는 것은 괜찮지만, 정식 코드가 프리뷰 코드를 쓰기 시작하면 다시 섞입니다. Gradle이나 Maven이라면 별도의 소스 세트나 모듈로 같은 구조를 만듭니다.
두 쪽에 줄 javac 인수를 손으로 매번 적다 보면 실수가 생깁니다. 다음 PreviewPathPolicy는 소스 파일, 출력 폴더, 프리뷰 여부를 받아 인수 목록을 만듭니다. 컴파일러를 실행하지는 않으므로 이 파일 자체는 정식 소스 명령으로 컴파일하고 실행합니다.
import java.util.ArrayList;
import java.util.List;
public final class PreviewPathPolicy {
static List<String> javacArguments(String source, String output, boolean preview) {
List<String> arguments = new ArrayList<>();
if (preview) {
arguments.add("--enable-preview");
}
arguments.add("--release");
arguments.add("25");
if (preview) {
arguments.add("-Xlint:preview");
}
arguments.add("-d");
arguments.add(output);
arguments.add(source);
return List.copyOf(arguments);
}
public static void main(String[] args) {
System.out.println(javacArguments("src/App.java", "out", false));
System.out.println(
javacArguments("preview/StableValuePreviewProbe.java", "out-preview", true));
}
}List의 toString()은 원소를 쉼표로 이어 대괄호로 감싸므로, 각 줄은 javac 뒤에 붙일 인수를 순서대로 보여 줍니다.
[--release, 25, -d, out, src/App.java]
[--enable-preview, --release, 25, -Xlint:preview, -d, out-preview, preview/StableValuePreviewProbe.java]첫 줄은 정식 소스용입니다. 프리뷰 옵션 없이 --release 25만 주고 결과는 out에 씁니다. 둘째 줄은 프리뷰 소스용으로 --enable-preview와 -Xlint:preview가 더해지고 출력 폴더도 out-preview로 바뀝니다. 정식 소스는 프리뷰를 켜지 않고 컴파일하므로, 누가 실수로 정식 소스에서 프리뷰 기능을 쓰면 첫 절처럼 컴파일 단계에서 막힙니다. 그래서 이 컴파일로 새로 만든 클래스 파일에는 마이너 버전 65535가 붙지 않습니다. 예전에 남은 파일이나 다른 출력에서 복사한 파일까지 검사하는 방법은 안정 빌드와 프리뷰 빌드를 CI에서 나누기에서 다룹니다.
목록의 맨 앞에 javac를 넣지 않은 데는 이유가 있습니다. 마지막 글에서는 프로그램 안에서 컴파일러를 부를 때 이 목록을 그대로 넘깁니다. 그러니 src/PreviewPathPolicy.java는 지우지 말고 남겨 두세요.
더 깊이: 프리뷰 클래스 파일은 컴파일한 릴리스에서만 실행된다
JVM 명세(JVMS 4.1)에 따르면 Java SE N을 구현한 JVM은 프리뷰 표식이 있는 클래스 파일을 메이저 버전이 N과 같고 프리뷰가 켜져 있을 때만 불러옵니다. 그래서 JDK 25에서 프리뷰 기능으로 만든 JAR는 JDK 26에서 --enable-preview를 붙여도 실행되지 않고, 새 JDK로 다시 컴파일해야 합니다. 다시 컴파일하는 것만으로 끝나지 않을 수도 있습니다. StableValue는 JDK 26의 두 번째 프리뷰(JEP 526)에서 LazyConstant로 이름이 바뀌고 orElseSet 같은 메서드도 빠졌습니다.
JDK 25가 LTS(장기 지원) 릴리스라는 점도 이 사정을 바꾸지 않습니다. LTS는 공급자가 보안 패치와 버그 수정을 오래 제공하겠다는 지원 정책이지, 그 안의 프리뷰 기능을 확정한다는 뜻이 아닙니다. 또 --enable-preview로 컴파일했다고 모든 클래스에 표식이 붙지는 않습니다. javac는 프리뷰 기능을 실제로 쓴 소스 파일에서 나온 클래스에만 표식을 붙이며, 이 점은 프리뷰 클래스 파일과 실행 규칙에서 확인합니다.
정리
- 프리뷰 기능은 완성됐지만 아직 확정되지 않은 기능입니다. 다음 릴리스에서 바뀌거나 빠질 수 있어서 기본으로 꺼져 있습니다.
- 컴파일할 때는
javac --enable-preview --release 25, 실행할 때는java --enable-preview가 필요합니다. 두 프로그램은 서로의 옵션을 알지 못합니다. - 프리뷰 기능을 쓴 클래스 파일에는 마이너 버전 65535가 기록되고, 같은 릴리스의 JVM에서 프리뷰를 켰을 때만 실행됩니다.
- 프리뷰 소스는
preview/, 결과물은out-preview로 정식 코드와 나눠, 정식 결과물에 섞이지 않게 합니다.
연습 문제
1. 어느 명령이 실패할까
preview/StableValuePreviewProbe.java에 대해 다음 명령을 차례로 따로따로 실행한다고 합시다. 각 명령이 성공하는지, 실패한다면 컴파일과 실행 중 어디서 실패하는지 예상해 보세요.
javac --enable-preview -d out-preview preview/StableValuePreviewProbe.java
javac --enable-preview --release 24 -d out-preview preview/StableValuePreviewProbe.java
javac --enable-preview --release 25 -d out-preview preview/StableValuePreviewProbe.java
java -cp out-preview StableValuePreviewProbe해설 보기
첫 명령은 --release가 없어서 --enable-preview must be used with either -source or --release 오류로 컴파일이 시작되지 않습니다. 둘째 명령은 버전 번호가 지금 JDK와 달라서 preview language features are only supported for release 25 오류가 납니다. 셋째 명령은 성공하고, -Xlint:preview가 없으니 Note 두 줄만 나옵니다. 넷째 명령은 컴파일된 클래스 파일이 있어도 실행할 때 --enable-preview가 없어서 UnsupportedClassVersionError로 거부됩니다. 컴파일 쪽 두 오류는 '프리뷰는 지금 JDK 릴리스의 것만 켤 수 있다'는 같은 규칙에서 나옵니다.
2. 옵션을 넣었는데도 실행이 거부되는 명령 고치기
다음 명령에는 --enable-preview가 분명히 들어 있는데도 UnsupportedClassVersionError가 납니다. 무엇이 문제인지 찾아 고치세요.
java -cp out-preview StableValuePreviewProbe --enable-preview힌트
java 명령에서 클래스 이름 뒤에 오는 값은 누구에게 전달되는지 생각해 보세요.
해설 보기
java 명령은 클래스 이름 앞까지만 JVM 옵션으로 읽고, 클래스 이름 뒤의 값은 프로그램의 main에 args로 넘깁니다. 그래서 위 명령에서 --enable-preview는 JVM이 아니라 args[0]이 되고, JVM은 프리뷰가 꺼진 채로 클래스를 불러오다가 거부합니다. 옵션을 클래스 이름 앞으로 옮기면 됩니다.
java --enable-preview -cp out-preview StableValuePreviewProbe이렇게 실행해 first=value-1, second=value-1, initializer-calls=1 세 줄이 나오면 성공입니다.
3. 컴파일 명령과 실행 명령 목록 만들기
프리뷰 여부에 따라 명령 전체를 목록으로 만드는 두 메서드 compile(String file, boolean preview)와 run(String className, boolean preview)를 가진 PreviewCommandPolicySolution을 작성하세요.
- 정식 소스는
javac --release 25 파일, 프리뷰 소스는javac --enable-preview --release 25 -Xlint:preview 파일입니다. - 프리뷰 클래스는
java --enable-preview 클래스, 정식 클래스는java 클래스로 실행합니다. main에서 프리뷰 소스StableLab.java(클래스StableLab)와 정식 소스Application.java(클래스Application)의 네 목록을 출력합니다.
코드를 쓰기 전에 네 목록이 어떻게 나와야 하는지 먼저 적어 보세요.
해설 보기
import java.util.List;
public final class PreviewCommandPolicySolution {
static List<String> compile(String file, boolean preview) {
if (preview) {
return List.of("javac", "--enable-preview", "--release", "25", "-Xlint:preview", file);
}
return List.of("javac", "--release", "25", file);
}
static List<String> run(String className, boolean preview) {
if (preview) {
return List.of("java", "--enable-preview", className);
}
return List.of("java", className);
}
public static void main(String[] args) {
System.out.println(compile("StableLab.java", true));
System.out.println(run("StableLab", true));
System.out.println(compile("Application.java", false));
System.out.println(run("Application", false));
}
}[javac, --enable-preview, --release, 25, -Xlint:preview, StableLab.java]
[java, --enable-preview, StableLab]
[javac, --release, 25, Application.java]
[java, Application]안정 코드와 프리뷰 코드의 명령 차이
Java 25 · 컴파일과 실행의 프리뷰 허용
안정 코드와 프리뷰 코드의 명령 차이
컴파일과 실행에 필요한 옵션이 다릅니다. 본문의 프로그램은 명령 인수 목록만 만들며, 컴파일러나 Java 프로세스를 실행하지 않습니다.
| 만들 명령 | 필요한 옵션 | 풀이가 하지 않는 일 |
|---|---|---|
| 안정 소스 컴파일 | --release 25 | 프로세스를 실행하거나 컴파일 결과를 확인하지 않음 |
| 프리뷰 소스 컴파일 | --enable-preview --release 25 -Xlint:preview | 실행 JDK의 버전이나 산출물 격리를 검사하지 않음 |
| 프리뷰 클래스 실행 | --enable-preview | 메인 클래스 존재·의존성·JDK 25 일치를 검사하지 않음 |
- 안정 소스 컴파일
- 필요한 옵션
--release 25- 풀이가 하지 않는 일
- 프로세스를 실행하거나 컴파일 결과를 확인하지 않음
- 프리뷰 소스 컴파일
- 필요한 옵션
--enable-preview--release 25-Xlint:preview- 풀이가 하지 않는 일
- 실행 JDK의 버전이나 산출물 격리를 검사하지 않음
- 프리뷰 클래스 실행
- 필요한 옵션
--enable-preview- 풀이가 하지 않는 일
- 메인 클래스 존재·의존성·JDK 25 일치를 검사하지 않음
PreviewCommandPolicySolution은 인수 목록을 만드는 예제입니다. Java 25 프리뷰 클래스는 Java 25 런타임과 프리뷰 허용이 필요하며, 실제 컴파일·실행 성공을 이 목록만으로 판정할 수는 없습니다.
프리뷰 소스의 컴파일 목록에는 세 옵션이, 실행 목록에는 --enable-preview 하나가 들어갑니다. --release는 컴파일 대상을 정하는 javac 옵션이므로 실행 목록에 옮겨 적지 않습니다. 이 메서드들은 목록만 만들 뿐이므로, 목록이 맞다고 해서 실제 컴파일과 실행이 성공했다는 뜻은 아닙니다. 본문의 폴더 구조와 합치려면 컴파일 목록에는 -d out-preview를, 실행 목록에는 클래스 이름 앞에 -cp out-preview를 더합니다. javac -d out src/PreviewCommandPolicySolution.java와 java -cp out PreviewCommandPolicySolution으로 실행해 위 네 줄과 같으면 성공입니다.
다음 글
구조화된 동시성과 StructuredTaskScope에서는 JDK 25의 프리뷰 API인 StructuredTaskScope로 여러 하위 작업을 한 코드 블록 안에서 시작하고 함께 기다리는 방법을 봅니다. 예제는 이 글에서 정한 preview/와 out-preview로 컴파일하고 실행합니다.