18.5. <ajax:progress>

AjaxProgress表示一个进度支持组件,不可视,通常与UIProgressBar组件(表示进度)和HtmlOutputText组件(表示进度消息)连用,为这些组件提供后台逻辑支持。该组件只能用于AJAX RenderKit下。

通过ajax:progress标签的"for"属性,可以指定其它组件做为AjaxProgress的表现,目前支持ProgressBar和HtmlOutputText。

通过ajax:progress的"action"属性,可绑定设置进度状态的回调方法,回调方法必须为以下的形式:

public void processMethod(org.operamasks.faces.component.ajax.ProcessStatus);

通过在回调方法里修改参数org.operamasks.faces.component.ajax.ProcessStatus,可将进度状态反馈给表现组件。

18.5.1. 组件信息

表 18.8. 组件信息

Component Typeorg.operamasks.faces.AjaxProgress
Component Familyorg.operamasks.faces.AjaxProgress
Renderer Typeorg.operamasks.faces.AjaxProgress
Component Classorg.operamasks.faces.component.ajax.AjaxProgress
Renderer Class(AJAX)org.operamasks.faces.render.ajax.AjaxProgressRenderer
Tag Classorg.operamasks.faces.webapp.ajax.ProgressTag

继承体系

+java.lang.Object

++javax.faces.component.UIComponent

+++javax.faces.component.UIComponentBase

++++org.operamasks.faces.component.ajax.AjaxProgress

18.5.2. 属性

表 18.9. 属性

action 定义类
类型 java.lang.String
是否必须 延时求值
服务器端执行动作的方法绑定,在服务器端收到客户端发出的请求后会得到调用。表达式所指定的方法必须是public void processStatus(org.operamasks.faces.component.ajax.ProgressStatus)形式
binding 定义类
类型 javax.el.ValueExpression(javax.faces.component.UIComponent)
是否必须 延时求值
将组件自身的实例绑定到指定的属性中
for 定义类
类型 javax.el.ValueExpression(java.lang.String)
是否必须 延时求值
空格分隔的组件id列表,每个id所代表的组件或者是UIProgressBar,或者是HtmlOutputText,这些组件将获得该组件提供的服务。具体的,Progress组件会把自己的状态值传给UIProgressBar类型的组件,把状态文本传给HtmlOutputText类型的组件作为innerHTML的值
id 定义类
类型 java.lang.String
是否必须 延时求值
组件唯一标识,如果未指定,则由服务器端自动生成
interval 定义类
类型 javax.el.ValueExpression(int)
是否必须 延时求值
进度条的总时间
jsvar 定义类
类型 javax.el.ValueExpression(java.lang.String)
是否必须 延时求值
客户端脚本使用的组件变量名,引用OM.ajax.Progress的对象。 在客户端脚本中可以调用这个变量的start(), stop(), pause(),resume(),poll()方法操纵Progress对象的行为。可以调用isRunning(),isStopped(),isPause(),isCompleted(),isFailed()方法得到Progress对象的状态
onstatechange 定义类
类型 javax.el.ValueExpression(java.lang.String)
是否必须 延时求值
当状态变化时执行的操作
rendered 定义类
类型 javax.el.ValueExpression(boolean)
是否必须 延时求值
是否渲染组件
start 定义类
类型 javax.el.ValueExpression(boolean)
是否必须 延时求值
如果为true,则在页面的onload事件中自动向服务器发出start的请求;如果为false,则需要用户自己主动发出start请求。默认值为false

18.5.3. 组件API

18.5.3.1. ProgressStatus

使用AjaxProgress组件时,服务器端回调方法会接受到一个ProgressStatus的参数。ProgressStatus中包含AjaxProgress当前的状态信息和客户端对AjaxProgress的控制请求。

表 18.10. 方法

