javax.faces.component.search.SearchExpressionHandler Maven / Gradle / Ivy
Show all versions of jakarta.faces Show documentation
/*
* Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package javax.faces.component.search;
import java.util.List;
import javax.faces.FacesException;
import javax.faces.component.ContextCallback;
import javax.faces.component.UIComponent;
import javax.faces.context.FacesContext;
/**
* 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 {@link UIComponent}, or a keyword (like @this or @form),
* or a series of such identifiers and keywords linked by
* the {@link javax.faces.component.UINamingContainer#getSeparatorChar} character value.
* See {@link 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 {@link 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 {@link javax.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 {@link 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 {@link javax.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 {@link #KEYWORD_PREFIX}, then it is considered as a keyword and the
* {@link SearchKeywordResolver}s will be used the resolve the keyword.
*
* -
* Otherwise, if the command does not start with {@link #KEYWORD_PREFIX}, then the component will be resolved
* based on the component ID.
*
*
*
*
*
*
* @since 2.3
*/
public abstract class SearchExpressionHandler {
/**
* The prefix to identify a keyword.
*
* @since 2.3
*/
public static final String KEYWORD_PREFIX = "@";
/**
* The default characters used to separate expressions
* in a series of expressions. Expressions are per default separated by space and comma.
*
* @since 2.3
*/
protected static final char[] EXPRESSION_SEPARATOR_CHARS = new char[] {
',', ' '
};
/**
* Resolves to a single clientId or passthrough expression for the given expression.
*
*
* @param searchExpressionContext the {@link SearchExpressionContext}
* @param expression the search expression
*
* @throws ComponentNotFoundException if the expression can not be resolved
* and if {@link SearchExpressionHint#IGNORE_NO_RESULT} was not passed.
* @throws FacesException if the expression is not valid.
*
* @return The resolved clientId or passtrough expression. If the expression can not be resolved and if
* {@link SearchExpressionHint#IGNORE_NO_RESULT} was passed, null will be returned.
*
* @since 2.3
*/
public abstract String resolveClientId(SearchExpressionContext searchExpressionContext, String expression);
/**
* Resolves to a {@link List} with clientIds or passthrough expressions for the given expressions.
* The expressions will be splitted by {@link #splitExpressions(javax.faces.context.FacesContext, java.lang.String)}
* and resolved one by one.
*
*
* @param searchExpressionContext the {@link SearchExpressionContext}
* @param expressions the search expressions
*
* @throws ComponentNotFoundException if one of the expression can not be resolved
* and if {@link SearchExpressionHint#IGNORE_NO_RESULT} was not passed.
* @throws FacesException if the expression is not valid.
*
* @return The resolved clientIds and passtrough expressions.
*
* @since 2.3
*/
public abstract List resolveClientIds(SearchExpressionContext searchExpressionContext, String expressions);
/**
* Resolves a single {@link UIComponent}s for the given
* expression. If the component is resolved, the {@link ContextCallback} will be invoked.
*
*
* @param searchExpressionContext the {@link SearchExpressionContext}
* @param expression the search expression
* @param callback the callback for the resolved component
*
* @throws ComponentNotFoundException if the expression can not be resolved
* and if {@link SearchExpressionHint#IGNORE_NO_RESULT} was not passed.
* @throws FacesException if the expression is not valid.
*
* @since 2.3
*/
public abstract void resolveComponent(SearchExpressionContext searchExpressionContext, String expression,
ContextCallback callback);
/**
* Resolves multiple {@link UIComponent}s for the given expression(s).
* The expressions will be splitted by {@link #splitExpressions(javax.faces.context.FacesContext, java.lang.String)}
* and resolved one by one.
* For each resolved component, the {@link ContextCallback} will be invoked.
*
*
* @param searchExpressionContext the {@link SearchExpressionContext}
* @param expressions the search expression(s)
* @param callback the callback for each resolved component
*
* @throws ComponentNotFoundException if any of the expressions can not be resolved
* and if {@link SearchExpressionHint#IGNORE_NO_RESULT} was not passed.
* @throws FacesException if the expression is not valid.
*
* @since 2.3
*/
public abstract void resolveComponents(SearchExpressionContext searchExpressionContext, String expressions,
ContextCallback callback);
/**
* Resolves multiple {@link UIComponent}s for the given
* expression. For each resolved component, the {@link 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.
*
*
* @param searchExpressionContext the {@link SearchExpressionContext}
* @param expression the search expression
* @param callback the callback for the resolved component
*
* @throws FacesException if the expression is not valid.
*
* @since 2.3
*/
public void invokeOnComponent(SearchExpressionContext searchExpressionContext,
String expression, ContextCallback callback) {
invokeOnComponent(searchExpressionContext, searchExpressionContext.getSource(), expression, callback);
}
/**
* Resolves multiple {@link UIComponent}s for the given
* expression. For each resolved component, the {@link 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.
*
*
* @param searchExpressionContext the {@link SearchExpressionContext}
* @param previous The previous resolved component, that will be the base for searching
* @param expression the search expression
* @param callback the callback for the resolved component
*
* @throws FacesException if the expression is not valid.
*
* @since 2.3
*/
public abstract void invokeOnComponent(SearchExpressionContext searchExpressionContext,
UIComponent previous, String expression, ContextCallback callback);
/**
* Splits an string, based on
* {@link #getExpressionSeperatorChars(javax.faces.context.FacesContext)} with possible multiple expressions into an array.
*
* @param context the {@link FacesContext} for the current request
* @param expressions The expressions as string
* @return the expression(s) as array
*
* @since 2.3
*/
public abstract String[] splitExpressions(FacesContext context, String expressions);
/**
* 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 {@link SearchKeywordResolver} and will be returned untouched.
*
* The client is responsible to resolve it later.
*
*
* @param searchExpressionContext the {@link SearchExpressionContext}
* @param expression the expression
* @return 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 valid expression.
*
*
* A expression is invalid if:
*
* - No {@link SearchKeywordResolver} matches the requested keyword
* - A keyword or id is placed after a leaf keyword (@none:@form)
*
*
*
* @param searchExpressionContext the {@link SearchExpressionContext}
* @param expression the expression
*
* @return If the given expression is a valid expression
*
* @since 2.3
*/
public abstract boolean isValidExpression(SearchExpressionContext searchExpressionContext, String expression);
/**
* Return the characters used to separate expressions
* in a series of expressions.
* The default implementation returns {@link SearchExpressionHandler#EXPRESSION_SEPARATOR_CHARS}.
*
* @param context the {@link FacesContext} for the current request
* @return the separator chars
*
* @since 2.3
*/
public char[] getExpressionSeperatorChars(FacesContext context) {
return EXPRESSION_SEPARATOR_CHARS;
}
}