セレクター

セレクターとは、 <include><exclude> タグによって与えられるファイル名以外の基準をもとに、ファイルセットを構成するファイルを選択する仕組みです。

セレクターの使い方

セレクターはファイルセットの要素であり、ファイルセットの中に現れます。 またセレクターは、<selector> タグを使用し、それを参照として使用することでどんなターゲットの外部でも定義可能です。

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

コアセレクター

コアセレクターはAntに標準で付いてきます。ファイルセットの中で使用可能であり、またセレクターコンテナの中に含むこともできます。

コアセレクターは:

コンテインズセレクター

ファイルセット中の<contains> タグはそのファイルセットで定義されたファイルを text 属性で指定された文字列を含むものだけに限定します。 .

    
属性 説明 必須
text全てのファイルに含まれなければならない文字を指定します。 Yes
casesensitive text 属性中の文字列を調べるときに大文字小文字を区別するかどうか。 デフォルトでは真です。 No
ignorewhitespace text 属性中の文字列を調べるときに文字列内の空白を無視するかどうか。 デフォルトは偽です。 No

コンテインズセレクターの使用例:

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

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

デイトセレクター

ファイルセット中の<date> タグはincludeタグで指定されたファイルに制限を設けます。 最終更新日がセレクターによって指定された期限を満たさないタグは結局選択されません。

属性 説明 必須
datetime MM/DD/YYYY HH:MM AM_or_PMフォーマットの文字列を使用して 調べる日付と時間を指定します。 2つのうちのどちらか1つ
millis 1970年からのミリ秒値。 通常はdatetime属性を使用する方が簡易です。
when 選択されるべきファイルを、それらファイルの最終更新時刻が指定された値の前、後まはた同じかどうか で決定するために日付をどのように解釈するかを指示します この属性で受け付ける値は:
  • before - 最終更新日が指示された日付より前のファイルを選択します。
  • after - 最終更新日が指示された日付より後のファイルを選択します。
  • equal - 最終更新日がこの正確な日付であるファイルを選択します。
デフォルトはequalです。
No

デイトセレクターの使用例:

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

2001年1月1日の真夜中より前に最終更新された全てのJARファイルを選択します。

ディペンドセレクター

<depend> タグは最終更新日時が他の場所に存在する同等ファイルより新しいファイルを選択します。

<depend> タグは比較対象ファイルの位置を決定するために 包含された<mapper> 要素の使用をサポートします。 もし<mapper> 要素が1つも指定されなかった場合は、identity タイプマッパーが使用されます。

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

属性 説明 必須
targetdir 比較対照ファイルを探すための基準ディレクトリ。 正確な位置はこの属性と、<mapper> 要素ある場合は、それらの組み合わせに依存します。 Yes
granularity ファイルの古さを判断する際に使用するミリ秒単位の猶予。 これは全てのファイルシステムが最終更新日の履歴作成にミリ秒単位をサポートしない為です。 ディフォルトは0ミリ秒で、DOSシステムでは2秒です。 No

ディペンドセレクターの使用例:

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

1.5リリースで更新された全てのJavaソースファイルが選択します。

デプスセレクター

<depth> タグはファイルセットの基準ディレクトリに対してどれくらいのディレクトリ階層の深さに ファイルがあるかを元にしてファイルを選択します。

属性 説明 必須
min ファイルが存在しなければならない基準ディレクトリからの階層の最小値。ディフォルトは制限なし。 2つのうちのどちらか1つ
max ファイルが存在しなければならない基準ディレクトリからの階層の最大値。ディフォルトは制限なし。

デプスセレクターの使用例:

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

基準ディレクトリとそれより1つ下のディレクトリにある全てのファイルを選択します。

ディファレントセレクター

The <different> タグは別の場所にある同等ファイルと’異なる’と判別されたファイルを選択します。比較するファイルを異なると判別するルールは下記です:

  1. 比較する同等ファイルが存在しない場合
  2. ファイルの大きさが違う場合
  3. ignoreFileTimes がOFFにセットされ、 異なったタイムスタンプを持つ場合
  4. バイトチェックで異なる場合
たとえ先行するタスクで常にアウトプットファイルを生成する 場合でも、後続のタスクにおいて、Different Selectorで 作成されたコピーに対して実行すれば、単にタイムスタンプだけで 判断するのではなく、実際のファイルの中身を判断します。 例えば、ウェッブサイトからフェッチされるものや、プログラムの アウトプットファイルです。チェック量を減らすために、このタスクを <copy>タスク内で使用したときにはソースファイルと目的ファイル のタイムスタンプを広げるためにpreservelastmodifiedをセットしてください。

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

