Zenn
🍇

21.4 Java標準のその他のツール（javaコマンド、jarコマンド、Javadocなど）～Java Basic編

2023/11/05に公開
Java
Udemy
#
javase
#
java17
tech

はじめに

自己紹介

皆さん、こんにちは、Udemy講師の斉藤賢哉です。私はこれまで、25年以上に渡って企業システムの開発に携わってきました。特にアーキテクトとして、ミッションクリティカルなシステムの技術設計や、Javaフレームワーク開発などの豊富な経験を有しています。
様々なセミナーでの登壇や雑誌への技術記事寄稿の実績があり、また以下のような書籍も執筆しています。

いずれもJava EE（Jakarta EE）を中心にした企業システム開発のための書籍です。中でも 「アプリケーションアーキテクチャ設計パターン」は、（Javaに限定されない）比較的普遍的なテーマを扱っており、内容的にはまだまだ陳腐化していないため、興味のある方は是非手に取っていただけると幸いです（中級者向け）。

Udemy講座のご紹介

この記事の内容は、私が講師を務めるUdemy講座『Java Basic編』の一部の範囲をカバーしたものです。『Java Basic編』はこちらのリンクから購入できます（セールス対象外のためいつも同じ価格）。また定価の約30%OFFで購入可能なクーポンをZenn内で定期的に発行していますので、興味のある方は、ぜひ私の他の記事をチェックしてみてください。

この講座は、以下のような皆様に強くお薦めします。

  • Javaの言語仕様や文法を正しく理解すると同時に、現場での実践的なスキル習得を目指している方
  • 新卒でIT企業に入社、またはIT部門に配属になった、新米システムエンジニアの方
  • 長年IT部門で活躍されてきた中堅層の方で、学び直し（リスキル）に挑戦しようとしている方
  • 今後、フリーランスエンジニアとしてのキャリアを検討している方
  • 「Chat GPT」のエンジニアリングへの活用に興味のある方
  • 「Oracle認定Javaプログラマ」の資格取得を目指している方
  • IT企業やIT部門の教育研修部門において、新人研修やリスキルのためのオンライン教材をお探しの方

この記事を含むシリーズ全体像

この記事はJava SEの一部の機能・仕様を取り上げたものですが、一連のシリーズになっており、シリーズ全体でJava SEを網羅しています。また認定資格である「Oracle認定Javaプログラマ」（Silver、Gold）の範囲もカバーしています。シリーズの全体像および「Oracle認定Javaプログラマ」の範囲との対応関係については、以下を参照ください。

https://zenn.dev/kenya_saitoh/articles/3fe26f51ab001b

21.4 Java標準のその他のツール

チャプターの概要

このチャプターでは、javaコマンド、jarコマンド、javadocコマンドなど、Java標準の各種ツールについて学びます。

21.4.1 javaコマンドと引数

コマンドライン引数

コマンドライン引数とは、javaコマンドによってクラスを実行するときに、外部から渡すことができる引数のことです。
メインメソッドは、public static void main(String[] args) {}と宣言しますが、可変引数を使用してpublic static void main(String... args) {}とすることもできます。いずれにしてもメインメソッドの引数は、String型の配列です。
実はこの配列には、コマンドライン引数が格納されています。
コマンドライン引数は、javaコマンドに以下のように指定します。

java  実行対象クラスのFQCN  引数1  引数2  引数3 ....

引数と引数は、空白文字で区切ります。また引数に空白を含めたい場合は、ダブルクォーテーションで囲む必要があります。
このようにしてjavaコマンドを実行すると、引数1、2、3....がString型の配列として変数argsに格納され、メインメソッドに渡されます。メインメソッドでは、例えば引数1であればargs[0]で値を取得することができます。

独自のシステムプロパティ

前述したようにJavaランタイムはシステム環境に関する情報を、システムプロパティとして管理していますが、開発者が独自のプロパティを定義し、Javaプログラム実行時にJVM引数として設定することも可能です。
JVM引数は、javaコマンドのDオプションによって以下のように設定します。

java  -Dプロパティ名=値  実行対象クラスのFQCN

例えば"program.mode"というプロパティを定義し、その値を実行時に設定する場合は、以下のようにjavaコマンドを投入します。

java  -D"program.mode"=normal  実行対象クラスのFQCN

実行されたJavaプログラムの中ではSystem.getProperty("program.mode")とすることで、設定されたプロパティ値（この場合は"normal"）を取得することができます。
このようにJavaプログラム実行時に外部から何らかの情報を渡す方法には、コマンドライン引数や独自のシステムプロパティといったものがあります。これらの使い分けは、業務処理のための引数はコマンドライン引数、動作環境に関する設定情報はシステムプロパティ、といった具合に考えるのが良いでしょう。

21.4.2 JARファイルとクラスパス

JARファイルとは

