セレクター

セレクターは、<fileset> を構成するファイルを、<include> および <exclude> タグによって提供されるファイル名以外の基準に基づいて選択するためのメカニズムです。

セレクターの使用方法

セレクターは FileSet の要素であり、その中に記述します。また、<selector> タグを使用してターゲットの外で定義し、参照として使用することもできます。

セレクターはそれぞれ異なる属性を持っています。一部のセレクターは他のセレクターを含むことができ、これらは セレクターコンテナ と呼ばれます。また、カスタムセレクター と呼ばれる、ユーザー定義の拡張を可能にするセレクターのカテゴリもあります。Apache Ant に組み込まれているものは コアセレクター と呼ばれます。

コアセレクター

コアセレクターは、Ant に標準で付属しているものです。これらは fileset 内で使用でき、セレクターコンテナ内に含めることができます。

コアセレクターは以下のとおりです。

• <contains> — 特定のテキスト文字列を含むファイルを選択します
• <date> — 特定の日時より前または後に変更されたファイルを選択します
• <depend> — 他の場所にある同等のファイルよりも最近変更されたファイルを選択します
• <depth> — ディレクトリツリーの指定された深さにあるファイルを選択します
• <different> — 他の場所にあるファイルとは異なるファイルを選択します
• <filename> — 名前が特定のパターンに一致するファイルを選択します。patternset の include および exclude 要素と同等です。
• <present> — 他の場所に存在するか、または存在しないファイルを選択します
• <containsregexp> — 正規表現に一致するファイルを選択します
• <size> — 特定のバイト数よりも大きいまたは小さいファイルを選択します
• <type> — 通常のファイルまたはディレクトリであるファイルを選択します
• <modified> — 設定されたアルゴリズムの戻り値がキャッシュに保存された値と異なる場合にファイルを選択します
• <signedselector> — ファイルが署名されている場合、およびオプションで特定の名前の署名がある場合にファイルを選択します
• <scriptselector> — BSF または JSR 223 スクリプト言語を使用して独自のセレクターを作成します
• <readable> — ファイルが読み取り可能である場合にファイルを選択します
• <writable> — ファイルが書き込み可能である場合にファイルを選択します
• <executable> — ファイルが実行可能である場合にファイルを選択します
• <symlink> — ファイルがシンボリックリンクである場合にファイルを選択します
• <ownedBy> — ファイルが指定されたユーザーによって所有されている場合にファイルを選択します
• <posixGroup> — ファイルが指定された POSIX グループを持っている場合にファイルを選択します
• <posixPermissions> — ファイルが指定された POSIX パーミッションを持っている場合にファイルを選択します

Contains セレクター

FileSet 内の <contains> タグは、fileset で定義されたファイルを、text 属性で指定された文字列を含むもののみに制限します。

<contains> セレクターは ResourceSelector として使用できます（<restrict> ResourceCollection を参照してください）。

Contains セレクターの使用例を次に示します

<fileset dir="${doc.path}" includes="**/*.html">
    <contains text="script" casesensitive="no"/>
</fileset>

文字列 script を含むすべての HTML ファイルを選択します。

Date セレクター

FileSet 内の <date> タグは、include タグで指定されたファイルに制限を設け、セレクターで指定された日付制限を満たさない最終変更日のタグは選択されません。

Date セレクターの使用例を次に示します

<fileset dir="${jar.path}" includes="**/*.jar">
    <date datetime="01/01/2001 12:00 AM" when="before"/>
</fileset>

2001 年 1 月 1 日の午前 0 時より前に最後に変更されたすべての JAR ファイルを選択します。

Depend セレクター

<depend> タグは、最終変更日が別の場所にある同等のファイルよりも新しいファイルを選択します。

<depend> タグは、比較対象のファイルの場所を定義するために、含まれる <mapper> 要素の使用をサポートしています。<mapper> 要素が指定されていない場合は、identity 型マッパーが使用されます。

<depend> セレクターは大文字と小文字を区別します。

Depend セレクターの使用例を次に示します

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <depend targetdir="${ant.1.4.1}/src/main"/>
</fileset>

1.5 リリースで変更されたすべての Java ソースファイルを選択します。

Depth セレクター