属性 説明 必須
targetdir 比較対照ファイルを探す基準ディレクトリ。 正確な位置はこの属性と、<mapper>要素により特定されます。 Yes
ignoreFileTimes 比較対照時にファイルの更新時間を使用するかどうか。 デフォルトは真です。(時間差は無理されます。) No
granularity ファイルの更新日付を判断する際に使用するミリ秒単位の猶予。 これは全てのファイルシステムが最終更新日の履歴作成にミリ秒単位をサポートしない為です。 ディフォルトは0ミリ秒で、DOSシステムでは2秒です。 No

ディファレントセレクターの使用例:

<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> タグはファイルセット中の<include><exclude>のように機能します。 しかし、このセレクターを代わりに使用することによって、セレクターコンテナ が選択した物を使い、他の全てのセレクターと組み合わせることができます。

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

属性 説明 必須
name 選択するファイル名。nameパラメータはAnt標準のワイルドカード文字を含むことができます。 Yes
casesensitive ファイル名を探すときに大文字小文字を区別するかどうか。 デフォルトは"真"です。 No
negate このファイル選択の機能を逆にするかどうか。 結果的にincludeタグではなくexcludeタグと似た動作をします。 デフォルトは"偽"です。 No

ファイルネームセレクターの使用例:

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

全てのカスケーディングスタイルシートを選択します。<

プレゼントセレクター

<present> タグは他のディレクトリ階層中の同一ファイルを選択します。

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

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

属性 説明 必須
targetdir 比較対照ファイルを探す基準ディレクトリ。 正確な位置はこの属性と、<mapper>要素により特定されます。 Yes
present ファイルがsrcディレクトリのみ存在する、もしくはsrcとtargetディレクトリツリーの両方に存在するべきか。 有効な値は:
  • srconly - targetディレクトリツリーに存在せず、srcディレクトリツリーのみに存在する場合にファイルを選択します。
  • both - rcとtargetディレクトリツリー両方に存在する場合にのみファイルを選択します。
デフォルトはbothです。この属性を"srconly"にした場合は、セレクターを<not>セレクターコンテナに含む場合と同等です。
No

プレゼントセレクターの使用例:

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

1.5リリースで新規のJavaソースファイルを全て選択します。

レギュラーエクスプレッションセレクター

ファイルセット内の<containsregexp>タグは そのファイルセット内のファイルをexpression属性で 指定された正規表現とマッチするファイルのみに限定します。

属性 説明 必須
expression 全てのファイルがマッチしなければならない正規表現を指定します Yes

レギュラーエクスプレッションセレクターの使用例:

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

正規表現にマッチするファイルを選択する (4〜6 の数字に続いてピリオドがあり、0〜9の数字)

サイズセレクター

ファイルセット中の<size> タグは includeタグで指定されたファイルが指定したサイズ制限を満たさない場合に選択しない制限をかけます。

属性 説明 必須
value ファイルの制限されるサイズ. Yes
units value 属性で表される単位。 "k","M", or "G" のような標準的な1文字SI表示を使用するとき、1000倍された値が使用されます。 もし2の累乗の単位を使用したいなら、IEC標準を使用してください: "Ki" を1024とし、"Mi" を1048576とします。 デフォルトでは単位はなく、value 属性の値は実バイト数を表します。 No
when サイズ値をどの様に扱うか指定します。サイズが指定された値より小さい、大きい、まはた同じファイルが 選択されます。この属性で受け付ける値は:
  • less - 指示されたサイズより小さいファイルを選択
  • more - 指示されたサイズより大きいファイルを選択
  • equal - 正確なサイズのファイルを選択
デフォルトはlessです。
No

サイズセレクターの使用例:

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

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

タイプセレクター

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

属性 説明 必須
type 選択対象となるファイルのタイプ 設定値:
  • file - 通常ファイル
  • dir - ディレクトリ
Yes

