Seam オブジェクトがどのように動作するかを見るために、 簡単なサンプルを通じて一歩を踏み出してみましょう。 まず最初に、helloAction と呼ばれる新しい Seam コンポーネントを作成しましょう。

          
  @Stateless
  @Name("helloAction")
  public class HelloAction implements HelloLocal {
    public String sayHello(String name) {
      return "Hello, " + name;
    }
  }
          
        

新しいコンポーネントのために、ローカルインタフェースも生成する必要があります。 @WebRemote アノテーションに特に注意してください。 Remoting を通じてのメソッドへのアクセスを可能とするために必要です。

          
  @Local
  public interface HelloLocal {
    @WebRemote
    public String sayHello(String name);
  }
          
        

書く必要があるサーバサイドのコードはこれだけです。 それでは、WEB ページのために - 新しいページを作成して、 以下のスクリプトをインポートしましょう。

          
  <script type="text/javascript" src="seam/resource/remoting/resource/remote.js"></script>
  <script type="text/javascript" src="seam/resource/remoting/interface.js?helloAction"></script>
          
        

完全にインタラクティブなユーザエクスペリエンスとするために、ページにボタンを付けましょう。

          
  <button onclick="javascript:sayHello()">Say Hello</button>
          
        

クリックされたとき、実際にボタンに何かを行わせるためには、もう少しスクリプトを追加する必要があります。

          
  <script type="text/javascript">
    //<![CDATA[

    function sayHello() {
      var name = prompt("What is your name?");
      Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);
    }

    function sayHelloCallback(result) {
      alert(result);
    }

    // ]]>
  </script>
          
        

作業完了です! アプリケーションをデプロイして、ページをブラウズしましょう。 ボタンをクリックして、プロンプトが出たら名前を入力しましょう。 呼び出しの成功を確認するための hello メッセージが、メッセージボックスに表示されます。 少し時間を節約したいのであれば、 Seam の /examples/remoting/helloworld ディレクトリにこの Hello World サンプルのすべてのソースコードがあります。

ところで、このスクリプトのコードは何をするのでしょうか。 もっと細かく分解してみましょう。手始めに、2 つのメソッドを実装した Javascript コードから見ていきましょう。 最初のメソッドはユーザに対して名前を入力するよう促し、リモートリクエストを行うという責務を持ちます。 以下の行から見てみましょう。

  Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);
        

この行の最初の部分 Seam.Component.getInstance("helloAction") は、 helloAction コンポーネントのプロキシ、あるいは"スタブ"を返します。 このスタブに対してコンポーネントのメソッド呼び出しが可能です。 それは、まさにこの行の残りの部分で発生します: sayHello(name, sayHelloCallback);

コード行全体で行っていることは、コンポーネントのsayHelloメソッドの呼び出しと、 パラメータとしてnameを渡すことです。 2 番目のパラメータsayHelloCallbackは、 このコンポーネントの sayHelloメソッドのパラメータではありません。 その代わり、Seam Remoting フレームワークにリクエストへのレスポンスを受けたら、 それを sayHelloCallbackメソッドに渡すべきことを指示します。 このコールバックパラメータは完全にオプションです。 返り値 void のメソッドを呼び出す場合、 あるいは結果を気にしない場合は、 遠慮なくそのままにしてください。

sayHelloCallbackメソッドが、リモートリクエストに対するレスポンスを受信した場合、 メソッド呼び出しの結果を表示するアラートメッセージが現れます。

Seam.Component Javascript オブジェクトは、 Seam コンポーネントと連携する多くのクライアントメソッドを提供します。 主な 2 つのメソッド、newInstance()と getInstance()は、 以降の章にも記述されていますが、 これらの主な違いは、newInstance() は、いつもコンポーネントタイプの新しいインスタンスを生成し、そして、getInstance()は、シングルトンのインスタンスを返すことです。

  @Name("customer")
  @Entity
  public class Customer implements Serializable
  {
    private Integer customerId;
    private String firstName;
    private String lastName;
    
    @Column public Integer getCustomerId() { 
      return customerId; 
    }
    
    public void setCustomerId(Integer customerId} { 
      this.customerId = customerId; 
    }
    
    @Column public String getFirstName() { 
      return firstName; 
    }
    
    public void setFirstName(String firstName) {
      this.firstName = firstName; 
    }
    
    @Column public String getLastName () {
      return lastName;
    }
    
    public void setLastName(String lastName) {
      this.lastName = lastName;
    }
  }
          

  var customer = Seam.Component.newInstance("customer");
          

  customer.setFirstName("John");
  // Or you can set the fields directly
  customer.lastName = "Smith";
          

  Seam.Component.getInstance("customerAction").saveCustomer(customer);          
          

  if (Seam.Component.getComponentName (instance) == "customer")
    alert("Customer");
  else if (Seam.Component.getComponentName (instance) == "staff")
    alert("Staff member");          
          

