8. アノテーション定義支援ツール

8.1. アノテーションの一覧表示・編集

8.1.1. アノテーション・ビューの表示

アノテーション・ビューは以下の手順で開きます。
メニュー ウィンドウ ＞ ビューの表示 ＞ その他... を選択すると、ビューの表示画面が表示されます。
ビューの表示画面で、WebOTX アノテーション ツール ＞ アノテーション・ビュー を選択して、OK をクリックします。

図8.1.1-1

アノテーション・ビューが表示されます。

図8.1.1-2

エディタ、あるいはプロジェクト・エクスプローラーで選択されるJava要素によって、付与できるアノテーションを一覧表示します。
アノテーション・ビューは以下のような画面です。

図8.1.1-3

各項目の説明を以下に示します。

表8.1.1-1

項番	項目	説明	備考
(1)	Java要素情報	付与対象の説明です。付与対象とは、ソースエディタでフォーカスのJava要素です。Java要素について、下記Java要素リストを参照してください。 表示形式： Annotaion型：要素名---ファイル名 有効なJava要素が選択されない場合、「Please select a Java element from an editor or explorer」というメッセージを表示します。	例： Type:TestStatelessSessionBean---TestStatelessSessionBean.java 意味は、該当ビューで表示するのはクラスTestStatelessSessionBeanに付与できるアノテーションです。該当クラスはTestStatelessSessionBean.javaファイルに定義されます。
(2)	Annotations	アノテーションの名前あるいはアノテーションの属性名を表示します。
(3)	Values	アノテーション名の場合は該当アノテーションがJava要素に付与されるかどうかを示します； アノテーション属性の場合は、該当属性の値を示します。	(1)アノテーション名の場合： trueの場合、該当アノテーションがJava要素に付与されます； falseの場合、該当アノテーションがJava要素に付与されません。 (2)アノテーション属性の場合： booleanあるいは列挙型の場合は、コンボボックスです； その以外は、テキストボックスです。
(4)	「+」、「-」ボタン	アノテーションの属性を表示するかどうかを制御します。	+をクリックして、該当アノテーションの属性を表示します； -をクリックして、該当アノテーションの属性を表示しません。

注：上記付与対象というJava要素リストは以下のとおりです。

表8.1.1-2

型	説明
Type	Java要素はクラス、インターフェース（アノテーションを含む）、あるいはenum（列挙型）であることを示します。
Method	Java要素はメソッドであることを示します。
Field	Java要素はフィールドであることを示します。
Parameter	Java要素はパラメータであることを示します。

Caution
コンストラクターはMethodに含まれません。コンストラクターはサポートしません。

アノテーションの付与できる対象はTarget属性としてアノテーション側で定義されています。エディタでJava要素にフォーカスをあてると、アノテーション・ビューには、Targetの適合するアノテーションの一覧が表示され、編集することができます。

8.1.2. アノテーションの一覧表示機能

Java要素の型によって、付与できるアノテーションを一覧表示する機能について説明します。
クラス（Type）に付与できるアノテーションの一覧表示は以下の画面の通りです。
付与対象がクラスまたはメソッドで、カテゴリが EJB 3.0である場合の画面表示を例に説明を行います。
付与対象がクラスの場合：

図8.1.2-1

エディタでクラス名が選択された場合、javax.ejb.Statelessやjavax.ejb.StatefulなどTargetがTypeであるアノテーションが一覧表示されます。（TargetがMethodであるjavax.ejb.PostActivateやjavax.ejb.PrePassivateなどは、一覧には表示されません。）
付与対象がメソッドの場合：
メソッドに付与できるEJB3.0に所属するアノテーションの一覧表示は以下の画面の通りです。

図8.1.2-2

エディタでメソッド名が選択された場合、javax.ejb.PostActivateやjavax.ejb.PrePassivateなどTargetがMethodであるアノテーションが、ビューで表示されます。（前出の、TargetがTypeであるjavax.ejb.Statelessやjavax.ejb.Statefulなどは一覧には表示されません。 ）

