일반 Java 애플리케이션의 보호

javaapp는 메인 클래스가 포함된 일반적인 Java 애플리케이션에 사용됩니다. 이 도구는 보호된 아카이브, 대상 플랫폼용 VLX JRE, 그리고 시작 스크립트를 생성합니다.

1. GUI 조작

애플리케이션 유형 페이지에서 Java Application를 선택하세요.
JAR, 포함된 Java 버전, 그리고 대상 플랫폼을 입력한 뒤, 단순 모드 또는 고급 모드 중 하나를 선택하세요.
고급 모드를 사용할 경우, 필요에 따라 Main class를 입력하고 JVM 파라미터, JavaFX 및 제외 규칙을 설정해야 합니다. 간단 모드에서는 이 페이지를 건너뛸 수 있습니다. 각 옵션의 의미는 Protector4J 고급 모드 설정를 참조하십시오.
출력 디렉터리를 선택하고, 파라미터 요약을 확인한 다음 Run protection를 클릭하세요.

2. CLI 예시

Manifest에 올바른 Main-Class가 포함된 경우:

p4j javaapp app.jar dist

Manifest에 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 overlay, JavaFX, 아카이브 접미사와 같은 옵션들을 조정할 수 있습니다. 후자의 세 가지 옵션에 대해서는 명령줄에서 명시적으로 지정한 값이 우선 적용되며, 권장되는 제외 클래스는 기본적으로 명시적으로 지정된 --exclude와 통합됩니다. 자동으로 제외 클래스를 추가하지 않으려면 --no-compat-excludes도 함께 입력할 수 있습니다. 스캐너는 단순히 정적 힌트 기반 분석만 수행하므로 코드를 수정해야 하는 문제들은 --compat-apply를 통해 자동으로 수정되지 않으며, 결과물이 생성된 후에도 대상 플랫폼에서 재테스트가 필요합니다.

기타 CLI 명령, 모든 옵션, 환경 변수 및 자동화 예제는 CLI 매개변수 참고를 참조하십시오.

3. 출력 구조

dist/
├── app.p4jx              # 또는 --archive-suffix jar를 사용하여 app.jar 생성
├── vlxjre/               # 아카이브 및 대상 플랫폼에 맞는 런타임
├── lib/                  # Manifest Class-Path에 의존하며, 선택 사항임
├── run.sh
├── run.command
├── run.bat
└── README.md

class가 아닌 리소스는 P4JX의 공개 리소스 뷰에 저장됩니다. 보호된 class 리소스의 경우 스캐너에는 메타데이터 스텁만 표시되며, 실제 메서드 본문은 VLX 런타임을 통해서만 로드될 수 있습니다.

4. 시작

./run.sh [애플리케이션 파라미터...]

Windows:

run.bat [애플리케이션 파라미터...]

출력 디렉토리에 있는 vlxjre를 시스템 JRE로 대체하지 마십시오. 반드시 수동으로 시작해야 하는 경우, 생성된 스크립트를 템플릿으로 삼아 클래스 경로, VM 파라미터, JavaFX 모듈 파라미터를 그대로 유지해야 합니다.

Windows 대상을 패키징할 때는 추가로 네이티브 시작 프로그램을 생성할 수 있으며, 이를 더블클릭하여 실행할 수 있습니다. 이 프로그램은 시작 스크립트와 함께 존재하며, 자세한 내용은 Windows EXE 시작 프로그램 생성를 참조하십시오.

JVM 시작 매개변수

패키징 시 GUI의 JVM startup options에 각 줄에 하나의 매개변수를 입력하거나, CLI에서 반복해서 사용할 수 있습니다.

--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, record 클래스들;
JNI를 통해 필드나 메서드에 접근하는 클래스들;
ORM, 의존성 주입 또는 프록시 프레임워크로 인해 수정이 필요한 클래스들;
서드파티 라이브러리 및 오픈소스 프레임워크들;
커스텀 ClassLoader를 통해 바이트 배열로부터 재정의되어야 하는 클래스들.

6. `.p4jx` 및 `.jar` 접미사

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

이 옵션은 파일명만 변경할 뿐, 아카이브의 내용은 여전히 P4JX입니다. 서드파티 컴포넌트가 URL이나 파일명에 .jar를 하드코딩한 경우에만 사용해야 하며, 이를 통해 아카이브가 일반 ZIP/JAR 형식으로 변하는 것은 아닙니다.