Seam - コンテキスト依存コンポーネント

このチュートリアルでは、 JBoss AS 4.0.5 がダウンロードされ、 EJB 3.0 プロファイルがインストールされたものとして話を進めます。 (JBoss AS インストールを使用して) また、Seam のコピーもダウンロードして、 作業ディレクトリに展開されているものとします。

各 Seam サンプルのディレクトリーは、以下の要領で構成されています。

ユーザ登録サンプルは、データベースに新規ユーザのユーザ名、 実名、 パスワードをデータベースに保存できる簡単なアプリケーションです。 このサンプルは Seam の高度な機能の全てを見せることはできませんが、 JSF アクションリスナとして EJB3 セッション Bean を使用する方法や、 基本的な Seam の設定方法を見せてくれます。

EJB 3.0 にまだ不慣れな方もいらっしゃるかもしれませんので、 ゆっくり進めていきます。

最初のページは 3 つの入力フィールドを持つ基本的なフォームを表示します。 試しに、項目を入力してフォームをサブミットしてください。 これでユーザオブジェクトはデータベースに保存されます。

1.2.1. コードの理解

このサンプルは、2 つの JSP ページ、1 つのエンティティ Bean と、1 つのステートレスセッション Bean で実装されています。

基本から始めるために、コードを見てみましょう。

1.2.1.1. エンティティ Bean: User.java

ユーザデータに EJB エンティティ Beanが必要です。 このクラスでは、 アノテーションによって 永続性 と データ妥当性検証 を宣言的に定義しています。 Seam コンポーネントとしてのクラスを定義するために、別にいくつかのアノテーションも必要です。

例 1.1.

@Entity                                                                                  (1)
@Name("user")                                                                            (2)
@Scope(SESSION)                                                                          (3)
@Table(name="users")                                                                     (4)
public class User implements Serializable
{
   private static final long serialVersionUID = 1881413500711441951L;
   
   private String username;                                                              (5)
   private String password;
   private String name;
   
   public User(String name, String password, String username)
   {
      this.name = name;
      this.password = password;
      this.username = username;
   }
   
   public User() {}                                                                      (6)
   
   @NotNull @Length(min=5, max=15)                                                       (7)
   public String getPassword()
   {
      return password;
   }

   public void setPassword(String password)
   {
      this.password = password;
   }
   
   @NotNull
   public String getName()
   {
      return name;
   }

   public void setName(String name)
   {
      this.name = name;
   }
   
   @Id @NotNull @Length(min=5, max=15)                                                   (8)
   public String getUsername()
   {
      return username;
   }

   public void setUsername(String username)
   {
      this.username = username;
   }

}

(1)	EJB3 標準 @Entity アノテーションは、 User クラスがエンティティ Bean であることを示しています。
(2)	Seam コンポーネントは、 @Name アノテーションで指定される コンポーネント名 が必要です。 この名前は Seam アプリケーション中でユニークである必要があります。 JSF が Seam に Seam コンポーネント名と同じコンテキスト変数の解決を求める時に、 コンテキスト変数がそのとき未定義 (null) であれば、 Seam はインスタンスを生成してから新しいインスタンスをコンテキスト変数にバインドします。 このサンプルでは、 JSF が初めて user という変数と出会うときに、 Seam は User をインスタンス化します。
(3)	Seam がインスタンスを生成する時には、 必ずコンポーネントの デフォルトコンテキスト にあるコンテキスト変数に新しいインスタンスをバインドします。 デフォルトコンテキストは @Scope アノテーションを使用して定義されます。 User Bean はセッションスコープのコンポーネントです。
(4)	EJB 標準 @Table アノテーションは、 User クラスが users テーブルにマッピングされることを示しています。
(5)	name、password 、 username は、 エンティティ Bean の永続属性です。 JBoss の永続属性はすべてアクセスメソッドを定義しています。 レスポンスのレンダリングフェーズおよびモデル値の更新フェーズで JSF によりこのコンポーネントが使用されるときに必要となります。
(6)	空コンストラクタは、EJB と Seam の両方の仕様から必要となります。
(7)	@NotNull と @Length アノテーションは、 Hibernate Validator フレームワークの一部です。 Seam は Hibernate Validator を統合しているため、 データの妥当性検証にこれを使用することができます (永続性に Hiberenate を使用していない場合でも使用できる)。
(8)	EJB 標準 @Id アノテーションは、 エンティティ Bean の主キーであることを示しています。

このサンプルで、もっとも注目してほしい重要なものは @Name と @Scope アノテーションです。 このアノテーションは、 このクラスが Seam コンポーネントであることを規定しています。

以下では、 User クラスのプロパティは 直接 JSF コンポーネントにバインドされ、 モデル値の変更フェーズで JSF によって投入されることがわかります。 JSP ページとエンティティ Bean ドメインモデル間を行き来するデータのコピーに面倒なコードは必要ありません。

しかし、 エンティティ Bean はトランザクション管理やデータベースアクセスを行わないはずなので、 このコンポーネントを JSF のアクションリスナとしては使用できません。 このため、 セッション Bean が必要となります。

1.2.1.2. ステートレスセッション Bean クラス: RegisterAction.java

ほとんどの Seam アプリケーションは、セッション Bean を JSF アクションリスナとして使用します。 (好みに応じて JavaBean を使うことも可能)

アプリケーション内の JSF アクションは正確に 1 つのみで、 これにセッションBean メソッドが 1 つリンクしています。 このサンプルでは、 アクションに関連する状態はすべて User Bean によって保持されるため、 ステートレスセッション Bean を使用しています。

サンプルの中で、本当に注意すべきコードは以下のみです。

例 1.2.

@Stateless                                                                               (1)
@Name("register")
public class RegisterAction implements Register
{

   @In                                                                                   (2)
   private User user;
   
   @PersistenceContext                                                                   (3)
   private EntityManager em;
   
   @Logger                                                                               (4)
   private Log log;
   
   public String register()                                                              (5)
   {
      List existing = em.createQuery(
         "select username from User where username=#{user.username}")                    (6)
         .getResultList();
         
      if (existing.size()==0)
      {
         em.persist(user);
         log.info("Registered new user #{user.username}");                               (7)
         return "/registered.jsp";                                                       (8)
      }
      else
      {
         FacesMessages.instance().add("User #{user.username} already exists");           (9)
         return null;
      }
   }

}

(1)	EJB 標準 @Stateless アノテーションは、 このクラスをステートレスセッション Bean としてマークしています。
(2)	@In アノテーションは、 Seam によってインジェクトされる Bean の属性としてマークしています。 ここで、この属性は、user (インスタンス変数名) という名前のコンテキスト変数からインジェクトされます。
(3)	EJB 標準 @PersistenceContext アノテーションは、 EJB3 エンティティ Entity Manager にインジェクトするために使用されます。
(4)	Seam @Logger アノテーションは、 コンポーネントの Log インスタンスをインジェクトするために使用されています。
(5)	アクションリスナメソッドは、データベースとやり取りするために、 標準 EJB3 EntityManager API を使用し、JSF 結果 (outcome) を返します。 これはセッション Bean なので、 register() メソッドが呼ばれたときに、 トランザクションは自動的に開始され、終了したときにコミットされることに留意してください。
(6)	Seam では EJB-QL 内で JSF EL 式を使用することができます。 バックグラウンドで行われるため見えませんが、 これにより普通の JPA setParameter() が標準 JPA Query オブジェクトを呼び出すことになります。 便利でしょう?
(7)	Log API は、テンプレート化されたログメッセージを容易に表示可能です。
(8)	JSF アクションリスナメソッドは、次にどのページを表示するかを決定するストリング値の結果 (outcome) を返します。 null 結果 (outcome) (あるいは、void アクションリスナメソッド) は、 前のページを再表示します。 普通の JSF では、 結果 (outcome) から JSF view id を決定するために、 常に JSF ナビゲーション規則 を使用することが普通です。 複雑なアプリケーションにとって、この間接的命令は、実用的な良い慣行です。 しかし、このようなとても簡単なサンプルのために、 Seam は、結果 (outcome) として JSF view id の使用を可能とし、 ナビゲーション規則の必要性を取り除きました。 結果 (outcome) として view id を使用する場合、 Seam は、常にブラウザリダイレクトを行うことに留意してください。
(9)	Seam は、共通な問題の解決を支援するために多くの 組み込みコンポーネントを提供しています。 FacesMessages コンポーネントは、 テンプレート化されたエラーや成功メッセージを容易に表示可能です。 組み込み Seam コンポーネントは、 インジェクションあるいは、instance() メソッド呼び出しによって取得可能です。

ここで、@Scope を明示的に指定していないことに留意してください。 各 Seam コンポーネントタイプは、明示的にスコープが指定されない場合、 デフォルトのスコープが適用されます。 ステートレスセッション Bean のデフォルトスコープは、ステートレスコンテキストです。 実際、すべてのステートレスセッション Bean は、 ステートレスコンテキストに属します。

このセッション Bean のアクションリスナは、この小さなアプリケーションのために、 ビジネスロジックと永続ロジックを提供しています。 さらに複雑なアプリケーションでは、 コードを階層化し永続ロジックが専門のデータアクセスコンポーネントとなるようにリファクタリングする必要があるかもしれません。 これをするのは簡単ですが、 Seam は、アプリケーションの階層化のために特殊な方法を強要していないことに留意してください。

さらに、このセッション Bean は WEB リクエスト (例えば、 User オブジェクト内のフォームの値) に関連するコンテキストにアクセスすると同時に、 トランザクションリソース (EntityManager オブジェクト) で保持される状態にもアクセスすることに注目してください。 従来の J2EE アーキテクチャからの分岐点になります。 繰り返しますが、 従来の J2EE の階層化の方が使い易ければ、 そちらの方を Seam アプリケーションに実装することもできます。 ただし、 多くのアプリケーションにとってはあまり役に立ちません。

1.2.1.3. セッション Bean ローカルインタフェース : Register.java

当然、セッション Bean には、ローカルインタフェースが必要です。

例 1.3.

@Local
public interface Register
{
   public String register();
}

Javaコードは以上です。続いて配備記述子です。

1.2.1.4. Seam コンポーネント配備記述子 : components.xml

既に多くの Java フレームワークを使用した経験がある方なら、 プロジェクトが成熟するにつれ徐々に大きくなり管理し難くなる XML ファイルにコンポーネントクラスをすべてを宣言することにもそのうち慣れていくことでしょう。 Seam ではアプリケーションコンポーネントに XML が付随する必要がないこと知ったら、 きっとほっとすることでしょう。 大部分の Seam アプリケーションは、ほんの少しの XML しか必要としません。 また、 この XMLはプロジェクトが大きくなっていっても、 あまり大きくなりません。

それにもかかわらず、ある コンポーネントの ある 外部設定の規定が可能であることは、 多くの場合、有用です。 (特に、Seam に組み込まれたコンポーネント) ここで、2 つの選択があります。 しかし、最も柔軟性のある選択は、 WEB-INF ディレクトリに位置する components.xml と呼ばれるファイルに設定を規定することです。 Seam に、JNDI で EJB コンポーネントの見つけ方を指示するためには、components.xml ファイルを使用します。

例 1.4.

<components xmlns="http://jboss.com/products/seam/components"
            xmlns:core="http://jboss.com/products/seam/core">
     <core:init jndi-pattern="@jndiPattern@"/>
</components>

このコードは、org.jboss.seam.core.init という名前の Seam コンポーネントの jndiPattern という名前のプロパティを設定します。

1.2.1.5. WEB 配備記述子 : web.xml

この小さなアプリケーションのプレゼンテーション層はWARにデプロイされます。 従って、WEB 配備記述子が必要です。

例 1.5.

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee 
                        http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

    <!-- Seam -->

    <listener>
        <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
    </listener>

    <!-- MyFaces -->

    <listener>
        <listener-class>
            org.apache.myfaces.webapp.StartupServletContextListener
        </listener-class>
    </listener>

    <context-param>
        <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
        <param-value>client</param-value>
    </context-param>

    <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <!-- Faces Servlet Mapping -->
    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>*.seam</url-pattern>
    </servlet-mapping>

</web-app>

この web.xml ファイルは、Seam と MyFaces を設定します。 ここで見る設定は、Seam アプリケーションではいつも同じです。

1.2.1.6. JSF 設定 : faces-config.xml

すべての Seam アプリケーションはプレゼンテーション層として JSF ビューを使用します。 従って、faces-config.xml が必要です。

例 1.6.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faces-config 
PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
                            "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">
<faces-config>

    <!-- A phase listener is needed by all Seam applications -->
    
    <lifecycle>
        <phase-listener>org.jboss.seam.jsf.SeamPhaseListener</phase-listener>
    </lifecycle>

</faces-config>

faces-config.xml ファイルは、Seam を JSF に統合します。 JSF 管理 Bean 宣言が不要なことに留意してください。 JSF 管理 Bean は、Seam コンポーネントです。 普通の JSF アプリケーションと比較すると、 Seam アプリケーションは、faces-config.xml をほとんど使用しません。

実際、基本的な記述子の設定だけあれば、 新しい機能を Seam アプリケーションに追加するときに必要となる XML は、 ナビゲーション規則とたぶんjBPM プロセス定義 だけです。 Seam は、XML に記された プロセスフロー と 設定データからビューを取得します。

この簡単なサンプルでは、 view id をアクションコードに埋め込んだため、 ナビゲーション規則さえ不要です。

1.2.1.7. EJB 配備記述子 : ejb-jar.xml

ejb-jar.xml ファイルは、 アーカイブ中のすべてのセッション Bean に SeamInterceptor を付加することによって EJB3 と統合します。

<ejb-jar xmlns="http://java.sun.com/xml/ns/javaee" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
         version="3.0">
         
   <interceptors>
     <interceptor>
       <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
     </interceptor>
   </interceptors>
   
   <assembly-descriptor>
      <interceptor-binding>
         <ejb-name>*</ejb-name>
         <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
      </interceptor-binding>
   </assembly-descriptor>
   
</ejb-jar>

1.2.1.8. EJB 永続配備記述子 : persistence.xml

persistence.xml ファイルは、EJB 永続プロバイダに、 データソースの場所を指示します。また、ベンダー特有の設定を含んでいます。 このサンプルでは起動時に自動スキーマエキスポートを可能としています。

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" 
             version="1.0">
    <persistence-unit name="userDatabase">
      <provider>org.hibernate.ejb.HibernatePersistence</provider>
      <jta-data-source>java:/DefaultDS</jta-data-source>
      <properties>
         <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
      </properties>
    </persistence-unit>
</persistence>

1.2.1.9. ビュー : register.jsp、registered.jsp

Seam アプリケーションのビューページは、 JSF をサポートする多くの技術を使用して実装されています。 JSP は多くの開発者にとって知られていること、ここでは最小限の要件しかないため、 このサンプルでは、JSP を使用しています。 (ただし、 JBoss のアドバイスに従っている場合は、 ご使用のアプリケーションには Facelet を使用しているでしょう。)

例 1.7.

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://jboss.com/products/seam/taglib" prefix="s" %>
<html>
 <head>
  <title>Register New User</title>
 </head>
 <body>
  <f:view>
   <h:form>
     <table border="0">
       <s:validateAll>
         <tr>
           <td>Username</td>
           <td><h:inputText value="#{user.username}"/></td>
         </tr>
         <tr>
           <td>Real Name</td>
           <td><h:inputText value="#{user.name}"/></td>
         </tr>
         <tr>
           <td>Password</td>
           <td><h:inputSecret value="#{user.password}"/></td>
         </tr>
       </s:validateAll>
     </table>
     <h:messages/>
     <h:commandButton type="submit" value="Register" action="#{register.register}"/>
   </h:form>
  </f:view>
 </body>
</html>

ここで Seam 固有となるのは <s:validateAll> タグのみです。 この JSF コンポーネントは 含まれるすべての入力フィールドをエンティティbean で指定される Hibernate Validator アノテーションに対して検証するよう JSF に指示しています。

例 1.8.

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<html>
 <head>
  <title>Successfully Registered New User</title>
 </head>
 <body>
  <f:view>
    Welcome, <h:outputText value="#{user.name}"/>, 
    you are successfully registered as <h:outputText value="#{user.username}"/>.
  </f:view>
 </body>
</html>

これは、標準 JSF コンポーネントを使用した何の変哲もない旧式の JSP ページです。 Seam 独特のものはありません。

1.2.1.10. EAR 配備記述子 : application.xml

最後に、EARとして アプリケーションがデプロイされるため、配備記述子も必要になります。

例 1.9.

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://java.sun.com/xml/ns/javaee" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_5.xsd"
             version="5">
             
    <display-name>Seam Registration</display-name>

    <module>
        <web>
            <web-uri>jboss-seam-registration.war</web-uri>
            <context-root>/seam-registration</context-root>
        </web>
    </module>
    <module>
        <ejb>jboss-seam-registration.jar</ejb>
    </module>
    <module>
        <java>jboss-seam.jar</java>
    </module>
    <module>
        <java>el-api.jar</java>
    </module>
    <module>
        <java>el-ri.jar</java>
    </module>
    
</application>

この配備記述子はエンタープライズアーカイブのモジュールとリンクし、 WEBアプリケーションをコンテキストルート /seam-registration にバインドします。

エンタープライズアプリケーション中のすべてのファイルを見終わりました。

データベースの検索結果をクリックが可能な一覧にすることは、 いずれのオンラインアプリケーションにおいてもたいへん重要な部分となります。 Seam は JSF に加えさらに特殊な機能を提供することで、 EJB-QL または HQL を使ったデータのクエリを容易にし、 JSF <h:dataTable> を使ったクリック可能な一覧としての表示を実現します。 この掲示板サンプルは、 この機能を実演しています。

