net.java.ao.schema.AbstractTableNameConverterのJavadoc

ActiveObjectsのnet.java.ao.schema.AbstractTableNameConverterクラスのJavadocの日本語訳です。原文は、https://activeobjects.dev.java.net/api/net/java/ao/schema/AbstractTableNameConverter.htmlです。

以下、日本語訳

net.java.ao.schema 
Class AbstractTableNameConverter
java.lang.Object
	net.java.ao.schema.AbstractTableNameConverter
すべての実装インタフェース:
	TableNameConverter
直系の既知のサブクラス:
	CamelCaseTableNameConverter, PluralizedNameConverter, UnderscoreTableNameConverter

---

public abstract class AbstractTableNameConverter
extends Object
implements TableNameConverter

TableNameConverterの抽象実装です。ほとんどのテーブル名コンバータに共通する基本的な機能を提供します。多くの場合、TableNameConverterを直接継承するより、このクラスを継承する方が適切です。

An abstract implementation of TableNameConverter which provides basic functionality common to most table name converters. For most use-cases, it is best to extend this class rather than directly implementing TableNameConverter.

このクラスが提供する機能のうち一番重要なのは、クラスとパターン(クラス名と生成されるテーブル名)のマッピングです。このマッピングはサブクラス(例えば、CamelCaseTableNameConverterで)からも利用できるため、非常に柔軟にテーブル名の自動生成を行えます。

The primary functionality provided by this class is both class and pattern mappings (between class names and generated table names). These mappings can be passed into arbitrary subclasses (such as CamelCaseTableNameConverter) allowing for maximum flexibility and control over auto-generated table names.

ほとんど場合、サブクラスはconvertName(Class)メソッドをオーバーライドするだけで、十分に機能します。

Most subclasses will only need to override the convertName(Class) method to accomplish most functionality.

作成者:
	Daniel Spiewak

---

コンストラクタの概要

protected AbstractTableNameConverter()

Initializes the class mappings and pattern mappings to empty maps.

メソッドの概要

void addClassMapping(Class<？ extends RawEntity<？>> clazz, String name)	エンティティ型とテーブル名とのマッピングを明示的に追加します。
void addClassMappings(Map>,String> mappings)	複数のクラスマッピングを一回のメソッド呼び出しで追加するための便利メソッドです。
void addPatternMapping(String pattern, String result)	正規表現パターンと変換結果のマッピングを名前コンバータに追加します。
void addPatternMappings(Map mappings, Iterator keys)	複数のパターンマッピングを一回で追加するための便利メソッドです。
protected abstract String convertName(Class<？ extends RawEntity<？>> entity)	クラス型から適切なテーブル名への実際の変換処理を行います。
String getName(Class<？ extends RawEntity<？>> entity)	エンティティ型に対応するテーブル名を返します。
protected String postProcessName(String back)	名前変換の後処理の第一ステップを行います。
protected String processName(String back)	名前変換の後処理の第二ステップを行います。

コンストラクタの詳細

AbstractTableNameConverter

protected AbstractTableNameConverter()

クラスマッピングとパターンマッピングを空のマップとして初期化します。

Initializes the class mappings and pattern mappings to empty maps.

メソッドの詳細

addClassMapping

public void addClassMapping(Class<？ extends RawEntity<？>> clazz,
                            String name)

