UICommand (Java EE 5)

Java EE API


javax.faces.component Class UICommand

java.lang.Object
  extended by javax.faces.component.UIComponent
      extended by javax.faces.component.UIComponentBase
          extended by javax.faces.component.UICommand
All Implemented Interfaces:
ActionSource, ActionSource2, StateHolder
Direct Known Subclasses:
HtmlCommandButton, HtmlCommandLink

public class UICommand
extends UIComponentBase
implements ActionSource2

Implements: ActionSource2

UICommand 是一个 UIComponent,它表示当用户将其激活时,将触发特定于应用程序的 "command" 或 "action" 的用户界面组件。此类组件通常呈现为按钮开关、菜单项或超链接。

当此 UICommanddecode() 方法或其相应的 Renderer 检测到此控件已被激活,它将把一个 ActionEvent 加入队列。之后,broadcast() 方法将确保此事件广播到所有感兴趣的侦听器。

将按以下顺序调用侦听器:

  1. ActionListener,按它们注册的顺序。
  2. "actionListener" MethodExpression(它将覆盖设置为 MethodBinding 的 "actionListener")。
  3. Application 中获取到的默认 ActionListener - 并且因此包含任何连接的 "action" MethodExpression

默认情况下,rendererType 属性必须设置为 "javax.faces.Button"。可以调用 setRendererType() 方法更改此值。

英文文档:

UICommand is a UIComponent that represents a user interface component which, when activated by the user, triggers an application specific "command" or "action". Such a component is typically rendered as a push button, a menu item, or a hyperlink.

When the decode() method of this UICommand, or its corresponding Renderer, detects that this control has been activated, it will queue an ActionEvent. Later on, the broadcast() method will ensure that this event is broadcast to all interested listeners.

Listeners will be invoked in the following order:

  1. ActionListeners, in the order in which they were registered.
  2. The "actionListener" MethodExpression (which will cover the "actionListener" that was set as a MethodBinding).
  3. The default ActionListener, retrieved from the Application - and therefore, any attached "action" MethodExpression.

By default, the rendererType property must be set to "javax.faces.Button". This value can be changed by calling the setRendererType() method.


Field Summary
static String
static String
 
Fields inherited from class javax.faces.component.UIComponent
 
Constructor Summary
 
Method Summary
 void
 void
 MethodBinding
 MethodExpression
 MethodBinding
 ActionListener[]
 String
 Object
 boolean
 void
 void
 void
 Object
 void
 void
 void
 void
 void
 
Methods inherited from class javax.faces.component.UIComponentBase
 
Methods inherited from class javax.faces.component.UIComponent
 
Methods inherited from class java.lang.Object
 

Field Detail

英文文档:

COMPONENT_TYPE

public static final String COMPONENT_TYPE

The standard component type for this component.

See Also:
Constant Field Values


英文文档:

COMPONENT_FAMILY

public static final String COMPONENT_FAMILY

The standard component family for this component.

See Also:
Constant Field Values

Constructor Detail

public UICommand()

使用默认属性值创建新的 UICommand 实例。

英文文档:

UICommand

public UICommand()

Create a new UICommand instance with default property values.

Method Detail

public String getFamily()
英文文档:

getFamily

public String getFamily()
Description copied from class: UIComponent

Return the identifier of the component family to which this component belongs. This identifier, in conjunction with the value of the rendererType property, may be used to select the appropriate Renderer for this component instance.

Specified by:
getFamily in class UIComponent

public MethodBinding getAction()
NullPointerException

如果实现类还实现了 ActionSource2,则此方法的实现必须调用 ActionSource2#getActionExpression 并检查该结果。如果结果来自以前对 #setAction 的调用,则从结果中提取 MethodBinding 并将其返回。否则,包装返回的 MethodBinding 实现中的 javax.el.MethodExpression 并将其返回。

如果实现类没有实现 ActionSource2,则返回一个 MethodBinding,该 MethodBinding 指向用户激活此 UIComponent 时要在请求处理生命周期的应用请求值调用应用程序 阶段(取决于 immediate 属性的值)调用的应用程序操作。

deprecated 此方法已由 #getActionExpression 替代。
英文文档:

getAction

public MethodBinding getAction()
Deprecated. This has been replaced by getActionExpression().

If the implementing class also implements ActionSource2, the implementation of this method must call through to ActionSource2.getActionExpression() and examine the result. If the result came from a previous call to ActionSource.setAction(javax.faces.el.MethodBinding), extract the MethodBinding from it and return it. Otherwise, wrap the returned MethodExpression in a MethodBinding implementation, and return it.

If the implementing class does not implement ActionSource2, return the MethodBindingpointing at the application action to be invoked, if this UIComponent is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property.

Specified by:
getAction in interface ActionSource

public void setAction(MethodBinding action)
NullPointerException

如果实现类还实现了 ActionSource2,则此方法的实现必须在实现 javax.el.MethodExpression 的类中包装参数 action,并调用 ActionSource2#setActionExpression,同时传递包装的 action

