IT 종합뉴스서비스

메타데이터(metadata)에서 자바의 어노테이션(Annotation)을 빼먹을 수는 없는 일. 사실 모든 데이터에는 메타데이터를 붙이고자 하는 욕구가 생기게 마련이다. 형이하학적으로만은 살 수 없어 형이상학(meta-physics)이 있듯이 말이다.

프로그래밍 언어의 소스 코드에 메타데이터를 붙이고자 하는 시도는 그런 근본적인 욕구에서 시작했다고는 하지만, 구체적인 쓸모도 많았다. 어노테이션 전에 대안으로 여겨졌던 Doclet은 XML 설정 지옥으로부터 개발자를 구원해주는 메시아 같은 존재였다. 오죽했으면 Attribute Oriented Programming이라는 말까지 나왔을까.

사실 자바의 어노테이션이 나온 데에는 C#의 어트리뷰트(Attribute)의 공도 없지 않았다. 혹자는 MS의 문제 해결 방법을 따르는 것은 별로 성공적이지 않았다고 꼬집기도 하지만, 폐해를 먼저 지적하기에는 어트리뷰트나 어노테이션이 채워주는 메타데이터의 구멍은 우리에게 갚진 것임이 틀림없다.

생각해보면, 소스코드(데이터)를 설명한다는 점에서 주석(Comment)도 메타데이터의 일종으로 볼 수 있을 것이다. 그래서 Doclet도 철학적으로는 그 점에 착안한 바가 크다.

하지만 프로그램 자체라기보다는 어떻게 운용할 것인가에 대한 설정(대표적으로 Java EE의 복잡다단한 XML 설정 파일들)이 코드와 분리되면서 개발자가 다루고 맡아야 할 것들이 훨씬 더 많아졌고 자바 코드와도 이질적이 되어갔다.

불편함은 생산성의 적이다. 심리적인 이유도 있겠지만, 연관성이 높은 정보를 떨어뜨려 놓는 일은 아무래도 현명한 처사는 아닐 것이다. 뭐든지 오남용은 좋지 않지만 어떻게 쓰면 좋을지조차 모른다면 오남용과는 차원이 다른 불편한 상태를 겪게 된다.

그동안 어노테이션의 사용에 대해서는 자주 소개가 되었기 때문에 여기에서 필자는 조금 다른 관점을 가져보기로 했다. 필자가 티맥스에 있을 때 자바 EE 5 플랫폼 개발에 참여하면서 맞닥뜨리게 된 임무가 바로 어노테이션 처리였다.

JDK 5에는 안타깝게도 어노테이션을 읽고 이해하는 API가 표준화되어 있지 않아 JDK에 들어있는 썬 고유의 라이브러리를 사용했다. 하지만 어노테이션의 처리는 비단 플랫폼 벤더만의 문제가 아닌 자바인 모두의 문제여서, 재빠르게 표준화가 진행되어 자바 SE 6에는 기본으로 포함되기에 이르렀다.

JSR 269 Pluggable Annotation Processing API

공식 사이트(http://jcp.org/en/jsr/detail?id=269)를 보면 알 수 있겠지만, 이 JSR은 꽤 오래 논의를 진행한 것이다(시작이 2005년 2월인데 끝은 2006년 12월이니 거의 2년이나 걸렸다). 그 사연을 추측해본다면, 어노테이션 처리를 위한 API의 표준화는 일찍부터(참고로 자바 SE 5는 2004년 9월에 출시) 공감을 얻어 JSR을 발의했지만, 정작 이 JSR을 품을 자바 SE 6는 2006년 12월에 나와서 JSR 269도 그에 맞춘 꼴이다.

그렇다고 JSR 269 이전에는 어노테이션을 처리할 수 없었던 것은 아니다. 썬의 JDK 5에는 APT(Annotation Processing Tool)라는 패키지가 포함되어, JSR 269가 나오기 전까지 임시로 그 역할을 대신했다.

APT는 크게 어노테이션 처리를 프로그래밍하기 위한 Mirror(자바의 Reflection에 대한 오마쥬로서의 이름) API와 어노테이션 프로세서를 호출하기 위한 apt 툴로 이루어져 있었다. 이중에서 API 부분이 JSR 269로 수용되어 자바 SE 6의 코어 API에 들어갔고, apt 툴은 javac 컴파일 명령의 옵션으로 승화되었다.

흥미로운 점은 javax.lang.model 패키지가 생긴 모양새다. Mirror API로부터 오긴 했지만, 어노테이션에 국한된 냄새를 띠고 있지 않다. 어노테이션 처리라는 것이 기본적으로 모든 자바 언어 요소(패키지, 클래스, 필드 등)를 대상으로 하므로 관련된 모델링이 필요해 만든 작업물이지만, 결과적으로 자바 언어의 구성 요소의 모델이 표준화된 셈이다.

APT를 이용한 어노테이션 처리는 필자가 언젠가 마소에 기고한 적이 있었다는 기억이 난다. 아마도 JSR 181 웹 서비스 메타데이터에 대한 것이었을 텐데, 혹시나 관심 있는 분들은 과월호를 검색해보길 바란다.

그럼 JSR 269라는 딱딱한 이름대신 이름의 이니셜 PAPA과 함께 구체적인 이야기들을 풀어가 보자.

Hello PAPA

백문이 불여일런(run). PAPA로 짤 수 있는 ‘이보다 더 간단할 수 없는’ 예제를 한번 만들어보자.

<리스트 1>HelloPapaProcessor.java

<리스트 1>을 포함한 이클립스 프로젝트를 http://iasos.googlecode.com/svn/trunk/maso-2007-07-papa/ 에 올려 두었다. SVN으로 체크아웃하면 자동으로 빌드 되어 실행하시기 편할 것이다. 아! 당연히도 앞으로의 얘기는 자바 SE 6를 기준으로 진행된다.

이 예제를 실행하려면 다음과 같은 시나리오를 알아 두어야 한다.

1. javax.annotation.processing.Processor 인터페이스를 구현한 어노테이션 프로세서는 main 메소드가 있는 실행 클래스가 아니다. 따라서 단독으로 실행될 수 없고, 항상 이 프로세스를 탈 대상 소스 파일이 필요하다.
2. javac 컴파일러 명령으로 소스 파일을 컴파일할 때, -processor 옵션으로 사용한 어노테이션 프로세서를 설정한다.
3. 어노테이션 프로세서 클래스 또한 javac 명령 실행 시 클래스패스(CLASSPATH 환경변수 또는 -classpath 옵션)에 들어 있어야 한다.

javac 명령은 기본적으로 컴파일 명령이므로, 어노테이션 프로세서의 실행과는 별도로 컴파일도 하게 된다. 따라서 클래스(.class) 바이너리 파일이 나오는데, 이 과정을 생략하고 순수하게 소스 파일의 어노테이션 처리만 하고 싶다면 -proc:only 옵션을 준다.

그래서 예제 프로젝트 maso-2007-07-papa를 체크 아웃한 디렉토리로 가서

javac -cp bin -proc:only -processor ias.HelloPapaProcessor src/ias/Child.java

명령 프롬트프나 셸에서 실행하면

Note: Hello PAPA

라고 출력된다.

HelloPapaProcessor는 어노테이션 프로세서가 아주 기본적으로 가져야 할 요소를 보여주는데, 어떤 어노테이션을 처리할지(@SupportedAnnotationTypes)와 소스 버전 어디부터 처리할지(@SupportedSourceVersion)를 어노테이션으로 정의한다.

원래 앞서 언급했듯이 javax.annotation.processing.Processor 인터페이스를 구현해야 하지만, 간단히 프로세스에 전념하고 싶은 경우에는 예제와 같이 AbstractProcessor를 상속하여 추상 메소드인 process만 구현하면 편하다.

process 메소드는 javac 컴파일러가 소스 코드를 컴파일하면서 어노테이션이 발견되면 인수들과 함께 호출해준다. 예제에서는 아무런 어노테이션 처리가 없으므로 false를 반환하지만, 실제 프로세서에서는 대상 어노테이션 처리 여부를 반환하도록 만든다.

하지만 HelloPapaProcessor는 간단해도 너무 간단해서, 어노테이션 처리가 실제 어떻게 이루어질 지는 전혀 보여주지 못하는 감이 있다. 그래서 먼저 그 대상인 Child.java부터 소개한 다음 이 클래스에 들어있는 어노테이션의 목록을 출력하는 AnnotationListProcessor를 살펴보겠다.

<리스트 2> Child.java

<리스트 3> AnnotationListProcessor

실행은

javac -cp bin -proc:only -processor ias.AnnotationProcessor src/ias/Child.java

로 하고, 결과는

Note: java.lang.SuppressWarnings
Note: java.lang.Override
Note: java.lang.Deprecated

와 같이 Child에 붙은 어노테이션이 모두 출력된다.

그런데, process 메소드에서 무조건 false를 반환하던 HelloPapaProcessor와는 달리, AnnotationListProcessor는 처리 대상 클래스에 어노테이션이 있으면 모두 수집하려 목록을 출력한 다음 true를 반환한다. 그렇다면 이 true를 반환한 것은 어떤 결과를 가져 올까?

프로세서를 하나만 쓰는 경우에는 별다른 차이가 없겠지만, 여러 개의 프로세서를 체인처럼 이어서 쓴다면 상황은 크게 달라진다. 예를 들어

javac -cp bin -proc:only -processor ias.HelloPapaProcessor,ias.AnnotationListProcessor src/ias/Child.java

와 같이 HelloPapaProcessor를 먼저 실행한 다음 AnnotationListProcessor를 실행하면, 예상처럼 두 프로세서가 순차적으로 실행된 결과가 나온다.

Note: Hello PAPA
Note: java.lang.SuppressWarnings
Note: java.lang.Override
Note: java.lang.Deprecated

그런데, 순서를 반대로 하면 출력 순서도 반대로 될 것 같은 예상을 멋지게 빗나가 버린다.

Note: java.lang.SuppressWarnings
Note: java.lang.Override
Note: java.lang.Deprecated

어찌된 일인지 Hello PAPA가 출력되지 않는다. 그 이유는 바로 AnnotationListProcessor가 true를 반환하여 자기에게 넘어온 어노테이션 전부는 이미 처리되었으니 그 뒤로는 처리하지 말라고 전했기 때문이다. 그래서 다음으로 호출된 HelloPapaProcessor의 process 메소드에는 아무런 어노테이션이 넘어가지 않았던 것이다.

여기서 한 발짝 더 나아가 생각해보자. 앞에서는 자바 언어가 기본적으로 정의한 어노테이션이지만 자신이 만든 어노테이션(User Created Annotation이라고나 할까?)만을 처리하는 프로세서를 만들어보는 것은 어떨까?

<리스트 4> Observation.java

Observation은 간단한 마커 어노테이션이다. 이것을 붙인 GrandChild 클래스를 만들어보자.

<리스트 5> GrandChild.java

ObservationProcessor는 Observation 어노테이션만을 찾아내는 역할을 한다.

<리스트 6> ObservationProcessor.java

먼저 ObservationProcessor만 단독으로 실행해보면

javac -cp bin -proc:only -processor ias.ObservationProcessor src/ias/Child.java

Observation 어노테이션을 수집했다고 표시된다.

Note: Observation mark is claimed

그렇다면, AnnotationListProcessor와 같이 실행하면 어떤 결과가 나올까? 짐작이 조금 가는가? GrandChild 클래스에는 Observation뿐 아니라 Override도 붙어 있다. 그런데 ObservationProcessor에서 Observation만을 수집했으니까, AnnotationListProcessor에게는 Override만 수집 대상으로 남을 것이다. 자 그럼 이런 추측이 맞는지 확인해보자.

javac -cp bin -proc:only -processor ias.ObservationProcessor, ias.AnnotationListProcessor src/ias/Child.java

의 실행 결과는

Note: Observation mark is claimed
Note: java.lang.Override

와 같아 우리의 예상이 멋지게 맞아 들었음을 보여준다.

개미(Ant)나 퍼먹어~

앞서 간단히 어노테이션 프로세서를 javac 명령으로 실행해봤지만, 실제로 이렇게 하실 분들은 거의 없을 것이다. 제목이 다소 선정적(?)으로 느껴질 지도 모르겠지만, 이제 프로젝트의 빌드에는 아파치 앤트(Apache Ant)를 많이 쓰고 있기 때문이다.

어노테이션이 처음 나온 자바 SE 5에서는 PAPA가 없었기 때문에, APT라는(비표준적인) 툴이 있어 앤트도 APT에 대응하는 앤트 태스크를 따로 두어 지원했었다.

Apt 태스크의 일부

다음은 Apt 태스크 내용 원문의 일부이다. 전문은 http://ant.apache.org/manual/CoreTasks/apt.html에서 확인할 수 있다.

Apt| Description
Runs the annotation processor tool (apt), and then optionally compiles the original code, and any generated source code. This task requires Java 1.5. It may work on later versions, but this cannot be confirmed until those versions ship. Be advised that the Apt tool does appear to be an unstable part of the JDK framework, so may change radically in future versions. In particular it is likely to be obsolete in JDK 6, which can run annotation processors as part of javac. If the task does break when upgrading JVM, please check to see if there is a more recent version of Ant that tracks any changes.
This task inherits from the Javac Task, and thus supports nearly all of the same attributes, and subelements. There is one special case, the fork attribute, which is present but which can only be set to true. That is, apt only works as a forked process.
In addition, it supports the following addition items:Apt| Description
Runs the annotation processor tool (apt), and then optionally compiles the original code, and any generated source code. This task requires Java 1.5. It may work on later versions, but this cannot be confirmed until those versions ship. Be advised that the Apt tool does appear to be an unstable part of the JDK framework, so may change radically in future versions. In particular it is likely to be obsolete in JDK 6, which can run annotation processors as part of javac. If the task does break when upgrading JVM, please check to see if there is a more recent version of Ant that tracks any changes.
This task inherits from the Javac Task, and thus supports nearly all of the same attributes, and subelements. There is one special case, the fork attribute, which is present but which can only be set to true. That is, apt only works as a forked process.
In addition, it supports the following addition items:

Apt 태스크는 apt를 실행하고 옵션으로 원래 코드와 생성된 코드도 컴파일 한다. 이 태스크는 자바 1.5가 필요하며 이후의 버전에서 실행될 수 있지만, 정확한 내용은 이후 버전이 나와 봐야 확인할 수 있다. APT 툴은 JDK 프레임워크에서 임시적인 부분으로 보이므로, 다음 버전에서 근본적으로 변할 수 있음을 알려둔다.

특히 JDK 6에서는 javac 컴파일러 명령의 일부로 어노테이션 프로세서를 실행할 수 있을 것으로 보여, APT가 사장(obsolete)될 가능성이 많다. 만약 JVM을 업그레이드하고 나서 태스크가 제대로 실행되지 않으면, 더 최신 버전의 앤트가 그 문제를 해결했는지 확인하라.

이 태스크는 Javac 테스크를 상속하므로, 거의 같은 속성과 부속 요소를 지원한다.

Parameters

APT 태스크의 설명에도 나와 있듯이 Apt 태스크는 JDK 6가 나오기 전까지의 임시방편적인 성격이 짙게 깔려 있다(지원하는 파라미터도 PAPA와 비슷하다). 하지만 안타깝게도 JDK 6가 나온 현재 시점에서 Apt를 대체하는 Javac 태스크의 확장은 나오지 않고 있다.

물론 하위 호환성을 위해 JDK 6에도 APT는 지원되고 있지만, 아무래도 표준화된 PAPA로 가는 것이 여러 종류의 JDK를 가리지 않을뿐더러 향후 투자성도 좋을 것이다.

그렇다면, PAPA 기반으로 만든 프로세서를 앤트에서 어떻게 쓸 수 있을까? 현재 앤트(버전 1.7.0)의 Javac 태스크에는 아직 PAPA와 관련된 파라미터는 없다. 다만, compilerarg라는 요소를 써서 직접 -processor나 -processorpath와 같은 옵션을 넣을 수 있다.

<리스트 7> build.xml

이 빌드 파일은 앞서 예제와는 다소 다른 방식으로 프로세서를 쓰고 있다. 먼저 build-processor 타깃에서는 프로세서를 컴파일 하여 processor 디렉토리에 별도로 둔다. 그다음 process-annotations를 하면 프로세서가 아닌 클래스에 대해 어노테이션을 처리하도록 했다. 이 때 프로세서가 있는 곳을 -processorpath로 지정하고 있다.

실행 결과는 다음과 같이 컴파일 대상 클래스(Child, GrandChild 등)에 붙은 어노테이션이 모두 출력된다.

ias@openlab01:~/maso-2007-07-papa$ ant process-annotations
Buildfile: build.xml

init:

build-processors:

process-annotations:
[javac] Compiling 3 source files to /home/ias/maso-2007-07-papa/bin
[javac] Note: java.lang.Deprecated
[javac] Note: java.lang.SuppressWarnings
[javac] Note: java.lang.Override
[javac] Note: ias.Observation

BUILD SUCCESSFUL
Total time: 1 second

Metadata rules everywhere
PAPA의 응용 범위는 놀라울 정도로 넓음을 짐작할 수 있다. 어노테이션의 처리는 단순히 어노테이션의 판독뿐 아니라, 그 어노테이션을 바탕으로 메타 코드를 생성할 수도 있기 때문이다.

예를 들어 어떤 클래스 X에 @Grand라는 어노테이션이 붙으면 자동으로 GrandX라는 클래스를 생성하는 식이다. 또한 그렇게 생성된 클래스도 다시 어노테이션 처리를 할 수 있어서 회차(round)라는 개념이 필요한 것이다.

더불어 이 글에서는 javac 명령을 명시적으로 사용했지만, JSR 199 Java Compiler API를 사용하면(고맙게도 이 또한 JDK 6에 기본 포함되어 있다) 어노테이션 처리를 포함한 컴파일 처리를 프로그램으로 짤 수 있다.

아직 자바 EE 5가 자바 SE 5까지만 요구하기 때문에 JSR 199 + JSR 269의 앙상블은 쓸 수 없지만, 점차 Java SE 6를 많이 쓰게 된다면 자바의 메타 프로그래밍에 근간이 될 기술들이라 믿는다. @

P.S. 예제와 관련된 질문이나 논의는 http://code.google.com/p/iasos/ 에서 Groups나 Issues로 대환영한다. ^o^/

어노테이션의 적극적인 활용 예

JSR 311 Java API for RESTful Web Services (JAX-RS)
자바 표준 기술에 있어 어노테이션의 채택은 두드러진 현상이다. 특히 최근에 Open API의 메시지 프로토콜로 각광을 받고 있는 REST를 자바 서버 측에서 지원하기 위한 표준 API인 JSR 311 JAX-RS는 웹 서비스와 EJB가 보여준 POJO(Plain Old Java Object) 기반 인터페이스 노출 기술을 더욱 진화시킨 모습이다.

아직 공식적인 조기 초안(Early Draft)조차 내지 않은 상황이지만, API와 RI(Reference Implementation) 둘 다 오픈 소스 프로젝트로 공개하고 있어 실시간으로 진행상황을 엿볼 수 있다.

JSR 311 API 프로젝트 - https://jsr311.dev.java.net/
(JSR 311 RI) Jersey 프로젝트 - https://jersey.dev.java.net/

두 프로젝트 다 매주 묶은 릴리즈와 더불어 SVN을 통해 최신 소스를 접근할 수 있다. 그럼, 2007년 6월말 현재로 JAX-RS가 어떻게 어노테이션을 활용하고 있는지 확인해 보자.

package com.sun.ws.rest.samples.helloworld.resources;
import javax.ws.rs.HttpMethod;
import javax.ws.rs.ProduceMime;
import javax.ws.rs.UriTemplate;

// The Java class will be hosted at the URI path "/helloworld"
@UriTemplate("/helloworld")
public class HelloWorldResource {

// The Java method will process HTTP GET requests
@HttpMethod("GET")
// The Java method will produce content identified by the MIME Media
// type "text/plain"
@ProduceMime("text/plain")
public String getClichedMessage() {
// Return some cliched textual content
return "Hello World";
}
}

이 코드는 Jersey에 포함되어 있는 HelloWorld 격의 예제다. 어노테이션이 상당히 많이 붙어있는데, 그것만 빼면 일반 자바 클래스와 다를 것이 없다.

즉, 어떤 특정 인터페이스를 구현한다던가 시그니쳐를 고정하는 일 없이, 자기 마음대로 클래스를 짜고 거기에 필요한 어노테이션을 붙이는 방식으로 짠다는 것이다.

위의 어노테이션들을 보면 다음과 같이 매우 직관적으로 메타데이터를 묘사하고 있다.

@UriTemplate("/helloworld") -> HelloWorldResource의 REST 리소스 주소를 지정
@HttpMethod("GET") -> getClichedMessage 메소드를 부를 때 쓸 HTTP 메소드
@ProduceMime("text/plain") -> getClichedMessage의 반환값이 HTTP 응답의 어떤 MIME 타입으로 나갈지를 지정

좀 더 본격적인 예제인 Bookstore를 보면 JAX-RS의 어노테이션이 얼마나 유용한지를 알 수 있다.

package com.sun.ws.rest.samples.bookstore.resources;
public class Item {
private String title;
private String author;
public Item(final String title, final String author) {
this.title = title;
this.author = author;
}
public String getTitle() {
return title;
}
public String getAuthor() {
return author;
}
}
package com.sun.ws.rest.samples.bookstore.resources;
import com.sun.ws.rest.api.NotFoundException;
import com.sun.ws.rest.api.view.Views;
import javax.ws.rs.UriParam;
import javax.ws.rs.UriTemplate;
@Views({"index.jsp"})
public class CD extends Item {
private final Track[] tracks;
public CD(final String title, final String author, final Track[] tracks) {
super(title, author);
this.tracks = tracks;
}
public Track[] getTracks() {
return tracks;
}
@UriTemplate("tracks/{num}/")
public Track getTrack(@UriParam("num") int num) {
if (num >= tracks.length)
throw new NotFoundException("Track, " + num + ", of CD, " + getTitle() + ", is not found");
return tracks[num];
}
}
package com.sun.ws.rest.samples.bookstore.resources;
import com.sun.ws.rest.api.view.Views;
@Views({"index.jsp"})
public class Book extends Item {
public Book(final String title, final String author) {
super(title, author);
}
}

맨 위의 Item은 일종의 최상위 클래스이고, CD와 Book이 각각 상속하여 자체적인 REST 리소스로 드러난다. 여기서 주목할 점은, 어떤 자바 오브젝트를 REST 리소스로 드러내는 데에 기존의 상속 구조를 흔들 필요가 없다는 것이다.

전에는 상속이나 구현으로(밖에) 표현할 수 없었던 이런 기능적인 메타데이터가 어노테이션으로 표시되면서 우리는 좀 더 자유롭게 데이터를 모델링하면서도 인터페이스의 수단으로 삼을 수 있게 되었다.

참고자료
1. 자바 관련 릴리즈 정보: http://mindprod.com/jgloss/javareleasedates.html
2. APT 공식 사이트: http://java.sun.com/j2se/1.5.0/docs/guide/apt/index.html
3. JSR 269 스펙 리드의 블로그: http://blogs.sun.com/darcy
4. 특정 어노테이션 처리 예제: http://www.artima.com/forums/flat.jsp?forum=276&thread=179769
5. 자바 클래스 구조를 분석하는 예제: http://blogs.sun.com/prats/entry/javac_demo%40foss-2006c

* 이 기사는 ZDNet Korea의 제휴매체인 마이크로소프트웨어에 게재된 내용입니다.