[Javadocs] add to o.o.search.aggs, builder, and collapse packages (#3254

)

Adds class level javadocs to org.opensearch.search.aggregations, builder, and
collapse packages.

Signed-off-by: Nicholas Walter Knize <nknize@apache.org>

server/src/main/java/org/opensearch/search/aggregations/AbstractAggregationBuilder.java

@@ -43,6 +43,8 @@
 
 /**
  * Base implementation of a {@link AggregationBuilder}.
+ *
+ * @opensearch.internal
  */
 public abstract class AbstractAggregationBuilder<AB extends AbstractAggregationBuilder<AB>> extends AggregationBuilder {
 

server/src/main/java/org/opensearch/search/aggregations/Aggregation.java

@@ -39,6 +39,8 @@
 
 /**
  * An aggregation. Extends {@link ToXContent} as it makes it easier to print out its content.
+ *
+ * @opensearch.internal
  */
 public interface Aggregation extends ToXContentFragment {
 

server/src/main/java/org/opensearch/search/aggregations/AggregationBuilder.java

@@ -48,6 +48,8 @@
 
 /**
  * A factory that knows how to create an {@link Aggregator} of a specific type.
+ *
+ * @opensearch.internal
  */
 public abstract class AggregationBuilder
     implements

server/src/main/java/org/opensearch/search/aggregations/AggregationBuilders.java

@@ -109,6 +109,8 @@
 
 /**
  * Utility class to create aggregations.
+ *
+ * @opensearch.internal
  */
 public class AggregationBuilders {
 

server/src/main/java/org/opensearch/search/aggregations/AggregationExecutionException.java

@@ -38,6 +38,8 @@
 
 /**
  * Thrown when failing to execute an aggregation
+ *
+ * @opensearch.internal
  */
 public class AggregationExecutionException extends OpenSearchException {
 

server/src/main/java/org/opensearch/search/aggregations/AggregationInitializationException.java

@@ -38,6 +38,8 @@
 
 /**
  * Thrown when failing to execute an aggregation
+ *
+ * @opensearch.internal
  */
 public class AggregationInitializationException extends OpenSearchException {
 

server/src/main/java/org/opensearch/search/aggregations/AggregationPhase.java

@@ -51,6 +51,8 @@
 
 /**
  * Aggregation phase of a search request, used to collect aggregations
+ *
+ * @opensearch.internal
  */
 public class AggregationPhase {
 

server/src/main/java/org/opensearch/search/aggregations/Aggregations.java

@@ -53,6 +53,8 @@
 
 /**
  * Represents a set of {@link Aggregation}s
+ *
+ * @opensearch.internal
  */
 public class Aggregations implements Iterable<Aggregation>, ToXContentFragment {
 

server/src/main/java/org/opensearch/search/aggregations/Aggregator.java

@@ -54,6 +54,8 @@
  * <p>
  * Be <strong>careful</strong> when adding methods to this class. If possible
  * make sure they have sensible default implementations.
+ *
+ * @opensearch.internal
  */
 public abstract class Aggregator extends BucketCollector implements Releasable {
 

server/src/main/java/org/opensearch/search/aggregations/AggregatorBase.java

@@ -52,6 +52,8 @@
 
 /**
  * Base implementation for concrete aggregators.
+ *
+ * @opensearch.internal
  */
 public abstract class AggregatorBase extends Aggregator {
 

server/src/main/java/org/opensearch/search/aggregations/AggregatorFactories.java

@@ -77,6 +77,8 @@
 
 /**
  * An immutable collection of {@link AggregatorFactories}.
+ *
+ * @opensearch.internal
  */
 public class AggregatorFactories {
     public static final Pattern VALID_AGG_NAME = Pattern.compile("[^\\[\\]>]+");

server/src/main/java/org/opensearch/search/aggregations/AggregatorFactory.java

@@ -40,6 +40,11 @@
 
 import static org.opensearch.search.aggregations.support.AggregationUsageService.OTHER_SUBTYPE;
 
+/**
+ * Base factory to instantiate an internal aggregator
+ *
+ * @opensearch.internal
+ */
 public abstract class AggregatorFactory {
     protected final String name;
     protected final AggregatorFactory parent;

server/src/main/java/org/opensearch/search/aggregations/BaseAggregationBuilder.java

@@ -40,6 +40,8 @@
 /**
  * Interface shared by {@link AggregationBuilder} and {@link PipelineAggregationBuilder} so they can conveniently share the same namespace
  * for {@link XContentParser#namedObject(Class, String, Object)}.
+ *
+ * @opensearch.internal
  */
 public interface BaseAggregationBuilder {
     /**

server/src/main/java/org/opensearch/search/aggregations/BucketCollector.java

@@ -40,6 +40,8 @@
 
 /**
  * A Collector that can collect data in separate buckets.
+ *
+ * @opensearch.internal
  */
 public abstract class BucketCollector implements Collector {
 

server/src/main/java/org/opensearch/search/aggregations/BucketOrder.java

@@ -49,6 +49,8 @@
  * "complete" buckets using {@link #comparator()} or against a combination
  * of the buckets internals with its ordinal with
  * {@link #partiallyBuiltBucketComparator(ToLongFunction, Aggregator)}.
+ *
+ * @opensearch.internal
  */
 public abstract class BucketOrder implements ToXContentObject, Writeable {
     /**

server/src/main/java/org/opensearch/search/aggregations/CardinalityUpperBound.java

@@ -41,6 +41,8 @@
 /**
  * Upper bound of how many {@code owningBucketOrds} that an {@link Aggregator}
  * will have to collect into.
+ *
+ * @opensearch.internal
  */
 public abstract class CardinalityUpperBound {
     /**

server/src/main/java/org/opensearch/search/aggregations/HasAggregations.java

@@ -32,6 +32,11 @@
 
 package org.opensearch.search.aggregations;
 
+/**
+ * Base interface for buckets that have sub aggs
+ *
+ * @opensearch.internal
+ */
 public interface HasAggregations {
 
     Aggregations getAggregations();

server/src/main/java/org/opensearch/search/aggregations/InternalAggregation.java

@@ -58,6 +58,8 @@
 
 /**
  * An internal implementation of {@link Aggregation}. Serves as a base class for all aggregation implementations.
+ *
+ * @opensearch.internal
  */
 public abstract class InternalAggregation implements Aggregation, NamedWriteable {
     /**

server/src/main/java/org/opensearch/search/aggregations/InternalAggregations.java

@@ -59,6 +59,8 @@
 
 /**
  * An internal implementation of {@link Aggregations}.
+ *
+ * @opensearch.internal
  */
 public final class InternalAggregations extends Aggregations implements Writeable {
 

server/src/main/java/org/opensearch/search/aggregations/InternalMultiBucketAggregation.java

@@ -45,6 +45,11 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+/**
+ * Base class for internal aggregations that are comprised of multiple buckets
+ *
+ * @opensearch.internal
+ */
 public abstract class InternalMultiBucketAggregation<
     A extends InternalMultiBucketAggregation,
     B extends InternalMultiBucketAggregation.InternalBucket> extends InternalAggregation implements MultiBucketsAggregation {

server/src/main/java/org/opensearch/search/aggregations/InternalOrder.java

@@ -58,6 +58,8 @@
 
 /**
  * Implementations for {@link Bucket} ordering strategies.
+ *
+ * @opensearch.internal
  */
 public abstract class InternalOrder extends BucketOrder {
     // TODO merge the contents of this file into BucketOrder. The way it is now is relic.

server/src/main/java/org/opensearch/search/aggregations/InvalidAggregationPathException.java

@@ -37,6 +37,11 @@
 
 import java.io.IOException;
 
+/**
+ * Error thrown when an invalid agg is called
+ *
+ * @opensearch.internal
+ */
 public class InvalidAggregationPathException extends OpenSearchException {
 
     public InvalidAggregationPathException(String msg) {

server/src/main/java/org/opensearch/search/aggregations/KeyComparable.java

@@ -39,6 +39,8 @@
  *
  * @param <T> {@link Bucket} of the same type that also implements {@link KeyComparable}.
  * @see BucketOrder#key(boolean)
+ *
+ * @opensearch.internal
  */
 public interface KeyComparable<T extends Bucket & KeyComparable<T>> {
 

server/src/main/java/org/opensearch/search/aggregations/LeafBucketCollector.java

@@ -42,6 +42,8 @@
 
 /**
  * Per-leaf bucket collector.
+ *
+ * @opensearch.internal
  */
 public abstract class LeafBucketCollector implements LeafCollector {
 

server/src/main/java/org/opensearch/search/aggregations/LeafBucketCollectorBase.java

@@ -41,6 +41,8 @@
  * A {@link LeafBucketCollector} that delegates all calls to the sub leaf
  * aggregator and sets the scorer on its source of values if it implements
  * {@link ScorerAware}.
+ *
+ * @opensearch.internal
  */
 public class LeafBucketCollectorBase extends LeafBucketCollector {
 

server/src/main/java/org/opensearch/search/aggregations/MultiBucketCollector.java

@@ -51,6 +51,8 @@
  * {@link BucketCollector}s. It is similar to the {@link MultiCollector} except that the
  * {@link #wrap} method filters out the {@link BucketCollector#NO_OP_COLLECTOR}s and not
  * the null ones.
+ *
+ * @opensearch.internal
  */
 public class MultiBucketCollector extends BucketCollector {
 

server/src/main/java/org/opensearch/search/aggregations/MultiBucketConsumerService.java

@@ -49,6 +49,8 @@
  * The consumer is used by {@link BucketsAggregator} and {@link InternalMultiBucketAggregation} to limit the number of buckets created
  * in {@link Aggregator#buildAggregations} and {@link InternalAggregation#reduce}.
  * The limit can be set by changing the `search.max_buckets` cluster setting and defaults to 65535.
+ *
+ * @opensearch.internal
  */
 public class MultiBucketConsumerService {
     public static final int DEFAULT_MAX_BUCKETS = 65535;

server/src/main/java/org/opensearch/search/aggregations/NonCollectingAggregator.java

@@ -41,6 +41,8 @@
 /**
  * An aggregator that is not collected, this can typically be used when running an aggregation over a field that doesn't have
  * a mapping.
+ *
+ * @opensearch.internal
  */
 public abstract class NonCollectingAggregator extends AggregatorBase {
     /**

server/src/main/java/org/opensearch/search/aggregations/ParsedAggregation.java

@@ -46,6 +46,8 @@
 /**
  * An implementation of {@link Aggregation} that is parsed from a REST response.
  * Serves as a base class for all aggregation implementations that are parsed from REST.
+ *
+ * @opensearch.internal
  */
 public abstract class ParsedAggregation implements Aggregation, ToXContentFragment {
 

server/src/main/java/org/opensearch/search/aggregations/ParsedMultiBucketAggregation.java

@@ -47,6 +47,11 @@
 
 import static org.opensearch.common.xcontent.XContentParserUtils.ensureExpectedToken;
 
+/**
+ * A multi-bucket agg that has been parsed
+ *
+ * @opensearch.internal
+ */
 public abstract class ParsedMultiBucketAggregation<B extends ParsedMultiBucketAggregation.Bucket> extends ParsedAggregation
     implements
         MultiBucketsAggregation {

server/src/main/java/org/opensearch/search/aggregations/PipelineAggregationBuilder.java

@@ -52,6 +52,8 @@
 /**
  * A factory that knows how to create an {@link PipelineAggregator} of a
  * specific type.
+ *
+ * @opensearch.internal
  */
 public abstract class PipelineAggregationBuilder
     implements

server/src/main/java/org/opensearch/search/aggregations/PipelineAggregatorBuilders.java

@@ -53,6 +53,11 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Builder utility class for pipeline aggs
+ *
+ * @opensearch.internal
+ */
 public final class PipelineAggregatorBuilders {
 
     private PipelineAggregatorBuilders() {}

server/src/main/java/org/opensearch/search/aggregations/SearchContextAggregations.java

@@ -35,6 +35,8 @@
 
 /**
  * The aggregation context that is part of the search context.
+ *
+ * @opensearch.internal
  */
 public class SearchContextAggregations {
 

server/src/main/java/org/opensearch/search/aggregations/bucket/BestBucketsDeferringCollector.java

@@ -61,6 +61,8 @@
  * matches and then is able to replay a given subset of buckets which represent
  * the survivors from a pruning process performed by the aggregator that owns
  * this collector.
+ *
+ * @opensearch.internal
  */
 public class BestBucketsDeferringCollector extends DeferringBucketCollector {
     static class Entry {

server/src/main/java/org/opensearch/search/aggregations/bucket/BucketUtils.java

@@ -33,6 +33,8 @@
 
 /**
  * Helper functions for common Bucketing functions
+ *
+ * @opensearch.internal
  */
 public final class BucketUtils {
 

server/src/main/java/org/opensearch/search/aggregations/bucket/BucketsAggregator.java

@@ -61,6 +61,11 @@
 import java.util.function.LongUnaryOperator;
 import java.util.function.ToLongFunction;
 
+/**
+ * Base class to collect all docs into buckets
+ *
+ * @opensearch.internal
+ */
 public abstract class BucketsAggregator extends AggregatorBase {
 
     private final BigArrays bigArrays;

server/src/main/java/org/opensearch/search/aggregations/bucket/DeferableBucketAggregator.java

@@ -45,6 +45,11 @@
 import java.util.Map;
 import java.util.function.BiConsumer;
 
+/**
+ * Aggregator that defers collecting docs based on some metric
+ *
+ * @opensearch.internal
+ */
 public abstract class DeferableBucketAggregator extends BucketsAggregator {
     /**
      * Wrapper that records collections. Non-null if any aggregations have

server/src/main/java/org/opensearch/search/aggregations/bucket/DeferringBucketCollector.java

@@ -48,6 +48,8 @@
 /**
  * A {@link BucketCollector} that records collected doc IDs and buckets and
  * allows to replay a subset of the collected buckets.
+ *
+ * @opensearch.internal
  */
 public abstract class DeferringBucketCollector extends BucketCollector {
 

server/src/main/java/org/opensearch/search/aggregations/bucket/InternalSingleBucketAggregation.java

@@ -51,6 +51,8 @@
 
 /**
  * A base class for all the single bucket aggregations.
+ *
+ * @opensearch.internal
  */
 public abstract class InternalSingleBucketAggregation extends InternalAggregation implements SingleBucketAggregation {
 

server/src/main/java/org/opensearch/search/aggregations/bucket/IteratorAndCurrent.java

@@ -36,6 +36,11 @@
 
 import java.util.Iterator;
 
+/**
+ * Utility class for keeping track of a current item in an iterator
+ *
+ * @opensearch.internal
+ */
 public class IteratorAndCurrent<B extends InternalMultiBucketAggregation.InternalBucket> implements Iterator<B> {
     private final Iterator<B> iterator;
     private B current;

server/src/main/java/org/opensearch/search/aggregations/bucket/MergingBucketsDeferringCollector.java

@@ -45,6 +45,8 @@
  * matches and then is able to replay a given subset of buckets. Exposes
  * mergeBuckets, which can be invoked by the aggregator when increasing the
  * rounding interval.
+ *
+ * @opensearch.internal
  */
 public class MergingBucketsDeferringCollector extends BestBucketsDeferringCollector {
     public MergingBucketsDeferringCollector(SearchContext context, boolean isGlobal) {