<depth> タグは、fileset のベースディレクトリからのディレクトリレベルの深さに基づいてファイルを選択します。

Depth セレクターの使用例を次に示します

<fileset dir="${doc.path}" includes="**/*">
    <depth max="1"/>
</fileset>

ベースディレクトリと、その下の 1 つのディレクトリにあるすべてのファイルを選択します。

Different セレクター

<different> セレクターは、別の場所にある同等のファイルと「異なる」と見なされた場合にファイルを選択します。2 つのファイル間の差異を判断する規則は次のとおりです

1. セレクターを適用するリソースコレクションにのみファイルが存在し、targetdir に存在しない場合（またはマッパーを適用した後）、ファイルが選択されます。
2. ファイルが targetdir （またはマッパーを適用した後）にのみ存在する場合は無視されます。
3. 長さが異なるファイルは異なります。
4. ignoreFileTimes が off に設定されている場合、ファイルのタイムスタンプが異なると、ファイルは異なると見なされます。
5. ignoreContents が true に設定されていない限り、2 つのファイルに対してバイト単位のチェックが実行されます。

これは、依存関係チェックを適切に処理しないプログラムやタスクを扱う場合に役立つセレクターです。前のタスクが常に出力ファイルを作成する場合でも、フォローアップタスクは別のセレクターで作成されたコピーから実行できるため、それらの依存関係は、単なるタイムスタンプではなく、ファイルの絶対状態に基づいて実行されます。例：Web サイトからフェッチしたもの、または一部のプログラムの出力。チェックの量を減らすために、このタスクを <copy> タスク内で使用する場合は、preservelastmodified を true に設定して、ソースファイルから宛先ファイルにタイムスタンプを伝播します。

<different> セレクターは、比較対象のファイルの場所を定義するために、含まれる <mapper> 要素の使用をサポートしています。<mapper> 要素が指定されていない場合は、identity 型マッパーが使用されます。

Different セレクターの使用例を次に示します

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <different targetdir="${ant.1.4.1}/src/main"
        ignoreFileTimes="true"/>
</fileset>

1.4.1 リリースと 1.5 リリースの間のすべての Java ソースファイルを比較し、ファイル時刻を無視して、異なるものを選択します。

Filename セレクター

<filename> タグは、fileset 内の <include> および <exclude> タグのように機能します。ただし、セレクターを使用することで、任意の セレクターコンテナを使用して、他のすべてのセレクターと組み合わせることができます。

<filename> セレクターは大文字と小文字を区別します。

Filename セレクターの使用例を次に示します

<fileset dir="${doc.path}" includes="**/*">
    <filename name="**/*.css"/>
</fileset>

すべてのカスケードスタイルシートファイルを選択します。

Present セレクター

<present> タグは、別のディレクトリツリーに同等のファイルがあるファイルを選択します。

<present> タグは、テスト対象のファイルの場所を定義するために、含まれる <mapper> 要素の使用をサポートしています。<mapper> 要素が指定されていない場合は、identity 型マッパーが使用されます。

<present> セレクターは大文字と小文字を区別します。

Present セレクターの使用例を次に示します

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">
    <present present="srconly" targetdir="${ant.1.4.1}/src/main"/>
</fileset>

1.5 リリースで新しく追加されたすべての Java ソースファイルを選択します。

正規表現セレクター

FileSet内の<containsregexp>タグは、そのFileSetで定義されたファイルを、expression属性で指定された正規表現に一致する内容を持つもののみに制限します。

<containsregexp>セレクターは、ResourceSelectorとして使用できます（<restrict> ResourceCollectionを参照）。

正規表現セレクターの使用例を以下に示します。

<fileset dir="${doc.path}" includes="*.txt">
    <containsregexp expression="[4-6]\.[0-9]"/>
</fileset>

正規表現に一致する（4、5、または6の後にピリオドと0から9までの数字が続く）すべてのテキストファイルを選択します。

サイズセレクター

FileSet内の<size>タグは、includeタグで指定されたファイルに制限を設け、セレクターで指定されたサイズ制限を満たさないタグは選択されないようにします。

サイズセレクターの使用例を以下に示します。

<fileset dir="${jar.path}">
  <patternset>
    <include name="**/*.jar"/>
  </patternset>
  <size value="4" units="Ki" when="more"/>
