javax.faces.component
Class UIComponentBase

java.lang.Object
  extended by javax.faces.component.UIComponent
      extended by javax.faces.component.UIComponentBase
All Implemented Interfaces:
java.util.EventListener, PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder
Direct Known Subclasses:
UIColumn, UICommand, UIData, UIForm, UIGraphic, UIMessage, UIMessages, UINamingContainer, UIOutput, UIPanel, UIParameter, UISelectItem, UISelectItems, UIViewRoot

public abstract class UIComponentBase
extends UIComponent

UIComponentBase is a convenience base class that implements the default concrete behavior of all methods defined by UIComponent.

By default, this class defines getRendersChildren() to find the renderer for this component and call its getRendersChildren() method. The default implementation on the Renderer returns false. As of version 1.2 of the JavaServer Faces Specification, component authors are encouraged to return true from this method and rely on the implementation of encodeChildren(javax.faces.context.FacesContext) in this class and in the Renderer (Renderer#encodeChildren). Subclasses that wish to manage the rendering of their children should override this method to return true instead.


Field Summary
 
Fields inherited from class javax.faces.component.UIComponent
ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY
 
Constructor Summary
UIComponentBase()
           
 
Method Summary
 void addClientBehavior(java.lang.String eventName, ClientBehavior behavior)
          

This is a default implementation of ClientBehaviorHolder.addClientBehavior(java.lang.String, javax.faces.component.behavior.ClientBehavior).

protected  void addFacesListener(FacesListener listener)
          Add the specified FacesListener to the set of listeners registered to receive event notifications from this UIComponent.
 void broadcast(FacesEvent event)
          Broadcast the specified FacesEvent to all registered event listeners who have expressed an interest in events of this type.
 void clearInitialState()
          

For each of the attached objects on this instance that implement PartialStateHolder, call PartialStateHolder#clearInitialState on the attached object.

 void decode(FacesContext context)
          Decode any new state of this UIComponent from the request contained in the specified FacesContext, and store this state as needed.
 void encodeBegin(FacesContext context)
          If our rendered property is true, render the beginning of the current state of this UIComponent to the response contained in the specified FacesContext.
 void encodeChildren(FacesContext context)
          If our rendered property is true, render the child UIComponents of this UIComponent.
 void encodeEnd(FacesContext context)
          If our rendered property is true, render the ending of the current state of this UIComponent.
 UIComponent findComponent(java.lang.String expr)
          Search for and return the UIComponent with an id that matches the specified search expression (if any), according to the algorithm described below.
 java.util.Map<java.lang.String,java.lang.Object> getAttributes()
          Return a mutable Map representing the attributes (and properties, see below) associated wth this UIComponent, keyed by attribute name (which must be a String).
 int getChildCount()
          Return the number of child UIComponents that are associated with this UIComponent.
 java.util.List<UIComponent> getChildren()
          Return a mutable List representing the child UIComponents associated with this component.
 java.util.Map<java.lang.String,java.util.List<ClientBehavior>> getClientBehaviors()
          

This is a default implementation of ClientBehaviorHolder.getClientBehaviors().

 java.lang.String getClientId(FacesContext context)
          Return a client-side identifier for this component, generating one if necessary.
 java.lang.String getDefaultEventName()
          

This is a default implementation of ClientBehaviorHolder.getDefaultEventName().

 java.util.Collection<java.lang.String> getEventNames()
          

This is a default implementation of ClientBehaviorHolder.getEventNames().

protected  FacesContext getFacesContext()
          Convenience method to return the FacesContext instance for the current request.
protected  FacesListener[] getFacesListeners(java.lang.Class clazz)
          Return an array of registered FacesListeners that are instances of the specified class.
 UIComponent getFacet(java.lang.String name)
          Convenience method to return the named facet, if it exists, or null otherwise.
 int getFacetCount()
          Return the number of facet UIComponents that are associated with this UIComponent.
 java.util.Map<java.lang.String,UIComponent> getFacets()
          Return a mutable Map representing the facet UIComponents associated with this UIComponent, keyed by facet name (which must be a String).
 java.util.Iterator<UIComponent> getFacetsAndChildren()
          Return an Iterator over the facet followed by child UIComponents of this UIComponent.
 java.lang.String getId()
          Return the component identifier of this UIComponent.
 java.util.List<SystemEventListener> getListenersForEventClass(java.lang.Class<? extends SystemEvent> eventClass)
          

Return the SystemEventListener instances registered on this UIComponent instance that are interested in events of type eventClass.

 UIComponent getParent()
          Return the parent UIComponent of this UIComponent, if any.
protected  Renderer getRenderer(FacesContext context)
          Convenience method to return the Renderer instance associated with this component, if any; otherwise, return null.
 java.lang.String getRendererType()
          Return the Renderer type for this UIComponent (if any).
 boolean getRendersChildren()
          Return a flag indicating whether this component is responsible for rendering its child components.
 ValueBinding getValueBinding(java.lang.String name)
          Deprecated. This has been replaced by UIComponent.getValueExpression(java.lang.String).
 boolean invokeOnComponent(FacesContext context, java.lang.String clientId, ContextCallback callback)
          Starting at this component in the View hierarchy, search for a component with a clientId equal to the argument clientId and, if found, call the ContextCallback#invokeContextCallback method on the argument callback, passing the current FacesContext and the found component as arguments.
 boolean isRendered()
          Return true if this component (and its children) should be rendered during the Render Response phase of the request processing lifecycle.
 boolean isTransient()
          If true, the Object implementing this interface must not participate in state saving or restoring.
 void markInitialState()
          

For each of the attached objects on this instance that implement PartialStateHolder, call PartialStateHolder#markInitialState on the attached object.

 void processDecodes(FacesContext context)
          Perform the component tree processing required by the Apply Request Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
 void processRestoreState(FacesContext context, java.lang.Object state)
          Perform the component tree processing required by the Restore View phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
 java.lang.Object processSaveState(FacesContext context)
          Perform the component tree processing required by the state saving portion of the Render Response phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
 void processUpdates(FacesContext context)
          Perform the component tree processing required by the Update Model Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
 void processValidators(FacesContext context)
          Perform the component tree processing required by the Process Validations phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.
 void queueEvent(FacesEvent event)
          Queue an event for broadcast at the end of the current request processing lifecycle phase.
protected  void removeFacesListener(FacesListener listener)
          Remove the specified FacesListener from the set of listeners registered to receive event notifications from this UIComponent.
static java.lang.Object restoreAttachedState(FacesContext context, java.lang.Object stateObj)
          This method is called by UIComponent subclasses that need to restore the objects they saved using saveAttachedState(javax.faces.context.FacesContext, java.lang.Object).
 void restoreState(FacesContext context, java.lang.Object state)
          Perform any processing required to restore the state from the entries in the state Object.
static java.lang.Object saveAttachedState(FacesContext context, java.lang.Object attachedObject)
          

This method is called by UIComponent subclasses that want to save one or more attached objects.

 java.lang.Object saveState(FacesContext context)
           Gets the state of the instance as a Serializable Object.
 void setId(java.lang.String id)
          Set the component identifier of this UIComponent (if any).
 void setParent(UIComponent parent)
          

Set the parent UIComponent of this UIComponent.

 void setRendered(boolean rendered)
          Set the rendered property of this UIComponent.
 void setRendererType(java.lang.String rendererType)
          Set the Renderer type for this UIComponent, or null for components that render themselves.
 void setTransient(boolean transientFlag)
          Denotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.
 void setValueBinding(java.lang.String name, ValueBinding binding)
          Deprecated. This has been replaced by UIComponent.setValueExpression(java.lang.String, javax.el.ValueExpression).
 void subscribeToEvent(java.lang.Class<? extends SystemEvent> eventClass, ComponentSystemEventListener componentListener)
          

Install the listener instance referenced by argument componentListener as a listener for events of type eventClass originating from this specific instance of UIComponent.

 void unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> eventClass, ComponentSystemEventListener componentListener)
          

