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 startup scripts.

1. GUI operations

Select Java Application on the application type page.
Choose to input the JAR file, select The included Java version and the target platform, then pick between simple mode or advanced mode.
When using advanced mode, fill in Main class as needed and configure JVM parameters, JavaFX settings, 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 another startup class needs to be used, 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:

Options	Behavior	When to Use It
`--compat-scan`	It only scans the input JAR, prints out risks and configuration recommendations, and then exits; it does not perform encryption nor generate `dist`, so there is no need to output a directory.	After initially protecting a protected application, upgrading dependencies or adjusting the protection scope, as well as when troubleshooting compatibility issues, use it first to view the report.
`--compat-apply`	After scanning, conservative recommendations are automatically merged, after which encoding continues to generate the output; therefore, it is necessary to specify the output directory.	Once the scan results have been reviewed and the automatic suggestions accepted, use them to complete the packaging; it can also be applied to repeated builds with verified rules or in CI pipelines.

For the protection of sensitive data, the protected application employs a compatibility scan to ensure it operates within its defined protection scope. This mechanism relies on protected methods and metadata stubs to enforce security measures. To unlock all advanced features, users must obtain a full license. The system also includes an archive suffix to identify securely stored files.javaapp,--compat-applyBased on the scan results, exclusion classes can be added, and options such as ZIP overlay, JavaFX, and archive suffix can be adjusted. For the latter three options, the values explicitly specified in the command line take precedence; recommended exclusion classes are applied by default.--excludeMerge. If you do not want exclusion classes to be automatically added, you can pass them in simultaneously.--no-compat-excludesThe scanner only performs static heuristic analysis, and issues that require code modifications will not be detected.--compat-applyAutomatic repair is available, but regression testing on the target platform is still required after generation.

For other CLI commands, all options, environment variables, and automation examples, please refer to CLI Parameters Reference.

3. The protection mechanism is designed to ensure the protected application remains secure. Before using it, it is necessary to run a compatibility scan to verify system requirements and adjust the protection scope as needed. To unlock all advanced features, such as access to the protected methods, a full license must be obtained. The system also generates metadata stubs for efficient resource management. Additionally, files with a specific archive suffix are treated with heightened protection to prevent unauthorized modification.

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.

When packaging for Windows, an additional native launcher can be generated, which can be run by double-clicking. It coexists with the startup script; see Generate a Windows EXE launcher for details.

JVM startup parameters

During packaging, one parameter can be entered per line in JVM startup options within the GUI, or they can be reused 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 re-packaging.

5. Recommended protection scope

Default class for protected applications. For production projects, it is recommended to explicitly define your own business packages:

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

Items that should usually be excluded:

DTOs and records used for direct Jackson 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 filename; the archived content remains P4JX. It should be used only when third-party components hardcode .jar in URLs or filenames; it does not convert the archive into a regular ZIP/JAR file.