</fileset>

4096バイトより大きいすべてのJARファイルを選択します。

タイプセレクター

<type>タグは、特定のタイプ（ディレクトリまたは通常ファイル）のファイルを選択します。

${src}内のディレクトリのみを選択するタイプセレクターの使用例を以下に示します。

<fileset dir="${src}">
  <type type="dir"/>
</fileset>

タイプセレクターは、他のセレクターと組み合わせて使用されることがよくあります。たとえば、templateディレクトリにも存在するファイルを選択し、空のディレクトリを選択しないようにするには、次のようにします。

<fileset dir="${src}">
    <and>
        <present targetdir="template"/>
        <type type="file"/>
    </and>
</fileset>

変更済みセレクター

<modified>セレクターは、ファイルの値を計算し、キャッシュに格納された値と比較して、これらの2つの値が異なる場合にファイルを選択します。

このセレクターは高度に設定可能であるため、選択が行われる順序は次のとおりです。

1. ファイルの絶対パスを取得します
2. 設定されたキャッシュからキャッシュされた値を取得します（キーとして絶対パスを使用）。
3. 設定されたアルゴリズムから新しい値を取得します。
4. これらの2つの値を設定されたコンパレーターと比較します。
5. 必要に応じて、要求された場合はキャッシュを更新します。
6. 比較結果に応じて選択を実行します。

比較、ハッシュ値の計算、およびストアは、特別なインターフェースの実装によって行われます。したがって、追加のパラメーターを提供できます。

<modified>セレクターは、ResourceSelectorとして使用できます（<restrict> ResourceCollectionを参照）。その場合、単純なファイルリソースをファイルにマップし、その処理を行います。リソースが別のタイプの場合、<modified>セレクターは（注意！）ハッシュ値を計算するためにコンテンツをローカルファイルにコピーしようとします。

ソースリソースがファイルシステムリソースでない場合、変更されたセレクターは、それを一時ディレクトリにダウンロードします。

ネストされた要素として指定されたパラメーター

<modified>セレクターは、カスタムインターフェース実装を見つけるためのパスのような構造を表すネストされた<classpath>要素をサポートします。

<modified>セレクターのすべての属性は、ネストされた<param/>タグで設定できます。追加の値は、以下の規則に従って<param/>タグで設定できます。

algorithm

algorithm属性と同じですが、以下の追加の値があります。

cache

cache属性と同じですが、以下の追加の値があります。

comparator

comparator属性と同じです。

algorithmclass

algorithmclass属性と同じです。

comparatorclass

comparatorclass属性と同じです。

cacheclass

cacheclass属性と同じです。

update

update属性と同じです。

seldirs

comparatorclass属性と同じです。

例

変更済みセレクターの使用例を以下に示します。

<copy todir="dest">
    <fileset dir="src">
        <modified/>
    </fileset>
</copy>

これにより、内容が変更されたsrcからdestへのすべてのファイルがコピーされます。cache.propertiesとMD5-DigestAlgorithmを使用した更新PropertyfileCacheを使用します。

<copy todir="dest">
    <fileset dir="src">
        <modified update="true"
                  seldirs="true"
                  cache="propertyfile"
                  algorithm="digest"
                  comparator="equal">
            <param name="cache.cachefile"     value="cache.properties"/>
            <param name="algorithm.algorithm" value="MD5"/>
        </modified>
    </fileset>
</copy>

これは、すべての値（デフォルトと同じ）を設定したCoreSelectorとして書き直した同じ例です。

<copy todir="dest">
    <fileset dir="src">
        <custom class="org.apache.tools.ant.types.selectors.modifiedselector.ModifiedSelector">
            <param name="update"     value="true"/>
            <param name="seldirs"    value="true"/>
            <param name="cache"      value="propertyfile"/>
            <param name="algorithm"  value="digest"/>
            <param name="comparator" value="equal"/>
            <param name="cache.cachefile"     value="cache.properties"/>
            <param name="algorithm.algorithm" value="MD5"/>
        </custom>
    </fileset>
</copy>

そして、これはCustomSelectorとして書き直した同じものです。

