コントロールの作成とビルド
それでは、実際にサンプルアプリケーションに含まれているソースを見ながら作成方法を解説します。中身は非常に簡単なファイルI/Oを行うコントロールと、コントロールを利用するクライアントであるサーブレットで構成されています。以下にサンプルアプリケーションの基本的なファイル構成を表にしました。
ファイル名 | 概要 |
SampleCtrlFile | コントロールパブリックインターフェイス |
SampleCtrlFileImpl | コントロール実装クラス |
SampleCtrlFileBean | コントロールBeanクラス |
SampleServlet | コントロールクライアント(サーブレット) |
コントロール実装クラスは、基本的にコントロールパブリックインターフェイスに「Impl」という名前を付けたクラス名にする必要があります。
新しいコントロールタイプを作成する
まず、SampleCtrlFile
とSampleCtrlFileImpl
の2クラスを作成する必要があります。
コントロールパブリックインターフェイスは、org.apache.beehive.controls.api.bean.ControlInterfaceアノテーションをインターフェイス宣言に付ける必要があります。これにより、このインターフェイスが、コントロールパブリックインターフェイスであることを意味付けします。
@ControlInterface public interface SampleCtrlFile { ・・・ }
コントロール実装クラスは、コントロールパブリックインターフェイスを実装したクラスとして作成し、このクラスにはorg.apache.beehive.controls.api.bean.ControlImplementationのアノテーションを付けます。これにより、このクラスがコントロール実装クラスであることを意味付けします。
@ControlImplementation(isTransient=true) public class SampleCtrlFileImpl implements SampleCtrlFile { ・・・ }
isTransient
は、コントロール実装クラスをシリアライズするかどうかを表すものです。これはtrueにしておきます。
これで、コントロールの雛形ができました。次にこれらに実装を加えていきます。
操作
操作とは、クライアントの要求に応えてコントロールが実行するアクションのことをいいます。このサンプルアプリケーションでは、ファイルを書き出す、ファイルを読み込むという2つの操作を実装しています。まず次のようにコントロールパブリックインターフェイスに操作の抽象メソッドを定義します。
//read file public String read() throws Exception; //write file public void write(String str) throws Exception;
さらに、コントロール実装クラスに対して、抽象メソッドをオーバーライドしたものを記述します。
//read file public String read()throws Exception { *** ファイルから読み込むコード(省略) *** } //write file public void write(String str)throws Exception { *** ファイルに書き込むコード(省略) *** }
イベント
イベントとは、一定の条件が一致したり、内部イベントが発生した場合に、コントロールからクライアントへ通知されるアクションのことをいいます。クライアントでは、イベントを受け取り、それに従って適切な処理を行うことができます。サンプルアプリケーションでは、ファイルの書き込みが終了したタイミングでログ出力のイベント実行を行っています。コントロールパブリックインターフェイスでは、org.apache.beehive.controls.api.events.EventSetアノテーションをつけた内部インターフェイスとしてイベントを定義します。ここではCallback
という名前の内部インターフェイスの中に、onWrite
というイベントを1つ定義しています。複数のイベントを定義したい場合には、ここに複数記述します。
@EventSet public interface Callback { void onWrite(String str); }
コントロール実装クラスでは、org.apache.beehive.controls.api.events.Clientアノテーションをつけた先ほどの内部インターフェイスCallback
をインスタンス変数として定義します。このインスタンス変数は、必要なタイミングで自動的に初期化されます。そして、適切な箇所でイベントを呼び出す記述を入れておきます。ここではwrite
メソッドの最後に入れています。これにより、write
メソッドの最後でクライアントに特定の処理を行わせることができます。
//イベント @Client Callback client; ・・・ client.onWrite("onWrite");
プロパティ
プロパティとは、クライアントから渡されるパラメータのことをいいます。プロパティの実際の値は、基本的にコントロールのクライアントのクラスにアノテーションとして記述します。そのため、そのアノテーションのクラスを定義しておく必要があります。サンプルアプリケーションでは、ファイルI/Oのファイルパスとファイル名をクライアントからプロパティとして受け取るように実装してあります。コントロールパブリックインターフェイスでは、org.apache.beehive.controls.api.properties.PropertySetアノテーションとjava.lang.annotation.RetentionアノテーションをつけたFileInfoというアノテーションを定義して、2つのプロパティをそのアノテーション内に定義しています。
@PropertySet @Retention(RetentionPolicy.RUNTIME) public @interface FileInfo{ public String filePath(); public String fileName(); }
PropertySetアノテーションは、アノテーションしたものをコントロールのプロパティとして認識するためのものです。また、Retentionアノテーションは、JDK標準のAPIで、注釈されたものの生存期間を表しています。生存期間を表現するための定数がRetentionPolicy
に3種類定義されているので、それを以下の表にまとめました。
種類名 | 概要 |
SOURCE | ソースファイルにのみ存在。クラスファイルの時点では存在しない。 |
CLASS | クラスファイルの時点でも存在。JavaVMに読み込まれた後は存在しない。 |
RUNTIME | JavaVMに読み込まれた後(実行時)も存在する。 |
サンプルアプリケーションでは、プロパティが実行時にも参照されるためRUNTIME
と指定しています。
コンテキスト
コンテキストとはコントロール内外のさまざまなプロパティ、サービスにアクセスするためのものです。ここでは、コントロール実装クラスでクライアントから渡されたプロパティを参照するのに利用しています。コンテキストを利用するには、必要なコンテキスト(ここでは、org.apache.beehive.controls.api.context.ControlBeanContext)を宣言し、それに対してorg.apache.beehive.controls.api.context.Contextアノテーションを付けます。これにより、自動的にコンテキストは初期化されます。次のように記述します。
@Context ControlBeanContext context;
次に、コンテキストからプロパティを取得するには次のような構文を使用します。
//コンテキストからクライアントで指定したプロパティを取得して処理
SampleCtrlFile.FileInfo fileInfo =
context.getControlPropertySet(SampleCtrlFile.FileInfo.class);
コンテキストライフサイクルイベント
コンテキストライフサイクルイベントとは、コントロールの初期化~終了などのライフサイクルに基づいて、定義されたイベントです。コンテキストライフサイクルイベントを以下の表にまとめました。
イベント名 | イベントのタイミング |
onCreate | コントロール初期化時 |
onPropertyChange | Bound Property(束縛特性)が変更された時 |
onVetoableChange | Constrained Property(制約付き特性)が変更された時 |
サンプルアプリケーションでは、onCreate
イベントを利用して、コントロールの初期化時にプロパティで定義されたファイルからファイルを生成するという処理を行っています。コンテキストライフサイクルイベントはコントロール実装クラスにのみ記述します。org.apache.beehive.controls.api.events.EventHandlerアノテーションに必要なプロパティを付けて、ライフサイクルイベントの対象のメソッドに付けます。EventHandlerアノテーションに必要なプロパティとその概要を表にしました。
プロパティ名 | 概要 |
field | コンテキストのフィールド名 |
eventName | コンテキストライフサイクルイベント名 |
eventSet | org.apache.beehive.controls.api.context.ControlBeanContext.LifeCycle.class(ライフサイクルイベント固定) |
次のように実装します。
@EventHandler(field="context",eventName="onCreate",eventSet=ControlBeanContext.LifeCycle.class) public void onCreate(){ ctgry.info("+++onCreate+++"); //コンテキストからクライアントで指定したプロパティを取得して処理 SampleCtrlFile.FileInfo fileInfo = context.getControlPropertySet(SampleCtrlFile.FileInfo.class); filePath = fileInfo.filePath(); new File(filePath).mkdirs();//ディレクトリ作成 fileName = fileInfo.fileName(); try { //ファイルが無ければ空ファイル生成 new File(filePath + "\\" +fileName).createNewFile(); } catch (IOException e) { e.printStackTrace(); } ctgry.info("filePath="+filePath+",fileName="+fileName); } @EventHandler(field="context",eventName="onPropertyChange",
eventSet=ControlBeanContext.LifeCycle.class) public void onPropertyChange(PropertyChangeEvent pce){ ctgry.info("+++onPropertyChange+++"); } @EventHandler(field="context",eventName="onVetoableChange",
eventSet=ControlBeanContext.LifeCycle.class) public void onVetoableChange(PropertyChangeEvent pce){ ctgry.info("+++onVetoableChange+++"); }
Antによりbuild
Antでbuildを行うことにより、これまで作成してきたパブリックインターフェイスとコントロール実装クラスからコントロールBeanクラスが生成されます。解凍したサンプルから次のように実行してください。
>cd BeehiveConrolSample\samples\controls-sample >ant clean build
これにより、コントロールBeanクラスなど必要なクラスが生成されます。