net.java.ao.DatabaseProviderのjavadocの日本語訳

DatabaseTypeの使いどころを調査していたところ、DatabaseProviderとその子クラスで頻繁に使われていることがわかりました。
そこで、まずDatabaseProviderの役割を理解するために、DatabaseProviderのjavadoc(メソッド概要部分)を日本語訳してみました。
ただし、javadocの内容(英語)を読んでよくわからない箇所は、ソースコードの内容をもとに適当に書きました。そのため、直訳ではありません。

対象のjavadoc: https://activeobjects.dev.java.net/api/net/java/ao/DatabaseProvider.html

更新履歴

更新日	更新内容
2008/12/04	メソッドの概要を修正＆publicでないメソッドを追加
2008/12/04	クラスの概要を追加
2008/12/06	直系の既知のサブクラスを追加

直系の既知のサブクラス

データベース・プロバイダ

クラス	DB
MySQLDatabaseProvider	MySQL
ClientDerbyDatabaseProvider	Derby(ネットワーク)
EmbeddedDerbyDatabaseProvider	Derby(組み込み)
OracleDatabaseProvider	Oracle
PostgreSQLDatabaseProvider	PostgreSQL
SQLServerDatabaseProvider	Microsoft SQL Server
HSQLDatabaseProvider	HSQLDB

参考: http://d.hatena.ne.jp/nattou_curry_2/20081124/1227499541

プール・プロバイダ

PoolProvider

参考: http://d.hatena.ne.jp/nattou_curry_2/20081124/1227491641

クラスの概要

すべてのDatabaseProvider実装の上位クラス。各種の実装のおかげで、(DDLのような)データベース固有の機能の周りを抽象化できています。DatabaseProviderは、Connectionインスタンスの生成と生のJDBCドライバの完全なカプセル化も行います。データベース固有のあらゆるコードは、APIロジック埋め込まずに、データベース・プロバイダー内に置くべきです。

The superclass parent of all DatabaseProvider implementations. Various implementations allow for an abstraction around database-specific functionality (such as DDL). DatabaseProvider(s) also handle the creation of new Connection instances and fully encapsulate the raw JDBC driver. Any database-specific code should be placed in the database provider, rather than embedded within the API logic.

この上位クラスは、多くのデータベース固有のメソッドに対してデフォルトの実装をベースラインとして持っているため、新しいデータベース・プロバイダを実装するために必要なことは最小限になります。(自分が読んだ時の)正気のために言うと、このベースライン実装は基本的にはMySQL固有になっています。したがって、すべてのDatabaseProviderの実装は、対象のデータベースとMySQLの違いをで実装します。このクラスが提供するデフォルト実装をうまく活用するには、このことを覚えておくべきです。

This superclass contains a base-line, default implementation of most database-specific methods, thus requiring a minimum of work to implement a new database provider. For the sake of sanity (read: mine), this base-line implementation is basically specific to MySQL. Thus any DatabaseProvider implementations are really specifying the differences between the database in question and MySQL. To fully utilize the default implementations provided in this class, this fact should be kept in mind.

このクラスでは、スレッド毎に一つのアクティブなConnectionインスタンスを使用可能にするために必要な細かな実装も扱います。実際のところ、これは接続プーリングのとても基本的(かつネイティブな)構造です。パフォーマンスの理由から、これに頼るべきではありません。代わりに、サードパーティの接続プールをクラスパスに入れて、PoolProviderの実装を使用できるようにすべきです。このクラスのスレッド固定の接続プーリングの目的はSQL文の外側でトランザクションを可能にすることです。

This class also handles the implementation details required to ensure that only one active Connection instance is available per thread. This is in fact a very basic (and naive) form of connection pooling. It should not be relied upon for performance reasons. Instead, a third-party connection pool should be available in the classpath, enabling the use of one of the PoolProvider implementations. The purpose of the thread-locked connection pooling in this class is to satisfy transactions with external SQL statements.

コンストラクタの概要

protected

コンストラクタ	概要(日本語訳)	概要(原文)
DatabaseProvider(String uri, String username, String password)	DatabaseProviderの基本的なコンストラクタ	The base constructor for DatabaseProvider.

メソッドの概要

public static