表8.1.2-1

選択された付与対象	カテゴリ	説明
クラス	プロジェクトのアノテーション表示選択により、選択された該当カテゴリのアノテーションを表示します。詳しくは8.2. アノテーション表示選択・ビューを参照してください。	カテゴリ設定範囲内において、Target定義にクラスが含まれるアノテーションを表示します。
メソッド		カテゴリ設定範囲内において、Target定義にメソッドが含まれるアノテーションを表示します。
その他		カテゴリ設定範囲内において、Target定義に付与対象が含まれるアノテーションを表示します。

Caution
1.javax.ejb.TransactionAttributeやjavax.interceptor.InterceptorsなどTargetがType、Method両方であるアノテーションは、クラス名が選択された場合もメソッドが選択された場合も、一覧に表示されます。
2.アノテーションをTargetとは異なる対象に付与すると、エディタでエラーが発生します。詳しい情報は8.3. アノテーションの検証を参照してください。
3.各アノテーションのTargetは、8.4. サポートするアノテーションを参照してください。

8.1.3. アノテーションの新規追加機能

具体的な例で、アノテーションの新規追加機能の使い方を説明します。
以下はjavax.ejb.StatelessをJavaクラスに追加する例です。
下図は、アノテーションを追加する前のエディタとアノテーション・ビューの状態です。

図8.1.3-1

アノテーション・ビューで、javax.ejb.StatelessアノテーションのValuesをtrueに変更します。

図8.1.3-2

javax.ejb.StatelessアノテーションがクラスTestStatelessSessionBeanに付与されます。
下図は、javax.ejb.StatelessアノテーションがクラスTestStatelessSessionBeanに付与された後の画面です。

図8.1.3-3

エディタで、以下の変化をご確認ください。
(1)　TestStatelessSessionBeanクラスの定義前で@Stateless()が追加されます。
(2)　import javax.ejb.Stateless;句が追加されます。
(3)　アノテーション・ビューでjavax.ejb.StatelessアノテーションのValuesはtrueにしたことを確認します。

8.1.4. アノテーションの属性の変更機能

アノテーション・ビューを使って、Java要素に付与されるアノテーションの属性を追加・更新・削除することができます。
具体的な例で、アノテーションの属性変更の使い方を説明します。
以下はjavax.ejb.Statelessを変更する例です。
下図は、属性変更の前のエディタとアノテーション・ビュー状態です。

図8.1.4-1

まず、アノテーションの属性の追加について説明します。
アノテーション・ビューで、javax.ejb.Statelessアノテーションのdescription属性のValuesにThe description of Stateless Annotationと、入力して、ENTER キーを押します。

図8.1.4-2

エディタで、@Statelessアノテーションにdescription属性が追加されます。
結果は、下図のようにします。

図8.1.4-3

Caution
アノテーションの後ろに括弧を持っていないアノテーションに、アノテーション・ビューで属性がただ正しく追加することができません。

以下は、アノテーション・ビューから属性が正しく追加できない例です。
下図のように@Statelessアノテーションの後ろに括弧を持っていません。 
　　この状態で、アノテーション・ビューで、javax.ejb.Statelessアノテーションのdescription属性のValues欄にtest description without kakkoを入力して、ENTER キーを押します。

図8.1.4-4

入力された値は正しくJavaソースの@Statelessアノテーションに反映されません。

図8.1.4-5

Caution
この現象は、括弧を持たないアノテーション記述にエディタで括弧を補うことで回避可能です。

後述の例を除き、アノテーション・ビューを利用してアノテーションを付与する場合は、ほとんどのアノテーションの後ろに自動的に括弧が追加されます。エディタで独自にアノテーションを記述する場合には、括弧まで記述するようご注意ください。
 WebOTX DeveloperのEJB 3.0生成ウィザードで自動的に付与されるアノテーションで、以下の４つには括弧が生成されません。これらのアノテーションを利用する場合、エディタでアノテーションに括弧を追加してください。
 ●　@Stateless
 ●　@Stateful
 ●　@Local
 ●　@Remote

