Custom Components

Overview

概要

Custom components are conditions, selectors, filters and other objects that are defined outside ant core.

カスタムコンポーネントとは、condition, selector, filterと、 ant core以外で定義されたそれら以外のオブジェクトです。

In Ant 1.6 custom conditions, selectors and filters has been overhauled.

Ant 1.6 で、カスタムcondition, selector, filter は全面的に洗いなおされました。

It is now possible to define custom conditions, selectors and filters that behave like Ant Core components. This is achieved by allowing datatypes defined in build scripts to be used as custom components if the class of the datatype is compatible, or has been adapted by an adapter class.

現在は、カスタムcondition, selector, filterを、 Antのコアコンポーネントと同じ振る舞いをするように定義できます。 ビルドスクリプト中で定義したデータタイプが、 互換、またはアダプタクラスによって適合できるクラスのデータであれば、 それをカスタムコンポーネントとして利用でき、 コアコンポーネントと同じように振る舞います。

The old methods of defining custom components are still supported.

カスタムコンポーネントを定義する古い方法も残されています。

Definition and use

定義と利用

A custom component is a normal Java class that implements a particular interface or extends a particular class, or has been adapted to the interface or class.

カスタムコンポーネントは、特有のインタフェースやクラスを拡張するか適合するように作成した、 通常のJavaのクラスです。

It is exactly like writing a custom task. One defines attributes and nested elements by writing setter methods and add methods.

それはカスタムタスクを作成するのと似ています。 属性や内部要素を、setterメソッドやaddメソッドを実装することで定義します。

After the class has been written, it is added to the ant system by using <typedef>.

クラスを作成したら、<typedef>を使ってAntシステムに組み込みます。

Custom Conditions

カスタム condition

Custom conditions are datatypes that implement org.apache.tools.ant.taskdefs.condition.Condition. For example a custom condition that returns true if a string is all upper case could be written as:

カスタム condition は、 org.apache.tools.ant.taskdefs.condition.Condition を実装したデータタイプです。 たとえば、文字列がすべて大文字であるときに true を返すような カスタム conditionは以下のようになります:

package com.mydomain;

import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.taskdefs.condition.Condition;

public class AllUpperCaseCondition implements Condition {
    private String value;

    // The setter for the "value" attribute"value"属性のセッタメソッド
    public void setValue(String value) {
        this.value = value;
    }

    // This method evaluates the conditionコンディションを評価するメソッド
    public boolean eval() {
        if (value == null) {
            throw new BuildException("value attribute is not setvalue属性がセットされていません");
        }
        return value.toUpperCase().equals(value);
   }
}
      

Adding the condition to the system is achieved as follows:

以下のようにして、この condition をシステムに組み込みます:

<typedef
    name="alluppercase"
    classname="com.mydomain.AllUpperCaseCondition"
    classpath="${mydomain.classes}"/>
      

This condition can now be used wherever a Core Ant condition is used.

この condition は コア condition が使えるところならどこでも使うことができます。

<condition property="allupper">
   <alluppercase value="THIS IS ALL UPPER CASE"/>
</condition>
      

Custom Selectors

カスタム Selector

Custom selectors are datatypes that implement org.apache.tools.ant.types.selectors.FileSelector.

カスタム selector は、 org.apache.tools.ant.types.selectors.FileSelector を実装したデータタイプです。

There is only one method required. public boolean isSelected(File basedir, String filename, File file). It returns true or false depending on whether the given file should be selected or not.

public boolean isSelected(File basedir, String filename, File file) というメソッドをオーバライドする必要があります。 引数の file が選択されるべきであれば true 、そうでなければ false を返します。

An example of a custom selection that selects filenames ending in ".java" would be:

たとえば、ファイル名が ".java" で終わっているものを選択するような カスタム selection は以下のようになります:

package com.mydomain;
import java.io.File;
import org.apache.tools.ant.types.selectors.FileSelector;
public class JavaSelector implements FileSelector {
    public boolean isSelected(File b, String filename, File f) {
       return filename.toLowerCase().endsWith(".java");
    }
}
      

Adding the selector to the system is achieved as follows:

以下のようにして、この selector をシステムに組み込みます:

<typedef
    name="javaselector"
    classname="com.mydomain.JavaSelector"
    classpath="${mydomain.classes}"/>
      

This selector can now be used wherever a Core Ant selector is used, for example:

このセレクタは コア selector が使えるところならどこでも使用できます。例えば:

<copy todir="to">
   <fileset dir="src">
      <javaselector/>
   </fileset>
</copy>
      

One may use org.apache.tools.ant.types.selectors.BaseSelector, a convenience class that provides reasonable default behaviour. It has some predefined behaviours you can take advantage of. Any time you encounter a problem when setting attributes or adding tags, you can call setError(String errmsg) and the class will know that there is a problem. Then, at the top of your isSelected() method call validate() and a BuildException will be thrown with the contents of your error message. The validate() method also gives you a last chance to check your settings for consistency because it calls verifySettings(). Override this method and call setError() within it if you detect any problems in how your selector is set up.

既定の動作をするために、 org.apache.tools.ant.types.selectors.BaseSelector コンビニエンスクラスを使用できます。 これには、いくつかの動作が定義済みです。 属性を設定したり、タグを追加したりしようとしたときに問題が生じたら、 setError(String errmsg) を呼び出して、そこに問題があることを示すことができます。 そのあと、isSelected()の実装の最初でvalidate()を呼び出せば、 設定したエラーメッセージを内容とする BuildExceptionがスローされます。 ついでに、validate()メソッドはverifySettings()を呼ぶので、 設定の一貫性をチェックすることができる最後の機会となりえます。 セレクタをセットアップする際に問題があったときには setError()を呼び出すように、 このメソッドをオーバライドしてください。

To write custom selector containers one should extend org.apache.tools.ant.types.selectors.BaseSelectorContainer. Implement the public boolean isSelected(File baseDir, String filename, File file) method to do the right thing. Chances are you'll want to iterate over the selectors under you, so use selectorElements() to get an iterator that will do that.

org.apache.tools.ant.types.selectors.BaseSelectorContainer を拡張することで、カスタムselectorのコンテナを実装することができます。 public boolean isSelected(File baseDir, String filename, File file) メソッドを意図通りに実装して下さい。 selectorElements()を使用して、 包含するselectorを順に処理するためのイテレータを取得できます。

For example to create a selector container that will select files if a certain number of contained selectors select, one could write a selector as follows:

例えば、内包するselectorが選択するファイルのうちの一定数を選択するようなコンテナは、 以下のように実装します:

public class MatchNumberSelectors extends BaseSelectorContainer {
    private int number = -1;
    public void setNumber(int number) {
        this.number = number;
    }
    public void verifySettings() {
        if (number < 0) {
           throw new BuildException("Number attribute should be setnumber属性が設定されていません");
        }
    }
    public boolean isSelected(File baseDir, String filename, File file) {
        validate();
        int numberSelected = 0;
        for (Enumeration e = selectorElements(); e.hasNextElement();) {
            FileSelector s = (FileSelector) e.nextElement();
            if (s.isSelected(baseDir, filename, file)) {
                numberSelected++;
            }
        }
        return numberSelected == number;
    }
}
      

To define and use this selector one could do:

このセレクタを定義して利用するためには以下のようにします:

<typedef name="numberselected"
         classname="com.mydomain.MatchNumberSelectors"/>
...
<fileset dir="${src.path}">
   <numberselected number="2">
      <contains text="script" casesensitive="no"/>
      <size value="4" units="Ki" when="more"/>
      <javaselector/>
   </numberselected>
</fileset>
      

The custom selector

カスタム selector

The custom selector was the pre ant 1.6 way of defining custom selectors. This method is still supported for backward compatibility.

ここでの カスタム selector は、ant 1.6 までのカスタムセレクタを定義していた手段です。 このメソッドは下位互換性維持のために、依然サポートされています。

You can write your own selectors and use them within the selector containers by specifying them within the <custom> tag.

セレクタコンテナ内で、<custom>タグを使って、 独自のselectorを実装して使用することができます。

To create a new Custom Selector, you have to create a class that implements org.apache.tools.ant.types.selectors.ExtendFileSelector. The easiest way to do that is through the convenience base class org.apache.tools.ant.types.selectors.BaseExtendSelector, which provides all of the methods for supporting <param> tags. First, override the isSelected() method, and optionally the verifySettings() method. If your custom selector requires parameters to be set, you can also override the setParameters() method and interpret the parameters that are passed in any way you like. Several of the core selectors demonstrate how to do that because they can also be used as custom selectors.