戻り値	メソッド	概要(日本語訳)	概要(原文)
DatabaseProvider	getInstance(String uri, String username, String password)	指定したJDBC URIに合うプロバイダのインスタンスを自動的に取得します。	Auto-magically retrieves the appropriate provider instance for the specified JDBC URI, passing it the given username and password.
DatabaseProvider	getInstance(String uri, String username, String password, boolean enablePooling)	指定したJDBC URIに合うプロバイダのインスタンスを自動的に取得し、ユーザ名とパスワードを渡します。	Auto-magically retrieves the appropriate provider instance for the specified JDBC URI, passing it the given username and password.

public

戻り値	メソッド	概要(日本語訳)	概要(原文)
void	dispose()	データベース・プロバイダや(接続プールのような)委譲を行うライブラリが保持するすべてのリソースを解放すします。	Frees any resources held by the database provider or delegate libraries (such as connection pools).
T	executeInsertReturningKey(Connection conn, Class pkType, String pkField, String sql, DBParam... params)	INSERT文を実行するために委譲されるメソッドで、自動生成された主キーの値を返す。	Delegate method to execute an INSERT statement returning any auto-generated primary key values.
Connection	getConnection()	プロバイダのインスタンスが表すデータベースへのJDBC接続のインスタンスを取得します。	Retrieves a JDBC Connection instance which corresponds to the database represented by the provider instance.
String	getPassword()	データベースの認証に使うパスワードを取得します。	Retrieves the password used to authenticate against the database.
ResultSet	getTables(Connection conn)	データベース中にあるすべてのテーブル(と関連するメタ情報)を結果セットとして返す。	Returns a result set of all of the tables (and associated meta) in the database.
String	getURI()	プロバイダが接続の取得に使用するJDBC URIを取得します。	Retrieves the JDBC URI in use by the provider to obtain connections when necessary.
String	getUsername()	データベースの認証に使用するユーザ名を取得します。	Retrieves the username used to authenticate against the database.
T	insertReturningKey(Connection conn, Class pkType, String pkField, boolean pkIdentity, String table, DBParam... params)	データベースに新しい行を作成するためのINSERT文を生成し、主キーの値を返す。	Generates an INSERT statement to be used to create a new row in the database, returning the primary key value.
Object	parseValue(int type, String value)	データベース固有でないStringの値を(Typesで定義される)intで指定したSQL型として構文解析し、適切なJavaの値を返す。	Parses the database-agnostic String value relevant to the specified SQL type in int form (as defined by Types and returns the Java value which corresponds.
void	putNull(PreparedStatement stmt, int index)	とど	TODO
String[]	renderAction(DDLAction action)	データベース固有でないDDLActionをデータベース固有のDDL文にレンダリングするプロセスで、委譲を行う最上位のメソッド	Top level delegating method for the process of rendering a database-agnostic DDLAction into the database-specific DDL statement(s).
String	renderQuery(Query query, TableNameConverter converter, boolean count)	データベース固有でないQueryオブジェクトをデータベース固有の(可能性がある)問い合わせ文にレンダリングするプロセスで、委譲を行う最上位のメソッド	Top level delegating method for rendering a database-agnostic Query object into its (potentially) database-specific query statement.
void	setQueryResultSetProperties(ResultSet res, Query query)	プロバイダがデータベース固有のオプションを、ライブラリが使用する前に、ResultSetインスタンスに設定できるようにします。	Allows the provider to set database-specific options on a ResultSet instance prior to its use by the library.
void	setQueryStatementProperties(Statement stmt, Query query)	プロバイダがデータベース固有のオプションを、SELECT問い合わせが使用する前に、Statementインスタンスに設定できるようにします。	Allows the provider to set database-specific options on a Statement instance prior to its usage in a SELECT query.

public abstract

戻り値	メソッド	概要(日本語訳)	概要(原文)
Class<？ extends Driver>	getDriverClass()	データベースに対応するJDBCドライバを返すために、抽象化されている	Returns the JDBC Driver class which corresponds to the database being abstracted.

protected

戻り値	メソッド	概要(日本語訳)	概要(原文)
protected boolean	considerPrecision(DDLField field)	フィールドの精度を指定できるどうかデータベースに確認します。	Determines whether or not the database allows explicit precisions for the field in question.
String	convertTypeToString(DatabaseType<？> type)	指定された型をデータベース固有のDDLのString値に変換します。	Converts the specified type into the database-specific DDL String value.
Connection	getConnectionImpl()	プロバイダのインスタンスが表わすデータベースへの新たな接続を作成します。	Creates a new connection to the database prepresented by the provider instance.
String	getDateFormat()	データベース固有のTIMESTAMPのテキストフォーマットをSimpleDateFormatで定義される形式で返す。	Returns the database-specific TIMESTAMP text format as defined by the SimpleDateFormat syntax.
String	getFunctionNameForField(DDLTable table, DDLField field)	(もしあれば)フィールドに対応する関数の名前を取得します。	Retrieves the name of the function which corresponds to the field in question (if any).
String	getTriggerNameForField(DDLTable table, DDLField field)	(もしあれば)フィールドに対応するトリガーの名前を取得します。	Retrieves the name of the trigger which corresponds to the field in question (if any).
boolean	isNumericType(int type)	JDBC型が数値型を表すかどうか確認するための簡易補助関数。	Simple helper function used to determine of the specified JDBC type is representitive of a numeric type.
String[]	renderAlterTableAddColumn(DDLTable table, DDLField field)	既存のテーブルに列を追加するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statements required to add a column to an existing table.
String	renderAlterTableAddKey(DDLForeignKey key)	テーブルに外部キーを追加するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statement required to add a foreign key to a table.
String[]	renderAlterTableChangeColumn(DDLTable table, DDLField oldField, DDLField field)	カラムを古い設計から指定されたDDLの内容に変更するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statements required to change the given column from its old specification to the given DDL value.
String	renderAlterTableChangeColumnStatement(DDLTable table, DDLField oldField, DDLField field)	テーブルとカラムを変更するだけのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statement only for altering a table and changing a column.
String[]	renderAlterTableDropColumn(DDLTable table, DDLField field)	テーブルから列を削除するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statements required to remove the specified column from the given table.
String	renderAlterTableDropKey(DDLForeignKey key)	テーブルから外部キーを削除するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statement required to remove a foreign key from a table.
String	renderAppend()	テーブル定義の最後に追加する必要のあるデータベース固有のオプションを生成します。	Generates any database-specific options which must be appended to the end of a table definition.
String	renderCalendar(Calendar calendar)	Calendarインスタンスをデータベース固有のフォーマットのTIMESTAMPリテラルとしてレンダリングします。	Renders the provided Calendar instance as a TIMESTAMP literal in the database-specific format.
String	renderConstraintsForTable(DDLTable table)	テーブルの外部キー制約をデータベース固有のDDLでレンダリングします。	Renders the foreign key constraints in database-specific DDL for the table in question.
String	renderCreateIndex(DDLIndex index)	新しいインデックスを作成するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statement required to create a new index.
String	renderAppend()	テーブル定義の最後に追加する必要のあるデータベース固有のオプションを生成します。	Generates any database-specific options which must be appended to the end of a table definition.
String	renderCalendar(Calendar calendar)	Calendarインスタンスをデータベース固有のフォーマットのTIMESTAMPリテラルとしてレンダリングします。	Renders the provided Calendar instance as a TIMESTAMP literal in the database-specific format.
String	renderConstraintsForTable(DDLTable table)	テーブルの外部キー制約をデータベース固有のDDLでレンダリングします。	Renders the foreign key constraints in database-specific DDL for the table in question.
String	renderCreateIndex(DDLIndex index)	新しいインデックスを作成するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statement required to create a new index.
String[]	renderDropFunctions(DDLTable table)	テーブルに関連する関数をすべて削除するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statements required to drop all associated functions for the given table representation.
String	renderDropIndex(DDLIndex index)	インデックスを削除するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statement required to drop an index.
String[]	renderDropSequences(DDLTable table)	テーブルに関連するシーケンスをすべて削除するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statements required to drop all associated sequences for the given table representation.
String	renderDropTable(DDLTable table)	テーブルを削除するためのデータベース固有のDDL文を生成します。	Generates the appropriate database-specific DDL statement to drop the specified table representation.
String[]	renderDropTriggers(DDLTable table)	テーブルに関連するトリガーを削除するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statements required to drop all associated triggers for the given table representation.
String	renderField(DDLField field)	フィールドとそのフィールドに関連する型をレンダリングするためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL fragment required to render the field and its associated type.
String	renderFieldPrecision(DDLField field)	フィールドの精度だけの文の断片をレンダリングします。	Renders the statement fragment for the given field representative of its precision only.
String	renderFieldType(DDLField field)	フィールドのデータベース固有のDDL型をレンダリングします。	Renders the database-specific DDL type for the field in question.
String	renderForeignKey(DDLForeignKey key)	外部キーをデータベース固有のDDLにレンダリングします。	Renders the specified foreign key representation into the database-specific DDL.
String	renderFunction(DatabaseFunction func)	DataBaseFunctionをデータベース固有の形式でレンダリングします。	Renders the specified DatabaseFunction in its database-specific form.
String	renderFunctionForField(DDLTable table, DDLField field)	フィールドに対応する関数をレンダリングし、対応がなければnullを返す。	Renders the function which corresponds to the specified field, or null if none.
String[]	renderFunctions(DDLTable table)	テーブルに必要なすべての関数を作成するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statements required to create all of the functions necessary for the given table.
String	renderOnUpdate(DDLField field)	OnUpdate機能を実現するためのフィールド接尾辞をレンダリングします。	Renders the appropriate field suffix to allow for the OnUpdate functionality.
String	renderQueryGroupBy(Query query)	問い合わせのGROUP BY部をデータベース固有のSQL方言にレンダリングします。	Renders the GROUP BY portion of the query in the database-specific SQL dialect.
String	renderQueryJoins(Query query, TableNameConverter converter)	問い合わせのJOIN部をデータベース固有のSQL方言にレンダリングします。	Renders the JOIN portion of the query in the database-specific SQL dialect.
String	renderQueryLimit(Query query)	問い合わせのLIMIT部をデータベース固有のSQL方言にレンダリングします。	Renders the LIMIT portion of the query in the database-specific SQL dialect.
String	renderQueryOrderBy(Query query)	問い合わせのORDER BY部をデータベース固有のSQL方言にレンダリングします。	Renders the ORDER BY portion of the query in the database-specific SQL dialect.
String	renderQuerySelect(Query query, TableNameConverter converter, boolean count)	QueryインスタンスのSELECT部をデータベース固有のSQL実装に必要なやり方でレンダリングします。	Renders the SELECT portion of a given Query instance in the manner required by the database-specific SQL implementation.
String	renderQueryWhere(Query query)	問い合わせのWHERE部をデータベース固有のSQL方言にレンダリングします。	Renders the WHERE portion of the query in the database-specific SQL dialect.
String[]	renderSequences(DDLTable table)	テーブルに必要なすべてのシーケンスを作成するために必要なデータベース固有のDDL文を生成します。	Generates the database-specific DDL statements required to create all of the sequences necessary for the given table.
String	renderTable(DDLTable table)	テーブルをデータベース固有のDDL文にレンダリングします。	Renders the specified table representation into the corresponding database-specific DDL statement.
String	renderTriggerForField(DDLTable table, DDLField field)	フィールドに関連するトリガーをレンダリングし、関連がなければnullを返す。	Renders the trigger which corresponds to the specified field, or null if none.
String[]	renderTriggers(DDLTable table)	テーブルに必要なすべてのトリガーを作成するためのデータベース固有のDDL文を生成します。	Generates the database-specific DDL statements required to create all of the triggers necessary for the given table.
String	renderUnique()	UNIQUE制約をデータベース固有のDDL文法に合わせてレンダリングします。	Renders the UNIQUE constraint as defined by the database-specific DDL syntax.
String	renderValue(Object value)	Javaのインスタンスをデータベース固有のやり方でレンダリングします。	Renders the given Java instance in a database-specific way.
void	setPostConnectionProperties(Connection conn)	新しい接続の作成後に呼ばれます。	Called to make any post-creation modifications to a new Connection instance.

protected abstract

戻り値	メソッド	概要(日本語訳)	概要(原文)
String	renderAutoIncrement()	INTEGERフィールドを自動生成されることを示すためのDDLの断片を生成します。	Generates the DDL fragment required to specify an INTEGER field as auto-incremented.

ActiveObjectsのjavadocにおける特殊な表現

database固有かそうでないかについて、ActiveObjectsのJavadocでは以下の表現が使われています。

database-specific: 「データベース固有の」と訳しました。DBにより異なる表現(実際のDDL文やSELECT文など)を、database-specificと表現するようです。
database-agnostic: 「データベース固有でない」と訳しました。ActiveObjects内部で使われる、抽象的な表現(DDLActionやQueryなど)をdatabase-agnosticと表現するようです。

内部動作を理解したい場合、この違いを区別は重要だと思います。

ここで、重要だと言ってしまったので、次はdatabase-agnosticなオブジェクトについて整理します。

さいごに

~~途中で飽きたのでpublicメソッドだけしか訳してません。~~(かつ確認がおおざっぱ)
気が向いたら続きも訳します。