Seam Remoting の大部分のクライアントサイドの機能は、Seam.Remotingオブジェクトに含まれます。 メソッドを直接呼ぶ必要はほとんどないとはいえ、 言及する価値のある重要なものがあります。

  var widget = Seam.Remoting.createType("com.acme.widgets.MyWidget");          
          

この章は、基本データタイプのサポートについて述べています。 サーバサイドではこれらの値は、一般的にプリミティブタイプ、あるいは、対応するラッパクラスと互換性があります。

一般的に、これらは、Seam エンティティ、JavaBean コンポーネント、または、non-component クラスです。 オブジェクトの新しいインスタンスを生成するためには、適切なメソッドを使用してください。 Seam コンポーネントにはSeam.Component.newInstance()、 また、その他のものにはSeam.Remoting.createType()を使用してください。

パラメータが、このセクションの別の場所で記述されたその他の有効なタイプの 1 つではない場合、 これら 2 つのメソッドのどちらかによって生成されるオブジェクトだけがパラメータ値として使用されるべきであることに気づくことは重要です。 いくつかの状況では、 以下のように厳密にパラメータタイプを決定できないコンポーネントメソッドがあるかもしれません。

  @Name("myAction")
  public class MyAction implements MyActionLocal {
    public void doSomethingWithObject(Object obj) {
      // code
    }
  }
        

この場合、 myWidget コンポーネントのインスタンスを渡したいところですが、 myAction のインターフェースはそのいずれのメソッドからも直接参照されないため myWidget を含みません。 これを回避するには、 MyWidget を明示的にインポートする必要があります。

                  
  <script type="text/javascript" src="seam/resource/remoting/interface.js?myAction&myWidget"></script>
          
        

これにより myWidget オブジェクトが Seam.Component.newInstance("myWidget") で作成されるようになり、 これが myAction.doSomethingWithObject() に渡されます。

日付の値は、 ミリ秒単位まで正確な String 表示に連続化されます。 クライアント側では Javascript Date オブジェクトを使って日付値と動作させます。 サーバー側では java.util.Date を使用します (または java.sql.Date や java.sql.Timestamp などの下位クラス)。

クライアント側では、 enums は Strings と同様に扱われます。 enums パラメータの値を設定する場合は単純に enum の String 表現を使います。 次のコンポーネントを例として参照してください。

  @Name("paintAction")
  public class paintAction implements paintLocal {
    public enum Color {red, green, blue, yellow, orange, purple};

    public void paint(Color color) {
      // code
    }    
  }            
        

paint() メソッドを red の色を使って呼び出すには、 String のままでパラメータ値を渡します。

  Seam.Component.getInstance("paintAction").paint("red");
        

逆も真になります。 つまり、 コンポーネントメソッドが enum パラメータを返す場合 (または返されるオブジェクトグラフのどこかに enum フィールドを含む場合)、 クライアント側では String として表示されます。

デフォルトの "Please Wait..." というメッセージを別のメッセージに変更するには、 Seam.Remoting.loadingMessage の値を設定します。

  Seam.Remoting.loadingMessage = "Loading...";        
        

ローディングメッセージを完全に表示させないようにするには、 displayLoadingMessage() および hideLoadingMessage() を何も行わない機能で上書きします。

  // don't display the loading indicator
  Seam.Remoting.displayLoadingMessage = function() {};
  Seam.Remoting.hideLoadingMessage = function() {};        
        

ローディングインジケーターを上書きしてアニメのアイコンの他、 好きなものを表示させることができます。 displayLoadingMessage() と hideLoadingMessage() の各メッセージを独自の実装で上書きしてこれを行います。

  Seam.Remoting.displayLoadingMessage = function() {
    // Write code here to display the indicator
  };
  
  Seam.Remoting.hideLoadingMessage = function() {
    // Write code here to hide the indicator
  };
        

リモートメソッドが Widget のインスタンスを返すけれど secret フィールドには機密情報が含まれているため公表したくない場合、 次のように制約します。

  @WebRemote(exclude = {"secret"})
  public Widget getWidget();      
        

"secret" の値は返されるオブジェクトの secret フィールドを参照します。 ここで、 クライアントに対してこの特定フィールドが公開されても構わないと仮定します。 返される Widget には child フィールドがあり、 これも Widget になります。 代わりに child の secret 値を隠したい場合はどうしたらよいでしょうか。 ドット表記を使用して結果となるオブジェクトグラフ内のこのフィールドのパスを指定することができます。

  @WebRemote(exclude = {"child.secret"})
  public Widget getWidget();      
        

