Apusic JSF — Getting Started

1.  目的

本教程将向您介绍下载、安装以及运行 Apusic JSF 及其示例 ，并向您介绍如何构建一个具有“系统用户登录”原型功能的 Hello World 用例。

2.  主题

l        概述

l        Apusic JSF 的下载、安装及启动

l        运行 Apusic JSF 示例 jsfdemo

l        Hello World – 您的第一个 JSF 应用示例

3.  概述

Apusic JSF 是基于 Ajax 技术的 JSF 开源引擎。通过 Apusic JSF 的 Ajax 特性，我们能够只把发生变化的数据打包成 Ajax 请求发送给服务器端，而服务器端也只会将发生变化的数据打包成 Ajax 应答，从而大大提升系统的运行效率。并且，传统的 JSF 请求应答将刷新整个页面，而 Apusic JSF 将只更新发生变化的客户端组件，从而给客户带来更好的人机体验。

4.  Apusic JSF 的下载、安装及启动

目前推出的 Apusic JSF 引擎内嵌并运行于 Apusic 5.0 应用服务器之上，因而用户只需下载并安装 Apusic 5.0 应用服务器，即可完成对 Apusic JSF 应用的支持。

Apusic 5.0 应用服务器是基于 JAVA EE5 标准的应用服务器，在使用 Apusic 5.0 应用服务器之前，用户需安装 JDK1.5 及以上版本。

l        JDK1.5 的下载及安装

用户可以从以下地址获得 JDK1.5 或 JDK 最新下载：

http://java.sun.com/javase/downloads/index.jsp

l        Apusic 5.0 应用服务器的下载

Apusic 5.0 应用服务器 beta 版，可以从以下地址获得：

http://www.operamasks.org/downsrc/apusic-5.0.zip

你也可以从 http://www.operamasks.org/Download.jsp 获得 Apusic 5.0 应用服务器的最新下载。

l        Apusic 5.0 应用服务器的安装

1)      将下载的 apusic-5.0.zip 文件解压到您所期望的应用服务安装目录，如 C:/Program Files/ApusicHome 文件夹下。

   注： Apusic 5.0 应用服务器 Beta 版直接解压即可，无须安装；对于 Apusic 5.0

发布版的安装用户可参照应用服务器安装在线文档：

 http://www.apusic.com/support/docs/4.1/server/server_install.htm

2)      对直接解压方式进行安装的用户，需要对 Apusic 5.0 应用服务器运行环境进行设置。

Ø         进入应用服务器安装目录 ( 如 C:/ ApusicHome) 下的 bin 文件夹。

Ø         编辑 setenv.cmd 批处理文件如下两项设置：

   set APUSIC_HOME=服务器安装目录（如C: /ApusicHome）

       set JAVA_HOME = JDK安装目录（如C:/ Java/jdk1.5.0_07）

Ø         保存对 setenv.cmd 文件的修改，并运行 setenv.cmd 批处理文件。

3)    运行Apusic 5.0应用服务器

Ø         通过安装向导完成 Apusic 5.0 应用服务器安装用户，可以通过

选择：开始 -> 程序 ->Apusic 应用服务器 5.0-> 启动 Apusic 应用服务器 5.0 启动服务器。

或运行 Apusic 5.0 应用服务器安装路径 ( 如C: /ApusicHome ) 的 bin 文件夹下的 startapusic.cmd 进行启动。

Ø         解压方式安装的用户，直接运行 Apusic 5.0 应用服务器安装路径 ( 如C: /ApusicHome ) 的 bin 文件夹下的 startapusic.cmd 进行启动。

Ø         服务器成功启动后 ( 控制台显示“服务器就绪”字样 ) ，用户即可用浏览器访问 http://localhost:6888 服务器默认部署应用。

5.  运行Apusic JSF示例jsfdemo

jsfdemo 提供了一系列 Apusic JSF 组件如 select box 、 menu 、 slider 、 progress bar 等的 Ajax 及非 Ajax 支持示例。

运行 jsfdemo 示例之前请确保：

1） 已正确安装了 Apusic 5.0 应用服务器， Apusic 5.0 应用服务器的下载及安装请参见“ Apusic JSF 的下载、安装及启动”。

2） 已正确下载 jsfdemo 示例工程。下载 Apusic 5.0 应用服务器 Beta 版的用户可以在 Apusic5.0 应用服务器安装目录（如C: /ApusicHome ）下的 applications 文件夹下找到 jsfdemo 打包文件 jsfdemo.war 。您也可以从以下地址获得：

http://www.operamasks.org/downsrc/jsfdemo.war.

