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.8. 组件信息
| Component Type | org.operamasks.faces.AjaxProgress |
| Component Family | org.operamasks.faces.AjaxProgress |
| Renderer Type | org.operamasks.faces.AjaxProgress |
| Component Class | org.operamasks.faces.component.ajax.AjaxProgress |
| Renderer Class(AJAX) | org.operamasks.faces.render.ajax.AjaxProgressRenderer |
| Tag Class | org.operamasks.faces.webapp.ajax.ProgressTag |
+java.lang.Object
++javax.faces.component.UIComponent
+++javax.faces.component.UIComponentBase
++++org.operamasks.faces.component.ajax.AjaxProgress
表 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 | ||||
使用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是否处于运行状态 |
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的当前状态 |
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的当前状态 |
以上代码演示了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 &gt;= 100) {
status.setPercentage(100);
status.setMessage("Progress completed");
status.setState(ProgressState.COMPLETED);
} else {
status.setPercentage(percentage);
status.setState(ProgressState.RUNNING);
}
}
}