Apache Beehiveの開発を体験する（コントロール作成編）

Apache Beehiveによるコントロールの作成と利用

コントロールの作成とビルド

　それでは、実際にサンプルアプリケーションに含まれているソースを見ながら作成方法を解説します。中身は非常に簡単なファイルI/Oを行うコントロールと、コントロールを利用するクライアントであるサーブレットで構成されています。以下にサンプルアプリケーションの基本的なファイル構成を表にしました。

サンプルアプリケーションのファイル構成

ファイル名	概要
SampleCtrlFile	コントロールパブリックインターフェイス
SampleCtrlFileImpl	コントロール実装クラス
SampleCtrlFileBean	コントロールBeanクラス
SampleServlet	コントロールクライアント（サーブレット）

　コントロール実装クラスは、基本的にコントロールパブリックインターフェイスに「Impl」という名前を付けたクラス名にする必要があります。

新しいコントロールタイプを作成する

　まず、SampleCtrlFileとSampleCtrlFileImplの2クラスを作成する必要があります。

　コントロールパブリックインターフェイスは、org.apache.beehive.controls.api.bean.ControlInterfaceアノテーションをインターフェイス宣言に付ける必要があります。これにより、このインターフェイスが、コントロールパブリックインターフェイスであることを意味付けします。

「SampleCtrlFile.java」のソース一部

@ControlInterface
public interface SampleCtrlFile {
・・・
}

　コントロール実装クラスは、コントロールパブリックインターフェイスを実装したクラスとして作成し、このクラスにはorg.apache.beehive.controls.api.bean.ControlImplementationのアノテーションを付けます。これにより、このクラスがコントロール実装クラスであることを意味付けします。

「SampleCtrlFileImpl.java」のソース一部

@ControlImplementation(isTransient=true)
public class SampleCtrlFileImpl implements SampleCtrlFile {
・・・
}

　isTransientは、コントロール実装クラスをシリアライズするかどうかを表すものです。これはtrueにしておきます。

　これで、コントロールの雛形ができました。次にこれらに実装を加えていきます。

操作

　操作とは、クライアントの要求に応えてコントロールが実行するアクションのことをいいます。このサンプルアプリケーションでは、ファイルを書き出す、ファイルを読み込むという2つの操作を実装しています。まず次のようにコントロールパブリックインターフェイスに操作の抽象メソッドを定義します。

「SampleCtrlFile.java」のソース一部

//read file
public String read() throws Exception;

//write file
public void write(String str) throws Exception;

　さらに、コントロール実装クラスに対して、抽象メソッドをオーバーライドしたものを記述します。

「SampleCtrlFileImpl.java」のソース一部

//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つ定義しています。複数のイベントを定義したい場合には、ここに複数記述します。

「SampleCtrlFile.java」のソース一部

@EventSet
public interface Callback
{
    void onWrite(String str);
}

　コントロール実装クラスでは、org.apache.beehive.controls.api.events.Clientアノテーションをつけた先ほどの内部インターフェイスCallbackをインスタンス変数として定義します。このインスタンス変数は、必要なタイミングで自動的に初期化されます。そして、適切な箇所でイベントを呼び出す記述を入れておきます。ここではwriteメソッドの最後に入れています。これにより、writeメソッドの最後でクライアントに特定の処理を行わせることができます。

「SampleCtrlFileImpl.java」のソース一部

//イベント
@Client Callback client;

・・・

client.onWrite("onWrite");

プロパティ

　プロパティとは、クライアントから渡されるパラメータのことをいいます。プロパティの実際の値は、基本的にコントロールのクライアントのクラスにアノテーションとして記述します。そのため、そのアノテーションのクラスを定義しておく必要があります。サンプルアプリケーションでは、ファイルI/Oのファイルパスとファイル名をクライアントからプロパティとして受け取るように実装してあります。コントロールパブリックインターフェイスでは、org.apache.beehive.controls.api.properties.PropertySetアノテーションとjava.lang.annotation.RetentionアノテーションをつけたFileInfoというアノテーションを定義して、2つのプロパティをそのアノテーション内に定義しています。

「SampleCtrlFile.java」のソース一部

@PropertySet
@Retention(RetentionPolicy.RUNTIME)
public @interface FileInfo{
    public String filePath();
    public String fileName();
}

　PropertySetアノテーションは、アノテーションしたものをコントロールのプロパティとして認識するためのものです。また、Retentionアノテーションは、JDK標準のAPIで、注釈されたものの生存期間を表しています。生存期間を表現するための定数がRetentionPolicyに3種類定義されているので、それを以下の表にまとめました。

Retentionアノテーションの生存期間の種類

種類名	概要
SOURCE	ソースファイルにのみ存在。クラスファイルの時点では存在しない。
CLASS	クラスファイルの時点でも存在。JavaVMに読み込まれた後は存在しない。
RUNTIME	JavaVMに読み込まれた後（実行時）も存在する。

　サンプルアプリケーションでは、プロパティが実行時にも参照されるためRUNTIMEと指定しています。

コンテキスト

　コンテキストとはコントロール内外のさまざまなプロパティ、サービスにアクセスするためのものです。ここでは、コントロール実装クラスでクライアントから渡されたプロパティを参照するのに利用しています。コンテキストを利用するには、必要なコンテキスト（ここでは、org.apache.beehive.controls.api.context.ControlBeanContext）を宣言し、それに対してorg.apache.beehive.controls.api.context.Contextアノテーションを付けます。これにより、自動的にコンテキストは初期化されます。次のように記述します。

「SampleCtrlFileImpl.java」のソース一部

@Context ControlBeanContext context;

　次に、コンテキストからプロパティを取得するには次のような構文を使用します。

「SampleCtrlFileImpl.java」のソース一部

//コンテキストからクライアントで指定したプロパティを取得して処理
SampleCtrlFile.FileInfo fileInfo =
    context.getControlPropertySet(SampleCtrlFile.FileInfo.class);

コンテキストライフサイクルイベント

　コンテキストライフサイクルイベントとは、コントロールの初期化～終了などのライフサイクルに基づいて、定義されたイベントです。コンテキストライフサイクルイベントを以下の表にまとめました。

コンテキストライフサイクルイベントの種類

イベント名	イベントのタイミング
onCreate	コントロール初期化時
onPropertyChange	Bound Property（束縛特性）が変更された時
onVetoableChange	Constrained Property（制約付き特性）が変更された時

　サンプルアプリケーションでは、onCreateイベントを利用して、コントロールの初期化時にプロパティで定義されたファイルからファイルを生成するという処理を行っています。コンテキストライフサイクルイベントはコントロール実装クラスにのみ記述します。org.apache.beehive.controls.api.events.EventHandlerアノテーションに必要なプロパティを付けて、ライフサイクルイベントの対象のメソッドに付けます。EventHandlerアノテーションに必要なプロパティとその概要を表にしました。

EventHandlerアノテーションのプロパティ

プロパティ名	概要
field	コンテキストのフィールド名
eventName	コンテキストライフサイクルイベント名
eventSet	org.apache.beehive.controls.api.context.ControlBeanContext.LifeCycle.class（ライフサイクルイベント固定）

　次のように実装します。

「SampleCtrlFileImpl.java」のソース一部

@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クラスなど必要なクラスが生成されます。