PreEmptive Protection - DashO v8.2 User Guide

プロジェクト ファイル リファレンス

このセクションでは、PreEmptive Protection - DashO の XML プロジェクト ファイルについて説明します。ユーザー インターフェイスを使用してファイルを生成している場合にもリファレンスとして役立つように、各オプションを詳しく解説します。

PreEmptive Protection - DashO プロジェクト ファイルには、どのような名前や拡張子を付けてもかまいませんが、優先される拡張子は .dox です。プロジェクト ファイルには、指定したアプリケーションがどのように難読化処理されるかについての情報が含まれています。プロジェクト ファイルは、DashO と一緒に配布される dasho.xsd に準拠する XML ドキュメントです。

メモ:

ほとんどの場合、要素や属性の先頭と末尾にある空白は削除されます。

<dasho>

<dasho> タグは、.dox ファイルの最も外側のタグです。

Version 属性

ファイル バージョンは必要な属性です。プロジェクト ファイルを読み取ることができる最も古い DashO のバージョンを指定します。たとえば、version="6.9" プロジェクトは、プロジェクトを編集しなくても、バージョン 7.2 の DashO で使用することができます。

<dasho version="7.2.0">

メモ:

DashO は、アプリケーションのバージョンと異なるバージョンでプロジェクト ファイルを作成することができます。ファイル バージョンは、プロジェクト ファイルを使用することができる DashO の最小バージョンを表します。

<propertylist> セクション

省略可能な <propertylist>(プロパティ リスト)セクションでは、プロパティと呼ばれる変数の定義および値の代入を行うことができます。これらは、プロジェクト ファイルで使用したり、他のプロパティの値を定義するために使用したりすることができます。

<propertylist>
    <property name="projectname" value="myproject">
    <property name="projectdir" value="c:\myprojects">
</propertylist>

プロジェクト ファイルが存在するディレクトリを示す、dasho.basedir と呼ばれる組み込みの外部プロパティがあります。保存されていない新しいプロジェクトでは、dasho.basedir は適用できません。

プロパティは、複数のプロジェクトや同じプロジェクトのさまざまなバージョン、あるいはさまざまなビルド環境間での移植を容易にするためのテンプレートとしての役割を果たすプロジェクト ファイルの作成に役立ちます。

プロパティ参照

プロパティは、次の構文で参照されます。

${property_name}

プロパティ参照は大文字と小文字を区別するので、${MyProjectDir}${myprojectdir} とは異なるプロパティを参照します。定義されていないプロパティを参照する場合は、そのリテラル値が使用されます。プロパティは、他のプロパティの条件に基づいて定義することができます。プロパティの値は、環境変数への参照も含め、1 つまたは複数のプロパティ参照を使用して指定できます。このプロパティ参照として、既定値、間接参照、置換構文が挙げられます。再帰的な変数を定義することはできません。

DashO は、プロパティを参照するための柔軟な方法を多数提供しています。