Remove the listener instance referenced by argument componentListener as a listener for events of type eventClass originating from this specific instance of UIComponent.

 
Methods inherited from class javax.faces.component.UIComponent
encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getFamily, getNamingContainer, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, setValueExpression, visitTree
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

UIComponentBase

public UIComponentBase()
Method Detail

getAttributes

public java.util.Map<java.lang.String,java.lang.Object> getAttributes()
Description copied from class: UIComponent

Return a mutable Map representing the attributes (and properties, see below) associated wth this UIComponent, keyed by attribute name (which must be a String). The returned implementation must support all of the standard and optional Map methods, plus support the following additional requirements:

Specified by:
getAttributes in class UIComponent

getValueBinding

public ValueBinding getValueBinding(java.lang.String name)
Deprecated. This has been replaced by UIComponent.getValueExpression(java.lang.String).

Call through to UIComponent.getValueExpression(java.lang.String) and examine the result. If the result is an instance of the wrapper class mandated in UIComponent.setValueBinding(java.lang.String, javax.faces.el.ValueBinding), extract the ValueBinding instance and return it. Otherwise, wrap the result in an implementation of ValueBinding, and return it.

Specified by:
getValueBinding in class UIComponent
Parameters:
name - Name of the attribute or property for which to retrieve a ValueBinding
Throws:
java.lang.NullPointerException - if name is null

