1 package com
.google
.appengine
.api
.search
;
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
;
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.
14 * For example, to discover 10 facets with 5 values each over 1000 extended results:
16 * FacetOptions facetOption = FacetOptions.newBuilder()
17 * .setDiscoverLimit(10)
18 * .setDiscoverValueLimit(5)
23 public final class FacetOptions
{
26 * Builder for {@link FacetOptions}.
28 public static final class Builder
{
29 private Integer discoveryValueLimit
;
30 private Integer discoveryLimit
;
31 private Integer depth
;
37 * Constructs a {@link FacetOptions} builder with the given facet options.
39 * @param options the search request to populate the builder
41 private Builder(FacetOptions options
) {
42 discoveryValueLimit
= options
.getDiscoveryValueLimit();
43 discoveryLimit
= options
.getDiscoveryLimit();
44 depth
= options
.getDepth();
48 * Sets the maximum number of values each discovered facet should have.
50 * @return this Builder
51 * @throws IllegalArgumentException if value is negative or zero or greater than
52 * {@link SearchApiLimits#FACET_MAXIMUM_VALUE_LIMIT}
54 public Builder
setDiscoveryValueLimit(int value
) {
55 this.discoveryValueLimit
= FacetQueryChecker
.checkDiscoveryValueLimit(value
);
60 * Sets the number of facets to be discovered.
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}
66 public Builder
setDiscoveryLimit(int value
) {
67 this.discoveryLimit
= FacetQueryChecker
.checkDiscoveryLimit(value
);
72 * Sets the number of documents from the search result to be analyzed for facet discovery.
74 * @return this Builder
75 * @throws IllegalArgumentException if the value is zero or negative or is larger
76 * than {@link SearchApiLimits#FACET_MAXIMUM_DEPTH}.
78 public Builder
setDepth(int value
) {
79 this.depth
= FacetQueryChecker
.checkDepth(value
);
84 * Returns an immutable {@link FacetOptions} that reflects the current state of this Builder.
86 public FacetOptions
build() {
87 return new FacetOptions(this);
91 private final Integer discoveryValueLimit
;
92 private final Integer discoveryLimit
;
93 private final Integer depth
;
95 private FacetOptions(Builder builder
) {
96 discoveryValueLimit
= builder
.discoveryValueLimit
;
97 discoveryLimit
= builder
.discoveryLimit
;
98 depth
= builder
.depth
;
102 * Returns the number of facets to be discovered or null if unset.
104 public Integer
getDiscoveryLimit() {
105 return discoveryLimit
;
109 * Returns the maximum number of values for each discovered facet or null if unset.
111 public Integer
getDiscoveryValueLimit() {
112 return discoveryValueLimit
;
116 * Returns the number of documents from the search result to be analyzed for facet discovery
119 public Integer
getDepth() {
124 * Creates and returns an empty {@link Builder}.
126 * @return a {@link Builder} which can construct a facet options.
128 public static Builder
newBuilder() {
129 return new Builder();
133 * Creates and returns a {@link Builder} that reflects the given options.
135 * @param options the options that the returned builder will reflect.
136 * @return a new builder with values set from the given options.
138 public static Builder
newBuilder(FacetOptions options
) {
139 return new Builder(options
);
143 * Copies the contents of this {@link FacetOptions} object into a
144 * {@link SearchParams} protocol buffer builder.
146 void copyToProtocolBuffer(SearchParams
.Builder builder
,
147 boolean enableFacetDiscovery
) {
148 if (enableFacetDiscovery
) {
149 if (discoveryLimit
== null) {
150 builder
.setAutoDiscoverFacetCount(SearchApiLimits
.FACET_DEFAULT_DISCOVERY_LIMIT
);
152 builder
.setAutoDiscoverFacetCount(discoveryLimit
);
155 builder
.clearAutoDiscoverFacetCount();
158 builder
.setFacetDepth(depth
);
160 if (discoveryValueLimit
!= null) {
161 builder
.setFacetAutoDetectParam(
162 FacetAutoDetectParam
.newBuilder().setValueLimit(discoveryValueLimit
));
167 public String
toString() {
168 return new Util
.ToStringHelper("FacetOptions")
169 .addField("discoveryValueLimit", getDiscoveryValueLimit())
170 .addField("discoveryLimit", getDiscoveryLimit())
171 .addField("depth", getDepth())