次に、属性の変更処理を示します。

図8.1.4-6

アノテーション・ビューでjavax.ejb.Statelessのdescription属性の値をModified It!に変更して、ENTER キーを押すと、変更結果がエディタに反映されます。

図8.1.4-7

最後に、属性の削除処理を示します。

図8.1.4-8

アノテーション・ビューでjavax.ejb.Statelessのdescription属性の値を空白にして、ENTER キーを押すと、エディタで@Statelessアノテーションのdescription属性が削除されます。

図8.1.4-9

Caution
文字列型、enum型とboolean型の属性は正しく追加・変更することができますが、それ以外、例えば：Class型、配列型、int型などがアノテーション・ビューを使って、正しくエディタに反映できないことがあります。ただし、表示対象（Javaファイル）に設定された属性の値はアノテーション・ビューで正しく表示されます。

8.2.2. アノテーション表示選択・ビューの表示

メニュー ウィンドウ ＞ ビューの表示 ＞ その他...を選択すると、ビューの表示画面が表示されます。
ビューの表示画面で、WebOTX アノテーション ツール ＞ アノテーション表示選択・ビュー を選択して、OK をクリックします。

図8.2.2-1

アノテーション表示選択・ビューが表示されます。

図8.2.2-2

アノテーション表示選択・ビューは、その時点で選択されているプロジェクト（あるいはプロジェクトに所属する要素フォルダ・Javaファイルなど）より、表示内容が異なります。
アノテーション表示選択・ビューは以下のような画面です。

図8.2.2-3

各項目の説明を以下に示します。

表8.2.2-1

項番	項目	説明	備考
(1)	ビューの提示情報	「アノテーションの所属カテゴリを選択してください」というメッセージが表示されます。	プロジェクトはJavaプロジェクトではない、あるいは、プロジェクトがクローズされた場合、「開いているJavaプロジェクトを指定してください。」というメッセージが表示されます。
(2)	EJB3.0 アノテーション チェックボックス	EJB3.0カテゴリに所属するアノテーションをアノテーション・ビューで表示するかどうかを指定します。
(3)	Java EE共通 アノテーション チェックボックス	Java EE共通カテゴリに所属するアノテーションをアノテーション・ビューで表示するかどうかを指定します。
(4)	JPA アノテーション チェックボックス	JPA カテゴリに所属するアノテーションをアノテーション・ビューで表示するかどうかを指定します。
(5)	Portlet アノテーション チェックボックス	Portletカテゴリに所属するアノテーションをアノテーション・ビューで表示するかどうかを指定します。
(6)	Webサービス アノテーション チェックボックス	Webサービスカテゴリに所属するアノテーションをアノテーション・ビューで表示するかどうかを指定します。
(7)	XML アノテーション チェックボックス	XMLカテゴリに所属するアノテーションをアノテーション・ビューで表示するかどうかを指定します。
(8)	アノテーション・バリデーターを有効にするチェックボックス	アノテーションの組み合わせ検証機能を有効にするかしないかを指定します。	ONにする場合、該当プロジェクトにアノテーションの組み合わせ検証を行います。 OFFにする場合、該当プロジェクトにアノテーションの組み合わせ検証を行いません。
(9)	確定ボタン	カテゴリに所属するアノテーション表示・非表示、バリデーターの有効・無効の変更を適用します。	デフォルトで、使用不可です。
(10)	リセットボタン	今回の変更は無視して、前回成功に設定した状態を戻ります。	デフォルトで、使用不可です。

　　　　

Caution
各カテゴリのデフォルト状態（チェックボックスがON・OFF）はプロジェクトの属性により、異なります。

プロジェクトの種類とサポートできるカテゴリの関係を、以下の表で示します。

表8.2.2-2