setValueBinding

public void setValueBinding(java.lang.String name,
                            ValueBinding binding)
Deprecated. This has been replaced by UIComponent.setValueExpression(java.lang.String, javax.el.ValueExpression).

Wrap the argument binding in an implementation of ValueExpression and call through to UIComponent.setValueExpression(java.lang.String, javax.el.ValueExpression).

Specified by:
setValueBinding in class UIComponent
Parameters:
name - Name of the attribute or property for which to set a ValueBinding
binding - The ValueBinding to set, or null to remove any currently set ValueBinding
Throws:
IllegalArgumentException - if name is one of id or parent
java.lang.NullPointerException - if name is null

getClientId

public java.lang.String getClientId(FacesContext context)
Description copied from class: UIComponent

Return a client-side identifier for this component, generating one if necessary. The associated Renderer, if any, will be asked to convert the clientId to a form suitable for transmission to the client.

The return from this method must be the same value throughout the lifetime of the instance, unless the id property of the component is changed, or the component is placed in a NamingContainer whose client ID changes (for example, UIData). However, even in these cases, consecutive calls to this method must always return the same value. The implementation must follow these steps in determining the clientId:

Find the closest ancestor to this component in the view hierarchy that implements NamingContainer. Call getContainerClientId() on it and save the result as the parentId local variable. Call UIComponent.getId() on this component and save the result as the myId local variable. If myId is null, call context.getViewRoot().createUniqueId() and assign the result to myId. If parentId is non-null, let myId equal parentId + UINamingContainer#getSeparatorChar + myId. Call Renderer#convertClientId, passing myId, and return the result.

Specified by:
getClientId in class UIComponent
Parameters:
context - The FacesContext for the current request
Throws:
java.lang.NullPointerException - if context is null

getId

public java.lang.String getId()
Description copied from class: UIComponent

Return the component identifier of this UIComponent.

Specified by:
getId in class UIComponent

setId

public void setId(java.lang.String id)
Description copied from class: UIComponent

Set the component identifier of this UIComponent (if any). Component identifiers must obey the following syntax restrictions:

Component identifiers must also obey the following semantic restrictions (note that this restriction is NOT enforced by the setId() implementation):

Specified by:
setId in class UIComponent
Parameters:
id - The new component identifier, or null to indicate that this UIComponent does not have a component identifier
Throws:
IllegalArgumentException - if id is not syntactically valid
IllegalStateException

getParent

public UIComponent getParent()
Description copied from class: UIComponent

Return the parent UIComponent of this UIComponent, if any. A component must allow child components to be added to and removed from the list of children of this component, even though the child component returns null from getParent( ).

Specified by:
getParent in class UIComponent

setParent

public void setParent(UIComponent parent)
Description copied from class: UIComponent

Set the parent UIComponent of this UIComponent. If parent.isInView() returns true, calling this method will first cause a PreRemoveFromViewEvent to be published, for this node, and then the children of this node. Then, once the re-parenting has occurred, a PostAddToViewEvent will be published as well, first for this node, and then for the node's children, but only if any of the following conditions are true.

This method must never be called by developers; a UIComponent's internal implementation will call it as components are added to or removed from a parent's child List or facet Map.

Specified by:
setParent in class UIComponent
Parameters:
parent - The new parent, or null for the root node of a component tree

isRendered

public boolean isRendered()
Description copied from class: UIComponent

Return true if this component (and its children) should be rendered during the Render Response phase of the request processing lifecycle.

Specified by:
isRendered in class UIComponent

setRendered

public void setRendered(boolean rendered)
Description copied from class: UIComponent

Set the rendered property of this UIComponent.

Specified by:
setRendered in class UIComponent
Parameters:
rendered - If true render this component; otherwise, do not render this component

getRendererType

public java.lang.String getRendererType()
Description copied from class: UIComponent

