Protector4J Advanced Mode Settings

The advanced mode allows users to manually determine the protection scope, compatibility options, and parameters specific to application types. When processing a new application for the first time, it is recommended to use the simple mode first or run a compatibility scan on the advanced parameters page before making adjustments based on the scan results.

This document provides a detailed explanation of the advanced mode in GUI User Guide. For determining which classes should remain unencrypted, refer to Compatibility and Protection Scope; for writing automated commands, follow the guidelines in CLI Parameters Reference.

1. Enter Advanced Mode

1. Select the application type and enter the JAR/WAR file.
2. Select The included Java version and at least one target platform.
3. Choose Advanced — customise the options yourself within Mode.
4. Click Next to access the advanced parameters page.

If you are already on the output confirmation page, you can click Customize… to return to the advanced parameters page. After making changes, go back to the output page to confirm that the summary reflects the new settings.

The Java version and target platform cannot be modified on the advanced parameters page; if adjustments are needed, return to the input page. Multi-platform tasks will generate separate outputs for each platform, and the vlxjre values cannot be interchanged.

2. General Options

The four application types share the advanced parameters section, but some settings apply depending on the type. Library Encryption does not generate a startup script, so it does not use JVM startup parameters; its archive suffix setting is used to suggest and synchronize output filenames.

The specific settings for various application types are as follows:

“Classes cannot be excluded.” indicates that by default, all application classes of this application type are under protection, but it does not mean that third-party dependencies are also protected. Spring Boot’s BOOT-INF/lib and Tomcat’s WEB-INF/lib remain in a normal state by default.

Archive suffix

Choosing jar only changes the file name; the file content remains in P4JX format. It cannot be modified using regular ZIP/JAR tools, nor can it be loaded by a standard JRE. For Library Encryption, this setting switches the output file’s suffix to .p4jx/.jar; if the user specifies a different custom suffix, the full file name is retained.

Corresponding CLI:

--archive-suffix p4jx
--archive-suffix jar

Disable JIT protection for methods

Enabling Disable JIT for protected methods prevents protected methods from entering the JIT compiler, which reduces the exposure of compiled machine code. However, this may significantly slow down compute-intensive code. This setting affects only protected methods and does not switch the entire JVM to a pure interpretation mode.

Corresponding CLI:

--no-jit

Scanner ZIP overlay

The overlay exposes only public resources, directories, and metadata stubs related to protection, without including the actual method bodies. It is used to ensure compatibility with tools that directly read the central directory of a ZIP file, but it cannot replace the Spring Boot fat layout, nor can it address scenarios where archives are parsed using ZipInputStream/JarInputStream from memory streams.

Corresponding CLI:

--zip-overlay scanner

JVM startup parameters

Enter one complete parameter per line, for example:

-Xms512m
-Xmx2g
-Dfile.encoding=UTF-8

Each line represents a parameter boundary; do not write multiple parameters on the same line. Parameters will be written to the startup scripts for macOS/Linux and Windows; Tomcat parameters will also be included in its startup path. Library Encryption does not generate startup scripts, so the input field is unavailable. For more complete platform examples, see JVM startup parameters configuration.

The corresponding CLI requires repeating certain options:

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

3. Compatibility scan and application recommendations

For all four types of applications, you can click Compatibility scan… to scan the current input. When accepting the results, the tool will merge the recommendations specific to that application type into the current settings, mainly including:

• Add classes that need to remain unencrypted;
• Enable the scanner ZIP overlay;
• Adjust the archive suffix;
• Enable JavaFX/WebView for Java Application or Spring Boot;
• Select a layout for Spring Boot;
• Choose 9 or 10.1 for Tomcat.

Library Encryption automatically applies only the scanner ZIP overlay and archive suffix recommendations. It is designed to provide protection for all classes in the input JAR and does not support class exclusion; if the scan detects content such as JNI/native classes that needs to remain unencrypted, the report will clearly advise moving them to a regular JAR or using a packaging mode that supports selective protection.

Editing can continue after accepting the recommendations. The scan will retain existing exclusion rules and will not disable the JavaFX that the user has enabled just because JavaFX is not detected. Canceling the dialog will result in the recommendations not being applied.

Code-level risks identified in the scan report, such as Agents, JNI, custom class loaders, or runtime bytecode modification, usually cannot be resolved simply by flipping a switch. It is necessary to adjust the code boundaries using Compatibility and Protection Scope and conduct actual testing.

4. Java Application settings

Main class

When left empty, it reads the Main-Class from the input JAR Manifest. Enter the full class name only if the Manifest lacks a main class or if it is necessary to override the default startup class, such as in com.example.Main.

Corresponding CLI: --main com.example.Main.

Classes to exclude

