com.google.appengine.api.search

## Class FacetRefinement

- java.lang.Object
- - com.google.appengine.api.search.FacetRefinement

-     public final class FacetRefinement
      extends java.lang.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

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static FacetRefinement` | `fromTokenString(java.lang.String token)` Converts a token string to a FacetRefinement object.
    `java.lang.String` | `getName()` Returns the name of the facet.
    `FacetRange` | `getRange()` Returns the range for numeric facets or null if there is no range.
    `java.lang.String` | `getValue()` Returns the value of the facet or null if there is no value.
    `java.lang.String` | `toString()`
    `java.lang.String` | `toTokenString()` Converts this refinement to a token string safe to be used in HTML.
    `static FacetRefinement` | `withRange(java.lang.String name, FacetRange range)` Create a `FacetRefinement` with the given `name` and `range`.
    `static FacetRefinement` | `withValue(java.lang.String name, java.lang.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(java.lang.String name,
                                                  java.lang.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:
        `java.lang.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(java.lang.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:
        `java.lang.IllegalArgumentException` - if `name` is null or empty.

    - #### getName

          public java.lang.String getName()

      Returns the name of the facet.

    - #### getValue

          public java.lang.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 java.lang.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(java.lang.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:
        `java.lang.IllegalArgumentException` - if the given token cannot be processed.

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`