Top Description Interfaces Classes Enums
[default module]

Package javax.faces.component.search

APIs for searching for components in the component tree by using expressions.

This feature has two entry points: for the page author and for the Java programmer. Following is a brief overview of each.

For the Page Author

The following tags support the use of search expressions: <h:message />, <h:messages />, <h:outputLabel />, and <f:ajax />. Each of those tags have one or more attributes whose value must be a client identifier. This feature expands the capability of those attributes to be search expressions. A search expression is space separated list of tokens, where a token can either be a client identifier, a search keyword, or a combination of both. See the specification for SearchKeywordResolver for the list of keywords that must be supported. See the specification for SearchExpressionHandler to learn how the search is performed.

Here is a brief example of the page author use case:

  1. <h:body>
  2.   <h:outputLabel id="label" for="@next" value="Test" />
  3.   <h:inputText id="input">
  4.     <f:ajax render="@this @next" />
  5.   </h:inputText>
  6.   <h:inputText id="input2" />
  7. </h:body>

For the Java Programmer

Using search expressions from Java code offers more flexibility. One must obtain a handle to the SearchExpressionHandler and invoke methods on it as desired.

The following example resolves to a clientId:

  1. SearchExpressionHandler handler = facesContext.getApplication().getSearchExpressionHandler();
  2. SearchExpressionContext context = SearchExpressionContext.createSearchExpressionContext(facesContext, facesContext.getViewRoot());
  3. String clientId = handler.resolveClientId(context, ":form:container:@next");

The following example resolves to a component:

  1. SearchExpressionHandler handler = facesContext.getApplication().getSearchExpressionHandler();
  2. SearchExpressionContext context = SearchExpressionContext.createSearchExpressionContext(facesContext, facesContext.getViewRoot());
  3. handler.resolveComponent(context, ":form:container:@next",
  4.                new ContextCallback() {
  5.                    public void invokeContextCallback(FacesContext context,
  6.                                             UIComponent target) {
  7.                        // target == the resolved component
  8.                    }
  9.                });

The following example uses multiple expressions and therefor resolves to multiple components:

  1. SearchExpressionHandler handler = facesContext.getApplication().getSearchExpressionHandler();
  2. SearchExpressionContext context = SearchExpressionContext.createSearchExpressionContext(facesContext, facesContext.getViewRoot());
  3. handler.resolveComponents(context, ":form:container:@next :input1 input2:@parent",
  4.                new ContextCallback() {
  5.                    public void invokeContextCallback(FacesContext context,
  6.                                             UIComponent target) {
  7.                        // target == the resolved component
  8.                    }
  9.                });

Extending the Capabilities of the Component Search Facility

Creation of the SearchExpressionContext

As with other factories in JSF, the FactoryFinder is used by the system to create instances of the SearchExpressionContext which holds state during the operation of this API.

Adding new SearchKewordResolvers

See SearchKeywordResolver for the specification of how the set of keywords can be expanded.

Interface Summary

Modifier and TypeInterface and Description
public interface
UntargetableComponent

Components implementing this interface are ignored by the algorithm - especially in the implementation of @child(n), @next and @previous.

Class Summary

Modifier and TypeClass and Description
public class
ComponentNotFoundException

Typed FacesException for the SearchExpressionHandler, if a component can't be resolved.

public abstract class
SearchExpressionContext

A context object that is used to hold state relating to resolve a search expression.

public abstract class
SearchExpressionContextFactory

Provide for separation of interface and implementation for the SearchExpressionContext contract.

public abstract class
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 javax.faces.component.UINamingContainer#getSeparatorChar character value.

public abstract class
SearchExpressionHandlerWrapper

Provides a simple implementation of SearchExpressionHandler that can be subclassed by developers wishing to provide specialized behavior to an existing SearchExpressionHandler instance.

public class
SearchKeywordContext

SearchKeywordContext provides context information that may be useful to SearchKeywordResolver#resolve implementations.

public abstract class
SearchKeywordResolver

A SearchKeywordResolver is responsible for resolving a single keyword.

Enum Summary

Modifier and TypeEnum and Description
public enum
SearchExpressionHint

An enum that specifies hints that impact the behavior of a component tree search.