org.omnifaces.util

Class Components

java.lang.Object

org.omnifaces.util.Components

public final class Components
extends java.lang.Object

Collection of utility methods for the JSF API with respect to working with UIComponent.

Author:

Bauke Scholtz, Arjan Tijms

Method Summary

Methods

Modifier and Type	Method and Description
static javax.faces.event.MethodExpressionActionListener	createActionListenerMethodExpression(java.lang.String expression) Create an action listener method expression based on the given EL expression.
static javax.faces.component.behavior.AjaxBehavior	createAjaxBehavior(java.lang.String expression) Create an ajax behavior which should invoke an ajax listener method expression based on the given EL expression.
static javax.el.MethodExpression	createMethodExpression(java.lang.String expression, java.lang.Class<?> returnType, java.lang.Class<?>... parameterTypes) Create a method expression based on the given EL expression, the given return type and the given parameter types, if any.
static javax.el.ValueExpression	createValueExpression(java.lang.String expression, java.lang.Class<?> type) Create an editable value expression based on the given EL expression and the given type.
static javax.el.MethodExpression	createVoidMethodExpression(java.lang.String expression, java.lang.Class<?>... parameterTypes) Create a void method expression based on the given EL expression and the given parameter types, if any.
static <T extends javax.faces.component.UIComponent> T	findComponent(java.lang.String clientId) Returns the UI component matching the given client ID search expression.
static <T extends javax.faces.component.UIComponent> T	findComponentInChildren(javax.faces.component.UIComponent component, java.lang.String clientId) Returns the UI component matching the given client ID search expression relative to the point in the component tree of the given component, searching only in its children.
static <T extends javax.faces.component.UIComponent> T	findComponentInParents(javax.faces.component.UIComponent component, java.lang.String clientId) Returns the UI component matching the given client ID search expression relative to the point in the component tree of the given component, searching only in its parents.
static <T extends javax.faces.component.UIComponent> T	findComponentRelatively(javax.faces.component.UIComponent component, java.lang.String clientId) Returns the UI component matching the given client ID search expression relative to the point in the component tree of the given component.
static <T extends javax.faces.component.UIComponent> java.util.List<T>	findComponentsInChildren(javax.faces.component.UIComponent component, java.lang.Class<T> type) Returns a list of UI components matching the given type in children of the given component.
static <T> T	getAttribute(javax.faces.component.UIComponent component, java.lang.String name) Returns the attribute of the given component on the given name.
static <T extends javax.faces.component.UIComponent> T	getClosestParent(javax.faces.component.UIComponent component, java.lang.Class<T> parentType) Returns from the given component the closest parent of the given parent type, or null if none is found.
static javax.faces.component.UICommand	getCurrentCommand() Returns the currently invoked UI command component, or null if there is none, which may happen when the current request is not a postback request at all, or when the view has been changed by for example a successful navigation.
static javax.faces.component.UIComponent	getCurrentComponent() Returns the current UI component from the EL context.
static javax.faces.component.UIForm	getCurrentForm() Returns the currently submitted UI form component, or null if there is none, which may happen when the current request is not a postback request at all, or when the view has been changed by for example a successful navigation.
static <T> T	getImmediateValue(javax.faces.component.UIInput input) Returns the value of the given input component whereby any unconverted submitted string value will immediately be converted/validated as this method is called.
static java.lang.String	getLabel(javax.faces.component.UIComponent input) Returns the value of the label attribute associated with the given UI component if any, else the client ID.
static java.lang.String	getOptionalLabel(javax.faces.component.UIComponent input) Returns the value of the label attribute associated with the given UI component if any, else null.
static <T> T	getValue(javax.faces.component.EditableValueHolder component) Returns the value of the given editable value holder component without the need to know if the given component has already been converted/validated or not.
static boolean	hasInvokedSubmit(javax.faces.component.UIComponent component) Returns whether the given component has invoked the form submit.
static boolean	hasSubmittedValue(javax.faces.component.EditableValueHolder component) Returns whether the given editable value holder component has a submitted value.
static javax.faces.component.UIComponent	includeCompositeComponent(javax.faces.component.UIComponent parent, java.lang.String libraryName, java.lang.String resourceName, java.lang.String id) Create and include the composite component of the given library ane resource name as child of the given UI component parent and return the created composite component.
static void	includeFacelet(javax.faces.component.UIComponent parent, java.lang.String path) Include the Facelet file at the given (relative) path as child of the given UI component parent.
static boolean	isEditable(javax.faces.component.UIInput input) Returns whether the given UI input component is editable.
static boolean	shouldVisitSkipIteration(javax.faces.component.visit.VisitContext context) Returns true if the given visit context contains the visit hint that iteration should be skipped.
static <T extends javax.faces.component.UIComponent> void	validateHasDirectParent(javax.faces.component.UIComponent component, java.lang.Class<T> parentType) Validate if the given component has a direct parent of the given parent type.
static void	validateHasNoChildren(javax.faces.component.UIComponent component) Validate if the given component has no children.
static <T extends javax.faces.component.UIComponent> void	validateHasParent(javax.faces.component.UIComponent component, java.lang.Class<T> parentType) Validate if the given component has a parent of the given parent type.

