JavaFX 애플리케이션 보호

일반 Java 애플리케이션에서도, Spring Boot 데스크톱 애플리케이션에서도 JavaFX를 사용할 수 있습니다. P4JX의 경량 런타임에는 기본적으로 JavaFX가 들어 있지 않으므로, 직접 사용하도록 설정하거나 호환성 검사가 대신 설정하도록 해야 합니다.

1. GUI에서 하는 방법

  1. 일반 JavaFX 애플리케이션은 애플리케이션 유형 페이지에서 Java 애플리케이션을 선택합니다. Spring 컨테이너 위에 만든 JavaFX 데스크톱 애플리케이션은 Spring Boot를 선택합니다. 라이브러리 암호화는 보호된 아카이브만 만들 뿐, JavaFX 애플리케이션 패키징을 대신하지 못합니다.

    Java 애플리케이션 또는 Spring Boot 선택

  2. 입력 JAR, 함께 넣을 Java 버전, 대상 플랫폼을 선택한 뒤 간단 모드와 고급 모드 중에서 고릅니다. JavaFX 구성 요소는 대상 Java 버전과 플랫폼별로 따로 받아오므로, 여러 플랫폼을 지정한 작업은 서로 독립적인 출력 패키지를 만듭니다.

    입력, Java 버전, 대상 플랫폼, 모드 선택

  3. 간단 모드에서는 호환성 검사가 javafx.* 참조나 JavaFX 의존성을 찾으면 JavaFX를 자동으로 사용하도록 설정하고 그 이유를 검사 결과에 표시합니다. javafx.scene.web도 함께 발견되면 WebView까지 포함합니다. 검사는 정적 휴리스틱 분석이므로, 출력 페이지로 넘어간 뒤에도 JavaFX 요약을 다시 확인하세요.

  4. 고급 모드에서는 JavaFX 런타임 탭에서 JavaFX를 패키지 런타임에 포함을 선택한 뒤 WebView 방식을 고릅니다.

    • 자동 (javafx.scene.web 탐지): 애플리케이션이 javafx.scene.web을 참조하는지에 따라 결정합니다.
    • 포함: 항상 WebView(fx-webkit)를 포함합니다.
    • 제외: WebView를 포함하지 않습니다.

    일반 Java 애플리케이션에서의 위치는 다음과 같습니다.

    일반 Java 애플리케이션의 고급 옵션에 있는 JavaFX 런타임 탭

    Spring Boot 데스크톱 애플리케이션도 같은 이름의 탭을 사용합니다.

    Spring Boot 고급 옵션에 있는 JavaFX 런타임 탭

  5. 출력 디렉터리를 고른 뒤 요약에서 JavaFX가 포함으로 표시되고 WebView 상태가 예상과 같은지 확인하고 보호 실행을 클릭합니다. 생성한 뒤에는 패키지 안의 실행 스크립트로 대상 플랫폼마다 창, FXML, CSS와 이미지 리소스, WebView를 확인하세요.

WebView 구성 요소는 약 40 MB입니다. 쓰지 않는다면 제외를 선택해 패키지 크기를 줄일 수 있습니다. 고급 페이지의 다른 설정은 Protector4J 고급 모드 설정을 참고하세요.

2. CLI로 구성 요소 내려받기

p4j javaapp fx-app.jar dist --javafx

Spring Boot와 JavaFX를 함께 쓰는 경우:

p4j springboot fx-boot.jar dist --javafx

WebView를 강제로 포함하거나 제외하는 경우:

--javafx-webview
--no-javafx-webview

도구는 대상 JDK 트레인과 플랫폼에 따라 현재 지역의 공개 다운로드 사이트에서 해당 구성 요소를 받아옵니다. JavaFX 다운로드와 VLX JRE 다운로드 모두 클라우드 스토리지 키를 클라이언트에 넘길 필요가 없습니다.

3. 오프라인 구성 요소

CLI에서는 로컬 디렉터리를 지정할 수 있습니다.

p4j javaapp fx-app.jar dist --javafx /opt/p4jx-fx

이 디렉터리는 다음 중 하나의 형태여야 합니다.

  • fx-core.tar.gz와 선택적인 fx-webkit.tar.gz
  • lib/를 루트로 하여 이미 펼쳐진 JavaFX 파일 트리

GUI에는 로컬 JavaFX 디렉터리를 고르는 기능이 없으므로, 오프라인 환경에서는 CLI를 사용하세요.

4. FXML

애플리케이션이 FXMLLoader를 사용하면 호환성 검사가 스캐너 ZIP 오버레이를 켜도록 권장합니다.

p4j javaapp fx-app.jar dist --javafx --zip-overlay scanner

FXML 리소스, 컨트롤러 시그니처, 프레임워크 스캔은 모두 대상 플랫폼에서 애플리케이션을 실제로 실행해 확인해야 합니다.

5. Java 8과 Java 11 이상

  • Java 8은 jfxrt.jar와 확장 디렉터리 모델을 쓰므로, 생성된 스크립트에 보통 모듈 옵션이 필요 없습니다.
  • Java 11 이상은 모듈화된 JavaFX JAR를 쓰므로, 생성된 스크립트가 전용 모듈 경로와 --add-modules를 설정합니다.

항상 생성된 run.sh, run.command, run.bat으로 실행하세요. vlxjre/lib 전체를 직접 모듈 경로로 지정하지 마세요.

6. 자동 판별 기준

판별기는 자기 코드의 클래스 참조와 의존 JAR의 파일 이름을 살펴봅니다. 모든 서드파티 의존성의 바이트코드까지 깊이 들여다보지는 않습니다. 그렇게 하면 선택적으로만 쓰이는 JavaFX 연동을 실제로 사용 중인 것으로 잘못 판단하기 때문입니다.

이름만으로는 알 수 없는 의존성 안에 JavaFX가 shade되어 있으면 자동 판별이 놓칠 수 있습니다. 그럴 때는 --javafx를 직접 지정하세요.

7. 권장하는 보호 범위

  • JavaFX Application 하위 클래스, FXML 컨트롤러, 프로퍼티 모델을 보호할지는 대상 Java 버전에서 실제로 시험한 결과에 따라 정하세요.
  • JNI나 네이티브 코드가 직접 접근하는 브리지 클래스는 보호하지 않은 상태로 둡니다.
  • 먼저 간단 모드나 --compat-scan을 쓰고, 그다음 창 생성, FXML 로딩, CSS와 이미지 리소스, WebView, 플랫폼 네이티브 라이브러리에 대해 회귀 테스트를 하세요.