エンティティ型とテーブル名とのマッピングを明示的に追加します。簡単に言うと、このメソッドはTableアノテーションの集中管理版です。このメソッドを使うと、あらゆる名前変換とパターンマッピングを上書きできます。さらに、エンティティインタフェースに付いている@Tableアノテーションも上書きできます((訳注:クラスマッピングが@Tableを上書きすることはないと思います。検証が必要です)。クラス型に対応するテーブル名を指定するメソッドの中で、このメソッドは最も影響範囲が広いです。

Adds an explicit mapping between a specific entity type and a corresponding table name. This is basically a centralized version of the Table annotation. This will override any name conversion and any pattern mappings available. Additionally, it will override any @Table annotation placed upon the entity interface directly. This is effectively the highest scoped method for specifying table names for correspondant class types.

引数:
	clazz - マッピングを作成するエンティティ型。
	name - エンティティ型に対応するテーブル名。

addClassMappings

public void addClassMappings(Map>,String> mappings)

一回のメソッド呼び出しで複数のクラスマッピングを追加するための便利メソッドです。このメソッドを使えば、クラスマッピングを外部ファイルからロードして、まとめて名前コンバータに渡すこともできます。

Convenience method to add multiple class mappings in a single method call. This allows the things such as loading class mappings from an external file and passing them to the name converter in bulk.

引数:
	mappings - 名前コンバータに渡すすべてのマッピングを含むmap。クラス型が重複した場合、新しいマッピングで上書きされます。
関連項目:
	addClassMapping(Class, String)

addPatternMapping

public void addPatternMapping(String pattern,
                              String result)

正規表現パターンと変換結果のマッピングを名前コンバータに追加します。convertName(Class)で一般的なテーブル名の変換を行った後に、このパターンが適用されます。@Tableかクラスマッピングが使用されたクラス名に対しては、このパターンは適用されません。

Adds a regular expression pattern and corresponding result mapping to the name converter. These patterns will be applied after the generic convertName(Class) value is retrieved. The pattern will not be applied to explicitly specified class names using @Table or a class mapping.

変換結果の値では、正規表現のマッチ結果に含まれるグループを参照することができます。例えば、以下のようにします。

The result value is a parsed string which can contain references to matched groups within the regular expression result. Example:

引数: パターン	引数: 変換結果
(.*p)erson	{1}eople

このマッピングは、「person」で終わる名前(大文字小文字を区別しない)を複数形に置き換えます。よって、「person」は「people」に、「gafferPerson」は「gefferPeople」になります。この例で想像したしれませんが、PluralizedNameConverterでは複数形へのテーブル名変換を実装するために、この種のパターンマッチングを使っています。

This mapping would pluralize any name ending in "person" (match case-insensetive) and replace the name with the pluralized form. Thus, "person" would become "people", "gafferPerson" would become "gafferPeople" and so on. As you may have guessed from the example, this sort of pattern matching is used to implement pluralization in table name conversion (using PluralizedNameConverter.

新たに追加されたマッピングは、マッピングリストの先頭に並びます。そのため、新たなマッピングは既存どのマッピングよりも優先されます。したがって、マッピングは追加した順序とは逆に並ぶため、最後に追加したマッピングが最も優先されます。

Mappings are added to the head of the mapping list. Thus, added mappings override any prior mappings, including prior manual mappings. Thus mappings added sequentially will invert in order, leading to the last mapping having the highest priority in evaluation.

引数:
	pattern - Javaフォーマットの正規表現。マッチさせるパターンを定義します(マッチングは大文字と小文字を区別しません)。
	result - 名前がパターンにマッチした場合、名前をこの文字列値に置き換える。

addPatternMappings

public void addPatternMappings(Map mappings,
                               Iterator keys)

複数のパターンマッピングを一回で追加するための便利メソッドです。マッピングの順序は意識する必要があるため、第二引数に順序を指定しなければなりません。技術的には、LinkedHashMapを渡せば十分なのですが、特定のクラスを使うことを強制したくないのです。

Convenience method to add multiple pattern mappings in a single shot. It's important to note that mappings must be ordered, thus the second parameter is required to enforce this ordering. Technically, just passing a LinkedHashMap would be sufficient, but enforcing the use of that particular class is annoying.

このメソッドを使うと、プロパティファイルからパターンをロードして、まとめて名前コンバータに取り込むこともできます。このやり方は、PluralizedNameConverterで英語の複数形の規則をロードおよび設定するために使用しています。

This method is in place to allow things such as loading of patterns from a properties file and importing them in bulk into the name converter. It is this technique which is used in PluralizedNameConverter to load and setup the english pluralization rules.

新たに追加したマッピングは、マッピングリストの先頭に並びます。そのため、新たなマッピングは既存どのマッピングよりも優先されます。しかし、新たなマッピングは、イテレータで指定した順序の通りに並べられます。したがって、追加されたマッピングはマッピングリストの先頭に並びますが、一方で追加されたマッピング内の順序は指定した順序になります(マッピング内での順序が逆になることはありません)。

Mappings are added to the head of the mapping list. Thus, added mappings override any prior mappings, including prior manual mappings. The order specified by the iterator is maintained however. Thus the addition of a block of ordered mappings will occur at the head of the mappings list, but will themselves remain in order (rather than being reversed).

引数:
	mappings - 追加するパターンマッピング(パターン => 変換結果)。
	keys - パターンの順序を決めるためのイテレータ。順序の評価の仕方を決めることができます。
関連項目:
	addPatternMapping(String, String)

getName

public String getName(Class<？ extends RawEntity<？>> entity)

エンティティ型に対応するテーブル名を返します。このメソッドでは、実際の変換処理を他のメソッドに委譲しています。さらに重要なのは、@Tableアノテーションやクラスマッピングが適用される場合、このメソッドは標準の変換アルゴリズムを実行しません。したがって、該当するクラスマッピングが見つかると、そのマッピングを使用してすぐにメソッドを終了します。その場合には、後処理やパターンマッチングは実行しません。

Returns the corresponding table name for the given entity type. This method handles delegation to other functions to perform the actual conversion. More importantly, this method handles @Table annotations as well as class mappings as a short-circuit on the standard conversion algorithm. Thus if an expressed mapping is found, it will be used and returned immediately, without post-processing, pattern matching or passing "Go".

定義:
インタフェースTableNameConverter内のgetName
引数:
	entity - テーブル名を生成するエンティティ型。
戻り値:
	指定されたエンティティ型に対応するデータベースのテーブル名。
関連項目:
	TableNameConverter.getName(Class)

convertName

protected abstract String convertName(Class<？ extends RawEntity<？>> entity)

クラス型から適切なテーブル名へ、実際に変換する処理を行います。クラスが@Tableアノテーションを持っているかどうかや、パターンマッピングに該当するかどうかについて、このメソッドで意識する必要はありません。これらについては上位実装のgetName(Class)メソッドで対応されています。

Performs the actual operation of converting a class type into a proper table name. This method need not concern itself with particulars of @Table annotations or pattern mappings. All of these things are handled in the getName(Class) method in the superclass implementation.

このメソッドは、可能な限り高速に実行できる必要があり、さらに、スレッドセーフである必要があります。必要であればキャッシュを行っても構いませんが、キャッシュは上位クラスが行うべき範囲です。それはともかく、このメソッドの実装は非常にシンプルにした方がよいです。また、エンティティ変換で必ずしもこのメソッドが呼ばれるとは限りません。(クラスマッピングや@Tableで上書きされているかによります)。

This method must run as fast as possible and should be thread-safe. If necessary, caching may be employed, but it is also within scope for such caching to be utilized within the superclass. As such, the implementation of this method should be kept extremely simple. Also note that this method may not be called for every entity type which must be converted (due to mappings, @Table overrides, etc).

引数:
	entity - 変換したいエンティティ型
戻り値:
	指定された型に対応するテーブル名。

processName

protected String processName(String back)

名前変換の後処理の第一ステップを行います。これにより、パターンマッピングが適用されます。このメソッドは他の変換関数より後に呼ばれます。他の変換関数とは、クラスマッピングやconvertName(Class)などです。

Performs first-step post-processing on converted names. This is where pattern mappings are applied. This method is called after other conversion functions such as class mappings, convertName(Class) and so on.

注意：このメソッドのオーバライドが必要なことはほとんどないでしょう。多くの慣習的な後処理はpostProcessName(String)メソッドで行った方がよいです。postProcessName(String)メソッドはこのメソッドの後に呼ばれ、このメソッドの結果が渡されます。

Note: few implementations will need to override this method. Most conventional post-processing should be handled in the postProcessName(String) method, which is invoked after this method, passing the result.

引数:
	back - 生成されたテーブル名。このテーブル名が規約とパターンに合うように処理する。
戻り値:
	(オプションにより)変更された後のテーブル名。

postProcessName

protected String postProcessName(String back)

名前変換の後処理の第二ステップを行います。このメソッドは変換処理の最終段階としてテーブル名の利用前に呼び出されます。これによって、「すべてのテーブル名を大文字にするべき」のような全体的な規則を適用する実装ができます。より重要度が低い規則や名前ごとに変わる規則は、processName(String)メソッドで行った方がよいです。

Performs second-step post-processing on converted names. This method is called to perform last-stage conventions enforcement prior to utilization of the table name. This allows implementations to impose sweeping conventions such as "all table names should be uppercase" and so on. Any minor or name-specific conventions should be enforced within the processName(String) method.

そもそも、このメソッドがあるるのは、複数形にしたテーブル名に特殊な変換を適用するためです。特殊な変換とは、たとえば、全ての文字の大文字や小文字への変換です。全体的な変更するためにすべてのテーブル名の変換の最後のステップで、このメソッドを呼び出すべきです(ただし、クラスマッピングに当てはまる場合と@Tableアノテーションがある場合は除きます)。デフォルトの実装では、指定された名前をそのまま返します。

The main reason for this method's existence is actually to allow for table name pluralizing on conversions imposing odd conventions, such as all uppercase or all lowercase. This method should be invoked as the last step of any table name conversion (with the exception of class mappings and @Table annotations) to allow for extremely broad-brush changes. The default implementation simply returns the passed name.

引数:
	back - 生成されたテーブル名。このテーブル名が全体的な規則に合うように処理する。
戻り値:
	(オプションにより)変更された後のテーブル名。