Methods inherited from class java.lang.Object

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

Method Detail

getCurrentComponent

public static javax.faces.component.UIComponent getCurrentComponent()

Returns the current UI component from the EL context.

Returns:

The current UI component from the EL context.

See Also:

UIComponent.getCurrentComponent(FacesContext)

getAttribute

public static <T> T getAttribute(javax.faces.component.UIComponent component,
                 java.lang.String name)

Returns the attribute of the given component on the given name.

Type Parameters:

T - The expected return type.

Parameters:

component - The component to return the attribute of the given name for.

name - The name of the attribute of the given component to be returned.

Returns:

The attribute of the given component on the given name.

Throws:

java.lang.ClassCastException - When T is of wrong type.

Since:

1.5

findComponent

public static <T extends javax.faces.component.UIComponent> T findComponent(java.lang.String clientId)

Returns the UI component matching the given client ID search expression.

Parameters:

clientId - The client ID search expression.

Returns:

The UI component matching the given client ID search expression.

Throws:

java.lang.ClassCastException - When T is of wrong type.

See Also:

UIComponent.findComponent(String)

findComponentRelatively

public static <T extends javax.faces.component.UIComponent> T findComponentRelatively(javax.faces.component.UIComponent component,
                                                                      java.lang.String clientId)

Returns the UI component matching the given client ID search expression relative to the point in the component tree of the given component. For this search both parents and children are consulted, increasingly moving further away from the given component. Parents are consulted first, then children.

Parameters:

component - the component from which the relative search is started.

clientId - The client ID search expression.

Returns:

The UI component matching the given client ID search expression.

Throws:

java.lang.ClassCastException - When T is of wrong type.

See Also:

UIComponent.findComponent(String)

findComponentInParents

public static <T extends javax.faces.component.UIComponent> T findComponentInParents(javax.faces.component.UIComponent component,
                                                                     java.lang.String clientId)

Returns the UI component matching the given client ID search expression relative to the point in the component tree of the given component, searching only in its parents.

Parameters:

component - the component from which the relative search is started.

clientId - The client ID search expression.

Returns:

The UI component matching the given client ID search expression.

Throws:

java.lang.ClassCastException - When T is of wrong type.

See Also:

UIComponent.findComponent(String)

findComponentInChildren

public static <T extends javax.faces.component.UIComponent> T findComponentInChildren(javax.faces.component.UIComponent component,
                                                                      java.lang.String clientId)

Returns the UI component matching the given client ID search expression relative to the point in the component tree of the given component, searching only in its children.

Parameters:

component - the component from which the relative search is started.

clientId - The client ID search expression.

Returns:

The UI component matching the given client ID search expression.

Throws:

java.lang.ClassCastException - When T is of wrong type.

See Also:

UIComponent.findComponent(String)

findComponentsInChildren

public static <T extends javax.faces.component.UIComponent> java.util.List<T> findComponentsInChildren(javax.faces.component.UIComponent component,
                                                                                       java.lang.Class<T> type)

Returns a list of UI components matching the given type in children of the given component.

Parameters:

component - The component to search in its children for UI components matching the given type.

type - The type of the UI components to be searched in children of the given component.

Returns:

A list of UI components matching the given type in children of the given component.

Throws:

java.lang.ClassCastException - When T is of wrong type.

getClosestParent

public static <T extends javax.faces.component.UIComponent> T getClosestParent(javax.faces.component.UIComponent component,
                                                               java.lang.Class<T> parentType)

Returns from the given component the closest parent of the given parent type, or null if none is found.

Type Parameters:

T - The generic parent type.

Parameters:

component - The component to return the closest parent of the given parent type for.

parentType - The parent type.

Returns:

From the given component the closest parent of the given parent type, or null if none is found.

Throws:

java.lang.ClassCastException - When T is of wrong type.

shouldVisitSkipIteration

public static boolean shouldVisitSkipIteration(javax.faces.component.visit.VisitContext context)

Returns true if the given visit context contains the visit hint that iteration should be skipped.

Parameters:

context - The involved visit context.

Since:

1.3

includeFacelet

public static void includeFacelet(javax.faces.component.UIComponent parent,
                  java.lang.String path)
                           throws java.io.IOException

Include the Facelet file at the given (relative) path as child of the given UI component parent. This has the same effect as using <ui:include>. The path is relative to the current view ID and absolute to the webcontent root.

