| オブジェクト指向プログラミングb 第3回 |
●Java APIの参照とjavadocの使い方「もっとJavaを学ぶ 第1回 (2003年4月 )」
【はじめに】
Javaには「窓を開く」「通信する」「ファイルを読み書きする」といった高度な機能を
持つクラスとそれらをパッケージまとめたものが元から用意されてる。これはJava APIと
呼ばれる。
実用的なソフトウェア・本格的なソフトウェアを作成するためには，このJava APIを知る
必要がある。今回は，
・Java API のマニュアルの見方，
・Javaのソースプログラムからマニュアルを自動生成する javadoc
について解説する。
【APIとJava API】
●API
多少なりとも付加価値の高いソフトウェアを作成するためには，
・音を出す
・ウィンドウを表示する
・グラフィックデータを表示する
・データ通信をしたりする
といった，機能を利用する必要がある。一般に，このような機能はオペレーティングシステム
がAPIとして提供している。APIとは，Application Programming Interfaceの略で，簡単に言
えば，様々な機能を，プログラムから利用できる形にまとめたものである。
一般的なプログラム言語では，Windows OS用のプログラムを作成しようとすれば，Windows
に用意されているAPIを利用することになるし，Macintosh用のプログラムを作成する場合は，
MacOSに用意されているAPIを利用することになる。
プログラミング技術を実践的に身につけていく最初の一歩は，APIの積極的な利用であると言
える。
●Java API
JavaはどのOSの上でも同じように動作する。これは，Java自体に非常に高機能なAPIが元か
ら用意されており，このAPIを使うだけで非常に高度なソフトウェアを作成できるからである。
このJavaに元から用意されているAPIを，Java APIなどと呼ぶ。
【Java APIのドキュメント】
Java APIの仕様書(Java APIドキュメント)の見方を解説する。まず，Java API ドキュメント
が何処で参照できるかを紹介する。なお，基本的にJava API ドキュメントは，htmlファイルで
提供されている。
●大学のデスクトップPC(Windows)
「スタートメニュー」→「Programming」→「Java 1.5.0 ドキュメント」
※情報大のノートPCにもJava API ドキュメントが入っている。探してみよ。
●Javaの公式Webサイト
Javaは米Sun microsystems社が作り上げたプログラミング言語であるため，Sun社がJavaの
公式Webサイト http://java.sun.com/を開設している。この公式サイトにJavaプラットフォーム
(動作環境)や開発環境(SDK, Software Development Kit)，ドキュメントなどが公開されている。
●Javaの種類とバージョン
ドキュメントを見る前に，Javaの種類について簡単に紹介する。Javaには，以下のような種類が
ある。
・スタンダード・エディション(Standard Edition, SE)
標準的な構成のもの。
・エンタープライズ・エディション(Enterprise Edition, EE)
ネットワーク対応の分散アプリケーションなどに用いられる
・マイクロ・エディション(Micro Edition, ME)
携帯電話やPDAなどの組み込み系デバイスに搭載するため，コンパクトにまとめられたもの
本授業で対象とするのは，スタンダードエディション(SE)である。
Javaは登場以来，幾度となく改良を加えられ，バージョンアップを繰り返してきた。2007年10月
の時点ではスタンダードエディションのバージョンは，1.6.0_03である。
ところで，Java APIなどに大きな改良・追加が行われたバージョン1.2以降のJavaプラットフォー
ムには，“Java 2”という名称が与えられている。この末尾の“2”は，Java自体の正式なバージョ
ン番号ではないので，注意が必要である。
なお，配布されているJavaプラットフォーム・ソフトウェアにも種類が異なるものが2つある。
・JRE(Java Runtime Environment)
Javaプラットフォームの純粋な実行環境部分だけを提供したもの。Javaのプログラムを動
かすだけならJREだけでよい
・JDK(Java Standard edition Development Kit)
JREにコンパイラなどの開発ツールを追加した開発用キットをSDK(Software Development
Kit)と呼ぶ。そして，Java SE用のSDK(Java Standard edition Development Kit)のことを
JDKと言う。
●APIドキュメントの入手
ドキュメント類は，以下のページから参照・ダウンロードできる。
・Javaに関するドキュメントサイト
※このページ上にあるリンクをたどっていくとJavaに関する様々な情報を見ることができる。
Java API ドキュメントは以下のところにある。
・JDK5.0 日本語ドキュメントのページ（JDK5.0は大学のコンピュータにも入っているJavaのバージョン1.5.xに対応）
の「API と 言語仕様に関するドキュメント 」欄の下にある「Java 2 プラットフォーム API 仕様」
※一括ダウンロードはここの「J2SE 5.0 ドキュメント」から
（非常に大きいファイルなので，大学のデスクトップPCにダウンロードしないこと）
・JDK6.0 日本語ドキュメントのページ（JDK6.0は最新のJavaのバージョン1.6.xに対応）
の「API、言語、仮想マシンのドキュメント」欄の下にある「JavaTM Platform API 仕様」
※一括ダウンロードはここの「Java SE 6 ドキュメント」から
（非常に大きいファイルなので，大学のデスクトップPCにダウンロードしないこと）
●APIドキュメントの読み方
APIドキュメントを開くと，次のようなページが表示される(図では，大学のデスクトップPCにインストールされている
Java 1.5.0よりも少し古いバージョン1.4.0のものになっているが，概要はほぼ同じである)。実際にこのページを開いてみよ。
このように，Java APIドキュメントのトップページは３つのパートに分かれている。
これらのパートを仮に
右：メインフレーム
左上：パッケージ一覧フレーム
左下：クラス一覧フレーム
と呼ぶことにしよう。
各フレームの概要について以下に紹介する。
●メインフレーム
メインフレームは，パッケージやクラス，インタフェイスなどの情報を詳しく表示するためのフレームである。
メインフレームの上部には，現在何がメインフレームに表示されているかを示すナビゲーションバーがある。最初
は左端の「概要」の項が選択されている。Fig.2の画面のように，初期状態でメインフレームに表示されているのは，
Java 2 SE APIを構成するパッケージの説明付き一覧である。この初期画面こそが「概要」なのである。
ナビゲーションバーには，「概要」の他に，「パッケージ」「クラス」「使用」「階層ツリー」「非推奨API」
「索引」「ヘルプ」という項目がある。これらの項目をクリックすると，それぞれのページを呼び出すことができる。
ページによっては，使用できない項目もある。たとえば，Fig.2にように「概要」を表示している状態では，「パッ
ケージ」「クラス」「使用」の項目は使用できない。「概要」以外の各項目の内容については，後述するが，「ヘル
プ」の項目に簡潔に紹介されているので，一度目を通しておこう。
●パッケージ一覧フレームとクラス一覧フレーム
次に，左側の上下2つのフレームを見てみよう。上部のパッケージ一覧フレームには，「すべてのクラス」という
項目とパッケージの一覧がアルファベット順に表示されている。「すべてのクラス」をクリックすると，Fig.2の画面
のように，クラス一覧フレームには，Java APIに含まれるすべてのクラスの一覧が表示される。
パッケージ一覧フレームの個々のパッケージ名をクリックすると，その下のクラス一覧フレーム内に，クリックした
パッケージの名称とそのパッケージに所属するインタフェイスやクラスなどの一覧がアルファベット順に表示される。
なお，インタフェイスはイタリック体で表示される。
たとえば，下図Fig.3-(1)の java.applet パッケージ名をクリックすると，クラス一覧フレーム(2)には下図に示すよ
うにjava.appletパッケージの名称と，java.appletパッケージに所属するインタフェイスとクラスの一覧が表示される。
●パッケージ情報の表示
クラス一覧フレーム内に表示されたパッケージの名称をクリックすると，メインフレームにそのパッ
ケージの仕様が表示される。下図(Fig.3)の例では，java.appletのパッケージ名称の部分(3)をクリック
し，メインフレームにjava.appletパッケージの説明が表示される(4)。
こうしてパッケージ情報を表示した場合，メインフレームのナビゲーションバーは，「パッケージ」
の項目がアクティブになっている(5)。
パッケージ情報を表示しているとき，ナビゲーションバーの「使用」「階層ツリー」「非推奨API」
をクリックすると，それぞれ次のような情報がメインフレームに表示される。
■「使用」
そのパッケージを使用している他のパッケージや，どのクラスがどのパッケージに使用
されているか，という情報
■「階層ツリー」
この項目は，非常に重要である。「階層ツリー」項目をクリックすると，そのパッケージに
所属するクラスのクラス階層(extendsによる継承関係とimplementsによる実装関係の階層)と，
インタフェイス階層(インタフェイス間のextendsによる継承関係の階層)が表示される。
たとえば，java.appletパッケージの階層構造を表示すると，クラス階層は，下図Fig.4-(1)の
ように表示される(実際に自分で表示させてみよ)。これは，図にするとFig.4-(2)のような階層
を表している。つまり，java.appletパッケージのクラスjava.applet.Appletと，Appletクラス
の内部で定義されているjava.applet.Applet.Applet.AccessibleAppletクラスが，どのような
クラス階層の中にあるかを示しているわけである。
クラス階層やインタフェイス階層を把握することが，Javaをはじめとしたオブジェクト指向言語
によるプログラミングでは非常に重要になる。プログラミングでJava APIを使う場合，このクラス
階層表示機能を使って，使用したいクラスの継承・実装関係を把握すると良い。
■「非推奨API」
この項目は，Javaがバージョンアップする過程で，古くなったり，不都合が出たりしたために，
「もう使用しない方が良い」とされるAPIを表示する。この項目を見て，非推奨のAPIはできるだけ
使用しないように気をつけよ。
●クラス・インタフェイス情報の表示
クラス一覧フレームの中のインタフェイス名，クラス名などをクリックすると，そのインタフェイス
やクラスの説明がメインフレームに表示される。
たとえば，Fig.3の状態でクラス一覧フレームの一番下に表示されているAppletクラスの項目をクリック
すると，メインフレームには，Appletクラスの説明が表示される(下図Fig.5-(2))。このとき，メインフレ
ームのナビゲーションバーは，「クラス」の項目がアクティブになっている(Fig.5-(3))。
メインフレームにクラスの情報を表示すると，クラスを表示した場合，メインフレームには，
(a)そのクラスの継承階層
(b)そのクラスが実装しているインタフェイス
(c)サブクラス
(d)クラスが導入されたときのJavaのバージョン
(e)フィールドの概要
(f)どのクラスからフィールドを継承したか
(g)コンストラクタの概要
(h)メソッドの概要
(i)どのクラスからメソッドを継承したか
(j)コンストラクタの詳細
(k)メソッドの詳細
といった仕様が表示される。インタフェイスを表示した場合も，同様の情報が表示される。
《授業内課題》
・java.applet.Appletクラスについて上記の点(a)〜(b)がどのように記述されているか確認せよ
・java.applet以外のパッケージについても，様々なクラスやインタフェイスの仕様を自分でいろいろと見てみよ。
なお，「パッケージ」の項目をクリックすると，そのインタフェイスやクラスが所属しているパッケージ
の説明がメインフレームに表示される。
以上のように，Java APIのドキュメントは，APIの概要から，詳細な仕様までWebブラウザで効率よく見る
ことができるようになっているので，Javaプログラミングを行うときは，随時参照するとよい。また，プロ
グラミングをしていないときでも，興味のあるところから眺めているだけで，知識がつくし，新たな発見も
あるだろう。
【javadocでドキュメント作成】
このように便利なAPIドキュメントだが，実はJava SDKに付属している javadoc というプログラムを使用
して，Javaのソースプログラムから自動的に作成することができるのである。Java APIドキュメントも，Java
のソースプログラムから自動生成されたものなのである。
このような便利な機能を使わない手は無い。そこで，javadocの簡単な使い方をご紹介していこう。
●javadocとは
javadocは，javaコンパイラの力を借りてソースプログラムを解析し，クラス名・インタフェイス名・フィ
ールド名・メソッド名などを自動的に抽出してくれる。また，説明文をドキュメンテーションコメントと呼ば
れる特別な形式のコメントとして書いておけば，javadocはその内容を処理して，ドキュメントに説明文を挿
入してくれる。
では，まずjavadocコマンドを起動してみよう。javacコマンドやjavaコマンドが使用できる状態になってい
るなら，特に何も設定しなくてもjavadocコマンドも使用できるはずである。コマンドプロンプトから
> javadoc
と入力してみよ(>はプロンプト)。すると，javadocの使い方が表示される。javadocコマンドに指定できるオ
プションも多数表示される。
このように，javadocコマンドには多様なオプションを指定でき，動作を細かくカスタマイズすることが可能
である。しかし，ここではオプションを全く指定せず，デフォルトの状態で使用する例で説明する。また，最も
簡単な使用例として，自分で作成したソースプログラムをドキュメント化するケースをとりあげる。
●javadocの使用例
javadocでドキュメント化する例として，List 1を使用する。List 1はクラスMySampleを宣言しているだけで
す。MySampleは，1つのフィールド，1つのコンストラクタ，1つのメソッドを持っているだけの，非常に単純
なクラスです。
List 1 MySample.java
なお，javadocは日本語文字コードにも対応している。UNIX系OSではEUC-JP(改行コードはLF)で，Windows OS
の場合はシフトJIS(改行コードはCR+LF)でソースプログラムを書く必要がある。なお，MacOS XはUNIX系OSだが，
Windows OSと同様に，シフトJIS(改行コードはCR+LF)で書かなければならない。
では，実際にjavadocを使ってList 1からドキュメントを生成してみよう。まず，List 1のMySample.javaをhtml
ファイルの入っていないフォルダに保存する。これは，javadocがhtml形式のファイルを生成するためで，もし生成
されるファイルと同じ名前のファイルがすでにList 1と同じフォルダにある場合は，それらを上書きしてしまう可能
性があるからである。
ここで，MySample.javaを一度コンパイルし，ちゃんとエラー無しにコンパイルできることを確認しておくこと。
確認が出来たら，次のようにコマンドを入力して，MySample.javaに関するドキュメントを生成する。
> javadoc MySample.java
すると，下図に示す12個のファイルが生成されるはずである。これらが，ドキュメントを構成するファイルである。
青色で示した MySample.html はクラスMySampleのドキュメントなので，クラス名と同じファイル名となっている。
では，Webブラウザで生成されたindex.htmlを開いてみよう。下図Fig.6のように表示されるはずである。左側のフ
レームにはクラスの一覧，右のメインフレームには上下にナビゲーションバーと各項目へのリンクがあり(Fig.6-(1)，
(17))，その間に，クラスMySampleの情報が記載されている。
クラスの情報をよく見ると，いろいろと説明が書かれているのが分かる。たとえば，Fig.6-(2)は，クラス名と継承
関係が表示されている。Fig.6-(3)は，クラスMySampleが，どのクラスを継承しているか(インタフェイスを実装して
いたら，その実装しているインタフェイスも)が書かれている。その他，Fig.6-(7)〜(16)に何が書かれているか，Fig.6
を見て確認せよ。
Fig.6-(4)〜(6)には，それぞれクラスMySampleの説明，MySampleがどのバージョンから導入されたのか，そして
関連項目が書かれてるわけだが，こういった付加情報は，前述したように，ソースプログラム内にドキュメンテーショ
ンコメントとしてプログラマ自身が記述しておく。
では，このドキュメンテーションコメントの書き方を簡単に紹介しよう。
【ドキュメンテーションコメントの書き方】
ドキュメンテーションコメントは，クラス・インタフェイス・フィールド・メソッドなどについての説明を記述するも
ので，説明したいクラス・インタフェイス・フィールド・メソッドなどの宣言の直前に書かなくてはならない。ドキュメ
ンテーションコメントはコメントの一種である。しかし，通常のコメントは /* から始まり */ で終了するが，ドキュメン
テーションコメントは，
/**
で始まり，
*/
で終了する。つまり，コメントの開始時にアスタリスクが２個連続している。下図Fig.7-(1)にあるように，1行でもかま
わないし，複数行に渡って書いてもかまわない。
上図のように複数行でドキュメンテーションコメントを書く場合には，
/**
* 説明文1。
* 説明文2。
*/
という形式になるわけだが，このとき，先頭行の/**と最終行の*/で挟まれた中間行の先頭にある*は，javadocには無視
される。そのため，上記の例の場合，説明文は間の*(と改行)は取り去られ，
説明文1。 説明文2。
となる。
たとえば，List 1-(1)〜(4)は，直後に宣言されているクラスMySampleのドキュメンテーションコメントであるが，
List 1-(2)には，2行にわたってクラスMySampleの説明が書かれている。この説明文が，Fig.6-(4)に表示されているわけ
である。List 1-(2)の2行の行頭にある*が省略されて，2行にわたる説明文が結合され，Fig.6-(4)では1行にまとめられて
いるのがわかる。
ただし，List 1-(2)のように日本語で複数行のコメントを書くと，1行にまとめられるときに，間に半角スペースが入っ
てしまう。List 1-(2)は
* MySample 〜 定義された
* クラスです。〜 立ちません。
となっているが，Fig.6-(4)では，2行の結合部分が
定義された<半角スペース>クラスです。
というように，間に半角スペースが入っている。これは，複数行の結合の仕方が英語をベースに考えられているためである。
●javadocタグ
List 1-(2)の説明文の後で，@から始まる英単語と，それに続くコメントがある(List 1-(3))。この@から始まる英単語は，
javadocタグと呼ばれるもので，特定の情報を記述するのに使用する(Fig.7-(2))。また，ドキュメンテーションコメントは，
前半の説明文部分であるコメントセクションと，後半の1個以上のjavadocタグからなるタグセクションに分かれている(Fig.10-(3))。
なお，タグセクションの後に説明文を書くことはできないので注意が必要である。
javadocタグは，形式的には，
@tag名 タグ用のコメント
という形になる。javadocタグは，ドキュメンテーションコメントの中の行頭(要するに，*の直後)に書かなくてはならない。
また，1行に書けるタグは1つだけだが，タグ用コメントは
* @tag名 複数行にわたるタグ用の
* コメントです。
というように複数行にわたって書くことが可能である(ただし，タグによっては，改行位置に制限がある場合もあるので注意)。
●タグの例：@sinceタグ
List 1-(3)の@sinceタグは，
@since バージョンナンバ
という形式で，そのクラスやインタフェイスが，そのライブラリのいつのバージョンから導入されたかを記述するものである。
List 1-(3)では，
@since 1.0.0
と書かれていて，これはFig.6-(5)のように表示される。
●タグの例：@seeタグ
また，List 1-(3)の@seeは，ハイパーリンクつきの参照先を記述するタグで，
@see クラス名など
とすると，該当するクラス名などを説明したドキュメントファイルへのハイパーリンクを張ってくれる。また，HTMLの<A>
タグを使って，
@see <A href="URL">文字列</a>
とすれば，指定したURLへのハイパーリンクを張ってくれる。List 1-(3)では雑誌CマガジンのWebサイトにハイパーリンク
を張ってあるので，Fig.6-(6)のC Magagineという文字列をクリックすると，CマガジンのWebサイトに移動する。
このように，ドキュメンテーションコメントの中では，一部のHTMLタグを使用することも可能である。例えば，
●MySampleの例
では，List 1のクラスMySampleの宣言の中身を見ていこう。ここで，List 1を再掲する。
List 1 MySample.java
List 1-(5)，(6)，(7)は，それぞれフィールド，コンストラクタ，メソッドの宣言を行っている。javadocが生成したドキュ
メントでは，フィールド，コンストラクタ，メソッドの概要が，Fig.6-(7)，(8)，(9)のようにあり，その後で，それぞれの詳
細情報が記載されている(Fig.6-(11)〜(16))。なお，概要欄と詳細欄の間には，そのクラスが継承したメソッドが，継承元ごと
にまとめられて表示されている(Fig.6-(10))。
List 1-(5)はフィールドaのドキュメンテーションコメントと宣言である。ここで注意して欲しいのは，Fig.6-(7)の「フィー
ルドの概要」のaの欄の説明(Fig.6-(7))では，ドキュメンテーションコメントの第1番目の文「フィールドaは，テスト用フィー
ルドです。」の部分だけが記載されていることである。このように，概要欄には，説明文の第1文が記載される。そのため，説明
文の第1文は，その文だけで概要が分かるような文にしなくてはならない。これは，コンストラクタやメソッドの説明文について
も同様である。
●タグの例：@paramタグ
List 1-(6)は，コンストラクタのドキュメンテーションコメントと宣言である。ここで登場するタグ@paramは，仮引数を説明
するもので，
@param 仮引数名 説明文
という形になっている。List 1-(6)の@paramタグの記述は，ドキュメントでは，Fig.6-(13)のように表示される。
●タグの例：@returnタグ
List 1-(7)は，メソッドfoo()のドキュメンテーションコメントと宣言である。新しいタグとして，@returnが登場している。こ
のタグはメソッドの返り値(戻り値)を説明するタグで，
@return 返り値の説明
という形で使用する。List 1-(7)の記述例は，Fig.6-(16)のように表示される。
●javadocを活用しよう
なお，javadocによってドキュメント化されるメンバは，デフォルトでは，publicメンバとprotectedメンバだけである。他の
アクセス特性を持つメンバの説明をドキュメント化したい場合は，javadocコマンドにオプションで指定することになる。その他，
javadocの詳しい使い方は，Javaのドキュメントをダウンロードすればその中に含まれているし，Javaの公式Webサイトでも公開
されている(JDK5用，JDK6用)ので，それを参照するように。
以上のように，javaでは，ソースプログラムから効率の良いブラウジングが可能なドキュメントを，自動的に生成する機能が備
わっている。参考書や雑誌記事のサンプルプログラムなどでは，スペースの都合上，ドキュメンテーションコメントは省略されて
いることが多いが，実際のソースプログラムでは，ちゃんとドキュメンテーションコメントをつけているのが普通である。自分で
プログラムを作成する場合は，積極的にjavadocを活用して，javaプログラミングを効率よく行えるようにしてみるとよい。
参考：
javadoc コマンドは，通常の使用では，protected と public のクラスとメンバーだけをドキュメント化します。
したがって，public指定されていないクラスや，privateなメンバなどはドキュメント化されません。
これは，利用者用マニュアルとしてのドキュメントを作成するのが本来の目的だからです。つまり，利用者に
隠すべき所(=利用者が知らなくてもよい所)はドキュメント化しないわけです。
しかし，開発者が，publicでないクラスやprivateなメンバも掲載された自分用のマニュアルを必要とする場合も
あるでしょう。そういった場合は，-private というオプションを付けて
> javadoc -private ソースファイル名
とすれば，publicでないクラスやprivateなメンバもドキュメント化される。
その他のjavadocのオプションについては，
> javadoc -help
とすると，オプション一覧が表示される。各プションの詳細やjavadocのその他の詳しい解説はこちら(JDK1.5用)
をやこちら(JDK1.6用)参照せよ。
戻る