Protector4J 詳細設定モード
詳細設定モードでは、保護範囲、互換性オプション、アプリケーションの種類ごとの固有オプションを手動で設定できます。新しいアプリケーションを初めて扱うときは、まずシンプルモードを使うか、詳細オプションのページで一度互換性スキャンを実行し、その結果にもとづいて調整することをおすすめします。
このページは GUI ガイドの詳細設定モードの節を詳しく説明したものです。どのクラスを保護しないままにするかを判断する際は互換性と保護範囲を、同じ内容を自動化コマンドで書く際は CLI リファレンスを参照してください。
1. 詳細設定モードに入る
- アプリケーションの種類を選び、入力する JAR または WAR を指定します。
- 同梱する Java バージョンと、ターゲットプラットフォームを 1 つ以上選びます。
- モードで詳細設定 — オプションを自分でカスタマイズしますを選びます。
- 次へをクリックして詳細オプションのページを開きます。
すでに出力確認ページにいる場合は、**カスタマイズ...**をクリックすると詳細オプションに戻れます。変更したら出力ページに戻り、サマリーに反映されていることを確認してください。
Java バージョンとターゲットプラットフォームは詳細オプションのページでは変更できません。変更するには入力ページに戻ってください。複数プラットフォームのタスクではプラットフォームごとに独立した出力が生成され、それぞれの vlxjre に互換性はありません。
2. 一般的なオプション
4 つのアプリケーションの種類でこの領域を共有しますが、一部の設定は特定の種類にのみ適用されます。ライブラリ暗号化は起動スクリプトを生成しないため JVM スタートアップオプションを持ちません。アーカイブサフィックスの設定は、出力ファイル名の推奨と同期に使われます。
| 設定 | 既定値 | 役割 | 推奨 |
|---|---|---|---|
| アーカイブサフィックス | p4jx | アプリケーションのアーカイブを .p4jx または .jar という名前にします | .p4jx のままにします。サードパーティのコンポーネントが .jar というファイル名をハードコードしている場合にのみ jar に変更します。 |
| 保護されたメソッドで JIT を無効化 | オフ | 保護対象メソッドをインタプリタのみで実行します | コードの機密性が高く、性能への影響を評価済みの場合に有効にします。 |
| スキャナ ZIP オーバーレイ | オフ | ZIP の構造をスキャンするツール向けに互換ビューを追加します | 互換性スキャンが推奨した場合、またはアプリケーションが実際に物理 ZIP の構造を読む場合にのみ有効にします。 |
| JVM スタートアップオプション | 空 | 生成される起動スクリプトに JVM オプションを書き込みます | 1 行に 1 つ、完全な形で入力します。 |
| 互換性スキャン... | 自動実行しない | 入力をスキャンし、保守的な推奨を提示します | 新しいアプリケーション、フレームワークの更新後、保護範囲の変更後に実行し直します。 |
アプリケーションの種類ごとの固有オプションは次のとおりです。
| 種類 | 固有オプション | 初期状態 | 対応する CLI オプション |
|---|---|---|---|
| Java アプリケーション | メインクラス、除外するクラス、JavaFX と WebView | メインクラスはマニフェストから取得。除外なし。JavaFX は同梱しない | --main、--exclude、--javafx、--javafx-webview / --no-javafx-webview |
| Spring Boot | メインクラス、レイアウト、依存 JAR の保護、除外するクラス、JavaFX と WebView | メインクラスは Start-Class から取得。レイアウトは p4jx-fat。依存関係は保護しない。除外なし。JavaFX は同梱しない | --main、--layout、--protect-lib、--exclude、および JavaFX 関連のオプション |
| Tomcat | Tomcat バージョン、コンテキストパス、除外するクラス | バージョン未選択。コンテキストパスは /app。除外なし | --tomcat-version、--context、--exclude |
「除外なし」とは、その種類のアプリケーションクラスをすべて保護するという意味であり、サードパーティの依存関係まで保護するという意味ではありません。Spring Boot の BOOT-INF/lib と Tomcat の WEB-INF/lib は、いずれも既定では保護範囲外です。
アーカイブサフィックス
jar を選んでもファイル名が変わるだけで、中身は P4JX のままです。通常の ZIP や JAR のツールでは開けず、標準の JRE でも読み込めません。ライブラリ暗号化では、この設定によって出力ファイルのサフィックスが .p4jx と .jar の間で切り替わります。自分で別のサフィックスを入力した場合は、入力したファイル名がそのまま使われます。
対応する CLI オプション：
--archive-suffix p4jx
--archive-suffix jar
保護されたメソッドで JIT を無効化
保護されたメソッドで JIT を無効化を有効にすると、保護対象メソッドが JIT コンパイラに渡らなくなり、コンパイル後の機械語が露出する範囲を狭められます。計算量の多いコードでは大幅に遅くなることがあります。この設定は保護対象メソッドにのみ影響し、JVM 全体をインタプリタ実行に切り替えるわけではありません。
対応する CLI オプション：
--no-jit
スキャナ ZIP オーバーレイ
オーバーレイが露出するのは、公開リソース、ディレクトリ、保護対象クラスのメタデータスタブだけで、実際のメソッド本体は決して含まれません。ZIP の中央ディレクトリを直接読むツールを動かし続けるためのものです。Spring Boot の fat レイアウトの代わりにはならず、ZipInputStream や JarInputStream でメモリストリームからアーカイブを解析する場合にも役立ちません。
対応する CLI オプション：
--zip-overlay scanner
JVM スタートアップオプション
1 行に 1 つ、完全な形で入力します。例：
-Xms512m
-Xmx2g
-Dfile.encoding=UTF-8
1 行が 1 つのオプションです。2 つを同じ行に書かないでください。これらは macOS、Linux、Windows の起動スクリプトに書き込まれ、Tomcat の場合はその起動経路にも書き込まれます。ライブラリ暗号化は起動スクリプトを生成しないため、この入力欄は使えません。各プラットフォームの詳しい例は JVM スタートアップオプションを参照してください。
対応する CLI では、オプションを繰り返します。
--jvm-option -Xms512m --jvm-option -Xmx2g
3. 互換性スキャンとその推奨
4 つの種類すべてで、**互換性スキャン...**から現在の入力をスキャンできます。結果を受け入れると、その種類に応じた推奨が現在の設定にマージされます。主な内容は次のとおりです。
- 保護しないままにすべきクラスの追加
- スキャナ ZIP オーバーレイの有効化
- アーカイブサフィックスの調整
- Java アプリケーションや Spring Boot での JavaFX と WebView の有効化
- Spring Boot のレイアウトの選択
- Tomcat 9 または 10.1 の選択
ライブラリ暗号化で自動適用されるのは、スキャナ ZIP オーバーレイとアーカイブサフィックスの 2 つだけです。入力 JAR 内のすべてのクラスを保護する設計のため除外に対応しておらず、保護しないままにすべきもの (JNI やネイティブクラスなど) が見つかった場合は、それらを通常の JAR に移すか、選択的な保護に対応したパッケージングモードに切り替えるようレポートが案内します。
推奨を受け入れたあとも編集を続けられます。スキャンは既存の除外ルールを保持し、JavaFX が検出されなかったという理由で、手動で有効にした JavaFX を無効にすることもありません。ダイアログをキャンセルした場合は何も適用されません。
レポートに挙がるコードレベルのリスク (エージェント、JNI、カスタムクラスローダー、実行時のバイトコード変更) は、設定を変えるだけでは解決できないのが普通です。互換性と保護範囲を参考にコードの境界を見直し、実際にテストしてください。
4. Java アプリケーションのオプション
メインクラス
空欄の場合は、入力 JAR のマニフェストから Main-Class を読み取ります。マニフェストにメインクラスがない場合や、上書きしたい場合にのみ完全なクラス名を入力します (例：com.example.Main)。
対応する CLI オプション：--main com.example.Main。
除外するクラス
既定ではすべてのアプリケーションクラスを保護します。ここに挙げたクラスやパッケージは保護されないままになります。DTO、エンティティ、設定クラス、JNI ブリッジクラス、フレームワークが拡張するクラス、自身の実際のバイトコードを読む必要があるクラスに適しています。ルールの書き方は下の「保護範囲と除外ルール」を参照してください。
JavaFX ランタイム
通常の JavaFX アプリケーションでは JavaFX をパッケージランタイムに含めるにチェックを入れます。WebView には 3 つの方針があります。
- 自動 (javafx.scene.web を検出)：
javafx.scene.webが検出された場合のみ含めます。 - 含める：常に
fx-webkitを含めます。 - 除外：含めません。
WebView はおよそ 40 MB 増えます。GUI はターゲットの Java バージョンとプラットフォームに合わせてコンポーネントをダウンロードします。ローカルのオフライン JavaFX ディレクトリを指定する場合は CLI を使ってください。
対応する CLI オプション：--javafx、--javafx-webview、--no-javafx-webview。自動に追加のオプションはありません。パッケージャーがアプリケーション自身の参照から判断するためです。
5. Spring Boot のオプション
メインクラス
空欄の場合はマニフェストから Start-Class を読み取ります。上書きする場合は完全なクラス名を入力します。
対応する CLI オプション：--main com.example.Application。
レイアウト
| レイアウト | 向いている場面 |
|---|---|
p4jx-fat | 既定のレイアウト。標準的な Spring Boot サービスで、保護範囲がもっとも広くなります。 |
fat | ClassGraph や Reflections を使うなど、物理的な Spring Boot JAR の構造が必要な場合。 |
separate | lib/* のフラットなクラスパスを必要とする、古い連携環境。 |
互換性スキャンが fat を明確に推奨している場合は、p4jx-fat に戻して ZIP オーバーレイで補おうとしないでください。各レイアウトの詳細は Spring Boot アプリケーションの保護を参照してください。
対応する CLI オプション：--layout p4jx-fat、--layout fat、--layout separate。
依存 JAR を保護
BOOT-INF/lib の依存関係は既定では保護されません。自社のクローズドソースの依存関係だけを選び、Spring、Tomcat、ロギングライブラリ、データベースドライバーといったサードパーティのフレームワークは暗号化しないでください。署名済みの JAR は、変更すると署名が壊れるため選択できません。
依存関係を選ぶとその中のすべてのクラスが保護されますが、除外するクラスを使えば特定のクラスやパッケージを保護対象から外せます。3 つの Spring Boot レイアウトすべてで依存関係の保護に対応しています。
対応する CLI オプション：--protect-lib 'company-core.jar,company-domain.jar'。CLI では glob も使えます。GUI は選択した JAR の正確なファイル名を記録します。
除外するクラスと JavaFX
使い方は Java アプリケーションとまったく同じです。除外ルールは、アプリケーションクラスと、保護対象に選んだ依存 JAR の両方に適用されます。Spring Boot のデスクトップアプリケーションでも、JavaFX ランタイムタブから JavaFX と WebView を同梱できます。
6. Tomcat のオプション
Tomcat バージョン
- WAR が
javax.servlet.*を使っている場合は Tomcat 9 · javax を選びます。 jakarta.servlet.*を使っている場合は Tomcat 10.1 · jakarta を選びます。
Tomcat 10.1 には Java 11 以降が必要です。判断がつかない場合は互換性スキャンを実行してください。javax と jakarta の両方を使っている場合は、バージョンを無理に選ばず、まず依存関係の競合を解消してください。
詳細設定モードではバージョンが事前選択されません。スキャンの推奨を受け入れるか、自分で選ぶまで先に進めません。対応する CLI オプションは --tomcat-version 9 または --tomcat-version 10 で、CLI では auto も指定できます。
コンテキストパス
/ で始まる配備パスを入力します (例：/app)。空欄の場合は /app が使われます。既存の Tomcat 出力ディレクトリにアプリケーションを追加する場合、コンテキストパスが既存のものと重複してはいけません。
対応する CLI オプション：--context /app。
除外するクラス
既定では WEB-INF/classes 配下のアプリケーションクラスを保護し、WEB-INF/lib は対象外です。サーブレット、フィルター、リスナー、DTO、設定クラス、エンティティ、JNI ブリッジクラス、コンテナーが拡張する必要のあるクラスは、通常は除外してください。
7. 保護範囲と除外ルール
詳細設定モードでは、GUI は既定ですべてのアプリケーションクラスを保護し、除外するクラスでフレームワークとの境界を引きます。ルールの書き方は 3 種類です。
com.example.SecretService このクラスのみ
com.example.service.* このパッケージのみ (サブパッケージを含まない)
com.example.service.** このパッケージとすべてのサブパッケージ
**選択...**でクラスツリーから選ぶことも、**追加...**で直接入力することもできます。パッケージを選ぶと既定でそのサブパッケージも対象になります。.* を使えばそのパッケージ自体だけに限定できます。Spring Boot のクラスツリーには、保護対象に選んだ依存 JAR も表示されます。
推奨する構成は、公開境界やフレームワークのエントリポイント → 通常のファサードまたはインターフェイス → 保護された中核実装、という並びです。保護範囲を広く見せるためだけに、サードパーティの依存関係やフレームワークのエントリポイントまで暗号化しないでください。
8. エクスポート、再利用、最終確認
パラメータをエクスポート...をクリックすると、手動で編集できる p4j-task.yml タスクファイルをエクスポートできます。確定済みのオプションが記録されますが、アカウントのメールアドレスとパスワードは決して書き込まれません。あとからウィンドウ上部のタスクファイルを読み込むでタスクを復元できます。この入口は、旧バージョンがエクスポートした p4j-encrypt-run.sh と .bat も引き続き読み込めます。
出力ページでは、少なくとも次を確認してください。
- 入力ファイル、アプリケーションの種類、Java バージョン、すべてのターゲットプラットフォーム
- アーカイブサフィックス、JIT の設定、スキャナオーバーレイ、JVM スタートアップオプション
- JavaFX と WebView、Spring Boot のレイアウト、または Tomcat のバージョンとコンテキストパス
- 保護対象に選んだ依存 JAR と、すべての除外ルール
- 出力ディレクトリと、
p4jx-xxxxサブディレクトリを新規作成するかどうか
生成後は、ターゲットプラットフォームごとにパッケージ内の起動スクリプトを使い、起動、フレームワークのスキャン、シリアライズ、リフレクション、リソースの読み込み、中核となる業務フローを確認してください。詳細オプションが正しく設定されていることは、タスクの設定が正しいことを示すだけで、最終成果物の検証の代わりにはなりません。