JAVA API 보는법

출처 : http://cauca.springnote.com/pages/1196036

일단 창이 세부분으로 나뉘어 있습니다.

왼쪽 상단에는 package만 나와있구요. 여기서 하나의 package를 선택하면 그 package안에 있는 모든 클래스가 왼쪽 하단의 창에 나타납니다.

그리고 왼쪽 하단의 창에 나타난 클래스를 클릭하면 그 클래스에 대한 내용이 비로소 오른쪽 메인 화면에 나타나죠.


우선 API 문서를 제대로 쓰고 싶다면 먼저 자바 tutorial을 읽어보길 권하고 싶습니다.

API는 기본적으로 어떤 package가, 어떤 클래스가 어떤 기능을 하는지 알고 있어야지 의미가 있거든요.

System.in.read()

를 한번 예로 들어볼께요.

http://download.oracle.com/javase/1.5.0/docs/api/java/lang/System.html

자바에서는 클래스명은 대문자로 씁니다.

"난 클래스를 소문자로 쓰고 싶어!!!" 한다면 누가 말릴 수는 없겠지만 왕따당합니다....^^;;;

클래스 - 대문자 (MyClass, Applet, JComponent 등 모두 다 대문자로 씁니다.)
클래스 안의 필드 - 소문자
클래스 안의 메소드 - 맨 앞글지는 소문자 그리고 메소드를 구성하는 단어의 첫글자는 대문자
isTrue(), createStatement(), initialCondition() 등

일단 이렇습니다.

따라서 System 은 클래스를 의미하고 in은 소문자로 되어있고 뒤에 in.read() 라는 메소드가 붙으니까 메소드는 아니니 System 클래스 내에 정의된 필드라는걸 대번에 알 수 있습니다.

System - 대문자로 시작하니 클래스이다.
.in - System 뒤에 붙어있으니 이것은 System에 정의된 필드이다.(정확하게는 static 필드이다.)
.read() - 메소드이다.


그러면 일단 API에서 System이라는 클래스가 무슨일을 하는지 알아봐야 할텐데, 문제는 이게 어느 package에 있는지 알 수가 없다는 겁니다.

이럴때는 좌측 상단에서

All classes를 누르면 package와 상관없이 모든 클래스가 출력됩니다.

All classes를 눌러서 왼쪽 하단의 창에서 System 클래스를 찾아봅니다.(알파벳순으로 정렬되어 나타납니다.)

그러면 오른쪽 메인 화면에

이 렇게 나타날겁니다. System 클래스는 java 디렉토리 밑에 io 디렉토리 안에 포함되어있는 클래스라는 것을 말해주고 System 클래스는 Object 클래스를 상속받고 있다는 뜻입니다. 자바의 모든 클래스는 묵시적으로 Object 클래스를 상속받고 있다는 점을 감안하면 System 클래스는 최상위 클래스라고 말할 수도 있겠죠.(java디렉토리가 어디 있냐하면 jdk를 설치하고 src.jar 라는 압축파일을 풀면 그안에 있습니다.)


그리고 그 다음에 간단하게 이 클래스가 무엇이다는 설명이 나옵니다.

---------------------------------------------------------------------------------
public final class System
extends Object
The System class contains several useful class fields and methods. It cannot be instantiated.

Among the facilities provided by the System class are standard input, standard output, and error output streams; access to externally defined "properties"; a means of loading files and libraries; and a utility method for quickly copying a portion of an array.

Since:
JDK1.0 <-- 자바 1.0 부터 제공되어왔음을 의미합니다.
------------------------------------------------------------------------------------
첫줄에는 System 클래스가 Object 클래스를 상속받고 final 임을 말해줍니다. 다시말해서

class MySystem extends System

처럼 다른 클래스가 상속받을 수 없는 단종된(?) 클래스임을 말하죠.(이런걸 알려면 그만큼 자바의 기본이 탄탄해야 함을 말하겠죠..)

그 다음줄에는

"몇가지 유용한 클래스 필드와 메소드들을 포함하고 있다. 이 값들은 초기화 될 수 없다"