プロジェクトの種類	アノテーションのカテゴリ	備考
EJB Project	EJB3.0 アノテーション Java EE共通 アノテーション JPA アノテーション Webサービス アノテーション XML アノテーション	1.  EJB ModuleのVersionは3.0でなければなりません。 2.  JPA アノテーションではJava Persistenceモジュールが必要です。
Dynamic Web Project	Java EE共通 アノテーション JPA アノテーション Webサービス アノテーション XML アノテーション	JPA アノテーションではJava Persistenceモジュールが必要です。
JPA Project
Utility Project
Connector Project
Application client Project
Portlet Project	Java EE共通 アノテーション JPA アノテーション Portlet アノテーション Webサービス アノテーション XML アノテーション	1.  JPA アノテーションではJava Persistenceモジュールが必要です。 2.  Portlet モジュールのバージョンはJSR Portlet 2.0以上でなければなりません。
EAR Project		サポートしていません。
ファセットを持っていないJavaプロジェクト	EJB3.0 アノテーション Java EE共通 アノテーション JPA アノテーション Portlet アノテーション Webサービス アノテーション XML アノテーション

　

Caution
全てのカテゴリにおいてJavaモジュールのバージョンは5.0以上でなければなりません。

Caution
Portlet アノテーション はポートレット開発に利用することができますが、それ以外の場合、利用しないでください。

8.2.3. アノテーション表示選択・ビューの使用

アノテーション・ビューに表示できるアノテーションのカテゴリを選択できます。これにより、必要なアノテーションだけをビューに表示でき、目的のアノテーションの探索が容易になります。
カテゴリを選択しない状態での、アノテーション表示選択・ビューとアノテーション・ビューは以下の画面の通りです。

図8.2.3-1

Caution
どのカテゴリも選択されない状態で、アノテーション・ビューにアノテーションが表示される場合、「開発時のトラブルシューティング」の アノテーションエディタをご覧ください。

次に、EJB3.0カテゴリを選択した例で、アノテーションの表示選択を説明します。
アノテーション表示選択・ビューで、EJB3.0 アノテーションをONにして、確定 をクリックします。

図8.2.3-2

エディタで、あるクラスを選択すると、アノテーション・ビューでクラスに付与できるEJB3.0カテゴリに所属するアノテーションが一覧表示されます。

図8.2.3-3

他の五つのカテゴリに所属するアノテーションがアノテーション・ビューで表示されないことを確認してください。

8.2.4. その他表示選択方法

表示選択はEclipseのFacetコンポーネントを利用して、実装しますので、Eclipseプロジェクトのファセット設定より、カテゴリの表示選択も設定できます。
該当機能は、ファセットを持つJavaプロジェクトのみに適用されます。
下記の図では、Webサービス アノテーションがOFFですが、プロジェクトのファセット属性を利用して、Webサービス アノテーション をONにすることで、Webサービスカテゴリに所属するアノテーションがアノテーション・ビューで表示されています。

図8.2.4-1

プロジェクト・エクスプローラーでStatelessSessionSampleプロジェクトを選択します。
右クリックメニュー プロパティーを選択します。

図8.2.4-2

StatelessSessionSampleプロジェクトのプロパティー画面が表示されます。
左側のProject Facets を選択します。

図8.2.4-3

WebOTX アノテーション カテゴリ ＞ Webサービス アノテーション ファセットをONにします。
OKをクリックします。

図8.2.4-4

エディタで、クラス名TestStatelessSessionBeanにカーソルを置いています。
アノテーション・ビューでクラスに付与できるWebサービスカテゴリに所属するアノテーションが一覧表示されます。

図8.2.4-5

アノテーション表示選択・ビューで、Webサービス アノテーション をONにした状態を確認します。
アノテーション・ビューでWebサービスカテゴリに所属するクラスに付与できるアノテーションが全て表示されています。
他のカテゴリに所属するアノテーションは表示されていません。

Caution
1.アノテーション・ビューで表示されないアノテーションも、エディタで付与することは可能です。
2. エディタでアノテーションが正しく付与できない場合、3　アノテーションの検証機能をご覧ください。