新しいカスタムselectorを作成するには、 org.apache.tools.ant.types.selectors.ExtendFileSelector を実装する必要があります。 org.apache.tools.ant.types.selectors.BaseExtendSelectorという、 <param>タグをサポートするためのメソッドが実装されている コンビニエンス基底クラスを拡張するのが簡単です。 まず、isSelectedメソッドをオーバライドし、 必要に応じてverifySettings()メソッドをオーバライドします。 もしカスタムセレクタがパラメータが設定されている必要があるなら、 setParameters()メソッドをオーバライドしてパラメータを 受け取れます。コアセレクタもカスタムセレクタと同じように使用されるので、 コアセレクタがいいサンプルになります。

Once that is written, you include it in your build file by using the <custom> tag.

実装したら、<custom>タグを使ってビルドファイルに組み込みます。

Attribute Description Required
classname The name of your class that implements org.apache.tools.ant.types.selectors.FileSelector. Yes
classpath The classpath to use in order to load the custom selector class. If neither this classpath nor the classpathref are specified, the class will be loaded from the classpath that Ant uses. No
classpathref A reference to a classpath previously defined. If neither this reference nor the classpath above are specified, the class will be loaded from the classpath that Ant uses. No
属性 説明 必須
classname org.apache.tools.ant.types.selectors.FileSelectorを実装したクラス名 Yes
classpath カスタムセレクタのクラスを読み込むためのclasspath。 classpathとclasspathrefのどちらも指定していない場合は、 クラスはAntが用いているクラスパスからロードされる。 No
classpathref 事前に定義されたクラスパスの参照。 classpathとclasspathrefのどちらも指定していない場合は、 クラスはAntが用いているクラスパスからロードされる。 No

Here is how you use <custom> to use your class as a selector:

以下は、作成したクラスを、<custom>タグを使用して、 作成したクラスをセレクタとして利用する方法です:

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

The core selectors that can also be used as custom selectors are

コアセレクタもカスタムセレクタのように使用できます

Here is the example from the Depth Selector section rewritten to use the selector through <custom>.

<custom>を使用して Depthセレクタを書き直している例を示します。

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

Selects all files in the base directory and one directory below that.

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

Custom Filter Readers

カスタム Filter Readers

Custom filter readers selectors are datatypes that implement org.apache.tools.ant.types.filters.ChainableReader.

カスタムフィルタリーダセレクタとは、 org.apache.tools.ant.types.filters.ChainableReader を実装しているデータタイプです。

There is only one method required. Reader chain(Reader reader). This returns a reader that filters input from the specified reader.

Reader chain(Reader reader) という、 指定したリーダーからの入力をフィルタするようなリーダーを返すメソッドだけが必要です。

For example a filterreader that removes every second character could be:

一文字づつ削除するようなフィルタリーダーは以下のようになります:

public class RemoveOddCharacters implements ChainableReader {
   public Reader chain(Reader reader) {
      return new BaseFilterReader(reader) {
          int count = 0;
          public int read() throws IOException {
              while (true) {
                int c = in.read();
                if (c == -1) {
                    return c;
                }
                count++;
                if ((count % 2) == 1) {
                    return c;
                }
              }
          }
      }
   }
}
      

For line oriented filters it may be easier to extend ChainableFilterReader an inner class of org.apache.tools.ant.filters.TokenFilter.

org.apache.tools.ant.filters.TokenFilterChainableFilterReader 内部クラスを拡張することで、 行指向フィルタを簡単に作成することができます。

For example a filter that appends the line number could be

行数を付加するフィルタは以下のようになります:

public class AddLineNumber extends ChainableReaderFilter {
   private void lineNumber = 0;
   public String filter(String string) {
      lineNumber++;
      return "" + lineNumber + "\t" + string;
   }
}
      

Copyright © 2003-2004 The Apache Software Foundation. All rights Reserved.
[訳注:これは的場聡弘が翻訳しました。 日本語訳に対するコメントがあれば report@jajakarta.orgに送ってください]