org.josef.web.jsf.util

Class JsfTreeUtil

java.lang.Object

org.josef.web.jsf.util.JsfTreeUtil

public final class JsfTreeUtil
extends Object

Java Server Faces Utility class focusing on the UI Component Tree.

Version:

1.0 $Revision: 5812 $

Author:

Kees Schotanus

Method Summary

Modifier and Type	Method and Description
static String	convertComponentForToClientFor(javax.faces.context.FacesContext context, String componentForId, javax.faces.component.UIComponent component) Utility method to convert the "component id" as used in a for attribute to a client id.
static <T extends javax.faces.component.UIComponent> List<T>	findAll(javax.faces.component.UIComponent uiComponent, Class<T> type) Finds all UI components of a certain type.
static <T extends javax.faces.component.UIComponent> List<T>	findAll(javax.faces.component.UIComponent uiComponent, Class<T> type, String attributeName) Finds all UI components of a certain type that have an attribute with the supplied attributeName.
static javax.faces.component.UIComponent	findComponent(javax.faces.component.UIComponent startingComponent, String id) Finds the component with the supplied id.
static String	getClientIdOfForm(javax.faces.context.FacesContext facesContext, javax.faces.component.UIComponent uiComponent) Gets the client id of the form in which the supplied uiComponent is nested.
static <T extends javax.faces.component.UIComponent> T	getParent(javax.faces.component.UIComponent uiComponent, Class<T> type) Gets the parent of the supplied uiComponent that is of the supplied type.
static String	toString(javax.faces.component.UIComponent uiComponent) Creates a String representation of the supplied uiComponent.
static String	toString(javax.faces.component.UIViewRoot uiViewRoot) Creates a String representation of the supplied uiViewRoot.
static void	walkTheTree(javax.faces.component.UIComponent uiComponent, UIComponentCallBack uiComponentCallBack) Walks the component tree.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getClientIdOfForm

public static String getClientIdOfForm(javax.faces.context.FacesContext facesContext,
                                       javax.faces.component.UIComponent uiComponent)

Gets the client id of the form in which the supplied uiComponent is nested.

Parameters:

facesContext - The FacesContext.

uiComponent - Component to get the form id for.

Returns:

The client id of the form in which the supplied uiComponent is nested or null when the supplied uiComponent is not nested within a form.
This may be the case when the uiComponent is an output component.

Throws:

NullPointerException - When the supplied uiComponent is null.

getParent

public static <T extends javax.faces.component.UIComponent> T getParent(javax.faces.component.UIComponent uiComponent,
                                                                        Class<T> type)

Gets the parent of the supplied uiComponent that is of the supplied type.
Getting the parent form for example can be achieved by the following code:
UIForm uiForm = JsfTreeUtil.getParent(uiComponent, UIForm.class);

Type Parameters:

T - The type the parent of the supplied uiComponent must have.

Parameters:

uiComponent - The UIComponent for which the parent component must be located.

type - The type of the parent component.

Returns:

The parent of the supplied uiComponent or null when no parent component of the supplied type exists.

Throws:

NullPointerException - When the supplied uiComponent is null.

walkTheTree

public static void walkTheTree(javax.faces.component.UIComponent uiComponent,
                               UIComponentCallBack uiComponentCallBack)

Walks the component tree.

Parameters:

uiComponent - The uiComponent to walk.

uiComponentCallBack - For each UIComponent found in the supplied uiComponent, the UIComponentCallBack.call(UIComponent, int) method is called.

Throws:

NullPointerException - When either the supplied uiViewRoot or uiComponentCallBack is null.

findAll

public static <T extends javax.faces.component.UIComponent> List<T> findAll(javax.faces.component.UIComponent uiComponent,
                                                                            Class<T> type)

Finds all UI components of a certain type. Example:

final List>UIPanel> panels = JsfTreeUtil.findAll(JsfUtil.getViewRoot(), UIPanel.class);

The code above locates all UIComponent objects of type UIPanel.

Type Parameters:

T - The type of the UIComponent to find.

Parameters:

uiComponent - The UIViewRoot to search.

type - The type of UIComponent to search.

Returns:

A List containing all the found UIComponent objects of the supplied type.

Throws:

NullPointerException - When either the supplied uiComponent or type is null.

findAll

public static <T extends javax.faces.component.UIComponent> List<T> findAll(javax.faces.component.UIComponent uiComponent,
                                                                            Class<T> type,
                                                                            String attributeName)

Finds all UI components of a certain type that have an attribute with the supplied attributeName.
Note: This method won't find the properties of a component. For example in:

<h:outputLabel for="idFor" value="..."/>

the for property wont't be found by this method. Example:

   final List>UIPanel> panels = JsfTreeUtil.findAll(JsfUtil.getViewRoot(), UIInput.class, "attributeName");
 

The code above locates all UIComponent objects of type UIInput that have an attribute named "attributeName".

Type Parameters:

T - The type of the UIComponent to find.

Parameters:

uiComponent - The uiComponent to start searching from.

type - The type of UIComponent to search.

attributeName - The name of the attribute.

Returns:

A List containing all the found UIComponent objects of the supplied type with an attribute named attributeName.

Throws:

IllegalArgumentException - When the supplied attributeName is empty.

NullPointerException - When either the supplied uiViewRoot or type or attributeName is null.

convertComponentForToClientFor

public static String convertComponentForToClientFor(javax.faces.context.FacesContext context,
                                                    String componentForId,
                                                    javax.faces.component.UIComponent component)

Utility method to convert the "component id" as used in a for attribute to a client id.
For a developer it's easier to supply a component id than a client id in a JSF page. This method aids in converting a component id to a client id. For example:

 <h:outputLabel for="idAge" value="Age:" />
 <h:panelGroup>
   <h:inputText id="idAge">
     <f:validateLength minimum="1" maximum="3" />
     <f:validateLongRange minimum="0" maximum="120" />
   </h:inputText>
   <jf:message for="idAge" />
 </h:panelGroup>

In the previous example the componentForId would contain "idAge" and the component would be the message component.

Parameters:

context - The FacesContext.

componentForId - The value of a for attribute containing a component id.
It is not an error when this parameter already contains a complete client id.

component - The component that contains the for attribute.

Returns:

The client id of the component that corresponds to the supplied componentForId.
When the supplied componentForId already contains a client id, the returned value is equal to the supplied componentForId.

Throws:

NullPointerException - When either the supplied context, componentForId or component is null.

IllegalArgumentException - When the supplied componentForId is empty.

findComponent

public static javax.faces.component.UIComponent findComponent(javax.faces.component.UIComponent startingComponent,
                                                              String id)

Finds the component with the supplied id.

Parameters:

startingComponent - The component to start the search from.

id - The id of the component to search for.

Returns:

The component with the supplied id or null when no such component exists.

Throws:

NullPointerException - When the supplied id is null.

IllegalArgumentException - When the supplied id is empty.

toString

public static String toString(javax.faces.component.UIViewRoot uiViewRoot)

Creates a String representation of the supplied uiViewRoot.

Parameters:

uiViewRoot - The UIViewRoot to create a String representation of.

Returns:

The component tree as a String.
The format of the returned String can be changed without notice.

Throws:

NullPointerException - When the supplied uiViewRoot is null.

toString

public static String toString(javax.faces.component.UIComponent uiComponent)

Creates a String representation of the supplied uiComponent.

Parameters:

uiComponent - The UI Component to create a String representation of.

Returns:

A String representation of the supplied uiComponent.