3） 已成功部署了 jsfdemo 示例。部署 jsfdemo 应用示例，可以通过两种方式完成：

Ø         直接修改配置文件 server.xml 。在应用服务器的安装目录（如C: /ApusicHome ）下的 config 目录下，打开 server.xml 文件，在 <Server> 标签里增加标签项 <application name="jsfdemo.war" base="C:/ApusicHome/applications/jsfdemo.war" start="auto"/> 即可。其中 application 标签 base 属性值为 jsfdemo 示例的存放路径。

Ø         利用 Apusic 5.0 应用服务器的图形化部署工具：具体操作请参照 Apusic 应用服务器用户手册或 Apusic 应用服务器在线文档的“ Apusic 应用服务器部署工具用户手册 ”一节。

注： Apusic 5.0 应用服务器已默认部署好 jsfdemo 示例。

4） 到此，您可以启动服务器，然后通过 http://localhost:6888/jsfdemo 访问 jsfdemo 示例。

注：您可以从以下地址获得 jsfdemo 应用的在线示例：

http://www.operamasks.org:8080/jsfdemo/

6.  Hello World – 您的第一个JSF应用示例

1 ）概述

Hello World 应用示例原型源于系统用户登录功能。 Hello World 应用示例由 5 个页面构成：

Ø         index.jsp ：作为 helloworld 应用示例的起点，其主要功能为页面导航之用，将用户 url 请求如 http://localhost:6888/helloworld/ 导向到 welcome.jsp

Ø         welcome.jsp ：作为应用示例的门户，并向世界问号 ”Hello World” 。

Ø         login.jsp ： login 页面是应用示例的主页面，由两个域构成：一个用于用户名，一个用于口令。该页面使用一个 Java Bean （本示例的 loginbean ） 来管理这两个值的持久性。在本文中，详细说明了 login 页面静态导航与动态导航的两种实现。

Ø         hello.jsp ：此页面作为 login 页面的导航目标页面之一，返回一条 hello 消息，并显示存储在辅助 bean （ loginbean ）中的用户名。

Ø         msg.jsp ：此页面作为 login 页面另一个导航目标页面，在本例 login 页面动态导航实现中，当用户输入口令不为 hello 时，进入该页面，并显示一条导航信息。

在本示例中，您将会学习以下内容：

Ø         示例各功能页面的构建。

Ø         Managedbean 的构建及使用。

Ø         页面静态、动态导航的构建。

2 ）示例构建环境

   在构建及运行本示例之前，需正确安装 Apusic 5.0 应用服务器或 Apusic JSF 引擎。

3 ）示例目录结构

    Hello World 应用示例是一个典型的 web 应用示例，其目录结构如下图所示：

Hello World 示例目录结构

4 ）构建index.jsp

   Index 页面作为页面导航之用，其代码清单如 listing 1-1 所示：    

 Listing 1-1 helloworld/index.jsp    

  <! doctype html public "-//w3c//dtd html 4.0 transitional//en" >

< html >

< head >

</ head >

< body >

< jsp:forward page = "welcome.jsf" />

</ body >

</ html >

5) 构建 welcome.jsp页面

   Welcome 页面作为应用示例的门户，并向世界问号 ”Hello World” 。其用户界面如下图所示：

Welcome 用户界面

Welcome 页面代码清单如 listing 1-2 所示：

Listing 1-2 helloworld/welcome.jsp

<%@ page contentType = "text/html;charset=GBK" %>

<%@ taglib prefix = "f" uri = "http://java.sun.com/jsf/core" %>

<%@ taglib prefix = "h" uri = "http://java.sun.com/jsf/html" %>

< f:view >

          < html >

          < head >

          < title > welcome </ title >

          </ head >

          < body >

          < h:form >

              < h1 > Hello World, This is my first JSF! </ h1 >

              < h3 > JSF 应用的一小步，赢得程序人生的一大步！ </ h3 >

              < p >< h:commandButton value = "Go Login" action = "login" /></ p >

          </ h:form >

          </ body >

          </ html >

</ f:view >

代码分析：

   此页面主要功能为，单击 Go Login 按钮 页面导航到 login.jsp 页面。

   在本页面中，我们利用 < h:commandButton > 标签来完成上述功能：

Ø         < h:commandButton > 标签的 value 属性值控制按钮的外观文字显示。

Ø         < h:commandButton > 标签的 action 属性值控制页面的导航规则。在这里 action 属性值 “ login ”为一导航规则逻辑名。关于导航规则的配置，请参照 “创建导航规则”。

6 ）构建及配置loginbean，构建login.jsp页面

   login 页面是应用示例的主页面，由两个域构成：一个用于用户名，一个用于口令。在本示例中，我们利用 loginbean 来管理这两个值的持久性。