@Entity
@Name("message")
@Scope(EVENT)
public class Message implements Serializable
{
   private Long id;
   private String title;
   private String text;
   private boolean read;
   private Date datetime;
   
   @Id @GeneratedValue
   public Long getId() {
      return id;
   }
   public void setId(Long id) {
      this.id = id;
   }
   
   @NotNull @Length(max=100)
   public String getTitle() {
      return title;
   }
   public void setTitle(String title) {
      this.title = title;
   }
   
   @NotNull @Lob
   public String getText() {
      return text;
   }
   public void setText(String text) {
      this.text = text;
   }
   
   @NotNull
   public boolean isRead() {
      return read;
   }
   public void setRead(boolean read) {
      this.read = read;
   }
   
   @NotNull 
   @Basic @Temporal(TemporalType.TIMESTAMP)
   public Date getDatetime() {
      return datetime;
   }
   public void setDatetime(Date datetime) {
      this.datetime = datetime;
   }
   
}

@Stateful
@Scope(SESSION)
@Name("messageManager")
public class MessageManagerBean implements Serializable, MessageManager
{

   @DataModel                                                                            (1)
   private List<Message> messageList;
   
   @DataModelSelection                                                                   (2)
   @Out(required=false)                                                                  (3)
   private Message message;
   
   @PersistenceContext(type=EXTENDED)                                                    (4)
   private EntityManager em;
   
   @Factory("messageList")                                                               (5)
   public void findMessages()
   {
      messageList = em.createQuery("from Message msg order by msg.datetime desc").getResultList();
   }
   
   public void select()                                                                  (6)
   {
      message.setRead(true);
   }
   
   public void delete()                                                                  (7)
   {
      messageList.remove(message);
      em.remove(message);
      message=null;
   }
   
   @Remove @Destroy                                                                      (8)
   public void destroy() {}

}

@Local
public interface MessageManager
{
   public void findMessages();
   public void select();
   public void delete();
   public void destroy();
}

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<html>
 <head>
  <title>Messages</title>
 </head>
 <body>
  <f:view>
   <h:form>
     <h2>Message List</h2>
     <h:outputText value="No messages to display" rendered="#{messageList.rowCount==0}"/>
     <h:dataTable var="msg" value="#{messageList}" rendered="#{messageList.rowCount>0}">
        <h:column>
           <f:facet name="header">
              <h:outputText value="Read"/>
           </f:facet>
           <h:selectBooleanCheckbox value="#{msg.read}" disabled="true"/>
        </h:column>
        <h:column>
           <f:facet name="header">
              <h:outputText value="Title"/>
           </f:facet>
           <h:commandLink value="#{msg.title}" action="#{messageManager.select}"/>
        </h:column>
        <h:column>
           <f:facet name="header">
              <h:outputText value="Date/Time"/>
           </f:facet>
           <h:outputText value="#{msg.datetime}">
              <f:convertDateTime type="both" dateStyle="medium" timeStyle="short"/>
           </h:outputText>
        </h:column>
        <h:column>
           <h:commandButton value="Delete" action="#{messageManager.delete}"/>
        </h:column>
     </h:dataTable>
     <h3><h:outputText value="#{message.title}"/></h3>
     <div><h:outputText value="#{message.text}"/></div>
   </h:form>
  </f:view>
 </body>
</html>

jBPM は、ワークフローやタスク管理の優れた機能を提供します。 どのように jBPM が Seam と統合されているかを知るために、 簡単な To-Do 一覧アプリケーションをお見せしましょう。 タスクの一覧を管理することは、jBPM の中心的な機能であるため、 このサンプルには Java コードがほとんどありません。

1.4.1. コードの理解

このサンプルの中心は、jBPM のプロセス定義です。 2 つの JSP と 2 つのちょっとした JavaBean もあります。 (データベースアクセスやトランザクション特性がないので、 セッション Bean を使用する理由はありません。) それではプロセス定義から始めましょう。

例 1.13.

<process-definition name="todo">
   
   <start-state name="start">                                                            (1)
      <transition to="todo"/>
   </start-state>
   
   <task-node name="todo">                                                               (2)
      <task name="todo" description="#{todoList.description}">                           (3)
         <assignment actor-id="#{actor.id}"/>                                            (4)
      </task>
      <transition to="done"/>
   </task-node>
   
   <end-state name="done"/>                                                              (5)
   
</process-definition>

(1)	<start-state> ノードはプロセスの論理的な開始を表します。 プロセスが開始すると、 直ちに todo ノードに遷移します。
(2)	<task-node> ノードは 待ち状態 を表します。 ビジネスプロセスの実行が一時停止され、 1 つまたは複数のタスクが行われるのを待機します。
(3)	<task> 要素は、ユーザによって実行されるタスクを定義します。 このノードには 1 つのタスクしか定義されていないので、 それが完了すると実行が再開され、 終了状態に遷移していきます。 このタスクは、 todoList という名前の Seam コンポーネント (JavaBean の 一種) から description を取得します。
(4)	タスクが生成されたとき、タスクにはユーザあるいはユーザグループを割り当てる必要があります。 このサンプルでは、タスクは、現在のユーザに割り当てられています。 それは、actor という名前の組み込み Seam コンポーネントから取得します。 どのような Seam コンポーネントもタスク割り当てを実行するために使用される可能性があります。
(5)	<end-state>ノードは、ビジネスプロセスの論理的な終了を定義します。 実行がこのノードに到達したとき、 プロセスインスタンスは破棄されます。

JBossIDE に提供されたプロセス定義エディタを使用してプロセス定義を見た場合、 以下のようになります。

このドキュメントは、ノードのグラフとして ビジネスプロセス を定義します。 これはささいな現実にあり得るビジネスプロセスです。 実行されなければならない タスク は、1 つだけです。 タスクが完了したとき ビジネスプロセスは終了します。

最初の JavaBean はログイン画面 login.jsp を処理します。 処理作業は、 単に actor コンポーネントを使用して jBPM actor id を初期化するだけです。 (実際のアプリケーションでは、 ユーザ認証も必要です。)

例 1.14.

@Name("login")
public class Login {
   
   @In
   private Actor actor;
   
   private String user;

   public String getUser() {
      return user;
   }

   public void setUser(String user) {
      this.user = user;
   }
   
   public String login()
   {
      actor.setId(user);
      return "/todo.jsp";
   }
}

ここでは、組み込み Actor コンポーネントをインジェクトするために、 @In を使用しているのがわかります。

次の JSP 自体は重要ではありません。

例 1.15.

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<html>
<head>
<title>Login</title>
</head>
<body>
<h1>Login</h1>
<f:view>
    <h:form>
      <div>
        <h:inputText value="#{login.user}"/>
        <h:commandButton value="Login" action="#{login.login}"/>
      </div>
    </h:form>
</f:view>
</body>
</html>

2 つめの JavaBean は、ビジネスプロセスインスタンスの開始とタスクの終了を担当します。

例 1.16.

@Name("todoList")
public class TodoList {
   
   private String description;
   
   public String getDescription()                                                        (1)
   {
      return description;
   }

   public void setDescription(String description) {
      this.description = description;
   }
   
   @CreateProcess(definition="todo")                                                     (2)
   public void createTodo() {}
   
   @StartTask @EndTask                                                                   (3)
   public void done() {}

}

(1)	description プロパティは、JSP ページからユーザ入力を受け取り、 タスク内容が設定されるように、それをプロセス定義に公開します。
(2)	Seam @CreateProcess アノテーションは、名前付きプロセス定義のために jBPM プロセスインスタンスを生成します。
(3)	Seam @StartTask アノテーションは、タスク上で作業を開始します。 @EndTask は、タスクを終了し、ビジネスプロセスの再開を可能にします。

現実的なサンプルでは、 @StartTask と @EndTask が同じメソッド上に出現することはありません。 なぜなら、 通常はそのタスクを完了するために、 アプリケーションを使用して行うべき作業があるからです。

最後に、このアプリケーションのポイントは todo.jsp にあります。

例 1.17.

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://jboss.com/products/seam/taglib" prefix="s" %>
<html>
<head>
<title>Todo List</title>
</head>
<body>
<h1>Todo List</h1>
<f:view>
   <h:form id="list">
      <div>
         <h:outputText value="There are no todo items." rendered="#{empty taskInstanceList}"/>
         <h:dataTable value="#{taskInstanceList}" var="task" rendered="#{not empty taskInstanceList}">
            <h:column>
                <f:facet name="header">
                    <h:outputText value="Description"/>
                </f:facet>
                <h:inputText value="#{task.description}"/>
            </h:column>
            <h:column>
                <f:facet name="header">
                    <h:outputText value="Created"/>
                </f:facet>
                <h:outputText value="#{task.taskMgmtInstance.processInstance.start}">
                    <f:convertDateTime type="date"/>
                </h:outputText>
            </h:column>
            <h:column>
                <f:facet name="header">
                    <h:outputText value="Priority"/>
                </f:facet>
                <h:inputText value="#{task.priority}" style="width: 30"/>
            </h:column>
            <h:column>
                <f:facet name="header">
                    <h:outputText value="Due Date"/>
                </f:facet>
                <h:inputText value="#{task.dueDate}" style="width: 100">
                    <f:convertDateTime type="date" dateStyle="short"/>
                </h:inputText>
            </h:column>
            <h:column>
                <s:button value="Done" action="#{todoList.done}" taskInstance="#{task}"/>
            </h:column>
         </h:dataTable>
      </div>
      <div>
      <h:messages/>
      </div>
      <div>
         <h:commandButton value="Update Items" action="update"/>
      </div>
   </h:form>
   <h:form id="new">
      <div>
         <h:inputText value="#{todoList.description}"/>
         <h:commandButton value="Create New Item" action="#{todoList.createTodo}"/>
      </div>
   </h:form>
</f:view>
</body>
</html>

1 つずつ見ていきます。

ページはタスク一覧をレンダリングしています。 これは、taskInstanceList と呼ばれる Seam 組み込みコンポーネントから取得します。 この一覧はJSFフォームの中に定義されています。

<h:form id="list">
   <div>
      <h:outputText value="There are no todo items." rendered="#{empty taskInstanceList}"/>
      <h:dataTable value="#{taskInstanceList}" var="task" rendered="#{not empty taskInstanceList}">
         ...
      </h:dataTable>
   </div>
</h:form>

一覧の各要素は jBPM クラス TaskInstance のインスタンスです。 以下のコードは単に、一覧中の各タスクの興味深いプロパティを表示しています。 記述内容、 優先順や、 納期の値については、 ユーザーがこれらの値を更新できるよう入力コントロールを使用します。

<h:column>
    <f:facet name="header">
       <h:outputText value="Description"/>
    </f:facet>
    <h:inputText value="#{task.description}"/>
</h:column>
<h:column>
    <f:facet name="header">
        <h:outputText value="Created"/>
    </f:facet>
    <h:outputText value="#{task.taskMgmtInstance.processInstance.start}">
        <f:convertDateTime type="date"/>
    </h:outputText>
</h:column>
<h:column>
    <f:facet name="header">
        <h:outputText value="Priority"/>
    </f:facet>
    <h:inputText value="#{task.priority}" style="width: 30"/>
</h:column>
<h:column>
    <f:facet name="header">
        <h:outputText value="Due Date"/>
    </f:facet>
    <h:inputText value="#{task.dueDate}" style="width: 100">
        <f:convertDateTime type="date" dateStyle="short"/>
    </h:inputText>
</h:column>

このボタンは、 @StartTask @EndTask アノテーション付きのアクションメソッドが呼び出されることにより終了します。 それは、task id をリクエストパラメータとして Seam に渡します。

<h:column>
    <s:button value="Done" action="#{todoList.done}" taskInstance="#{task}"/>
</h:column>

(seam-ui.jar パッケージから、 Seam <s:button> JSF コントロールを使用していることに留意してください。)

このボタンは、 タスクのプロパティを変更するために使用されます。 フォームがサブミットされたとき、 Seam と jBPM は、タスクに対するどのような変化も永続化します。 アクションリスナメソッドは全く不要です。

<h:commandButton value="Update Items" action="update"/>

ページの 2 つ目のフォームは新しいアイテムを作成するために使用されます。 @CreateProcessアノテーション付きアクションメソッドから呼び出されることにより行われます。

<h:form id="new">
    <div>
        <h:inputText value="#{todoList.description}"/>
        <h:commandButton value="Create New Item" action="#{todoList.createTodo}"/>
    </div>
</h:form>

このサンプルには、その他いくつか必要なファイルがありますが、 それらは 標準的な jBPM や Seam の設定であり特殊なものはありません。

比較的自由な (アドホック) 画面遷移をさせる Seam アプリケーションの場合、 JSF/Seam ナビゲーション規則がページフローを定義するのに最適な方法となります。 画面遷移に制約が多いスタイルのアプリケーションの場合、 特によりステートフルなユーザインタフェースの場合、 ナビゲーション規則ではシステムの流れを本当に理解するのは困難になります。 フローを理解するには、 ビューページ、 アクション、 ナビゲーション規則からフローに関する情報をかき集める必要があります。

Seam は、jPDL プロセス定義を使うことでページフロー定義を可能にします。 この簡単な数字当てゲームサンプルからどのようにこれが実現されているかがわかります。

1.5.1. コードの理解

このサンプルは 1 つのJavaBean、3 つの JSP ページ、それと jPDL プロセスフロー定義で実装されています。 ページフローから見始めましょう。

例 1.18.

<pageflow-definition name="numberGuess">
   
   <start-page name="displayGuess" view-id="/numberGuess.jsp">
      <redirect/>
      <transition name="guess" to="evaluateGuess">
          <action expression="#{numberGuess.guess}" />
      </transition>                                                                      (1)
   </start-page>                                                                         (2)
                                                                                         (3)
   <decision name="evaluateGuess" expression="#{numberGuess.correctGuess}">
      <transition name="true" to="win"/>
      <transition name="false" to="evaluateRemainingGuesses"/>
   </decision>                                                                           (4)
   
   <decision name="evaluateRemainingGuesses" expression="#{numberGuess.lastGuess}">
      <transition name="true" to="lose"/>
      <transition name="false" to="displayGuess"/>
   </decision>
   
   <page name="win" view-id="/win.jsp">
      <redirect/>
      <end-conversation />
   </page>
   
   <page name="lose" view-id="/lose.jsp">
      <redirect/>
      <end-conversation />
   </page>
   
</pageflow-definition>

(1)	<page> 要素は、待ち状態を定義しています。 ここでは、システムは特定の JSF ビューを表示し、ユーザ入力を待っています。 view-id は普通の JSF ナビゲーション規則で使用されている JSF view id と同じものです。 ページが画面遷移するときに、 redirect 属性は、Seam に post-then-redirect の使用を指示しています。 (この結果がブラウザ URL に表示されます。)
(2)	<transition> 要素は JSF 結果 (outcome) に名前を付けます。 JSF アクションがその結果 (outcome) となる場合に、 transition が起動されます。 jBPM transition action が呼び出された後、 実行はページフローグラフの次のノードに進みます。
(3)	transition の <action> は、 jBPM の transitionでそれが起こることを除けば、 JSF action と同じです。 transition action は、どのような Seam コンポーネントでも呼び出すことが可能です。
(4)	<decision> ノードはページフローを分岐させ、 JSF EL 式を評価することによって次に実行されるノードを決定します。

JBossIDE ページフローエディタでのページフローは以下のようになります。

ページフローを見終わりました。 アプリケーションの残りの部分を理解することはもう簡単です。

これはアプリケーションの主要なページ numberGuess.jsp です。

例 1.19.

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<html>
<head>
<title>Guess a number...</title>
</head>
<body>
<h1>Guess a number...</h1>
<f:view>
    <h:form>
        <h:outputText value="Higher!" rendered="#{numberGuess.randomNumber>numberGuess.currentGuess}" />
        <h:outputText value="Lower!" rendered="#{numberGuess.randomNumber<numberGuess.currentGuess}" />
        <br />
        I'm thinking of a number between <h:outputText value="#{numberGuess.smallest}" /> and 
        <h:outputText value="#{numberGuess.biggest}" />. You have 
        <h:outputText value="#{numberGuess.remainingGuesses}" /> guesses.
        <br />
        Your guess: 
        <h:inputText value="#{numberGuess.currentGuess}" id="guess" required="true">
            <f:validateLongRange
                maximum="#{numberGuess.biggest}" 
                minimum="#{numberGuess.smallest}"/>
        </h:inputText>
        <h:commandButton type="submit" value="Guess" action="guess" />
        <br/>
        <h:message for="guess" style="color: red"/>
    </h:form>
</f:view>
</body>
</html>

アクションを直接呼び出す代わりに、 どのようにコマンドボタンはguess transitionを指定しているかに着目してください。

win.jsp ページはごく普通のものです。

例 1.20.

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<html>
<head>
<title>You won!</title>
</head>
<body>
<h1>You won!</h1>
<f:view>
    Yes, the answer was <h:outputText value="#{numberGuess.currentGuess}" />.
    It took you <h:outputText value="#{numberGuess.guessCount}" /> guesses.
    Would you like to <a href="numberGuess.seam">play again</a>?
  </f:view>
</body>
</html>

lose.jsp も同様です (同様なので省略します)。 最後は、 JavaBean Seam コンポーネントです。

例 1.21.

@Name("numberGuess")
@Scope(ScopeType.CONVERSATION)
public class NumberGuess {
   
   private int randomNumber;
   private Integer currentGuess;
   private int biggest;
   private int smallest;
   private int guessCount;
   private int maxGuesses;
   
   @Create                                                                               (1)
   @Begin(pageflow="numberGuess")                                                        (2)
   public void begin()
   {
      randomNumber = new Random().nextInt(100);
      guessCount = 0;
      biggest = 100;
      smallest = 1;
   }
   