By default, all application classes are protected. Classes or packages in this list remain unencrypted and are suitable for DTOs, entities, configuration classes, JNI bridge classes, and those that need to be enhanced by frameworks or have their actual bytecode read. For the rule format, see “Protection scope and exclusion rules”.

JavaFX runtime

For regular JavaFX applications, select Bundle JavaFX into the packaged runtime. For WebView, options are available:

• Auto: Included when javafx.scene.web is detected;
• Include: Forces inclusion of fx-webkit;
• Exclude: Must be excluded.

WebView will add approximately 40 MB. The GUI will download assets for the target Java version and platform; use the CLI when specifying a local offline JavaFX directory.

Corresponding CLIs: --javafx, --javafx-webview, and --no-javafx-webview. Auto does not include additional WebView options, as it is determined by the packer based on the application’s references.

5. Spring Boot settings

Main class

If left empty, Start-Class reads from the Manifest. Enter the full class name if you need to override the main class.

Corresponding CLI: --main com.example.Application.

Layout

If the compatibility scan explicitly recommends fat, do not force the use of p4jx-fat just by enabling ZIP overlay. For layout details, see Protection for Spring Boot applications.

Corresponding CLIs: --layout p4jx-fat, --layout fat, or --layout separate.

Protect dependency JARs…

Dependencies in BOOT-INF/lib are not protected by default. Only select your own proprietary dependencies; do not encrypt third-party framework packages such as Spring, Tomcat, logging tools, or database drivers. Signed JARs will appear unselectable because modifying them would break their signature.

Once a dependency is selected, all its classes are protected, but Classes to exclude rules can still be used to exclude specific classes or packages from this dependency. All three Spring Boot layouts support protecting dependencies.

Corresponding CLI: --protect-lib 'company-core.jar,company-domain.jar'. The CLI also supports glob patterns; the GUI saves the exact file names of the selected JARs.

Classes to exclude and JavaFX

The usage is the same as that of a Java Application. The exclusion rules apply to both the application classes and the dependent JARs that are set to be protected. Spring Boot + JavaFX desktop applications can also have JavaFX/WebView packaged in the JavaFX runtime tab.

6. Tomcat settings

Tomcat version

• Use javax.servlet.* for the WAR and select Tomcat 9 · javax;
• Use jakarta.servlet.* for the WAR and select Tomcat 10.1 · jakarta.

Tomcat 10.1 requires at least Java 11. Run a compatibility scan if unsure; if the application uses both javax and jakarta, do not force a version selection—resolve dependency conflicts first.

The advanced mode does not have preselected versions. You must accept the scan suggestions or manually select a version before proceeding. Corresponding CLI options: --tomcat-version 9 or --tomcat-version 10; the CLI also allows auto.

Context path

Enter the deployment path starting with /, such as /app. If left blank, /app will be used. When adding an application to an existing Tomcat output directory, the context path must not duplicate an existing application.

Corresponding CLI: --context /app.

Classes to exclude

By default, it provides protection for applications under WEB-INF/classes, while WEB-INF/lib is not protected by default. Classes such as Servlet, Filter, Listener, DTO, configuration files, entities, JNI bridge classes, and classes that require enhancement by the container should usually be excluded.

7. Protection scope and exclusion rules

In advanced mode, the GUI defaults to protecting all application classes, with framework boundaries defined by Classes to exclude. Three types of rules are supported:

com.example.SecretService   Match only this class
com.example.service.*       Match the current package, excluding sub-packages
com.example.service.**      Match the current package and all its sub-packages

Classes can be selected from the class tree using Choose…, or added manually via Add…. By default, package selection covers the current package and its sub-packages; use .* to exclude only the current package. The Spring Boot class tree also displays the dependent JARs that have been selected for protection.

The recommended configuration is “Public boundary/framework entry → Regular facade or interface → Protected core implementation”. Avoid encrypting all third-party dependencies or framework entries just to expand the protection scope.

8. Export, Reuse, and Final Review

Clicking Export parameters… allows you to export:

• p4j-encrypt-run.sh
• p4j-encrypt-run.bat

The export script saves the currently configured options but does not include account email addresses or passwords. You can later restore the task using Load Task File at the top.

After entering the output page, review the following items at least:

• Enter the file, application type, Java version, and all target platforms.
• Archiving suffixes, JIT, scanner overlay, and JVM parameters;
• JavaFX/WebView, Spring Boot layout, or Tomcat version/context;
• Protected dependency JARs and all exclusion rules;
• Output directory and whether to create a new p4jx-xxxx subdirectory.

After generation, it is necessary to use the in-package startup script on each target platform to verify startup, framework scanning, serialization, reflection, resource loading, and core business paths. Correct configuration on the advanced parameters page only indicates that the task parameters have been set; it cannot replace final product verification.