□技術メモ - アノテーション JavaDoc Log4j

※管理人の個人的な技術メモです。サンプルソースを実行した結果について
管理人はいかなる責任も負いかねますのでご自身の責任でお試しください。

-----------------------------------------------------------

〇アノテーション

・アノテーションとはデータに対して関連情報（メタデータ）を付加すること。
・Javaにおけるアノテーションとは、クラス、メソッド、パッケージ等に対して付加情報を記入する機能。
・Java標準APIでよく見かけるアノテーションとしては以下のようなものがある。他にもいろいろある。

@Deprecated : 非推奨
@Override   : オーバライドでない場合にエラー表示があるので、スペルミスを見つけやすい。
@SuppressWarnings : コンパイラのワーニングを表示しない。

--------

〇JavaDoc

・JavaのソースコードからHTML形式のAPI仕様書を生成する。
・JDKの javadoc.exe にパスを通して実行する。以下は実行例。
・以下のコマンドで作成されるHTMLを参照しながらjavadocを作成するとよい。

javadoc -private -d testfolder test.java
    // testfolder は作成するフォルダ名。
    // この下にパッケージの階層と同じフォルダ階層が作成される。

・以下は、メソッドに対するjavadocの例。
@param, @throws は複数扱えるが、@return は１つのみ表記できる。

/** タイトル<br>説明<br>
 * @param  変数名    変数の説明
 * @throws 例外      例外の説明
 * @return 戻り値
 * */

・クラスの説明では、@version, @author などが使える。
  Java Platform SE 6 のWebリファレンスなどを参考に、クラスのJavadocを作成すればよい。

・<BLOCKQUOTE>...</BLOCKQUOTE>は、フォーマット済み文書を扱える。
  つまり、このタグ内の文書は見た目そのままでブラウザに表示される。
  通常の改行も、<br>の改行も、１つの改行になる。

--------

〇プロパティエディタ

・Javaにおいて各種設定を記述したファイル。KEY=値の形式で記述されたテキストファイル。
・情報をファイルに読み書きすることが可能。
・英数字(ISO 8859_1)以外の文字をそのまま記述することができないため、2byte文字はUnicode参照文字形式で記述される。
・2byte文字を扱う場合は、native2asciiを使用して、ネイティブコード (Latin 1 および Unicode 以外) のファイルを
  Unicode コードに変換することが必要。
  %JAVA_HOME%\bin に存在する。
  日本語に復元するコマンドは以下の通り。
  native2ascii -reverse [元ファイル名] [復元後ファイル名]
・上記のような変換が煩わしい場合は、Limyプロパティーエディター等のエディタを使うことで
  日本語を扱うことができる。

--------

〇Log4j サンプルコードおよび設定(2017.08記)

・サンプルは以下を参照。
http://3rd.geocities.jp/tnoguchislg/1-java-javaScript/log4j.txt
以下、簡単に説明。
・設定ファイルは、XML形式、プロパティ形式、外部ファイルなしがある。
・以下、XML形式の場合について説明。
・log4j:configuration タグ内にタグ形式で設定する。
・<appender>タグは、出力形式および出力パス（ファイルの場合）などを定義する。
・クラスは、コンソール出力ならConsoleAppender（およびその継承クラス）、
  ファイルならFileAppender（およびその継承クラス）を設定する。
・<root>および<logger>を定義する。
・<logger>には出力対象のクラスを定義する。
  パッケージの階層を指定して、指定の階層およびその配下のクラスからの出力を受け付ける。
・<root>はすべてのクラスからの出力を受け付ける。
  指定の漏れを回避するため<root>を指定してもいいし、
  すべてのログを受け付けてごちゃごちゃするのが嫌なら<root>の中には何も置かなければいい。
・<root>および<logger>の中に<appender-ref>のタグを置くことで、<appender>との紐づけを行う。
  これにより、出力方法および出力パスを指定できる。
・levelタグは、出力レベルの絞り込みを指定できる。
  優先度の高いものから以下の通りになる。
  FATAL, ERROR, WARN, INFO, DEBUG (この下にTRACEがあるらしいが未確認)
・出力レベルは、<appender>タグ、<root><logger>タグのいずれでも指定できる。
  例えば、<appender>でFATAL, <logger>でWARNを指定すれば、出力されるのはFATALのみになる。
・<root>および<logger>内では、<level>は0件もしくは1件指定できる。
  <appender-ref>は複数件指定できる。
・以下、ログ出力実装側の注意点。
・XMLの設定ファイルを読み込む場合と、プロパティ形式の設定ファイルを読み込む場合では、
  コードが違うので注意が必要。