8.3. アノテーションの検証

アノテーション検証機能について説明します。

8.3.1. アノテーションの定義位置の検証機能

該当機能は、アノテーション自身のTarget定義によって行う検証です。
各アノテーションのTargetは8.4. サポートするアノテーションを参照してください。
以下の例は、メソッドには付与できない@Statefulアノテーションを、エディタでメソッドに付与した際の、エラー事例です。マウスをエラー発生箇所に置くと、関連するエラーメッセージが表示されます。

図8.3.1-1

8.3.2. アノテーションの属性名の検証機能

Java要素に付与されたアノテーションに不正な属性名を設定した場合のエラーです。
例えば、クラスに付与される@StatefulアノテーションにmappedName2という、存在しない属性を設定すると、検証によりエラーとなります。マウスをエラー発生箇所に置くと、関連するエラーメッセージが表示されます。

図8.3.2-1

8.3.3. アノテーションの属性のタイプの検証機能

Java要素に付与されたアノテーションの属性に不正な型の値を設定した場合、エディタでエラーを提示します。
例えば、クラスに付与される@MessageDrivenアノテーションのactivationConfig属性に、期待する属性型とは異なる文字列型の値を設定すると、エディタでエラーが発生します。また、マウスをエラー発生箇所に置くと、関連するエラーメッセージが表示されます。

図8.3.3-1

8.3.4. 同一アノテーションの属性間の組み合わせの検証機能

同じアノテーションの各属性間に、制約が存在する場合があります。そのような、属性の組み合わせによるエラーの有無を検証することができます。
2 アノテーション表示選択・ビューで説明した手順で、アノテーション表示選択・ビューを開いてください。

図8.3.4-1

アノテーション表示選択・ビューで、アノテーション・バリデーターを有効にするをONにして、確定をクリックします。

図8.3.4-2

下記の画面のように、エディタでエラー箇所を確認できます。

図8.3.4-3

エディタのエラーフラグにマウスを置くと、関連するエラーメッセージが表示されます。

図8.3.4-4

ユーザが検証機能を利用したくない場合は、以下の手順で、検証機能を無効化できます。
アノテーション表示選択・ビューを表示します。

図8.3.4-5

アノテーション表示選択・ビューで、アノテーション・バリデーターを有効にするをOFFにして、 確定をクリックします。

図8.3.4-6

エディタでエラーが表示されなくなります。

図8.3.4-7

8.3.5. 異なるアノテーション間の組み合わせの検証機能

同じクラスに付与されるアノテーション間に、制約が存在する場合があります。そのような、アノテーションの組み合わせによるエラーの有無を検証することができます。
また、ユーザが検証機能を使用したくない場合、該当検証機能を無効化することもできます。
検証機能の有効・無効化については8.3.5. 異なるアノテーション間の組み合わせの検証機能を参照してください。
クラスTestAnnotationValidatorに同時に@Statelessと@Statefulと言う、相反するアノテーションを付与します。
TestAnnotationValidator.javaを保存します。
下図のように、エディタでエラー箇所が表示されます。

図8.3.5-1

エディタのエラー箇所にマウスを置くと、関連するエラーメッセージが表示されます。

図8.3.5-2

Caution
1.アノテーション表示選択・ビューで、アノテーション・バリデーターを有効にする をONにすると、組み合わせ検証が有効になります。ただし文法検証は、関係しません。

2.該当バージョンで、EJB 3.0アノテーション、JavaEE共通アノテーションとWebサービスアノテーションに関する検証ルールのみ提供されます。JPAアノテーションとXMLアノテーションに関する検証ルールが提供されません。

8.4. サポートするアノテーション

8.4.1. Java EE共通 アノテーション

Java EE共通カテゴリに所属するアノテーションは以下の通りです。

表8.4.1-1