Parameters:

parent - The parent component to include the Facelet file in.

path - The (relative) path to the Facelet file.

Throws:

java.io.IOException - Whenever something fails at I/O level. The caller should preferably not catch it, but just redeclare it in the action method. The servletcontainer will handle it.

Since:

1.5

See Also:

FaceletContext.includeFacelet(UIComponent, String)

includeCompositeComponent

public static javax.faces.component.UIComponent includeCompositeComponent(javax.faces.component.UIComponent parent,
                                                          java.lang.String libraryName,
                                                          java.lang.String resourceName,
                                                          java.lang.String id)

Create and include the composite component of the given library ane resource name as child of the given UI component parent and return the created composite component. This has the same effect as using <my:resourceName>. The given component ID must be unique relative to the current naming container parent and is mandatory for functioning of input components inside the composite, if any.

Parameters:

parent - The parent component to include the composite component in.

libraryName - The library name of the composite component.

resourceName - The resource name of the composite component.

id - The component ID of the composite component.

Returns:

The created composite component, which can if necessary be further used to set custom attributes or value expressions on it.

Since:

1.5

getCurrentForm

public static javax.faces.component.UIForm getCurrentForm()

Returns the currently submitted UI form component, or null if there is none, which may happen when the current request is not a postback request at all, or when the view has been changed by for example a successful navigation. If the latter is the case, you'd better invoke this method before navigation.

Returns:

The currently submitted UI form component.

See Also:

UIForm.isSubmitted()

getCurrentCommand

public static javax.faces.component.UICommand getCurrentCommand()

Returns the currently invoked UI command component, or null if there is none, which may happen when the current request is not a postback request at all, or when the view has been changed by for example a successful navigation. If the latter is the case, you'd better invoke this method before navigation.

Returns:

The currently invoked UI command component.

Since:

1.6

isEditable

public static boolean isEditable(javax.faces.component.UIInput input)

Returns whether the given UI input component is editable. That is when it is rendered, not disabled and not readonly.

Parameters:

input - The UI input component to be checked.

Returns:

true if the given UI input component is editable.

getLabel

public static java.lang.String getLabel(javax.faces.component.UIComponent input)

Returns the value of the label attribute associated with the given UI component if any, else the client ID. It never returns null.

Parameters:

input - The UI input component for which the label is to be retrieved.

Returns:

The value of the label attribute associated with the given UI component if any, else the client ID.

getOptionalLabel

public static java.lang.String getOptionalLabel(javax.faces.component.UIComponent input)

Returns the value of the label attribute associated with the given UI component if any, else null.

Parameters:

input - The UI input component for which the label is to be retrieved.

Returns:

The value of the label attribute associated with the given UI component if any, else null.

getValue

public static <T> T getValue(javax.faces.component.EditableValueHolder component)

Returns the value of the given editable value holder component without the need to know if the given component has already been converted/validated or not. Note that it thus returns the unconverted submitted string value when the conversion/validation hasn't been taken place for the given component and it returns the converted object value -if applicable- when conversion/validation has been taken place for the given component.

Parameters:

component - The editable value holder component to obtain the value for.

Returns:

The value of the given editable value holder component.

Throws:

java.lang.ClassCastException - When T is of wrong type.

getImmediateValue

public static <T> T getImmediateValue(javax.faces.component.UIInput input)

Returns the value of the given input component whereby any unconverted submitted string value will immediately be converted/validated as this method is called. This method thus always returns the converted/validated value.

Parameters:

input - The input component to obtain the converted/validated value for.

Returns:

The converted/validated value of the given input component.

Throws:

java.lang.ClassCastException - When T is of wrong type.

Since:

1.2

hasSubmittedValue

public static boolean hasSubmittedValue(javax.faces.component.EditableValueHolder component)

Returns whether the given editable value holder component has a submitted value.

Parameters:

component - The editable value holder component to be checked.

Returns:

true if the given editable value holder component has a submitted value, otherwise false.

hasInvokedSubmit

public static boolean hasInvokedSubmit(javax.faces.component.UIComponent component)

Returns whether the given component has invoked the form submit. In non-ajax requests, that can only be an UICommand component. In ajax requests, that can also be among others an UIInput component.

Parameters:

component - The component to be checked.

Returns:

true if the given component has invoked the form submit.

Since:

1.3

createValueExpression

public static javax.el.ValueExpression createValueExpression(java.lang.String expression,
                                             java.lang.Class<?> type)

Create an editable value expression based on the given EL expression and the given type.

Parameters:

expression - The EL expression to represent an editable value expression.

type - The type of the property referenced by the value expression.

Returns:

The created editable value expression, ready to be used as UIComponent.setValueExpression(String, ValueExpression).

createMethodExpression

