Jakarta EE 11.0.0 · jakarta.faces.component.search.SearchExpressionHandler

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 jakarta.faces.component.UINamingContainer#getSeparatorChar 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 jakarta.faces.component.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 jakarta.faces.component.UINamingContainer#getSeparatorChar 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.

Field Summary

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

Constructor Summary

Access	Constructor and Description
public	SearchExpressionHandler()

Method Summary

Modifier and Type	Method and Description
public char[]	Returns: the separator chars getExpressionSeperatorChars(FacesContext the `FacesContext` for the current request context) Return the characters used to separate expressions in a series of expressions.
public void	invokeOnComponent(SearchExpressionContext the `SearchExpressionContext` searchExpressionContext, String the search expression expression, ContextCallback the callback for the resolved component callback) Resolves multiple `UIComponent`s for the given expression.
public abstract void	invokeOnComponent(SearchExpressionContext the `SearchExpressionContext` searchExpressionContext, UIComponent The previous resolved component, that will be the base for searching previous, String the search expression expression, ContextCallback the callback for the resolved component callback) Resolves multiple `UIComponent`s for the given expression.
public abstract boolean	Returns: If the given expression is a passtrough expression isPassthroughExpression(SearchExpressionContext the `SearchExpressionContext` searchExpressionContext, String the expression expression) Checks if the given expression is a "passtrough expression".
public abstract boolean	Returns: If the given expression is a valid expression isValidExpression(SearchExpressionContext the `SearchExpressionContext` searchExpressionContext, String the expression expression) Checks if the given expression is a valid expression.
public abstract String	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. resolveClientId(SearchExpressionContext the `SearchExpressionContext` searchExpressionContext, String the search expression expression) Resolves to a single clientId or passthrough expression for the given expression.
public abstract List<String>	Returns: The resolved clientIds and passtrough expressions. resolveClientIds(SearchExpressionContext the `SearchExpressionContext` searchExpressionContext, String the search expressions expressions) Resolves to a `List` with clientIds or passthrough expressions for the given expressions.
public abstract void	resolveComponent(SearchExpressionContext the `SearchExpressionContext` searchExpressionContext, String the search expression expression, ContextCallback the callback for the resolved component callback) Resolves a single `UIComponent`s for the given expression.
public abstract void	resolveComponents(SearchExpressionContext the `SearchExpressionContext` searchExpressionContext, String the search expression(s) expressions, ContextCallback the callback for each resolved component callback) Resolves multiple `UIComponent`s for the given expression(s).
public abstract String[]	Returns: the expression(s) as array splitExpressions(FacesContext the `FacesContext` for the current request context, String The expressions as string expressions) Splits an string, based on `getExpressionSeperatorChars(jakarta.faces.context.FacesContext)` with possible multiple expressions into an array.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

EXPRESSION_SEPARATOR_CHARS	back to summary
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

EXPRESSION_SEPARATOR_CHARS

back to summary

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

KEYWORD_PREFIX	back to summary
public static final String KEYWORD_PREFIX The prefix to identify a keyword. Since 2.3

KEYWORD_PREFIX

back to summary

public static final String KEYWORD_PREFIX

The prefix to identify a keyword.

Since: 2.3

Constructor Detail

SearchExpressionHandler	back to summary
public SearchExpressionHandler()

Method Detail

getExpressionSeperatorChars back to summary

getExpressionSeperatorChars	back to summary
public char[] getExpressionSeperatorChars(FacesContext context) Return the characters used to separate expressions in a series of expressions. The default implementation returns `SearchExpressionHandler#EXPRESSION_SEPARATOR_CHARS`. Parameters context:FacesContext the `FacesContext` for the current request Returns:char[] the separator chars Since 2.3

public char[] getExpressionSeperatorChars(FacesContext context)

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

Parameters

context:FacesContext: the FacesContext for the current request

Returns:char[]

the separator chars

Since

2.3

invokeOnComponent back to summary

invokeOnComponent	back to summary
public void invokeOnComponent(SearchExpressionContext searchExpressionContext, String expression, ContextCallback callback) Resolves multiple `UIComponent`s 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:SearchExpressionContext the `SearchExpressionContext` expression:String the search expression callback:ContextCallback the callback for the resolved component Exceptions FacesException: if the expression is not valid. Since 2.3

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:SearchExpressionContext: the SearchExpressionContext
expression:String: the search expression
callback:ContextCallback: the callback for the resolved component

