일반 Java 애플리케이션 보호

javaapp는 메인 클래스가 있는 일반 Java 애플리케이션을 다룹니다. 보호된 아카이브, 대상 플랫폼별 VLX JRE, 실행 스크립트를 생성합니다.

1. GUI에서 하는 방법

  1. 애플리케이션 유형 페이지에서 Java 애플리케이션을 선택합니다.

    Java 애플리케이션 선택

  2. 입력 JAR, 함께 넣을 Java 버전, 대상 플랫폼을 선택한 뒤 간단 모드와 고급 모드 중에서 고릅니다.

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

  3. 고급 모드에서는 필요에 따라 메인 클래스를 입력하고 JVM 시작 옵션, JavaFX 설정, 제외 규칙을 지정합니다. 간단 모드에서는 이 페이지를 건너뜁니다. 각 옵션의 의미는 Protector4J 고급 모드 설정을 참고하세요.

    일반 Java 애플리케이션의 고급 옵션 설정

  4. 출력 디렉터리를 선택하고 요약을 확인한 뒤 보호 실행을 클릭합니다.

    출력 디렉터리를 선택하고 보호 실행

2. CLI 예제

매니페스트에 올바른 Main-Class가 이미 선언되어 있는 경우:

p4j javaapp app.jar dist

매니페스트에 Main-Class가 없거나 다른 클래스로 시작하려면 --main으로 지정합니다.

p4j javaapp app.jar dist --main com.example.Main

메인 클래스와 JVM 옵션을 함께 지정하는 경우:

p4j javaapp app.jar dist \
  --main com.example.Main \
  --jvm-option -Xms512m \
  --jvm-option -Xmx2g

애플리케이션의 일부만 보호하는 경우:

p4j javaapp app.jar dist \
  --protect 'com.example.core.**' \
  --exclude 'com.example.core.dto.**'

호환성 검사와 권장 설정 자동 적용:

p4j javaapp app.jar --compat-scan
p4j javaapp app.jar dist --compat-apply

두 옵션은 함께 쓸 수 없습니다. 차이는 다음과 같습니다.

옵션동작사용 시점
--compat-scan입력 JAR를 검사해 위험 요소와 설정 권장을 출력하고 종료합니다. 인코딩하지 않고 dist도 만들지 않으므로 출력 디렉터리가 필요 없습니다.처음 보호할 때, 의존성을 올리거나 보호 범위를 바꾼 뒤, 호환성 문제를 조사할 때 먼저 보고서를 확인합니다.
--compat-apply검사한 뒤 보수적인 권장 설정을 반영하고 그대로 인코딩해 결과물을 만듭니다. 따라서 출력 디렉터리가 필요합니다.검사 결과를 확인하고 권장 설정을 받아들인 뒤 패키징을 마무리할 때 사용합니다. 규칙이 검증된 반복 빌드나 CI에도 적합합니다.

javaapp에서 --compat-apply는 검사 결과에 따라 제외 규칙을 추가하고 스캐너 ZIP 오버레이, JavaFX, 아카이브 확장자를 조정할 수 있습니다. 이 세 가지는 명령줄에서 직접 지정한 값이 우선합니다. 권장되는 제외 규칙은 기본적으로 직접 지정한 --exclude와 합쳐집니다. 자동 추가를 원하지 않으면 --no-compat-excludes를 함께 전달하세요. 스캐너는 정적 휴리스틱 분석만 수행하므로 소스 수정이 필요한 문제는 --compat-apply로 해결되지 않으며, 패키징한 뒤에도 대상 플랫폼에서 회귀 테스트가 필요합니다.

그 밖의 CLI 명령, 전체 옵션, 환경 변수, 자동화 예제는 CLI 레퍼런스를 참고하세요.

3. 출력 구조

dist/
├── app.p4jx              # --archive-suffix jar 를 쓰면 app.jar
├── vlxjre/               # 아카이브 및 대상 플랫폼과 맞는 런타임
├── lib/                  # 매니페스트 Class-Path 의존성 (선택)
├── run.sh
├── run.command
├── run.bat
└── README.md

클래스가 아닌 리소스는 P4JX 아카이브의 공개 리소스 뷰에 저장됩니다. 보호 대상 클래스가 스캐너에 보여 주는 것은 메타데이터 스텁뿐이며, 실제 메서드 본문은 VLX 런타임만 읽을 수 있습니다.

4. 실행

./run.sh [애플리케이션 인수...]

Windows:

run.bat [애플리케이션 인수...]

출력 디렉터리의 vlxjre를 시스템 JRE로 바꾸지 마세요. 꼭 직접 실행해야 한다면 생성된 스크립트를 본보기로 삼아 클래스패스, VM 옵션, JavaFX 모듈 옵션을 그대로 유지하세요.

Windows용으로 패키징할 때는 두 번 클릭해 실행할 수 있는 네이티브 실행기를 함께 만들 수 있습니다. 실행 스크립트와 함께 존재합니다. 자세한 내용은 Windows EXE 실행기 생성을 참고하세요.

JVM 시작 옵션

패키징할 때 GUI의 JVM 시작 옵션에 한 줄에 하나씩 입력하거나, 명령줄에서 옵션을 반복해 지정합니다.

--jvm-option -Xms512m --jvm-option -Xmx2g

배포된 디렉터리에서 영구적으로 바꾸려면:

  • macOS와 Linux: run.sh를 편집해 APP_JAVA_OPTS 판정 앞에 JVM_OPTS+=("-Xms512m" "-Xmx2g")를 추가합니다. run.command는 같은 run.sh를 호출합니다.
  • Windows: run.bat을 편집해 APP_JAVA_OPTS 판정 앞에 set "JVM_OPTS=%JVM_OPTS% -Xms512m -Xmx2g"를 추가합니다.

일시적인 옵션은 APP_JAVA_OPTS로 주입할 수 있습니다. 자세한 예제와 주의 사항은 JVM 시작 옵션을 참고하세요. 직접 수정한 스크립트는 다시 패키징할 때 덮어씌워집니다.

5. 권장하는 보호 범위

기본적으로 애플리케이션 자신의 클래스를 보호합니다. 운영 프로젝트에서는 자사 업무 패키지를 명시적으로 지정하는 편이 안전합니다.

--protect 'com.mycompany.product.**'

보통 제외해야 할 클래스:

  • Jackson이 직접 직렬화·역직렬화하는 DTO와 레코드
  • 필드나 메서드에 JNI로 접근하는 클래스
  • ORM, 의존성 주입 컨테이너, 프록시 프레임워크가 다시 써야 하는 클래스
  • 서드파티 라이브러리와 오픈소스 프레임워크
  • 사용자 정의 ClassLoader가 바이트 배열에서 재정의해야 하는 클래스

6. .p4jx와 .jar 확장자

p4j javaapp app.jar dist --archive-suffix jar

이 옵션은 파일 이름만 바꿀 뿐 아카이브의 내용은 여전히 P4JX입니다. 서드파티 구성 요소가 URL이나 파일 이름에 .jar를 하드코딩한 경우에만 사용하세요. 아카이브가 일반 ZIP이나 JAR가 되는 것은 아닙니다.