Javaには、JARファイルと呼ばれる専用のアーカイブファイルがあります。JARとは「Java Archive」の略称で、JARファイルの拡張子は".jar"です。
JARファイルによって、コンパイル済みのクラスファイルやプロパティファイルや画像ファイルなどのリソースファイルを、アーカイブ、すなわち1つにまとめて管理することが可能になります。JARファイルに資源をアーカイブすることにより、プログラムの配布やテスト環境や本番環境などへの持ち運びが容易になり、可搬性が向上します。
またJARファイルは、内包するクラスを実行するときにわざわざ解凍する必要がありません。JARファイル内のクラスが他のクラスから参照される場合は、ファイル自体にクラスパスを設定することもできます。
なおJARファイルは、後述するjarコマンドによって生成しますが、実際のアプリケーション開発ではGradleなどのビルドツールによって生成するケースが一般的です。

jarコマンドの使用方法

JARファイルは、JDKに付属するjarコマンドによって作成します。
jarコマンドの基本的な構文は以下のとおりで、まずオプションを指定し、その後ろにJARファイル名、そして対象のディレクトリやファイルを記述します。オプションも含めて、Linuxではお馴染みのtarコマンドに似ています。

jar  オプション  JARファイル名  ディレクトリ/ファイル ....

jarコマンドの主要なオプションを、以下に示します。
【表21-4-1】 jarコマンドの主要なオプション

オプション 説明
-c JARファイルを新規作成する＊
-t JARファイルの内容を一覧表示する＊
-x JARファイルを解凍する＊
-u JARファイルを更新する＊
-v 実行中にコマンドラインに処理内容を表示する
-f JARファイル名を指定する

＊の付いたオプションは、1回のjarコマンド実行で1つだけ指定可能

以下に、jarコマンド実行の主な例を示します。

  • 例1：2つのクラスファイル、Foo.class、Bar.classをアーカイブし、JARファイルhoge.jarを新規作成する。
    jar -cvf hoge.jar Foo.class Bar.class
  • 例2：classesディレクトリ配下のすべてのファイルをアーカイブし、JARファイルhoge.jarを新規作成する。
    jar -cvf hoge.jar classes
  • 例3：JARファイルhoge.jarの内容を解凍し、内包するクラス群をカレントディレクトリに展開する。
    jar -xvf hoge.jar
  • 例4：JARファイルhoge.jarの内容を一覧表示する。
    jar -tf hoge.jar

21.4.3 「APIリファレンス」とJavadoc

Javadocとは

Javaにおいて、HTML形式のドキュメントを作成するための標準的な仕組みを、Javadocと呼びます。本レッスンでもたびたび登場した、Java SEの「APIリファレンス」も、Javadocによって生成されています。
Image.png

Javadocを利用すると、ソースコード上に特殊なコメントを記述し、それをツールに読み込ませるだけで、HTML形式のドキュメンドを容易に生成することができます。
このようなドキュメントは、作成したクラスをAPIとして外部に提供する場合、API利用のためのガイドとして必須になるでしょう。またAPI利用者向けのガイドとしてだけではなく、当該アプリケーションの保守のためのドキュメントとして活用するケースもあります。

Javadocのためのコメント記述方法

Javadocによるドキュメント生成では、クラス、またはメソッド、コンストラクタ、フィールドといったメンバーを宣言する直前の位置に、特殊な記法でコメント（Javadocコメント）を記述します。具体的には、以下のように/**から*/までの複数行の範囲がJavadocコメントと見なされます。

snippet
/**    
 * ここにJavadocのためのコメントを記述する（複数行可能）
 */
public class JavadocSample extends Foo implements Serializable {
    ........
}

通常の複数行コメントとは異なり、開始の記法が/**となっている点が特徴です。
またJavadocコメント内には、説明文に加えてJavadocタグと呼ばれる、アットマークから始まるタグを埋め込むことができます。
以下に、比較的よく使われる主要なJavadocタグを示します。

【表21-4-2】比較的よく使われる主要なJavadocタグ

Javadocタグ 説明
@author このクラスの作成者の名前（クラス用）
@version 現在のバージョン（クラス用）
@since 導入されたバージョン（クラスまたはメンバー用）
@param 引数の説明（メソッド、コンストラクタ用）
@return 戻り値の説明（メソッド用）
@exception 例外の説明（メソッド、コンストラクタ用）
@deprecated 非推奨（クラスまたはメンバー用）
@see 参照先（クラスまたはメンバー用）

この中で@deprecatedタグが表す「非推奨」とは、具体的には以下のようなケースを指します。

  • ある要素（クラスやメンバー）に何らかの機能的な不備があり、別の要素の使用を推奨するようなケース
  • ある要素（クラスやメンバー）が不必要になったが、いきなり削除するのではなく、その要素にアクセスしている他クラスへの影響を考慮して、一定期間残存させるようなケース

Javadocコメントの具体例

それでは、Javadocコメントの記載を具体例で見ていきましょう。以下は、パッケージpro.kensait.java.basic.lsn_21_4_3.javadocに所属するJavadocSampleクラスのコードです。このクラス自体には何ら意味はありませんが、クラス、フィールド、コンストラクタ、メソッドに対して、Javadocタグを使ってコメントを記述した例として紹介します。

pro.kensait.java.basic.lsn_21_4_3.javadoc.JavadocSample
/**    
 * <p>クラスJavadocSampleの説明（概要）をここに書く。
 * クラスJavadocSampleの説明（詳細）をこれ以降に書く。</p>
 * <p>説明文中からリンク{@link Foo}を張ることもできる。</p>
 * @author  Kenya Saitoh
 * @version 1.2
 * @since   1.1
 * @see     Serializable
 * @see     Foo#foo
 */