Return the Renderer type for this UIComponent (if any).

Specified by:
getRendererType in class UIComponent

setRendererType

public void setRendererType(java.lang.String rendererType)
Description copied from class: UIComponent

Set the Renderer type for this UIComponent, or null for components that render themselves.

Specified by:
setRendererType in class UIComponent
Parameters:
rendererType - Logical identifier of the type of Renderer to use, or null for components that render themselves

getRendersChildren

public boolean getRendersChildren()
Description copied from class: UIComponent

Return a flag indicating whether this component is responsible for rendering its child components. The default implementation in UIComponentBase#getRendersChildren tries to find the renderer for this component. If it does, it calls Renderer#getRendersChildren and returns the result. If it doesn't, it returns false. As of version 1.2 of the JavaServer Faces Specification, component authors are encouraged to return true from this method and rely on UIComponentBase#encodeChildren.

Specified by:
getRendersChildren in class UIComponent

getChildren

public java.util.List<UIComponent> getChildren()
Description copied from class: UIComponent

Return a mutable List representing the child UIComponents associated with this component. The returned implementation must support all of the standard and optional List methods, plus support the following additional requirements:

Specified by:
getChildren in class UIComponent

getChildCount

public int getChildCount()
Description copied from class: UIComponent

Return the number of child UIComponents that are associated with this UIComponent. If there are no children, this method must return 0. The method must not cause the creation of a child component list.

Specified by:
getChildCount in class UIComponent

findComponent

public UIComponent findComponent(java.lang.String expr)
Description copied from class: UIComponent

Search for and return the UIComponent with an id that matches the specified search expression (if any), according to the algorithm described below.

For a method to find a component given a simple clientId, see UIComponent.invokeOnComponent(javax.faces.context.FacesContext, java.lang.String, javax.faces.component.ContextCallback).

Component identifiers are required to be unique within the scope of the closest ancestor NamingContainer that encloses this component (which might be this component itself). If there are no NamingContainer components in the ancestry of this component, the root component in the tree is treated as if it were a NamingContainer, whether or not its class actually implements the NamingContainer interface.