<target name="generate-and-upload-site">
    <echo> generate the site using forrest </echo>
    <antcall target="site"/>

    <echo> upload the changed file </echo>
    <ftp server="${ftp.server}" userid="${ftp.user}" password="${ftp.pwd}">
        <fileset dir="htdocs/manual">
            <modified/>
        </fileset>
    </ftp>
</target>

ホームページ生成（例：Apache Forrest）のビルド環境内でのこのセレクターの便利なシナリオ。ここでは、すべての変更されたファイルがサーバーにアップロードされます。したがって、CacheSelectorはアップロード時間を大幅に節約します。

<modified cacheclassname="com.mycompany.MyCache">
    <classpath>
        <pathelement location="lib/mycompany-antutil.jar"/>
    </classpath>
</modified>

Ant自身のクラスパス外にあるjarのcom.mycompany.MyCacheをキャッシュ実装として使用します

RuleBasedCollatorに関する注意

RuleBasedCollatorは動作のためにフォーマットが必要ですが、インスタンス化中に必要になります。この場合の初期化アルゴリズムには問題があります。したがって、これを使用しないでください（または、回避策を教えてください :-）。

署名付きセレクター

<signedselector>タグは、署名付きファイル、およびオプションで特定の名前で署名されたファイルを選択します。

Apache Ant 1.7以降

読み取り可能セレクター

<readable>セレクターは、読み取り可能なファイルのみを選択します。Antはjava.io.File#canReadのみを呼び出すため、ファイルが読み取り不可能であってもJVMがこの状態を検出できない場合、このセレクターは引き続きファイルを選択します。

書き込み可能セレクター

<writable>セレクターは、書き込み可能なファイルのみを選択します。Antはjava.io.File#canWriteのみを呼び出すため、ファイルが書き込み不可能であってもJVMがこの状態を検出できない場合、このセレクターは引き続きファイルを選択します。

実行可能セレクター

<executable>セレクターは、実行可能なファイルのみを選択します。Antはjava.nio.file.Files#isExecutableのみを呼び出すため、ファイルが実行不可能であってもJVMがこの状態を検出できない場合、このセレクターは引き続きファイルを選択します。

Ant 1.10.0以降

シンボリックリンクセレクター

<symlink>セレクターは、シンボリックリンクであるファイルのみを選択します。Antはjava.nio.file.Files#isSymbolicLinkのみを呼び出すため、ファイルがシンボリックリンクであってもJVMがこの状態を検出できない場合、このセレクターはファイルを選択しません。

Ant 1.10.0以降

所有者セレクター

<ownedBy>セレクターは、指定されたユーザーが所有するファイルのみを選択します。Antはjava.nio.file.Files#getOwnerのみを呼び出すため、ファイルシステムがこの操作をサポートしていない場合、このセレクターはファイルを選択しません。

Ant 1.10.0以降

PosixGroupセレクター

<posixGroup>セレクターは、指定されたPOSIXグループが所有するファイルのみを選択します。Antはjava.nio.file.Files#readAttributesのみを呼び出すため、ファイルシステムがこの操作またはPOSIX属性をサポートしていない場合、このセレクターはファイルを選択しません。

Ant 1.10.4以降

PosixPermissionsセレクター

<posixPermissions>セレクターは、指定されたPOSIX権限を持つファイルのみを選択します。Antはjava.nio.file.Files#getPosixFilePermissionsのみを呼び出すため、ファイルシステムがこの操作をサポートしていない場合、このセレクターはファイルを選択しません。

Ant 1.10.4以降

スクリプトセレクター

<scriptselector> 要素を使用すると、Apache BSF または JSR 223 でサポートされている任意の言語で複雑な選択アルゴリズムを記述できます。スクリプトと依存関係の説明については、スクリプトタスクを参照してください。

Apache Ant 1.7以降

このセレクターは、ネストされた <classpath> 要素を取ることができます。この要素の使用法については、scriptタスクを参照してください。

src 属性が指定されていない場合、スクリプトはセレクター宣言内にネストされている必要があります。

埋め込まれたスクリプトは、テストごとに呼び出され、bean self がセレクターにバインドされます。これには、ファイルを選択するために setSelected(boolean) を使用して設定できる selected 属性があります。

次の bean は、プロジェクト、プロパティ、ターゲットの従来のセットに加えて、すべてのスクリプトに対して構成されます。

