SearchExpressionHandler

java.lang.Object
- jakarta.faces.component.search.SearchExpressionHandler

Direct Known Subclasses:

SearchExpressionHandlerWrapper
```
public abstract class SearchExpressionHandler
extends java.lang.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 and Description
`protected static char[]`	`EXPRESSION_SEPARATOR_CHARS` The default characters used to separate expressions in a series of expressions.
`static java.lang.String`	`KEYWORD_PREFIX` The prefix to identify a keyword.

Constructor Summary

Constructors
Constructor and Description

SearchExpressionHandler()

Constructors
Constructor and Description
`SearchExpressionHandler()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`char[]`	`getExpressionSeperatorChars(FacesContext context)` Return the characters used to separate expressions in a series of expressions.
`void`	`invokeOnComponent(SearchExpressionContext searchExpressionContext, java.lang.String expression, ContextCallback callback)` Resolves multiple `UIComponent`s for the given expression.
`abstract void`	`invokeOnComponent(SearchExpressionContext searchExpressionContext, UIComponent previous, java.lang.String expression, ContextCallback callback)` Resolves multiple `UIComponent`s for the given expression.
`abstract boolean`	`isPassthroughExpression(SearchExpressionContext searchExpressionContext, java.lang.String expression)` Checks if the given expression is a "passtrough expression".
`abstract boolean`	`isValidExpression(SearchExpressionContext searchExpressionContext, java.lang.String expression)` Checks if the given expression is a valid expression.
`abstract java.lang.String`	`resolveClientId(SearchExpressionContext searchExpressionContext, java.lang.String expression)` Resolves to a single clientId or passthrough expression for the given expression.
`abstract java.util.List<java.lang.String>`	`resolveClientIds(SearchExpressionContext searchExpressionContext, java.lang.String expressions)` Resolves to a `List` with clientIds or passthrough expressions for the given expressions.
`abstract void`	`resolveComponent(SearchExpressionContext searchExpressionContext, java.lang.String expression, ContextCallback callback)` Resolves a single `UIComponent`s for the given expression.
`abstract void`	`resolveComponents(SearchExpressionContext searchExpressionContext, java.lang.String expressions, ContextCallback callback)` Resolves multiple `UIComponent`s for the given expression(s).
`abstract java.lang.String[]`	`splitExpressions(FacesContext context, java.lang.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 Detail
  - KEYWORD_PREFIX
```
public static final java.lang.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 Detail
  - SearchExpressionHandler
```
public SearchExpressionHandler()
```
- Method Detail
  - resolveClientId
```
public abstract java.lang.String resolveClientId(SearchExpressionContext searchExpressionContext,
                                                 java.lang.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 java.util.List<java.lang.String> resolveClientIds(SearchExpressionContext searchExpressionContext,
                                                                  java.lang.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,
                                      java.lang.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,
                                       java.lang.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,
                              java.lang.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,
                                       java.lang.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 java.lang.String[] splitExpressions(FacesContext context,
                                                    java.lang.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,
                                                java.lang.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,
                                          java.lang.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

Class SearchExpressionHandler

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

KEYWORD_PREFIX

EXPRESSION_SEPARATOR_CHARS

Constructor Detail

SearchExpressionHandler

Method Detail

resolveClientId

resolveClientIds

resolveComponent

resolveComponents

invokeOnComponent

invokeOnComponent

splitExpressions

isPassthroughExpression

isValidExpression

getExpressionSeperatorChars