getAction 方法签名 public org.operamasks.faces.component.ajax.ProgressAction getAction()
参数说明  
返回值 ProgressAction对象表示客户端对Progress的控制请求
方法描述 获取客户端对Progress的控制请求对象
getState 方法签名 public org.operamasks.faces.component.ajax.ProgressState getState()
参数说明  
返回值 ProgressState对象表示Progress当前状态
方法描述 获取Progress的当前状态对象
setState 方法签名 public void setState(org.operamasks.faces.component.ajax.ProgressState state)
参数说明 state:当前Progress的状态
返回值  
方法描述 设置Progress当前状态对象
getPhase 方法签名 public int getPhase()
参数说明  
返回值 整型数表示的Progress所处于的阶段
方法描述 获取一个整型数表示Progress所处于的阶段
setPhase 方法签名 public void setPhase(int phase)
参数说明 phase:用整型数表示Progress所处于的阶段
返回值  
方法描述 设置一个整型数,表示Progress当前所处于的阶段
getPercentage 方法签名 public int getPercentage()
参数说明  
返回值 当前Progress所执行到的百分比
方法描述 获取当前Progress所执行到的百分比
setPercentage 方法签名 public setPercentage(int percentage)
参数说明 一个整型数表示Progress所执行到的百分比
返回值  
方法描述 设置Prgress所执行到的百分比
getMessage 方法签名 public java.lang.String getMessage()
参数说明  
返回值 当前Progress提供的提示信息
方法描述 获取当前Progress提供的提示信息
setMessage 方法签名 public void setMessage(java.lang.String message)
参数说明 message:当前Progress提供的提示信息
返回值  
方法描述 设置当前Progress所提供的提示信息
isStopped 方法签名 public boolean isStopped()
参数说明  
返回值 true表示当前Progress已经停止;false表示Prgress还未停止
方法描述 确定当前Progress是否处于停止状态
isPaused 方法签名 public boolean isPaused()
参数说明  
返回值 true表示当前Progress处于暂停状态;false表示当前Progress并未处于暂停状态
方法描述 确定当前Progress是否处于暂停状态
isComplete 方法签名 public boolean isComplete()
参数说明  
返回值 true表示当前Progress已经结束;false表示当前Progress还未结束
方法描述 确定当前Progress所提供的提示信息
isFailed 方法签名 public boolean isFailed()
参数说明  
返回值 true表示当前Progress失败;false表示当前Progress未失败
方法描述 确定当前Progress是否失败
isRunning 方法签名 public boolean isRunning()
参数说明  
返回值 true表示当前Progress处于运行状态;false表示Progress未处于运行状态
方法描述 确定当前Progress是否处于运行状态

18.5.3.2. ProgressState

ProgressState类表示Progress当前状态,可通过调用ProgressStatus.getState()获取它。

表 18.11. 属性

_RUNNING 属性类型 int
属性说明 静态整型值,表示当前Progress处于运行状态
_STOPPED 属性类型 int
属性说明 静态整型值,表示当前Progress处于停止状态
_PAUSED 属性类型 int
属性说明 静态整型值,表示当前Progress处于暂停状态
_COMPLETED 属性类型 int
属性说明 静态整型值,表示当前Progress处于结束状态
_FAILED 属性类型 int
属性说明 静态整型值,表示当前Progress处于失败状态
RUNNING 属性类型 org.operamasks.faces.component.ajax.ProgressState
属性说明 一个静态ProgressState对象,表示当前Progress处于运行状态
STOPPED 属性类型 org.operamasks.faces.component.ajax.ProgressState
属性说明 一个静态ProgressState对象,表示当前Progress处于停止状态
PAUSED 属性类型 org.operamasks.faces.component.ajax.ProgressState
属性说明 一个静态ProgressState对象,表示当前Progress处于暂停状态
COMPLETED 属性类型 org.operamasks.faces.component.ajax.ProgressState
属性说明 一个静态ProgressState对象,表示当前Progress处于结束状态
FAILED 属性类型 org.operamasks.faces.component.ajax.ProgressState
属性说明 一个静态ProgressState对象,表示当前Progress处于失败状态

表 18.12. 方法

