java/src/main/com/google/appengine/api/search/FacetResult.java

   1 package com.google.appengine.api.search;
   2
   3 import com.google.appengine.api.search.checkers.Preconditions;
   4 import com.google.common.collect.ImmutableList;
   5
   6 import java.io.Serializable;
   7 import java.util.ArrayList;
   8 import java.util.List;
   9
  10 /**
  11  * Represents a facet result computed from an extended search result set. A facet result contains
  12  * a name, a type, and a set of values. Name is a single facet name and each value has a label and
  13  * a count. The value label can be a single facet value name, or a range label
  14  * (in "[start,end)" format).
  15  */
  16 public final class FacetResult implements Serializable {
  17
  18   private static final long serialVersionUID = 1222792844480713320L;
  19
  20   private static final int MAX_VALUE_TO_STRING = 10;
  21
  22   /**
  23    * A builder of facet result. This is not thread-safe.
  24    */
  25   public static final class Builder {
  26     private final List<FacetResultValue> values = new ArrayList<>();
  27     private String name;
  28
  29     /**
  30      * Constructs a builder for a facet result.
  31      */
  32     private Builder() {
  33     }
  34
  35     /**
  36      * Sets the name of this facet result that is a single facet name.
  37      *
  38      * @param name The name of the facet for this facet result.
  39      * @return this builder
  40      * @throws NullPointerException if the name is null.
  41      * @throws IllegalArgumentException if the name is empty.
  42      */
  43     public Builder setName(String name) {
  44       Preconditions.checkNotNull(name, "name cannot be null");
  45       Preconditions.checkArgument(!name.isEmpty(), "name cannot be empty.");
  46       this.name = name;
  47       return this;
  48     }
  49
  50     /**
  51      * Add a value to this facet result.
  52      *
  53      * @param value the value to add.
  54      * @return this builder
  55      */
  56     public Builder addValue(FacetResultValue value) {
  57       Preconditions.checkNotNull(value, "value cannot be null");
  58       values.add(value);
  59       return this;
  60     }
  61
  62     /**
  63      * Builds a facet result. The builder must at least have a name.
  64      *
  65      * @return the facet result built by this builder
  66      * @throws NullPointerException if the name is null.
  67      * @throws IllegalArgumentException if the name is empty or null.
  68      */
  69     public FacetResult build() {
  70       return new FacetResult(this);
  71     }
  72   }
  73
  74   private final ImmutableList<FacetResultValue> values;
  75   private final String name;
  76
  77   /**
  78    * Constructs a facet result with the given builder.
  79    *
  80    * @param builder the builder capable of building a facet result
  81    */
  82   private FacetResult(Builder builder) {
  83     values = ImmutableList.copyOf(builder.values);
  84     name = builder.name;
  85     checkValid();
  86   }
  87
  88   /**
  89    * The list of facet values computed during search. Each value
  90    * result has a label, count, and refinement token.
  91    *
  92    * @return an unmodifiable list of values
  93    */
  94   public List<FacetResultValue> getValues() {
  95     return values;
  96   }
  97
  98   /**
  99    * Name of this facet result that is a single facet name.
 100    *
 101    * @return name as string
 102    */
 103   public String getName() {
 104     return name;
 105   }
 106
 107   public static FacetResult.Builder newBuilder() {
 108     return new Builder();
 109   }
 110
 111   private void checkValid() {
 112     Preconditions.checkNotNull(name, "name cannot be null.");
 113     Preconditions.checkArgument(!name.isEmpty(), "name cannot be empty.");
 114   }
 115
 116   /**
 117    * Creates a new facet result builder from the given protocol
 118    * buffer facet result object. All the content of the result will be copied to the builder.
 119    *
 120    * @param facetResult the facet result protocol buffer to build
 121    * a facet result object from
 122    * @return the facet result builder initialized from a facet
 123    * result protocol buffer
 124    */
 125   static FacetResult.Builder newBuilder(SearchServicePb.FacetResult facetResult) {
 126     FacetResult.Builder frBuilder = newBuilder();
 127     frBuilder.setName(facetResult.getName());
 128     for (SearchServicePb.FacetResultValue value : facetResult.getValueList()) {
 129       frBuilder.addValue(FacetResultValue.withProtoMessage(value));
 130     }
 131     return frBuilder;
 132   }
 133
 134   @Override
 135   public String toString() {
 136     return new Util.ToStringHelper("FacetResult")
 137         .addField("name", getName())
 138         .addIterableField("values", getValues(), MAX_VALUE_TO_STRING)
 139         .finish();
 140   }
 141 }