Ø         构建loginbean

Loginbean 包含了对用户名（ name ）及口令（ password ）的 get 和 set 操作，其代码清单如 listing 1-3 所示：

Listing 1-3 helloworld/src/com/apuisc/helloworld/LoginBean.java

package  com.apusic.helloworld;

public class LoginBean {

  private String name;
  private String password;
  /**
   * @return  返回  name 。
   */
  public String getName() {
    return name;
  }
  /**
   * @param name  要设置的  name 。
   */
  public void setName(String name) {
    this.name = name;
  }
  /**
   * @return  返回  password 。
   */
  public String getPassword() {
    return password;
  }
  /**
   * @param password  要设置的  password 。
   */
  public void setPassword(String password) {
    this.password = password;
  }
}

Ø         配置LoginBean

在 Hello World 应用中， LoginBean 的应用实例（ Instance ）配置是在 faces-config.xml 文件中完成的，具体配置如 listing 1-4 所示：      

  Listing 1-4 helloworld/WEB-INF/faces-config.xml

< managed-bean >

              < managed-bean-name > loginbean </ managed-bean-name >

              < managed-bean-class >

                  com.apusic.helloworld. LoginBean

              </ managed-bean-class >

              < managed-bean-scope > session </ managed-bean-scope >

</ managed-bean >

以上配置完成了：构建了 com.apusic.helloworld. LoginBean 的一个对象，并赋予其逻辑引用名 loginbean ，该 LoginBean 在一个用户 session 周期内有效，也即是在同一个客户的所有请求中有效。一旦 LoginBean 配置成功，用户即可在示例中通过其逻辑引用名访问（详细参见“构建 login 页面”一节），用户无须再进行构建及维护。

Ø         构建login页面

Login 页面用户界面如下图所示：

Login 用户界面

Login 页面代码清单如 listing 1-5 所示：

Listing 1-5 helloworld/login.jsp

<%@ page contentType = "text/html;charset=GBK" %>

<%@ taglib prefix = "f" uri = "http://java.sun.com/jsf/core" %>

<%@ taglib prefix = "h" uri = "http://java.sun.com/jsf/html" %>

< f:view >

               < html >

               < head >

               < title > login </ title >

               </ head >

               < body >

               < h:form >

                   < h3 > 请输入用户名与密码 : </ h3 >

                   < table >

                      < tr >

                         < td > Name: </ td >

                         < td >< h:inputText value = "#{loginbean.name}"id="username" required="true" />

< h:message for = "username" />

</ td >

                      </ tr >

                      < tr >

                          < td > Password: </ td >

                          < td >< h:inputSecret value = "#{loginbean.password}"/></td>

                      </ tr >

                  </ table >

                  < p >< h:commandButton value = "Login" action = "hello" /></ p >

               </ h:form >

               </ body >

               </ html >

</ f:view >

代码分析：

在 login 页面演示了对 loginbean 的使用：

< h:inputText value = "#{loginbean.name}"id="username" required="true" />

< h:inputSecret value = "#{loginbean.password}"/>

在该页面中，利用值绑定方法（如 #{loginbean.name} ）实现了对 loginbean 属性值（如 loginbean 的 name ）的自动读取与更新操作。当组件（如 inputText ）被渲染成 <input type=”text”.../> 时（如 login.jsp 页面被加载时）， loginbean 相应属性的 getter 操作会自动被调用。当用户提交一个 request 请求时， loginbean 相应属性的 setter 操作会自动被调用（如点击 login 按钮 提交页面）。

另外，该页面还演示了 <h:message .../> 组件的应用，在本页面中构建了针对 username 域（ inputText 组件）的消息，当用户未输入用户名时给予提示。

7）构建 Hello.jsp页面。

Hello 页面用户界面如下图所示：

Hello 用户界面

Hello 页面代码清单如 listing 1-6 所示：

Listing 1-6 helloworld/hello.jsp

<%@ page contentType = "text/html;charset=GBK" %>

<%@ taglib prefix = "f" uri = "http://java.sun.com/jsf/core" %>

<%@ taglib prefix = "h" uri = "http://java.sun.com/jsf/html" %>         

< f:view >

  < html >

              < head >

                < title > hello </ title >

    </ head >

              < body >< h:form >

                  < h2 >

          < strong >

                       Welcome to JavaServer Faces, < h:outputText value = "#{loginbean.name}"/>! 

                      </ font ></ strong >

                  </ h2 >

                   < p >

                         < h:commandButton value = "Do it Again" action = "welcome" />

                   </ p >

               </ h:form ></ body >

             </ html >

