'BuildListener'에 해당되는 글 1건

  1. 2013.08.12 [번역] Apache Ant - 사용자 태스크 작성하기

바로 이전 포스트에서 SVNANT를 이용하여 Ant로 SVN을 관리하는 방법에 대해 다루었습니다. 그런데, SVNANT 같은 것은 어떻게 만드는 것일까요? 사실 SVNANT 뿐만 아니라 ant-contrib와 같은 모든 Ant의 서드파티 플러그인들은 Ant가 제공하는 태스크(Task) 확장 기능에 기반하고 있습니다. 오늘은 이 방법에 대해 다뤄볼까 합니다.

본 번역은 Apache Ant에서 제공하는 공식 문서 중 하나를 번역한 것입니다. 사용자 정의 태스크를 만드는 방법, 태스크의 생명주기(Life Cycle), Ant와의 연동 등등 자세하게 다루고 있어 이를 통해 내가 원하는 Ant 태스크를 손쉽게 만들 수 있습니다. 원문의 주소는 http://ant.apache.org/manual/develop.html 입니다.

자 그럼 이제 시작해볼까요.



Apache Ant를 이용한 개발


사용자 태스크 작성하기(Writing your own Task)

 

사용자 태스크를 만드는 방법은 아주 간단합니다.


  1. org.apache.tools.ant.Task 클래스나, 태스크들이 확장할 수 있도록 만들어 놓은 그 외의 클래스들을 상속하여 자바 클래스를 만듭니다.
  2. 각각의 속성들을 위한 setter 메소드들을 만듭니다. setter 메소드들은 모두 하나의 입력값(argument)만을 받는 public void 메소드여야 합니다. 메소드명은 set으로 시작되어야 하고, 그 뒤에 속성명이 나와야 하는데, 첫 글자는 대문자로 지정되어야 하며 그 외에는 소문자로 지정*되어야 합니다. 즉, 속성명이 file인 경우 setFile이라고 하는 메소드를 생성해야 하는 것입니다. 입력값의 유형(type)에 맞게 Ant가 자동으로 데이터 타입에 대한 전환을 수행할 것입니다. 이 내용은 아래에서 다루고 있습니다.
  3. 만약 여러분이 작성한 태스크가 포함된 엘리먼트(nested element)로 다른 태스크들을 포함하고 있어야 한다면(parallel 태스크처럼), 작성된 클래스는 반드시 org.apache.tools.ant.TaskContainer 인터페이스를 구현해야 합니다. 만약 그렇게 했다면, 그 태스크는 그 외의 다른 포함 엘리먼트들을 지원할 수 없게 됩니다. 이 내용은 아래에서 다루고 있습니다. 
  4. 먄약 태스크가 character 데이터(시작 태그와 끝 태그 내에 포함되어 있는 문자열**)를 지원해야 한다면, public void addText(String) 메소드를 작성하세요. Ant는 Ant가 태스크에 전달하는 텍스트에 속성(properties)를 확장***하지 않는다는 것에 주의하세요.
  5. 포함되어있는 각각의 엘리먼트들을 위해 create, add 혹은 addConfigured 메소드를 작성하세요. create 메소드는 반드시 public 메소드여야 하고, 입력값이 없어야 하며, Object형을 리턴하여야 합니다. create 메소드의 이름은 반드시 create로 시작되어야 하고, 그 위에 엘리먼트명이 따라와야 합니다. add(혹은 addConfigured) 메소드는 public void  메소드이어야 하며, 입력값이 없는 기본 생성자를 갖고 있는 Object 유형의 입력값 하나만 지정되어야 합니다. add(addConfigured) 메소드의 이름은 add(addConfigured)로 시작되어야 하며, 엘리먼트 이름이 그 뒤에 따라와야 합니다. 자세한 내용은 아래에서 확인할 수 있습니다.
  6. 입력값이 없고 BuildExeption을 던지는 public void execute 메소드를 작성합니다. 이 메소드에서 태스크의 작업이 수행됩니다. 


* 사실 Ant에서 첫 번째 문자 외의 대소문자는 크게 문제가 되지 않지만, 나머지를 모두 소문자로 처리하는 것이 관습적으로 좋습니다.

** CDATA 섹션을 의미합니다. - 옮긴이

*** 속성을 확장(expand properties)한다는 말은 자동 형변환을 의미하는 듯 합니다. - 옮긴이


스크의 생명주기(The Life Cycle of a Task)


  1. 태스크에 대응하는 태그를 포함하고 있는 XML 엘리먼트는 parser가 작동하면서 UnknownElement로 변환됩니다. 이 UnknownElement는 대상 객체 내의 목록에 추가되거나 다른 UnknownElement 내에 재귀적으로(recursively) 추가됩니다. 
  2. 대상 객체가 실행(execute)될 때, 각각의 UnknownElement들은 perform() 메소드를 통해 호출됩니다.  이것이 태스크를 객체화(instantiate)합니다. 이 말은, 태스크들은 오직 런타임시에만 객체화된다는 의미입니다.
  3. 태스크들은 상속받은 project와 location 변수들을 통해 자신을 포함하고 있는 프로젝트와 빌드파일이 속해 있는 위치를 얻습니다.
  4. 만약 사용자가 태스크에 id 속성을 지정하였다면, 프로젝트는 런타임시에 새롭게 생성된 태스크에 대한 참조(reference)를 등록합니다.
  5. 이 태스크는 상속받은 target 변수를 통해 자신이 속해있는 대상(target)에 대한 참조를 얻습니다.
  6. init() 메소드가 런타임시에 호출됩니다.
  7. 이 태스크에 대응하는 XML 엘리먼트의 모든 자식 엘리먼트들은 런타임시에 createXXX() 메소드를 통해 생성되거나, addXXX() 메소드를 통해 객체화되어 태스크에 추가됩니다. addConfiguredXXX() 메소드에 대응되는 자식 엘리먼트들은 addConfiguredXXX() 메소드가 호출되는 시점이 아니라 이 때에 생성됩니다. 
  8. 태스크 내의 모든 속성들이 런타임시에 setXXX 메소드를 통해 설정됩니다.
  9. 이 태스크에 대응하는 XML 엘리먼트 내의 character 데이터 섹션의 내용이 런타임시에 addText 메소드를 통해 태스크에 추가됩니다.
  10. 모든 자식 요소의 모든 속성들이 런타임시에 그에 대응하는 setXXX 메소드를 통해 설정됩니다. 
  11. 만약 이 태스크에 대응하는 XML 엘리먼트의 자식 엘리먼트들이 addConfiguredXXX() 메소드를 위해 생성되었다면, 이 메소드들이 이 때 호출됩니다.
  12. execute() 메소드가 런타임시에 호출됩니다. 만약 target1과 target2가 모두 target3에 의지하고 있다면, 'target1 target2'와 같이 두 개의 target을 동시에 실행하면 target3를 두 번 실행하게 됩니다. 


속성값들에 대한 Ant의 형변환


Ant는 그에 대응하는 setter 메소드로 값을 전달하기 이전에 언제나 그 속성을 확장할 것입니다. Ant 1.8 이후부터, Ant의 속성 처리를 확장하는 것이 가능한데, 하나의 속성 참조를 포함하는 스트링에 대한 처리 결과로 스트링이 아닌 객체가 될 수도 있다는 말입니다. 이는 그 유형에 맞는 setter 메소드를 통해 직접 수행됩니다. 이것이 수행되기 위해서는 기본을 뛰어넘는 개입이 필요하기 때문에, 이것을 사용할 때에는 속성값에 그 의도를 나타내는 플래그를 추가하는 것이 바람직합니다.

속성에 대한 setter를 작성하는 가장 보편적인 방법은 java.lang.String 입력값을 사용하도록 하는 것입니다. 이 경우 Ant는 (속성 확장 후) 그 리터럴 값을 태스크로 전달하게 됩니다. 하지만 이것 외에 추가적으로 처리되는 내용이 있습니다. setter 메소드의 입력값의 유형이 String이 아닐 경우 다음과 같은 작업을 수행합니다.


  • boolean인 경우 : 빌드 파일에서 지정된 값이 true, yes, on 중 하나라면 true 값이, 그렇지 않으면 false 값이 전달됨
  • char 거나 java.lang.Character인 경우 : 빌드 파일에 지정된 값의 첫 번째 문자가 전달됨
  • 원시자료형인 경우 : 해당 원시자료형에 맞는 유형으로 변한되어 전달됨. 그러므로 속성 값으로 숫자가 아닌 값이 입력되지 않도록 확인해야 함
  • java.io.File인 경우 : 일단 빌드파일에서 지정된 값이 파일에 대한 절대 경로인지 확인함. 만약 아니라면 프로젝트의 basedir을 기준으로 상대 경로로 해석되어 전달됨
  • org.apache.tools.ant.types.Resource인 경우 : java.io.File인 경우에서와 마찬가지로 일단 File로 인식된 다음에 그것이 org.apache.tools.ant.types.resources.FileResource로서 전달됨. (Ant 1.8 이후부터)
  • org.apache.tools.ant.types.Path인 경우 : 빌드 파일에 지정된 입력값을 콜론(:)이나 세미콜론(;)으로 자름(tokenize). 상대 경로는 프로젝트의 basedir을 기준으로 한 상대 경로로 처리됨
  • java.lang.Class인 경우 : 빌드 파일에 지정된 값이 해석된 뒤, 시스템 클래스로더로부터 해당하는 이름의 클래스를 로딩하여 전달됨
  • 하나의 스트링 입력값을 받는 생성자를 갖고 있는 유형이라면 이 생성자에 빌드 파일에 포함된 값을 전달하여 객체가 생성됨
  • org.apache.tools.ant.types.EnumeratedAttribute인 경우 : Ant가 이 클래스들의 setValue 메소드를 호출함. 태스크가 열거된 속성(enumerated attribtues)를 지원해야 하는 경우에 사용함.(속성 값은 미리 지정된 값들의 집합에 포함되어 있어야 함)
  • Java5 enum인 경우 : 빌드파일에 지정된 값에 대응되는 enum 상수 값이 전달됨. EnumeratedAttribute를 사용하는 것보다 쉽고 코드가 깔끔해짐. 당연한 이야기지만 JDK1.4 이하에서는 사용할 수 없음. enumeration 내의 모든 재정의된 toString() 메소드들은 무시됨. 빌드 파일은 반드시 정의된 이름을 사용하여야 함(Enum.getName()을 확인할 것) enum 상수명을 빌드 파일 내에서 보기 좋게 하기 위해 Java의 명명 규칙과는 달리 소문자로 사용할 수 있음. Ant 1.7.0에서 처럼.


하나의 속성값에 대해 하나 이상의 setter 메소드가 있는 경우라면 어떻게 될까요? String 입력값을 받는 메소드 대신 다른 유형을 받는 메소드가 항상 선택됩니다. 두 개 이상의 setter 메소드들이 있다면 Ant가 알아서 선택하게 하나만 호출하게 되는데, 어떤 것이 호출될지는 알 수 없습니다. 이는 Java 가상 머신의 구현에 달려 있습니다.


포함된 엘리먼트에 대한 지원(Supporting nested elements)


작성된 태스크가 inner라는 이름의 엘리먼트를 포함해야 한다고 해 봅시다. 먼저 이 포함된 엘리먼트를 표상하는 클래스가 필요할 것입니다. 가끔은 중첩된 fileset 엘리먼트들을 지원하기 위해 org.apache.tools.ant.types.FileSet과 같은 Ant의 클래스들 중 하나를 사용할 수도 있습니다.

포함된 엘리먼트의 속성들이나 그것들에 포함된 자식 엘리먼트들은 태스크를 처리하는 데 사용된 메커니즘과 동일한 메커니즘으로 처리되어야 합니다. (예를 들어, 속성들을 위해서는 setter 메소드를, 중첩된 텍스트를 위해서는 addText를, 그리고 자식 엘리먼트를 위해서는 create/add/addConfigured 메소드를 사용합니다.)

<inner>라는 엘리먼트를 위해 사용할 NestedElement라는 클래스가 있다고 했을 때, 세 가지 옵션을 선택할 수 있습니다.


  1. public NestedElement createInner()
  2. public void addInner(NestedElement anInner)
  3. public void addConfiguredInner(NestedElement anInner)


이들 각각은 어떤 차이가 있을까요?

옵션1은 태스크에 NestedElement의 인스턴스를 생성해 줍니다. 그리고 이것은 유형(Type)에 대한 어떠한 제한도 없습니다. 옵션2와 옵션3의 경우, Ant가 NestedInner의 인스턴스를 태스크에 전달하기 전에 먼저 생성합니다. NestedInner 클래스는 입력값이 없는 생성자(no-arg constructor)나 Project 클래스를 입력값으로 받는 생성자 둘 중 하나를 갖고 있어야 합니다. 옵션1과 옵션2의 차이는 이것 밖에 없습니다.

옵션2와 옵션3의 차이점은 각각의 메소드에 해당 객체를 전달하기 전에 Ant가 어떤 작업을 하느냐 입니다. addInner는 생성자가 호출된 후 바로 객체를 받게 되지만, addConfiguredInner는 새로운 객체를 위한 속성값들과 포함된 자식들이 모두 처리된 다음에 그 객체를 전달받게 됩니다. 

이 옵션들 중 하나 이상을 사용하면 어떻게 될까요? 세 가지 옵션 중 하나가 실행될 것이지만, 어떤 것이 실행될지는 알 수 없습니다. 이 역시 Java 가상 머신의 구현에 따라 결정되기 때문입니다.


포함된 유형들(Nested Types)


<typedef>를 이용하여 정의된 임의의 유형을 포함하는 방법에는 두 가지가 있습니다.


  1. public void add(Type type)
  2. public void addConfigured(Type type)


이 두 옵션들의 차이점은 바로 위 섹션에서 설명했던 차이점과 동일합니다.

예를 들어, org.apache.tools.ant.taskdefs.condition.Condition 클래스 우형의 객체를 다뤄야 한다면 다음과 같이 하면 됩니다.

public class MyTask extends Task {
    private List conditions = new ArrayList();
    public void add(Condition c) {
        conditions.add(c);
    }
    public void execute() {
     // iterator over the conditions
    }
}


이 클래스는 다음과 같이 사용할 수 있습니다.

<taskdef name="mytask" classname="MyTask" classpath="classes"/>
<typedef name="condition.equals" classname="org.apache.tools.ant.taskdefs.conditions.Equals"/>
<mytask>
    <condition.equals arg1="${debug}" arg2="true"/>
</mytask>


조금 더 복잡한 예제는 다음과 같습니다.

public class Sample {
    public static class MyFileSelector implements FileSelector {
         public void setAttrA(int a) {}
         public void setAttrB(int b) {}
         public void add(Path path) {}
         public boolean isSelected(File basedir, String filename, File file) {
             return true;
         }
     }

    interface MyInterface {
        void setVerbose(boolean val);
    }        

    public static class BuildPath extends Path {
        public BuildPath(Project project) {
            super(project);
        }
        
        public void add(MyInterface inter) {}
        public void setUrl(String url) {}
    }

    public static class XInterface implements MyInterface {
        public void setVerbose(boolean x) {}
        public void setCount(int c) {}
    }
}



이 클래스는 Path를 구현하거나 상속하는 MyFileSelecteor와 MyInterface 클래스들을 정의하고 있습니다.  이 클래스들은 다음과 같은 방법으로 사용될 수 있습니다.

<typedef name="myfileselector" classname="Sample$MyFileSelector"
         classpath="classes" loaderref="classes"/>
<typedef name="buildpath" classname="Sample$BuildPath"
         classpath="classes" loaderref="classes"/>
<typedef name="xinterface" classname="Sample$XInterface"
         classpath="classes" loaderref="classes"/>

<copy todir="copy-classes">
   <fileset dir="classes">
      <myfileselector attra="10" attrB="-10">
         <buildpath path="." url="abc">
            <xinterface count="4"/>
         </buildpath>
      </myfileselector>
   </fileset>
</copy>


TaskContainer


TaskContainer는 addTask라는 하나의 메소드로 구성되어 있는데, 이 메소드는 포함된 엘리먼트를 위해 사용되는 add 메소드와 기본적으로 동일합니다. 태스크의 인스턴스는 태스크의 execute 메소드가 호출될 때 설정(속성값들과 포함되니 엘리먼트들이 처리됨)될 것이며 그 전에는 설정되지 않습니다.

execute 메소드가 호출될 것이라고 말했지만 사실은 그렇지 않습니다. 사실, Ant는 org.apache.tools.ant.Task의 perform 메소드를 호출하는데, 그러면 그 다음에 execute 메소드가 호출됩니다. 이 메소드는 빌드 이벤트들이 촉발될 수 있도록 합니다. 만약 태스크 내에서 execute 메소드를 직접 호출해야 한다면, 그 인스턴스의 execute 메소드 대신 perform 메소드를 호출해야 합니다.


예제(Java)


이제 System.out 스트림으로 메시지를 출력하는 우리의 태스크를 만들어봅시다. 이 태스크는 message라 불리는 하나의 속성을 가지고 있습니다.

package com.mydomain;

import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.Task;

public class MyVeryOwnTask extends Task {
    private String msg;

    // The method executing the task
    public void execute() throws BuildException {
        System.out.println(msg);
    }

    // The setter for the "message" attribute
    public void setMessage(String msg) {
        this.msg = msg;
    }
}


정말 쉽죠?

시스템에 이렇게 작성한 태스크를 추가하는 것 역시 매우 쉽습니다.


  1. Ant가 시작될 때 이 태스크를 구현한 클래스가 클래스패스에 있는지 확인합니다.
  2. 프로젝트에 <taskdef> 엘리먼트를 추가합니다. 이를 통해 태스크가 실제로 시스템에 추가됩니다.
  3. 나머지 빌드파일에서 이 태스크를 사용합니다.


예제(XML)


<?xml version="1.0"?>

<project name="OwnTaskExample" default="main" basedir=".">
  <taskdef name="mytask" classname="com.mydomain.MyVeryOwnTask"/>

  <target name="main">
    <mytask message="Hello World! MyVeryOwnTask works!"/>
  </target>
</project>


예제2 


태스크를 생성한 빌드파일에서 태스크를 사용하고 싶다면, target 엘리먼트 내에서 컴파일 수행 후에 <taskdef> 선언을 추가합니다. 그리고 그 코드가 조금 전 컴파일된 위치를 가리키는 taskdef의 classpath 속성을 사용합니다.

<?xml version="1.0"?>

<project name="OwnTaskExample2" default="main" basedir=".">

  <target name="build" >
    <mkdir dir="build"/>
    <javac srcdir="source" destdir="build"/>
  </target>

  <target name="declare" depends="build">
    <taskdef name="mytask"
        classname="com.mydomain.MyVeryOwnTask"
        classpath="build"/>
  </target>

  <target name="main" depends="declare">
    <mytask message="Hello World! MyVeryOwnTask works!"/>
  </target>
</project>


태스크를 (좀 더 영구적으로) 추가하는 또 다른 방법은, 태스크의 이름과 구현된 클래스명을 org.apache.tools.ant.taskdefs 패키지 내의 default.properties 파일에 추가하는 것입니다. 이렇게 하면 이 클래스가 마치 빌트-인 클래스인 것 처럼 사용할 수 있습니다.




빌드 이벤트들(Build Events)


Ant에서는 프로젝트를 빌드하는 데 필요한 태스크를 수행하는 과정에서 빌드 이벤트가 발생되도록 할 수 있습니다. 이 이벤트들을 처리하기 위해 Ant에 리스너를 추가할 수도 있습니다. 이 기능은, 예를 들어, Ant와 GUI를 연결하거나 Ant와 IDE를 통합할 때 사용될 수 있습니다.

빌드 이벤트를 사용하기 위해 Ant의 Project 객체를 생성할 필요가 있습니다. 그리고 나서 addBuildListener 메소드를 이용하여 프로젝트에 작성한 리스너를 추가할 수 있습니다. 리스너들은 org.apache.tools.antBuildListener 인터페이스를 구현해야 합니다. 리스너는 다음 이벤트들이 발생할 때 BuildEvent를 전달 받을 수 있습니다.


  • 빌드 시작
  • 빌드 종료
  • 타겟 시작
  • 타겟 종료
  • 태스크 시작
  • 태스크 종료
  • 메시지 로그됨

만약 빌드 파일이 <ant>나 <subant> 혹은 <antcall>을 이용하여 다른 빌드 파일을 실행하는 경우라면, 그 자신의 타겟과 태스크 수준의 이벤트를 발생시키는 새로운 "project"를 생성하는 것이 되므로, 이 경우에는 빌드 시작이나 종료와 같은 이벤트가 전달되지 않게 됩니다. Ant 1.6.2 부터는 이와 같은 경우 새로운 두 가지 이벤트를 처리하기 위한 BuildListener를 확장한 SubBuildListener라고 하는 인터페이스를 제공합니다. 이것이 처리하는 이벤트들은 다음과 같습니다.


  • 서브빌드 시작
  • 서브빌드 종료


이것을 처리해야 하는 경우라면, BuildListener 대신 이 새로운 인터페이스를 구현하기만 하면 됩니다.(물론 이 리스너를 등록해야 하구요.)

명령실행줄에서 리스너를 추가하고 싶다면 -listener 옵션을 이용할 수도 있습니다. 예를 들어 다음과 같습니다.


ant -listener org.apache.tools.ant.XmlLogger


위 명령을 사용하면 Ant가 실행됨과 동시에 빌드 처리 과정이 XML로 출력되게 됩니다. 이 리스너는 Ant에 포함되어 있는 기본 리스너인데, 표준 출력으로 결과를 출력하게 됩니다.


참고 : 리스너가 직접 System.out이나 System.err에 접근하는 것을 삼가해야 하는데, 그 이유는 System 스트림에 대한 출력은 이벤트 시스템을 빌드하기 위해 Ant의 코어에 의해 리다이렉트되기 때문입니다. 이들 스트림에 직접 접근하는 것은 무한루프를 야기할 수 있습니다. Ant의 버전에 따라, 빌드가 예기치 않게 종료될 수도 있고 JVM상에서 StackOverflowError가 발생할 수도 있습니다. 로거(logger)도 역시 System.out과 System.err에 직접 접근해서는 안 됩니다. 로거들도 자신에게 설정된 스트림을 이용하도록 해야 합니다.

참고2 : "빌드 시작"과 "빌드 종료" 이벤트를 제외한 모든 BuildListener 메소드들은 여러 스레드에서 동시에 호출될 수 있습니다. - 예를 들어 Ant가 <parallel> 태스크를 수행하는 경우가 그렇습니다.


**** 마지막 Source code Integration 섹션은 주제와 직접적인 관계가 없으므로 생략합니다.



이 문서에는 다뤄져 있지 않지만, taskdef를 별도의 xml 파일로 만들고 이 파일을 <taskdef>로 등록할 수도 있습니다. 다음 예는 SVNANT의 taskdef XML 파일입니다. 참고하시기 바랍니다.

<?xml version="1.0"?>
<antlib>
<!-- Tasks -->
<taskdef classname="org.tigris.subversion.svnant.SvnTask" name="svn"/>

<!-- Types -->
<typedef classname="org.tigris.subversion.svnant.types.SvnFileSet" name="svnFileSet"/>
<typedef classname="org.tigris.subversion.svnant.types.SvnSetting" name="svnSetting"/>

<!-- Selectors -->
<typedef classname="org.tigris.subversion.svnant.selectors.Normal" name="svnNormal"/>
<typedef classname="org.tigris.subversion.svnant.selectors.Added" name="svnAdded"/>
<typedef classname="org.tigris.subversion.svnant.selectors.Replaced" name="svnReplaced"/>
<typedef classname="org.tigris.subversion.svnant.selectors.Modified" name="svnModified"/>
<typedef classname="org.tigris.subversion.svnant.selectors.Conflicted" name="svnConflicted"/>
<typedef classname="org.tigris.subversion.svnant.selectors.Ignored" name="svnIgnored"/>
<typedef classname="org.tigris.subversion.svnant.selectors.Unversioned" name="svnUnversioned"/>
<typedef classname="org.tigris.subversion.svnant.selectors.Locked" name="svnLocked"/>
<typedef classname="org.tigris.subversion.svnant.selectors.Missing" name="svnMissing"/>
<typedef classname="org.tigris.subversion.svnant.selectors.Deleted" name="svnDeleted"/>

<!-- Conditions -->
<typedef classname="org.tigris.subversion.svnant.conditions.Exists" name="svnExists"/>
<typedef classname="org.tigris.subversion.svnant.conditions.Available" name="svnAvailable"/>

</antlib>

신고
Posted by Layered 트랙백 0 : 댓글 0

댓글을 달아 주세요