   public void setCurrentGuess(Integer guess)
   {
      this.currentGuess = guess;
   }
   
   public Integer getCurrentGuess()
   {
      return currentGuess;
   }
   
   public void guess()
   {
      if (currentGuess>randomNumber)
      {
         biggest = currentGuess - 1;
      }
      if (currentGuess<randomNumber)
      {
         smallest = currentGuess + 1;
      }
      guessCount ++;
   }
   
   public boolean isCorrectGuess()
   {
      return currentGuess==randomNumber;
   }
   
   public int getBiggest()
   {
      return biggest;
   }
   
   public int getSmallest()
   {
      return smallest;
   }
   
   public int getGuessCount()
   {
      return guessCount;
   }
   
   public boolean isLastGuess()
   {
      return guessCount==maxGuesses;
   }

   public int getRemainingGuesses() {
      return maxGuesses-guessCount;
   }

   public void setMaxGuesses(int maxGuesses) {
      this.maxGuesses = maxGuesses;
   }

   public int getMaxGuesses() {
      return maxGuesses;
   }

   public int getRandomNumber() {
      return randomNumber;
   }
}

(1)	最初に、JSP ページが numberGuess コンポーネントを要求するとき、 Seam は新しいコンポーネントを生成します。 そして、@Create メソッドが呼ばれ、 コンポーネント自身の初期化が可能になります。
(2)	@Begin アノテーションは、 Seam の対話を開始し (詳細は後述)、 対話のページフローを使用するためのページフロー定義を指定します。

お分かりの通り、この Seam コンポーネントは純粋なビジネスロジックです。 ユーザインタラクションのフローについて理解する必要はまったくありません。 これによりコンポーネント再利用の可能性を向上させます。

DVD ストアのデモアプリケーションは、 タスク管理とページフローのための jBPM の実践的な使用法を見せてくれます。

ユーザ画面は、検索やショッピングカート機能の実装のために jPDL ページフローを利用しています。

この管理画面は、オーダの承認やショッピングサイクルを管理するために jBPM を利用します。 ビジネスプロセスは、異なるプロセス定義を選択することにより動的に変更されるかもしれません。

TODO

dvdstore ディレクトリの中をご覧ください。

問題追跡デモは Seam のワークスペース管理の機能をよく披露しています。 対話スイッチャ、対話一覧、ブレッドクラム

TODO

issues ディレクトリの中をご覧ください。

Hibernate 予約デモは、 永続性のために Hibernate、 セッション Bean の代わりに JavaBean を使用した簡単な予約デモの移植版です。

TODO

hibernate ディレクトリの中をご覧ください。

Seam は、サーバサイドで状態保持するアプリケーションの実装をとても容易にします。 しかし、サーバサイドの状態管理は、いつも適切というわけではありません。 (特に、コンテンツ を提供する機能において ) この種の問題のために、ユーザにページをブックマークさせ、 そして、比較的ステートレスなサーバとする必要がしばしばあります、 その結果、ブックマークを通していつでもどんなページにもアクセス可能になります。 この Blog サンプルは、 Seam を使用した RESTful アプリケーションの実装方法を見せてくれます。 検索結果ページを含むすべてのアプリケーションのページは、 ブックマークが可能です。

この Blog サンプルは、"引っぱり (PULL) " - スタイル MVC の使用を実演しています。 ここで、ビューのためのデータ取得とデータ準備のアクションメソッドリスナを使用する代わりに、 ビューは、レンダリングしているコンポーネントからデータを引き出します (PULL)。

<h:dataTable value="#{blog.recentBlogEntries}" var="blogEntry" rows="3">
   <h:column>
      <div class="blogEntry">
         <h3>#{blogEntry.title}</h3>
         <div>
            <h:outputText escape="false" 
                  value="#{blogEntry.excerpt==null ? blogEntry.body : blogEntry.excerpt}"/>
         </div>
         <p>
            <h:outputLink value="entry.seam" rendered="#{blogEntry.excerpt!=null}">
               <f:param name="blogEntryId" value="#{blogEntry.id}"/>
               Read more...
            </h:outputLink>
         </p>
         <p>
            [Posted on 
            <h:outputText value="#{blogEntry.date}">
               <f:convertDateTime timeZone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
            </h:outputText>]
            &#160;
            <h:outputLink value="entry.seam">[Link]
               <f:param name="blogEntryId" value="#{blogEntry.id}"/>
            </h:outputLink>
         </p>
      </div>
   </h:column>
</h:dataTable>

@Name("blog")
@Scope(ScopeType.STATELESS)
public class BlogService 
{
   
   @In                                                                                   (1)
   private EntityManager entityManager;
  
   @Unwrap                                                                               (2)
   public Blog getBlog()
   {
      return (Blog) entityManager.createQuery("from Blog b left join fetch b.blogEntries")
            .setHint("org.hibernate.cacheable", true)
            .getSingleResult();
   }

}

<div id="search">
   <h:form>
      <h:inputText value="#{searchAction.searchPattern}"/>
      <h:commandButton value="Search" action="/search.xhtml"/>
   </h:form>
</div>

<navigation-rule>
   <navigation-case>
      <from-outcome>searchResults</from-outcome>
      <to-view-id>/search.xhtml</to-view-id>
      <redirect/>
   </navigation-case>
</navigation-rule>

<div id="search">
   <h:form>
      <h:inputText value="#{searchAction.searchPattern}"/>
      <h:commandButton value="Search" action="searchResults"/>
   </h:form>
</div>

<pages>
   <page view-id="/search.xhtml">
      <param name="searchPattern" value="#{searchService.searchPattern}"/>
   </page>
   ...
</pages>

<h:dataTable value="#{searchResults}" var="blogEntry">
   <h:column>
      <div>
         <h:outputLink value="entry.seam">
            <f:param name="blogEntryId" value="#{blogEntry.id}"/>
            #{blogEntry.title}
         </h:outputLink>
         posted on 
         <h:outputText value="#{blogEntry.date}">
            <f:convertDateTime timeZone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
         </h:outputText>
      </div>
   </h:column>
</h:dataTable>

@Name("searchService")
public class SearchService 
{
   
   @In
   private EntityManager entityManager;
   
   private String searchPattern;
   
   @Factory("searchResults")
   public List<BlogEntry> getSearchResults()
   {
      if (searchPattern==null)
      {
         return null;
      }
      else
      {
         return entityManager.createQuery("select be from BlogEntry be where lower(be.title) like :searchPattern or lower(be.body) like :searchPattern order by be.date desc")
               .setParameter( "searchPattern", getSqlSearchPattern() )
               .setMaxResults(100)
               .getResultList();
      }
   }

   private String getSqlSearchPattern()
   {
      return searchPattern==null ? "" : '%' + searchPattern.toLowerCase().replace('*', '%').replace('?', '_') + '%';
   }

   public String getSearchPattern()
   {
      return searchPattern;
   }

   public void setSearchPattern(String searchPattern)
   {
      this.searchPattern = searchPattern;
   }

}

@Name("entryAction")
@Scope(STATELESS)
public class EntryAction
{
   @In(create=true) 
   private Blog blog;
   
   @Out
   private BlogEntry blogEntry;
   
   public void loadBlogEntry(String id) throws EntryNotFoundException
   {
      blogEntry = blog.getBlogEntry(id);
      if (blogEntry==null) throw new EntryNotFoundException(id);
   }
   
}

<pages>
   ...

   <page view-id="/entry.xhtml" action="#{entryAction.loadBlogEntry(blogEntry.id)}">
      <param name="blogEntryId" value="#{blogEntry.id}"/>
   </page>

   <page view-id="/post.xhtml" action="#{loginAction.challenge}"/>

   <page view-id="*" action="#{blog.hitCount.hit}"/>

</pages>

<div class="blogEntry">
   <h3>#{blogEntry.title}</h3>
   <div>
      <h:outputText escape="false" value="#{blogEntry.body}"/>
   </div>
   <p>
      [Posted on&#160;
      <h:outputText value="#{blogEntry.date}">
         <f:convertDateTime timezone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
      </h:outputText>]
   </p>
</div>

@ApplicationException(rollback=true)
@HttpError(errorCode=HttpServletResponse.SC_NOT_FOUND)
public class EntryNotFoundException extends Exception
{
   EntryNotFoundException(String id)
   {
      super("entry not found: " + id);
   }
}

@Name("entryAction")
@Scope(STATELESS)
public class EntryAction
{
   @In(create=true) 
   private Blog blog;
   
   @In @Out
   private BlogEntry blogEntry;
   
   public void loadBlogEntry() throws EntryNotFoundException
   {
      blogEntry = blog.getBlogEntry( blogEntry.getId() );
      if (blogEntry==null) throw new EntryNotFoundException(id);
   }
   
}

<pages>
   ...

   <page view-id="/entry.xhtml" action="#{entryAction.loadBlogEntry}">
      <param name="blogEntryId" value="#{blogEntry.id}"/>
   </page>
   
   ...
</pages>

JBoss AS 4.0 は JSF 1.1 実装 Apache MyFaces を同梱しています。 長い間待ちましたが、 いまだ MyFaces からの JSF 1.2 実装はありません。 これ以外の理由も含めて、 JBoss AS 4.2 はデフォルトで JSF 1.2 リファレンス実装を組み込むことになります。 4.2 のリリース後すぐに、 Seam サンプルを JSF 1.2 に移行する予定です。

待つことができない人のために、Seam は、すでに JSF 1.2 互換であり、 JBoss 4.0.5 上で JSF 1.2 を実行する Seam サンプルを手に入れることは簡単です。 あの予約サンプルで始めましょう。

JBoss を再起動し、 examples/booking ディレクトリで ant と入力します。

始める前に、JDK 5 または JDK 6 とJBoss AS 4.0.5 と Ant 1.6、そして、それに合う Eclipse 用の JBoss IDE プラグイン と TestNG プラグインがインストールされていることを確認してください。 Eclipse の JBoss サーバビューに JBoss 設定を追加してください。 デバッグモードで JBoss を起動してください。 最後に、Seam ディストリビューションを展開したディレクトリで、 コマンドプロンプト起動してください。

JBoss には WAR や EAR のホット再デプロイメントに優れたサポートがあります。 残念ながら、 JVM にバグがあるため、 — 開発段階では一般的な — EAR の再デプロイメントを繰り返すと、最終的には JVM が perm gen スペースを使い果たしてしまうことになります。 この理由により、デプロイメント時には perm gen space を大きく確保した JVM で JBoss を稼動させることを推奨します。 JBoss IDE から JBoss を稼動させる場合は、 「VM 引数」の下にあるサーバ起動設定でこれを設定することができます。 以下のような値がよいでしょう。

-Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512

十分なメモリがないとすると、以下が最小の推奨値です。

-Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256

コマンドラインから JBoss を起動しているならば、 bin/run.conf の JVM オプション設定が可能です。

今すぐに変更を行いたくない場合は特に行う必要はありません — OutOfMemoryException が発生した時点で対処してください。

最初にすべきことは、あなたの環境用に seam-gen を設定することです。 ( JBoss AS インストールディレクトリ、Eclipse ワークスペース、 データベースコネクション ) それは簡単です。単純にタイプしてください。

cd jboss-seam-1.1.x
seam setup

以下のように必要な情報の入力を要求されるでしょう。

C:\Projects\jboss-seam>seam setup
Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml

setup:
    [echo] Welcome to seam-gen :-)
    [input] Enter your Java project workspace [C:/Projects]

    [input] Enter your JBoss home directory [C:/Program Files/jboss-4.0.5.GA]

    [input] Enter the project name [myproject]
helloworld
    [input] Is this project deployed as an EAR (with EJB components) or a WAR (with no EJB support) [ear] (ear,war,)

    [input] Enter the Java package name for your session beans [com.mydomain.helloworld]
org.jboss.helloworld
    [input] Enter the Java package name for your entity beans [org.jboss.helloworld]

    [input] Enter the Java package name for your test cases [org.jboss.helloworld.test]

    [input] What kind of database are you using? [hsql] (hsql,mysql,oracle,postgres,mssql,db2,sybase,)
mysql
    [input] Enter the Hibernate dialect for your database [org.hibernate.dialect.MySQLDialect]

    [input] Enter the filesystem path to the JDBC driver jar [lib/hsqldb.jar]