如果实现类没有实现 ActionSource2,则设置一个 MethodBinding,该 MethodBinding 指向用户激活此 UIComponent 时要在请求处理生命周期的应用请求值调用应用程序 阶段(取决于 immediate 属性的值)调用的应用程序操作。

此表达式所引用的任何方法都必须是公共的,返回类型为 String,并且不接受任何参数。

deprecated 此方法已由 #setActionExpression(javax.el.MethodExpression) 替代。
英文文档:

setAction

public void setAction(MethodBinding action)
Deprecated. This has been replaced by setActionExpression(javax.el.MethodExpression).

If the implementing class also implements ActionSource2, the implementation of this method must wrap the argument action in a class that implements MethodExpression and call through to ActionSource2.setActionExpression(javax.el.MethodExpression), passing the wrapped action.

If the implementing class does not implement ActionSource2, set the MethodBinding pointing at the appication action to be invoked, if this UIComponent is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property.

Any method referenced by such an expression must be public, with a return type of String, and accept no parameters.

Specified by:
setAction in interface ActionSource
Parameters:
action - The new MethodBinding expression

public MethodBinding getActionListener()
NullPointerException

如果以前没有为此实例调用过 #setActionListener,则此方法必须返回 null。如果调用过 #setActionListener,则此方法必须返回原先传递给 #setActionListener 的那个 MethodBinding 实例。

用户激活此 UIComponent 时要调用的方法将在请求处理生命周期的应用请求值调用应用程序 阶段(取决于 immediate 属性的值)调用。

deprecated 请改用 #getActionListeners
英文文档:

getActionListener

public MethodBinding getActionListener()
Deprecated. Use getActionListeners() instead.

If ActionSource.setActionListener(javax.faces.el.MethodBinding) was not previously called for this instance, this method must return null. If it was called, this method must return the exact MethodBinding instance that was passed to ActionSource.setActionListener(javax.faces.el.MethodBinding).

The method to be invoked, if this UIComponent is activated by the user, will be called during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending upon the value of the immediate property.

Specified by:
getActionListener in interface ActionSource

public void setActionListener(MethodBinding actionListener)
NullPointerException

ActionListener 的实现中包装参数 actionListener,并将其存储在支持 #getActionListeners 方法的内部数据结构中,小心地重写通过以前调用 setActionListener 存储的任何实例。

此表达式所引用的任何方法都必须是公共的,返回类型为 void,并接受类型为 ActionEvent 的单个参数。

deprecated 此方法已由 #addActionListener(javax.faces.event.ActionListener) 替代。
英文文档:

setActionListener

public void setActionListener(MethodBinding actionListener)
Deprecated. This has been replaced by addActionListener(javax.faces.event.ActionListener).

Wrap the argument actionListener in an implementation of ActionListener and store it in the internal data structure that backs the ActionSource.getActionListeners() method, taking care to over-write any instance that was stored by a previous call to setActionListener.

Any method referenced by such an expression must be public, with a return type of void, and accept a single parameter of type ActionEvent.

Specified by:
setActionListener in interface ActionSource
Parameters:
actionListener - The new method binding expression

public boolean isImmediate()
英文文档:

isImmediate

public boolean isImmediate()
Description copied from interface: ActionSource

Return a flag indicating that the default ActionListener provided by the JavaServer Faces implementation should be executed immediately (that is, during Apply Request Values phase of the request processing lifecycle), rather than waiting until the Invoke Application phase. The default value for this property must be false.

Specified by:
isImmediate in interface ActionSource

public void setImmediate(boolean immediate)
英文文档:

setImmediate

public void setImmediate(boolean immediate)
Description copied from interface: ActionSource

Set the "immediate execution" flag for this UIComponent.

Specified by:
setImmediate in interface ActionSource
Parameters:
immediate - The new immediate execution flag

public Object getValue()

返回 UICommandvalue 属性。这通常呈现为一个标签。

英文文档:

getValue

public Object getValue()

Returns the value property of the UICommand. This is most often rendered as a label.


public void setValue(Object value)

设置 UICommandvalue 属性。这通常呈现为一个标签。

value 新值
英文文档:

setValue

public void setValue(Object value)

Sets the value property of the UICommand. This is most often rendered as a label.

Parameters:
value - the new value

public MethodExpression getActionExpression()
英文文档:

getActionExpression

public MethodExpression getActionExpression()
Description copied from interface: ActionSource2

Return the MethodExpression pointing at the application action to be invoked, if this UIComponent is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property.

Note that it's possible that the returned MethodExpression is just a wrapper around a MethodBinding instance whith was set by a call to ActionSource.setAction(javax.faces.el.MethodBinding). This makes it possible for the default ActionListener to continue to work properly with older components.

Specified by:
getActionExpression in interface ActionSource2

public void setActionExpression(MethodExpression actionExpression)
英文文档:

setActionExpression

public void setActionExpression(MethodExpression actionExpression)
Description copied from interface: ActionSource2

Set the MethodExpression pointing at the appication action to be invoked, if this UIComponent is activated by the user, during the Apply Request Values or Invoke Application phase of the request processing lifecycle, depending on the value of the immediate property.

Any method referenced by such an expression must be public, with a return type of String, and accept no parameters.

Specified by:
setActionExpression in interface ActionSource2
Parameters:
actionExpression - The new method expression

public void addActionListener(ActionListener listener)
ThrowsNullPointerException: NullPointerException 如果 listenernull
英文文档:

addActionListener

public void addActionListener(ActionListener listener)
Description copied from interface: ActionSource

Add a new ActionListener to the set of listeners interested in being notified when ActionEvents occur.

Specified by:
addActionListener in interface ActionSource
Parameters:
listener - The ActionListener to be added
Throws:
NullPointerException - if listener is null

public ActionListener[] getActionListeners()
英文文档:

getActionListeners

public ActionListener[] getActionListeners()
Description copied from interface: ActionSource

Return the set of registered ActionListeners for this ActionSource instance. If there are no registered listeners, a zero-length array is returned.

Specified by:
getActionListeners in interface ActionSource

public void removeActionListener(ActionListener listener)
ThrowsNullPointerException: NullPointerException 如果 listenernull
英文文档:

removeActionListener

public void removeActionListener(ActionListener listener)
Description copied from interface: ActionSource

Remove an existing ActionListener (if any) from the set of listeners interested in being notified when ActionEvents occur.

Specified by:
removeActionListener in interface ActionSource
Parameters:
listener - The ActionListener to be removed
Throws:
NullPointerException - if listener is null

public Object saveState(FacesContext context)
英文文档:

saveState

public Object saveState(FacesContext context)
Description copied from interface: StateHolder

Gets the state of the instance as a Serializable Object.

If the class that implements this interface has references to instances that implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.saveState(javax.faces.context.FacesContext) method on all those instances as well. This method must not save the state of children and facets. That is done via the StateManager

This method must not alter the state of the implementing object. In other words, after executing this code:

 Object state = component.saveState(facesContext);
 

component should be the same as before executing it.

The return from this method must be Serializable

Specified by:
saveState in interface StateHolder
Overrides:
saveState in class UIComponentBase

public void restoreState(FacesContext context, Object state)
英文文档:

restoreState

public void restoreState(FacesContext context,
                         Object state)
Description copied from interface: StateHolder

Perform any processing required to restore the state from the entries in the state Object.

If the class that implements this interface has references to instances that also implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.restoreState(javax.faces.context.FacesContext, java.lang.Object) method on all those instances as well.

Specified by:
restoreState in interface StateHolder
Overrides:
restoreState in class UIComponentBase

public void broadcast(FacesEvent event) throws AbortProcessingException

除了默认的 UIComponent#broadcast 处理外,将要广播的 ActionEvent 传递给 actionListener 引用的方法(如果有),以及传递给 javax.faces.application.Application 上注册的默认 ActionListener

event 要广播的 FacesEvent
ThrowsAbortProcessingException: 通知 JavaServer Face 实现不应该继续处理当前事件
ThrowsIllegalArgumentException: 如果此组件不支持此 FacesEvent 的实现类
ThrowsNullPointerException: 如果 eventnull
英文文档:

broadcast

public void broadcast(FacesEvent event)
               throws AbortProcessingException

In addition to to the default UIComponent.broadcast(javax.faces.event.FacesEvent) processing, pass the ActionEvent being broadcast to the method referenced by actionListener (if any), and to the default ActionListener registered on the Application.

Overrides:
broadcast in class UIComponentBase
Parameters:
event - FacesEvent to be broadcast
Throws:
AbortProcessingException - Signal the JavaServer Faces implementation that no further processing on the current event should be performed
IllegalArgumentException - if the implementation class of this FacesEvent is not supported by this component
NullPointerException - if event is null

public void queueEvent(FacesEvent e)

截取 ActionEventqueueEvent,且如果 immediate 标志为 true,则将事件的 phaseId 标记为 PhaseId.APPLY_REQUEST_VALUES,否则标记为 PhaseId.INVOKE_APPLICATION

英文文档:

queueEvent

public void queueEvent(FacesEvent e)

Intercept queueEvent and, for ActionEvents, mark the phaseId for the event to be PhaseId.APPLY_REQUEST_VALUES if the immediate flag is true, PhaseId.INVOKE_APPLICATION otherwise.

Overrides:
queueEvent in class UIComponentBase
Parameters:
e - FacesEvent to be queued


Submit a bug or feature

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.

一看就知道只有菜鸟才干这么无知的事啦。

PS : 未经我党受权你也可自由散发此文档。 如有任何错误请自行修正;若因此而造成任何损失请直接找人民主席,请勿与本人联系。谢谢!