アノテーションには、pureQuery StaticBinder がインターフェースに対してバインド操作を実行するときに使用するオプションを制御するメタデータを 含めることもできます。
@ColumnOverride(propertyName="extension", column="PHONE")
public class EmployeeNewCo extends Employee {...
構文図で使用されている規則については、構文図の読み方を参照してください。
>>-@ColumnOverride--(--propertyName--=--"--property--",--column--=--"--name--")-><
>>-@ColumnOverrides--(------------------------------------------> .-,----------------------------------------------------------------------------. V | >--{----@ColumnOverride--(--propertyName--=--"--property--",--column--=--"--name--")-+--}--> >--)-----------------------------------------------------------><
@ColumnOverride アノテーションの配列は、@ColumnOverrides アノテーションの小括弧内の中括弧内に存在します。
>>-@Table--(--name--=--name_of_table----------------------------> >--+---------------------------------+--)---------------------->< | (1) | '-------schema--=--name_of_schema-'
クラス・レベルで指定されるオプション・アノテーションです。 これは、Bean 内のすべてのプロパティーに対してデフォルト表名を指定します。 このアノテーションは、結合が含まれる SQL ステートメントに対してネストされた Bean のセットを作成する場合は必要ありません。 ただし、このアノテーションを使用すると Bean の定義が簡素化されます。
デフォルト表名は、@Column アノテーションで指定された表名でオーバーライドできます。
@Table アノテーションは、@JoinColumn アノテーションに対してデフォルト表名を指定しません。
インライン・スタイルの @ColumnOverride や @ColumnOverrides とは異なり、@Table アノテーションは データ・アクセス・オブジェクト (DAO) スタイルとインライン・スタイルの両方でサブクラスによって継承されます。
pureQuery は、public フィールド、public get() メソッド、および set() メソッドでのみ プロパティー・レベル・アノテーションを認識します。 pureQuery は、private フィールドまたは保護フィールドではアノテーションを認識しません。
構文図で使用されている規則については、構文図の読み方を参照してください。
このアノテーションは プロパティーのマップ先となるデータベース・オブジェクト内の SQL 列を指定します。 このアノテーションは public フィールドおよび public メソッドでのみ使用できます。 他の場所で使用するとしても、pureQuery はそれを無視します。>>-@Column--(--name--=--name_of_column--+-------------------------+->< '-table--=--name_of_table-'
次の 2 つの理由のいずれかに該当する場合は、@Column アノテーションを使用できます。
@Column(name="DEPTNO")
public String deptNum;
@Column(name="EMPNO")
public String getEmpNum() {
return empNum;
}
例
select a.col1, b.col1 from a, b where a.id=b.id;
照会結果を
保持する Bean 内の対応するプロパティーのメソッド setA_col1 と setB_col1 には、2 つの col1 列が
存在する表の名前を指定する @Column アノテーションが必要です。
public class JoinExample{
private int a_col1;
private int b_col1;
@Column (name="col1", table="a")
public void setA_col1 (int a_col1)
{
this.a_col1 = a_col1;
}
public int getA_col1 ()
{
return a_col1;
}
@Column (name="col1", table="b")
public void setB_col1 (int b_col1)
{
this.b_col1 = b_col1;
}
public int getB_col1 ()
{
return b_col1;
}
}
>>-@Format--(--fomatterClass--=--formatter_class----------------> >--+-----------------------------------------+--)-------------->< '-, -formattingOptions--=--pattern-string-'
このアノテーションで指定されるクラスには、 必要な変換を行うために呼び出されるフォーマッターと、そのフォーマット設定オプションが含まれています。 このアノテーションは、pureQuery メソッドの入力または出力として指定される Bean オブジェクト内のフィールドで 使用できます。このアノテーションは、DAO スタイルとインライン・スタイルの両方に適用されます。
このフォーマッター・クラスは、 ストリング・フィールドを入力変数用の適切な JDBC 日時型に変換し、 返された JDBC 型を出力用のストリング変数に変換およびフォーマット設定します。
次の例では startDate フィールドがフォーマット設定されています。
class MyBean {
…
@Format(formatter=com.ibm.pdq.Dateformatter.class, formattingOtions=”style=LONG;
timezone=UTC”)
String startDate;
…
}
このアノテーションは Java プリミティブ・フィールドには適用されません。 Java プリミティブが NULL 値を表すことができないためです。
@Required アノテーションが指定されない場合、デフォルトの動作では、入力パラメーター上の Java NULL が認識され、 対応するホスト変数値が SQL NULL に設定されます。
SQL パラメーターに対する入力として使用されるフィールドに @Required アノテーションが指定されていて、 そのフィールドにアクセスしたときに Java NULL 値がそのフィールドに含まれている場合、pureQuery によって例外が スローされ、SQL 操作は試行されません。
次の例では、customerAddress 値に NULL 以外の値が含まれていなければなりません。
@Required
String customerAddress;
表結合が含まれる SQL 照会の場合、ネストされた Bean のセットを作成して、 その Bean が照会からデータを返すようにすることができます。Bean の階層は、データベース内のデータの関係構造を複製したものです。 表と列の関係を指定するには、ネストされた Bean で pureQuery アノテーションを指定します。 pureQuery Runtime は、照会の結果を Bean に追加します。 表結合で使用されるネストされた Bean について詳しくは、表結合を含むネストされた Bean および SQL 照会を参照してください。
プロパティー・レベルのアノテーション
>>-@Id---------------------------------------------------------><
このアノテーションは、同一クラスの Bean 同士が等しいことを判別するために pureQuery Runtime で 使用される ID 列をアノテーション付きプロパティーが表すように指示します。 このアノテーションは Bean のプロパティーで使用されます。 ID 列 とは、子 Bean を親 Bean にリンクする列のことです。 pureQuery Runtime でネストされた Bean を生成できるようにするには、少なくとも 1 つの @Id アノテーションをトップレベルの Bean で指定する必要があります。 データベース内で一致する列を、主キー列または外部キー列として宣言する必要はありません。
@Column アノテーションを @Id アノテーションとともに使用すれば、ResultSet オブジェクトをキー列にマップする列名と表名を指定できます。
子 Bean では、@Id アノテーションまたは @JoinPoint アノテーションを使用して、親 Bean を子 Bean にリンクする ID 列を定義できます。 両方のアノテーションを指定した場合、@JoinPoint アノテーション情報が使用され、@Id アノテーションは無視されます。 @JoinPoint アノテーションは親 Bean での Bean に対する参照において指定されます。 @Id アノテーションはその Bean 自体において指定されます。
Bean に複合キーがある場合、複数の @Id アノテーションを子 Bean において指定するか、 またはキーを親 Bean の @JoinPoint アノテーションとともに指定する必要があります。 @JoinPoint アノテーションでは、propertyName エレメントを含む @JoinColumn アノテーションでキーを指定する必要があります。
pureQuery Runtime は、ネストされた Bean の処理時に Bean が同じかどうかを判断するために、@Id アノテーションを持つ Bean プロパティーを検査します。 @Id アノテーションを持つすべてのプロパティーが同一の場合、その Bean は同じと見なされます。 @Id アノテーションを持つ Bean プロパティーは、データベースにおいて主キーや外部キーでなくてもかまいませんが、 同一クラスの Bean 同士が等しいことをこのプロパティーから判断できなければなりません。
>>-@JoinColumn--(--name--=--name_of_column----------------------> >--+--------------------------+---------------------------------> '-table--=--name_of_column-' >--+-----------------------------------+--)-------------------->< '-propertyName--=--name_of_property-'
このアノテーションは、親 Bean のプロパティー名が ResultSet オブジェクトの 列ラベルとも、表名とも一致しない場合、子 Bean の ID 列として ResultSet オブジェクトの列を指定します。 このアノテーションは、子 Bean 上のアノテーションとして親 Bean 内で指定されます。 子 Bean は単一 Bean または Bean リストです。
@JoinColumn アノテーションは、@JoinPoint アノテーションでのみ指定できます。
空ストリング ("") を name エレメントの値として指定すると、pureQuery Runtime は、プロパティーが一致しないという警告を生成せずに、 このプロパティーでのネストされた Bean 生成のサポートを無効にします。 特定の子 Bean/Bean リストにデータを追加したくない場合は、サブクラスに空ストリングを指定します。
>>-@JoinPoint---------------------------------------------------> >--+-----------------------------------------------------------------------------------------+->< '-(--+--------------------------------------------------+--+-------------------------+--)-' '-+------------+--array_of_@JoinColumn_annotations-' '-columnPrefix--=--prefix-' +-joinCol--=-+ '-value--=---'
トップレベル Bean (つまりメソッドまたはインライン API の戻り値である Bean) で 1 つ以上の @JoinPoint アノテーションを指定する必要があります。 このアノテーションにより、pureQuery Runtime でネストされた Bean のセットを生成できるようになります。
このアノテーションは、Bean/Bean リストが含まれるプロパティーでのみ定義できます。 オプションの @JoinColumn アノテーションは、子 Bean の ID 列にマップされる ResultSet オブジェクトの列を定義します。 オプションの columnPrefix エレメントは、子 Bean 内の各プロパティーに追加される列接頭部を指定します。 子 Bean に複合キーがある場合は、ResultSet オブジェクトの複数の列をキー列として指定する必要があります。
このアノテーションは、Bean/Bean リストが含まれるプロパティーでのみ定義できます。 オプションのエレメント(@JoinColumn アノテーションの配列、または columnPrefix エレメント) が 1 つも指定されていない場合、 すべての ResultSet マッピングと ID 列定義が子 Bean から取得されます。
@JoinColumn アノテーションの配列はオプションであり、子 Bean プロパティーに適用されます。 複数の @JoinColumn アノテーションの配列は、中括弧 ({ }) で囲む必要があります。
@JoinColumn アノテーションが指定されていない場合、pureQuery Runtime は参照先の子 Bean の @Id アノテーションを使用して、子 Bean のID 列にマップされる ResultSet 列を判別します。 子 Bean に @Id アノテーションが 1 つも含まれていない場合は、警告が生成され、その子 Bean は無視されます。
エレメント joinCol とエレメント value は同時には使用できません。 どちらか一方を指定することはできますが、両方を指定することはできません。 このエレメントは、columnPrefix エレメントの指定時は必須エレメントです。
columnPrefix エレメントの値は、子 Bean 内の各プロパティーの前に付けられるストリングを指定します。 pureQuery Runtime はこの接頭部を使用して固有のクラスとプロパティーを生成します。 この接頭部を使用すれば、同じ Bean クラスを反復なしでネストされた Bean 構造内の異なるレベルまたは同一レベルで使用できます。 このような接頭部付きのプロパティーは固有になるようにしてください。 接頭部がクラスに追加されると、その接頭部は、その接頭部が付けられたクラスの Bean のすべての子 Bean とプロパティーに適用されます。 接頭部は追加式になっていて、必要な深さまでネストし続けることができます。 columnPrefix エレメントの値は子 Bean にのみ適用され、親 Bean の @JoinColumn アノテーションで定義されている列ラベルには適用されません。
列の接頭部は、子 Bean にデータを追加する列が照会で返される場合にのみ適用されます。
@JoinPoint({
@JoinColumn (name = "DEPTNO", table = "DEPARTMENT", propertyName="empDepartment"),
@JoinColumn (name = "EMPNO", table = "EMPLOYEE", propertyName="employeeId")
})
public List<Employee> getListofDeptEmployees ();
最初の @JoinColumn アノテーションは、DEPARTMENT 表の DEPTNO 列を Employee Bean の プロパティー empDepartment にマップします。
ResultSet オブジェクトの列ラベル WORKDEPT を使用することを選択したのであれば、 列ラベル WORKDEPT が ResultSet オブジェクトに存在する場合は、エレメント propertyName = "empDepartment" エレメントを指定する必要はありません。 プロパティー WORKDEPT は、Employee Bean 内のアノテーション @Column (name = "WORKDEPT") によって作成されました。
@JoinPoint(value = {
@JoinColumn (name = "DEPTNO", table = "DEPARTMENT", propertyName="empDepartment"),
@JoinColumn (name = "EMPNO", table = "EMPLOYEE", propertyName="employeeId")
})
public List<Employee> getListofDeptEmployees ();
@JoinPoint(columnPrefix = "DE", joinCol = {
@JoinColumn (name = "DEPTNO", table = "DEPARTMENT", propertyName="empDepartment"),
@JoinColumn (name = "EMPNO", table = "EMPLOYEE", propertyName="employeeId")
})
public List<Employee> getListofDeptEmployees ();
部門の従業員を表す DE という columnPrefix が 接頭部として Employee Bean のすべてのプロパティーに付けられています。 このストリング DE は、ResultSet のすべての従業員列 (Employee Bean の部門リスト用に定められた列) に (AS 文節によって) 追加されます。
この接頭部は、その Employee Bean 内のすべての子 Bean にも適用されます。
例えば、Employee Bean に子 Department Bean が含まれている場合、 その Employee Bean 内にある Department Bean のすべてのプロパティーには接頭部として DE が付けられます。
このように接頭部が付けられる処理は、ResultSet オブジェクト内のすべてのレベルで繰り返されます。 子 Department Bean 内にある Employee Bean のリストの 2 番目のレベルでは接頭部として DEDE が付けられます。
この接頭部は、該当する Employee Bean 内のすべての子 Bean にも 適用されます (ネストされた Bean 構造内のすべての Employee Bean が対象というわけではありません)。 例えば、この接頭部は Project Bean 内の Employee Bean のリストでは使用されません。
@JoinPoint
public List<Emp> emps;
@JoinPoint(columnPrefix="m_")
public Emp manager;
columnPrefix="m_" エレメントを指定すれば、 接頭部として m_ が付いた EMPLOYEE 表の列が Emp manager フィールドにマップされます。
CREATE TABLE HRDEPT.EMPLOYEE(
EMPNO CHAR(6) NOT NULL,
FIRSTNME VARCHAR(12) NOT NULL,
MIDINIT CHAR(1),
LASTNAME VARCHAR(15),
WORKDEPT CHAR(2),
PHONENO CHAR(4),
HIREDATE DATE,
PRIMARY KEY(EMPNO))
一部の列名は、短縮されているか、または Java 命名規則に従っていません。Employee Bean の以下の定義では com.company.Employee クラスのオブジェクトのユーザーにさらに有意な名前を提供するために、@Column アノテーションを使用しています。
public class Employee
{
private String employeeId;
private String firstName;
private String middleInitial;
private String lastName;
private String departmentId;
private String extension;
private Date hireDate;
@Column(name = "EMPNO")
public String getEmployeeId ()
{
return employeeId;
}
public void setEmployeeId (String employeeId)
{
this.employeeId = employeeId;
}
@Column(name = "FIRSTNME")
public String getFirstName ()
{
return firstName;
}
public void setFirstName (String firstName)
{
this.firstName = firstName;
}
@Column(name = "MIDINIT")
public String getMiddleInitial ()
{
return middleInitial;
}
public void setMiddleInitial (String middleInitial)
{
this.middleInitial = middleInitial;
}
public String getLastName ()
{
return lastName;
}
public void setLastName (String lastName)
{
this.lastName = lastName;
}
@Column(name = "WORKDEPT")
public String getDepartmentId ()
{
return departmentId;
}
public void setDepartmentId (String departmentId)
{
this.departmentId = departmentId;
}
@Column(name = "PHONENO")
public String getExtension ()
{
return extension;
}
public void setExtension (String extension)
{
this.extension = extension;
}
public Date getHireDate ()
{
return hireDate;
}
public void setHireDate (Date hireDate)
{
this.hireDate = hireDate;
}
}
わずかに異なるスキーマを持つデータベースに対してアプリケーションが実行されるとします。 表は以下のように定義されます。
CREATE TABLE HRDEPTNEWCO.EMPLOYEE(
EMPNO CHAR(6) NOT NULL,
FIRSTNME VARCHAR(12) NOT NULL,
MIDINIT CHAR(1),
LASTNAME VARCHAR(15),
WORKDEPT CHAR(2),
PHONE CHAR(4),
HIREDATE DATE,
PRIMARY KEY(EMPNO))
新しい表定義を使用できるように、Employee Bean のサブクラスを作成して、 前のアノテーションをオーバーライドできます。 サブクラスの先頭は、以下のようになります。
@ColumnOverride(propertyName="extension", column="PHONE")
public class EmployeeNewCo extends Employee {...
@Id
@GeneratedKey
@Column(name = "EMPNO")
public String getEmployeeId ()
{
return employeeId;
}
public void setEmployeeId (String employeeId)
{
this.employeeId = employeeId;
}
@Id
@Column(name = "WORKDEPT")
public String getDepartmentId ()
{
return departmentId;
}
public void setDepartmentId (String departmentId)
{
this.departmentId = departmentId;
}
@JoinPoint({
@JoinColumn (name = "DEPTNO", table = "DEPARTMENT", propertyName="workDept"),
@JoinColumn (name = "EMPNO", table = "EMPLOYEE", propertyName="employeeId")
})
public List<Employee> getListofDeptEmployees ();
最初の @JoinColumn アノテーションでは、DEPARTMENT 表の DEPTNO 列が Employee Bean 内の プロパティー workDept にマップされます。 ResultSet の列ラベル WORKDEPT が使用された場合、ResultSet に列ラベル WORKDEPT が存在すれば、propertyName="workDept" は必要ありません。 プロパティー WORKDEPT は、Employee Bean 内のアノテーション @Column (name = "WORKDEPT") によって作成されます。