${prop} 単純な置換。prop の値が定義されていないか空白の場合、置換は行われず、${prop} は変更されません。
${prop:-default} 既定値による置換。prop が定義されており、空白でない場合は、その値を使用します。そうでない場合は、値として既定値を使用します。
${prop:+value} 定義されている場合は置換。prop が定義されており、空白でない場合は、その値が使用されます。それ以外で prop が定義されている場合は、空白の文字列が代用されます。
${prop:?message} 設定されていない場合にエラーを生成。prop が定義されており、空白でない場合は、その値が使用されます。そうでない場合は、メッセージのテキストを含むエラーが生成され、ビルドが終了します。
${prop/pattern/replace} パターン代入後に置換。正規表現 pattern の最初の出現箇所を置換テキスト replace で置き換えます。replace が空白の場合は、一致するテキストが削除されます。
${prop//pattern/replace} パターン代入後に置換。正規表現 pattern のすべての出現箇所を置換テキスト replace で置き換えます。replace が空白の場合は、一致するテキストが削除されます。
${prop/#pattern/replace} パターン代入後に置換。先頭の正規表現 pattern を置換テキスト replace で置き換えます。replace が空白の場合は、一致するテキストが削除されます。
${prop/%pattern/replace} パターン代入後に置換。末尾の正規表現 pattern を置換テキスト replace で置き換えます。replace が空白の場合は、一致するテキストが削除されます。
${prop#pattern} パターン削除後に置換。先頭の正規表現 pattern を削除します。
${prop%pattern} パターン削除後に置換。末尾の正規表現 pattern を削除します。
${!prop} 間接的な置換。prop が定義されており、空白でない場合は、その値がプロパティ名として使用されます。その後、このプロパティの値は置換値として使用されます。間接的な置換に続いて、前述の参照のうちどれでも使用することができます。

メモ:

prop が定義されていないか空白の場合は、${prop:-} を使用して空の文字列を代入することができます。

動的プロパティ

プロジェクト ファイルのいくつかの場所で、動的プロパティを使用することができます。このプロパティの値には、処理されているクラスやメソッドに関する情報が含まれます。

  • ${CLASS_NAME} – パッケージ名を含む、現在のクラスの完全な名前。

  • ${CLASS_SIMPLENAME} – クラスの簡易名。つまり、パッケージ名のないクラス名。

  • ${CLASS_PACKAGE} – 末尾のピリオドを含む、クラスのパッケージ名。これは、既定のパッケージのクラスでは空の文字列になります。プロパティが展開されるようにするには、${CLASS_PACKAGE:-} を使用します。

  • ${METHOD_NAME} – 現在のメソッドの名前。コンストラクターの場合、これは ${CLASS_SIMPLENAME} と同じです。

  • ${PROP_NAME} – メソッドが setter または getter である場合は、関連するプロパティの名前。コンストラクターの場合、これは ${CLASS_SIMPLENAME} と同じです。

以下のプロパティ値は、プロジェクト ファイルの場所と名前によって異なります。

  • ${dasho.file} – プロジェクト ファイルの絶対パス。

  • ${dasho.basedir} – プロジェクト ファイルがあるディレクトリへの絶対パス。

  • ${dasho.project} – プロジェクト ファイルの、パスも拡張子もない名前。

以下のプロパティ値は、実行環境によって異なります。

  • ${dasho.java.version} – DashO が検出した JVM バージョン。"1.7" または "1.8"。

  • ${jce.jar} – Java Cryptography Extension jar の絶対パス。

  • ${jsse.jar} – Java Secure Socket Extension jar の絶対パス。

  • ${javaws.jar} – Java Web Start jar の絶対パス。

タイムスタンプ プロパティ

DashO では、現在の日付および時刻に関する情報を挿入できるように、tstamp プロパティが用意されています。tstamp プロパティは、次の 2 つの異なる方法で使用できます。

  • ${tstamp} – ロケールの既定の書式を使用して、日付の情報を挿入します。

  • ${tstamp[pattern]} – 書式指定を使用して、日付の情報を挿入します。pattern は、Java の SimpleDateFormat クラスで使用されるものと同じです。

プロパティの優先順位

プロジェクト ファイルに定義されているプロパティ、Java のシステム プロパティ、または環境プロパティの値を参照することができます。プロパティの値を解決するために、DashO は次の順序でソースを調べます。

  • Java のシステム プロパティ

  • 環境プロパティ

  • プロジェクト ファイルのプロパティ

Java コマンド ラインの -D オプション、DashO コマンド ラインの --properties <filename> オプションを使用するか、Gradle 統合または Ant 統合を介せば、プロジェクト ファイルに定義されているプロパティをオーバーライドすることができます。

メモ:

--properties 引数によって設定されたプロパティは、-D オプションによって設定されたプロパティをオーバーライドします。

プロパティは、次のタグと共に使用することができます。

  • <entrypoints>/<applet>name 属性

  • <entrypoints>/<ejb>name 属性

  • <entrypoints>/<iappli>name 属性

  • <entrypoints>/<library>/<jar> および <entrypoints>/<library>/<dir>path 属性

  • <entrypoints>/<midlet>name 属性

  • <entrypoints>/<android>name 属性

  • <entrypoints>/<publics>name 属性

  • <entrypoints>/<quickjar> のパス属性

  • <entrypoints>/<servlet>name 属性

  • <entrypoints>/<unconditional>name 属性

  • <global>/<exclude>classname 属性

  • <includenonclassfiles>/<copy>source および relativedest 属性

  • <inputpath>/<pathelement> および <classpath>/<pathelement>location 属性

  • <mapping>/<mapinput>suffix 属性

  • <mapping>/<mapinput>path 属性

  • <mapping>/<mapoutput>path 属性

  • <mapping>/<mapreport>path 属性

  • <output>/<dir>path 属性

  • <output>/<jar>path および manifest 属性

  • <output>/<constpooltag> の値

  • <output>/<sourcefile> の値

  • <premark>/<passphrase> の値

  • <premark>/<watermark> の値

  • <preverifier> の値

  • <rename>/<class-options>prefix 属性

  • <rename>/<class-options>alphabet 属性

  • <rename>/<member-options>alphabet 属性

  • <report>path 属性

  • <expiry>periodwarningperioddate、および warningdate 属性

  • <expiry>/<property>name および value 属性

  • <tamperCheck>action および customDataSource 属性

  • <tamperCheck>/<signerInfo>aliaskeystorestorepass、および storetype 属性

  • <tamperResponse>source および customDataSource 属性

  • <debugEnabledCheck>action および customDataSource 属性

  • <debugEnabledResponse>source および customDataSource 属性

  • <debuggingCheck>action および customDataSource 属性

  • <debuggingResponse>source および customDataSource 属性

  • 名前の値が customDataSource の場合、<annotations>/<property>value 属性

  • <shelfLifeCheck>actioncustomDataSourceexpirationDatewarningDatestartDateSourceexpirationPeriodwarningPeriod、および tokenSource 属性

  • <signJar> の値とその keystorestoretypestorepassaliaskeypasssigfile、および addArgs 属性

<global> セクション

<global> セクションは省略可能であり、実行全体にわたって適用するオプションを定義するためにあります。このセクションには、グローバル オプションとグローバル除外が含まれています。

メモ:

グローバル オプションは、大文字と小文字を区別しません。

Fornamedetection グローバル オプション

fornamedetection オプションは、動的に対象選択されるクラスを検索する、DashO の組み込み機能をオンにします。これにより、実行にかなりの処理時間が追加されます。最初に、このオプションを備えたアプリケーションを実行し、その後、これらのクラスをエントリ ポイントとしてファイルに追加することをお勧めします。

場合によっては、DashO は、どのクラスが動的に読み込まれるのかを判断できません。プログラムは、クラスの名前をユーザー入力として読み込むか、または外部ファイルで指定するよう要求することができます。しかし、ほとんどの対象選択はそれほどあいまいなものではないため、DashO はそれらが何であるかを安全に判断できます。レポート ファイルは、指定されたクラスの対象選択の検出に関連付けられている信頼度を報告します。HIGH の信頼度は、ほぼ確実に正しいです。つまり、DashO は次のようなものを検出します。

Class a = Class.forName("java.awt.Rectangle");

POSSIBLE の信頼度は、経験に基づいた推測です。DashO は次のようなコードを検出します。

String s = getUnknownString();
Class a = Class.forName(s);
Rectangle r = (Rectangle)a.newInstance();

この場合、DashO は正確にどのクラスが読み込まれるのかを検出できません。しかし、読み込まれたクラスが Rectangle にキャストされることは「わかります」。したがって、DashO は Rectangle のすべてのサブクラスを検出し、それらを可能性がある(POSSIBLE)という信頼度で対象として選択します。

fornamedetection オプションを使用し、強制(force)モードで実行することで、検出したものを自動的に対象として選択するよう DashO に指示します。これは、DashO の決定に自信を持っている場合にのみ行ってください。

強制モードで実行すると、指定された forName() 呼び出しについて動的に読み込まれたクラスを判断できない場合でも、実行が停止しません。

<global>
    <option>fornamedetection</option>
</global>

Ignorenotfoundclasses グローバル オプション

ignorenotfoundclasses オプションは、DashO がクラスパスに存在しないクラスへの参照に遭遇した場合でも、アプリケーションを処理できるようにします。DashO は、見つからないすべてのクラスを無視できるわけではありません。スーパー クラスやスーパー インターフェイスが見つからない場合は、続行できません。

このオプションは、実行からの情報を収集できるように、DashO が終了することを可能にするための手段としてのみ使用する必要があります。すべてのクラスにアクセスせずに、必要なすべての依存関係を安全に判断することはできません。

<global>
    <option>ignorenotfoundclasses</option>
</global>

Ignorebrokencalls グローバル オプション

ignorebrokencalls オプションは、DashO が見つけることができないクラスのメソッドへの参照に遭遇した場合でも、アプリケーションを処理できるようにします。これは、クラスパス内のエラーによって、または最新のものでない jar ファイルによって発生する場合があります。DashO がクラスを処理できるとしても、クラスパスと jar に期待するクラスが含まれていることを確かめるために、それらをチェックしたいと思うでしょう。

<global>
    <option>ignorebrokencalls</option>
</global>

Force グローバル オプション

DashO は、クラスのリフレクションの使用を検出すると、リフレクション コードの場所とターゲットをメモしておき、その分析を続行します。分析の終わりに、リフレクション レポートを出力して、ビルド処理を中止します。プロジェクト内のすべてのリフレクション問題に対処したら、DashO がビルドを完了できるように、force オプションを追加することができます。forceオプションは、プロジェクト ファイルで指定するか、またはコマンド ラインの --force オプションを介して DashO に渡すことができます。難読化を UI やビルド システム統合を介して実行できるよう、.dox ファイルにこの値を設定することをお勧めします。--force は DashO コマンド ラインでのみ動作します。

メモ:

差し込まれたコードがリフレクションを使用することがあるため、このオプションなしで実行するときには差し込みを無効にする必要があるかもしれません。

<global>
    <option>force</option>
</global>

Makepublic および Nomakepublic グローバル オプション

既定では、DashO はディスクに書き込む前に、公開するすべてのクラス、非公開でないメソッド、および非公開でないフィールドのアクセス修飾子を変更します。これにはいくつかの影響があります。

  • これは、パッケージのメンバーシップを変更し、保護されたアクセス修飾子または既定の(package-private)アクセス修飾子を使用するクラスの問題を解決します。

  • 一般に、DashO はプログラムにメソッド呼び出しを組み込まないので、これは危険ではありません。結局のところ、コンパイラがコンパイル時にアクセス制限を強制します。

  • 都合よく、パブリック メソッドの動的リンクは、より制限されたアクセス レベルよりも高速です。そもそもパブリックには制限がないので、相当するパッケージやクラスのメンバーシップを検証するランタイムは必要ありません。

この動作を止めるには、nomakepublic オプションを使用します。この動作を強制するには、makepublic オプションを使用します。既定の動作を使用する、つまり、どのように動作するかを DashO に決めさせるには、どちらのオプションも含めないでください。

メモ:

nomakepublic を使用すると、クラス、メソッド、またはフィールドの保護された/既定の(package-private)アクセス修飾子でアクセス エラーが発生するかもしれません。つまり、指定されたパッケージにあったクラスは現在、名前が変更された新しいパッケージにある可能性があります。しかし、それでもまだ、アクセスの例外を引き起こす元のパッケージからパブリックでないクラス、メソッド、またはフィールドへのアクセスを試みることができます。

DashO の既定の動作は、この問題をおおむね回避しており、ほとんどのアプリケーションにとって安全と見られています。

<global>
    <option>nomakepublic</option>
</global>

Renameforname グローバル オプション

renameforname オプションは、動的に読み込んだクラスの名前を変更できるようにします。DashO がクラスを読み込むために使用される文字列を明白に判断できない場合には、そのクラスを <entrypoints> セクションに列挙する必要があります。こうしたあいまいな場合は、fornamedetection オプションが possible の信頼度で報告するものに対応します。

メモ:

コードの中で Java の assert キーワードを使ってアサーションを使用すると、クラスが内省的になります。renameforname オプションを使用しない限り、DashO はそのクラスの名前を変更不能にします。

<global>
    <option>renameforname</option>
</global>

グローバル <exclude>

exclude オプションでは、入力クラスの一部として表示されるが、DashO の最終出力に含めてはいけないクラスまたはメソッドを指定できます。グローバル exclude の正規表現に一致するクラスは、処理されず、最終出力の対象として選択されません。

たとえば、サード パーティ製の jar ファイル内に存在するテストやサンプルを対象から除外することができます。

<global>
    <exclude classname="com\.thirdparty\.tests\..*"/>
    <exclude classname="com\.thirdparty\.sample\..*"/>
</global>

メモ:除外されるクラスの名前は、常に正規表現として指定されます。

Bypassdasho グローバル オプション

bypassdasho オプションは、入力を処理しないように DashO を構成します。入力 jar ファイルとディレクトリは、直接出力にコピーされるようになります。このオプションは、出力での merge 属性が false に設定されている場合、または APK を出力する場合にのみ使用することができます。

<global>
    <option>bypassdasho</option>
</global>

<inputpath> セクション

<inputpath> セクションには、DashO が処理するクラスの場所が含まれます。DashO は、ディレクトリ、zip ファイル、および jar ファイルを処理することができます。また、location に複数のエントリを含めることができます。各エントリは、OS 固有のクラスパスの区切り文字で区切ります。

<inputpath>
    <pathelement location="c:\test\app.jar"/>
    <pathelement location="c:\test\classes"/>
    <pathelement location="c:\test\one.jar;c:\test\two.jar"/>
</inputpath>

メモ:

c:\test\classes は、パッケージ指定のどの部分にもなりません。パッケージのルート ディレクトリになります。

<globalProcessingExclude> セクション

<globalProcessingExclude> セクションには、すべての処理から除外する必要のあるクラスの場所が含まれます。これは、ControlFlow や Renaming など個々の領域の除外セクションに含めるのと同じ効果があります。

<globalProcessingExclude>
    <classes name="android**"/>
    <classes name="com.example.ExcludeMe"/>
</globalProcessingExclude>

<classpath> セクション

<classpath> セクションには、入力クラスを分析する際に DashO が必要とするかもしれないクラスの場所が含まれます。これらのクラスは、通常、サード パーティ製のパッケージであるか、または Java ランタイム環境の一部である jar ファイルです。DashO は、クラスパス内のディレクトリ、zip ファイル、および jar ファイルを処理することができます。また、location に複数のエントリを含めることができます。各エントリは、OS 固有のクラスパスの区切り文字で区切ります。

<classpath>
    <pathelement location="c:\test\app.jar"/>
    <pathelement location="c:\test\classes"/>
    <pathelement location="c:\test\one.jar;c:\test\two.jar"/>
</classpath>

メモ:

c:\test\classes は、パッケージ指定のどの部分にもなりません。パッケージのルート ディレクトリになります。

Systemclasspath 属性

任意で、<classpath> セクションで指定されたディレクトリと jar ファイルに加え、システム クラスパス を append または prepend することができます。次のオプションは、<classpath> セクションで指定されたディレクトリと jar ファイルの一覧の末尾に、システム クラスパスを追加します。

<classpath systemclasspath="append">
    <pathelement location="c:\test\classes"/></classpath>

メモ:システム クラスパスは、sun.boot.class.path プロパティと、利用可能な CLASSPATH 環境変数内の値で構成されています。

Appendrtjar 属性

既定では、DashO は、現在使用している Java のバージョンのランタイム jar ファイルを追加します。別のバージョンを使用する必要がある場合は、この動作を制御できます。

<classpath appendrtjar="false">
    <pathelement location="c:\Java\jre1.7.0_80\lib\rt.jar"/>
</classpath>

メモ:

J2ME または Android API を使用するプロジェクトでは、このオプションを使用する必要があります。このようなプロジェクトは、これら特定の環境用のランタイム jar ファイル、たとえば midpapi10.jarAndroid.jar を必要とします。

<entrypoints> セクション

エントリ ポイントとは、DashO がアプリケーションで使用されているクラスや、メソッド、およびフィールドを判断するために行う依存関係の分析の開始点です。言い換えれば、これらがアプリケーションのエントリ ポイントです。

エントリ ポイントは DashO によって分析され、クラスが機能するにはどのクラス、メソッド、およびフィールドが必要であるかを判断します。たとえば、エントリ ポイントが呼び出すすべてのメソッド、およびこれらのメソッドが呼び出す後続のメソッドは、DashO で必要であると判断されます。つまり、DashO に対して特定の Main メソッドが必要であると通知した場合は、その Main メソッドが呼び出すすべてのメソッドも必要であるということです。

<quickjar> エントリ ポイント(非推奨)

Quick Jar エントリ ポイントは、JAR ファイルにカプセル化されたプログラムや API ライブラリを難読化するために使用されることがあります。

このオプションをアプリケーションで機能させるには、JAR ファイルのマニフェストに Main-Class: {classname} 形式の行が含まれている必要があります。ここで、{classname} は、アプリケーションの開始点となる public static void main(String[] args) メソッドを持つクラスを識別します。

DashO は、静的依存関係の分析を行うために、マニフェストでこの情報を使用します。マニフェストに Main-Class 情報がない場合は、DashO は jar ファイルをライブラリとして処理します。DashO は自動的に、jar ファイル内のすべてのパブリック メソッドをエントリ ポイントとして使用します。

入力 jar には、Main-Class エントリを持つマニフェスト ファイルが含まれているものと仮定します。

Main-Class: test.MyApplication

この場合は、クラス test.MyApplication の main メソッドがエントリ ポイントと見なされます。

  • 複数の Quick Jar エントリ ポイントを指定することができます。ただし、Quick Jar エントリ ポイントを他の種類のエントリ ポイントと混在させることはできません。

  • DashO の不要コードの除去、つまり除去機能は、Quick Jar モードでは停止されており、<removal> セクションに入れた値は無視されます。

  • エントリ ポイントとして複数の Quick Jar を指定した場合、DashO は、単一の出力 jar ファイルまたはディレクトリにのみ難読化されたクラスを書き込みます。

  • 入力 jar ファイル内の非クラス ファイルはすべて、自動的に出力に含められます。

  • 制御フロー、最適化、および文字列の暗号化の対象選択と対象除外は無視されます

<entrypoints>
    <quickjar path="c:\myapp.jar"/>
</entrypoints>

メモ: Quick Jar モードの使用は現在推奨されておらず、今後の DashO のバージョンからは削除されます。

<method> および <field> エントリポイント

エントリ ポイント メソッドは、アプリケーションがどこから開始するのかを示しています。もしコードを見ていて、誰かにそのコードがどんな処理をするものかを尋ねられたら、まず最初にどこに注目するでしょうか?おそらく、そのコードに main メソッドが含まれているかどうかをチェックするでしょう。その main は、そのアプリケーションにおけるエントリー ポイント メソッドです。一般に、指定されたクラスの main を使用します。

<entrypoints>
    <classes name="test.MyApplication">
        <method name="main" signature="java.lang.String[]"/>
    </classes>
</entrypoints>

メソッドの署名を指定するときは、上記の例のように、String[] ではなく java.lang.String[] を用いて、完全修飾のクラス名を使用します。複数のパラメーターは、スペースを入れずにカンマで区切る必要があります。また、メソッド名として特別な <init> 表記法を使用すると、コンストラクターをエントリ ポイントとして指定することができます。プロジェクト ファイルは XML なので、忘れずに &lt;&gt; を使用してください。

クラス、メンバー、およびメソッドの署名の名前は、リテラル、パターン、あるいは正規表現として指定することができます。詳細については、名前:リテラル、パターン、および正規表現を参照してください。

Rename 属性

エントリ ポイントは、いくつかの外部メカニズムによって参照されているため、既定では名前を変更できません。場合によっては、エントリ ポイントの名前を変更することができます。たとえば、DashO は、名前が変更されたクラスを使って jar ファイルのマニフェストの Main-Class 属性を更新します。この場合、クラスの名前は変更できますが、main メソッドの名前は変更できません。<classes><method>、および <field> タグはすべて、項目の名前変更機能を制御する rename 属性を持っています。

<entrypoints>
    <classes name="test.OtherApplication" rename="true">
        <method name="main" signature="java.lang.String[]"/>
    </classes>
</entrypoints>

<publics> エントリ ポイント

<classes> エントリ ポイントと同様、name 属性にはリテラル、パターン、または正規表現を指定できます。ときには、クラスがアプリケーションへのインターフェイスである場合があります。そのクラスは、アプリケーションへのエントリ ポイントである多くのメソッドを含んでいるかもしれません。指定したクラスのすべてのパブリック メソッドをエントリ ポイントとして指定したい場合は、それぞれを個別に指定するか、あるいは <publics> タグを使用することができます。

<entrypoints>
    <publics name="test.MyApplet"/>
</entrypoints>

<publics> で指定されたクラスやメンバーも、rename-class および rename-members 属性を使用して、名前を変更可能にすることができます。どちらの属性も省略可能で、既定値は false です。

<entrypoints>
    <publics name="com.yoyodyne.**Bean" rename-class="true" rename-members="false"/>
</entrypoints>

<library> エントリ ポイント

API ライブラリでは、library オプションを使用することにより、ディレクトリまたは jar ファイル内のすべてのクラスのすべてのパブリック メソッドおよび保護されたメソッドを指定できます。

<entrypoints>
    <library public="off">
        <dir path="myAPIDirectory"/>
    </library>
</entrypoints>

メモ:

ディレクトリまたは jar ファイルをライブラリとして追加する場合は、それを <classpath> に追加する必要はありません。DashO はこれを自動的に行います。

<entrypoints>
    <library public="off">
        <jar path="myAPI.jar"/>
    </library>
</entrypoints>

public の値は on または off になります。省略した場合は、on と見なされます。

myAPIDirectory 下にあるすべてのディレクトリの、再帰下降によって見つかったすべてのクラスの全パブリック メソッドは、トリガーとして使用されます。myAPIDirectory は、パッケージ指定の一部であってはなりません。それは、パッケージが存在するディレクトリになるということです。つまり、クラスパスに置くものと同じディレクトリになります。jar ファイルを使用すると簡単です。jar で見つかったすべてのクラスが使用されます。path 値に示す場所には、複数のエントリを含めることができます。それぞれは OS 固有のクラスパスの区切り文字で区切ります。

パブリック メソッドのみをエントリ ポイントとして使用したい場合は、library タグの publicon に設定して使用します。

<classes> エントリ ポイント

含まれるメソッドをあれこれ推測せずにクラスを対象として選択することも可能です。一部のアプリケーションを正確にパッケージ化するために、ここに手動でクラスを指定することは極めて重要です。アプリケーションで Class.forName() コンストラクトを使用している場合、DashO は必要とされる可能性のあるすべてのクラスを判断することができません。このような場合、DashO は forName(s) の場所を知らせて、終了します。その後、手動でここにそれらのクラスを入力し、force オプションを設定して DashO を再実行する必要があります。ここで指定されたすべてのクラスは、メソッドおよびフィールドの除去に利用できます。

<entrypoints>
    <classes name="com.yoyodyne.Application"/>
</entrypoints>

これにより、DashO は com.yoyodyne.Application を読み込むようになりますが、どのメソッド、フィールドもエントリ ポイントとして使用しなくなります。そのクラスがシステム メソッドやユーザーが作成した他のメソッドをオーバーライドする場合は、クラスのメソッドも対象として選択されます。この方法で入力されたクラスは、グローバル renameforname オプションがオンになっている場合には、名前を変更可能になります。

<unconditional> エントリ ポイント

ときには、他のクラスから明示的に参照されていないクラスであっても、対象として選択する必要が生じることがあります。これは無条件のエントリ ポイントを介して行われます。この場合は、クラスのすべてンのメンバーがエントリ ポイントとして使用され、出力に現れます。他のエントリ ポイントと同様、name 属性にはリテラル、パターン、または正規表現を指定できます。既定で、クラスとメンバーの名前は変更不能ですが、rename-class および rename-members 属性を使用することにより、名前を変更可能にすることができます。

特殊なアプリケーションのエントリ ポイント

DashO には、いくつかの異なる型の Java アプリケーション構成が組み込まれています。便宜上、DashO は、これらのアプリケーションのうちの一部について、エントリ ポイントを指定するための特別な構文を定義しています。名前は、リテラル、パターン、または正規表現として指定できます。名前:リテラル、パターン、および正規表現を参照してください。既定で、クラスとメンバーの名前は変更不能です。すべての種類が rename-class 属性を使用し、一部の種類が rename-members 属性をサポートしています。

<applets>

アプレットの init() および paint() メソッドは特に、自動的に対象として選択されます。アプレットがオーバーライドするすべてのメソッドは、自動的にエントリ ポイントになります。しかし、どのようなアプレット クラスがエントリ ポイント クラスであるかについて、完全な形式の指示を指定する必要があります。

<entrypoints>
    <applet name="test.MyApplet"/>
</entrypoints>

<applets> タグでは、rename-class 属性(既定で false)は使用しますが、rename-members 属性は使用しません。つまり、エントリ ポイント メンバーはインターフェイスによって定義されており、名前を変更できません。クラス内の他のメソッドは名前を変更できます。

<servlets>

サーブレットのエントリ ポイントは次のように指定することができます。

<entrypoints>
    <servlet name="test.MyServlet"/>
</entrypoints>

<servlets> タグでは、rename-class 属性(既定で false)は使用しますが、rename-members 属性は使用しません。つまり、エントリ ポイント メンバーは基本クラスによって定義されており、名前を変更できません。クラス内の他のメソッドは名前を変更できます。

<ejb> Enterprise Java Beans

Enterprise Java Beans は、特定の EJB に関連するクラスを指定するための独自の表記法を持っています。

<entrypoints>
    <ejb name="MyEntityBean"/>
    <ejb name="MyRemoteInterface"/>
    <ejb name="MyHomeInterface"/>
    <ejb name="MySessionBean"/>
    <ejb name="MyPrimaryKey"/>
</entrypoints>

<ejb> タグは、rename-class 属性(既定で false)と rename-members 属性(既定で false)の両方を使用します。

メモ:

もう 1 つの方法として、EJB ではそれらのエントリ ポイントを指定するために <publics> 表記を使用することができます。

<midlet> と <iappli>

DashO は、Mobile Information Device Profile(MIDP)仕様(MIDlet)で書かれたアプリケーションの明示的なサポートを提供しています。midlet クラスは、依存関係の任意のレベルで javax.microedition.midlet.Midlet のサブクラスにすることができます。

<entrypoints>
    <midlet name="test.MyMidlet"/>
</entrypoints>

同様に、DashO は、NTT ドコモの iアプリ フレームワーク用に書かれたアプリケーションも明示的にサポートしています。iappli クラスは、依存関係の任意のレベルで com.nttdocomo.ui.IApplication のサブクラスにすることができます。

<entrypoints>
    <iappli name="test.MyIappli"/>
</entrypoints>

タグは両方とも、rename-class 属性(既定で false)は使用しますが、rename-members 属性は使用しません。エントリ ポイント メンバーは基本クラスによって定義されており、名前を変更できません。クラス内の他のメソッドは名前を変更できます。

MIDlet プロジェクトの構成

Java ランタイム Jar を含めないでください。Appendrtjar 属性 セクションを参照してください。代わりに、環境変数またはプロパティが Oracle の Wireless Toolkit のインストールを指すように設定します。

メモ:WTK_HOME セットアップと呼ばれる環境変数がある場合は、それを直接使用するか、またはその設定を使用する DashO プロパティを作成することができます。

<propertylist>
    <!-- To force the environment variable to be set -->
    <property name="wtk.home" value="${WTK_HOME:?WTK_HOME not defined}"/>
    <!-- To use a default if not set -->
    <property name="wtk.home" value="${WTK_HOME:-C:\WTK2.5.1}"/>
</propertylist>

クラスパスに cldcapimidpapi の jar を追加します。これらの jar ファイルは、Oracle の Wireless Toolkit の一部です。

<classpath>
    <jar path="${wtk.home}/lib/cldcapi10.jar"/>
    <jar path="${wtk.home}/lib/midpapi10.jar"/>
</classpath>

プロジェクトの事前検証を設定します。

<preverifier run="true">
    ${wtk.home}/bin/preverify.exe
</preverifier>

<android>

DashO は、android クラスのサポートを提供しています。クラスは、android.app.Applicationandroid.app.Activityandroid.app.Serviceandroid.content.BroadcastReceiver、または android.content.ContentProvider のサブクラスにすることができます。エントリ ポイントは、AndroidManifest.xml に挙げられているクラスです。名前の変更は、アプリケーションの外部で参照されないクラスについてのみ行われるべきです。

<entrypoints>
    <android name="com.example.myApp.MyActivity"/>
    <android name="com.example.myApp.MyIntActivity" rename-class="true"/>
</entrypoints>

<android> タグは、rename-class 属性(既定で false)と rename-members 属性(既定で true)の両方を使用します。

<springbean>

DashO は Spring Beans をサポートしています。これらは、beans.xml ファイルで参照されるクラスになります。他の特殊クラスには存在しない、<springbean> でサポートされる追加属性があります。

  • entrypoints – 以下のような属性の bean 定義で使用される、メソッド名のカンマ区切りの一覧。

    • init-method – bean を作成した後に Spring フレームワークによって呼び出されるメソッド。

    • destroy-method – bean を破棄する前に Spring フレームワークによって呼び出されるメソッド。

    • factory-method – bean をインスタンス化するときに Spring フレームワークによって呼び出されるメソッド。

  • renamePropertyMethodsTrue/False(既定で false):プロパティ メソッドの名前を変更します:get*()set*(*)、および is*()(および、これらのメソッドで表されるフィールド)。

  • renameEntryPointsTrue/False(既定で false):entrypoints 下に挙げられているエントリ ポイント メソッドの名前を変更します。

<entrypoints>
    <springbean name="com.example.spring.beans.MyBean"
        entrypoints="initBean,destroyBean,createBeanOne,createBeanTwo"
        rename-class="false" renamePropertyMethods="true" renameEntryPoints="true"/>
</entrypoints>

<springbean> タグは、rename-class 属性(既定で true)と rename-members 属性(既定で true)の両方を使用します。これら bean のパブリック コンストラクターはすべて保持されます。

<report> セクション

レポート ファイルが指定されている場合は、DashO は除去されたすべてのメソッドとフィールドを示すレポートを作成します。またレポートには、全体のメソッド、フィールド、および定数プール エントリの除去を含む、プロジェクト全体の総数がまとめられています。

<report path="c:\output\dasho-report.txt"/>

Quick Jar モードには除去がないため、レポート ファイルの生成もありません。警告とエラーはコンソールに渡されます。

レポートからの抜粋は次のようになります。

Removal Option : Remove all unused

Dependency Report for Entry Points:
GifWiz.Editor.main(java.lang.String[])
------------------------------------------------------------------------

gifwiz.ConsoleMessage
========================================================================
Removable Method display()
Removable Method outline(int)
Removable Field n
Removable Field z1

gifWiz.Arc
========================================================================
Removable Method round(double)
Removable Method update_scp()
Removable Method update_scp(int)
Removable Method corners()
Removable Field ccw
Removable Field cw
Removable Field dalpha21
Removable Field dalpha10

各 Removable メソッドは、プログラムの実行において不必要であると DashO が判断したものです。

DashO は、実行に関して要約した結果も出力します。

Statistics In Out Change
========================================================================
Classes 612 596 -2.6%
Methods 8975 7095 -20.9%
Fields 4953 2792 -43.6%
Constants 103306 90756 -21.9%

Processing Time: 4:46.977 min

この DashO の実行で、すべてのメソッドのほぼ 21% 近くを除去することができました。しかし、これはアプリケーションのサイズが 21% 縮小されたというわけではありません。除去されたメソッドのパーセンテージは、アプリケーションのサイズのわずか 1% かもしれません。

<output> セクション

<output> タグは、DashO で出力をディレクトリ、jar ファイル、または APK ファイルへ書き込むようにするかどうかを示します。出力の形式は、名前の変更オプションに依存します。また、複数の結果を 1 つの出力にまとめるか、入力と同じパッケージを保持するかどうかを制御します。名前の変更を指定しない場合は、現在存在するディレクトリ/パッケージ構造は指定されたディレクトリに再作成されるので、出力先がソースと同じにならないようにしてください。名前を変更する場合は、パッケージの概念を削除することができ、すべてのクラスが指定されたディレクトリに置かれます。

<output merge="true">
    <dir path="c:\output\"/>
</output>

任意で、jar ファイルの出力で manifest を指定することができます。DashO は、出力 jar ファイルにマニフェスト ファイルをコピーします。マニフェストの jar ファイルを指定した場合は、それがマニフェストのソースとして使用されます。

<output merge="true">
    <jar path="c:\output\dashoed.jar" manifest="c:\misc\Manifest.mf"/>
</output>

APK に出力する場合は、入力として APK を持っている必要があります。APK を整列させるかどうかを指定することができます。これは、APK も署名されている場合にのみ、true に設定する必要があります。

<output zipAlign="true">
    <apk path="c:\output\myApp.apk"/>
</output>

メモ:

pathmanifest の両方の属性は、プロパティをサポートしています。

Jar 属性

DashO が <jar> タグを使用して 1 つ以上の jar ファイルを作成する場合、あるいは merge=false である場合には、jar ファイルの作成をカスタマイズする属性を指定することができます。

  • compress="boolean" – jar ファイル内のエントリを圧縮するかどうかを決定します。既定値は true です。

  • level="0-9" – jar ファイルのエントリの圧縮レベル。既定値は 6 です。値が大きいほど、より高い圧縮率を与えます。

  • filesonly="boolean" – jar に含めるエントリを、ファイルのみとするか、フィールドとディレクトリの両方とするかどうかを決定します。既定値は true です。

  • includenonclassjars="boolean" – 残りのクラスが何も含まれていない jar ファイルを出力に含める必要があるかどうかを決定します。既定値は false です。

<output merge="false" compress="true" level="4" filesonly="false">
    <dir path="c:\output\"/>
</output>

このサンプルでは、ファイルとそのディレクトリ構造の両方のエントリを含む jar ファイルが、中程度の圧縮レベルで生成されます。

APK 属性

DashO で <apk> タグを使用して APK を作成する場合には、APK を整列させる必要があるかどうかを指定できます。

  • zipAlign="boolean" – zipalign を使用して、APK を整列させる必要があるかどうかを決定します。既定値は false です。これは、APK も署名されている場合にのみ、true に設定する必要があります。

Merge 属性

DashO は、難読化された結果を結合して単一のディレクトリまたは jar に入れるか、または入力クラスの元のパッケージを保持することができます。この動作は、<output> タグの merge 属性を使用して制御されます。merge 属性の値は、true または false です。merge 属性が指定されていない場合は、既定値の true になります。

merge="true"

これが DashO の既定のモードです。merge="true" の場合は、<dir path="..."/> または <jar path="..."/> のいずれかを出力に使用できます。DashO は、難読化されたすべてのクラスを結合して、指示された jar ファイルまたは出力ディレクトリへ入れます。

merge="false"

merge="false" が指定された場合は、<dir path="..."/> のみ出力に使用できます。DashO は、出力ディレクトリに入力クラスの元のパッケージを保持します。jar ファイルによってもたらされるクラスは、出力ディレクトリの同じ名前の jar ファイルに配置されます。また、jar ファイルによってもたらされるマニフェスト ファイルと非クラス ファイルは、難読化された jar ファイルにコピーされます。ディレクトリによってもたらされるクラスは、出力ディレクトリ内のサブディレクトリに配置されます。DashO は、共通のルートの場所を基とする、jar ファイルとディレクトリ間の相対パスを保持しようとします。この設定は、<dir> 出力および <jar> 出力にのみ適用されます。

メモ:

merge="false" オプションには <dir path="..."/> タグが必須です。<jar path="…"/> タグが指定されている場合は、merge="false" の設定は無視されます。Quick Jar モードでは、必ずマージが実行されます。

Autocopy 属性

merge="false" が指定されている場合は、autocopy 属性も指定することができます。autocopy="true" が指定されている場合、入力 jar ファイル内の非クラス ファイルは、自動的にそれぞれの出力にコピーされます。入力ディレクトリに現れる非クラス ファイルがコピーされることはありません。この設定は、<dir> 出力にのみ適用されます。

<output merge="false" autocopy="true">
    <dir path="obfuscated"/>
</output>

<constpooltag>

クラス ファイルをマークするために、それ用の定数プール エントリを隠れた状態で追加することができます。この文字列は、DashO が出力するすべてのクラスに配置されますが、一時的ユーザーに対し印刷物にして公表されることはなく、明らかにされません。クラスの逆アセンブル ツールを使用するものだけが、この文字列を見ることができます。value 属性には、クラスの動的プロパティを含む、プロパティ参照を含めることができます。

<output>
    <constpooltag value="Copyright 1984 Yoyodyne Engineering, Inc."/>
</output>

メモ:

値はカスタム クラス属性として参照されるため、予約されている属性名を指定することはできません。

<sourcefile>

このタグでは、スタック トレースで使用される Java の SourceFile 属性の値を設定できます。value 属性には、クラスの動的プロパティを含む、プロパティ参照を含めることができます。

<output>
    <sourcefile value="${CLASS_SIMPLENAME}-v${ver}"/>
</output>

<removal> セクション

<removal> オプションでは、クラス、メソッド、およびフィールドの除去や、メタデータの除去に使用する精度のレベルを指定できます。クラスとメンバーの除去については、タグに 2 つの属性 classesmembers があります。これらのオプションは次のとおりです。

  • none – 除去しない

  • unused-non-public – 使用されていない項目で、パブリックでないものだけを除去する

  • unused – 使用されていないすべての項目を除去する

属性が 2 つとも省略されているか、<removal> が指定されていない場合には、除去は行われません。

本当のアプリケーション(他のクラスからサブクラスに指定されたり、呼び出されたりするものではない)をパッケージ化している場合は、unused オプションが最良の選択です。

使用するサード パーティ製の API ライブラリに付属する使用許諾契約書に従って、アプリケーションが必要とするすべてのクラスを DashO に組み込めるようにすることが最良の方法です。そのように、結果として生じる出力は、アプリケーションが具体的にそれをどのように使用するかに合わせ、アプリケーションが必要とするすべてのクラスを含む 1 つの jar ファイルまたはディレクトリになります。

removal は <excludelist> 要素をサポートしています。この要素には、除去されないクラス、メソッド、およびフィールドを選択する規則を含めることができます。この要素については、<includelist> および <excludelist> 規則セクションで説明します。

<removal classes="unused-non-public" members="unused"/>

メモ:

除去は、Quick Jar モードではオフになっています。Quick Jar モードは、removal セクションで設定されたオプションをすべて無視します。

<debug> セクション

このセクションは、コンパイラによってクラス ファイルに挿入されたデバッグ情報を削除するよう DashO に指示します。type 属性は、削除する情報の種類を指定するために使用されます。次の種類を削除することができます。

  • SourceFile – クラスがコンパイルされたソース ファイルの名前。

  • SourceDirectory – クラスがコンパイルされたソース ファイルの場所。

  • SourceDebugExtension – 拡張デバッグ情報として解釈されるツール特有の文字列。

  • LineNumberTable – 元のソース ファイル内の特定の行番号に割り当てられるバイト コード。デバッガーとスタック トレースによって使用されます。

  • LocalVariables – メソッドの実行中にローカル変数の名前と型を判断するために、デバッガーによって使用されます。

  • LocalVariableTypes – ジェネリックを使用するローカル変数の署名。

複数の項目はスペースで区切られます。

2 つの特別なキーワードもサポートされます。

  • All – デバッグ情報はすべて削除されます。

  • None – デバッグ情報は何も削除されません。

<debug> セクションが存在しない場合は、すべてのデバッグ情報が保持されます。セクションはあっても type 属性が存在しない場合は、すべてのデバッグ情報が削除されます。

<debug/>
<debug types="None" />
<debug types="SourceDirectory SourceDebugExtension" />

メモ:

制御フローの難読化の変換処理では、 セクションでローカル変数情報の削除を要求していない場合でも、それらの削除を必要とします。

<attributes> セクション

コンパイラは、クラス ファイル内の属性に追加のメタデータを格納します。DashO では、これらの属性の処分(ディスポジション)を個別に決定することができます。タグの type 属性は、削除する属性の種類を指定するために使用されます。次の種類を削除することができます。

  • Exceptions – メソッドがスローする、チェックされた例外を示します。

  • Signature – ジェネリック型、ジェネリックを含むメソッド宣言、およびパラメーター化された型を示します。

  • Deprecated – クラス、インターフェイス、メソッド、またはフィールドが置き換えられていることを示します。

  • Synthetic – ソース コードに現れないクラス メンバーを示します。

  • EnclosingMethod – ローカル クラスまたは匿名クラスを囲む方法を示します。

  • RuntimeVisibleAnnotations – クラス、メソッド、またはフィールドの、リフレクションで見ることができるアノテーションを保持します(例:@Deprecated@FunctionalInterface、および @SafeVarargs

  • RuntimeInvisibleAnnotations – クラス、メソッド、またはフィールドの、リフレクションで見ることができないアノテーションを保持します。

  • RuntimeVisibleParameterAnnotations – メソッドに対するパラメーターの、リフレクションで見ることができるアノテーションを保持します。

  • RuntimeInvisibleParameterAnnotations – メソッドに対するパラメーターの、リフレクションで見ることができないアノテーションを保持します。

  • AnnotationDefault – アノテーション要素の既定値。

  • InnerClasses – 内部クラスと外部クラス間の関係を示します。

  • Unknown – その他すべての属性の種類(MethodParameters 属性を含む)。

複数の項目はスペースで区切られます。

2 つの特別なキーワードもサポートされます。

  • All – 属性はすべて削除されます。

  • None – 属性は何も削除されません。

<attributes> セクションが存在しない場合は、すべての属性が保持されます。セクションはあっても type 属性が存在しない場合は、次の属性が削除されます:DeprecatedSyntheticRuntimeInvisibleAnnotations、および RuntimeInvisibleParameterAnnotations

<attributes/>
<attributes types="All" />
<attributes types="Deprecated Synthetic" />

メモ:

TypeAnnotations 属性は常に削除されます。これはハードコードされていて構成することができません。

<methodCallRemoval> セクション

DashO では、戻り値の型が void であるメソッドの呼び出しを除去することができます。これにより、製品コードからログやコンソール出力の呼び出しを簡単に除去できるようになります。<methodCallRemoval> 要素の属性はありません。すべての構成は、<method> サブ要素に含まれています。

<method> セクション

このセクションは、出力で呼び出してはいけないメソッドを定義します。

このタグの属性は、クラス名、メソッド名、および署名によって呼び出さないメソッドを識別します。

  • className – この string 属性は、メソッドを含んでいるクラスの名前を指定します。

  • methodName – この string 属性は、メソッドの名前を指定します。

  • signature – この string 属性は、メソッドのパラメーターを指定します。

className 属性

className 文字列属性には、メソッドを含んでいるパッケージとクラスの完全な名前が含まれています。このクラスのメソッドに対する直接の呼び出しのみが除去されます。サブクラスにある同じメソッド名や署名に対する呼び出しは除去されません。** のクラス名を指定することで、DashO に対し、どのクラスがメソッドを含んでいるかに関係なく、メソッドおよび署名のすべての呼び出しを除去するように指示できます。** を使用する場合は、それらのメソッドの名前が変更されないように、名前の変更の対象除外規則を追加する必要があります。

methodName 属性

methodName 文字列属性には、メソッドの名前が含まれます。初期化メソッドまたはコンストラクター メソッドは指定できず、また void を返すメソッドでなければなりません。

signature 属性

signature 文字列属性には、メソッドのパラメーターの型が含まれます。パラメーターは、順序正しく、カンマで区切って指定する必要があります。型名の後に次元を表す [] を追加することにより、配列パラメーターが指定されます。オブジェクト型のパラメーターを入力する場合は、完全なパスを使用する必要があります。また、大文字と小文字やスペルは正確である必要があります。"double" を "doubel" と間違って入力すると、そのパラメーターはプリミティブの double 型ではなく、"doubel" という名前の Object として扱われてしまいます。

<methodCallRemoval>
    <method className="**" methodName="method1" signature="java.lang.String"/>
    <method className="com.example.methodCallRemoval.SubSubClassOne"
        methodName="method2" signature="java.lang.String, int, double,
        float[][]"/>
</methodCallRemoval>

<renaming> セクション

DashO は、クラス、メソッド、およびフィールドの名前を短い意味のない名前に変更することができます。これは、クラスのサイズの縮小にとって、また難読化技法として重要です。後述のセクションを使用すると、名前の変更対象から特定のクラスやメンバーを除外することができます。

メモ:

DashO の名前の変更アルゴリズムとその影響については、高度なトピックを参照してください。

次のタグは、option 属性とアノテーションの名前の変更を使用して、名前の変更のグローバル制御を可能にしています。有効な値は onoff です。

<renaming option="on" renameAnnotations="on"/>

<class-options> セクション

このタグの属性は、クラスの名前の変更を制御します。

  • rename – この boolean オプションは、クラスの名前の変更をオンまたはオフにします。false の場合は、クラスは元の名前を保持します。

  • keeppackages – この boolean オプションは、元のパッケージの名前と階層を保持したまま、クラス自体の名前を変更できるようにします。

  • alphabet – 新しいクラス名を作成するために使用される文字を定義する文字列。

  • minlength – 新しいクラス名の最小の長さ。

  • randomize – クラスの新しい名前は、順次的またはランダムに割り当てることができます。このオプションが true の場合、識別子はランダムに割り当てられます。

  • prefix – この属性は、名前が変更されたすべてのクラスに付加されるプレフィックスを指定します。プレフィックスにピリオドを含めると、クラスは効果的に新しいパッケージに配置されます。

prefix 属性

プレフィックスは、名前が変更されたすべてのクラスに付加されます。ピリオドを含む prefix を定義することにより、名前が変更されたクラスをカスタム パッケージに入れることができます。

<renaming option="on"/>
    <class-options prefix="pkg.X_"/>
</renaming>

次の表は、プレフィックスを使った名前の変更の可能性を示しています。

プレフィックス 変更後の名前
C Ca
pkg. pkg.a
pkg.X_ pkg.X_a
keeppackage 属性

このオプションが true の場合、クラスの名前は変更されますが、その名前のパッケージの部分は変更されません。

<renaming option="on"/>
    <class-options keeppackages="true"/>
</renaming>

以下に、このような名前の変更の例を示します。

元の名前 変更後の名前
yoyodyne.application.Main yoyodyne.application.a
yoyodyne.application.LoadData yoyodyne.application.b
yoyodyne.tools.BinaryTree yoyodyne.tools.c
yoyodyne.tools.LinkedList yoyodyne.tools.d

prefix と併せて使用した場合、元のパッケージ名は、prefix によって加えられる部分より前に現れます。

<renaming option="on"/>
    <class-options keeppackages="true" prefix="x_"/>
</renaming>

これは次のような結果になります。

元の名前 変更後の名前
yoyodyne.application.Main yoyodyne.application.x_a
yoyodyne.application.LoadData yoyodyne.application.x_b
yoyodyne.tools.BinaryTree yoyodyne.tools.sub.x_c
yoyodyne.tools.LinkedList yoyodyne.tools.sub.x_d
alphabet 属性

省略可能な alphabet 属性では、新しいクラス名を作成するために使用される文字を定義します。省略すると、既定の文字集合が使用されます。文字集合を定義する際は、次の制限が適用されます。

  • 文字集合の最小の長さは 2 文字です。大きなプロジェクトに対しては、3 文字以上が推奨されます。

  • 文字集合の初めの文字は、Java 識別子の開始文字として有効でなければなりません。少なくとも 1 つは開始文字がある必要があります。

  • 文字集合の残りの文字は、Java 識別子で有効な文字でなければなりません。

<member-options> セクション

このセクションは、メソッドとフィールドの名前の変更を制御します。

  • keeppublics – true に設定すると、すべてのパブリック メソッドおよびフィールドは、元の名前を保持します。<entrypoints> セクション library オプションでは、すべてのパブリック メソッドを、本質的に元の名前を保持するエントリ ポイントとして扱います。このオプションを指定すると冗長になります。

  • alphabet – 新しいメンバー名を作成するために使用される文字を定義する文字列。使い方は、<class-options> タグの alphabet 属性の場合と同じです。

  • minlength – 新しいメンバー名の最小の長さ。

  • randomize – メンバーの新しい名前は、順次的またはランダムに割り当てることができます。このオプションが true の場合、識別子はランダムに割り当てられます。

<renaming> の対象除外リスト

このセクションは、入力クラス ファイルの名前変更を動的に微調整する方法を提供します。このセクションには、実行時に適用される "対象除外規則" のリストを含めることができます。規則で特定のクラス、メソッド、またはフィールドを選択した場合、その項目の名前は変更されません。

メモ:

これらの規則は、エントリ ポイントによって定義される名前の変更の制限と併せて適用されます。

各規則は論理的に OR で結合されます。つまり、1 つでも規則にマッチした項目の名前は変更されません。<excludelist> は、クラス、メソッド、およびフィールドによる名前の除外をサポートしています。

<renaming option="on">
    <excludelist>
        <classes name="samples.SimpleApp" excludeclass="true"/>
    </excludelist>
</renaming>

<mapreport> セクション

DashO は、実行したすべての名前の変更のレポートだけでなく、名前が変更された結果に関する統計情報も生成することができます。これは、入れ子になった <mapreport> タグを使用して作成されます。

<renaming option="on">
    <mapping>
        <mapreport path="c:\workproject-mapreport.txt"/>
        </mapping>
</renaming>

メモ:

path 属性はプロパティをサポートします。

リストの例は次のとおりです。

one.A (b)
========================================================================
a pub1(int)
b def1(int)
c pub2(int)

two.B (c)
========================================================================
a pub1(int)
b pub2(int)
c def1(int)

クラスとメソッドの新しい名前が示されています。名前を変更した後は、バグの追跡が困難になります。特に、メソッドのオーバーロードが非常に高い確率で発生するので、割り当てファイルが不可欠になります。また、割り当てファイルは、オーバーロード誘導の結果に関する統計を提供します。

Number of Methods : 7095
Renamed to ’a’ : 2031 (28.6%)
Renamed to ’b’ : 786 (11.0%)
Renamed to ’c’ : 484 (6.8%)
Renamed to ’d’ : 327 (4.6%)
Renamed to ’e’ : 230 (3.2%)
Renamed to ’f’ : 169 (2.4%)
Renamed to ’g’ : 131 (1.8%)
Renamed to ’h’ : 120 (1.7%)
Renamed to ’i’ : 106 (1.5%)

これらの統計は、それぞれ与えられた名前に変更されたメソッドの総数を表しています。

<mapoutput> セクション

<mapoutput> ファイル オプションを指定することで、DashO の名前の変更機能に対し、名前の変更がどのように行われたかを追跡記録するよう指示できます。その結果、ユーザーは名前の変更状況をすぐに調査できるほか、今後 DashO を実行する際に入力として使用することができます。このオプションで作成されるファイルは、増分難読化難読化されたスタック トレースのデコードを実行する際の、入力割り当てファイルとして使用されます。

このファイルを不注意で失ってしまうと、将来のアプリケーションの増分更新の機会を失う可能性があります。そのため、このファイルを適切にバックアップしておくことが非常に重要になります。このような理由から、DashO は既存のファイルが検出された場合には、自動的にこのファイルを上書きしないようになっています。

属性 overwrite="true" は、既存ファイルの上書きを可能にするよう DashO に指示します。

メモ:

overwrite 属性は省略可能で、省略すると、既定値の false になります。

<renaming option="on">
    <mapping>
        <mapoutput path="c:\work\project.map" overwrite="true"/>
    </mapping>
</renaming>

<mapinput> セクション

<mapinput> オプションで作成されるファイルは、増分入力ファイル オプションで使用することができます。

<renaming option="on">
    <mapping>
        <mapinput path="c:\work\project.map"/>
    </mapping>
</renaming>
Suffix 属性

mapinput には、増分難読化全体にわたって変更を追跡するために直ちに利用できる、任意の suffix オプションがあります(つまり、suffix には、日付や何かほかの識別文字列を指定できます)。

<renaming option="on">
    <mapping>
        <mapinput suffix="new">
            <file path="c:\work\project.map"/>
        </mapinput>
    </mapping>
</renaming>

<optimization> セクション

<optimization> セクションでは、項目を対象として選択したり、対象から除外したりするための詳細な規則など、バイト コードの最適化に固有のオプションを指定できます。option 属性が off に設定されている場合は、セクションの残りの部分の内容に関係なく、DashO は最適化をまったく行いません。

<optimization option="on"/>

最適化を行う場所を微調整するために、 セクションに の両方を含めて、クラスとメソッドを選択する規則を含むことができます。これらについては、<includelist> および <excludelist> 規則セクションで説明します。

<optimization option="on">
    <includelist>
        <classes name="samples.**"/>
    </includelist>
    <excludelist>
        <classes name="samples.SimpleApp"/>
    </excludelist>
</optimization>

メモ:

Quick Jar モードは、<optimization> セクション内のすべての対象選択および対象除外を無視します。

<controlflow> セクション

<controlflow> セクションでは、ユーザーは項目を対象として選択したり、対象から除外したりするための詳細な規則など、制御フローの難読化に固有のオプションを指定できます。option 属性が off に設定されている場合は、セクションの残りの部分の内容に関係なく、DashO は制御フローの難読化をまったく行いません。tryCatch 属性が設定されていない、または on に設定されている場合は、逆コンパイラをさらに混乱させるために追加の例外ハンドラーがコードに追加されます。catchHandlers 属性は、メソッドに追加する例外ハンドラーの最大数を決定します。

<controlflow option="on" tryCatch="on" catchHandlers="1" />

制御フローの難読化は Java コードの保護レベルを上げますが、ときどきこの変換処理は強力に作用して、パフォーマンスに影響を及ぼすことがあります。制御フローの難読化を行う場所を微調整するために、<controlflow> タグに <includelist><excludelist> の両方を含めて、クラスとメソッドを選択する規則を含むことができます。これらについては、<includelist> および <excludelist> 規則セクションで説明します。

<controlflow option="on">
    <excludelist>
        <classes name="SimpleApp"/>
    </excludelist>
</controlflow>

メモ:

Quick Jar モードは、 セクション内のすべての対象選択および対象除外を無視します。

<stringencrypt> セクション

<stringencrypt> セクションでは、ユーザーは項目を対象として選択したり、対象から除外したりするための詳細な規則など、文字列の暗号化に固有のオプションを指定できます。option 属性が off に設定されている場合は、セクションの残りの部分の内容に関係なく、DashO は文字列の暗号化をまったく行いません。

<stringencrypt option="on"/>

文字列の暗号化は、単純な文字列検索によってプログラムの重要な部分を見つけることをもっと困難にすることで、コードの調査を妨害します。しかし、実行時に文字列を復号することは、パフォーマンスにいくらか負荷をかけます。文字列が暗号化される場所を微調整するために、<stringencrypt> タグに <includelist><excludelist> の両方を含めて、クラスとメソッドを選択する規則を含むことができます。これらについては、<includelist> および <excludelist> 規則セクションで説明します。このセクションには、<seInput> および <seOutput> を含むこともできます。これらについては、<seInput> および <seOutput> セクションで説明します。

<stringencrypt option="on">
    <includelist>
        <classes name="com.yoyodyne.**"/>
    </includelist>
    <excludelist>
        <classes name="com.yoyodyne.ui.**"/>
    </excludelist>
</stringencrypt>

メモ:

Quick Jar モードは、<stringencrypt> セクション内のすべての対象選択および対象除外を無視します。

level 属性と implementations 属性

level および implementations 属性を使用すると、文字列の暗号化プロセスの複雑さを高めることができます。level の値は、単純だけれど高速な復号を用いる 1 から、アプリケーションの一部の速度を落とす可能性がある複雑な実装の 10 までです。level の既定値は 2 です。値が増えるに従って、文字列値の逆コンパイルやリバース エンジニアリングの複雑さを高めるために、入り交じった表現法が用いられます。また、より大きな値にすると、復号メソッドの実装にランダム度が導入されて、バイト コード パターンによって文字列値を見つけることがさらに困難になります。

implementations 属性は、一意の復号メソッドをいくつ生成して、入力内のクラスに追加するかを決定します。メソッドの名前と署名はランダムに選択されます。復号メソッドは、アプリケーション サイズの増加を最小限に抑えるために、最も短い名前が付けられたクラスに置かれます。名前の長さが同じクラスについては、より多くのメソッドを含んでいるか、より複雑さを備えたクラスが最初に選択されます。最大 10 個まで実装を追加できます。implementations の既定値は 2 です。

<stringencrypt option="on" level="3" implementations="4">

<decrypter> セクション

<decrypter> セクションでは、実行時に文字列を復号するために使用されるメソッドを DashO がどこに置くかを制御できます。このタグは、<includelist> および <excludelist> 規則 で使用される <classes> タグに似ています。

このセクションで選択されたクラスは、生成された静的な匿名内部クラスの外部クラスとして使用され、復号メソッドが格納されます。

<decrypter> 要素には、外部クラスを選択する 4 つの属性があります。

  • name – クラスの名前。これは、クラスの名前、複数のクラスを選択するパターン、または正規表現を指定できます。

  • regex – name 属性の解釈を決定します。true の場合、name は正規表現です。

  • modifiers – クラスを選択するために使用される修飾子。詳細については、Modifiers 属性を参照してください。

  • excludedPackages – decrypter クラスに置くことから除外されるパッケージのカンマ区切りの一覧。既定のルート パッケージの名前は、java、javax、および android です。

<decrypter> セクションを省略すると、DashO は自動的に場所を決定します。

<decrypter modifiers="static class" name="com.yoyodyne.**"/>

<seInput> セクション

<seInput> セクションは、前回の実行における文字列の decrypter が記述されているファイルを保持します。これは、増分難読化時に使用されます。

<seInput path="c:\example_project\prev_project-se.map" />

<seOutput> セクション

<seOutput> セクションは、現在の実行における文字列の decrypter に関する情報を格納するためのファイルを保持します。このファイルが存在する場合は、上書きされます。

<seOutput path="c:\example_project\project-se.map" />

<customEncryption> セクション

<customEncryption> セクションは、カスタムの暗号化メソッドおよび復号メソッドの使用に関する情報を保持します。

  • useCustomEncryption – カスタム暗号化を使用する必要があるかどうかを設定します(true/false)。

  • encryptionJar – カスタム暗号化のクラスおよびメソッドを含んでいる jar ファイルへのパス。

  • encryptionClass – カスタム暗号化メソッドを実装するクラスの完全な名前。

  • encryptionMethod – 文字列を暗号化するために使用されるメソッドの名前。

  • decryptionClass – カスタム復号メソッドを実装するクラスの完全な名前。

  • decryptionMethod – 文字列を復号するために使用されるメソッドの名前。

また、カスタム暗号化の使用対象となるクラスおよびメソッドを選択するための規則を含んでいる、<includelist> も含める必要があります。これらについては、<includelist> および <excludelist> 規則セクションで説明します。ここで留意すべき点は、この <includelist> は、文字列の暗号化のために選択された全クラス/メソッドのサブセットである必要があるということです。

カスタム暗号化に関する詳細については、カスタム暗号化の使用セクションを参照してください。

<customEncryption useCustomEncryption="true" encryptionJar="custEncryption.jar"
        encryptionClass="com.example.myCustomEncryption.Encrypt" encryptionMethod="myEncrypter" decryptionClass="com.example.myProject.Decrypt" decryptionMethod="myDecrypter" >
    <includelist>
        <classes name="com.example.mySpecialClasses.**"/>
    </includelist>
</customEncryption>

<make-synthetic> セクション

<make-synthetic> セクションは、[Make Synthetic]難読化オプションを制御します。このオプションは、メソッドとフィールドを、Java コンパイラによって生成される合成としてマークします。これは、一部の逆コンパイラを混乱させます。タグには 1 つの属性と値が含まれ、value には指定できる設定が 4 つあります。

  • none – メソッドもフィールドも影響を受けません。これは、セクション全体を省略するのと同じです。

  • private – private または package-private のメソッドとフィールドは合成とされます。

  • non-public – private、package-private、または protected のメソッドとフィールドは合成とされます。

  • all – すべてのメソッドとフィールドが合成とされます。value 属性が省略された場合は、これが既定値となります。

MakeSynthetic は <excludelist> 要素をサポートしています。この要素には、合成としてマークされないクラス、メソッド、およびフィールドを選択する規則を含めることができます。この要素については、<includelist> および <excludelist> 規則セクションで説明します。

<make-synthetic value="non-public"/>

<premark> セクション

<premark> セクションでは、ソフトウェアのウォーターマーク処理に固有のオプションを指定する方法について説明します。optionoff に設定されている場合は、premark セクションの残りの部分の内容に関係なく、DashO は PreMark をまったく行いません。on になっている場合は、DashO は指定されたエンコードとウォーターマーク文字列を使用して、アプリケーションにウォーターマークを埋め込みます。

<premark option="on"/>

Truncate 属性

出力 jar ファイルが生成されるまで、DashO はウォーターマーク文字列の最大長を予測することはできません。しかし、DashO に対し、ビルド中にウォーターマーク文字列が出力 jar ファイルに収まらなかった場合どう対処するかを指示しておくことはできます。既定の設定では、エラー メッセージを表示してビルドが停止します。on に設定されている場合は、DashO は jar に収まるように文字列を切り詰め、警告メッセージを出力します。どちらの場合も、メッセージにウォーターマークの最大サイズが示されます。

<premark truncate="on" option="on"/>

<encoding>

DashO は、文字のエンコードに必要なビット数を最小限に抑えるために、文字エンコード(「文字コード」と呼ぶ)を使用します。小さい文字エンコードを使用すれば、より長いウォーターマーク文字列を作成できます。

<premark option="on">
    <encoding name="7bit-a"/>
</premark>

DashO には 5 つの文字コードが定義されており、その中からウォーターマーク文字列をエンコードするための文字コードを選択できます。

名前 説明 1 文字あたりのビット数
6bit-a 6 ビット 大文字の英数字および記号 6
6bit-b 6 ビット 英数字および記号 6
7bit-a 7 ビット 英数字および記号 7
4bit-a 4 ビット 16 進数 4
utf8 任意の文字 8

ウォーターマーク 文字列には、指定したエンコードで認められた上記の文字のみを入れることができます。たとえば、文字列に小文字の英字が含まれている場合は、6bit-a のような大文字の英字のみを保持するエンコードは使用できません。

メモ:

ユーザー インターフェイスは、各文字コードに定義されている特定の文字を表示します。

<watermark>

<watermark> オプションは、出力 jar ファイルに埋め込むウォーターマークを設定します。ウォーターマーク文字列の文字は、指定したエンコードで許可される文字セットに準拠している必要があります。

ウォーターマーク文字列の最大サイズは、構成オプションと対象となる jar ファイルの複雑さによって決定されます。通常、jar ファイルが大きければ、より大きい文字列を入れることができます。

<premark option="on">
    <watermark>Copyright Yoyodyne Engineering, Inc.</watermark>
</premark>

<passphrase>

また、暗号化アルゴリズムには一定のブロック長情報が必要です。ウォーターマーク文字列の暗号化を選択した場合は、より多くの空き領域を必要とします。結果として、指定可能なウォーターマーク文字列の最大長が、暗号化をしない場合に比べて短くなる可能性があります。

<premark option="on">
    <passphrase>secret</passphrase>
</premark>

<includenonclassfiles> セクション

DashO は、関連する非クラス ファイルを実行の一部として jar ファイルに保存するために、その出力先ディレクトリにコピーすることができます。たとえば、アプリケーションが、jar のディレクトリ階層中に gif ファイルが散在する jar ファイル内に埋め込まれると仮定します。難読化されたクラス ファイルを出力先に入れることに加えて、指定した出力先の中に、その他の非クラス ファイルに対する gif ファイルをコピーすることもできます。

さらに、出力先ディレクトリのルートあるいは非クラス ファイルがコピーされる jar のルートからの相対パスを指定するために、非クラス ファイルを含めることも可能です。この相対パスは省略可能です。相対パスが指定されていない場合、個々の非クラス ファイルは、出力先ディレクトリまたは jar のルートにコピーされます。

メモ:

非クラス ファイルの処理中に検出された XML 構成ファイルは、クラス名やメソッド名を変更できるように更新されることがあります。

次の例では、DashO は非クラス ファイルを出力先ディレクトリまたは jar のルートにコピーします。

<includenonclassfiles>
    <copy source="c:\gifs\important.gif"/>
</includenonclassfiles>

次の例では、DashO は c:\gifs ディレクトリの .gif ファイルを、出力先ディレクトリまたは jar のルートにコピーします。ソース内の別のディレクトリで .gif ファイルは検索されません。

<includenonclassfiles>
    <copy source="c:\gifs\*.gif"/>
</includenonclassfiles>

次の例では、非クラス ファイルは c:\test\dashoed\gifs ディレクトリにコピーされます。サブディレクトリの gifs は、出力ディレクトリ c:\test\dashoed に作成されます。

<output>
    <dir path="c:\test\dashoed"/>
</output>

<includenonclassfiles>
    <copy source="c:\gifs\important.gif" relativedest="/gifs"/>
</includenonclassfiles>

ソースとしてディレクトリが指定されている場合、再帰下降によって見つかったすべての非クラス ファイルは、階層を保持しながら出力先にコピーされます。

<includenonclassfiles>
    <copy source="c:\nonclassfiles\"/>
</includenonclassfiles>

jar または zip ファイルが指定されている場合、非クラス ファイルは内部階層を保持しながらコピーされます。

<includenonclassfiles>
    <copy source="c:\test\nonclassfiles.jar"/>
</includenonclassfiles>

jar または zip ファイルで相対パスが指定されている場合は、指定された相対パスの下に階層が再作成されます。

<includenonclassfiles>
    <copy source="c:\test\nonclassfiles.jar" relativedest="misc"/>
</includenonclassfiles>

メモ:

エントリ ポイントを使用して指定された jar のすべての非クラス ファイルは、自動的に出力先 jar へコピーされます。

<preverifier> セクション

J2ME CLDC アプリケーションを実行している場合、DashO では、DashO によるアプリケーションの処理が完了した後に、クラス ファイルの事前検証を実行することができます。run 属性を true に設定している場合は、事前検証プログラムへのパスを指定できます。パスのみを指定した場合、プログラム名は preverify であると見なされます。

また、 タグには、事前検証プログラムに追加オプションを渡す次の属性が含まれています。

  • nofinalize="true/false" – 事前検証に -nofinalize を渡す:ファイナライザーは許可されません。

  • nonative="true/false" – 事前検証に -nonative を渡す:ネイティブ メソッドは許可されません。

  • nofp="true/false" – 事前検証に -nofp を渡す:浮動小数点演算は許可されません。

<preverifier run="true" nonative="true" nofp="true">
    ${wtk.home}/bin/preverify.exe
</preverifier>

<signjar> セクション

<signjar> セクションでは、DashO によって作成された jar ファイルまたは APK に対して jarsigner または apksigner ツールを実行できます。jarsigner の詳細は、http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/jarsigner.html にあります。apksigner の詳細は、https://developer.android.com/studio/command-line/apksigner.html にあります。

<signjar> タグには次の属性があります。

  • option="on/off" – 署名のオン/オフを切り替えます。この属性が存在しない場合、既定値は on です。

  • keystore="" – キー ストアの URL。省略可能で、既定値はユーザーのホーム ディレクトリの .keystore になります。URL にプロトコルが含まれていない場合、キー ストアはファイルと見なされます。DashO プロパティを参照できます。

  • storepass="" – キー ストアのパスワード。必須です。これは、keypass が指定されていない場合は非公開鍵の既定値でもあります。ユーザー インターフェイスはこれをエンコード形式で格納しますが、値はプレーン テキストで指定できます。DashO プロパティを参照できます。

  • storetype="" – キー ストアのタイプ。省略可能で、既定値は、Java セキュリティ プロパティ ファイルの keystore.type に設定されている値になります。DashO プロパティを参照できます。

  • alias="" – キー ストアに非公開鍵を格納するために使用される別名。必須です。DashO プロパティを参照できます。

  • keypass="" – jar ファイルを署名するために使用される非公開鍵のパスワード。省略可能で、既定値はキー ストアのパスワードになります。ユーザー インターフェイスはこれをエンコード形式で格納しますが、値はプレーン テキストで指定できます。DashO プロパティを参照できます。

  • sigfile="" – .SF および .DSA ファイルのベース名。省略可能で、既定値は alias から派生する値になります。DashO プロパティを参照できます。

  • internalsf="true/false" – .DSA の中に署名ファイルのコピーを含めます。省略可能で、既定値は false になります。jarsigner にのみ適用されます。

  • sectionsonly="true/false" – 署名ファイルに、マニフェスト ファイルのハッシュを含むヘッダーは追加されません。省略可能で、既定値は false になります。jarsigner にのみ適用されます。

  • addArgs="" – jarsigner または apksigner の任意の追加引数。省略可能です。jarsigner を使用して APK に署名する場合は、これを "-sigalg SHA1withRSA -digestalg SHA1" に設定する必要があるかもしれません。apksigner を使用する場合は、APK の署名方式を設定するために、これを --v1-signing-enabled [true|false] --v2-signing-enabled [true|false] または --min-sdk-version nn --max-sdk-version nnnn は sdk バージョン)に設定してください。DashO プロパティを参照できます。

<signjar option="on" keystore="../dev/keystore" storepass="${keystore.psw}"
        alias="lazardo">
    ${jdk.home}/bin/jarsigner
</signjar>

<injection> セクション

<instrumentation> セクション

このセクションでは、PreEmptive Analytics のインストルメンテーションを指定する方法について説明します。このセクションには、インストルメンテーションのプロパティを定義するオプション、アノテーションの処理、および仮想アノテーションの定義が含まれています。

<instrumentation> タグには次の属性があります。

  • option="on/off" – DashO のインストルメンテーション機能のオン/オフ(on または off)を切り替えます。この属性が存在しない場合、既定値は on です。

  • honorAnnotations="true/false" – コンパイルされたクラスに存在するインストルメンテーション アノテーションを使用するかどうかを決定します。true の場合、DashO はクラス内のインストルメンテーション アノテーションを処理します。この属性が存在しない場合、既定値は true です。

  • stripAnnotations="true/false" – コンパイルされたクラスに存在するインストルメンテーション アノテーションを出力に保持するかどうかを決定します。true の場合、DashO はアノテーションを削除します。この属性が存在しない場合、既定値は true です。

  • sendMessages="true/false" – false に設定すると、メッセージは PreEmptive Analytics サーバーへ送信されません。supportOfflinetrue の場合は、後で送信するようにメッセージが保存されます。この機能は、OfflineMode および OfflineModeSource アノテーションによって、またはプログラムを使って制御することができます。この属性が存在しない場合、既定値は true です。

  • supportOffline="true/false" – すぐに PreEmptive Analytics サーバーへ送信できないメッセージの処分を決定します。true に設定すると、それらのメッセージは、サーバーへ送信できるようになるまでローカルに保存されます。sendMessagesfalse であるか、またはサーバーへの通信が可能でない場合は、メッセージをローカルに保存できます。この機能は、OfflineModeSupport および OfflineModeSupportSource アノテーションによって、またはプログラムを使って制御することができます。この属性が存在しない場合、既定値は true です。

  • fullData="true/false" – ユーザー/ホストと、システム プロファイル メッセージで送信されるデータを識別するために送信される情報の量を決定します。これを false に設定すると、最低限量の情報が送信されるようになり、スタートアップとシャットダウンの時間を減らすことができます。この属性が存在しない場合、既定値は true です。

タグが存在しない場合、コンパイルされたクラス内のアノテーションは無視されますが、出力で保持されます。option 属性が off の場合は、タグの内容に関係なく、<instrumentation> タグ全体が無視されます。属性には既定値があるので、以下のタグは同等です。

<instrumentation />
<instrumentation option="on"
    honorAnnotations="true"
    stripAnnotations="true"
    sendMessages="true"
    supportOffline="true"
    fullData="true"/>

メモ:

instrumentation は、Quick Jar モードでは利用できません。Quick Jar モードは、instrumentation セクションで設定されたオプションをすべて無視します。

<instrumentation> タグは単に、com.preemptive.annotation.instrumentation パッケージからアノテーションを処理、または削除するだけです。これらのアノテーションの詳細については、関連する javadocs を参照してください。

<endpoint> セクション

<endpoint> は、ランタイム情報が送信される場所を定義します。<endpoint> タグには次の属性があります。

  • name="name" – これは、PreEmptive Analytics サーバーの場所です。エンドポイントは URL に似ていますが、プロトコルが含まれていません。指定されていない場合は、PreEmptive Analytics Commercial エンドポイントが使用されます。

  • ssl="true/false" – エンドポイントへデータを送信する際に、HTTP または HTTPS プロトコルを使用します。既定値は true です。

これらの値は、EndPoint および UseSSL アノテーションによって設定することもできます。

<runtime> セクション

<instrumentation> タグには、省略可能な <runtime> タグを含めることができます。このタグは、アプリケーションでどの PreEmptive Analytics System の実装 jar が使用され、それがどのように処理されるかを指定するために使用されます。タグを省略すると、属性の既定値が使用されます。 タグには次の属性があります。

  • target="java15" – アプリケーションの実行環境。サポートされている値は、java15(Java 1.5 以上)と android4(Android SDK 1.6)以上です。

  • merge="true/false" – ランタイム ライブラリをアプリケーションのクラスとマージします。既定値は true で、DashO はクラスをまとめて出力にすることができるため、実装のクラスの完全な名前の変更と除去が可能になります。false の場合は、実装の jar ファイルをアプリケーションに同梱し、そのクラスパスに追加する必要があります。

<instrumentation>
    <runtime target="java15" merge="true" />
</instrumentation>

Android の使用

Android のプロジェクトでは、android.permission.INTERNET アクセス許可を AndroidManifest.xml に追加して、PreEmptive Analytics がデータを送信できるようにする必要があります。

<company> および <application> セクション

<instrumentation> タグには、省略可能な <company><application> のタグを含めることができます。これらは、インストルメンテーションで使用されるプロパティ値を定義します。タグとそのすべての属性は省略可能です。

<company>
  • name="name" – アプリケーションの名前。

  • id="id" – アプリケーションを提供する会社の ID。この値は GUID で指定する必要があります。

<application>
  • name="name" – アプリケーションの名前。

  • id="id" – アプリケーションの ID。この値は GUID で指定する必要があります。

  • version="version" – アプリケーションのバージョン。このバージョンは任意の形式で表現することができます。

  • type="type" – アプリケーションのタイプ。タイプは、ユーザーが定義した任意の文字列を指定できます。

<instrumentation>
    <company name="Yoyodyne Engineering, Inc."
        id="DF29A894-C1AB-5947-E0A2-0D9779CFFB63" />
    <application id="40A80B91-FB16-BB0F-96CF-6931B4472204"
        version="9.3.4" type="Swing App" />
</instrumentation>

<expiry> セクション

<instrumentation> タグには、任意の期限切れ情報を含めることができます。これらは、アプリケーションに配置される期限切れトークンを作成する ShelfLifeCheck アノテーションで使用される値を定義します。すべての属性が、差し込みが行われるときに展開されるプロパティ参照を含むことができることに注意してください。

  • key="file" – PreEmptive Solutions から入手した Shelf Life キー ファイル。

  • date="date" – MM/DD/YYYY 形式の固定の有効期限。これは、アプリケーションが期限切れになると見なされる日付です。

  • warningdate="date" – MM/DD/YYYY 形式の固定の警告日付。これは、期限切れに関する警告を開始する日付です。

  • period="days" – 有効期限。これは、アプリケーションが期限切れになると見なされる開始日からの日数です。開始日は、StartDateSource アノテーションを含んでいるアプリケーションによって提供されます。

  • warningperiod="days" – 警告期間。これは、期限切れの警告期間を開始する、期限までの日数です。

固定の日付と期間の組み合わせが許可されます。固定の日付と期間の両方の値が存在している場合は、固定の日付が使用されます。アプリケーション コードに現れるアノテーションや、仮想アノテーションによって定義されているアノテーションは、これらの値をオーバーライドしたり増加させたりすることができます。

<instrumentation>
    <expiry key="../yoyodyne.slkey"
        date="10/25/${EXP_YR}"
        warningperiod="90"/>
</instrumentation>
期限切れトークンのプロパティ

ユーザー定義のプロパティを期限切れトークンに追加することができます。これらのプロパティは、DashO の他のプロパティ タグと同じ形式を使用します。プロパティは、ShelfLifeCheck アノテーションを使ってユーザー操作が指定されているアプリケーションによって調べることができます。

<instrumentation>
    <expiry key="…" date="10/25/2016">
        <property name="REGION" value="2"/>
        <property name="COUNTRY" value="GB"/>
    </expiry>
</instrumentation>

namevalue の両方の属性にはプロパティ参照を含めることができます。これらは ShelfLifeCheck が差し込まれるときに展開されます。

仮想アノテーション

<instrumentation> タグには、1 つ以上の仮想アノテーション定義を含むことができます。DashO は、これらのアノテーションがコンパイルされたクラス ファイルにあるかのように、そのアノテーションに従って行動します。仮想アノテーションを使用すると、既存のアノテーションの拡大や、それらの値のオーバーライドが行えます。仮想アノテーションは、1 つまたは複数の <classes> タグを使用して、コンパイルされたクラスに関連付けられています。これらのタグは、選択対象リストや選択除外リストで見られるものと同じ構文を使います。詳細については、<includelist> および <excludelist> 規則のセクションを参照してください。

メモ:

<classes> タグは excludeclass 属性をサポートしていませんし、このタグに <field> タグを含めることもできません。

1 つ以上のアノテーション タグが、<classes> タグやそれに含まれる <method> タグ内に現れることがあります。

<annotation> タグ

<annotation> タグは、クラスまたはメソッドに適用される仮想アノテーションを定義します。アノテーションには 2 つの属性があり、入れ子のプロパティをいくつでも持つことができます。

  • name="name" – アノテーションの名前。ここでは任意の名前を使用できますが、DashO は com.preemptive.annotation.instrumentation パッケージで見つかったアノテーションだけを処理します。アノテーションは、完全修飾名ではなく、ApplicationStart などのような単純な名前で参照することができます。

  • value="value" – アノテーションに対する省略可能な値。SystemProfile などの一部のアノテーションは値を使用しませんが、FeatureTick など他のアノテーションは値を 1 つ必要とします。値は、アノテーションが適用されるときに展開されるプロパティ参照を含めることができます。

<classes name="com.yoyodyne.Overthruster">
    <annotation name="CompanyId"
        value="DF29A894-C1AB-5947-E0A2-0D9779CFFB63"/>
    <method name="main" signature="java.lang.String[]">
        <annotation name="ApplicationStart">
            <property name="customDataSource" value="staticProps"/>
        </annotation>
        <annotation name="ApplicationStop">
            <property name="customDataSource" value="staticProps"/>
        </annotation>
    </method>
</classes>

上記の例では、main メソッドがアプリケーションの開始と停止を制限しています。どちらのメッセージも、静的フィールドの staticProps から追加のプロパティを送信します。会社名はクラスに設定されていますが、その後、main メソッドで ApplicationStart によって使用されることに注目してください。アノテーションの順序は重要ではありません。DashO は、コードがインストルメント化されるときに詳細を整理します。

<classes name="com.yoyodyne.Overthruster">
    <method name="start" signature="">
        <annotation name="ApplicationStart">
            <property name="where" value="End"/>
        </annotation>
        <annotation name="Company">
            <property name="name" value="Yoyodyne Engineering, Inc."/>
            <property name="id" value="DF29A894-C1AB-5947-E0A2-0D9779CFFB63"/>
        </annotation>
    </method>
    <method name="stop" signature="">
        <annotation name="ApplicationStop"/>
    </method>
    <method name="testOscillation " signature="">
        <annotation name="FeatureStart" value="Oscillation Test">
            <property name="customDataSource" value="getTestParameters()"/>
        </annotation>
        <annotation name="FeatureStop" value="Oscillation Test">
            <property name="customDataSource" value="getTestParameters()"/>
        </annotation>
    </method>
</classes>

上記の例は、プロパティを含んでいるアノテーションの使用方法を示しています。ApplicationStart は、start メソッドの終了時に実行されます。Company アノテーションは値を持ちませんが、2 つのプロパティで構成されます。どちらの機能メッセージも、メソッドの getTestParameters().から追加のプロパティを送信します。

アノテーションの値は、クラスとメソッド両方の動的プロパティを使用することができます。クラス レベルで使用されるアノテーションで、METHOD_NAMEPROP_NAME を使用できます。実際の値は、アノテーションが特定のメソッドに適用されるときにのみ展開されます。

<checks> セクション

このセクションでは、コードに差し込むチェックとレスポンスについて説明します。これらのチェックおよびレスポンスには、<locations> セクションが含まれている必要があります。

チェック

ほとんどのチェックには、次の標準属性があります。

  • action – チェックの状態を伴う、任意の操作の呼び出し/設定。ほとんどのチェックでは、これは boolean 型になります(ソースおよび操作の指定を参照してください)。

  • response – チェックがトリガーされたときに実行するレスポンス。

    • exit – ランダムなゼロ以外のリターン コードを生成してアプリケーションを終了する。

    • hang – 現在のスレッドをハングさせる。

    • errorjava.lang.Error の、ランダムに選択されたサブクラスをスローする。

    • exceptionjava.lang.Exception の、ランダムに選択されたチェックされていないサブクラスをスローする。

    • none – 何もしない(既定)。

  • sendMessage – チェックがトリガーされた場合に、メッセージを PreEmptive Analytics へ送信するかどうか。(既定:false

  • customDataSource – 任意の、メッセージと一緒に送信されるカスタム データのソース(カスタム データ ソースを参照してください)。

  • where – コードを差し込む場所。

    • Beginning – メソッドの最初の部分(既定)。

    • End – メソッドの最後の部分(すべての exit ポイント)。

    • BeginningAndEnd – メソッドの最初と最後の部分。

レスポンス

ほとんどのレスポンスには、次の標準属性があります。

  • source – チェックがトリガーされたかどうかを判断するソース。これは boolean 型になります(ソースおよび操作の指定を参照してください)。

  • responsesource が、チェックがトリガーされたことを示す場合に、実行するレスポンス。

    • exit – ランダムなゼロ以外のリターン コードを生成してアプリケーションを終了する。

    • hang – 現在のスレッドをハングさせる。

    • errorjava.lang.Error の、ランダムに選択されたサブクラスをスローする。

    • exceptionjava.lang.Exception の、ランダムに選択されたチェックされていないサブクラスをスローする。

    • none – 何もしない(既定)。

  • probabilityresponse(つまり exithangerror、または exception)が発生する確率。0.0 から 1.0 までの小数を指定できます(既定値:1.0)。

  • sendMessage – メッセージを PreEmptive Analytics へ送信するかどうか。true の場合、チェックがトリガーされたことを source が示す場合に、メッセージが送信されます。probability の影響は受けません。(既定:false

  • customDataSource – 任意の、メッセージと一緒に送信されるカスタム データのソース(カスタム データ ソースを参照してください)。

  • where – コードを差し込む場所。

    • Beginning – メソッドの最初の部分(既定)。

    • End – メソッドの最後の部分(すべての exit ポイント)。

    • BeginningAndEnd – メソッドの最初と最後の部分。

<debuggingCheck> セクション

デバッグ チェックは、アプリケーションがデバッグされているかどうかを判断します(デバッグ チェックとレスポンスを参照してください)。デバッグ チェックは標準属性を備えています。

<debuggingCheck action="myBoolean" response="none" sendMessage="false" where="End">
    <locations>
        <classes name="com.example.MyClass">
            <method name="runCalculation"
                signature="int, int"/>
        </classes>
    </locations>
</debuggingCheck>

<debuggingResponse> セクション

デバッグのレスポンスを使用すると、アプリケーションは、チェック自体が発生した場所から離れた領域でデバッグ チェックに対応できるようになります(デバッグ チェックとレスポンスを参照してください)。デバッグのレスポンスは標準属性を備えています。

<debuggingResponse source="myBoolean" response="error" sendMessage="true"
        customDataSource="props" where="Beginning" probability="0.5">
    <locations>
        <classes name="com.example.MyOtherClass">
            <method name="runOtherCalculation"
                signature="double"/>
        </classes>
    </locations>
</debuggingResponse>

<debugEnabledCheck> セクション

デバッグ有効化チェックは、アプリケーションのデバッグが有効になっているかどうかを判断します(デバッグ チェックとレスポンスを参照してください)。デバッグ有効化チェックは標準属性を備えています。

<debugEnabledCheck action="myBoolean" response="none" sendMessage="false" where="End">
    <locations>
        <classes name="com.example.MyClass">
            <method name="runCalculation"
                signature="int, int"/>
        </classes>
    </locations>
</debugEnabledCheck>

<debugEnabledResponse> セクション

デバッグ有効化のレスポンスを使用すると、アプリケーションは、チェック自体が発生した場所から離れた領域でデバッグ有効化チェックに対応できるようになります(デバッグ チェックとレスポンスを参照してください)。デバッグ有効化のレスポンスは標準属性を備えています。

<debugEnabledResponse source="myBoolean" response="error" sendMessage="true"
        customDataSource="@staticProperties" where="Beginning" probability="0.5">
    <locations>
        <classes name="com.example.MyOtherClass">
            <method name="runOtherCalculation"
                signature="double"/>
        </classes>
    </locations>
</debugEnabledResponse>

<rootCheck> セクション

ルート チェックは、ルート化されたデバイスでアプリケーションが実行されているかどうかを判断します(ルート チェックとレスポンスを参照してください)。ルート チェックは標準属性を備えています。

<rootCheck action="myBoolean" response="none" sendMessage="false" where="End">
    <locations>
        <classes name="com.example.MyClass">
            <method name="runCalculation"
                signature="int, int"/>
        </classes>
    </locations>
</rootCheck>

メモ: ルート チェックは Android でのみサポートされます。

<rootResponse> セクション

ルートのレスポンスを使用すると、アプリケーションは、チェック自体が発生した場所から離れた領域でルート チェックに対応できるようになります(ルート チェックとレスポンスを参照してください)。ルートのレスポンスは標準属性を備えています。

<rootResponse source="myBoolean" response="error" sendMessage="true"
        customDataSource="@staticProperties" where="Beginning" probability="0.5">
    <locations>
        <classes name="com.example.MyOtherClass">
            <method name="runOtherCalculation"
                signature="double"/>
        </classes>
    </locations>
</rootResponse>

メモ: ルートのレスポンスは Android でのみサポートされます。

<shelfLifeCheck> セクション

Shelf Life チェックは、有効期限パラメーターに基づいて、アプリケーションの有効期限が切れているか、または間もなく切れるかどうかを判断します(Shelf Life を参照してください)。Shelf Life チェックは、response を除くすべての標準属性を備えているほかに、6 つの追加属性があります。

  • expirationDate – アプリケーションの有効期限が切れる絶対日付。MM/DD/YYYY 形式です。

  • warningDate – 期限切れに関する警告を開始する絶対日付。MM/DD/YYYY 形式です。

  • startDateSource – 実行時に java.util.Date として提供される開始日のソース。

  • expirationPeriod – 相対的な有効期限。開始日からの日数を示します。

  • warningPeriod – 相対的な警告期間。有効期限までの日数を示します。

  • tokenSource – Shelf Like トークンを外部で管理する場合に、java.io.Reader とするトークンのソース。

メモ:この場合、標準の action 属性は、Token 引数を受け入れ、void を返すメソッドを必要とします(既定:ShelfLifeCheck で説明されている既定の操作)。

<shelfLifeCheck action="customShelfLifeAction()" sendMessage="true"
        where="End" customDataSource="getLicensingDetails()"
        expirationDate="11/01/2016" warningDate="10/01/2016">
    <locations>
        <classes name="com.example.Main">
            <method name="earlySetupMethod" signature="java.lang.String"/>
        </classes>
        <classes name="com.example.MyOtherClass">
            <method name="infrequentButCriticalCalculation" signature="double"/>
        </classes>
    </locations>
</shelfLifeCheck>

<tamperCheck> セクション

改ざんチェックは、アプリケーションが変更されたかどうかを判断します(改ざんチェックとレスポンスを参照してください)。改ざんチェックは標準属性を備えています。

改ざんチェックには、任意で、署名情報を構成する signerInfo 要素を含めることができます。これは、<signjar> に設定されている情報をオーバーライドします。

  • alias – キー ストアに非公開鍵を格納するために使用される別名。DashO プロパティを参照できます。

  • keystore – キー ストアの URL。既定値はユーザーのホーム ディレクトリの .keystore になります。URL にプロトコルが含まれていない場合、キー ストアはファイルと見なされます。DashO プロパティを参照できます。

  • storepass – キー ストアのパスワード。ユーザー インターフェイスはこれをエンコード形式で格納しますが、値はプレーン テキストで指定できます。DashO プロパティを参照できます。

  • storetype – キー ストアの種類。既定値は、Java セキュリティ プロパティ ファイルの keystore.type に設定されている値になります。DashO プロパティを参照できます。

<tamperCheck action="myBoolean" response="none" sendMessage="false" where="End">
    <locations>
        <classes name="com.example.MyClass">
            <method name="runCalculation"
                signature="int, int"/>
        </classes>
    </locations>
    <signerInfo alias="correct_cert" storepass="[SbJlvHrFg8s4GblvgMcQ4w==]"
                keystore="keystore.ks"/>
</tamperCheck>

<tamperResponse> セクション

改ざんのレスポンスを使用すると、アプリケーションは、チェック自体が発生した場所から離れた領域で改ざんチェックに対応できるようになります(改ざんチェックとレスポンスを参照してください)。改ざんのレスポンスは標準属性を備えています。

<tamperResponse source="myBoolean" response="error" sendMessage="true"
        customDataSource="customData()" where="Beginning" probability="0.5">
    <locations>
        <classes name="com.example.MyOtherClass">
            <method name="runOtherCalculation"
                signature="double"/>
        </classes>
    </locations>
</tamperResponse>

<locations> セクション

すべてのチェックおよびレスポンスでは、場所を設定する必要があります。locations タグは、その子として <classes> を必要とします。

ソースおよび操作の指定

いくつかのアノテーション、チェック、およびレスポンスは、生成された情報で使用される動的な情報のソースや操作を指定します。これらは、現在のクラスに定義されているフィールドやメソッド、または別のクラスの静的メソッドやフィールドを参照できます。

静的フィールドおよびメソッドは、どのメソッドからでも使用できます。インスタンス フィールドおよびメソッドは、同じクラス内のインスタンス メソッドからのみ使用できます。フィールドは、アノテーションが求める必要な型でなければなりません。メソッドは、アノテーションが求める必要な戻り値の型とパラメーターを持っていなければなりません。指定されたフィールドおよびメソッドは、実行時に差し込み場所からアクセスできる必要があります。

フィールドやメソッドは、次の形式を使用して指定します。

  • field – 現在のクラスの フィールド field をソースとして使用します。ソースが静的メソッドから使用される場合、ソースは静的でなければなりません。そうでない場合は、インスタンス フィールドまたは静的フィールドを指定できます。

  • @field – 現在のクラスの静的フィールド field をソースとして使用します。これは、静的メソッドまたはインスタンス メソッドから使用できます。

  • class.field – クラス class の静的フィールド field をソースとして使用します。class は、完全修飾された Java クラス名です。これは、静的メソッドまたはインスタンス メソッドから使用できます。

  • method() – 現在のクラスのメソッド method をソースとして使用します。ソースが静的メソッドから使用される場合、ソースは静的でなければなりません。そうでない場合は、インスタンス メソッドまたは静的メソッドを指定できます。

  • @method() – 現在のクラスの静的メソッド method をソースとして使用します。これは、静的メソッドまたはインスタンス メソッドから使用できます。

  • class.method() – クラス class の静的メソッド method をソースとして使用します。class は、完全修飾された Java クラス名です。これは、静的メソッドまたはインスタンス メソッドから使用できます。

メモ:

@ は、別のクラスの静的メソッドまたは静的フィールドを参照する場合には使用できません。同じクラスの静的メソッドまたは静的フィールドを参照する場合、@ は省略可能です。

このソースまたは操作が、複数の場所に差し込むよう構成されているチェックまたはレスポンスから使用されている場合には、指定されたソースまたは操作は、それぞれの差し込み場所と相対していなければなりません。

ソースまたは操作が正しく指定されていないと、エラーが発生します。

カスタム データ ソース

差し込まれたイベントまたはメッセージの customDataSource を定義する場合、値は java.util.Properties フィールドの名前、または java.util.Properties のインスタンスを返す、引数のないメソッドである必要があります。既定では、すべてのプロパティは文字列であり、サーバーによって文字列として解釈され照合されます。どんな型のオブジェクトでもプロパティに置くことができます。それらは、オブジェクトの toString() メソッドを使用して文字列に変換されます。たとえば、java.lang.Number を使用して、サーバーに数値を送信することができます。

Properties properties = new Properties();
String theName = "My Name";
int theCount = 42;
// このプロパティは文字列です
properties.setProperty("name", theName);
// このプロパティも文字列です
properties.setProperty("countString", Integer.toString(theCount));
// このプロパティは数値です
properties.put("countNumber", new Integer(theCount));
// このプロパティは文字列で、MyObj.toString() を使用します
properties.put("myObject", new MyObj());

<includelist> および <excludelist> 規則

プロジェクト ファイルの一部のタブは、<includelist> および <excludelist> を使用して、操作が適用される項目を微調整します。これらのタグは、特定のクラス、メソッド、またはフィールドを選択するために適用される規則のリストを指定します。

対象選択と対象除外の両方を使用しているタグでは、最初に対象選択が決定されます。<includelist> が空の場合は、*すべての項目が対象として選択されます。項目が選択されたら、次に対象除外規則が調べられます。<excludelist> が空の場合は、どの項目も対象から除外されません。各リスト内の規則は、それらがプロジェクト ファイルで指定されている順序で適用されます。また、<excludelist> に加えて使用され、特定の機能について構成される <globalProcessingExclude> セクションもあります。さらに、DashO の内部規則、その他のオプションの要件、およびクラス自体によって、項目が除外される可能性があります。

クラス、メンバーと同様にメソッドの署名の名前も、リテラル、パターン、あるいは正規表現として指定することができます。詳細については、名前:リテラル、パターン、および正規表現を参照してください。項目の修飾子も条件として使用できます。詳細については、Modifiers 属性を参照してください。

<classes> タグ

<classes> タグは、1 つ以上のクラスを選択する規則を定義するために使用されます。クラス名は完全修飾名である必要があり、内部クラスは、外部と内部のクラス名の間に $ を区切り文字として使用して指定されることに注意してください。

<classes> タグは、フィールドとメソッドを選択するための追加規則を指定するために、クラスを選択します。タグに <field> タグも <method> タグも含まれていなければ、このタグをクラスのすべてのメンバー、あるいはクラス自体に適用するために使用できます。この動作は、規則を使用しているオプションによって決まります。

いくつかの対象除外リストでは、<classes> 名をクラスのメンバーではなくクラス自体に適用されるようにすることができます。これは、省略可能な excludeclass 属性によって制御されます。excludeclass 属性の既定値は true です。excludeclass 属性がそのオプションで使用されているかどうかを確認するために、<excludelist> を使用する個々のタグを調べてください。

<classes name=".*" regex="true"/>

<classes name="library.Class1$NestedClass"/>

<classes name="myco.Test.MyOtherTest" excludeclass="false">

<method> タグ

<method> タグは <classes> タグ内で使用されます。メソッドは、名前(name)と署名(signature)を指定して選択できます。<method> の regex の設定は <classes> タグから継承されます。囲っている <classes> の regex の値が true であれば、name 属性と signature 属性は正規表現です。次の例は、正規表現を使用して、任意の数のパラメーターを持つ set で始まるメソッドをすべて選択します。

<classes name=".*" regex="true">
    <method name="set.*" signature=".*"/>
</classes>

signature 属性を選択の条件として使用することができます。signature 属性は、メソッドのパラメーター一覧の型と一致する Java 型のカンマ区切りの一覧です。パラメーターのクラス名は完全修飾名でなければなりません。パラメーターのないメソッドを指定するには、空の文字列を使用します。

<classes name=".*" regex="true">
    <method name="get[A-Z].*" signature=""/>
</classes>

<classes name=".*">
    <method name="set*" signature="int,MyClass,MyClass[]"/>
</classes>

<classes name="AnalysisEngine">
    <method name="compute" signature="int,java.util.List,float[]"/>
</classes>

<field> タグ

<field> タグは <classes> タグ内で使用されます。囲っている <classes>regex の値が true であれば、name 属性は正規表現でなければなりません。

一部のオプションの操作はメソッドにのみ適用されるので、<field> タグは、すべての対象選択リストおよび対象除外リストには適用できません。<field> タグが使用可能かどうかを確認するために、対象選択リストまたは対象除外リストを使用する個々のタグを調べてください。次の例は、正規表現を使用して、counter で始まるフィールドをすべて選択します。

<classes name=".*" regex="true">
    <field name="counter.*"/>
</classes>

<method> と <field> の組み合わせ

<classes> タグに複数の <method> タグと <field> タグを含めることで、プロジェクト内の多くの項目を選択する規則を作成することができます。たとえば、次のような例です。

<classes name="com\.yoyodyne\.beans\..*" regex="true">
    <method name="get[A-Z].*" signature=""/>
    <method name="set[A-Z].*" signature=".*"/>
    <method name="is[A-Z].*" signature=""/>
    <field name="CONST_.*"/>
</classes>

Modifiers 属性

<classes><method>、および <field> タグはすべて modifiers 属性を持っています。この属性は、項目が持つ Java の修飾子やキーワードによって項目を一致させるために使用されます。複数の修飾子は、スペースで区切って指定できます。modifiers が省略された場合、項目の修飾子は選択条件の一部として使用されません。修飾子は次のとおりです。

  • public – ソース コードにおける項目の参照範囲は public です。

  • protected – ソース コードにおける項目の参照範囲は protected です。

  • private – ソース コードにおける項目の参照範囲は private です。

  • default – これは、ソース コードで publicprotectedprivate のいずれも指定されていないときに、項目に与えられる既定の参照範囲を表します。

  • abstract – 項目は、ソース コードで abstract に設定されています。<field> で使用されている場合には意味を持ちません。

  • final – 項目は、ソース コードで final に設定されています。

  • static – 項目は、ソース コードで static に設定されています。

  • native – メソッドは、ソース コードで native に設定されています。<classes> または <field> で使用されている場合には意味を持ちません。

  • strictfp – 項目は、ソース コードで strictfp に設定されています。

  • synchronized – メソッドは、ソース コードで synchronized に設定されています。<classes> または <field> で使用されている場合には意味を持ちません。

  • transient – フィールドは、ソース コードで transient に設定されています。<classes> または <method> で使用されている場合には意味を持ちません。

  • volatile – フィールドは、ソース コードで volatile に設定されています。<classes> または <method> で使用されている場合には意味を持ちません。

  • class – 項目は class(クラス)です。これは、<classes> で使用される場合にのみ意味を持ちます。

  • interface – 項目は interface(インターフェイス)です。これは、<classes> で使用される場合にのみ意味を持ちます。

  • enum – 項目は enum(列挙型)です。これは、<classes> で使用される場合にのみ意味を持ちます。

  • annotation – 項目は Java annotation(アノテーション)です。これは、<classes> で使用される場合にのみ意味を持ちます。

  • synthetic – Java コンパイラはこの項目を実装情報の詳細として作成しているため、ソース コードの一部として現れません。

認識できない修飾子は無視されます。修飾子の前に ! を加えることで、修飾子を否定として指定することもできます。修飾子は大文字と小文字を区別しません。

<classes modifiers="public class" name="com.yoyodyne.*">
    <method modifiers="!private !native" name="*" signature="**"/>
    <field modifiers="!public final" name="*"/>
</classes>

<classes modifiers="!default !private !enum !annotation" name="**">
    <method modifiers="!default !private" name="*" signature="**"/>
    <field modifiers="!default !private" name="*"/>
</classes>

名前:リテラル、パターン、および正規表現

クラスとメンバーの名前は、リテラル値、パターン、または正規表現のいずれかで指定できます。リテラル値を使用すると、一致させる項目を正確に指定できますが、パターンや正規表現を使用すると、1 つのエントリに対して 1 つ以上の項目を一致させることができます。既定では、? または * が含まれていない限り、名前はリテラル値として扱われます。正規表現を指定するには、タグに regex="true" 属性を追加する必要があります。

正規表現の使用

入力される正規表現は、Java 正規表現サポートによってコンパイルできなければなりません。無効なパターンが使用された場合にはビルドが失敗します。Java 正規表現でサポートされる構文の詳細については、Java Regular Expression Tutorial を参照してください。

メモ: 引数のないメソッド署名と一致させる場合は、正規表現に ^$ または \Q\E を使用します。

パターンの使用

パターンはリテラル値によく似ていますが、次に挙げるパターンのインジケーターを 1 つ以上含んでいます。

  • ? – 1 文字と一致します。

  • * – 制限付きで 0 個以上の文字と一致します。一致させることができるものは、照合している項目の種類によって異なります。これについては、以降のセクションで説明します。

  • ** – 制限なしで 0 個以上の文字と一致します。

クラス名のパターン

* がクラス名で使用されている場合には、サブパッケージではなく単独のパッケージ内の項目と一致します。** パターンは、パッケージあるいは任意のサブパッケージ内の項目と一致します。

メソッド名とフィールド名のパターン

メソッド名やフィールド名で使用されている *** の間に違いはありません。どちらも 0 個以上の文字と一致します。

メソッド署名のパターン

メソッド署名でパターンが使用されている場合は、*** の間に違いがあります。* パターンはメソッドへの 0 または 1 個の引数と一致するのに対し、** は任意の数の引数と一致します。

以下に、署名の一致の例を示します。

* ** long,* long,**
()
(int)
(java.lang.String)
(long,int)
(long,boolean,int)

メモ: 引数のないメソッド署名と一致させる場合は、パターンを空白のままにしておきます。

PreEmptive Protection - DashO Version 8.2.0. Copyright © 2017 PreEmptive Solutions, LLC