・設定ファイルにXMLを指定する場合は、org.apache.log4j.xml.DOMConfiguratorをimportする。
  utilにも同じ名前のクラスがあって紛らわしいので注意すること。

--------

〇Log4j(2017.06記)

・Javaにおけるロギング実装方法。
  現在は、JakartaからApache Logging Services Projectに移管している。

・設定ファイルはproperties形式か、XML形式で記述する。以下について定義すればよい。
Category : Loggerをグルーピングする。すべてのCategoryの親はrootCategoryになる。
Logger   : ログ出力する本体。
Appender : ログの出力先を表す。標準出力、ファイル、ソケット、メール、Telnetなどに出力可能。	
Layout   : 出力されるログのフォーマット。

・出力フォーマットには以下のようなものがある。(*)付きはパフォーマンスが良くないので注意。
%p    ログの優先順位。優先度の高いものから以下の通り。
      FATAL , ERROR , WARN , INFO , DEBUG
%M(*) ロギング要求をしたメソッド
%l(*) ソース名、行数。
%F(*) ファイル名
%L(*) 行数
%d    日時。%d{HH:mm:ss} や %d{dd MMM yyyy HH}などと記述する。
%C    クラス名
%c    カテゴリ名
%t    スレッド名
%10m  メッセージ。左側空白１０文字埋め。
%-10m メッセージ。右側空白１０文字埋め。
%n    改行

・以下は設定ファイルの例１
--------
#全てのログはエラーレベル出力。Appenderの名称は「Appender1」
log4j.rootCategory=ERROR, Appender1
#Apeenderの具象クラス
log4j.appender.Appender1=org.apache.log4j.FileAppender
#出力先
log4j.appender.Appender1.File=D:\\log\\testlog4j.log
#出力レイアウト。単純なレイアウトならSimpleLayout クラスを使用すればよい。
log4j.appender.Appender1.layout=org.apache.log4j.PatternLayout
#レイアウト定義
log4j.appender.Appender1.layout.ConversionPattern=%d{yyyyMMdd HH:mm:ss} %-5p %c - %m %t (%F:%L)%n
--------

・実装は以下の通り
--------
import org.apache.log4j.Logger;
import org.apache.log4j.PropertyConfigurator;

public class Log4JLoggingTest {
  public static void main(String[] args) {
    Logger logger = Logger.getLogger(Log4JLoggingTest.class.getName());
    PropertyConfigurator.configure(パス + "\log4j.properties"); //設定ファイルを読み込む

    logger.error("error発生！");
  }
}
--------

・以下は設定ファイルの例２
--------
log4j.logger.patternLayoutLogger=WARN,Appender2
log4j.appender.Appender2=org.apache.log4j.ConsoleAppender
log4j.appender.Appender2.Target = System.out
log4j.appender.Appender2.layout=org.apache.log4j.PatternLayout
log4j.appender.Appender2.layout.ConversionPattern=%d{yyyyMMdd HH:mm:ss} %-5p %c - %m %t (%F:%L)%n
--------

・実装は以下の通り
--------
import org.apache.log4j.Logger;
import org.apache.log4j.PropertyConfigurator;

public class Log4jExample {
  public static void main(String[] args) {

    Logger logger = (Logger)Logger.getInstance("patternLayoutLogger");
    //PropertyConfigurator.configure(フルパス);    //パスの指定がない場合は、binの直下等を優先順位順でさがす

    logger.warn("warn発生！");
  }
}
--------

・設定ファイルを探して、最初に見つけたファイルを読み込む。
  下記の順に探すらしい。
--------
log4j.xml（カレントスレッドのクラスローダ上）
log4j.xml（org.apache.log4j.helpers.Loaderのクラスローダ上）
log4j.xml（ClassLoader.getSystemResource()）
log4j.properties（カレントスレッドのクラスローダ上）
log4j.properties（org.apache.log4j.helpers.Loaderのクラスローダ上）
log4j.properties（ClassLoader.getSystemResource()）

・設定ファイルを使用しない場合
--------
public class クラス {

private static final Logger logger = Logger.getLogger(クラス.class);
  static {
    try {
      Layout layout = new PatternLayout("%d{yyyyMMdd HHmmss}%C,%p,%m\n");
      Appender fileAppender = new FileAppender(layout, "./test.log");    //ファイル出力定義
      BasicConfigurator.configure(fileAppender);
      Appender consoleAppender = new ConsoleAppender(layout);            //コンソール出力定義
      BasicConfigurator.configure(consoleAppender);
    } catch (IOException e) {
      e.printStackTrace();
    }
  }
}
--------