A search expression consists of either an identifier (which is matched exactly against the id property of a UIComponent, or a series of such identifiers linked by the UINamingContainer#getSeparatorChar character value. The search algorithm should operates as follows, though alternate alogrithms may be used as long as the end result is the same:

Specified by:
findComponent in class UIComponent
Parameters:
expr - Search expression identifying the UIComponent to be returned
Returns:
the found UIComponent, or null if the component was not found.
Throws:
java.lang.NullPointerException - if expr is null

invokeOnComponent

public boolean invokeOnComponent(FacesContext context,
                                 java.lang.String clientId,
                                 ContextCallback callback)
                          throws FacesException

Starting at this component in the View hierarchy, search for a component with a clientId equal to the argument clientId and, if found, call the ContextCallback#invokeContextCallback method on the argument callback, passing the current FacesContext and the found component as arguments. This method is similar to UIComponent.findComponent(java.lang.String) but it does not support the leading UINamingContainer#getSeparatorChar syntax for searching from the root of the View.

The default implementation will first check if this.getClientId() is equal to the argument clientId. If so, first call UIComponent.pushComponentToEL(javax.faces.context.FacesContext, javax.faces.component.UIComponent), then call the ContextCallback#invokeContextCallback method on the argument callback, passing through the FacesContext argument and passing this as the component argument. Then call UIComponent.popComponentFromEL(javax.faces.context.FacesContext). If an Exception is thrown by the callback, wrap it in a FacesException and re-throw it. Otherwise, return true.

Otherwise, for each component returned by UIComponent.getFacetsAndChildren(), call invokeOnComponent() passing the arguments to this method, in order. The first time invokeOnComponent() returns true, abort traversing the rest of the Iterator and return true.

When calling ContextCallback#invokeContextCallback the implementation of this method must guarantee that the state of the component passed to the callback correctly reflects the component's position in the View hierarchy with respect to any state found in the argument clientId. For example, an iterating component such as UIData will need to set its row index to correctly reflect the argument clientId before finding the appropriate child component backed by the correct row. When the callback returns, either normally or by throwing an Exception the implementation of this method must restore the state of the view to the way it was before invoking the callback.

If none of the elements from UIComponent.getFacetsAndChildren() returned true from invokeOnComponent(), return false.

Simple usage example to find a component by clientId.


private UIComponent found = null;

private void doFind(FacesContext context, String clientId) {
  context.getViewRoot().invokeOnComponent(context, clientId,
      new ContextCallback() {
         public void invokeContextCallback(FacesContext context,
                                       UIComponent component) {
           found = component;
         }
      });
}
 

Overrides:
invokeOnComponent in class UIComponent
Parameters:
context - the FacesContext for the current request
clientId - the client identifier of the component to be passed to the argument callback.
callback - an implementation of the Callback interface.
Returns:
true if the a component with the given clientId is found, the callback method was successfully invoked passing that component as an argument, and no Exception was thrown. Returns false if no component with the given clientId is found.
Throws:
java.lang.NullPointerException - if any of the arguments are null
FacesException - if the argument Callback throws an Exception, it is wrapped in a FacesException and re-thrown.
Since:
1.2

getFacets

public java.util.Map<java.lang.String,UIComponent> getFacets()
Description copied from class: UIComponent

Return a mutable Map representing the facet UIComponents associated with this UIComponent, keyed by facet name (which must be a String). The returned implementation must support all of the standard and optional Map methods, plus support the following additional requirements:

Specified by:
getFacets in class UIComponent

getFacetCount

public int getFacetCount()
Description copied from class: UIComponent

Return the number of facet UIComponents that are associated with this UIComponent. If there are no facets, this method must return 0. The method must not cause the creation of a facet component map.

For backwards compatability with classes that extend UIComponent directly, a default implementation is provided that simply calls UIComponent.getFacets() and then calls the size() method on the returned Map. A more optimized version of this method is provided in UIComponentBase#getFacetCount.

Overrides:
getFacetCount in class UIComponent

getFacet

public UIComponent getFacet(java.lang.String name)
Description copied from class: UIComponent

Convenience method to return the named facet, if it exists, or null otherwise. If the requested facet does not exist, the facets Map must not be created.

Specified by:
getFacet in class UIComponent
Parameters:
name - Name of the desired facet

getFacetsAndChildren

public java.util.Iterator<UIComponent> getFacetsAndChildren()
Description copied from class: UIComponent

Return an Iterator over the facet followed by child UIComponents of this UIComponent. Facets are returned in an undefined order, followed by all the children in the order they are stored in the child list. If this component has no facets or children, an empty Iterator is returned.

The returned Iterator must not support the remove() operation.

Specified by:
getFacetsAndChildren in class UIComponent

broadcast

public void broadcast(FacesEvent event)
               throws AbortProcessingException
Description copied from class: UIComponent

Broadcast the specified FacesEvent to all registered event listeners who have expressed an interest in events of this type. Listeners are called in the order in which they were added.

If the event is an instance of BehaviorEvent and the current component is the source of the event call BehaviorEvent.getBehavior() to get the Behavior for the event. Call Behavior.broadcast(javax.faces.event.BehaviorEvent) on the Behavior instance.

Specified by:
broadcast in class UIComponent
Parameters:
event - The FacesEvent to be broadcast
Throws:
AbortProcessingException - Signal the JavaServer Faces implementation that no further processing on the current event should be performed
IllegalStateException
java.lang.NullPointerException - if event is null

decode

public void decode(FacesContext context)
Description copied from class: UIComponent

Decode any new state of this UIComponent from the request contained in the specified FacesContext, and store this state as needed.

During decoding, events may be enqueued for later processing (by event listeners who have registered an interest), by calling queueEvent().

Specified by:
decode in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
java.lang.NullPointerException - if context is null

encodeBegin

public void encodeBegin(FacesContext context)
                 throws java.io.IOException
Description copied from class: UIComponent

If our rendered property is true, render the beginning of the current state of this UIComponent to the response contained in the specified FacesContext. Call UIComponent.pushComponentToEL(javax.faces.context.FacesContext,javax.faces.component.UIComponent). Call Application.publishEvent(javax.faces.context.FacesContext, java.lang.Class, java.lang.Object), passing PreRenderComponentEvent.class as the first argument and the component instance to be rendered as the second argument.

If a Renderer is associated with this UIComponent, the actual encoding will be delegated to Renderer#encodeBegin(FacesContext, UIComponent).

If our rendered property is false, call UIComponent.pushComponentToEL(javax.faces.context.FacesContext,javax.faces.component.UIComponent) and return immediately.

Specified by:
encodeBegin in class UIComponent
Parameters:
context - FacesContext for the response we are creating
Throws:
java.lang.NullPointerException - if context is null
java.io.IOException - if an input/output error occurs while rendering

encodeChildren

public void encodeChildren(FacesContext context)
                    throws java.io.IOException
Description copied from class: UIComponent

If our rendered property is true, render the child UIComponents of this UIComponent. This method will only be called if the rendersChildren property is true.

If a Renderer is associated with this UIComponent, the actual encoding will be delegated to Renderer#encodeChildren(FacesContext, UIComponent). If no Renderer is associated with this UIComponent, iterate over each of the children of this component and call UIComponent.encodeAll(javax.faces.context.FacesContext).

Specified by:
encodeChildren in class UIComponent
Parameters:
context - FacesContext for the response we are creating
Throws:
java.lang.NullPointerException - if context is null
java.io.IOException - if an input/output error occurs while rendering

encodeEnd

public void encodeEnd(FacesContext context)
               throws java.io.IOException
Description copied from class: UIComponent

If our rendered property is true, render the ending of the current state of this UIComponent.

If a Renderer is associated with this UIComponent, the actual encoding will be delegated to Renderer#encodeEnd(FacesContext, UIComponent).

Call UIComponent#popComponentFromEL. before returning regardless of the value of the rendered property.

Specified by:
encodeEnd in class UIComponent
Parameters:
context - FacesContext for the response we are creating
Throws:
java.io.IOException - if an input/output error occurs while rendering
java.lang.NullPointerException - if context is null

addFacesListener

protected void addFacesListener(FacesListener listener)

Add the specified FacesListener to the set of listeners registered to receive event notifications from this UIComponent. It is expected that UIComponent classes acting as event sources will have corresponding typesafe APIs for registering listeners of the required type, and the implementation of those registration methods will delegate to this method. For example:

 public class FooEvent extends FacesEvent {
   ...
   protected boolean isAppropriateListener(FacesListener listener) {
     return (listener instanceof FooListener);
   }
   protected void processListener(FacesListener listener) {
     ((FooListener) listener).processFoo(this);
   }
   ...
 }
 

public interface FooListener extends FacesListener { public void processFoo(FooEvent event); }

public class FooComponent extends UIComponentBase { ... public void addFooListener(FooListener listener) { addFacesListener(listener); } public void removeFooListener(FooListener listener) { removeFacesListener(listener); } ... }

Specified by:
addFacesListener in class UIComponent
Parameters:
listener - The FacesListener to be registered
Throws:
java.lang.NullPointerException - if listener is null

getFacesListeners

protected FacesListener[] getFacesListeners(java.lang.Class clazz)
Description copied from class: UIComponent

Return an array of registered FacesListeners that are instances of the specified class. If there are no such registered listeners, a zero-length array is returned. The returned array can be safely be cast to an array strongly typed to an element type of clazz.

Specified by:
getFacesListeners in class UIComponent
Parameters:
clazz - Class that must be implemented by a FacesListener for it to be returned
Throws:
IllegalArgumentException - if class is not, and does not implement, FacesListener
java.lang.NullPointerException - if clazz is null

removeFacesListener

protected void removeFacesListener(FacesListener listener)

Remove the specified FacesListener from the set of listeners registered to receive event notifications from this UIComponent.

Specified by:
removeFacesListener in class UIComponent
Parameters:
listener - The FacesListener to be deregistered
Throws:
java.lang.NullPointerException - if listener is null

queueEvent

public void queueEvent(FacesEvent event)
Description copied from class: UIComponent

Queue an event for broadcast at the end of the current request processing lifecycle phase. The default implementation in UIComponentBase must delegate this call to the queueEvent() method of the parent UIComponent.

Specified by:
queueEvent in class UIComponent
Parameters:
event - FacesEvent to be queued
Throws:
IllegalStateException - if this component is not a descendant of a UIViewRoot
java.lang.NullPointerException - if event is null

subscribeToEvent

public void subscribeToEvent(java.lang.Class<? extends SystemEvent> eventClass,
                             ComponentSystemEventListener componentListener)

Install the listener instance referenced by argument componentListener as a listener for events of type eventClass originating from this specific instance of UIComponent. The default implementation creates an inner SystemEventListener instance that wraps argument componentListener as the listener argument. This inner class must call through to the argument componentListener in its implementation of SystemEventListener#processEvent and its implementation of SystemEventListener#isListenerForSource must return true if the instance class of this UIComponent is assignable from the argument to isListenerForSource.

Overrides:
subscribeToEvent in class UIComponent
Parameters:
eventClass - the Class of event for which listener must be fired.
componentListener - the implementation of ComponentSystemEventListener whose ComponentSystemEventListener.processEvent(javax.faces.event.ComponentSystemEvent) method must be called when events of type facesEventClass are fired.
Throws:
NullPointerException - if any of the arguments are null.
Since:
2.1

unsubscribeFromEvent

public void unsubscribeFromEvent(java.lang.Class<? extends SystemEvent> eventClass,
                                 ComponentSystemEventListener componentListener)

Remove the listener instance referenced by argument componentListener as a listener for events of type eventClass originating from this specific instance of UIComponent. When doing the comparison to determine if an existing listener is equal to the argument componentListener (and thus must be removed), the equals() method on the existing listener must be invoked, passing the argument componentListener, rather than the other way around.

Overrides:
unsubscribeFromEvent in class UIComponent
Parameters:
eventClass - the Class of event for which listener must be removed.
componentListener - the implementation of ComponentSystemEventListener whose ComponentSystemEventListener#processEvent method must no longer be called when events of type eventClass are fired.
Throws:
NullPointerException - if any of the arguments are null.
Since:
2.1

getListenersForEventClass

public java.util.List<SystemEventListener> getListenersForEventClass(java.lang.Class<? extends SystemEvent> eventClass)

Return the SystemEventListener instances registered on this UIComponent instance that are interested in events of type eventClass.

Specified by:
getListenersForEventClass in interface SystemEventListenerHolder
Overrides:
getListenersForEventClass in class UIComponent
Parameters:
eventClass - the Class of event for which the listeners must be returned.
Throws:
java.lang.NullPointerException - if argument eventClass is null.
Since:
2.1

processDecodes

public void processDecodes(FacesContext context)
Description copied from class: UIComponent

Perform the component tree processing required by the Apply Request Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.

Specified by:
processDecodes in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
java.lang.NullPointerException - if context is null

processValidators

public void processValidators(FacesContext context)
Description copied from class: UIComponent

Perform the component tree processing required by the Process Validations phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.

Specified by:
processValidators in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
java.lang.NullPointerException - if context is null

processUpdates

public void processUpdates(FacesContext context)
Description copied from class: UIComponent

Perform the component tree processing required by the Update Model Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.

Specified by:
processUpdates in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
java.lang.NullPointerException - if context is null

processSaveState

public java.lang.Object processSaveState(FacesContext context)
Description copied from class: UIComponent

Perform the component tree processing required by the state saving portion of the Render Response phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.

This method may not be called if the state saving method is set to server.

Specified by:
processSaveState in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
java.lang.NullPointerException - if context is null

processRestoreState

public void processRestoreState(FacesContext context,
                                java.lang.Object state)
Description copied from class: UIComponent

Perform the component tree processing required by the Restore View phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself, as follows.

This method may not be called if the state saving method is set to server.

Specified by:
processRestoreState in class UIComponent
Parameters:
context - FacesContext for the request we are processing
Throws:
java.lang.NullPointerException - if context is null

getFacesContext

protected FacesContext getFacesContext()
Description copied from class: UIComponent

Convenience method to return the FacesContext instance for the current request.

Specified by:
getFacesContext in class UIComponent

getRenderer

protected Renderer getRenderer(FacesContext context)
Description copied from class: UIComponent

Convenience method to return the Renderer instance associated with this component, if any; otherwise, return null.

Specified by:
getRenderer in class UIComponent
Parameters:
context - FacesContext for the current request

markInitialState

public void markInitialState()

For each of the attached objects on this instance that implement PartialStateHolder, call PartialStateHolder#markInitialState on the attached object.

Specified by:
markInitialState in interface PartialStateHolder
Overrides:
markInitialState in class UIComponent
Since:
2.0

clearInitialState

public void clearInitialState()

For each of the attached objects on this instance that implement PartialStateHolder, call PartialStateHolder#clearInitialState on the attached object.

Specified by:
clearInitialState in interface PartialStateHolder
Overrides:
clearInitialState in class UIComponent
Since:
2.0

saveState

public java.lang.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


restoreState

public void restoreState(FacesContext context,
                         java.lang.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.

If the state argument is null, take no action and return.


isTransient

public boolean isTransient()
Description copied from interface: StateHolder

If true, the Object implementing this interface must not participate in state saving or restoring.


setTransient

public void setTransient(boolean transientFlag)
Description copied from interface: StateHolder

Denotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.

Parameters:
transientFlag - boolean pass true if this Object will not participate in state saving or restoring, otherwise pass false.

saveAttachedState

public static java.lang.Object saveAttachedState(FacesContext context,
                                                 java.lang.Object attachedObject)

This method is called by UIComponent subclasses that want to save one or more attached objects. It is a convenience method that does the work of saving attached objects that may or may not implement the StateHolder interface. Using this method implies the use of restoreAttachedState(javax.faces.context.FacesContext, java.lang.Object) to restore the attached objects.

This method supports saving attached objects of the following type: Objects, null values, and Collections of these objects. If any contained objects are not Collections and do not implement StateHolder, they must have zero-argument public constructors. The exact structure of the returned object is undefined and opaque, but will be serializable.

Parameters:
context - the FacesContext for this request.
attachedObject - the object, which may be a List instance, or an Object. The attachedObject (or the elements that comprise attachedObject may implement StateHolder.
Throws:
java.lang.NullPointerException - if the context argument is null.

restoreAttachedState

public static java.lang.Object restoreAttachedState(FacesContext context,
                                                    java.lang.Object stateObj)
                                             throws java.lang.IllegalStateException

This method is called by UIComponent subclasses that need to restore the objects they saved using saveAttachedState(javax.faces.context.FacesContext, java.lang.Object). This method is tightly coupled with saveAttachedState(javax.faces.context.FacesContext, java.lang.Object).

This method supports restoring all attached objects types supported by saveAttachedState(javax.faces.context.FacesContext, java.lang.Object).

Parameters:
context - the FacesContext for this request
stateObj - the opaque object returned from saveAttachedState(javax.faces.context.FacesContext, java.lang.Object)
Throws:
java.lang.NullPointerException - if context is null.
IllegalStateException - if the object is not previously returned by saveAttachedState(javax.faces.context.FacesContext, java.lang.Object).

addClientBehavior

public void addClientBehavior(java.lang.String eventName,
                              ClientBehavior behavior)

This is a default implementation of ClientBehaviorHolder.addClientBehavior(java.lang.String, javax.faces.component.behavior.ClientBehavior). UIComponent does not implement the ClientBehaviorHolder interface, but provides default implementations for the methods defined by ClientBehaviorHolder to simplify subclass implementations. Subclasses that wish to support the ClientBehaviorHolder contract must declare that the subclass implements ClientBehaviorHolder, and must provide an implementation of ClientBehaviorHolder.getEventNames().

Parameters:
eventName - the logical name of the client-side event to attach the behavior to.
behavior - the Behavior instance to attach for the specified event name.
Since:
2.0

getEventNames

public java.util.Collection<java.lang.String> getEventNames()

This is a default implementation of ClientBehaviorHolder.getEventNames(). UIComponent does not implement the ClientBehaviorHolder interface, but provides default implementations for the methods defined by ClientBehaviorHolder to simplify subclass implementations. Subclasses that wish to support the ClientBehaviorHolder contract must declare that the subclass implements ClientBehaviorHolder, and must override this method to return a non-Empty Collection of the client event names that the component supports.

Since:
2.0

getClientBehaviors

public java.util.Map<java.lang.String,java.util.List<ClientBehavior>> getClientBehaviors()

This is a default implementation of ClientBehaviorHolder.getClientBehaviors(). UIComponent does not implement the ClientBehaviorHolder interface, but provides default implementations for the methods defined by ClientBehaviorHolder to simplify subclass implementations. Subclasses that wish to support the ClientBehaviorHolder contract must declare that the subclass implements ClientBehaviorHolder, and must add an implementation of ClientBehaviorHolder.getEventNames().

Since:
2.0

getDefaultEventName

public java.lang.String getDefaultEventName()

This is a default implementation of ClientBehaviorHolder.getDefaultEventName(). UIComponent does not implement the ClientBehaviorHolder interface, but provides default implementations for the methods defined by ClientBehaviorHolder to simplify subclass implementations. Subclasses that wish to support the ClientBehaviorHolder contract must declare that the subclass implements ClientBehaviorHolder, and must provide an implementation of ClientBehaviorHolder.getEventNames().



Submit a bug or feature

Copyright © 2009-2011, Oracle Corporation and/or its affiliates. All Rights Reserved. Use is subject to license terms.

Generated on 10-February-2011 12:41