Class Db

java.lang.Object

database.Db

public final class Db
extends Object

輕量級 JDBC 樣板助手:把「取得連線 → 建立 PreparedStatement → 綁定參數 → 走訪 ResultSet → 逐一關閉」這段在數十個檔案重複出現的裸 JDBC 樣板收斂成單一入口,並一律 以 try-with-resources 管理 PreparedStatement/ResultSet 的生命週期。

連線語意(關鍵):所有方法都向 DatabaseConnection.getConnection() 取得 執行緒區域(ThreadLocal)共用連線。此連線由 DatabaseConnection 全程持有並 跨呼叫重用,絕不可關閉;因此本助手的 try-with-resources 只涵蓋 Statement 與 ResultSet,刻意不把 Connection 納入資源管理。這點與專案既有慣例一致(見 MapleAndroid/MapleEquipIdOnly),也是行為保持的前提。

本助手為選用:既有呼叫端可逐步採用,新程式碼建議直接使用。錯誤處理沿用既有風格 —— 方法拋出受檢的 SQLException,由呼叫端依原樣 try/catch 記錄,故導入不改變例外語意。

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Db.RowMapper<T>	把單一資料列(ResultSet 目前游標位置)對應成型別 T 的函式式介面。

Method Summary

Modifier and Type	Method	Description
static int	insertReturningKey(String sql, Object... args)	執行一段 INSERT 並回傳自動產生的第一個鍵值(通常是自增主鍵)。
static <T> List<T>	query(String sql, Db.RowMapper<T> mapper, Object... args)	走訪一段查詢的所有資料列,逐列交給 mapper 轉成 T,彙整為 List 回傳。
static <T> T	queryFirst(String sql, Db.RowMapper<T> mapper, Object... args)	取查詢的第一列;有資料時以 mapper 轉成 T,查無資料則回傳 null。
static int	update(String sql, Object... args)	執行一段 INSERT / UPDATE / DELETE。

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

query

public static <T> List<T> query(String sql,
 Db.RowMapper<T> mapper,
 Object... args)
                         throws SQLException

走訪一段查詢的所有資料列,逐列交給 mapper 轉成 T,彙整為 List 回傳。

Type Parameters:

T - 每列對應的結果型別

Parameters:

sql - 參數化 SQL(以 ? 佔位)

mapper - 把單一資料列(ResultSet 目前游標)轉成 T 的對應器

args - 依序綁定到 SQL 佔位符的參數

Returns:

由每列對應結果組成的清單;查無資料時為空清單(不為 null)

Throws:

SQLException - 任何 JDBC 錯誤

queryFirst

public static <T> T queryFirst(String sql,
 Db.RowMapper<T> mapper,
 Object... args)
                        throws SQLException

取查詢的第一列;有資料時以 mapper 轉成 T,查無資料則回傳 null。

Type Parameters:

T - 結果型別

Parameters:

sql - 參數化 SQL

mapper - 單列對應器

args - 綁定參數

Returns:

第一列的對應結果,或查無資料時為 null

Throws:

SQLException - 任何 JDBC 錯誤

update

public static int update(String sql,
 Object... args)
                  throws SQLException

執行一段 INSERT / UPDATE / DELETE。

Parameters:

sql - 參數化 SQL

args - 綁定參數

Returns:

受影響的資料列數

Throws:

SQLException - 任何 JDBC 錯誤

insertReturningKey

public static int insertReturningKey(String sql,
 Object... args)
                              throws SQLException

執行一段 INSERT 並回傳自動產生的第一個鍵值(通常是自增主鍵)。

Parameters:

sql - 參數化 INSERT SQL

args - 綁定參數

Returns:

自動產生的鍵值;若驅動未回傳任何鍵值則為 -1

Throws:

SQLException - 任何 JDBC 錯誤