Exceptions

FacesException:: if the expression is not valid.

Since

2.3

invokeOnComponent back to summary

invokeOnComponent	back to summary
public abstract void invokeOnComponent(SearchExpressionContext searchExpressionContext, UIComponent previous, String expression, ContextCallback callback) Resolves multiple `UIComponent`s 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:SearchExpressionContext the `SearchExpressionContext` previous:UIComponent The previous resolved component, that will be the base for searching expression:String the search expression callback:ContextCallback the callback for the resolved component Exceptions FacesException: if the expression is not valid. Since 2.3

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

Parameters

searchExpressionContext:SearchExpressionContext: the SearchExpressionContext
previous:UIComponent: The previous resolved component, that will be the base for searching
expression:String: the search expression
callback:ContextCallback: the callback for the resolved component

Exceptions

FacesException:: if the expression is not valid.

Since

2.3

isPassthroughExpression back to summary

isPassthroughExpression	back to summary
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:SearchExpressionContext the `SearchExpressionContext` expression:String the expression Returns:boolean If the given expression is a passtrough expression Since 2.3

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:SearchExpressionContext: the SearchExpressionContext
expression:String: the expression

Returns:boolean

If the given expression is a passtrough expression

Since

2.3

isValidExpression back to summary

isValidExpression	back to summary
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:SearchExpressionContext the `SearchExpressionContext` expression:String the expression Returns:boolean If the given expression is a valid expression Since 2.3

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:SearchExpressionContext: the SearchExpressionContext
expression:String: the expression

Returns:boolean

If the given expression is a valid expression

Since

2.3

resolveClientId back to summary

resolveClientId	back to summary
public abstract String resolveClientId(SearchExpressionContext searchExpressionContext, String expression) Resolves to a single clientId or passthrough expression for the given expression. Parameters searchExpressionContext:SearchExpressionContext the `SearchExpressionContext` expression:String the search expression Returns:String 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. Exceptions 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

public abstract String resolveClientId(SearchExpressionContext searchExpressionContext, String expression)

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

Parameters

searchExpressionContext:SearchExpressionContext: the SearchExpressionContext
expression:String: the search expression

Returns:String

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.

Exceptions

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 back to summary

resolveClientIds	back to summary
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:SearchExpressionContext the `SearchExpressionContext` expressions:String the search expressions Returns:List<String> The resolved clientIds and passtrough expressions. Exceptions 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

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:SearchExpressionContext: the SearchExpressionContext
expressions:String: the search expressions

Returns:List<String>

The resolved clientIds and passtrough expressions.

Exceptions

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 back to summary

resolveComponent	back to summary
public abstract void resolveComponent(SearchExpressionContext searchExpressionContext, String expression, ContextCallback callback) Resolves a single `UIComponent`s for the given expression. If the component is resolved, the `ContextCallback` will be invoked. Parameters searchExpressionContext:SearchExpressionContext the `SearchExpressionContext` expression:String the search expression callback:ContextCallback the callback for the resolved component Exceptions 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

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:SearchExpressionContext: the SearchExpressionContext
expression:String: the search expression
callback:ContextCallback: the callback for the resolved component

Exceptions

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 back to summary

resolveComponents	back to summary
public abstract void resolveComponents(SearchExpressionContext searchExpressionContext, String expressions, ContextCallback callback) Resolves multiple `UIComponent`s 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:SearchExpressionContext the `SearchExpressionContext` expressions:String the search expression(s) callback:ContextCallback the callback for each resolved component Exceptions 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

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:SearchExpressionContext: the SearchExpressionContext
expressions:String: the search expression(s)
callback:ContextCallback: the callback for each resolved component

Exceptions

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

splitExpressions back to summary

splitExpressions	back to summary
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:FacesContext the `FacesContext` for the current request expressions:String The expressions as string Returns:String[] the expression(s) as array Since 2.3

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:FacesContext: the FacesContext for the current request
expressions:String: The expressions as string

Returns:String[]

the expression(s) as array

Since

2.3

public abstract Class SearchExpressionHandler

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail