|
Core Java Technologies Tech Tips에 오신 여러분을 환영합니다. Java
2 Platform, Standard Edition (J2SE)에 기반한 core Java technologies
와 APIs의 사용에 관한 최신 정보를 얻어 가시기 바랍니다. 이 글에서는 Java 2 Platform
Standard Edition Development Kit 5.0(JDK 5.0)을 사용합니다.
Download
JDK 5.0
이번 호에서는,
 리소스 번들 로딩
javadoc에서 ListResourceBundles 숨기기
을 다루게 됩니다.
저자 Daniel H. Steinberg
리소스 번들 로딩
리소스 번들을 이용해 텍스트 스트링을 각국의 언어별(특히, 영어에 있어서는 각 지역별 영어)로
임베드할 수 있다. 이전의 Tech
Tip에서는 리소스 번들의 사용에 대해서 논의했었다. 이를 잠시 되새겨보자. 당신의 프로그램에
"Hello, World"와 같은 스트링이 필요하다면 이를 프로그램에 코딩하는
것이 하나의 방법이 되겠다. 그러나 리소스 번들을 이용하면 스트링을 하드 코딩할 필요가 없다. 대신에
룩업 테이블에 스트링을 넣고 런타임시 프로그램이 스트링을 찾아보도록 할 수 있다. 프로그램이 다른
지역값(locale)으로 구동한다면 찾아보기(lookup)기능은, 번역되어있을 경우에는 다른 스트링을,
번역되어있지 않을 경우에는 원래의 스트링을 찾을 것이다. 지역값에 상관없이 동일한 코드로 구동되므로
프로그램의 코드에는 영향을 미치지 않는다. 사용자가 해야할 것은 값들의 룩업 테이블을 생성하고 번역하는
것 뿐이다.
앞에서 언급했듯이 리소스 번들은 지역값을 대상으로 한다. 영어가 지역값일 때 "영어로 'greet' 스트링이 필요함."라고 할 수 있으며, 미국 영어의 'color'와 영국 영어의 'colour'의 차이를 둘 수도 있다. 지역값은 국가별 언어뿐 아니라 각 언어 안에서도 지역구분을 지원하기 때문이다. 즉 미국식 영어 중에서도 Southern California나 New York City등의 각 지역에 따라 다른 구문을 지정할 수 있다.
ListResourceBundle를 확장하는 .class 파일에 리소스 번들을 정의하거나 .properties 파일로 백업되는 PopertyResourceBundle를 사용할 수도 있다. 리소스 번들과 지역값을 결합시킬 때는 두가지 검색이 수반된다. 첫번째 검색으로는 가장 가까운 요청 리소스 번들을 찾고, 두번째 검색으로는 요청된 key에 대한 스트링을 찾는다. 왜 이러한 차이를 둘까? 리서치 번들을 검색할 때 시스템은 리소스 번들을 찾는 즉시 검색을 중단하고 요청된 리소스 번들을 로딩한다. 시스템이 요청된 번들에서 key를 찾지 못하면 다른 리소스 번들에서 찾게 된다. 결국 찾지 못하면 시스템은 MissingResourceException를 던진다.
이에 대한 시연으로 Greeting 이라는 이름의 번들 안에서 New York 지역값에 대한 스트링을 찾는다고 가정하고 지역값이 다음과 같이 생성되었다고 하자.
Locale newYork = new Locale("en", "US", "NewYork")
그리고 다음과 같이 리소스 번들을 요청하면,
ResourceBundle bundle =
ResourceBundle.getBundle("Greeting", newYork);
시스템은 우선 번들에 대한 .class 파일을 찾는다. 그 파일은 New
York 과 같이 변하는 지역값은 레벨로서 그 파일은 Greeting_en_US_NewYork.class이
될 것이다. 시스템이 클래스 경로에서 .class파일을 찾지 못하면 Greeting_en_US_NewYork.properties파일을
검색하게된다. 이어서 Greeting_en_US.class, Greeting_en_US.properties,
Greeting_en.class, Greeting_en.properties,
Greeting.class, Greeting.properties를
검색하게 될 것이다. 리소스 번들을 찾게 되면 시스템은 검색을 멈춘다. 다행히 캐쉬가 포함되어 있어
시스템이 언제나 모든 곳을 검색하는 것은 아니다. 그렇지만 검색해야하는 곳이 잠재적으로 매우 많은
것이 사실이다.
그 후 시스템은 두번째 찾아보기를 실행한다. 이번에는 요청된 키를 찾는 단계이다. 요청한 키가
시스템이 찾은 번들 안에 없다면 시스템은 언어, 지역, 등의 현재 번들의 레벨을 넘어서서 또다른
리소스 번들을 찾게 된다. 이에 따라 .class 파일이든 .properties
파일이든지 상관없이 좀 더 많은 번들을 로딩하게 된다.
사용자들이 아마도 궁금할 것은 .class 파일을 사용하는 것과 .properties 파일을 사용하는 것 중 어느 것이 더 나은것인가에 대한 것이다. .class 파일이 먼저 검색되고 그 다음이 .properties 파일이다. 또한 .class은 클래스 로더에서 직접 로딩되는 반면 .properties 파일은 번들이 로딩될 필요하 있을 때마다 매번 파싱되어야한다. 파싱은 두번의 과정을 거친다. \uXXX과 같은 유니코드를 다루려면 시스템은 반드시 각각의 key=value 라인을 두번씩 스캔한 후, 값으로부터 키를 분리해야한다.
자 이제 이 두개의 로딩 시간을 비교해보자. 다음의 테스트 프로그램으로 먼저 시작해보면,
import java.util.*;
public class Test1 {
public static void main(String args[]) {
Locale locale = Locale.ENGLISH;
long start = System.nanoTime();
ResourceBundle myResources =
ResourceBundle.getBundle("MyResources", locale);
long end1 = System.nanoTime();
String string = myResources.getString("HelpKey");
long end2 = System.nanoTime();
System.out.println("Load: " + (end1 - start));
System.out.println("Fetch: " + (end2 - end1));
System.out.println("HelpKey: " + string);
}
}
사용자가 1.4 Java 플랫폼을 구동한다면 테스트 프로그램을 변경하여 nanoTime 대신 currentTimeMillis을 호출하도록 한다. nanoTime 메소드는 나노세컨드 단위(10억분의 1초)로 실행되며, currentTimeMillis는 밀리세컨드 단위(천분의 1초)로 실행된다. 또한 이번 팁의 마지막 부분에 나오는 microbenchmarks를 참고하자.
다음으로 테스트 프로그램과 같은 디렉토리 안에 ListResourceBundle 클래스를 생성하자.
import java.util.*;
public class MyResources extends ListResourceBundle {
public Object[][] getContents() {
return contents;
}
private static final Object[][] contents = {
{"OkKey", "OK"},
{"CancelKey", "Cancel"},
{"HelpKey", "Help"},
{"YesKey", "Yes"},
{"NoKey", "No"},
};
}
테스트 프로그램과 MyResources 클래스를 컴파일하고 테스트 프로그램을 구동시키자.
결과는 작업 환경, 즉 RAM의 크기와 프로세서의 속도에 따라 달라질 것이다. 다음은 768 MB RAM으로 Windows XP를 구동하는 800 MHz 장치에서의 결과이다.
Load: 25937415
Fetch: 62994
이제 properties 파일인 MyResources.properties를 다음의 요소와 함께 생성하자.
OkKey=OK
CancelKey=Cancel
HelpKey=Help
YesKey=Yes
NoKey=No
테스트 프로그램을 다시 구동하고, 이번에는 먼저 MyResources 클래스를 제거한다. .properties 파일을 이용하여 프로그램을 구동할 것이다. 다음은 좀전과 같은 사양의 장치에서 나온 결과이다.
Load: 101469357
Fetch: 35450
로딩시간에 있어서는 ListResourceBundle이 PropertyResourceBundle보다 빠르다는 것을 알 수 있다. 그러나 놀랍게도 패칭(fetch) 시간으로는 PropertyResourceBundle이 ListResourceBundle보다 두 배 가까이 빠르다. 대략, 로딩에 있어서는 다섯배의 차이가 나고 패칭에 있어서는 두배의 차이가 나므로 이를 따라잡기 위해서는 많은 패칭 작업이 필요하다. 나노세컨드는 10억분의 1의 시간이라는 것과 밀리세컨드는 천분의 1초라는 사실을 잊지 말기 바란다.
테스트 프로그램을 다시 구동하고, 이번에는 .class와 .properties파일에 있는 100개의 요소들을 사용하자. 이전 파일의 다섯 요소를 20번 복사하고 복사할 때마다 처음부분을 약간 변경함으로써 간단히 파일을 생성할 수 있다. 예를 들어 OkKey를 OkKey1으로, CancelKey를 CancelKey1로 변경하는 식이다. 이에 대한 결과는 이전의 결과와 같이 로딩에 있어서는 ListResourceBundle이 빠르고 패칭에 있어서는 PropertyResourceBundle이 빠를 것이다. 사실 PropertyResourceBundle의 100개 요소에 대한 로딩시간은 5개를 패칭하는 시간과 비슷하다는 걸 알 수 있을 것이다.
ListResourceBundle
Load: 12782686
Fetch: 262788
PropertyResourceBundle
Load: 12600795
Fetch: 35175
지역값을 언어(Locale.ENGLISH)에서 언어/지역(Locale.US)으로 바꾸면 좀 더 재미있는 결과가 나타난다.
Loading 5 / Locale.US:
ListResourceBundle
Load: 13152117
Fetch: 32921
PropertyResourceBundle
Load: 14592024
Fetch: 261060
Loading 100 / Locale.US:
ListResourceBundle:
Load: 12837863
Fetch: 264264
PropertyResourceBundle
Load: 14468366
Fetch: 33166
모든 클래스에서 ListResourceBundle이 초기 번들을 로딩하는 시간은 언제나 빠른 반면에, 패칭 시간은 가끔 느리기도 한다. 그렇다면 어떤 것이 좋을까? 작은 리소스 번들의 경우 ListResourceBundle이 둘 중에 빠르고, 큰 경우 ListResourceBundle를 사용하지 않는 것이 좋아 보인다. ListResourceBundle은 2차원으로 배열된 것을 룩업맵으로 변경시켜야하므로 이것이 더 느린 이유이다.
이 결과들을 보면 ListResourceBundle를 사용하지 않겠다고 마음먹을 수도 있다. 예를 들어 서버 기반 프로그램에서 .class 파일보다 .properties 파일을 유지하는 것이 더 쉽고, 로딩 시간은 무시해도 괜찮다고 느낄 수 있다. 그러나 ListResourceBundle은 단지 스트링의 2차원적 배열만이 아니다. getContents 메소드는 Object 배열을 리턴한다.
public Object[][] getContents()
이것은 무엇을 의미하나? 간단한 스트링을 넘어선 컨텐츠를 로컬화하고 싶다면 반드시 ListResourceBundle 오브젝트를 사용해야한다. 이는 이미지, 색깔, 차원 등을 로컬화해준다. PropertyResourceBundle에서는 스트링 이외의 오브젝트를 가질 수 없다.
샘플 프로그램에서의 시간 테스트는 microbenchmark 으로 여겨질 수 있음을 주의하기 바란다. 이는 당연히 발전될 것이지만 리소스 번들 로딩의 캐싱으로는 한번의 구동에서 여러 번의 루핑을 실행할 때 정확한 로딩 시간을 측정하기 힘들다. Microbenchmark를 작성하는 기술에 대해서는 JavaOne 2002 발표자료인 How NOT To Write A Microbenchmark를 참조하기 바란다. 덧붙여, 이 분야의 많은 성능 작업이 JDK 5.0에서 완료되었으며 Java 2 SDK, Standard Edition, v 1.4.x 사용할 때와는 숫자들이 대체로 다를 것이다.
리소스 번들로 작업하는 것에 대한 좀 더 많은 정보는 Java Tutorial의 javadoc for the ResourceBundle class, internationalization trail과 Core Java Internationalization페이지를 참고하기 바란다.
javadoc에서 ListResourceBundles 숨기기
첫번째 테크팁 리소스 번들 로딩하기에서 ListResourceBundle과
PropertyResourceBundle의 몇가지 성능을 비교해보았었다.
PropertyResourceBundle 루트 대신 ListResourceBundles를
사용하기로 했다면 고려해야할 사항이 한가지 더 있다. 리스트 리소스 번들에 대한 클래스들이 반드시
공개 클래스로 정의되어야한다는 사실이다. 문제는 소스 트리에 javadoc
툴을 구동시킬 때 리소스 번들 클래스의 API 문서가 같은 패키지 안에 있다면, 다른 클래스들과
같이 나타난다는 것이다. 이러한 구현의 세부적 사항은 숨겨져 있어야 한다. 왜냐하면 나중에 PropertyResourceBundle로
변경하였을 경우 공개 클래스가 사라지고 제품에 대한 공개 API는 변경되기 때문이다. 이 문제를
어떻게 처리할 수 있을까? 실제로 javadoc에서 ListResourceBundles를
숨기는 방법이 있을까? 이번 테크팁에서 이에 대한 해결책을 보여주려고한다.
javadoc 툴은 디폴트값으로 결과에서 클래스들을 감추는 두가지 옵션을 지원한다. 파일 안에 있는 모든 클래스의 리스트를 지정하고 툴로 하여금 이 고정된 세트에 javadoc을 구동하도록 지시할 수 있다. 또는 패키지 안에 모든 리소스 번들을 위치시키고 툴로 하여금 리소스 번들이 위치한 패키지를 무시하는 패키지들을 구동시킬 수도 있다. 리스트를 유지하는 것이 어렵기 때문에 첫번째 테크닉은 좀 성가실 수 있다-. 두번째 테크닉으로는 리소스 번들을 사용하는 소스와 동일한 디렉토리 안에 리소스 번들을 보유하는 것을 방지하도록 한다.
자, 결과를 생성할 때 특정 클래스를 무시하도록 어떻게 javadoc를 사용자 정의할 수 있을까? 이는 클래스들의 전체 리스트를 생성(리소스 번들 클래스 없이)하는 대신 간단히 리소스 번들 클래스들의 리스트를 제공함으로써 해결할 수 있다.
이 해결책은 J2SE 1.4와 5.0 버전에서 모두 작용한다. 이를 위해서는 -excludefile을 허용하는 doclet를 구동한다. -excludefile 은 사용자가 지정한 클래스들을 제외한다. 다음은 doclet을 구동하는 방법이다.(커멘트들이 한 줄에 들어가야함을 주의하기 바란다.)
java -classpath <path to doclet and path to tools.jar>
ExcludeDoclet -excludefile <path to exclude file>
<javadoc options>
커멘트에 대한 반응으로 Doclet 클래스의 validOptions 메서드는 -excludefile 옵션을 찾는다. 찾게 되면, 메서드는 제외된 파일(무시된 클래스들과 패키지들)의 컨텐츠를 읽는다. 그 후 start 메서드가 호출된다. 각 클래스 또는 패키지가 진행됨에 따라 메소드는 제외된 클래스들과 패키지들을 버리게 된다. Doclet은 optionLength 메소드를 포함하며, 이는 doclet이 J2SE 1.4와 5.0에서 구동될 수 있게 한다. 다음은 ExcludeDoclet이다.
import java.io.*;
import java.util.*;
import com.sun.tools.javadoc.Main;
import com.sun.javadoc.*;
/**
* A wrapper for Javadoc. Accepts an additional option
* called "-excludefile", which specifies which classes
* and packages should be excluded from the output.
*
* @author Jamie Ho
*/
public class ExcludeDoclet extends Doclet {
private static List m_args = new ArrayList();
private static Set m_excludeSet = new HashSet();
/**
* Iterate through the documented classes and remove the
* ones that should be excluded.
*
* @param root the initial RootDoc (before filtering).
*/
public static boolean start(RootDoc root) {
root.printNotice
("\n\nRemoving excluded source files.......\n\n");
ClassDoc[] classes = root.classes();
for (int i = 0; i < classes.length; i++) {
if (m_excludeSet.contains(classes[i].qualifiedName()) ||
m_excludeSet.contains
(classes[i].containingPackage().name())) {
root.printNotice
("Excluding " + classes[i].qualifiedName());
continue;
}
m_args.add(classes[i].position().file().getPath());
}
root.printNotice("\n\n");
return true;
}
/**
* Let every option be valid. The real validation happens
* in the standard doclet, not here. Remove the "-excludefile"
* and "-subpackages" options because they are not needed by
* the standard doclet.
*
* @param options the options from the command line.
* @param reporter the error reporter.
*/
public static boolean validOptions(String[][] options,
DocErrorReporter reporter) {
for (int i = 0; i < options.length; i++) {
if (options[i][0].equalsIgnoreCase("-excludefile")) {
try {
readExcludeFile(options[i][1]);
} catch (Exception e) {
e.printStackTrace();
}
continue;
}
if (options[i][0].equals("-subpackages")) {
continue;
}
for (int j = 0; j < options[i].length; j++) {
m_args.add(options[i][j]);
}
}
return true;
}
/**
* Parse the file that specifies which classes and packages
* to exclude from the output. You can write comments in this
* file by starting the line with a '#' character.
*
* @param filePath the path to the exclude file.
*/
private static void readExcludeFile(String filePath)
throws Exception {
LineNumberReader reader =
new LineNumberReader(new FileReader(filePath));
String line;
while ((line = reader.readLine()) != null) {
if (line.trim().startsWith("#"))
continue;
m_excludeSet.add(line.trim());
}
}
/**
* Method required to validate the length of the given option.
* This is a bit ugly but the options must be hard coded here.
* Otherwise, Javadoc will throw errors when parsing options.
* We could delegate to the Standard doclet when computing
* option lengths, but then this doclet would be dependent on
* the version of J2SE used. I'd rather hard code so that
* this doclet can be used with 1.4.x or 1.5.x.
*
* @param option the option to compute the length for.
*/
public static int optionLength(String option) {
if (option.equalsIgnoreCase("-excludefile")) {
return 2;
}
//General options
if (option.equals("-author") ||
option.equals("-docfilessubdirs") ||
option.equals("-keywords") ||
option.equals("-linksource") ||
option.equals("-nocomment") ||
option.equals("-nodeprecated") ||
option.equals("-nosince") ||
option.equals("-notimestamp") ||
option.equals("-quiet") ||
option.equals("-xnodate") ||
option.equals("-version")) {
return 1;
} else if (option.equals("-d") ||
option.equals("-docencoding") ||
option.equals("-encoding") ||
option.equals("-excludedocfilessubdir") ||
option.equals("-link") ||
option.equals("-sourcetab") ||
option.equals("-noqualifier") ||
option.equals("-output") ||
option.equals("-sourcepath") ||
option.equals("-tag") ||
option.equals("-taglet") ||
option.equals("-tagletpath")) {
return 2;
} else if (option.equals("-group") ||
option.equals("-linkoffline")) {
return 3;
}
//Standard doclet options
option = option.toLowerCase();
if (option.equals("-nodeprecatedlist") ||
option.equals("-noindex") ||
option.equals("-notree") ||
option.equals("-nohelp") ||
option.equals("-splitindex") ||
option.equals("-serialwarn") ||
option.equals("-use") ||
option.equals("-nonavbar") ||
option.equals("-nooverview")) {
return 1;
} else if (option.equals("-footer") ||
option.equals("-header") ||
option.equals("-packagesheader") ||
option.equals("-doctitle") ||
option.equals("-windowtitle") ||
option.equals("-bottom") ||
option.equals("-helpfile") ||
option.equals("-stylesheetfile") ||
option.equals("-charset") ||
option.equals("-overview")) {
return 2;
} else {
return 0;
}
}
/**
* Execute this doclet to filter out the unwanted classes
* and packages. Then execute the standard doclet.
*
* @param args The Javadoc arguments from the command line.
*/
public static void main(String[] args) {
String name = ExcludeDoclet.class.getName();
Main.execute(name, name, args);
Main.execute((String[]) m_args.toArray(new String[] {}));
}
}
다음과 같이 doclet을 컴파일하자.
javac -classpath tools.jar ExcludeDoclet.java
tools.jar를 JDK 인스톨의 적절한 위치로 변경하자. 예를 들어 윈도우 환경에서 구동하고 JDK를 c:\jdk1.5.0 directory, specify c:\jdk1.5.0\lib\tools.jar에 인스톨했다면, c:\jdk1.5.0\lib\tools.jar로 지정한다.
다음으로 skip.txt과 같은 파일을 생성하여 어떤 클래스를 스킵할 것인지 확인한다. 보통 이는ListResourceBundle 서브클래스들이 될 것이다. 이에 대한 예제로, 표준 JDK 클래스로 ExcludeDoclet를 구동하고 java.lang 패키지를 무시하자.
java.lang.Math
java.lang.Long
java.lang.InternalError
java.lang.InterruptedException
java.lang.Iterable
java.lang.LinkageError
다음의 커멘드(한 줄에 위치)를 구동하자.
java -classpath .;c:\jdk1.5.0\lib\tools.jar ExcludeDoclet
-d docs -excludefile skip.txt -sourcepath c:\jdk1.5.0\src
-source 1.5 java.lang
이 커멘드는 skip.txt 로 식별된 6개의 클래스와 인터페이스들을 제외한 java.lang 패키지에 대한 javadoc을 생성할 것이다.
다음은 생성된 javadoc의 일부로써 java.lang 패키지의 인터페이스들을 보여주고있다. Iterable 인터페이스가 제외되었음을 유의하기 바란다.
사용자 정의 doclet의 생성에 대한 좀 더 자세한 정보는 Generating Custom Doclets를 참고하기 바란다.
본 메일은 수신을 동의한 회원님에게만 발송됩니다. 관련문의 : SKDN@sun.com
본 메일의 수신을 거부하시려면 수신거부를
클릭해 주세요.
Copyright 2003-2005 Sun Korea, Inc. All rights reserved.
|