</ f:view >

代码分析：

该页面引用 loginbean 的 name 属性值（自动实现 getter 操作），向用户问好。

至此，我们已经完成了 Hello World 示例的页面构建，接下来，我们会实现页面中出现的逻辑导航规则（如 login 、 hello 、 welcome 等）的配置。

8）创建导航规则

   在本示例中有以下封闭的导航路线： welcome.jsp(login) à login.jsp(hello) à hello.jsp(welcome) à welcome.jsp

   在 JSF 中，在 faces-config.xml 文件中，实现对应用导航的配置，以 welcome 页面到 login 页面的导航为例：

            < navigation-rule >

           < from-view-id > /welcome.jsp </ from-view-id >

           < navigation-case >

              < from-outcome > login </ from-outcome >

              < to-view-id > /login.jsp </ to-view-id >

           </ navigation-case >

    </ navigation-rule >

   一个导航以 < navigation-rule > 标签来完成，其中：

Ø         < from-view-id > 是指可以使用该导航规则的页面，在本例中即是指只有 welcome.jsp 页面才拥有对 login 导航的使用，其它页面对 login 的任何使用将无效。要使该规则应用于多个页面，用户可以不指定该属性，详细参见“创建 login 动态导航”一节。

Ø         < from-outcome > 是指导航规则的逻辑名，在导航规则可见域范围类的页面的相应组件（ < h:commandButton ../> ）的 action 值如果与该逻辑名匹配，则该规则被调用。

Ø         < to-view-id > 是指该导航规则的目标响应页面。

注： view-id （包括 from-view-id 与 to-view-id ）属性值必须以 ”/” 开头，并且其扩展名必须与实际文件的文件扩展名（如“ .jsp ”）一致，而不是与 URL 请求中的扩展名一致。

Hello World 应用示例的导航规则如 listing 1-7 所示。

Listing 1-7 helloworld/WEB-INF/faces-config.xml

       < navigation-rule >

          < from-view-id > /welcome.jsp </ from-view-id >

          < navigation-case >

              < from-outcome > login </ from-outcome >

              < to-view-id > /login.jsp </ to-view-id >

          </ navigation-case >

       </ navigation-rule >

< navigation-rule >

            < from-view-id > /login.jsp </ from-view-id >

          < navigation-case >

               < from-outcome > hello </ from-outcome >

              < to-view-id > /hello.jsp </ to-view-id >

           </ navigation-case >

        </ navigation-rule >

< navigation-rule >

< from-view-id > /hello.jsp </ from-view-id >

         < navigation-case >

           < from-outcome > welcome </ from-outcome >

           < to-view-id > /welcome.jsp </ to-view-id >

       </ navigation-case >

</ navigation-rule >

9）Hello World的JSF Web 应用配置

   Listing 1-8 演示了对 Faces Servlet 、 Faces servelt Mapping 的配置：

Listing 1-8 helloworld/WEB-INF/web.xml

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

< web-app xmlns = "http://java.sun.com/xml/ns/j2ee" xmlns:xsi = http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation = "http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version = "2.4" >

         < servlet >

             < servlet-name > FacesServlet </ servlet-name >

              < servlet-class > javax.faces.webapp.FacesServlet </ servlet-class >

          </ servlet >

< servlet-mapping >

    < servlet-name > FacesServlet </ servlet-name >

    < url-pattern > *.jsf </ url-pattern >

</ servlet-mapping >

</ web-app >

< servlet > 标签指定了 FacesServelt 的实现类， < servlet-mapping > 标签指定了 FacesServelt 应该处理的 URL 请求，在本例中即是指响应对所有以 ”.jsf” 为后缀的 URL 请求，在“ JSF 规范”中，推荐使用 faces 作为扩展名，但这不是必须的 ( 如本例中以 jsf 为替代扩展名 ) ， FacesServlet 将 url 请求转换为对应的 JSP 。

例如下列 URL ：

   http://localhost:6888/helloworld/welcome.jsf

将转换为：

   http://localhost:6888/helloworld/welcome.jsp

10）部署并运行 Hello World 示例

   在部署 Hello World 示例之前，请确保已正确安装了 Apusic 5.0 应用服务器或 Apusic JSF 引擎。

   直接修改 Apusic 5.0 应用服务器的 Config 目录下的 server.xml 文件，在 <Server> 标签里增加标签项 <application name="helloworld" base="D:/helloworld" start="auto"/> ，启动服务器即可。其中： base 属性值 “ D:/helloworld ”为您所建的 hello world 工程路径。工程部署详细说明参照“运行 Apusic JSF 示例 jsfdemo ”一节。

   正确部署并启动服务器之后，即可通过 http://localhost:6888/helloworld/ 进行访问。