getName 方法签名 public java.lang.String getName()
参数说明  
返回值 ProgressState名。值为"running","stopped","completed","paused","failed"其中之一
方法描述 获取ProgressState名
getOrdinal 方法签名 public int getOrdinal()
参数说明  
返回值 一个整数型序号,表示Progress的当前状态,值为_RUNNING,_STOPPED,_COMPLETED,_PAUSED,_FAILED之一
方法描述 获取用整数型序号表示的Progress的当前状态

18.5.3.3. ProgressAction

ProgressAction类表示客户端对AjaxProgress的状态控制请求,可通过调用ProgressStatus.getAction()获取它。

表 18.13. 属性

_START 属性类型 int
属性说明 静态整型值,表示启动Progress指令
_STOP 属性类型 int
属性说明 静态整型值,表示停止Progress指令
_PAUSE 属性类型 int
属性说明 静态整型值,表示暂停Progress指令
_RESUME 属性类型 int
属性说明 静态整型值,表示恢复Progress指令
_POLL 属性类型 int
属性说明 静态整型值,表示继续Progress指令
START 属性类型 org.operamasks.faces.component.ajax.ProgressState
属性说明 一个静态ProgressState对象,表示启动Progress指令
STOP 属性类型 org.operamasks.faces.component.ajax.ProgressState
属性说明 一个静态ProgressState对象,表示停止Progress指令
PAUSE 属性类型 org.operamasks.faces.component.ajax.ProgressState
属性说明 一个静态ProgressState对象,表示暂停Progress指令
RESUME 属性类型 org.operamasks.faces.component.ajax.ProgressState
属性说明 一个静态ProgressState对象,表示恢复Progress指令
POLL 属性类型 org.operamasks.faces.component.ajax.ProgressState
属性说明 一个静态ProgressState对象,表示继续Progress指令

表 18.14. 方法

getName 方法签名 public java.lang.String getName()
参数说明  
返回值 ProgressAction名。值为"start","stop","pause","resume","poll"其中之一
方法描述 获取ProgressState名
getOrdinal 方法签名 public int getOrdinal()
参数说明  
返回值 一个整数型序号,表示客户端对Progress的控制指令,值为_START,_STOP,_PAUSE,_RESUME,_POLL之一
方法描述 获取用整数型序号表示的Progress的当前状态

18.5.4. 例子

以上代码演示了AjaxProgress的用法,AjaxProgress组件本身是不可视的组件,上例中用ajax:progress的"for"属性将任务进度的展现委托给了w:progressBar和h:outputText。一个w:button调用Progress组件的客户端方法start()启动AjaxProgress,每秒发出一次请求(ajax:progress的"interval"属性默认值)给服务器端更新任务进度状态。

<h:form id='myform'>
  <p> <w:button accesskey='s' onclick="percentageTask.start();" value="start" /> </p>
  <table>
    <tr>
      <td>
        <w:progressBar id="percentageProgress"/>
      </td>
    </tr>
    <tr>
      <td style="text-align:center;font-size:12px">
        <h:outputText id="percentageMessage" value="idle"/>
      </td>
    </tr>
  </table>
  <ajax:progress id='percentageTask' for="percentageProgress percentageMessage" 
          action="#{ProgressBean.percentageAction}" onstatechange="window.status=this.state;"/>
</h:form>

这段代码通过设置ProgressStatus的"percentage","message"和"state"属性,将任务进度通知页面上的进度表现组件。

public void percentageAction(ProgressStatus status) {
    if (status.getAction().ordinal() == ProgressAction._START) {
        this.percentage = 0;
        status.setPercentage(0);
        status.setState(ProgressState.RUNNING);
    } else if(status.getAction().ordinal() == ProgressAction._POLL) {
        // Get task's progress percentage from external resource.
        this.percentage = getTaskProgressPercentage();
        if (percentage &amp;gt;= 100) {
            status.setPercentage(100);
            status.setMessage("Progress completed");
            status.setState(ProgressState.COMPLETED);
        } else {
            status.setPercentage(percentage);
            status.setState(ProgressState.RUNNING);
        }
    }
}