../../mysql-connector.jar
    [input] Enter JDBC driver class for your database [com.mysql.jdbc.Driver]

    [input] Enter the JDBC URL for your database [jdbc:mysql:///test]

    [input] Enter database username [sa]
gavin
    [input] Enter database password []

    [input] Are you working with tables that already exist in the database? [n] (y,n,)
y
    [input] Do you want to drop and recreate the database tables and data in import.sql each time you deploy? [n] (y,n,)
n
[propertyfile] Creating new property file: C:\Projects\jboss-seam\seam-gen\build.properties
     [echo] Installing JDBC driver jar to JBoss server
     [echo] Type 'seam new-project' to create the new project

BUILD SUCCESSFUL
Total time: 1 minute 17 seconds
C:\Projects\jboss-seam>

このツールは気の利いたデフォルト値を提供します。 プロンプトに対して単に enter を押すだけで大丈夫です。

必須となる最重要な選択は、プロジェクトのEAR形式デプロイとWAR形式デプロイのどちらにするかです。 EAR プロジェクトは EJB3.0 に対応し、 Java EE 5 が必要です。 WAR プロジェクトは EJB3.0 には対応しませんがおそらく J2EE 環境にデプロイメントが可能でしょう。 WARは EAR に比べシンプルで理解しやすいパッケージです。 JBoss を ejb3 プロファイルでインストールした場合は ear を選択してください。 これ以外は war を選択してください。 ここからは、 このチュートリアルは EAR デプロイメントが選択されたと仮定しますが、 WAR デプロイメントの場合もまったく同じステップで進むことができます。

既存のデータモデルで作業をしている場合、 データベースに既にテーブルが存在していることを seam-gen に必ず知らせてください。

設定は seam-gen/build.properties に格納されていますが、 2 度目に seam setup を実行することで変更することも可能です。

以下のようにタイプすることで、Eclipse ワークスペースディレクトリに、 新規プロジェクトの生成が可能です。

seam new-project

C:\Projects\jboss-seam>seam new-project
Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml

validate-workspace:

validate-project:

copy-lib:
     [echo] Copying project jars ...
     [copy] Copying 32 files to C:\Projects\helloworld\lib
     [copy] Copying 9 files to C:\Projects\helloworld\embedded-ejb

file-copy-wtp:

file-copy:
     [echo] Copying project resources ...
     [copy] Copying 12 files to C:\Projects\helloworld\resources
     [copy] Copying 1 file to C:\Projects\helloworld\resources
     [copy] Copying 5 files to C:\Projects\helloworld\view
     [copy] Copying 5 files to C:\Projects\helloworld
    [mkdir] Created dir: C:\Projects\helloworld\src

new-project:
     [echo] A new Seam project named 'helloworld' was created in the /Users/gavin/Documents/workspace directory
     [echo] Type 'seam explode' and go to http://localhost:8080/helloworld
     [echo] Eclipse Users: Add the project into Eclipse using File > New > Project and select General > Project (not Java Project)
     [echo] NetBeans Users: Open the project in NetBeans

BUILD SUCCESSFUL
Total time: 7 seconds
C:\Projects\jboss-seam>

Seam jar、依存する jar そして JDBC ドライバ jar を新しい Eclipse プロジェクトにコピーし、 Eclipse メタデータおよび Ant ビルドスクリプトに従って必要となるすべてのリソースと設定ファイル群、 facelets テンプレートファイル、 スタイルシートを生成します。 新規 -> プロジェクト... -> 一般 -> プロジェクト -> 次へ の手順でプロジェクトを追加し、 プロジェクト名 (この場合、 helloworld) を入力して、 完了 をクリックすれば、 Eclipse プロジェクトは自動的に展開された JBoss AS ディレクトリ構造にデプロイされます。 新規プロジェクトウィザードから Java プロジェクト は選択しないでください。

Eclipse のデフォルト JDK が SE 5 あるいは Java SE 6 JDK でなければ、 プロジェクト -> プロパティ -> Java コンパイラ の手順で、Java SE 5 互換の JDK を選ぶ必要があります。

別の方法として、Eclise の外部から seam explode とタイプすることでプロジェクトのデプロイが可能です。 seam explode.

welcome page を見るには、http://localhost:8080/helloworld に進んでください。 これは、テンプレート view/layout/template.xhtml を使用した facelets page, view/home.xhtml です。 Eclipse からこのページやテンプレートの編集が可能です。 そしてブラウザを更新することで即座に結果を見ることが可能です。

プロジェクトディレクトリに XML 設定ドキュメントが生成されますがびっくりしないでください。 これらのほとんどが標準 Java EE に関するもので、 1 度生成したら 2 度と見る必要のないものです。 全 Seam プロジェクトで 90% は同じものです。 (seam-gen が書けるほどですから記述が非常に簡単なドキュメントです。)

生成されたプロジェクトは3つのデータベースと永続性設定を含んでいます。 HSQLDB に対して TestNG ユニットテストを実行する場合に、 jboss-beans.xml、 persistence-test.xml、 そして import-test.sql ファイルが使用されます。 import-test.sql 中のデータベーススキーマとテストデータは、 常にテストが実行される前にデータベースにエキスポートされます。 myproject-dev-ds.xml、 persistence-dev.xml そして import-dev.sql ファイルは、 アプリケーションを開発データベースにデプロイするときに使用します。 seam-gen に既存データベースで作業しているかを伝えるかどうかによって、 スキーマはデプロイ時に自動的にエキスポートされる場合があります。 myproject-prod-ds.xml、 persistence-prod.xml そして import-prod.sql ファイルは、 本番環境データベースにアプリケーションをデプロイするときに使用します。 デプロイ時にスキーマは自動的にエキスポートされません。

従来のアクションスタイルの Web フレームワークに慣れている場合、 おそらく、どのように Java のステートレスアクションメソッドで簡単なWebページが生成することができるのだろうかと思われていると思います。 以下のように入力すると、

seam new-action

Seam はなんらかの情報を求めてきます。 そして、 プロジェクト用に新しい facelets page と Seam コンポーネントを生成します。

C:\Projects\jboss-seam>seam new-action ping
Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml

validate-workspace:

validate-project:

action-input:
    [input] Enter the Seam component name
ping
    [input] Enter the local interface name [Ping]

    [input] Enter the bean class name [PingBean]

    [input] Enter the action method name [ping]

    [input] Enter the page name [ping]


setup-filters:

new-action:
     [echo] Creating a new stateless session bean component with an action method
     [copy] Copying 1 file to C:\Projects\hello\src\com\hello
     [copy] Copying 1 file to C:\Projects\hello\src\com\hello
     [copy] Copying 1 file to C:\Projects\hello\src\com\hello\test
     [copy] Copying 1 file to C:\Projects\hello\src\com\hello\test
     [copy] Copying 1 file to C:\Projects\hello\view
     [echo] Type 'seam restart' and go to http://localhost:8080/helloworld/ping.seam

BUILD SUCCESSFUL
Total time: 13 seconds
C:\Projects\jboss-seam>

新しい Seam コンポーネントを追加したので、 展開したディレクトリのデプロイを再起動する必要があります。 seam restart と入力するか、 Eclipse 内から生成されたプロジェクト build.xml ファイル の restart ターゲットを実行することで行うことができます。 再起動を強制する別の方法は、 Eclipse の resources/META-INF/application.xml ファイルを編集することです。 アプリケーションを変更するたびに JBoss を再起動する必要はないことに留意してください。

さあ、http://localhost:8080/helloworld/ping.seam に進んで、クリックボタンを押してください。 プロジェクトの src directory ディレクトリを見れば、このアクションに隠されたコードを見ることができます。 ping() メソッドにブレークポイントを置いて、 クリックボタンを押してください。

最後に、PingTest.xml ファイルを test パッケージに配置し、 Eclipse の TestNG プラグインを使用して統合テストを実行します。 別な方法として、 seam test を使用してテストを起動するか、 生成されたビルドから test ターゲットを起動します。

次のステップは、以下のようにフォームを生成することです。

seam new-form

C:\Projects\jboss-seam>seam new-form
Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml

validate-workspace:

validate-project:

action-input:
    [input] Enter the Seam component name
hello
    [input] Enter the local interface name [Hello]

    [input] Enter the bean class name [HelloBean]

    [input] Enter the action method name [hello]

    [input] Enter the page name [hello]


setup-filters:

new-form:
     [echo] Creating a new stateful session bean component with an action method
     [copy] Copying 1 file to C:\Projects\hello\src\com\hello
     [copy] Copying 1 file to C:\Projects\hello\src\com\hello
     [copy] Copying 1 file to C:\Projects\hello\src\com\hello\test
     [copy] Copying 1 file to C:\Projects\hello\view
     [copy] Copying 1 file to C:\Projects\hello\src\com\hello\test
     [echo] Type 'seam restart' and go to http://localhost:8080/hello/hello.seam

BUILD SUCCESSFUL
Total time: 5 seconds
C:\Projects\jboss-seam>

再びアプリケーションを再起動させ、 http://localhost:8080/helloworld/hello.seam に進みます。 生成されたコードを見てみましょう。 テストを実行します。 何か新しいフィールドをフォームと Seam コンポーネントに追加してみましょう。 (Java コードを変更したら常にデプロイを再起動することを忘れないようにしてください。)

手動でデータベースの中にテーブルを生成します。 (別のデータベースに切り替える必要がある場合はもう一度 seam setup を実行します。) ここで次のように入力します。

seam generate-entities

デプロイを再起動して、 http://localhost:8080/helloworld に進んでください。 データベースの参照、 既存オブジェクトの編集、 新しいオブジェクトの生成が可能です。 生成されたコードを見ると、 おそらくあまりに簡単なのに驚かれたと思います。 Seam はデータアクセスコードが手作業で簡単に記述できるように設計されたからです。 また seam-gen を使用して適当なことを行いたくないユーザーにも適しています。

最後に、 標準の Java EE 5 パッケージングを使用してアプリケーションをデプロイできるようにしたいと思います。 まず、 seam unexplode を実行して展開したディレクトリを削除する必要があります。 EAR をデプロイするには、 コマンドプロンプトで seam deploy を入力する、 あるいは生成されたプロジェクトの build スクリプトの deploy ターゲットを実行します。 seam undeploy または undeploy ターゲットを使うとアンデプロイができます。

デフォルトでは、アプリケーションは dev profile でデプロイされます。 EAR は persistence-dev.xml ファイルと import-dev.sql ファイルを含み、 myproject-dev-ds.xml ファイルがデプロイされます。 プロファイルは変更可能で、 以下のように入力して prod profile を使用します。

seam -Dprofile=prod deploy

アプリケーション用に新しいデプロイメントプロファイルを定義することもできます。 プロジェクトに適切な名前が付いたファイルを追加します — 例えば、 persistence-staging.xml、 import-staging.sql と myproject-staging-ds.xml などです。 -Dprofile=staging を使ってプロファイルの名前を選択します。

展開されたディレクトリで Seam アプリケーションをデプロイする場合、 開発時になんらかの増分ホットデプロイのサポートを受けるでしょう。 components.xml に以下の行を追加することで、 Seam と Facelets の両方でデバッグモードを有効にする必要があります。

<core:init debug="true"/>

以下のファイルは、 Webアプリケーションを完全に再起動することなく置き換えがされるかもしれません。

ただし、 いずれかの Java コードを変更する必要がある場合は、 アプリケーションを完全に再起動する必要があります。 (JBoss では、 トップレベルのデプロイメント記述子に手を入れることで行えるでしょう。 EAR デプロイメントなら application.xml、 WAR デプロイメントなら web.xml です。)

しかし、 早いペースの編集/コンパイル/テストのサイクルを望むならば、 Seam は JavaBean コンポーネントの増分再デプロイメントをサポートしています。 この機能を有効にするためには、 JavaBean コンポーネントを WEB-INF/dev ディレクトリにデプロイする必要があります。 その結果、コンポーネントは WAR あるいは EAR クラスローダではなく、 特殊な Seam クラスローダによってロードされるようになります。

以下の制約を知っている必要があります。

seam-gen を使用して WAR プロジェクトを生成する場合、 増分ホットデプロイメントは、src/action ソースディレクトリにあるクラスにそのまま使用可能です。 しかしならが、 seam-gen は EAR プロジェクトに対する増分ホットデプロイに対応していません。

これまでに見た例は、以下の規則に従う非常に単純な対話モデルを利用します。

Seam は透過的に JSF のポストバックとリダイレクト全体に渡り対話コンテキストを伝播します。 特に何もしなければ、 non-faces リクエスト (例えば、 GETリクエスト) は対話コンテキストを伝播せずに新しいテンポラリの対話内で処理されます。 これが通常 (必ずではないが) 望ましい動作となります。

non-faces リクエスト全体に Seam 対話を伝播させたい場合、 リクエストパラメータとして Seam 対話 ID を明示的にコード化する必要があります。

<a href="main.jsf?conversationId=#{conversation.id}">Continue</a>

JSF のようにする場合には以下のようにします。

<h:outputLink value="main.jsf">
    <f:param name="conversationId" value="#{conversation.id}"/>
    <h:outputText value="Continue"/>
</h:outputLink>

Seam タグライブラリを使用する場合、 以下は等価です。

<h:outputLink value="main.jsf">
    <s:conversationId/>
    <h:outputText value="Continue"/>
</h:outputLink>

ポストバック用の対話コンテキストの伝播を無効にしたい場合は、 同様のテクニックが使えます。

<h:commandLink action="main" value="Exit">
    <f:param name="conversationPropagation" value="none"/>
</h:commandLink>

Seam タグライブラリを使用する場合、 以下は等価です。

<h:commandLink action="main" value="Exit">
    <s:conversationPropagation type="none"/>
</h:commandLink>

対話コンテキストの伝播を無効にすることと、 対話を終了することとは全く異なることですので注意してください。

conversationPropagation リクエストパラメータ または <s:conversationPropagation> タグは、 対話の開始と終了、あるいはネストされた対話の開始にも使用することができます。

<h:commandLink action="main" value="Exit">
    <s:conversationPropagation type="end"/>
</h:commandLink>

<h:commandLink action="main" value="Select Child">
    <s:conversationPropagation type="nested"/>
</h:commandLink>

<h:commandLink action="main" value="Select Hotel">
    <s:conversationPropagation type="begin"/>
</h:commandLink>

<h:commandLink action="main" value="Select Hotel">
    <s:conversationPropagation type="join"/>
</h:commandLink>

この対話モデルは、 マルチウィンドウ操作に関して正常に動作するアプリケーションの構築を容易してくれます。 多くのアプリケーションにとって必要なものはこれだけです。 複雑なアプリケーションのなかには以下の追加要件の両方あるいはどちらかを必要とするものがあります。

ネストされた対話は既存の対話のスコープ内で @@Begin(nested=true) とマークされたメソッドを呼び出すことによって作成されます。 ネストされた対話はそれ自身の対話コンテキストを持っていて、 また、 外側の対話のコンテキストへの読取り専用アクセスも持っています (外側の対話のコンテキスト変数を読むことはできるが、書き込みはできない) 。 次に @End が出てくると、 ネストされた対話は破棄されて外側の対話が対話スタックを「POP」することによって再開します。 対話は任意の深さにネストすることができます。

特定のユーザーアクティビティ (ワークスペース管理や戻るボタン) により、 内側の対話が終了する前に外側の対話が開始させることができます。 この場合、 同じ外側の対話に属する複数の並列ネスト対話を持つことができます。 ネストされた対話が終了する前に外側の対話が終了すると、 Seam はネストされた対話コンテキストを外側のコンテキストと共にすべて破棄します。

対話は継続可能な状態と見なすこともできます。 ネストされた対話により、 ユーザーインタラクションにおける様々なポイントにおいてアプリケーションは一貫した継続可能な状態を捕らえることができるようになります。 従って、 戻るボタンを押すことやワークスペース管理に対して正しい動作を保証します。

TODO: 戻るボタンを押した場合に、 どのようにしてネストされた対話が不正が発生しないよう防止するかを示す例。

通常、 現在ネストされている対話の親となる対話にコンポーネントが存在する場合、 このネストされている対話は同じインスタンスを使用します。ときには、 親となる対話内に存在するコンポーネントインスタンスがその子となる対話からは見えなくなるように、 ネストされるそれぞれの対話内に別々のインスタンスを持たせると便利なことがあります。 コンポーネントに @PerNestedConversation アノテーションを付けるとこれを行うことができます。

ページが non-faces リクエスト (例、 HTTP GET リクエスト) 経由でアクセスされる場合、 JSF は起動されるアクションリスナを全く定義しません。 ユーザーがそのページをブックマークする、あるいは <h:outputLink> からそのページに行き着く場合などに発生します。

ページがアクセスされたら直ちに対話を開始したい場合があります。 JSF アクションメソッドがないため、 アクションに @Begin アノテーションを付けるという普通の方法では問題を解決することができません。

このページが状態をコンテキスト変数にフェッチする必要がある場合、 さらなる問題が発生します。 すでに、2 つの問題解決方法を見てきました。 Seam コンポーネントにその状態が保持される場合、 @Create メソッドでその状態をフェッチできます。 保持されていなければ、 コンテキスト変数に対して @Factory メソッドを定義することができます。

これらのオプションがうまくいかない場合、 Seam では pages.xml ファイルに ページアクション を定義することができます。

<pages>
    <page view-id="/messageList.jsp" action="#{messageManager.list}"/>
    ...
</pages>

ページがレンダリングされるようとするときは常に、 レスポンスのレンダリングフェーズの冒頭でこのアクションメソッドが呼び出されます。 ページアクションが null 以外の結果を返す場合、 Seam は適切な JSF 及び Seam ナビゲーションの規則を処理するので、 まったく異なるページがレンダリングさることになるかもしれません。

ページのレンダリング前に行いたいことが対話の開始だけなら、 ビルトインアクションメソッドを次のように使用できます。

<pages>
    <page view-id="/messageList.jsp" action="#{conversation.begin}"/>
    ...
</pages>

また、 このビルトインアクションは JSF コントロールからも呼び出すことができ、 同様に #{conversation.end} を使って対話を終了することができます。

既存の対話にジョインするあるいはネストされる対話を開始する、 ページフローまたはアトミック対話を開始するためにさらに制御が必要な場合は、 <begin-conversation> エレメントを使用してください。

<pages>
    <page view-id="/messageList.jsp">
       <begin-conversation nested="true" pageflow="AddItem"/>
    <page>
    ...
</pages>

また、 <end-conversation> エレメントもあります。

<pages>
    <page view-id="/home.jsp">
       <end-conversation/>
    <page>
    ...
</pages>

1 番目の問題を解決するには、 現在 5 つのオプションから選択できます。

JSF コマンドリンクは常に JavaScript でフォームサブミットを行います。 これによりウェブブラウザの「新しいウィンドウで開く」または「新しいタブで開く」機能を動作させなくしてしまいます。 プレーンの JFS でこの機能が必要な場合は、 <h:outputLink> を使用する必要があります。 ただし、 <h:outputLink> には重要な制限が 2 つあります。

Seam は 1 番目の問題解決に対しては ページアクションという概念を提供していますが、 これは 2 番目の問題についてはまったく役に立ちません。 これについてはリクエストパラメータを渡すという RESTful 方法を使ってサーバー側にある選択オブジェクトに再問い合わせを行うことで回避できました。 Seam ブログサンプルアプリケーションなどの場合には、 実際にこれが最適の手段となります。 RESTful スタイルはサーバー側の状態を必要としないためブックマーク機能をサポートします。 ブックマークはあまり必要ないなどこれ以外の場合は、 @DataModel および @DataModelSelection を使用すると非常に便利で透過的になります。

この機能を補ってさらに対話伝播の管理をより簡略化するために、 Seam は <s:link> JSF タグを提供しています。

このリンクは JSF ビュー ID だけを指定することができます。

<s:link view=“/login.xhtml” value=“Login”/>

あるいは、 アクションメソッドを指定することができます (この場合、 アクションの結果は最終的なページを確定する)。

<s:link action=“#{login.logout}” value=“Logout”/>

JSF ビュー ID とアクションメソッドの両方を指定すると、 アクションメソッドが null 以外の結果を返さない限り「ビュー」が使用されます。

<s:link view="/loggedOut.xhtml"  action=“#{login.logout}” value=“Logout”/>

リンクは <h:dataTable> 内で使用する DataModel の選択列を自動的に伝播します。

<s:link view=“/hotel.xhtml” action=“#{hotelSearch.selectHotel}” value=“#{hotel.name}”/>

既存の対話のスコープを残しておくことができます。

<s:link view=“/main.xhtml” propagation=“none”/>

対話を開始、 終了、 またはネストすることができます。

<s:link action=“#{issueEditor.viewComment}” propagation=“nest”/>

リンクが対話を開始すると、 使用されるページプローを指定することもできます。

<s:link action=“#{documentEditor.getDocument}” propagation=“begin” 
        pageflow=“EditDocument”/>

jBPM タスクリストを使用する場合の taskInstance 属性です。

<s:link action=“#{documentApproval.approveOrReject}” taskInstance=“#{task}”/>

(上記の例は DVD ストアデモアプリケーションを参照してください。)

最後に、 ボタンとしてレンダリングされる「リンク」が必要な場合は <s:button> を使用します。

<s:button action=“#{login.logout}” value=“Logout”/>

動作に対して成功したか失敗したかをユーザーに示すメッセージを表示するのは非常に一般的です。 これには、 JSF FacesMessage を使うと便利です。 残念ながら、 成功のアクションはブラウザリダイレクトを要することが多く、 JSF はリダイレクト全体に faces のメッセージは伝播しません。 このためプレーン JSF で成功のメッセージを表示するのはかなり困難になります。

ビルトインの対話スコープ Seam コンポーネントである facesMessages がこの問題を解決してくれます。 (Seam リダイレクトフィルタをインストールしておく必要があります。)

@Name("editDocumentAction")
@Stateless
public class EditDocumentBean implements EditDocument {
    @In EntityManager em;
    @In Document document;
    @In FacesMessages facesMessages;
    
    public String update() {
        em.merge(document);
        facesMessages.add("Document updated");
    }
}

facesMessages に追加されるメッセージはすべてすぐ次のフェースであるレスポンスレンダリングフェーズで現在の対話に対して使用されます。 これは Seam がリダイレクト全体に一時的な対話コンテキストを維持するので長期実行の対話がない場合でも機能します。

JSF EL 式を faces メッセージサマリーに含ませることもできます。

facesMessages.add("Document #{document.title} was updated");

たとえば、 通常の方法でメッセージを表示することができます。

<h:messages globalOnly="true"/>

通常、 Seam は各セッション内の各対話に対して特に意味のない固有 ID を生成します。 対話を開始するときに、 この ID 値をカスタマイズすることができます。

この機能を使って対話 ID 生成アルゴリズムをカスタマイズすることができます。

@Begin(id="#{myConversationIdGenerator.nextId}") 
public void editHotel() { ... }

あるいは、 何か意味のある対話 ID を割り当てるのに使うこともできます。

@Begin(id="hotel#{hotel.id}") 
public String editHotel() { ... }

@Begin(id="hotel#{hotelsDataModel.rowData.id}") 
public String selectHotel() { ... }

@Begin(id="entry#{params['blogId']}")
public String viewBlogEntry() { ... }

@BeginTask(id="task#{taskInstance.id}") 
public String approveDocument() { ... }

ご覧のように、 上記の例では、 特定のホテル、ブログ、あるいはタスクが選択される毎に同じ対話 id となります。 既に存在するものと同じ対話 id での対話では何が起こるのでしょうか？ そうです。 Seam は既存の対話を検出し、 @Begin メソッドを再び開始することなくその対話へリダイレクトします。 この特長は、 ワークスペース管理を使用するときに生成されるワークスペースの数を制御する際に役立ちます。

ワークスペース管理は、1 つのウィンドウの中で対話を「切り換える」能力です。 Seam はワークスペース管理を Java コードのレベルで完全に透過的にします。 ワークスペース管理を可能にするために、必要なすべては以下の通りです。

<pages>
    <page view-id="/main.xhtml">Search hotels: #{hotelBooking.searchString}</page>
    <page view-id="/hotel.xhtml">View hotel: #{hotel.name}</page>
    <page view-id="/book.xhtml">Book hotel: #{hotel.name}</page>
    <page view-id="/confirm.xhtml">Confirm: #{booking.description}</page>
</pages>

<pageflow-definition name="shopping">

   <start-state name="start">
      <transition to="browse"/>
   </start-state>
   
   <page name="browse" view-id="/browse.xhtml">
      <description>DVD Search: #{search.searchPattern}</description>
      <transition to="browse"/>
      <transition name="checkout" to="checkout"/>
   </page>
   
   <page name="checkout" view-id="/checkout.xhtml">
      <description>Purchase: $#{cart.total}</description>
      <transition to="checkout"/>
      <transition name="complete" to="complete"/>
   </page>
   
   <page name="complete" view-id="/complete.xhtml">
      <end-conversation />
   </page>
   
</pageflow-definition>

6.7.3. 対話切り替え

次の断片を JSP または facelets のページに含ませて、 現在の対話またはその他いずれのアプリケーションのページにも切り替えられるドロップダウンメニューを取得します。

<h:selectOneMenu value="#{switcher.conversationIdOrOutcome}">
    <f:selectItem itemLabel="Find Issues" itemValue="findIssue"/>
    <f:selectItem itemLabel="Create Issue" itemValue="editIssue"/>
    <f:selectItems value="#{switcher.selectItems}"/>
</h:selectOneMenu>
<h:commandButton action="#{switcher.select}" value="Switch"/>

この例では、 ユーザに新しい対話を開始させる 2 つの追加アイテムに加えて、 各対話のためのアイテムを含むメニューがあります。

6.7.4. 対話一覧

対話一覧は対話切り替えに非常によく似ていますが、 表形式で表示される点が異なります。

<h:dataTable value="#{conversationList}" var="entry"
        rendered="#{not empty conversationList}">
    <h:column>
        <f:facet name="header">Workspace</f:facet>
        <h:commandLink action="#{entry.select}" value="#{entry.description}"/>
        <h:outputText value="[current]" rendered="#{entry.current}"/>
    </h:column>
    <h:column>
        <f:facet name="header">Activity</f:facet>
        <h:outputText value="#{entry.startDatetime}">
            <f:convertDateTime type="time" pattern="hh:mm a"/>
        </h:outputText>
        <h:outputText value=" - "/>
        <h:outputText value="#{entry.lastDatetime}">
            <f:convertDateTime type="time" pattern="hh:mm a"/>
        </h:outputText>
    </h:column>
    <h:column>
        <f:facet name="header">Action</f:facet>
        <h:commandButton action="#{entry.select}" value="#{msg.Switch}"/>
        <h:commandButton action="#{entry.destroy}" value="#{msg.Destroy}"/>
    </h:column>
</h:dataTable>

恐らく、 多くの方が独自のアプリケーションに合うようカスタマイズを希望するだろうと思います。

対話一覧は便利ですが、 ページ上で対話一覧によって占有される領域が多いため、 すべてのページに対しては対話一覧を置きたくないでしょう。

対話一覧によりユーザーがワークスペースを破壊することができるので留意してください。

6.7.5. ブレッドクラム (Breadcrumbs)

ブレッドクラムは、 ネストされた対話モデルを使うアプリケーションで役に立ちます。 ブレッドクラムは、 現在の対話スタック内の対話へのリンクの一覧になります。

<t:dataList value="#{conversationStack}" var="entry">
    <h:outputText value=" | "/> 
    <h:commandLink value="#{entry.description}" action="#{entry.select}"/>
</t:dataList>

JSF は驚いたことにループに対して標準コンポーネントを全く提供していないため、 ここでは、 MyFaces <t:dataList> コンポーネントを使用していることに注意してください。

これらすべての機能が動作しているところを確認するには、 Seam 問題追跡システム (Seam Issue Tracker) デモを参照してください。

重要ではありませんが、 JSF コンポーネントへのバインディングの保持には使用できないという制限が対話型コンポーネントにはあります。 (一般的には、 アプリケーション論理からビューに対する強い依存関係を作ってしまうため、 絶対的に必要でない限り一般的にはこの JSF の機能は使用しないようにした方がよいでしょう。) postback リクエストで、 Seam 対話コンテキストが復元される前、 ビューの復元フェーズ中にコンポーネントのバインディングは更新されます。

これを回避するには、 イベントスコープコンポーネントを使ってコンポーネントバインディングを格納し、 それを必要とする対話スコープコンポーネントにインジェクトします。

@Name("grid")
@Scope(ScopeType.EVENT)
public class Grid
{
    private HtmlPanelGrid htmlPanelGrid;

    // getters and setters
    ...
}

@Name("gridEditor")
@Scope(ScopeType.CONVERSATION)
public class GridEditor
{
    @In(required=false)
    private Grid grid;
    
    ...
}

Seam には、ページフローを定義する 2 つの方法があります。

簡単なアプリケーションでは、ステートレスなナビゲーションモデルで十分です。 とても複雑なアプリケーションは、場所に応じて両方を使用します。 それぞれのモデルは、それぞれの強みも弱みもあります。

7.1.1. 2 つのナビゲーションモデル

ステートレスなモデルは、 一組の名前の付いた論理的なイベントの結果 (outcome) から 直接、結果として生じるビューのマッピングを定義します。 ナビゲーション規則は、どのページがイベントのソースであったかということ以外、 アプリケーションによって保持されたどのような状態も全く気にしません。 これは、アクションリスナメソッドがページフローを決めなければならないことがあることを意味しています。 なぜなら、それらだけがアプリケーションの現在の状態にアクセスできるからです。

これは JSF ナビゲーション規則を使用したページフローの例です。

<navigation-rule>
    <from-view-id>/numberGuess.jsp</from-view-id>
        
    <navigation-case>
        <from-outcome>guess</from-outcome>
        <to-view-id>/numberGuess.jsp</to-view-id>
        <redirect/>
    </navigation-case>

    <navigation-case>
        <from-outcome>win</from-outcome>
        <to-view-id>/win.jsp</to-view-id>
        <redirect/>
    </navigation-case>
        
    <navigation-case>
        <from-outcome>lose</from-outcome>
        <to-view-id>/lose.jsp</to-view-id>
        <redirect/>
    </navigation-case>

</navigation-rule>

これは Seam ナビゲーション規則を使用したページフローの例です。

<page view-id="/numberGuess.jsp">
        
    <navigation>
        <rule if-outcome="guess">
            <redirect view-id="/numberGuess.jsp"/>
        </rule>
        <rule if-outcome="win">
            <redirect view-id="/win.jsp"/>
        </rule>
        <rule if-outcome="lose">
            <redirect view-id="/lose.jsp"/>
        </rule>
    </navigation-case>

</navigation-rule>

ナビゲーション規則が冗長過ぎると考えるならば、 アクションリスナーメソッドから直接、ビューIDを返すことが可能です。

public String guess() {
    if (guess==randomNumber) return "/win.jsp";
    if (++guessCount==maxGuesses) return "/lose.jsp";
    return null;
}

これは、リダイレクトの結果であることに留意ください。 リダイレクト中に使用するパラメータを指定することも可能です。

public String search() {
    return "/searchResults.jsp?searchPattern=#{searchAction.searchPattern}";
}

ステートフルなモデルは、 名前の付いた論理的なアプリケーションの状態間で起こる遷移の組み合わせを定義します。 このモデルでは、jPDL ページフロー定義中に、どのようなユーザインタラクションのフロー表現も可能であり、 インタラクションのフローを全く知らないアクションリスナーメソッドを書くことも可能です。

これは jPDL を使用したページフロー定義の例です。

<pageflow-definition name="numberGuess">
    
   <start-page name="displayGuess" view-id="/numberGuess.jsp">
      <redirect/>
      <transition name="guess" to="evaluateGuess">
      	<action expression="#{numberGuess.guess}" />
      </transition>
   </start-page>
   
   <decision name="evaluateGuess" expression="#{numberGuess.correctGuess}">
      <transition name="true" to="win"/>
      <transition name="false" to="evaluateRemainingGuesses"/>
   </decision>
   
   <decision name="evaluateRemainingGuesses" expression="#{numberGuess.lastGuess}">
      <transition name="true" to="lose"/>
      <transition name="false" to="displayGuess"/>
   </decision>
   
   <page name="win" view-id="/win.jsp">
      <redirect/>
      <end-conversation />
   </page>
   
   <page name="lose" view-id="/lose.jsp">
      <redirect/>
      <end-conversation />
   </page>
   
</pageflow-definition>

ここで、すぐに気づく 2 つのことがあります。

• JSF/Seam ナビゲーション規則は、より 簡単です。 (しかし、これは、根底となる Java コードがより複雑化であるという事実をあいまいにしています。)

• jPDL は、JSP や Java コードを見る必要がなく、 即座に、ユーザインタラクションの理解ができます。

それに加えて、ステートフルモデルは、もっと 制約的 です。 各論理的な状態 (ページフローの各ステップ) に対して他の状態に遷移可能な制約された組み合わせがあります。 ステートレスモデルは、アドホックな モデルです。 それは、アプリケーションではなく、 比較的制約のない、ユーザが次に行きたいところを決めるフリーフォームナビゲーションに適しています。

ステートフル / ステートレスナビゲーションの判断は、 典型的なモーダル / モーダレスインタラクションの考え方ととてもよく似ています。 さて、アプリケーションをモーダルな振る舞いから回避することは、 対話を持つ 1 つの主な理由ですが、 Seam アプリケーションは、 通常、単純な意味でのモーダルではありません。 しかし、Seam アプリケーションは、 特定な対話レベルで、モーダル可能であり、しばしばそうです。 モーダルな振る舞いは、 可能な限り回避したものとして知られています。 ユーザがしたいことの順番を予測することは、とても困難です。 しかし、ステートフルモデルの存在意義があるのは疑う余地はありません。

2 つのモデルの最大の違いは、 戻るボタンの振る舞いです。

<page view-id="/checkout.xhtml" 
        no-conversation-view-id="/main.xhtml"/>

<page name="checkout" 
        view-id="/checkout.xhtml" 
        back="enabled">
    <redirect/>
    <transition to="checkout"/>
    <transition name="complete" to="complete"/>
</page>

<page name="checkout" 
        view-id="/checkout.xhtml" 
        back="enabled" 
        no-conversation-view-id="/main.xhtml">
    <redirect/>
    <transition to="checkout"/>
    <transition name="complete" to="complete"/>
</page>

実際、どちらのナビゲーションモデルも、それにふさわしい場所があります。 いつ、どちらのモデルがふさわしいかは、すぐに理解できるようになります。

ビジネスプロセスは、だれ (who) がタスクを実行することができるか、 いつ (when) タスクを実行すべきかという明確なルールに従って、 ユーザ、あるいは、ソフトウェアのシステムによって実行されなければならない明確なタスクの集合です。 Seam jBPMインテクグレーションは、ユーザにタスクリストを表示し、それらのタスクを管理することを容易にします。 Seam はまた BUSINESS_PROCESS コンテキスト中のビジネスプロセスに関連する、 状態をアプリケーションに保管させ、 jBPM 変数経由でその状態を永続化させます。

<page> の代わりに、<task-node> ノードを持つ以外、 簡単なビジネスプロセス定義はページフロー定義とほぼ同じであるように見えます。 (一貫した原則 (The One Kind of Stuff principle)) 長期間のビジネスプロセスにおいて、 待ち状態は、システムが、ユーザがログインし、タスクを実行するのを待っているところです。

<process-definition name="todo">
   
   <start-state name="start">
      <transition to="todo"/>
   </start-state>
   
   <task-node name="todo">
      <task name="todo" description="#{todoList.description}">
         <assignment actor-id="#{actor.id}"/>
      </task>
      <transition to="done"/>
   </task-node>
   
   <end-state name="done"/>
   
</process-definition>

<core:jbpm>
    <core:process-definitions>
        <value>todo.jpdl.xml</value>
    </core:process-definitions>
</core:jbpm>

@In Actor actor;

public String login() {
    ...
    actor.setId( user.getUserName() );
    actor.getGroupActorIds().addAll( user.getGroupNames() );
    ...
}

@CreateProcess(definition="todo")
public void createTodo() { ... }

<page>
    <create-process definition="todo" />
</page>

<task name="todo" description="#{todoList.description}">
    <assignment actor-id="#{actor.id}"/>
</task>

<task name="todo" description="#{todoList.description}">
    <assignment pooled-actors="employees"/>
</task>

<h:dataTable value="#{pooledTaskInstanceList}" var="task">
    <h:column>
        <f:facet name="header">Description</f:facet>
        <h:outputText value="#{task.description}"/>
    </h:column>
    <h:column>
        <s:link action="#{pooledTask.assignToCurrentActor}" value="Assign" taskInstance="#{task}"/>
    </h:column>            	
</h:dataTable>

<h:commandLink action="#{pooledTask.assignToCurrentActor}"> 
    <f:param name="taskId" value="#{task.id}"/>
</h:commandLink>

<h:dataTable value="#{taskInstanceListForType['todo']}" var="task">
    <h:column>
        <f:facet name="header">Description</f:facet>
        <h:outputText value="#{task.description}"/>
    </h:column>
    <h:column>
        <s:link action="#{todoList.start}" value="Start Work" taskInstance="#{task}"/>
    </h:column>            	
</h:dataTable>

@StartTask
public String start() { ... }

<page>
    <start-task />
</page>

@EndTask(transition="completed")
public String completed() { ... }

<page>
    <end-task transition="completed" />
</page>

複雑なビジネスプロセスの管理を実現する各種の高度な機能の全体的な概要については jBPM ドキュメントを参照してください。

Seam は、 旧世代の Java アプリケーションアーキテクチャの典型であるステートレス性に悩む Hibernate チームのフラストレーションから生まれました。 Seam の状態管理アーキテクチャは元々、 永続性に関する問題の解決を目的として設計されました — 特に楽観的なトランザクションの処理に関連する問題。 スケーラブルなオンラインアプリケーションは常に楽観的なトランザクションを使用します。 微小レベル (データベース／JTA) のトランザクションは、 アプリケーションが並列している極少数のクライアント群のみをサポートするよう設計されていない限り、 ユーザーのインテラクションをスパンしません。 しかし、 目的とするほぼすべての作業はまずユーザーに対するデータの表示に関連し、 次に少し遅れて同じデータの更新に関連してきます。 このため、 Hibernate は楽観的なトランザクションをスパンした永続コンテキストという目的に対応するよう設計されました。

残念ながら、 Seam や EJB 3.0 より以前の「ステートレス」と呼ばれるアーキテクチャには楽観的なトランザクションを表示するための構成概念がありませんでした。 このため、 代わりに微小なトランザクションに対してスコープされる永続コンテキストを提供していました。 当然、 ユーザーにとっては問題が多くなり、 恐怖の LazyInitializationException として Hibernate に関するユーザーからの苦情は最多となりました。 ここで必要なのはアプリケーション層で楽観的トランザクションを表示する構成概念なのです。

EJB 3.0 はこの問題を認識し、 コンポーネントの寿命に対してスコープされる拡張永続コンテキストでステートフルなコンポーネント (ステートフルセッション bean) という目的を導入します。 これは問題に関して完全なソリューションではありませんが (それ自体は便利な構成となる) 、 2 つの問題があります。

Seam は、 対話及び対話に対してスコープされるステートフルセッション bean コンポーネントを提供することにより 1 番目の問題を解決します。 (ほとんどの対話は実際にはデータ層で楽観的トランザクションを表示します。) 永続コンテキストの伝播を必要としないような多くのシンプルなアプリケーション (Seam ブッキングデモなど) にはこれで十分です。 各対話内で軽く作用しあっているコンポーネントを多く持っているようなもう少し複雑なアプリケーションの場合、 コンポーネント群全体への永続コンテキストの伝播は重要な問題となります。 このため、 Seam は EJB 3.0 の永続コンテキスト管理モデルを拡張して対話スコープの拡張永続コンテキストを提供しています。

EJB セッション bean は宣言型トランザクション管理を特長としています。 EJB コンテナは bean が呼び出されると透過的にトランザクションを起動し、 呼出しが終了するとトランザクションも終了させることが可能です。 JSF アクションリスナーとして動作するセッション bean メソッドを記述する場合、 そのアクションに関連するすべての作業を 1 つのトランザクションで行うことができ、 アクションの処理が完了したら必ずコミットまたはロールバックされるようにすることができます。 これは素晴らしい機能であり、 いくつかの Seam アプリケーションに必要とされるものはこれだけです。

ただし、 この方法には問題が 1 つあります。 Seam アプリケーションは単一のメソッドコールからセッション bean へのリクエストに対して全データアクセスを行わない可能性があります。

1 リクエストごとのトランザクション数が多くなると、 使用しているアプリケーションが多くの並列リクエストを処理している際にそれだけ多くの微小で個別の問題に遭遇する可能性が高くなります。 書き込み動作はすべて、 必ず、 同じトランザクション内で起こらなければならないからです。

Hibernate ユーザーはこの問題を回避するため

このパターンは通常、 リクエスト全体にスパンする単一トランザクションとして実装されます。 この実装ではいくつかの問題があります。 もっとも深刻となる問題は、 トランザクションをコミットするまでそれが成功なのかどうか全く確認できないことです — ただし、 「ビュー内のオープンセッション」トランザクションがコミットされるようになると、 ビューは完全にレンダリングされるので、 レンダリングされるレスポンスはすでにクライアントにフラッシュされている場合があります。 ユーザーのトランザクションが成功しなかったことをユーザーに知らせるにはどうしたらよいでしょうか。

Seam はトランザクション個別の問題と関連フェッチの問題の両方を解決しながら、 「ビュー内のオープンセッション」で問題を回避します。 解決法は 2 つに分けられます。

次のセクションでは、 対話スコープの永続コンテキストの設定方法について説明していきますが、 まず最初に Seam トランザクション管理を有効にする方法を説明しておく必要があります。 Seam トランザクション管理なしで対話スコープの永続コンテキストを使用することができ、 また Seam 管理永続コンテキストを使用していない場合でも Seam トランザクション管理を利用すると便利なことがあるので留意しておいてください。 ただし、 この 2 つの機能は連携して動作するよう設計されているため、 併用する方が最適です。

<lifecycle>
     <phase-listener>
        org.jboss.seam.jsf.TransactionalSeamPhaseListener
    </phase-listener>
</lifecycle>

Seam を Java EE 5 環境の外で使用している場合、 コンテナによる永続コンテキストのライフサイクルの管理は期待できません。 EE 5 環境であっても、 単一の対話の範囲内で連携する多くの疎結合コンポーネントを持つ複雑なアプリケーションがあるかもしれず、 この場合にはコンポーネント間での永続コンテキストの伝播が簡単ではなくエラーが発生しやすい場合があります。

いずれの場合では、 コンポーネントで managed persistence context (JPA 用) または managed session (Hibernate 用) のいずれかを使用する必要があります。 Seam 管理永続コンテキストは単純にビルトインの Seam コンポーネントで対話コンテキストで EntityManager または Session のインスタンスを管理します。 @In でインジェクトすることができます。

Seam 管理の永続コンテキストはクラスタ化された環境で非常に効率的です。 EJB 3.0 の仕様はコンテナによるコンテナ管理拡張永続コンテキストの使用を許可しない最適化を Seam は実行することができます。 ノード間の永続コンテキストの状態を複製することなく拡張永続コンテキストの透過的なフェールオーバーをサポートします。 (この見過ごされてしまった点については、 次回の EJB 仕様のリビジョンで修正したいと考えています。)

<core:managed-persistence-context name="bookingDatabase" 
                           auto-create="true"
            persistence-unit-jndi-name="java:/EntityManagerFactories/bookingData"/>

<property name="jboss.entity.manager.factory.jndi.name" 
          value="java:/EntityManagerFactories/bookingData"/>

@In EntityManager bookingDatabase;

<core:hibernate-session-factory name="hibernateSessionFactory"/>

<core:managed-hibernate-session name="bookingDatabase" 
                         auto-create="true"
           session-factory-jndi-name="java:/bookingSessionFactory"/>

<session-factory name="java:/bookingSessionFactory">
    <property name="transaction.flush_before_completion">true</property>
    <property name="connection.release_mode">after_statement</property>
    <property name="transaction.manager_lookup_class">org.hibernate.transaction.JBossTransactionManagerLookup</property>
    <property name="transaction.factory_class">org.hibernate.transaction.JTATransactionFactory</property>
    <property name="connection.datasource">java:/bookingDatasource</property>
    ...
</session-factory>

@In Session bookingDatabase;

@In EntityManager em; //a Seam-managed persistence context

@Begin(flushMode=MANUAL)
public void beginClaimWizard() {
    claim = em.find(Claim.class, claimId);
}

public void addPartyToClaim() {
    Party party = ....;
    claim.addParty(party);
}

@End
public void commitClaim() {
    em.flush();
}

EntityManager インターフェースにより getDelegate() メソッドを介してベンダー固有の API にアクセスすることができます。 必然的に、 Hibernate が最も関心の高いベンダーとなり、 org.hibernate.Session が最も強力となるデリゲートインターフェースになります。 これ以外を使用するのがばかばかしくなるほどです。 偏見無しによいので試してみてください。

ただし、 Hibernate またはそれ以外のものいずれを使用するかに限らず、 いずれは Seam コンポーネントでデリゲートを使用したくなる場合がくるでしょう。 以下にその一例を示します。

@In EntityManager entityManager;

@Create
public void init() {
    ( (Session) entityManager.getDelegate() ).enableFilter("currentVersions");
}

typecast は Java 言語の中でも間違いなく繁雑な構文になるため、 できる限り避けるのが一般的です。 デリゲートで取得する別の方法を次に示します。 まず、 以下の行を components.xml に追加します。

<factory name="session" 
         scope="STATELESS" 
         auto-create="true" 
         value="#{entityManager.delegate}"/>

これでセッションを直接インジェクトできるようになります。

@In Session session;

@Create
public void init() {
    session.enableFilter("currentVersions");
}

Seam 管理の永続コンテキストを使用する場合や @PersistenceContext を使ってコンテナ管理の永続コンテキストをインジェクトする場合、 Seam は EntityManager または Session オブジェクトをプロキシします。 これにより、 EL 式をクエリ文字列内で安全且つ効果的に使用することができるようになります。 たとえば、 次を見てください。

User user = em.createQuery("from User where username=#{user.username}")
         .getSingleResult();

上記の例は、 以下の例と同等になります。

User user = em.createQuery("from User where username=:username")
         .setParameter("username", user.getUsername())
         .getSingleResult();

当然、 次のようには絶対に記述しないでください。

User user = em.createQuery("from User where username=" + user.getUsername()) //BAD!
         .getSingleResult();

(効率が悪く、 SQL インジェクション攻撃に対して脆弱となります。)

Hibernate 固有の斬新な機能が filters になります。 フィルタによりデータベース内のデータ表示に制限を与えることができるようになります。 フィルタについては Hibernate のドキュメントで詳細に説明されています。 ここでは、 フィルタを Seam アプリケーションに統合する簡単な方法を記載しておくのがよいだろうと思います。 特に Seam Application Framework でうまく動作する方法を説明します。

Seam 管理の永続コンテキストには、 EntityManager や Hibernate Session がはじめて作成されたときに有効にされるよう定義されたフィルタの一覧がある場合があります。 (当然、 Hibernate が永続を実現する構成要素である場合にのみ使用できます。)

<core:filter name="regionFilter">
    <core:name>region</core:name>
    <core:parameters>
        <key>regionCode</key>
        <value>#{region.code}</value>
    </core:parameters>
</core:filter>

<core:filter name="currentFilter">
    <core:name>current</core:name>
    <core:parameters>
        <key>date</key>
        <value>#{currentDate}</value>
    </core:parameters>
</core:filter>

<core:managed-persistence-context name="personDatabase"
    persistence-unit-jndi-name="java:/EntityManagerFactories/personDatabase">
    <core:filters>
        <value>#{regionFilter}</value>
        <value>#{currentFilter}</value>
    </core:filters>
</core:managed-persistence-context>

このフレームワークの提供するコンポーネントは、二つの使い方のいずれかで利用することが出来ます。 一つは、他のSeamの組み込みコンポーネントで行っているように、components.xmlでインスタンスを設定して使用する方法です。 下のcomponents.xmlの設定 (部分) ではContactエンティティに対する基本的なCRUD操作をインストールしています。

<framework:entity-home name="personHome" 
                       entity-class="eg.Person" 
                       entity-manager="#{personDatabase}">
    <framework:id>#{param.personId}</framework:id>
</framework:entity-home>

もし、これが「XMLプログラミング」に偏重しているように思えて、好みに合わなければ、代りに機能を拡張して行うことも出来ます。

@Stateful
@Name("personHome")
public class PersonHome extends EntityHome<Person> implements LocalPersonHome {
    @RequestParameter String personId;
    @In EntityManager personDatabase;
    
    public Object getId() { return personId; }
    public EntityManager getEntityManager() { return personDatabase; }
    
}

第二の方法 (機能の拡張を使う) は大きなメリットとして、簡単に拡張したり、内蔵された機能をオーバーライドすることが出来ます。 (このフレームワークの提供するクラスは、拡張や、カスタム化に対応できるよう、注意深く作成されています。)

また、第２のメリットとして、クラスをEJBのステートフルセッションビーンとすることが出来ます。 (必ずEJBにする必要はなく、好みで、プレーンなJavaビーンとすることも出来ます。)

現時点で、Seamアプリケーションフレームワークは、CRUD 用にEntityHome とHibernateEntityHome、それにQueryの為のEntityQuery と HibernateEntityQueryの４つのコンポーネントを提供しています。

HomeとQueryはセッション、イベント、それに対話スコープで機能するように作成されています。 どのスコープを使用するかは、アプリケーションのステートモデルに依存します。

SeamアプリケーションフレームワークはSeamが管理している永続性コンテキストでのみ動作します。 デフォルトで、entityManagerという名前の永続性コンテキストを探します。

Homeオブジェクトは、特定のエンティティクラスに対する永続性操作を提供します。Personクラスについて考えてみましょう。

@Entity
public class Person {
    @Id private Long id;
    private String firstName;
    private String lastName;
    private Country nationality;
    
    //getters and setters...
}

コンフィギュレーションで、下のようにpersonHomeコンポーネントを定義することが出来ます。

<framework:entity-home name="personHome" entity-class="eg.Person" />

また、機能を拡張して下のように、同様のことが出来ます。

@Name("personHome")
public class PersonHome extends EntityHome<Person> {}

Homeオブジェクトはpersist()、 remove()、 update() それに getInstance() の 4 つの操作を提供します。

HomeはJSFページから、下のように直接利用することが出来ます。

<h1>Create Person</h1>
<h:form>
    <div>First name: <h:inputText value="#{personHome.instance.firstName}"/></div>
    <div>Last name: <h:inputText value="#{personHome.instance.lastName}"/></div>
    <div>
        <h:commandButton value="Create Person" action="#{personHome.persist}"/>
    </div>
</h:form>

通常、Personはpersonで参照出来た方が便利ですので、components.xmlに下のように一行加えて、そのようにしましょう。

<factory name="person" 
         value="#{personHome.instance}"/>

<framework:entity-home name="personHome" 
                       entity-class="eg.Person" />

(コンフィギュレーションを使用している場合、) PersonHome に @Factory を追加します。

@Name("personHome")
public class PersonHome extends EntityHome<Person> {
    
    @Factory("person")
    public Person initPerson() { return getInstance(); }
    
}

(機能を拡張している場合) これで、下のように JSF ページの記述が簡単になります。

<h1>Create Person</h1>
<h:form>
    <div>First name: <h:inputText value="#{person.firstName}"/></div>
    <div>Last name: <h:inputText value="#{person.lastName}"/></div>
    <div>
        <h:commandButton value="Create Person" action="#{personHome.persist}"/>
    </div>
</h:form>

これで、Personの新しいエントリーを作成することが出来るようになります。 はい、これで全てです。 次に、表示、更新、それに削除機能を既存のデータ−ベースの Personエントリー操作に追加するためには、PersonHomeに対象のエントリーを特定する識別子を伝える必要があります。 下のように、ページパラメータを使って、これを行います。

<pages>
    <page view-id="/editPerson.jsp">
        <param name="personId" value="#{personHome.id}"/>
    </page>
</pages>

これで、JSFページにこれらの機能を追加することが出来ます。

<h1>
    <h:outputText rendered="#{!personHome.managed}" value="Create Person"/>
    <h:outputText rendered="#{personHome.managed}" value="Edit Person"/>
</h1>
<h:form>
    <div>First name: <h:inputText value="#{person.firstName}"/></div>
    <div>Last name: <h:inputText value="#{person.lastName}"/></div>
    <div>
        <h:commandButton value="Create Person" action="#{personHome.persist}" rendered="#{!personHome.managed}"/>
        <h:commandButton value="Update Person" action="#{personHome.update}" rendered="#{personHome.managed}"/>
        <h:commandButton value="Delete Person" action="#{personHome.remove}" rendered="#{personHome.managed}"/>
    </div>
</h:form>

リクエストパラメータ無しでページにリンクした場合、「Person作成」としてページが表示され、personId をリクエストパラメータとして渡した場合には、「Person編集」としてページが表示されます。

Personをその国籍を初期化して作成しなければならない場合を考えてみましょう。これも簡単に出来ます。 コンフィギュレーションを使う場合は；

<factory name="person" 
         value="#{personHome.instance}"/>

<framework:entity-home name="personHome" 
                       entity-class="eg.Person" 
                       new-instance="#{newPerson}"/>

<component name="newPerson" 
           class="eg.Person">
    <property name="nationality">#{country}</property>
</component>

また、機能を拡張して行う場合は下の様になります。

@Name("personHome")
public class PersonHome extends EntityHome<Person> {
    
    @In Country country;
    
    @Factory("person")
    public Person initPerson() { return getInstance(); }
    
    protected Person createInstance() {
        return new Person(country);
    }
    
}

勿論、Countryオブジェクトは、例えばCountryHomeというHomeオブジェクトの管理下のオブジェクトとすることも出来ます。

アソシエーションの管理など、 より洗練された操作を実現するのも PersonHome にメソッドを追加するだけで出来るようになります。

@Name("personHome")
public class PersonHome extends EntityHome<Person> {
    
    @In Country country;
    
    @Factory("person")
    public Person initPerson() { return getInstance(); }
    
    protected Person createInstance() {
        return new Person(country);
    }
    
    public void migrate()
    {
        getInstance().setCountry(country);
        update();
    }
    
}

Homeオブジェクトは操作が成功したときに自動的にフェースメッセージを表示します。 これを、カスタマイズするには、下のようにコンフィギュレーションを設定します。

<factory name="person" 
         value="#{personHome.instance}"/>

<framework:entity-home name="personHome"
                       entity-class="eg.Person"
                       new-instance="#{newPerson}">
    <framework:created-message>New person #{person.firstName} #{person.lastName} created</framework:created-message>
    <framework:deleted-message>Person #{person.firstName} #{person.lastName} deleted</framework:deleted-message>
    <framework:updated-message>Person #{person.firstName} #{person.lastName} updated</framework:updated-message>
</framework:entity-home>

<component name="newPerson" 
           class="eg.Person">
    <property name="nationality">#{country}</property>
</component>

あるいは、機能を拡張して下のようにすることも出来ます。

@Name("personHome")
public class PersonHome extends EntityHome<Person> {
    
    @In Country country;
    
    @Factory("person")
    public Person initPerson() { return getInstance(); }
    
    protected Person createInstance() {
        return new Person(country);
    }
    
    protected String getCreatedMessage() { return "New person #{person.firstName} #{person.lastName} created"; }
    protected String getUpdatedMessage() { return "Person #{person.firstName} #{person.lastName} updated"; }
    protected String getDeletedMessage() { return "Person #{person.firstName} #{person.lastName} deleted"; }
    
}

しかし、メッセージ定義における最良の方法は (デフォルトで messages という名前の) Seam に対して既知のリソースバンドルに定義することでしょう。

Person_created=New person #{person.firstName} #{person.lastName} created
Person_deleted=Person #{person.firstName} #{person.lastName} deleted
Person_updated=Person #{person.firstName} #{person.lastName} updated

この方法を使えば、国際化に対応することが出来ますし、コードやコンフィギュレーションファイルとプレゼンテーション層とを切り離すことが出来ます。

最後のステップは<s:validateAll> と<s:decorate>を使って、ページにバリデーション機能を追加することですが、これは皆さんへの宿題としておきましょう。

データベース中のPersonの全てのインスタンスのリストが必要な場合、Queryオブジェクトを使って、下のようにすることが出来ます。

<framework:entity-query name="people" 
                        ejbql="select p from Person p"/>

また、これ (この結果) をJSFページから使うことが出来ます。

<h1>List of people</h1>
<h:dataTable value="#{people.resultList}" var="person">
    <h:column>
        <s:link view="/editPerson.jsp" value="#{person.firstName} #{person.lastName}">
            <f:param name="personId" value="#{person.id}"/>
        </s:link>
    </h:column>
</h:dataTable>

量の多いページを処理する為にページングも必要でしょう。

<framework:entity-query name="people" 
                        ejbql="select p from Person p" 
                        order="lastName" 
                        max-results="20"/>

表示するページを決める為にページパラメータを使います。

<pages>
    <page view-id="/searchPerson.jsp">
        <param name="firstResult" value="#{people.firstResult}"/>
    </page>
</pages>

ページングを管理するJSFのコードは若干繁雑ですが、許容範囲内です。

<h1>Search for people</h1>
<h:dataTable value="#{people.resultList}" var="person">
    <h:column>
        <s:link view="/editPerson.jsp" value="#{person.firstName} #{person.lastName}">
            <f:param name="personId" value="#{person.id}"/>
        </s:link>
    </h:column>
</h:dataTable>

<s:link view="/search.xhtml" rendered="#{people.previousExists}" value="First Page">
    <f:param name="firstResult" value="0"/>
</s:link>

<s:link view="/search.xhtml" rendered="#{people.previousExists}" value="Previous Page">
    <f:param name="firstResult" value="#{people.previousFirstResult}"/>
</s:link>

<s:link view="/search.xhtml" rendered="#{people.nextExists}" value="Next Page">
    <f:param name="firstResult" value="#{people.nextFirstResult}"/>
</s:link>

<s:link view="/search.xhtml" rendered="#{people.nextExists}" value="Last Page">
    <f:param name="firstResult" value="#{people.lastFirstResult}"/>
</s:link>

実用的な検索スクリーンでは、絞りこんだ検索結果を得るために、多くの検索のクライテリアをユーザに入力してもらう必要があります。 この重要なユースケースをサポートする為に、Queryオブジェクトはオプションとして制約を設定することが出来ます。

<component name="examplePerson" class="Person"/>
        
<framework:entity-query name="people" 
                        ejbql="select p from Person p" 
                        order="lastName" 
                        max-results="20">
    <framework:restrictions>
        <value>lower(firstName) like lower( #{examplePerson.firstName} + '%' )</value>
        <value>lower(lastName) like lower( #{examplePerson.lastName} + '%' )</value>
    </framework:restrictions>
</framework:entity-query>

上記の例ではexampleオブジェクトの使用について留意してください。

<h1>Search for people</h1>
<h:form>
    <div>First name: <h:inputText value="#{examplePerson.firstName}"/></div>
    <div>Last name: <h:inputText value="#{examplePerson.lastName}"/></div>
    <div><h:commandButton value="Search" action="/search.jsp"/></div>
</h:form>

<h:dataTable value="#{people.resultList}" var="person">
    <h:column>
        <s:link view="/editPerson.jsp" value="#{person.firstName} #{person.lastName}">
            <f:param name="personId" value="#{person.id}"/>
        </s:link>
    </h:column>
</h:dataTable>

ここの例ではコンフィギュレーションによる再利用を示していますが、Queryオブジェクトの再利用は機能を拡張して行う事も同様に可能です。

Seamアプリケーションフレームワークのオプショナルなクラスとして、Controllerと、そのサブクラスとして、 EntityController、 HibernateEntityController とBusinessProcessControllerがあります。 これらのクラスは、一般に利用されるコンポーネントのメソッドに対する、少し便利なアクセス方法を提供しています。 これらは、新しいユーザがSeamに組み込まれた豊富な機能を探検するための出発点を提供し、また若干のコード量の削減に貢献します。

例として、SeamのRegistrationの例のRegisterActionをSeamアプリケーションフレームワークで書き直すと以下のようになります。

@Stateless
@Name("register")
public class RegisterAction extends EntityController implements Register
{

   @In private User user;
   
   public String register()
   {
      List existing = createQuery("select u.username from User u where u.username=:username")
         .setParameter("username", user.getUsername())
         .getResultList();
      
      if ( existing.size()==0 )
      {
         persist(user);
         info("Registered new user #{user.username}");
         return "/registered.jspx";
      }
      else
      {
         addFacesMessage("User #{user.username} already exists");
         return null;
      }
   }

}

ご覧のように、びっくりするような改善にはなりません、、、。

最初のステップは、Seam コンテキスト変数で org.drools.RuleBase インスタンスを有効化することです。 多くのルール駆動型アプリケーションでは、 ルールは、動的にデプロイ可能である必要があります。 従って、ルールのデプロイと Seam での有効化を可能とするソリューションを実装する必要があるでしょう。 (将来版の Drools は、この問題を解決するルールサーバを提供するでしょう。) テスト目的で、Seam はクラスパスから静的なルール一式をコンパイルする、組み込みコンポーネントを提供しています。 このコンポーネントは、components.xml によりインストール可能です。

<drools:rule-base name="policyPricingRules">
    <drools:rule-files>
        <value>policyPricingRules</value>
    </drools:rule-files>
</drools:rule-base>

このコンポーネントは、.drl ファイル一式からルールをコンパイルし、 Seam アプリケーションコンテキスト中に org.drools.RuleBase をキャッシュします。 複数のルールベースをルール駆動型アプリケーションにインストールする必要もあり得ることに留意してください。

Drools DSLを利用するのであれば、DSL定義を指定しなければなりません:

<drools:rule-base name="policyPricingRules" dsl-file="policyPricing.dsl">
    <drools:rule-files>
        <value>policyPricingRules</value>
    </drools:rule-files>
</drools:rule-base>

次に、各対話に対して org.drools.WorkingMemory インスタンスを有効化する必要があります。 (各 WorkingMemory は、現在の対話に関連する fact を蓄積します。)

<drools:managed-working-memory name="policyPricingWorkingMemory" auto-create="true" rule-base="#{policyPricingRules}"/>

policyPricingWorkingMemory に、 ruleBase 設定プロパティにより、 ルールベースへの参照を与えていることに留意してください。

WorkingMemory を、 任意の Seam コンポーネントにインジェクトし、 fact をアサートし、そしてルールを実行することができます。

@In WorkingMemory policyPricingWorkingMemory;

@In Policy policy;
@In Customer customer;

public void pricePolicy() throws FactException
{
    policyPricingWorkingMemory.assertObject(policy);
    policyPricingWorkingMemory.assertObject(customer);
    policyPricingWorkingMemory.fireAllRules();
}

ルールベースが jBPM アクションハンドラとして、あるいはデシジョンハンドラ、割り当てハンドラなどとして動作するようにさせることも可能です — ページフローまたはビジネスプロセス定義のどちらでも可。

<decision name="approval">
         
    <handler class="org.jboss.seam.drools.DroolsDecisionHandler">
        <workingMemoryName>orderApprovalRulesWorkingMemory</workingMemoryName>
        <assertObjects>
            <element>#{customer}</element>
            <element>#{order}</element>
            <element>#{order.lineItems}</element>
        </assertObjects>
    </handler>
    
    <transition name="approved" to="ship">
        <action class="org.jboss.seam.drools.DroolsActionHandler">
            <workingMemoryName>shippingRulesWorkingMemory</workingMemoryName>
            <assertObjects>
                <element>#{customer}</element>
                <element>#{order}</element>
                <element>#{order.lineItems}</element>
            </assertObjects>
        </action>
    </transition>
    
    <transition name="rejected" to="cancelled"/>
    
</decision>

<assertObjects> 要素は、 WorkingMemory 中に、fact としてアサーションされるオブジェクト、 または、オブジェクトのコレクションを返す EL 式を指定します。

jBPM タスク割り当てのために Drools の使用もサポートしています。

<task-node name="review">
    <task name="review" description="Review Order">
        <assignment handler="org.jboss.seam.drools.DroolsAssignmentHandler">
            <workingMemoryName>orderApprovalRulesWorkingMemory</workingMemoryName>
            <assertObjects>
                <element>#{actor}</element>
                <element>#{customer}</element>
                <element>#{order}</element>
                <element>#{order.lineItems}</element>
            </assertObjects>
        </assignment>
    </task>
    <transition name="rejected" to="cancelled"/>
    <transition name="approved" to="approved"/>
</task-node>

あるオブジェクトは、ルールでは Drools グローバルとして扱われます。 すなわち、 jBPM Assignable は assignable として 、 そしてSeam Decision オブジェクトは decision として扱われます。 デシジョンを扱うルールは、デシジョンの結果を決定するために、 decision.setOutcome("result") を呼ぶ必要があります。 割り当てを実行するルールは、 Assignable を使ってアクターIDを設定する必要があります。

package org.jboss.seam.examples.shop

import org.jboss.seam.drools.Decision

global Decision decision

rule "Approve Order For Loyal Customer"
  when
    Customer( loyaltyStatus == "GOLD" )
    Order( totalAmount <= 10000 )
  then
    decision.setOutcome("approved");
end

package org.jboss.seam.examples.shop

import org.jbpm.taskmgmt.exe.Assignable

global Assignable assignable

rule "Assign Review For Small Order"
  when
    Order( totalAmount <= 100 )
  then
    assignable.setPooledActors( new String[] {"reviewers"} );
end

各ユーザログインのセッションは、 java.util.Locale インスタンスと関連しています。 (アプリケーションでは、 locale という名前の セッションスコープのコンポーネントとして扱えます ) 通常の環境では、 ロケールのための特別な設定は不要です。 Seam ではアクティブはロケールの決定は単純に JSF に委譲しています。

Seam 設定プロパティによるマニュアルでロケールの設定が 可能 です。 ( org.jboss.seam.core.localeSelector.language、 org.jboss.seam.core.localeSelector.country、 そして、org.jboss.seam.core.localeSelector.variant ) でも、これを行う妥当な理由は考え付きません。

しかし、アプリケーションユーザインタフェースを介して、 ユーザにマニュアルでロケール設定を可能とさせることは有用です。 Seam は上記のアルゴリズムによって決定されるロケールをオーバライドする組み込み機能も提供しています。 すべきことは、JSP または、Facelet ページのフォームに以下の断片を追加するだけです。

<h:selectOneMenu value="#{localeSelector.language}">
    <f:selectItem itemLabel="English" itemValue="en"/>
    <f:selectItem itemLabel="Deutsch" itemValue="de"/>
    <f:selectItem itemLabel="Francais" itemValue="fr"/>
</h:selectOneMenu>
<h:commandButton action="#{localeSelector.select}" value="#{messages['ChangeLanguage']}"/>

あるいは、faces-config.xml に対応されたすべてのロケールの組み合わせが欲しければ、 以下を使ってください。

<h:selectOneMenu value="#{localeSelector.localeString}">
    <f:selectItems value="#{localeSelector.supportedLocales}"/>
</h:selectOneMenu>
<h:commandButton action="#{localeSelector.select}" value="#{messages['ChangeLanguage']}"/>

これを使用してドロップダウンからアイテムを選択し、ボタンをクリックすれば、 その後のセッションの期間、Seam と JSF のロケールはオーバライドされます。

JSF は、ユーザインタフェースのラベルや説明用テキストの国際化を、 <f:loadBundle /> を使用によって対応しています。 Seam アプリケーションでもこのアプローチが使用可能です。 別途、組み込みの EL 式を利用したテンプレート化されたラベルを表示するために、 Seam メッセージ コンポーネントを利用することも可能です。

Hello=Hello

Hello=G'day

<core:resource-bundle>
    <core:bundle-names>
        <value>mycompany_messages</value>
        <value>standard_messages</value>       
    </core:bundle-names>
</core:resource-bundle>

<page view-id="/welcome/hello.jsp" bundle="HelloMessages"/>

<h:outputText value="#{messages['Hello']}"/>

<h:outputText value="#{messages.Hello}"/>

Hello=Hello, #{user.firstName} #{user.lastName}

Hello=G'day, #{user.firstName}

@In private Map<String, String> messages;

@In("#{messages['Hello']}") private String helloMessage;

@Name("hello")
@Stateless
public class HelloBean implements Hello {
    @In FacesMessages facesMessages;
    
    public String sayIt() {
        facesMessages.addFromResourceBundle("Hello");
    }
}

org.jboss.seam.core.timezone という名の セッションスコープの java.util.Timezone インスタンスと、 org.jboss.seam.core.timezoneSelector という名の タイムゾーン変更のためのSeamコンポーネントもあります。 デフォルトではタイムゾーンはサーバのデフォルトタイムゾーンです。 あいにくJSF仕様では、 <f:convertDateTime>を使って明示的にタイムゾーンを指定しない限り、 全ての日付と時刻はUTCであると想定され、UTCとして表示されます。 これは非常に不便なデフォルト動作です。

Seamはこの動作をオーバーライドし、全ての日付と時刻をデフォルトでSeamタイムゾーンにします。 さらにSeamは、Seamタイムゾーンにおける変換をいつでも行えるよう、 <s:convertDateTime> タグを提供します。

Seamアプリケーションはまた、とても簡単にスキン変更ができます。 テーマAPIはローカライゼーションAPIにとても似ていますが、 もちろんこれら２つの関心事は直交しており、 ローカライゼーションとテーマの両方をサポートするアプリケーションもあります。

まず、サポートされるテーマのセットを設定します:

<theme:theme-selector cookie-enabled="true">
    <theme:available-themes>
        <value>default</value>
        <value>accessible</value>
        <value>printable</value>
    </theme:available-themes>
</theme:theme-selector>

最初にリストされたテーマがデフォルトテーマであることに注意してください。

テーマは、テーマと同じ名前でプロパティファイルに定義されます。 例えば、 default テーマは default.properties に一連のエントリとして定義されます。 例えば、default.properties は以下のように定義します:

css ../screen.css
template template.xhtml

通常、 テーマリソースバンドルのエントリは CSS スタイルや画像へのパスや facelet テンプレートの名前になるでしょう (通常はテキストであるローカライゼーションリソースバンドルとは違って)。

これでJSPやfaceletページにおいてこれらのエントリを使えます。 例えば、faceletページでスタイルシートを適用するには:

<link href="#{theme.css}" rel="stylesheet" type="text/css" />

最も強力な使い方として、 faceletでは <ui:composition> によってテンプレートを適用できます。

<ui:composition xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:f="http://java.sun.com/jsf/core"
    template="#{theme.template}">

ちょうどロケールセレクタのように、 ユーザが自由にテーマを変更できるよう、組み込みのテーマセレクタがあります。

<h:selectOneMenu value="#{themeSelector.theme}">
    <f:selectItems value="#{themeSelector.themes}"/>
</h:selectOneMenu>
<h:commandButton action="#{themeSelector.select}" value="Select Theme"/>

ロケールセレクタ、テーマセレクタ、タイムゾーンセレクタは全て、 ロケールとテーマ設定をクッキーに永続化することをサポートしています。 単に cookie-enabled プロパティを設定してください。

<theme:theme-selector cookie-enabled="true">
    <theme:available-themes>
        <value>default</value>
        <value>accessible</value>
        <value>printable</value>
    </theme:available-themes>
</theme:theme-selector>

<core:locale-selector cookie-enabled="true"/>

シンプルな例:

It's easy to make *bold text*, /italic text/, |monospace|, 
~deleted text~, super^scripts^ or _underlines_.

これを <s:formattedText/> で表示させると、 以下のHTMLが生成されます:

<p>
It's easy to make <b>bold text</b>, <i>italic text</i>, <tt>monospace</tt>
<del>deleted text</del>, super<sup>scripts</sup> or <u>underlines</u>.
</p>

空行は新しいパラグラフを作成するときに使用します。 また、+ は見出しに使用します:

+This is a big heading
You /must/ have some text following a heading!
 
++This is a smaller heading
This is the first paragraph. We can split it across multiple 
lines, but we must end it with a blank line.

This is the second paragraph.

(段落内の改行は単に無視されます。 新しい段落としてテキストを記述したい場合は空行が必要なことを忘れないでください。) これが結果の HTML です:

<h1>This is a big heading</h1>
<p>
You <i>must</i> have some text following a heading!
</p>
 
<h2>This is a smaller heading</h2>
<p>
This is the first paragraph. We can split it across multiple 
lines, but we must end it with a blank line.
</p>

<p>
This is the second paragraph.
</p>

順序付きリストは # 文字で作成できます。順序なしリストは = 文字を使います:

An ordered list:
        
#first item
#second item
#and even the /third/ item

An unordered list:

=an item
=another item

<p>
An ordered list:
</p>
 
<ol>       
<li>first item</li>
<li>second item</li>
<li>and even the <i>third</i> item</li>
</ol>

<p>
An unordered list:
</p>

<ul>
<li>an item</li>
<li>another item</li>
</ul>

引用ブロックはダブルクオートで囲む必要があります:

The other guy said:
        
"Nyeah nyeah-nee 
/nyeah/ nyeah!"

But what do you think he means by "nyeah-nee"?

<p>
The other guy said:
</p>
        
<q>Nyeah nyeah-nee
<i>nyeah</i> nyeah!</q>

<p>
But what do you think he means by <q>nyeah-nee</q>?
</p>

*, |, # などの特殊文字や、<, >, & などのHTMLで利用される文字は \ でエスケープします:

You can write down equations like 2\*3\=6 and HTML tags
like \<body\> using the escape character: \\.

<p>
You can write down equations like 2*3=6 and HTML tags
like &lt;body&gt; using the escape character: \.
</p>

また、 バックティック (`) を使ってコードのブロックを囲むことができます。

My code doesn't work:

`for (int i=0; i<100; i--)
{
    doSomething();
}`

Any ideas?

<p>
My code doesn't work:
</p>

<pre>for (int i=0; i&lt;100; i--)
{
    doSomething();
}</pre>

<p>
Any ideas?
</p>

リンクを作るには以下の構文を利用します:

Go to the Seam website at [=>http://jboss.com/products/seam].

または、リンクテキストを指定したい場合:

Go to [the Seam website=>http://jboss.com/products/seam].

上級者向けですが、この構文を利用したwikiワードのリンクを解釈できるようSeam Textパーサをカスタマイズすることも可能です。

テキストには限定されたHTMLのサブセットを含めることが出来ます (心配しないでください、 クロスサイトスクリプティング攻撃には利用できないようなサブセットを選んでいます)。 これはリンクを作成する際などに便利です。

You might want to link to <a href="http://jboss.com/products/seam">something
cool</a>, or even include an image: <img src="/logo.jpg"/>

テーブルも作れます:

<table>
    <tr><td>First name:</td><td>Gavin</td></tr>
    <tr><td>Last name:</td><td>King</td></tr>
</table>

あなたがやろうと思えば他にもいろいろできるでしょう!

iText サポートは jboss-seam-pdf.jar で提供されます。 この JAR には、 PDF にレンダリングが可能となるビューの作成に使用される iText JSF 制御、 およびレンダリングされたドキュメントをユーザーに提供する DocumentStore コンポーネントが含まれています。 PDF サポートをご使用のアプリケーションに含ませるには、 iText JAR ファイルと一緒に WEB-INF/lib ディレクトリに jboss-seam-pdf.jar を含ませます。 Seam の iText サポートを使用するのに必要な設定はこれだけで他にはありません。

Seam iText モジュールにはビューテクノロジーとして Facelets を使用する必要があります。 ライブラリの今後のバージョンは JSP の使用にも対応する可能性があります。 また、 seam-ui パッケージの使用も必要となります。

examples/itext プロジェクトには実行可能なデモ用 PDF サポートのサンプルが含まれています。 正確なパッケージ化の導入を行い、 現在サポートされている PDF 生成の主要な機能を実際に示すサンプルがいくつか含まれています。

ドキュメントは http://jboss.com/products/seam/pdf 名前空間にあるタグを使って facelets documents で生成されます。 ドキュメントには必ずドキュメントの root に document タグがなければなりません。 document タグは Seam がドキュメントを DocumentStore に生成し HTML リダイレクトをその格納コンテントにレンダリングする準備を行います。 次は 1 行のみのテキストから成る小規模の PDF ドキュメントです。

<p:document xmlns:p="http://jboss.com/products/seam/pdf">                                                      
   The document goes here.                                                                                             
</p:document>
        

役に立つドキュメントにはテキスト以外のものも含まれる必要があります。 ただし、 標準 UI コンポーネントは HTML 生成に対して適合されるので、 PDF コンテントの生成には役に立ちません。 Seam は特殊な UI コンポーネントを適切な PDF コンテントの生成に対して提供しています。 <p:image> や <p:paragraph> のようなタグはシンプルなドキュメントのベーシックな基盤となります。 <p:font> のようなタグはその回りのコンテントすべてに対してスタイル情報を提供します。

<p:document xmlns:p="http://jboss.com/products/seam/pdf"> 
    <p:image alignment="right" wrap="true" resource="/logo.jpg" />
    <p:font size="24">
        <p:paragraph spacingAfter="50">My First Document</p:paragraph>
    </p:font>

    <p:paragraph alignment="justify">
        This is a simple document.  It isn't very fancy.
    </p:paragraph>
</p:document>
        

<p:paragraph>
    The item costs <p:text value="#{product.price}">
        <f:convertNumber type="currency" currencySymbol="$"/>
    </p:text>
</p:paragraph>
            

<p:image resource="/jboss.jpg" />

<p:image imageData="#{images.chart}" />

生成されるドキュメントが本または論文の構造をとる場合、 p:chapter と p:section の各タグを使用して必要となる構造を構成することができます。 セクションは章の内側でのみ使用できますが、 適宜、 ネストさせることができます。 ほとんどの PDF ビューワはドキュメント内の章とセクション間を簡単に移動できる機能を提供しています。

<p:document xmlns:p="http://jboss.com/products/seam/pdf"
            title="Hello">

   <p:chapter number="1">
      <p:title><p:paragraph>Hello</p:paragraph></p:title>
      <p:paragraph>Hello #{user.name}!</p:paragraph>
   </p:chapter>

   <p:chapter number="2">
      <p:title><p:paragraph>Goodbye</p:paragraph></p:title>
      <p:paragraph>Goodbye #{user.name}.</p:paragraph>
   </p:chapter>

</p:document>    
        

一覧の構成は p:list と p:listItem のタグを使って表示させることができます。 一覧には適宜、 ネストされたサブリストを含ませることもできます。 一覧のアイテムは一覧の外側では使用できません。 次のドキュメントは ui:repeat タグを使って Seam コンポーネントから取得した値の一覧を表示しています。

<p:document xmlns:p="http://jboss.com/products/seam/pdf"
            xmlns:ui="http://java.sun.com/jsf/facelets"
            title="Hello">
   <p:list style="numbered">
      <ui:repeat value="#{documents}" var="doc">
         <p:listItem>#{doc.name}</p:listItem>
      </ui:repeat>
   </p:list>
</p:document>                
        

表の構成は p:table と p:cell のタグを使って作成することができます。 多くの表構成とは異なり明示的な列の宣言はありません。 表にコラムが 3 つある場合は、 3 セルすべてが自動的に列を形成します。 表の構成が複数ページに渡る場合、 ヘッダとフッタは繰り返されます。

<p:document xmlns:p="http://jboss.com/products/seam/pdf"   
            xmlns:ui="http://java.sun.com/jsf/facelets"
            title="Hello">   
   <p:table columns="3" headerRows="1">
      <p:cell>name</p:cell>
      <p:cell>owner</p:cell>
      <p:cell>size</p:cell>
      <ui:repeat value="#{documents}" var="doc">
         <p:cell>#{doc.name}</p:cell>
         <p:cell>#{doc.user.name}</p:cell>
         <p:cell>#{doc.size}</p:cell>
      </ui:repeat>
   </p:table>
</p:document>            
        

本セクションでは複数のタグで属性により共有される定数のいくつか説明します。

ドキュメントの生成は特に設定を必要とすることなく、 そのまま動作させることができます。 ただし、 本格的なアプリケーションには必要となる設定ポイントがいくつかあります。

デフォルトの実装は汎用 URL /seam-doc.seam から PDF ドキュメントを提供します。 多くのブラウザ (そしてユーザー) は、 /myDocument.pdf などのように実際の PDF 名を含む URL を好みます。 これにはいくつか設定が必要になってきます。 PDF ファイルを提供するには、 すべての *.pdf リソースが Seam Servlet Filter および DocumentStoreServlet にマッピングされなければなりません。

<filter>
    <filter-name>Seam Servlet Filter</filter-name>
    <filter-class>org.jboss.seam.servlet.SeamServletFilter</filter-class>
</filter>

<filter-mapping>
    <filter-name>Seam Servlet Filter</filter-name>
    <url-pattern>*.pdf</url-pattern>
</filter-mapping>

<servlet>
    <servlet-name>Document Store Servlet</servlet-name>
    <servlet-class>org.jboss.seam.pdf.DocumentStoreServlet</servlet-class>
</servlet>

<servlet-mapping>
    <servlet-name>Document Store Servlet</servlet-name>
    <url-pattern>*.pdf</url-pattern>
</servlet-mapping>

document store コンポーネントにある useExtensions オプションは、 document store に生成されているドキュメントタイプに対して正しいファイル名の拡張子を付けて URL を生成するよう指示することによりこの機能を補います。

        
<components xmlns="http://jboss.com/products/seam/components"
            xmlns:pdf="http://jboss.com/products/seam/pdf">
    <pdf:documentStore useExtensions="true" />
</components>

生成されるドキュメントは対話スコープに格納され、 対話が終了するときに期限が切れます。 この時点で、 ドキュメントへの参照は無効になります。 ドキュメントが存在しない場合、 documentStore の errorPage プロパティを使って表示されるデフォルトのビューを指定できます。

        
<pdf:documentStore useExtensions="true" errorPage="/pdfMissing.seam" />

iText に関する詳細は、 次を参照してください。

Seam Mail を使うためにテンプレート作成用の新しい言語を丸ごと学ぶ必要はありません — email は単純に facelet になります。

<m:message xmlns="http://www.w3.org/1999/xhtml"
    xmlns:m="http://jboss.com/products/seam/mail"
    xmlns:h="http://java.sun.com/jsf/html">
  
    <m:from name="Peter" address="peter@example.com" />
    <m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>
    <m:subject>Try out Seam!</m:subject>
    
    <m:body>
        <p><h:outputText value="Dear #{person.firstname}" />,</p>
        <p>You can try out Seam by visiting 
        <a href="http://labs.jboss.com/jbossseam">http://labs.jboss.com/jbossseam</a>.</p>
        <p>Regards,</p>
        <p>Peter</p>
    </m:body>
    
</m:message>

<m:message> タグはメッセージ全体を包み、 Seam に email のレンダリングを開始するよう指示します。 <m:message> タグ内では、 メッセージの送信元の設定に <m:from> タグ、 送信者の指定に <m:to> タグ (通常のfacelet 内にいるのでそれに応じた EL の使用方法に注意してください)、 また <m:subject> タグを使用します。

<m:body> は email のボディを包みます。 HTML 正規タグをボディ内や JSF コンポーネント内に使用することができます。

これで email テンプレートのできあがりです。 送信方法についてですが、 m:message のレンダリングの最後に、 mailSession が email を送信するようコールされるので、 ユーザーがすべきことは Seam にそのビューをレンダリングするよう支持するだけです。

@In(create=true)
private Renderer renderer;
   
public void send() {
    try {
       renderer.render("/simple.xhtml");
       facesMessages.add("Email sent successfully");
   } 
   catch (Exception e) {
       facesMessages.add("Email sending failed: " + e.getMessage());
   }
}

たとえば、 無効な email アドレスを入力すると例外が投げられ、 その例外がキャッチされてユーザーに表示されます。

<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar"/>

<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar" fileName="this-is-so-cool.jar"/>

<m:attachment value="#{numbers}"/>

<m:attachment value="#{person.photo}" contentType="image/png"/>

<m:attachment fileName="tiny.pdf">
    <p:document>                                                      
        A very tiny PDF                                                                                                
    </p:document>
</m:attachment>

<ui:repeat value="#{people}" var="person">
    <m:attachment value="#{person.photo}" contentType="image/jpeg" fileName="#{person.firstname}_#{person.lastname}.jpg"/>
</ui:repeat>

<m:body>
    <f:facet name="alternative">Sorry, your email reader can't show our fancy email, 
please go to http://labs.jboss.com/jbossseam to explore Seam.</f:facet>
</m:body>

<ui:repeat value="#{allUsers} var="user">
    <m:to name="#{user.firstname} #{user.lastname}" address="#{user.emailAddress}" />
</ui:repeat>

<ui:repeat value="#{people}" var="p">
    <m:message>
        <m:from name="#{person.firstname} #{person.lastname}">#{person.address}</m:from>
        <m:to name="#{p.firstname}">#{p.address}</m:to>
            ...
    </m:message>
</ui:repeat>

<m:message>
   <m:from name="Seam" address="do-not-reply@jboss.com" />
   <m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>
   <m:subject>#{subject}</m:subject>
   <m:body>
       <html>
           <body>
               <ui:insert name="body">This is the default body, specified by the template.</ui:insert>
           </body>
       </html>
   </m:body>
</m:message>

<ui:param name="subject" value="Templating with Seam Mail"/>
<ui:define name="body">
    <p>This example demonstrates that you can easily use <i>facelets templating</i> in email!</p>
</ui:define>

<m:message charset="UTF-8">
   ...
</m:message>

<?xml version="1.0" encoding="UTF-8"?>

<m:message xmlns:m="http://jboss.com/products/seam/mail"
           importance="low"
           requestReadReceipt="true"/>

<m:header name="X-Sent-From" value="JBoss Seam"/>

EJB を使用している場合、 MDB (Message Driven Bean) を使用して email を受信することができます。 Seam は mail-ra.rar の改良バージョンと共に JBoss AS で配信されます。 改良点が JBoss AS のリリースバージョンに参入するまでのあいだ、 デフォルトの rar を Seam で配信されるものに置き換えることを推奨します。

次のように設定することができます。

@MessageDriven(activationConfig={
         @ActivationConfigProperty(propertyName="mailServer", propertyValue="localhost"),
         @ActivationConfigProperty(propertyName="mailFolder", propertyValue="INBOX"),
         @ActivationConfigProperty(propertyName="storeProtocol", propertyValue="pop3"),
         @ActivationConfigProperty(propertyName="userName", propertyValue="seam"),
         @ActivationConfigProperty(propertyName="password", propertyValue="seam")
})
@ResourceAdapter("mail-ra.rar")
@Name("mailListener")
public class MailListenerMDB implements MailListener {

   @In(create=true)
   private OrderProcessor orderProcessor;

   public void onMessage(Message message) {
      // Process the message
      orderProcessor.process(message.getSubject());
   }
   
}

受信する各メッセージにより、 onMessage(Message message) がコールされることになります。 ほとんどの seam アノテーションは MDB 内で動作しますが、 永続コンテキストにはアクセスしないでください。

デフォルトの mail-ra.rar についての詳細は http://wiki.jboss.org/wiki/Wiki.jsp?page=InboundJavaMail をご覧ください。 Seam と共に配信されているバージョンには、 JavaMail のデバッグ機能を有効にする debug プロパティ、 使用している MDB へのメッセージ配信が正常に完了すると POP3 メールボックスをフラッシュする機能を無効にする flush プロパティ (デフォルトでは ture)、 デフォルトの TCP ポートを上書きする port プロパティも含まれています。 これに対する api は今後 JBoss AS に加えられる変更に準じて変わる可能性があるので注意してください。

JBoss AS を使用していない場合は mail-ra.rar を使用することができます (メールディレクトリ内の Seam に含まれている)。 または、 同様のアダプタを含む独自のアプリケーションサーバーを思考しても構いません。

アプリケーションに Email サポートを含ませるには、 WEB-INF/lib ディレクトリ内に jboss-seam-mail.jar を含ませます。 JBoss AS を使用している場合は、 Seam の email サポートを使用するのに特別な設定は必要ありません。 これ以外は、 JavaMail API があるか、 JavaMail API が実装されているか (JBoss AS で使用される API と impl は lib/mail.jar として seam と共に配信される)、 Java Activation Framework のコピーがあるか (lib/activation.jar として seam と共に配信される) を確認する必要があります。

Seam Email モジュールにはビューテクノロジーとして Facelets を使用する必要があります。 ライブラリの今後のバージョンでは JSP の使用にも対応する可能性があります。 また、 seam-ui パッケージの使用も必要となります。

mailSession コンポーネントは JavaMail を使って「実際の」 SMTP サーバーと交信します。

<components xmlns="http://jboss.com/products/seam/components"
        xmlns:core="http://jboss.com/products/seam/core"
        xmlns:mail="http://jboss.com/products/seam/mail">
        
    <mail:mail-session session-jndi-name="java:/Mail"/>
    
</components>

<components xmlns="http://jboss.com/products/seam/components"
        xmlns:core="http://jboss.com/products/seam/core"
        xmlns:mail="http://jboss.com/products/seam/mail">
        
    <mail:mail-session host="smtp.example.com"/>
    
</components>

Email は http://jboss.com/products/seam/mail 名前スペース内でタグを使って生成されます。 ドキュメントには常にメッセージのルートに message タグがあるはずです。 メッセージタグは Seam による email 生成の準備を行います。

facelets の標準テンプレート作成タグは通常通りに使用できます。 ボディ内では、 外部リソース (スタイルシート、 javascript) にアクセスを必要としない JSF タグを使用できます。

ビルトインの pojoCache コンポーネントは org.jboss.cache.aop.PojoCache のインスタンスを管理します。 不変の Java オブジェクトであれば安全にキャッシュに置くことができ、 オブジェクトはクラスタ内でレプリケーションされます (レプリケーションが有効な場合)。 変更の可能性があるオブジェクトをキャッシュに持ちたい場合は、 JBossCache のバイトコード・プロセッサを実行し、 オブジェクトの変更が自動的に検知され、 レプリケーションされるようにする必要があります。

pojoCacheを使うには、クラスパスにJBossCacheのjarを置き、treecache.xmlというリソースに適切なcacheの設定を記述するだけです。 JBossCacheには恐ろしく厄介で紛らわしい設定がたくさんあるので、ここでは説明しません。 詳細はJBossCacheの文書を参照してください。

SeamにEARをデプロイする場合は、JBossCacheのjarと設定ファイルをEARに直接含めることをお勧めします。 application.xmlにjarを記述することを忘れないでください。

次のように、Seamコンポーネントにキャッシュをインジェクトします。

@Name("chatroom")
public class Chatroom {
    @In PojoCache pojoCache;
    
    public void join(String username) {
      try
      {
         Set<String> userList = (Set<String>) pojoCache.get("chatroom", "userList");
         if (userList==null) 
         {
            userList = new HashSet<String>();
            pojoCache.put("chatroom", "userList", userList);
         }
         userList.put(username);
      }
      catch (CacheException ce)
      {
         throw new RuntimeException(ce);
      }
    }
}

JBossCacheを複数設定する場合は、components.xmlを使用してください。

<core:pojo-cache name="myCache" cfg-resource-name="myown/cache.xml"/>

SeamのJBossCache の利用でもっとも興味深いのは、 JSFにおけるページ断片のキャッシュ問題を解決する、 <s:cache> タグです。 <s:cache> は内部的に pojoCache を使うので、 使用する場合は前述の手順を行ってください (EAR に jar を入れる、 やっかいな設定を切り抜ける、などの手順です。)

<s:cache>は、あまり変更されないレンタリング・コンテンツに使用してください。 たとえば、最新のblogエントリを表示するblogのウェルカムページです。

<s:cache key="recentEntries-#{blog.id}" region="welcomePageFragments">
   <h:dataTable value="#{blog.recentEntries}" var="blogEntry">
      <h:column>
         <h3>#{blogEntry.title}</h3>
         <div>
            <s:formattedText value="#{blogEntry.body}"/>
         </div>
      </h:column>
   </h:dataTable>
</s:cache>

key を指定することによって、 各ページ断片のキャッシュバージョンを複数持つことができます。 この例では、 ひとつの blog に対してひとつのキャッシュバージョンが存在します。 region には、 すべてのバージョンを保存する JBossCache のノードを指定します。 異なるノードは異なる有効期限ポリシーを持つ場合があります。 (前述の厄介な設定で指定できます。)

そして、 <s:cache> の大きな問題は、 対象のデータがいつ変更されるか (たとえば、 新しい blog がいつ投稿されるか) を知り得ないということです。 つまり、 キャッシュされた断片は、 明示的にキャッシュから排除する必要があります。

public void post() {
    ...
    entityManager.persist(blogEntry);
    pojoCache.remove("welcomePageFragments", "recentEntries-" + blog.getId() );
}

あるいは、変更を即座にユーザに見せる必要がないのであれば、JBossCacheノードの有効期限を短く設定しても良いでしょう。