self bean は、次の属性を持つセレクターにマッピングされます。書き込み可能なのは selected フラグのみで、残りはゲッターメソッドを介して読み取り専用です。

例

<scriptselector language="javascript">
  self.setSelected(true);
</scriptselector>

すべてのファイルを選択します。

<scriptselector language="javascript">
  self.setSelected((filename.length%2)==0);
</scriptselector>

ファイル名の長さが偶数のファイルを選択します。

セレクターコンテナ

より複雑な選択を作成するために、他のセレクターを含むさまざまなセレクターを使用できます。それらは、子セレクターの選択をさまざまな方法で結合します。

セレクターコンテナは次のとおりです。

• <and>—含まれているすべてのセレクターがファイルを選択した場合にのみ、ファイルを選択します。
• <majority>—セレクターの過半数がファイルを選択した場合にファイルを選択します。
• <none>—含まれているセレクターのいずれもファイルを選択しない場合にのみ、ファイルを選択します。
• <not>—セレクターを 1 つだけ含めることができ、選択するものと選択しないものを反転させます。
• <or>—含まれているセレクターのいずれかがファイルを選択した場合にファイルを選択します。
• <selector>—セレクターを 1 つだけ含み、"if" または "unless" 条件が満たされている場合に、すべてのリクエストをそのまま転送します。これは、参照を定義する場合に使用するセレクターです。<project> の要素として使用できます。また、ファイルの選択を Ant プロパティの設定に依存させたい場合にも使用します。

すべてのセレクターコンテナは、他のコンテナを含む任意の他のセレクターを要素として含めることができます。コンテナを使用すると、セレクタータグは任意に深くすることができます。コンテナ内で許可されるセレクター要素の完全なリストを次に示します。

• <and>
• <contains>
• <custom>
• <date>
• <depend>
• <depth>
• <filename>
• <majority>
• <none>
• <not>
• <or>
• <present>
• <selector>
• <size>

And セレクター

<and> タグは、含まれているすべての要素によって選択されるファイルを選択します。ファイルを選択しないセレクターを見つけるとすぐに戻るため、すべてのセレクターをチェックすることが保証されているわけではありません。

And セレクターの使用例を次に示します

<fileset dir="${dist}" includes="**/*.jar">
    <and>
        <size value="4" units="Ki" when="more"/>
        <date datetime="01/01/2001 12:00 AM" when="before"/>
    </and>
</fileset>

先ミレニアム以降更新されていない、4096 バイトを超えるすべての JAR ファイルを選択します。

Majority セレクター

<majority> タグは、含まれている要素の過半数がファイルを選択している場合に、ファイルを選択します。同点は、allowtie 属性で指定されたように処理されます。

Majority セレクターの使用例を次に示します

<fileset dir="${docs}" includes="**/*.html">
    <majority>
        <contains text="project" casesensitive="false"/>
        <contains text="taskdef" casesensitive="false"/>
        <contains text="IntrospectionHelper" casesensitive="true"/>
    </majority>
</fileset>

3 つのフレーズ project、taskdef、および IntrospectionHelper (この最後のフレーズは大文字と小文字を完全に一致させる必要があります) のうち少なくとも 2 つを含むすべての HTML ファイルを選択します。

None セレクター

<none> タグは、含まれている要素のいずれによっても選択されていないファイルを選択します。ファイルを選択するセレクターが見つかるとすぐに戻るため、すべてのセレクターをチェックすることが保証されているわけではありません。

None セレクターの使用例を次に示します

<fileset dir="${src}" includes="**/*.java">
    <none>
        <present targetdir="${dest}"/>
        <present targetdir="${dest}">
            <mapper type="glob" from="*.java" to="*.class"/>
        </present>
    </none>
</fileset>

dest ディレクトリに同等の .java または .class ファイルがない .java ファイルのみを選択します。

Not セレクター

<not> タグは、含まれている単一のセレクターの意味を反転させます。

Not セレクターの使用例を次に示します

<fileset dir="${src}" includes="**/*.java">
    <not>
        <contains text="test"/>
    </not>
</fileset>

src ディレクトリ内の、文字列 test を含まないすべてのファイルを選択します。

Or セレクター