라고 나와있습니다.


클래스에 대한 기본적인 설명이 끝나고 나면 Field Summary와 Method Summary 가 나옵니다.

Field Summary는 System 클래스가 가지고 있는 필드에 대한 설명이고 Method Summary는 System 클래스가 가지고 있는 메소드에 대한 설명입니다.

Field Summary를 보면 님께서 궁금해하시는

System.in.read()

에서 in 이 바로 System 클래스에 정의되고 구현된 static InputStream 임을 알 수 있을겁니다.

단 순히 System.in.read() 를 봤을때는 System(클래스), in(필드), read()(메소드) 라는 것밖에 모르지만 API를 보면 비로소 in 이 어떤 형의 필드인지, 그 기능은 무엇인지를 알 수 있습니다. 여기서는 InputStream 으로 정의된 in 이라는 것을 알 수 있었습니다.

Field Summary에서 "in"을 누르면 좀 더 자세한 설명을 볼 수 있습니다.

------------------------------------------------------
The "standard" input stream. This stream is already open and ready to supply input data. Typically this stream corresponds to keyboard input or another input source specified by the host environment or user.
--------------------------------------------------------

in 이라는 standart input stream은 이미 열려져 있고 언제든지 입력 데이터를 읽어들일 준비가 되어있다고 나와있습니다. 언제든지 준비가 되어있기때문에 우리는 아무때나

System.in.read() 를 사용해서 키보드에서 "탁탁탁~" 치는 내용을 읽어들일 수 있는겁니다.

그럼 read()는 뭔가를 알고 싶다면 in이 InputStream 형의 객체이므로 read()는 InputStream 클래스에 정의된 메소드임을 알 수 있으므로 InputStream 을 클릭해서 위의 과정을 반복해야 합니다.


API는 이런식으로 이용하는겁니다.



그런데, 사실 자바에 익숙하지 않은 사람이 단지 API만을 보고 "아하~ 그렇구나~" 이해하는건 거의 불가능하다고 봅니다. -_-;;(만약 그런 사람이 있다면 그사람은 대학교에서 컴파일러를 가르치는 교수님이거나 천재일겁니다.)

이때문에 먼저 tutorial 이나 자바 기초 서적을 옆에 두고 API문서의 설명이 구체적으로 어떤식으로 구현되는가를 살펴보는게 중요합니다.

API는 말 그대로 메뉴얼(?) 내지는 설명서에 불과할 뿐, 실제로 어떻게 각 클래스가 구현되어있는지를 말해주지는 않습니다.

진공청소기를 새로 사면 안에 설명서가 있잖아요, 그런 설명서에 불과하더든요. 설명서에는 작동법에 대해서 나타나 있지 진공청소기의 구조가 속속들이 나타나지는 않듯이 API는 클래스의 메소드와 필드에 대한 설명을 하고 있을 뿐이죠.

이때문에 API를 보고 프로그래밍 하는게 처음에는 쉽지가 않지만, 반드시 익숙해져야만 자바 프로그래밍에 익숙해질 수 있습니다.



그럼 한가지 더, javax.swing.JButton 클래스를 놓고 함 분석해보겠습니다.

http://download.oracle.com/javase/1.5.0/docs/api/javax/swing/JButton.html

1. 위처럼 상속구조가 나오고

2. 상속,구현 관계가 나옵니다.

All Implemented Interfaces:
Accessible, ImageObserver, ItemSelectable, MenuContainer, Serializable, SwingConstants

Direct Known Subclasses:
BasicArrowButton, MetalComboBoxButton

JButton 클래스는 6가지의 interface가 구현되어있다고 나와있고 2개의 클래스가 이 JButton 클래스를 상속받고 있다고 나옵니다.

3. 그다음에는 본격적으로 JButton 클래스에 대한 간략한 설명이 나옵니다.

간략한 설명 부분에서는 API에서 설명하기에는 범위가 너무 광범위 할 경우에 How to use 라는 링크를 걸어두고 있습니다. 여기서는

http://java.sun.com/docs/books/tutorial/uiswing/components/button.html

링크를 걸어두고 있네요. API문서는 이렇게 tutorial 문서와 연결되어있습니다. API를 봐도 이해가 안될것 같다 싶으면 강의 링크를 걸어두고 궁금하면 여기가서 더 공부해라, 뭐 그런 의미죠.

4. 그다음에는 Warning 이 나올때도 있고 안나올때도 있습니다. 말 그대로 권고사항 정도입니다.

5. Nested Class Summary 가 나옵니다.

JButton 클래스를 구현할때 그안에 정의된 내부 클래스에 대한 설명이 간략하게 나옵니다. 궁금하면 링크를 눌러서 해당 클래스 페이지로 이동하면 다시 API 문서가 뜰겁니다.

6. Field Summary 에 대해서 나옵니다.

여 기서는 JButton에서 선언되고 정의된 필드 뿐만이 아니라, JButton이 다른 클래스를 상속하고 있으므로 부모 클래스로부터 물려받은 필드들까지 보여줍니다. (Fields inherited from ... 이런 식으로 나옵니다. 그러니까 이 필드들은 각 부모 클래스에 정의된 필드로서 물려받은 유산(?)이라고 보면 됩니다.)

7. Constructor Summary가 나옵니다.

이게 중요합니다. 우리가 어떤 클래스의 인스턴스를 만들때 여기를 잘 봐야지 알 수 있습니다. 반드시 주어진 Constructor 의 형식을 갖춰야지 인스턴스를 생성할 수 있습니다.

8. Method Summary 가 나옵니다.

JButton에서 구현된 메소드 뿐만이 아니라, 부모클래스로부터 물려받은 메소드들까지 나옵니다.

9. Detail part 가 나옵니다.

위에서 설명된 값들에 대한 상세한 설명이 되어있는 부분입니다. 링크를 누르면 이동하도록 되어있죠.



님께서 필요한 클래스를 찾았는데 어떻게 이용할것인지 막막하다고 하셨죠? 당연합니다. API에 익숙하지 않으면 API를 아무리 읽어보더라도 "그래서 어쩌라는거냐"는 말밖에 안나옵니다. ^^


일단 이렇게 해보세요.

필 요한 클래스를 찾았다면 그 클래스를 가지고 무슨 일을 하려고 하는지를 생각하세요. 그리고 그 클래스에 정의된 메소드들을 살펴보세요. 만약 처음 접하는 클래스라면 원하는 기능을 찾기 전에 먼저 Method Field를 한번 읽어보시길 바랍니다.

읽어보시고 대충 이 클래스가 이런 기능을 지원하고 있구나라고 감을 잡으시고 그다음에 보물찾기에 돌입하는 겁니다. ^^;;

일 단 님께서 원하는 기능이 어떤 값을 얻고 싶은것인지, 아니면 원하는 값을 setting 하고 싶은것인지 구별해보세요. 클래스로부터 어떤 값을 추출하고 싶다면 get 으로 시작하는 메소드를 찾아보시고, 어떤 값을 정해주고 싶다면 set으로 시작하는 메소드를 찾아보세요.(없을 수도 있습니다. 그럴 경우는 직접 구현해야 합니다.)




마지막으로 제가 얼마전에 Date 객체를 이용할때 API문서를 사용한 방법을 한번 적어볼께요..

파일을 읽어들여서 마지막으로 수정된 날짜를 구하는 logic을 하고 있어서 날짜를 나타내는 클래스가 필요했습니다. 형식은

2003년 4월 23일

과 같은 식으로 출력하는 것이었습니다.

그래서 일단 File 클래스에서 언제 수정되었는지를 나타내는 메소드를 찾아봤더니

long lastModified()

라는 메소드가 있었습니다. 상세 내용을 보니까

Returns:
A long value representing the time the file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970), or 0L if the file does not exist or if an I/O error occurs

라고 나왔습니다. 1970년 1월 1일 이후의 날짜를 밀리초 단위로 넘겨준다는거였죠...-_-;;;