public static javax.el.MethodExpression createMethodExpression(java.lang.String expression,
                                               java.lang.Class<?> returnType,
                                               java.lang.Class<?>... parameterTypes)

Create a method expression based on the given EL expression, the given return type and the given parameter types, if any. As an example, the following action method examples,

• public void submit1()
• public String submit2()
• public void submit3(String argument)
• public String submit4(String argument)
• public void submit5(String argument1, Long argument2)
• public String submit6(Long argument1, String argument2)

can be created as follows:

• createMethodExpression("#{bean.submit1}", Void.class);
• createMethodExpression("#{bean.submit2}", String.class);
• createMethodExpression("#{bean.submit3('foo')}", Void.class, String.class);
• createMethodExpression("#{bean.submit4('foo')}", String.class, String.class);
• createMethodExpression("#{bean.submit5('foo', 0)}", Void.class, String.class, Long.class);
• createMethodExpression("#{bean.submit6(0, 'foo')}", String.class, Long.class, String.class);

Parameters:

expression - The EL expression to create a method expression for.

returnType - The return type of the method expression. Can be null if you don't care about the return type (e.g. void or String).

parameterTypes - The parameter types of the method expression.

Returns:

The created method expression, ready to be used as UICommand.setActionExpression(MethodExpression).

createVoidMethodExpression

public static javax.el.MethodExpression createVoidMethodExpression(java.lang.String expression,
                                                   java.lang.Class<?>... parameterTypes)

Create a void method expression based on the given EL expression and the given parameter types, if any. As an example, the following action method examples,

• public void submit1()
• public void submit3(String argument)
• public void submit5(String argument1, Long argument2)

can be created as follows:

• createVoidMethodExpression("#{bean.submit1}");
• createVoidMethodExpression("#{bean.submit3('foo')}", String.class);
• createVoidMethodExpression("#{bean.submit5('foo', 0)}", String.class, Long.class);

Parameters:

expression - The EL expression to create a void method expression for.

parameterTypes - The parameter types of the void method expression.

Returns:

The created void method expression, ready to be used as UICommand.setActionExpression(MethodExpression).

createActionListenerMethodExpression

public static javax.faces.event.MethodExpressionActionListener createActionListenerMethodExpression(java.lang.String expression)

Create an action listener method expression based on the given EL expression. The target method must take an ActionEvent as argument. As an example, the following action method example,

• public void actionListener(ActionEvent event)

can be created as follows:

• createActionListenerMethodExpression("#{bean.actionListener}");

Parameters:

expression - The EL expression to create an action listener method expression for.

Returns:

The created action listener method expression, ready to be used as UICommand.addActionListener(javax.faces.event.ActionListener).

createAjaxBehavior

public static javax.faces.component.behavior.AjaxBehavior createAjaxBehavior(java.lang.String expression)

Create an ajax behavior which should invoke an ajax listener method expression based on the given EL expression. The target method must take an AjaxBehaviorEvent as argument. As an example, the following ajax listener example,

• public void ajaxListener(AjaxBehaviorEvent event)

can be created as follows:

• createAjaxBehavior("#{bean.ajaxListener}");

Note that this is essentially the programmatic equivalent of <f:ajax>. So if you intented to create for example a <p:ajax> programmatically, then don't use this method.

Parameters:

expression - The EL expression to be invoked when the created ajax behavior is processed.

Returns:

The created ajax behavior, ready to be used as UIComponentBase.addClientBehavior(String, ClientBehavior) whereby the string argument represents the client event name, such as "action", "valueChange", "click", "blur", etc.

validateHasParent

public static <T extends javax.faces.component.UIComponent> void validateHasParent(javax.faces.component.UIComponent component,
                                                                   java.lang.Class<T> parentType)
                              throws java.lang.IllegalArgumentException

Validate if the given component has a parent of the given parent type.

Parameters:

component - The component to be validated.

parentType - The parent type to be checked.

Throws:

java.lang.IllegalArgumentException - When the given component doesn't have any parent of the given type.

validateHasDirectParent

public static <T extends javax.faces.component.UIComponent> void validateHasDirectParent(javax.faces.component.UIComponent component,
                                                                         java.lang.Class<T> parentType)
                                    throws java.lang.IllegalArgumentException

Validate if the given component has a direct parent of the given parent type.

Parameters:

component - The component to be validated.

parentType - The parent type to be checked.

Throws:

java.lang.IllegalArgumentException - When the given component doesn't have a direct parent of the given type.

validateHasNoChildren

public static void validateHasNoChildren(javax.faces.component.UIComponent component)
                                  throws java.lang.IllegalArgumentException

Validate if the given component has no children.

Parameters:

component - The component to be validated.

Throws:

java.lang.IllegalArgumentException - When the given component has any children.