public class JavadocSample extends Foo implements Serializable {
    /**
     * <p>フィールドdata1の説明をここに書く。</p>
     */
    int data1;
    /**
     * <p>フィールドdata2の説明をここに書く。</p>
     */
    int data2;
    /**
     * <p>コンストラクタの説明（概要）をここに書く。
     * コンストラクタの説明（詳細）をこれ以降に書く。</p>
     */
    public JavadocSample() {
    }
    /**
     * <p>メソッドmethod1の説明（概要）をここに書く。
     * method1の説明（詳細）をこれ以降に書く。</p>
     *
     * @since      1.1
     * @param str1 引数str1の説明。
     * @param str2 引数str2の説明。
     * @return     戻り値の説明。
     * @exception  HogeException この例外がどんな状況で発生するか。
     */
    public String method1(String str1, String str2) throws HogeException {
        return str1 + str2;
    }
    /**
     * <p>メソッドmethod2の説明（概要）をここに書く。
     * method2の説明（詳細）をこれ以降に書く。</p>
     */
    private void method2() {
    }
    /**
     * <p>メソッドmethod3の説明（概要）をここに書く。
     * method3の説明（詳細）をこれ以降に書く。</p>
     * @deprecated 「VER1.xで廃止予定」など
     */
    public void method3() {
    }
}

クラスや各メンバーに記述するJavadocコメントに、どのような内容を記載すべきかについては、このコード内のコメントを参照してください。
補足として、まず@see Serializableとありますが、このように記述するとSerializableインタフェースの「APIリファレンス」へのリンクが張られます。
またmethod2のようにprivateなメンバーは外部には非公開のため、ドキュメントとしても外部公開は控えるべきでしょう。ドキュメントにprivateなメンバーを含めるかどうかは、ツールを起動するときのオプションで制御することが可能です。必要に応じて、内部の保守用ドキュメントと外部の利用者向けドキュメントといった具合に、成果物を分けて生成すると良いでしょう。

Javadocによるドキュメント生成

Javadocによるドキュメント生成には、いくつかの方法があります。
まず第一に、JDKに付属するjavadocコマンドを利用する、という方法があります。その他にもEclipseの機能によって生成したり、Gradleなどのビルドツールによって生成したりする方法があります。これらの方法の中でも、実際のアプリケーション開発ではビルドツールを利用するケースが一般的です。
本レッスンでは、前項に登場したJavadocSampleクラスを対象に、Eclipseの機能によってドキュメント生成する方法を紹介します。
まずメニューバーの「ファイル」から「エクスポート」を選択します。「エクスポート・ウィザード」が立ち上がるため「Javadoc」を選択します。

Image.png

続いて対象プロジェクトや、出力ディレクトリを指定します。対象プロジェクトはこのプロジェクト（21_others）のパッケージ"pro.kensait.java.basic.lsn_21_4_3"とし、出力ディレクトリは「C:\LetsLearn\Java\repos\learn_java_basic-main\21_others\doc」としています。またドキュメントの対象にする可視性の範囲を指定します。ここではprivateを選択します。

Image.png

続いて必要なタグにチェックを入れ、またドキュメント内でリンク先を設定する対象を選択します。ここではこのプロジェクト全体とJava SEのクラスライブラリを指定します。

Image.png

続いて生成するHTMLの文字コードを指定し、最後に「完了」ボタンを押下します。

Image.png
すると、指定したディレクトリの下にHTML形式のドキュメントが生成されます。その中のindex.htmlをWebブラウザで開くと、以下のようになります。
Image.png

このチャプターで学んだこと

このチャプターでは、以下のことを学びました。

  1. javaコマンドにおけるコマンドライン引数について。
  2. 独自のシステムプロパティの設定方法について。
  3. JARファイルの特徴やjarコマンドの使用方法について。
  4. 「APIリファレンス」とJavadocによるドキュメント生成方法について。

Discussion