ディレクトリ${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. 比較結果を元に選択を行う。
比較、ハッシュ値の計算、保存は特別なインターフェイスの実装によって行われます。 したがって、その他の追加パラメータが存在する場合があります。

属性 説明 必須
algorithm 使用されるアルゴリズムの種類 設定可能な値は(詳細は後述する):
  • hashvalue - HashvalueAlgorithm
  • digest - DigestAlgorithm
No, ディフォルトはdigest
cache 使用されるキャッシュの種類 設定可能な値は(詳細は後述する):
  • propertyfile - PropertyfileCache
No, ディフォルトはpropertyfile
comparator 使用されるコンパレータの種類 設定可能な値は(詳細は後述する):
  • equal - EqualComparator
  • rule - java.text.RuleBasedCollator
No, ディフォルトはequal
update 値が異なった場合にキャッシュを更新するか否か? (ブール条件) No, ディフォルトは
seldirs ディレクトリは選択されるべきか否か? (ブール条件) No, ディフォルトは

これらの属性はネストした <param/> タグと共に使用できます。<param/>タグは下記のルールに従う場合、 他の値を設定できます。

Algorithmエs
Name Description
hashvalue ファイルの内容をjava.lang.Stringに読み込み、 hashValue()を使用する。その他の設定は不要。
digest java.security.MessageDigestを使用する。このアルゴリズムは下記の属性をサポートする:
  • algorithm.algorithm (任意): Digestアルゴリズムの名前 (例: 'MD5' or 'SHA', ディフォルト = MD5)
  • algorithm.provider (任意): Digestプロバイダの名前 (ディフォルト = null)
Cacheエs
propertyfile java.util.Propertiesクラスを使用し、ファイルするためにロードし格納する可能性。 このキャッシュの実装は下記の属性をサポートする:
  • cache.cachefile (optional): プロパティファイルの名前 (ディフォルト = cache.properties)
Comparatorエs
equal 単純なオブジェクト比較
rule オブジェクト比較にjava.text.RuleBasedCollatorを使用

モディファイドセレクターの使用例:

    <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>
    

ホームページ作成の構築環境でこのセレクターを用いる有効な方法 (e.g. with Apache Forrest). 更新された全てのファイルがサーバーへアップロードされる。CacheSelectorは多くのアップロード時間を短縮します。

セレクターコンテナ

より複雑な選択物を作成するには、他のセレクターを含む様々なセレクターを使用することができます。 それらはいろんな方法で子セレクターによる選択物を組み合わせます。

セレクターコンテナは:

全てのセレクターコンテナは、他のセレクターコンテナを含め、他のどんなセレクターを要素として含むことができます。 コンテナを使用することで、selectorタグは任意に深くすることができます。 ここにコンテナ内に許容されるselector要素の完全な一覧があります:

アンドセレクター

<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>

2001年1月1日午前12時から更新されていない4096バイトより大きい全てのJARファイルを選択します。

マジョリティセレクター

<majority> タグに包含された要素の過半数が選択する場合にそのファイルを選択します。 同等数の場合はallowtie 属性によって指定されます。

属性 説明 必須
allowtie あるファイルを選択するセレクターと選択しないセレクターが同数の場合に そのファイルが選択されるべきかどうかどうか。 デフォルトは真です。 No

マジョリティセレクターの使用例:

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

"project"、 "taskdef" 、 "IntrospectionHelper"の3つの語句のうち2つ以上を含む全てのHTMLファイルを選択します。(3つ目の語句は大文字小文字を 区別する)

ナンセレクター

<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> タグに含まれた単一のセレクターの意味を逆転します。

ノットセレクターの使用例:

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

rcディレクトリ中にある"test"という文字列を含まない全てのファイルを選択します。

オアセレクター

<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"属性を使用する事によって成立します。

属性 説明 必須
if 指定されたプロパティが設定されている場合、ファイルを選択する。 No
unless 指定されたプロパティが設定されていない場合、ファイルを選択する。 No

セレクターリファレンスの使用例:

<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>

最新かつ同等なclassファイルと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ソースファイルとtestソースとclassファイルを条件付で含むファイルセット

カスタムセレクター

自分自身のセレクターを書くことができ、それを<custom> タグ中で指定し、 セレクターコンテナの中で使用することができます。

まず、自分自身のセレクタークラスをJavaで書かなければなりません。 セレクターとして満たさなければならないただ1つの必要条件は、1つのメソッドを持つ org.apache.tools.ant.types.selectors.FileSelector インターフェースを実装することです。 詳しくはProgramming Selectors in Ant を見てください。

セレクタークラスを作成後、それを<custom>タグを使ってビルドファイルに含みます。

属性 説明 必須
classname org.apache.tools.ant.types.selectors.FileSelectorを実装する自身で作成したクラスの名前。. Yes
classpath カスタムセレクタークラスをロードするために使用するクラスパス。 もしこのclasspathとclasspathrefのどちらも指定されない場合、そのクラスはAntが使用しているクラスパスからロードされます。 No
classpathref 既に定義されているクラスパスへの参照。 もしこの参照と上記classpathのどちらも指定されない場合、そのクラスはAntが使用しているクラスパスからロードされます。 No

自身が作成したクラスをセレクターとして使用するための<custom> タグ使用例:

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

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

<custom>タグを通してセレクターを使用するように書き直したデプスセレクター部分の例:

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

基準ディレクトリとその1つ下のディレクトリにある全てのファイルを選択します。

カスタムセレクターを作成する事に関するより詳しい情報については、 Programming Selectors in Antを参考にしてください。


Copyright © 2002-2004 The Apache Software Foundation. All rights Reserved.

[訳注:これは松田明子が翻訳しました。日本語訳に対するコメントがあれば report@jajakarta.orgに送ってください]