Protection for regular Java applications

javaapp is used for regular Java applications with a main class. It generates a protected archive, the target platform’s VLX JRE, and a startup script.

1. GUI operations

Select Java Application on the application type page.
Select the input JAR, The included Java version, and target platform, then choose between simple mode or advanced mode.
When using advanced mode, fill in Main class as needed and configure JVM parameters, JavaFX, and exclusion rules; this page can be skipped in simple mode. For the meaning of each option, see Protector4J Advanced Mode Settings.
Select the output directory, review the parameter summary, then click Run protection.

2. CLI examples

When the Manifest already contains the correct Main-Class:

p4j javaapp app.jar dist

If the Manifest lacks Main-Class or a different startup class is needed, specify it through --main:

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

Specify both the startup class and JVM parameters at the same time:

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

Selective protection:

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

Compatibility scan and automatic application suggestions:

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

These two options cannot be used simultaneously. Their differences are:

Option	Behavior	When to use
`--compat-scan`	It only scans the input JAR, prints risks and configuration suggestions, and then exits; it does not encode or generate `dist`, so an output directory is not required.	Use it first to view reports after initially protecting an application, upgrading dependencies, adjusting the protection scope, or troubleshooting compatibility issues.
`--compat-apply`	It automatically merges conservative suggestions after scanning, then continues encoding and generating outputs, so an output directory must be specified.	Use it to complete packaging after reviewing the scan results and accepting the automatic suggestions; it can also be used for repeated builds with verified rules or in CI workflows.

For javaapp and --compat-apply, you can add exclusion classes based on the scan results and adjust options such as ZIP overlay, JavaFX, and archive suffixes. For the latter three options, explicitly specified values in the command line take precedence; recommended exclusion classes are merged with explicitly specified --exclude by default. If you do not want exclusion classes to be added automatically, you can also pass in --no-compat-excludes. The scanner only performs static heuristic analysis, and issues that require code modifications will not be automatically fixed by --compat-apply; regression testing on the target platform is still needed after generation.

For other CLI commands, all options, environment variables, and automation examples, see CLI Parameters Reference.

3. Output structure

dist/
├── app.p4jx              # or --archive-suffix jar to generate app.jar
├── vlxjre/               # Runtime that matches the archive and target platform
├── lib/                  # Dependencies on Manifest Class-Path, optional
├── run.sh
├── run.command
├── run.bat
└── README.md

Non-class resources are stored in P4JX’s public resource view. Protected class resources only display metadata stubs to the scanner; the actual method bodies can only be loaded by the VLX runtime.

4. Start

./run.sh [Application parameters...]

Windows:

run.bat [Application parameters...]

Do not replace vlxjre in the output directory with the system JRE. If manual startup is necessary, retain its class path, VM parameters, and JavaFX module parameters using the generated script as a template.

JVM startup parameters

During packaging, you can enter one parameter per line in JVM startup options in the GUI, or reuse them in the CLI:

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

Permanently modify the current directory after deployment:

macOS/Linux: Edit run.sh and add JVM_OPTS+=("-Xms512m" "-Xmx2g") before the check in APP_JAVA_OPTS; run.command will call the same run.sh.
Windows: Edit run.bat and add set "JVM_OPTS=%JVM_OPTS% -Xms512m -Xmx2g" before the check in APP_JAVA_OPTS.

Temporary parameters can be injected through APP_JAVA_OPTS. For complete examples and precautions, see JVM startup parameters configuration. Manual script modifications will be overwritten during repackaging.

5. Recommendations for protection scope

Classes of the protected application are set by default. For production projects, it is recommended to explicitly specify your own business packages:

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

The following should usually be excluded:

DTOs and records that use Jackson for direct serialization/deserialization;
Classes whose fields or methods are accessed via JNI;
Classes that require modification by ORM, dependency injection, or proxy frameworks;
Third-party libraries and open-source frameworks;
Classes that must be redefined from byte arrays using a custom ClassLoader.

6. Suffixes `.p4jx` and `.jar`

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

This option only changes the file name; the archive content remains P4JX. It is used only when third-party components hardcode .jar in URLs or file names; it does not convert the archive into a regular ZIP/JAR.