項番	パッケージ名	アノテーション名	Target
1	javax.annotation	Generated	[ALL]
2	javax.annotation	PostConstruct	[M]
3	javax.annotation	PreDestroy	[M]
4	javax.annotation	Resource	[F, M, T]
5	javax.annotation	Resources	[T]
6	javax.annotation.security	DeclareRoles	[T]
7	javax.annotation.security	DenyAll	[M]
8	javax.annotation.security	PermitAll	[M, T]
9	javax.annotation.security	RolesAllowed	[M, T]
10	javax.annotation.security	RunAs	[T]
11	javax.ejb	EJB	[F, M, T]
12	javax.ejb	EJBs	[T]
13	javax.persistence	PersistenceContext	[F, M, T]
14	javax.persistence	PersistenceContexts	[T]
15	javax.persistence	PersistenceUnit	[F, M, T]
16	javax.persistence	PersistenceUnits	[T]
17	javax.xml.ws	WebServiceRef	[F, M, T]
18	javax.xml.ws	WebServiceRefs	[T]

Caution
EJB（ｓ）、PersistenceContext（s）、PersistenceUnit（s）とWebServiceRef（s）の8つのアノテーションが他のパッケージからJava EE共通カテゴリに移動します。

8.4.2. XMLアノテーション

XML カテゴリに所属するアノテーションは以下の通りです。

表8.4.2-1

項番	パッケージ名	アノテーション名	Target
1	javax.xml.bind.annotation	XmlAccessorOrder	[Pkg, T]
2	javax.xml.bind.annotation	XmlAccessorType	[Pkg, T]
3	javax.xml.bind.annotation	XmlAnyAttribute	[F, M]
4	javax.xml.bind.annotation	XmlAnyElement	[F, M]
5	javax.xml.bind.annotation	XmlAttachmentRef	[F, M, Par]
6	javax.xml.bind.annotation	XmlAttribute	[F, M]
7	javax.xml.bind.annotation	XmlElement	[F, M]
8	javax.xml.bind.annotation	XmlElementDecl	[M]
9	javax.xml.bind.annotation	XmlElementRef	[F, M]
10	javax.xml.bind.annotation	XmlElementRefs	[F, M]
11	javax.xml.bind.annotation	XmlElements	[F, M]
12	javax.xml.bind.annotation	XmlElementWrapper	[F, M]
13	javax.xml.bind.annotation	XmlEnum	[T]
14	javax.xml.bind.annotation	XmlEnumValue	[F]
15	javax.xml.bind.annotation	XmlID	[F, M]
16	javax.xml.bind.annotation	XmlIDREF	[F, M]
17	javax.xml.bind.annotation	XmlInlineBinaryData	[F, M, T]
18	javax.xml.bind.annotation	XmlList	[F, M, Par]
19	javax.xml.bind.annotation	XmlMimeType	[F, M, Par]
20	javax.xml.bind.annotation	XmlMixed	[F, M]
21	javax.xml.bind.annotation	XmlNs	[]
22	javax.xml.bind.annotation	XmlRegistry	[T]
23	javax.xml.bind.annotation	XmlRootElement	[T]
24	javax.xml.bind.annotation	XmlSchema	[Pkg]
25	javax.xml.bind.annotation	XmlSchemaType	[F, M, Pkg]
26	javax.xml.bind.annotation	XmlSchemaTypes	[Pkg]
27	javax.xml.bind.annotation	XmlTransient	[F, M]
28	javax.xml.bind.annotation	XmlType	[T]
29	javax.xml.bind.annotation	XmlValue	[F, M]
30	javax.xml.bind.annotation.adapters	XmlJavaTypeAdapter	[F, M, Pkg, Par, T]
31	javax.xml.bind.annotation.adapters	XmlJavaTypeAdapters	[Pkg]

!ENTRY org.eclipse.wst.common.project.facet.core 4 0 2011-xx-xx HH:MM:SS
!MESSAGE Project facet webotx.portlet has not been defined. It is used in plugin com.nec.webotx.annotation.

@TransactionManagement(TransactionManagementType.BEAN)

@TransactionManagement(value = TransactionManagementType.BEAN)