Package com.google.appengine.api.search

Class FacetRefinement

java.lang.Object

com.google.appengine.api.search.FacetRefinement

public final class FacetRefinement
extends Object

A Facet Refinement to filter out search results based on a facet value.

We recommend using refinement token strings instead of this class. We include a refinement token string with each FacetResultValue returned by the backend that can be passed to Query.Builder.addFacetRefinementFromToken(String) to refine follow-up queries.

We also support manually-specified query refinements by passing an instance of this class to Query.Builder.addFacetRefinement(FacetRefinement).

Example: Request to only return documents that have a number facet named "rating" with a value between one and two:

 FacetRefinement lowRating = FacetRefinement.withRange("rating", FacetRange.startEnd(1.0, 2.0));
 query.addFacetRefinement(lowRating);
 

Method Summary

Modifier and Type	Method	Description
static FacetRefinement	fromTokenString(String token)	Converts a token string to a FacetRefinement object.
String	getName()	Returns the name of the facet.
FacetRange	getRange()	Returns the range for numeric facets or null if there is no range.
String	getValue()	Returns the value of the facet or null if there is no value.
String	toString()
String	toTokenString()	Converts this refinement to a token string safe to be used in HTML.
static FacetRefinement	withRange(String name, FacetRange range)	Create a FacetRefinement with the given name and range.
static FacetRefinement	withValue(String name, String value)	Create a FacetRefinement with the given name and value.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

withValue

public static FacetRefinement withValue(String name,
                                        String value)

Create a FacetRefinement with the given name and value.

Parameters:

name - the name of the facet.

value - the value of the facet (both numeric and atom).

Returns:

an instance of FacetRefinement.

Throws:

IllegalArgumentException - if name is null or empty or the value length is less than 1 or greater than SearchApiLimits#FACET_MAXIMUM_VALUE_LENGTH.

withRange

public static FacetRefinement withRange(String name,
                                        FacetRange range)

Create a FacetRefinement with the given name and range.

Parameters:

name - the name of the facet.

range - the range of the numeric facet.

Returns:

an instance of FacetRefinement.

Throws:

IllegalArgumentException - if name is null or empty.

getName

public String getName()

Returns the name of the facet.

getValue

public String getValue()

Returns the value of the facet or null if there is no value.

getRange

public FacetRange getRange()

Returns the range for numeric facets or null if there is no range.

toTokenString

public String toTokenString()

Converts this refinement to a token string safe to be used in HTML.

NOTE: Do not persist token strings. The format may change.

Returns:

A token string safe to be used in HTML for this facet refinement.

fromTokenString

public static FacetRefinement fromTokenString(String token)

Converts a token string to a FacetRefinement object.

NOTE: Do not persist token strings. The format may change.

Parameters:

token - A token string returned by FacetResultValue.getRefinementToken() or toTokenString().

Returns:

A FacetRefinement object.

Throws:

IllegalArgumentException - if the given token cannot be processed.

toString

public String toString()

Overrides:

toString in class Object