<or> タグは、含まれている要素のいずれかによって選択されるファイルを選択します。ファイルを選択するセレクターが見つかるとすぐに戻るため、すべてのセレクターをチェックすることが保証されているわけではありません。

Or セレクターの使用例を次に示します

<fileset dir="${basedir}">
    <or>
        <depth max="0"/>
        <filename name="*.png"/>
        <filename name="*.gif"/>
        <filename name="*.jpg"/>
    </or>
</fileset>

トップディレクトリ内のすべてのファイルと、その下のすべての画像ファイルを選択します。

セレクター参照

<selector> タグは、参照を通じて再利用できるセレクターを作成するために使用されます。これは、<project> タグの要素として、ターゲットの外で使用できる唯一のセレクターです。他のセレクターを 1 つだけ含めることができますが、もちろん、そのセレクターはコンテナにすることができます。

<selector> タグは、Ant プロパティが存在するかどうかに基づいて、条件付きでファイルを選択するためにも使用できます。この機能は、ターゲットまたは <patternset> 内の <include> および <exclude> タグで使用される方法とまったく同じ方法で、if および unless 属性を使用して実現されます。

セレクター参照の使用例を次に示します

<project default="all" basedir="./ant">

    <selector id="completed">
        <none>
            <depend targetdir="build/classes">
                <mapper type="glob" from="*.java" to="*.class"/>
            </depend>
            <depend targetdir="docs/manual/api">
                <mapper type="glob" from="*.java" to="*.html"/>
            </depend>
        </none>
    </selector>

    <target>
        <zip>
            <fileset dir="src/main" includes="**/*.java">
                <selector refid="completed"/>
            </fileset>
        </zip>
    </target>

</project>

関連付けられた最新のクラスファイルと javadoc ファイルを持つすべての java ファイルを zip 圧縮します。

また、プロパティが設定されているかどうかに基づいて、条件付きでファイルを選択する例を次に示します

<fileset dir="${working.copy}">
    <or>
        <selector if="include.tests">
            <filename name="**/*Test.class">
        </selector>
        <selector if="include.source">
            <and>
                <filename name="**/*.java">
                <not>
                    <selector unless="include.tests">
                        <filename name="**/*Test.java">
                    </selector>
                </not>
            </and>
        </selector>
    </or>
</fileset>

Java ソースファイルとテストソースおよびクラスファイルを条件付きで含むファイルセット。

カスタムセレクター

独自のセレクターを作成し、<custom> タグ内で指定することにより、セレクターコンテナ内で使用できます。

最初に、セレクタークラスを Java で記述する必要があります。セレクターになるために満たす必要がある唯一の要件は、単一のメソッドを含む org.apache.tools.ant.types.selectors.FileSelector インターフェイスを実装することです。詳細については、Ant でのセレクターのプログラミングを参照してください。

それが記述されたら、<custom> タグを使用してビルドファイルに含めます。

クラスをセレクターとして使用するために <custom> を使用する方法を次に示します

<fileset dir="${mydir}" includes="**/*">
    <custom classname="com.mydomain.MySelector">
        <param name="myattribute" value="myvalue"/>
    </custom>
</fileset>

また、多くのコアセレクターは、<param> 要素を使用して属性を指定することにより、カスタムセレクターとして使用できます。これらは次のとおりです。

• クラス名が org.apache.tools.ant.types.selectors.ContainsSelector のContains セレクター
• クラス名が org.apache.tools.ant.types.selectors.DateSelector のDate セレクター
• クラス名が org.apache.tools.ant.types.selectors.DepthSelector のDepth セレクター
• クラス名が org.apache.tools.ant.types.selectors.FilenameSelector のFilename セレクター
• クラス名が org.apache.tools.ant.types.selectors.SizeSelector のSize セレクター

<custom> を通じてセレクターを使用するために書き換えられた、Depth セレクターのセクションの例を次に示します。

<fileset dir="${doc.path}" includes="**/*">
    <custom classname="org.apache.tools.ant.types.selectors.DepthSelector">
        <param name="max" value="1"/>
    </custom>
</fileset>

ベースディレクトリと、その下の 1 つのディレクトリにあるすべてのファイルを選択します。

独自のセレクターの記述に関する詳細については、Ant でのセレクターのプログラミングを参照してください。