自 Java 1.4 開始，JDK 包括了一個嶄新的日志框架包 java.util.logging，該日志框架設計精良，和 JDK 緊密結合，控制靈活，使用簡 單。日志記錄對於軟件的維護特別是對於已部署到運行環境之後的軟件調試都有著重要的意義。在實際的項目中，往往還需要比該框架所提供 的更為復雜的日志功能。對於這種需求，JDK 日志框架具有足夠的可擴展能力，可以自定義不同需求的日志處理、消息格式化、日志消息級別 等組件。在下面的內容中，本文將介紹了如何擴展 JDK 日志框架，自定義日志處理方式。並就一個實際的例子來介紹如何結合 JDK 日志框架 和 STAF（Software Testing Automation Framework，一種自動化測試框架）日志服務來對 Java 程序進行監視。
JDK 日志框架介紹
JDK 的日志框架即 java.util.logging 包。對於一個軟件的日志系統而言，首先必須得有一個日志對象，該對象負責記錄日志信息。同時 該信息可以輸出到不同的位置，例如控制台，文件甚至網絡中。對於信息的格式，則可以根據不同的需求，可以輸出成普通文本，XML 或者 HTML 的格式。同時還需要對日志信息進行不同級別的分類，這樣的好處是可以過濾冗余信息，只保留關鍵的日志。對於一個日志框架而言，日 志對象必須是可配置的，它可以按照配置來輸出到指定的目標，同時按照配置來決定輸出的格式和決定何種級別以上的日志才能輸出。配置的 形式還可以是多種多樣的，既能是代碼的形式，也能是配置文件的形式。尤其是配置文件的形式，對於一個已經部署到運行環境中的軟件而言 ，可以非常方便的改變日志配置而無需改變其源代碼。
JDK 日志框架提供了上述的所有功能。它主要包括如下幾個部件：
Logger：日志記錄對象。用於記錄日志信息。
Handler：用於處理日志信息的輸出。在 Handler 類中，可以決定日志是輸出到文件中還是控制台中。
Filter: 用於過濾日志。在 Filter 類中，可以根據日志級別或者某種條件來決定是否輸出該日志。這樣達到去除冗余信息的目的。
Formatter：用於格式化日志信息。該類可以將日志文本格式化成 XML 或者 HTML 的格式，這完全依賴於具體的實現。
Level：用於表示日志的級別。 JDK 日志框架默認有如下級別 : SEVERE，WARNING，INFO，CONFIG，FINE，FINER，FINEST 。
對於程序而言，它的 Logger 對象首先會判斷日志的級別是否滿足輸出級別的要求，然後將滿足級別要求的日志消息交給所配置的 Handler 對象來處理，如果日志對象配置了一個 Filter 對象，那麼 Filter 對象將會對日志信息做一次過濾。 Handler 對象接受到日志消息後，根據 其所配置的格式化類 Formatter 來改變日志的格式，根據所配置的 Filter 對象和 Level 對象來再次過濾日志信息，最後輸出到該種 Handler 對象所指定的輸出位置中，該輸出位置可以是控制台，文件，網絡 socket 甚至是內存緩沖區。其架構模型如 圖 1 所示。
圖 1 JDK 日志框架
JDK 提供了如下幾種默認支持的 Handler 類：
ConsoleHandler： 輸出日志到控制台中
FileHandler：輸出日志到指定文件中
MemoryHandler：輸出日志到內存緩沖區中，當一定的條件滿足的時候（如某種關鍵字的日志信息）再將緩沖區中的日志輸出
SocketHandler: 輸出日志到網絡 socket 中
StreamHandler: 輸出日志到輸入輸出流對象中
同時 JDK 日志框架也不失其靈活性，你可以定制自己所需要的 Handler，將日志按照自定義的需求輸出到不同的位置，同時 Formatter， Level 類都可以自定義擴展，下面就詳細敘述如何自定義擴展這些組件。
自定義日志 Handler
所有的 Handler 類都是繼承自 java.util.logging.Handler 抽象類，該類結構圖如 圖 2 所示。
圖 2 Handler 類圖
由該類圖可見，Handler 抽象類提供了抽象接口：publish, flush 和 close 。這些接口提供了日志輸出的基本功能。同時 Handler 類保 存了 Formatter，Filter 和 Level 對象用來控制日志輸出。因此，編寫自定義的 Handler 類需要如下步驟：
繼承 Handler 抽象類
實現 publish，flush 和 close 方法。其中 publish 方法是用於發布一條日志記錄。 flush 方法是清空內存緩沖區。 close 方法是當應 用程序關閉的時候，釋放該 Handler 類所申請的資源（如文件，socket 等）
設置默認的 Formatter，Filter 和 Level 對象。必要的時候，可以在類的初始化時候讀取配置文件來設置這些參數。
一個典型的自定義 Handler 類實現如清單 1 所示。
清單 1 自定義 Handler 類
public class MyHandler extends Handler {
private boolean doneHeader = false;
public MyHandler() {
setLevel(Level.INFO);
setFilter(null);
setFormatter(new SimpleFormatter());
}
_cnnew1@Override
public void close() throws SecurityException {
if (!doneHeader) {
output(getFormatter().getHead(this));
doneHeader = true;
}
output(getFormatter().getTail(this));
flush();
}
@Override
public void flush() {
// 清空緩沖區
}
@Override
public void publish(LogRecord record) {
if (!isLoggable(record)) {
return;
}
String msg = getFormatter().format(record);
try {
if (!doneHeader ) {
output(getFormatter().getHead(this));
doneHeader = true;
}
output(msg);
} catch (Exception ex) {
reportError(null, ex, ErrorManager.WRITE_FAILURE);
}
}
private void output(String message) {
// 實現日志輸出
}
}
這裡 reportError 方法是將日志類中的錯誤信息輸出到外界，這個是由 ErrorManager 類實現的，ErrorManager 類負責記錄日志框架中 Handler 的錯誤，一般情況下是將該錯誤打印到控制台中。具體的每條日志消息被 JDK 日志框架封裝成 LogRecord 對象，該類部分定義如 清 單 2 所示。
清單 2 LogRecord 類定義
public class LogRecord implements java.io.Serializable {
public String getLoggerName();
public void setLoggerName(String name);
public ResourceBundle getResourceBundle();
public void setResourceBundle(ResourceBundle bundle);
public Level getLevel();
public void setLevel(Level level);
public String getMessage();
public void setMessage(String message);
public Object[] getParameters();
public void setParameters(Object parameters[]);
public int getThreadID();
public void setThreadID(int threadID);
public long getMillis();
public void setMillis(long millis);
public Throwable getThrown();
public void setThrown(Throwable thrown);
...
}
由清單 2 可見，LogRecord 類包含了一個日志消息的級別、消息文本、時間、參數、線程等等所有的信息，這些都交給 Handler， Formatter 和 Filter 這些對象來處理。同時該類也是可序列化的，可以序列化到網絡和文件中。該類還可以和一個 ResourceBundle 對象綁 定，實現消息字符串的本地化處理。
本節描述了一個典型的自定義的 Handler 類的實現。在本文後面部分將會有一個實際的例子來介紹如何實現一個 STAF 日志處理類。
自定義日志 Formatter
日志可以被格式化為一定格式的文本，也可以成為 XML 或者 HTML 這樣標准的格式。這取決於 Formatter 類的具體實現。 Formatter 抽 象類提供了 format 成員函數用於擴展。一個典型的自定義 Formatter 類實現如清單 3 所示：
清單 3 LogRecord 類定義
public class MyFormatter extends Formatter {
private final String lineSeparator = System.getProperty("line.separator");
@Override
public String format(LogRecord record) {
StringBuffer sb = new StringBuffer();
String message = formatMessage(record);
sb.append(record.getLevel().getLocalizedName());
sb.append(message);
sb.append(lineSeparator);
if (record.getThrown() != null) {
try {
StringWriter sw = new StringWriter();
PrintWriter pw = new PrintWriter(sw);
record.getThrown().printStackTrace(pw);
pw.close();
sb.append(sw.toString());
} catch (Exception ex) {
}
}
return sb.toString();
}
}
其中 formatMessage 方法提供了默認的將日志記錄本地化和格式化的方法。它還能支持 java.text 風格的文本格式化，這只需要在調用 Logger 對象的 setMessage 方法設定 java.text 風格的格式字符串，同時通過 setParameters 方法設置參數，這樣 formatMessage 將會根 據所設置的 java.text 風格的格式字符串來格式化日志消息。總之，formatMessage 方法方便了子類格式化字符串。使子類只需要定義輸出文 本的格式而無需考慮本地化等問題。
自定義日志消息級別
JDK 日志框架默認提供了 SEVERE，WARNING，INFO，CONFIG，FINE，FINER，FINEST 這幾種日志級別。如果我們需要定義更多的日志級別， 只需要繼承 java.util.logging.Level 類，然後將自定義的級別作為靜態成員變量聲明即可。一個典型的自定義的消息類如清單 4 所示。
清單 4 自定義 Level 類
public class MyLevel extends Level {
protected MyLevel(String name, int value) {
super(name, value);
}
public static final Level Level1 = new MyLevel("Level1", 123);
... // 其他自定義級別
}
權重值 value 是一個整型數。在默認的 JDK 日志級別中，SEVERE 的權重是 1000，FINEST 是 300，可以根據具體的需求來定義每個自定 義級別的權重。例如在 WARNING 和 INFO 級別中加入一個新的級別，該級別的權重必須介於 800 到 900 之間。
自由的日志配置
和其他日志框架一樣，JDK 日志框架同樣提供了強大的日志配置功能。你既可以通過代碼進行動態配置，也可以通過配置文件來實現自由靈 活的配置。通過代碼動態配置，應用程序可以實現在運行過程中改變日志類的配置，動態地改變不同的配置組合。一個簡單的動態配置代碼如 清單 5 所示。
清單 5 動態配置 Logger 對象
public static void main(String[] args){
Handler fh = new FileHandler("%t/wombat.log");
Logger.getLogger("logname").addHandler(fh);
Logger.getLogger("com.wombat").setLevel("com.wombat",Level.FINEST);
...
}
配置文件的配置方法則同樣靈活多變。它主要是在應用程序啟動時根據一個指定的配置文件來設置日志對象。在配置文件中，日志對象是由 其名稱來標識的。一個典型的日志配置文件如清單 6 所示。
清單 6 JDK Logger 配置文件
# 設置日志對象的 Handler，日志對象的名稱是 com.xyz.foo
com.xyz.foo.handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler
# 設置日志對象的基本輸出級別
com.xyz.foo.level = INFO
#FileHandler 只允許輸出 SEVERE 以上級別的日志
java.util.logging.ConsoleHandler.level = SEVERE
#ConsoleHandler 允許輸出 INFO 以上級別的日志
java.util.logging.ConsoleHandler.level = INFO
當設置好一個日志配置文件後，在 java 程序的啟動參數中，我們可以通過添加 -Djava.util.logging.config.file 參數來定義配置文件 路徑，一個典型的 java 命令行如下：
java -Djava.util.logging.config.file=logger.properties -cp . Mainclass
我們也可以在應用程序中聲明自定義的 Handler，Formatter，Level 等組件，這只需要這些自定義組件能夠在 classpath 中找到即可。
實例——結合 STAF 日志服務
STAF（Software Testing Automation Framework）是一個自動化軟件測試框架，它可以實現分布式的自動化軟件測試管理。我們可以應用 STAF 庫的 Java API 來做基於 STAF 框架的應用，同時 STAF 同時也提供了日志服務。其日志服務是用來記錄自動化測試流程中的信息，方便 在 24x7 的自動化測試中記錄自動化測試的操作，便於發現潛在的自動化測試管理腳本的問題。
既然我們可以用 STAF 的 Java API 來做基於 STAF 的應用，我們也可以將 JDK 的日志框架同 STAF 的日志服務接口結合起來。 STAF 的 日志服務的 Java 接口定義如清單 7 所示：
清單 7 STAFLog 類定義
public class STAFLog
{
public STAFLog(String logType, String logName, STAFHandle handle);
public STAFResult log(int level, String msg)
// Log type constants
public static STAFResult log(STAFHandle theHandle, String logType,
String logName, int level, String msg)
public String getName();
public String getLogType();
public int getMonitorMask();
... //other methods
}
從清單 7 我們可以看出，STAFLog 類提供了方法可以將日志信息存儲到 STAF 的日志庫中， 這個日志庫既可以是本地的文件，也可以是另 一個 STAF 服務器上的日志庫。這是通過本地 STAF 服務器的配置來決定的。而 STAFLog.log() 方法只用於記錄日志信息。
將 STAF 日志服務的 Java API 同 JDK 日志框架結合起來需要做如下步驟：
創建 STAF 日志 Handler 類
該類封裝了 STAF 日志服務 API 的接口。同時 STAF 的 Java API 需要一個全局的 STAFHandle 對象，用來表示本地的 STAF 服務句柄。 這個可以通過建立一個靜態的 STAFHandle 對象即可。其代碼如下所示，我們定義了一個 STAFHandler 類如清單 8 所示。
清單 8 STAFHandler 類實現
import java.util.logging.*;
import com.ibm.staf.wrapper.STAFLog;
public class STAFHandler extends Handler {
private String logName;
private static STAFHandle stafHandle = null;
public STAFHandler(String name) {
configure();
logName = name;
}
public STAFHandler() {
configure();
}
@Override
public void close() throws SecurityException {
if (stafHandle != null){
try {
stafHandle.unRegister();
} catch (STAFException e) {
//ignore
}
}
}
@Override
public void flush() {
//nothing
}
@Override
public void publish(LogRecord record) {
if (!isLoggable(record)) {
return;
}
String msg;
try {
msg = getFormatter().format(record);
} catch (Exception ex) {
reportError(null, ex, ErrorManager.FORMAT_FAILURE);
return;
}
try {
STAFLog.log(stafHandle, STAFLog.MACHINE,
logName, record.getLevel().getName(), msg);
} catch (Exception ex) {
reportError(null, ex, ErrorManager.WRITE_FAILURE);
}
...
在實現 STAFHandler 類時有以下幾個要點：
由於 STAF API 的調用時需要一個 STAFHandle 的對象來代表本地的 STAF 服務，在該類中聲明了一個全局變量用來存儲 STAFHandle 。
close 方法是用來清理系統資源的，上述代碼的 close 方法中釋放了全局變量 STAFHandle 對象。
publish 方法就是獲得格式化後的消息後，直接調用 STAF 的日志 API 將日志發送到 STAF 服務中。
但到目前為止，我們還沒有給 STAFHandler 類添加一個配置的代碼，使之可以支持配置文件。下面我們定義了一個函數 configure，其代 碼如清單 9 所示。
清單 9 配置函數實現
private void configure() {
if (stafHandle == null) {
try {
stafHandle = new STAFHandle("my application");
} catch (STAFException e) {
reportError("registe staf handle error", e, ErrorManager.OPEN_FAILURE);
}
}
LogManager manager = LogManager.getLogManager();
String cname = getClass().getName();
//set staf log name
logName = manager.getProperty(cname + ".name");
if (logName == null)
logName = "demo.staflog";
//set formatter
String sformatter = manager.getProperty(cname + ".formatter");
Formatter formatter = null;
if (sformatter != null) {
try {
formatter = (Formatter)Class.forName(sformatter).newInstance();
} catch (Exception e) {
//ignore
}
}
setFormatter(formatter == null? new STAFFormatter() : formatter);
//set level
String sLevel = manager.getProperty(cname + ".level");
Level level = null;
if (sLevel != null) {
try {
level = STAFLevel.parse(sLevel);
} catch (Exception e) {
//ignore
}
}
setLevel(level == null? STAFLevel.DEBUG : level);
}
在實現配置文件支持的代碼中，有以下幾個要點：
STAF API 的初始化需要注冊 STAFHandle 對象。而且該注冊只能執行一次。我們根據全局變量 stafHandle 的值來決定是否注冊該對象。
JDK 的日志框架有一個全局的 singleton 管理類 STAFManager，該類用於管理日志類，並提供了讀取日志配置文件的成員函數 getProperty 。在上述的代碼中，我們通過 STAFManager.getProperty 方法，從日志配置文件中讀取 STAFHandler 對象所設置的 Formatter 類名，然後通過反射生成一個新的 Formatter 對象，設置到 Handler 對象中。
對於日志級別也是通過 STAFManager.getProperty 方法。需要注意的是由於我們的日志級別是自定義的級別，所以 Level 對象是由我們自 定義的 Level 類 STAFLevel 來生成的。
我們也能定義自己需要的屬性。比如清單 9 中我們定義了一個 .name 屬性，用來存儲 STAF 日志名稱，通過 getProperty 函數從配置文 件中讀取 .name 屬性。
創建一個適合 STAF 日志的 Formatter 類
由於 STAF 日志服務無需特殊的格式，我們只需要定義一個普通文本格式的 Formatter 即可。其代碼如清單 10 所示，注意這裡考慮了如 果記錄了一個異常對象的情況，將異常對象的 stack 打印到字符串中添加到消息文本中。
清單 10. STAFFormatter 實現
import java.io.*;
import java.util.logging.*;
public class STAFFormatter extends Formatter {
private final String lineSeparator = System.getProperty("line.separator");
@Override
public String format(LogRecord record) {
StringBuffer sb = new StringBuffer();
String message = formatMessage(record);
sb.append(message);
sb.append(lineSeparator);
if (record.getThrown() != null) {
try {
StringWriter sw = new StringWriter();
PrintWriter pw = new PrintWriter(sw);
record.getThrown().printStackTrace(pw);
pw.close();
sb.append(sw.toString());
} catch (Exception ex) {
}
}
return sb.toString();
}
}
創建對應於 STAF 日志級別的 Level 對象
這是由於 STAFLog 有著不同的日志消息級別，它包括 Fatal， Error, Warning, Info, Tracer, Debug 等級別，有些是 JDK 日志框架已 有的級別，有些則不是。我們需要增加新的 Level 對象來滿足 STAFLog 的需求。一個新的 Level 類：STAFLevel 定義如清單 11 所示。
清單 11 自定義 STAFLevel
import java.util.logging.Level;
public class STAFLevel extends Level {
protected STAFLevel(String name, int value) {
super(name, value);
}
protected STAFLevel(String name, int value, String resourceBundleName) {
super(name, value, resourceBundleName);
}
public static final Level FATAL = new STAFLevel("FATAL",980);
public static final Level ERROR = new STAFLevel("ERROR",980);
public static final Level TRACE = new STAFLevel("TRACE", 790);
public static final Level DEBUG = new STAFLevel("DEBUG", 690);
}
清單 11 定義了 FATAL，ERROR，TRACE 和 DEBUG 級別。這就和 STAFLog 中的部分級別一一對應起來了。
將一切組合起來
清單 12 描述了如何在一段實際的代碼中將 STAF 日志處理類和 JDK 日志類結合起來。 從清單 12 可以看出，該實例默認指定輸出到 STAF 日志服務的日志名稱為“ staflogger ”。然後通過動態配置的方法來設定 Handler，Level 和 Formatter 。最後在調用 JDK 的日志對 象的 log 方法記錄了 4 種自定義級別的日志。
清單 12 一個完整的例子
package demo.staflog;
import java.util.logging.Logger;
public class STAFLoggerTest {
public static void main(String[] args) {
Logger logger = Logger.getLogger(STAFLoggerTest.class.getName());
logger.setUseParentHandlers(false);
logger.setLevel(STAFLevel.DEBUG);
STAFHandler stafHandler = new STAFHandler("staflogger");
stafHandler.setLevel(STAFLevel.DEBUG);
stafHandler.setFormatter(new STAFFormatter());
logger.addHandler(stafHandler);
//log
logger.log(STAFLevel.DEBUG, "debug log");
logger.log(STAFLevel.FATAL, "fatal log");
logger.log(STAFLevel.ERROR, "error log");
logger.log(STAFLevel.TRACE, "trace log");
}
}
但我們也可以將這些代碼改為配置文件的方式，其配置文件如清單 13 所示：
清單 13 STAFLog 類定義
# 設置日志對象的 Handler
demo.staflog.STAFLoggerTest.handlers= demo.staflog.STAFHandler
demo.staflog.STAFLoggerTest.level = DEBUG
# 取消發送日志到父 Logger 對象
demo.staflog.STAFLoggerTest.useParentHandlers = FALSE
# 設置 Handler 的名稱，輸出級別和格式化對象
demo.staflog.STAFHandler.name= staflogger
demo.staflog.STAFHandler.level = DEBUG
demo.staflog.STAFHandler.formatter = demo.staflog.STAFFormatter
這樣代碼可以簡化為清單 14 。
清單 14 STAFLog 類定義
public class STAFLoggerTest {
private static Level defaultLevel = STAFLevel.DEBUG;
public static void main(String[] args) {
//log
logger.log(STAFLevel.DEBUG, "debug log");
logger.log(STAFLevel.FATAL, "fatal log");
logger.log(STAFLevel.ERROR, "error log");
logger.log(STAFLevel.TRACE, "trace log");
}
}
配置文件的方式相對於動態配置的方式更加靈活，因為這無需改變和重新編譯代碼，只需要修改配置文件，就能修改日志中 Handler， Level 和 Formatter 的組合配置，這對於已經部署發布的軟件而言，有著更為實際的意義。
當運行代碼後，在命令行中輸入 STAF 命令來顯示 STAF 日志 staflogger：
mymachine:~ myname$ staf local log query machine mymachine logname staflogger
Response
--------
Date-Time Level Message
----------------- ----- ----------
20081111-16:15:21 Debug debug log
20081111-16:15:21 Fatal fatal log
20081111-16:15:21 Error error log
20081111-16:15:21 Trace trace log
這顯示了我們剛才在 Java 代碼中記錄的信息，它們已經被輸出到 STAF 的日志服務中了。
結束語
JDK 日志框架簡單靈活，它雖然比 log4j 出現的時期晚，但其功能並不比 log4j 少。而且 JDK 日志框架直接隸屬於 JDK，被 Java 標准 所支持而無需安裝第三方庫文件。本文介紹了 JDK 日志框架的結構，如何擴展 JDK 日志框架使之滿足實際的項目需求。並以如何在 Java 程 序中將日志輸出到 STAF 的日志服務中為例，一步步描述了如何實現擴展 JDK 日志組件，使之和 STAF 日志服務結合到一起，同時如何創建靈 活的配置文件來組合日志框架組件。希望本文可以給其他需要擴展 JDK 日志組件的開發者提供幫助。
本文配套源碼
