Module jakarta.faces

Package jakarta.faces.component.search

Class SearchExpressionHandler

java.lang.Object

jakarta.faces.component.search.SearchExpressionHandler

Direct Known Subclasses:

SearchExpressionHandlerImpl, SearchExpressionHandlerWrapper

public abstract class SearchExpressionHandler
extends Object

The SearchExpressionHandler is responsible for resolving search expression(s)

A search expression consists of either an identifier (which is matched exactly against the id property of a UIComponent, or a keyword (like @this or @form), or a series of such identifiers and keywords linked by the UINamingContainer.getSeparatorChar(jakarta.faces.context.FacesContext) character value. See SearchKeywordResolver for the list of supported keywords. The search algorithm must operate as follows, though alternate alogrithms may be used as long as the end result is the same:

• Identify the UIComponent that will be the base for searching:
  • If the search expression begins with the separator character (called an "absolute" search expression), the base will be the UIViewRoot. The leading separator character will be stripped off, and the remainder of the search expression will be treated as a "relative" search expression as described below.
  • Otherwise, the SearchExpressionContext.getSource() will be used.
• The search expression (possibly modified in the previous step) is now a "relative" search expression that will be used to locate the component (if any) based on the identifier and/or keywords:
  • The expression will be splitted by UINamingContainer.getSeparatorChar(jakarta.faces.context.FacesContext) into "commands". The commands will be resolved one by one. For the first command, the source component, like mentioned above, will be used to start the lookup. For all further commands, the previous resolved component, from the previous command, will be used the start the lookup.
  • If the command starts with the KEYWORD_PREFIX, then it is considered as a keyword and the SearchKeywordResolvers will be used the resolve the keyword.
  • Otherwise, if the command does not start with KEYWORD_PREFIX, then the component will be resolved based on the component ID.

Since:

2.3

Field Summary

Fields

Modifier and Type	Field	Description
protected static final char[]	EXPRESSION_SEPARATOR_CHARS	The default characters used to separate expressions in a series of expressions.
static final String	KEYWORD_PREFIX	The prefix to identify a keyword.

Constructor Summary

Constructors

Constructor	Description
SearchExpressionHandler()

Method Summary

Modifier and Type	Method	Description
char[]	getExpressionSeperatorChars(FacesContext context)	Return the characters used to separate expressions in a series of expressions.
abstract void	invokeOnComponent(SearchExpressionContext searchExpressionContext, UIComponent previous, String expression, ContextCallback callback)	Resolves multiple UIComponents for the given expression.
void	invokeOnComponent(SearchExpressionContext searchExpressionContext, String expression, ContextCallback callback)	Resolves multiple UIComponents for the given expression.
abstract boolean	isPassthroughExpression(SearchExpressionContext searchExpressionContext, String expression)	Checks if the given expression is a "passtrough expression".
abstract boolean	isValidExpression(SearchExpressionContext searchExpressionContext, String expression)	Checks if the given expression is a valid expression.
abstract String	resolveClientId(SearchExpressionContext searchExpressionContext, String expression)	Resolves to a single clientId or passthrough expression for the given expression.
abstract List<String>	resolveClientIds(SearchExpressionContext searchExpressionContext, String expressions)	Resolves to a List with clientIds or passthrough expressions for the given expressions.
abstract void	resolveComponent(SearchExpressionContext searchExpressionContext, String expression, ContextCallback callback)	Resolves a single UIComponents for the given expression.
abstract void	resolveComponents(SearchExpressionContext searchExpressionContext, String expressions, ContextCallback callback)	Resolves multiple UIComponents for the given expression(s).
abstract String[]	splitExpressions(FacesContext context, String expressions)	Splits an string, based on getExpressionSeperatorChars(jakarta.faces.context.FacesContext) with possible multiple expressions into an array.

Methods inherited from class java.lang.Object

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

Field Details

KEYWORD_PREFIX

public static final String KEYWORD_PREFIX

The prefix to identify a keyword.

Since:

2.3

See Also:

• Constant Field Values

EXPRESSION_SEPARATOR_CHARS

protected static final char[] EXPRESSION_SEPARATOR_CHARS

The default characters used to separate expressions in a series of expressions. Expressions are per default separated by space and comma.

Since:

2.3

Constructor Details

SearchExpressionHandler

public SearchExpressionHandler()

Method Details

resolveClientId

public abstract String resolveClientId(SearchExpressionContext searchExpressionContext,
 String expression)

Resolves to a single clientId or passthrough expression for the given expression.

Parameters:

searchExpressionContext - the SearchExpressionContext

expression - the search expression

Returns:

The resolved clientId or passtrough expression. If the expression can not be resolved and if SearchExpressionHint.IGNORE_NO_RESULT was passed, null will be returned.

Throws:

ComponentNotFoundException - if the expression can not be resolved and if SearchExpressionHint.IGNORE_NO_RESULT was not passed.

FacesException - if the expression is not valid.

Since:

2.3

resolveClientIds

public abstract List<String> resolveClientIds(SearchExpressionContext searchExpressionContext,
 String expressions)

Resolves to a List with clientIds or passthrough expressions for the given expressions. The expressions will be splitted by splitExpressions(jakarta.faces.context.FacesContext, java.lang.String) and resolved one by one.

Parameters:

searchExpressionContext - the SearchExpressionContext

expressions - the search expressions

Returns:

The resolved clientIds and passtrough expressions.

Throws:

ComponentNotFoundException - if one of the expression can not be resolved and if SearchExpressionHint.IGNORE_NO_RESULT was not passed.

FacesException - if the expression is not valid.

Since:

2.3

resolveComponent

public abstract void resolveComponent(SearchExpressionContext searchExpressionContext,
 String expression,
 ContextCallback callback)

Resolves a single UIComponents for the given expression. If the component is resolved, the ContextCallback will be invoked.

Parameters:

searchExpressionContext - the SearchExpressionContext

expression - the search expression

callback - the callback for the resolved component

Throws:

ComponentNotFoundException - if the expression can not be resolved and if SearchExpressionHint.IGNORE_NO_RESULT was not passed.

FacesException - if the expression is not valid.

Since:

2.3

resolveComponents

public abstract void resolveComponents(SearchExpressionContext searchExpressionContext,
 String expressions,
 ContextCallback callback)

Resolves multiple UIComponents for the given expression(s). The expressions will be splitted by splitExpressions(jakarta.faces.context.FacesContext, java.lang.String) and resolved one by one. For each resolved component, the ContextCallback will be invoked.

Parameters:

searchExpressionContext - the SearchExpressionContext

expressions - the search expression(s)

callback - the callback for each resolved component

Throws:

ComponentNotFoundException - if any of the expressions can not be resolved and if SearchExpressionHint.IGNORE_NO_RESULT was not passed.

FacesException - if the expression is not valid.

Since:

2.3

invokeOnComponent

public void invokeOnComponent(SearchExpressionContext searchExpressionContext,
 String expression,
 ContextCallback callback)

Resolves multiple UIComponents for the given expression. For each resolved component, the ContextCallback will be invoked. This method is the most essential method in the API. It implements the algorithm which handles the recursion of the keywords and id's.

Parameters:

searchExpressionContext - the SearchExpressionContext

expression - the search expression

callback - the callback for the resolved component

Throws:

FacesException - if the expression is not valid.

Since:

2.3

invokeOnComponent

public abstract void invokeOnComponent(SearchExpressionContext searchExpressionContext,
 UIComponent previous,
 String expression,
 ContextCallback callback)

Resolves multiple UIComponents for the given expression. For each resolved component, the ContextCallback will be invoked. This method is the most essential method in the API. It implements the algorithm which handles the recursion of the keywords and id's.

Parameters:

searchExpressionContext - the SearchExpressionContext

previous - The previous resolved component, that will be the base for searching

expression - the search expression

callback - the callback for the resolved component

Throws:

FacesException - if the expression is not valid.

Since:

2.3

splitExpressions

public abstract String[] splitExpressions(FacesContext context,
 String expressions)

Splits an string, based on getExpressionSeperatorChars(jakarta.faces.context.FacesContext) with possible multiple expressions into an array.

Parameters:

context - the FacesContext for the current request

expressions - The expressions as string

Returns:

the expression(s) as array

Since:

2.3

isPassthroughExpression

public abstract boolean isPassthroughExpression(SearchExpressionContext searchExpressionContext,
 String expression)

Checks if the given expression is a "passtrough expression". A passthrough expression must only be a keyword. This keyword will not be resolved by the SearchKeywordResolver and will be returned untouched. The client is responsible to resolve it later.

Parameters:

searchExpressionContext - the SearchExpressionContext

expression - the expression

Returns:

If the given expression is a passtrough expression

Since:

2.3

isValidExpression

public abstract boolean isValidExpression(SearchExpressionContext searchExpressionContext,
 String expression)

Checks if the given expression is a valid expression.

A expression is invalid if:

• No SearchKeywordResolver matches the requested keyword
• A keyword or id is placed after a leaf keyword (@none:@form)

Parameters:

searchExpressionContext - the SearchExpressionContext

expression - the expression

Returns:

If the given expression is a valid expression

Since:

2.3

getExpressionSeperatorChars

public char[] getExpressionSeperatorChars(FacesContext context)

Return the characters used to separate expressions in a series of expressions. The default implementation returns EXPRESSION_SEPARATOR_CHARS.

Parameters:

context - the FacesContext for the current request

Returns:

the separator chars

Since:

2.3