オブジェクトグラフ内にオブジェクトが存在できるその他の場所は Map あるいはなんらかの集合の種類内になります (List、 Set、 Array など)。 集合は簡単で、 その他のフィールドと同様に扱えます。 たとえば、 Widget の widgetList フィールド内に他の Widget 一覧が含まれていて、 この一覧の Widget の secret フィールドを制約している場合、 アノテーションは次のようになります。

  @WebRemote(exclude = {"widgetList.secret"})
  public Widget getWidget();      
        

Map のキーまたは値を制約する場合の表記は少し異なります。 Map のフィールド名の後ろに [key] を付け加えると Map のキーオブジェクト値を制約し、 [value] は値オブジェクトの値を制約します。 次の例では widgetMap フィールドに制約された secret フィールドを持たせる方法を示しています。

  @WebRemote(exclude = {"widgetMap[value].secret"})
  public Widget getWidget();      
        

最後に、結果となるオブジェクトグラフ内のどこに出現するかに関係なくオブジェクトタイプのフィールド制約に使用できる表記について説明します。 この表記はコンポーネント名 (オブジェクトが Seam コンポーネントである場合) または完全修飾クラス名 (オブジェクトが Seam コンポーネントではない場合のみ) のいずれかを使用し角括弧を使って表現されます。

  @WebRemote(exclude = {"[widget].secret"})
  public Widget getWidget();      
        

制約同士はオブジェクトグラフ内で複数のパスからオブジェクトをフィルタするために組み合わせることもできます。

  @WebRemote(exclude = {"widgetList.secret", "widgetMap[value].secret"})
  public Widget getWidget();      
        

JMS トピックをサブスクライブする前に、 まず Seam Remoting でサブスクライブさせることができるトピック一覧を設定する必要があります。 seam.properties、 web.xml または components.xml の org.jboss.seam.remoting.messaging.subscriptionRegistry.allowedTopics 配下にあるトピックを一覧表示させます。

<remoting:remoting poll-timeout="5" poll-interval="1"/>

次の例では JMS Topic へのサブスクライブ方法を示しています。

  function subscriptionCallback(message)
  {
    if (message instanceof Seam.Remoting.TextMessage)
      alert("Received message: " + message.getText ());
  }        
        
  Seam.Remoting.subscribe("topicName", subscriptionCallback);
        

Seam.Remoting.subscribe() メソッドは 2 つのパラメータを受け取ります。 1 つ目はサブスクライブする JMS Topic 名になり、 2 つ目はメッセージが受け取られると呼び出すコールバック機能になります。

サポートされているメッセージは 2 種類で、 テキストメッセージとオブジェクトメッセージです。 コールバック機能に渡されるメッセージタイプのテストを必要とする場合は、 instanceof 演算子を使ってメッセージが Seam.Remoting.TextMessage なのか Seam.Remoting.ObjectMessage であるのかをテストすることができます。 TextMessage はその text フィールドにテキスト値を含み (または代わりに getText() を呼び出す)、 ObjectMessage はその object フィールドにオブジェクト値を含みます (またはその getObject() メソッドを呼び出す)。

トピックのサブスクライブを中止するには、 Seam.Remoting.unsubscribe() を呼び出してトピック名で渡します。

  Seam.Remoting.unsubscribe("topicName");        
        

ポーリングの発生方法を制御するために変更できるパラメータが 2 つあります。 1 つ目は Seam.Remoting.pollInterval で、 新しいメッセージに対して後続ポールが発生する間隔を制御します。 秒単位で表現します、 デフォルト設定は 10 になります。

2 つ目のパラメータは Seam.Remoting.pollTimeout で、 このパラメータも秒単位で表現されます。 サーバーへのリクエストがタイムアウトして空白の応答を送信するまでの新しいメッセージを待機する長さを制御します。 デフォルトは 0秒で、 サーバーがポールされると配信できるメッセージがない場合は空白の応答が直ちに返されます。

pollTimeout 値を高く設定する場合は注意が必要です。 各リクエストがメッセージを待機する必要があるということは、 メッセージが受信されるまでまたはそのリクエストがタイムアウトするまでサーバースレッドが固定されるということになります。 こうしたリクエストが同時に多数発生すると、 大量のスレッドが固定される結果になります。

これらのオプションは components.xml 経由で設定することを推奨しますが、 必要に応じて Javascript で上書きすることができます。 次の例ではポーリングがかなりアグレッシブに発生するよう設定する方法を示しています。 これらのパラメータはご使用のアプリケーションに適切な値を設定してください。

components.xml:

<remoting:remoting poll-timeout="5" poll-interval="1"/>

JavaScript:

  // Only wait 1 second between receiving a poll response and sending the next poll request.
  Seam.Remoting.pollInterval = 1;
  
  // Wait up to 5 seconds on the server for new messages
  Seam.Remoting.pollTimeout = 5;