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

   1 package com.google.appengine.api.search;
   2
   3 import com.google.appengine.api.search.SearchServicePb.FacetAutoDetectParam;
   4 import com.google.appengine.api.search.SearchServicePb.SearchParams;
   5 import com.google.appengine.api.search.checkers.FacetQueryChecker;
   6 import com.google.appengine.api.search.checkers.SearchApiLimits;
   7
   8 /**
   9  * A {@code FacetOptions} represents facet options such as the number of facets to discover
  10  * ({@code discoveryLimit}), the number of values to be included in each discovered
  11  * facet ({@code discoveryValueLimit}), and the depth of the results to check ({@code depth}).
  12  * Note that discovery is disabled when {@code discoveryLimit} is zero.
  13  * <p>
  14  * For example, to discover 10 facets with 5 values each over 1000 extended results:
  15  * <pre>
  16  *   FacetOptions facetOption = FacetOptions.newBuilder()
  17  *       .setDiscoverLimit(10)
  18  *       .setDiscoverValueLimit(5)
  19  *       .setDepth(1000)
  20  *       .build();
  21  * </pre>
  22  */
  23 public final class FacetOptions {
  24
  25   /**
  26    * Builder for {@link FacetOptions}.
  27    */
  28   public static final class Builder {
  29     private Integer discoveryValueLimit;
  30     private Integer discoveryLimit;
  31     private Integer depth;
  32
  33     private Builder() {
  34     }
  35
  36     /**
  37      * Constructs a {@link FacetOptions} builder with the given facet options.
  38      *
  39      * @param options the search request to populate the builder
  40      */
  41     private Builder(FacetOptions options) {
  42       discoveryValueLimit = options.getDiscoveryValueLimit();
  43       discoveryLimit = options.getDiscoveryLimit();
  44       depth = options.getDepth();
  45     }
  46
  47     /**
  48      * Sets the maximum number of values each discovered facet should have.
  49      *
  50      * @return this Builder
  51      * @throws IllegalArgumentException if value is negative or zero or greater than
  52      * {@link SearchApiLimits#FACET_MAXIMUM_VALUE_LIMIT}
  53      */
  54     public Builder setDiscoveryValueLimit(int value) {
  55       this.discoveryValueLimit = FacetQueryChecker.checkDiscoveryValueLimit(value);
  56       return this;
  57     }
  58
  59     /**
  60      * Sets the number of facets to be discovered.
  61      *
  62      * @return this Builder
  63      * @throws IllegalArgumentException if the value is zero or negative or is larger
  64      * than {@link SearchApiLimits#FACET_MAXIMUM_DISCOVERY_LIMIT}
  65      */
  66     public Builder setDiscoveryLimit(int value) {
  67       this.discoveryLimit = FacetQueryChecker.checkDiscoveryLimit(value);
  68       return this;
  69     }
  70
  71     /**
  72      * Sets the number of documents from the search result to be analyzed for facet discovery.
  73      *
  74      * @return this Builder
  75      * @throws IllegalArgumentException if the value is zero or negative or is larger
  76      * than {@link SearchApiLimits#FACET_MAXIMUM_DEPTH}.
  77      */
  78     public Builder setDepth(int value) {
  79       this.depth = FacetQueryChecker.checkDepth(value);
  80       return this;
  81     }
  82
  83     /**
  84      * Returns an immutable {@link FacetOptions} that reflects the current state of this Builder.
  85      */
  86     public FacetOptions build() {
  87       return new FacetOptions(this);
  88     }
  89   }
  90
  91   private final Integer discoveryValueLimit;
  92   private final Integer discoveryLimit;
  93   private final Integer depth;
  94
  95   private FacetOptions(Builder builder) {
  96     discoveryValueLimit = builder.discoveryValueLimit;
  97     discoveryLimit = builder.discoveryLimit;
  98     depth = builder.depth;
  99   }
 100
 101   /**
 102    * Returns the number of facets to be discovered or null if unset.
 103    */
 104   public Integer getDiscoveryLimit() {
 105     return discoveryLimit;
 106   }
 107
 108   /**
 109    * Returns the maximum number of values for each discovered facet or null if unset.
 110    */
 111   public Integer getDiscoveryValueLimit() {
 112     return discoveryValueLimit;
 113   }
 114
 115   /**
 116    * Returns the number of documents from the search result to be analyzed for facet discovery
 117    * or null if unset.
 118    */
 119   public Integer getDepth() {
 120     return depth;
 121   }
 122
 123   /**
 124    * Creates and returns an empty {@link Builder}.
 125    *
 126    * @return a {@link Builder} which can construct a facet options.
 127    */
 128   public static Builder newBuilder() {
 129     return new Builder();
 130   }
 131
 132   /**
 133    * Creates and returns a {@link Builder} that reflects the given options.
 134    *
 135    * @param options the options that the returned builder will reflect.
 136    * @return a new builder with values set from the given options.
 137    */
 138   public static Builder newBuilder(FacetOptions options) {
 139     return new Builder(options);
 140   }
 141
 142   /**
 143    * Copies the contents of this {@link FacetOptions} object into a
 144    * {@link SearchParams} protocol buffer builder.
 145    */
 146   void copyToProtocolBuffer(SearchParams.Builder builder,
 147       boolean enableFacetDiscovery) {
 148     if (enableFacetDiscovery) {
 149       if (discoveryLimit == null) {
 150         builder.setAutoDiscoverFacetCount(SearchApiLimits.FACET_DEFAULT_DISCOVERY_LIMIT);
 151       } else {
 152         builder.setAutoDiscoverFacetCount(discoveryLimit);
 153       }
 154     } else {
 155       builder.clearAutoDiscoverFacetCount();
 156     }
 157     if (depth != null) {
 158       builder.setFacetDepth(depth);
 159     }
 160     if (discoveryValueLimit != null) {
 161       builder.setFacetAutoDetectParam(
 162           FacetAutoDetectParam.newBuilder().setValueLimit(discoveryValueLimit));
 163     }
 164   }
 165
 166   @Override
 167   public String toString() {
 168     return new Util.ToStringHelper("FacetOptions")
 169         .addField("discoveryValueLimit", getDiscoveryValueLimit())
 170         .addField("discoveryLimit", getDiscoveryLimit())
 171         .addField("depth", getDepth())
 172         .finish();
 173   }
 174 }