결국 몇년 몇월 몇일날 수정되었다는 것을 나타내주는 메소드는 없어서 구현해야 하는 상황이었는데, 날짜를 나타내는 Date 객체가 있다는 것을 알고 이 객체를 찾아봤습니다.

lastModified() 메소드가 long 값을 넘겨주니까 long 값으로 Date 객체를 만들 수 있나 찾아봤더니 다행히도 Constructor에

Date(long date)

가 존재했습니다.

그런데 Method Field 를 보니까 getDate(), getMonth(), getYear() 함수가 deprecated 되어버렸더군요.(이제 이 메소드는 쓰지 않는게 좋다는 의미이죠..-_-;;)

난감해했는데, deprecated된 메소드에 다음과같이 쓰여있었습니다.

int getMonth()
Deprecated. As of JDK version 1.1, replaced by Calendar.get(Calendar.DAY_OF_MONTH).

이 함수의 기능은 Calendar.get(Calendar.DAY_OF_MONTH); 로 대체되었다는 말이죠. 그래서 얼씨구나~ 하고 Calendar 클래스 API를 뒤져봤습니다.

그런데 Calendar 클래스를 생성하려고 Constructor Summary를 뒤져봤더니 public 생성자가 없는겁니다.


public 생성자가 없다는 것은

Calendar cal = new Calendar(....);

이런식으로 만들 수 없다는 뜻입니다. 그래서 클래스 설명 부분을 찾아봤더니

Calendar.getInstance() 라는 메소드로 인스턴스를 만들라고 나와있었습니다. 이렇게해서 일단 Calendar 의 인스턴스를 만들 수 있었습니다.

그 런데, 또 문제가 발생했습니다. Calendar 인스턴스를 만들긴 했지만, 제가 원하는것은 그 파일이 언제 수정되었는지를 나타내는 것입니다. 그런데 인스턴스를 만들고 get(Calendar.DAY_OF_MONTH) 를 호출하면 현재의 달, 그러니까 8월이 나오는 겁니다.

이건 제가 원하는게 아니므로 File.lastModified() 로부터 추출한 long 값으로 만든 Date 객체를 어떻게든 적용해야 했습니다.(이것은 원하는 값을 설정해주는 것이므로 set 메소드를 모두 봤습니다.)

set 메소드를 뒤져보니까

--------------------------------------
void setTime(Date date)
Sets this Calendar's current time with the given Date.
--------------------------------------

이렇게 나오더군요. 현재 시간의 Calendar를 주어진 Date 객체로 설정해준다는 것이죠.

이게 바로 제가 찾던 그것이었습니다.

저는 이렇게 해서

File.lastModified() 를 호출해서 Date 인스턴스를 만들었고, 그다음에 Calendar.getInstance() 를 호출해서 현재의 시간에 대한 Calendar 인스턴스를 만들어내고 앞에서 얻어낸 Date 인스턴스의 값으로 설정함으로써 제가 원하는 년, 월, 일을 추출할 수 있게 된것입니다.



API는 이런식으로 이용하면 됩니다.

하지만 API에 원하는 모든게 다 있는건 아닙니다. 다 뒤져봤는데 없다면 직접 구현하는 수밖에 없습니다.

API가 필요한 이유도, 수백개의 클래스, 그리고 그 클래스 안에 정의된 수천개의 메소드와 필드들을 프로그램을 작성하는 사람이 사용할 수 있어야 하기때문입니다.

아 무리 열심해 클래스를 만들어놓으면 뭐하겠습니까? 다른 사람들이 그게 어디다 써먹는건지 모르면 의미가 없겠죠. 이때문에 API를 잘 볼 줄 알아야 프로그램을 더 쉽고 효율적으로 할 수 있다고 하는겁니다.(API몰라도 할 수는 있습니다. 다만 엄청난 시간과 노력이 필요하죠..^^;;)

암튼 많은 도움됐으면 좋겠네요..^^
======================================================================

출처 : http://cauca.springnote.com/pages/1196036

링크및 이미지 수정외엔 거의 원본과 다름없습니다