11）创建login动态导航

到目前为止，我们已成功完成了一个简单的 JSF 应用示例。正如前面所述，本示例源于系统用户登录功能，在实际情况中，存在着用户登陆成功与不成功等两种可能。在上述示例中，只有到登陆成功的导航（静态导航）。

在本小节中，我们即将看到 Hello World 的动态导航创建过程，从而实现系统登陆功能原型。

Ø         需求界定

在 login 页面，当用户输入口令不为“ hello ”时，导航到 msg.jsp ，否则导航到 hello.jsp 页面。

Ø         创建条件导航

a.      添加动态导航方法

在 loginbean.java 中添加 loginAction 方法，如 listing 1-9 所示：

Listing 1-9 helloworld/src/com/apuisc/helloworld/loginbean.java

    public  String loginAction() {
        // Add event code here...
         if (password.equals("hello")) {
            return "hello";
            } else {
            String message = " 您输入的 password 不是 hello ，输入 hello 进入 hello.jsp 页面！ " ;
            FacesContext.getCurrentInstance().addMessage(null, new FacesMessage(message));
            return "msg";
            }
    }

在此方法中，当 login 页面输入口令为 “ hello ”时， loginAction 返回导航逻辑名： hello 。否则，返回导航逻辑名 msg ，并传给导航处理页面一个导航消息。

b.      修改动态导航

为 loginbean 添加了动态导航方法之后，我们即可修改 login.jsp 的导航规则，具体过程如下：

将 login.jsp 文件中的

< h:commandButton value = "Login" action = "hello" />

修改为

< h:commandButton value = "Login" action = "#{loginbean.loginAction}" />

c.       构建 msg.jsp

Msg.jsp 的代码清单如 listing 1-10 所示：

Listing 1-10 helloworld/msg.jsp

<%@ page contentType = "text/html;charset=GBK" %>

<%@ taglib prefix = "f" uri = "http://java.sun.com/jsf/core" %>

<%@ taglib prefix = "h" uri = "http://java.sun.com/jsf/html" %>

< f:view >

               < html >

               < head >

               < title > welcome </ title >

               </ head >

               < body >

               < h:form >

                   < h1 > Hello World, This is my first JSF! </ h1 >

                   < h3 > JSF 应用的一小步，赢得我们程序人生的一大步！ </ h3 >

                   < p >< h:messages /></ p >

                   < p >< h:commandButton value = "Do it Again" action = "welcome" /></ p >

               </ h:form >

               </ body >

               </ html >

</ f:view >

Ø         合并导航规则

在 listing 1-10 中，我们看到，在 msg.jsp 页面中，我们用到了 welcome 导航。正如创建导航规则所述，我们需要将 welcome 导航规则进行合并处理，以便 hello.jsp 及 msg.jsp 都能使用。 Welcome 导航修改如下：

< navigation-rule >

           < navigation-case >

              < from-outcome > welcome </ from-outcome >

              < to-view-id > /welcome.jsp </ to-view-id >

           </ navigation-case >

  </ navigation-rule >

在新的导航规则中，我们去处了对 < from-view-id > 的指定。

Ø         重新构建工程并部署。

将 loginbean.java 文件（ helloworld/src/com/apuisc/helloworld/loginbean.java ）重新编译并更新其 class 文件。

从新部署应用，启动服务器，并访问应用 http://localhost:6888/helloworld/

至此，我们已经完成了 Hello World 应用示例，您已经成功开启了您 JSF 应用的第一步，恭喜您！

12）示例工程下载

   您可以从以下地址获得 Hello World 工程的源码 helloworld.war ：

http://www.operamasks.org/downsrc/helloworld.war

   您可以将下载的 helloworld.war 直接部署到 Apusic 5.0 应用服务器上：

   修改应用服务器安装路径 ( 如 c:/ApusicHome ) 下 config 目录下的 server.xml 文件，在 <server> 标签中增加：

<application name="helloworld" base="D:/helloworld.war" start="auto"/>

其中， D:/helloworld.war 为您下载的 helloworld 示例存放路径。

  您也可以从以下地址获得 Helloworld 的在线示例：

http://www.operamasks.org:8080/helloworld/

7.  总结

在本文中，您学习了：

1)       Apusic JSF的下载、安装及运行jsfdemo示例的基本知识

2)       构建了Hello World示例，学习了jsf页面的构建、 Managedbean 的构建及使用、页面静态及动态导航的使用、以及相关 JSF Web 应用工程的配置等。