[Javadocs] add to o.o.rest, snapshots, and tasks packages (#3219) (#3311

)

Adds javadocs to org.opensearch.rest, snapshots, and tasks packages.

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

server/src/main/java/org/opensearch/rest/AbstractRestChannel.java

@@ -47,6 +47,11 @@
 
 import static java.util.stream.Collectors.toSet;
 
+/**
+ * Base REST channel
+ *
+ * @opensearch.api
+ */
 public abstract class AbstractRestChannel implements RestChannel {
 
     private static final Predicate<String> INCLUDE_FILTER = f -> f.charAt(0) != '-';

server/src/main/java/org/opensearch/rest/BaseRestHandler.java

@@ -66,6 +66,8 @@
  * the transport requests executed by the associated client. While the context is fully copied over, not all the headers
  * are copied, but a selected few. It is possible to control what headers are copied over by returning them in
  * {@link ActionPlugin#getRestHeaders()}.
+ *
+ * @opensearch.api
  */
 public abstract class BaseRestHandler implements RestHandler {
 

server/src/main/java/org/opensearch/rest/BytesRestResponse.java

@@ -52,6 +52,11 @@
 import static org.opensearch.OpenSearchException.REST_EXCEPTION_SKIP_STACK_TRACE_DEFAULT;
 import static org.opensearch.common.xcontent.XContentParserUtils.ensureExpectedToken;
 
+/**
+ * REST response in bytes
+ *
+ * @opensearch.api
+ */
 public class BytesRestResponse extends RestResponse {
 
     public static final String TEXT_CONTENT_TYPE = "text/plain; charset=UTF-8";

server/src/main/java/org/opensearch/rest/DeprecationRestHandler.java

@@ -40,6 +40,8 @@
 /**
  * {@code DeprecationRestHandler} provides a proxy for any existing {@link RestHandler} so that usage of the handler can be
  * logged using the {@link DeprecationLogger}.
+ *
+ * @opensearch.api
  */
 public class DeprecationRestHandler implements RestHandler {
 

server/src/main/java/org/opensearch/rest/MethodHandlers.java

@@ -40,6 +40,8 @@
 
 /**
  * Encapsulate multiple handlers for the same path, allowing different handlers for different HTTP verbs.
+ *
+ * @opensearch.api
  */
 final class MethodHandlers {
 

server/src/main/java/org/opensearch/rest/RestChannel.java

@@ -41,6 +41,8 @@
 
 /**
  * A channel used to construct bytes / builder based outputs, and send responses.
+ *
+ * @opensearch.api
  */
 public interface RestChannel {
 

server/src/main/java/org/opensearch/rest/RestController.java

@@ -75,6 +75,11 @@
 import static org.opensearch.rest.RestStatus.NOT_ACCEPTABLE;
 import static org.opensearch.rest.RestStatus.OK;
 
+/**
+ * OpenSearch REST controller
+ *
+ * @opensearch.api
+ */
 public class RestController implements HttpServerTransport.Dispatcher {
 
     private static final Logger logger = LogManager.getLogger(RestController.class);

server/src/main/java/org/opensearch/rest/RestHandler.java

@@ -43,6 +43,8 @@
 
 /**
  * Handler for REST requests
+ *
+ * @opensearch.api
  */
 @FunctionalInterface
 public interface RestHandler {

server/src/main/java/org/opensearch/rest/RestHeaderDefinition.java

@@ -35,6 +35,8 @@
 /**
  * A definition for an http header that should be copied to the {@link org.opensearch.common.util.concurrent.ThreadContext} when
  * reading the request on the rest layer.
+ *
+ * @opensearch.api
  */
 public final class RestHeaderDefinition {
     private final String name;

server/src/main/java/org/opensearch/rest/RestRequest.java

@@ -67,6 +67,11 @@
 import static org.opensearch.common.unit.ByteSizeValue.parseBytesSizeValue;
 import static org.opensearch.common.unit.TimeValue.parseTimeValue;
 
+/**
+ * REST Request
+ *
+ * @opensearch.api
+ */
 public class RestRequest implements ToXContent.Params {
 
     // tchar pattern as defined by RFC7230 section 3.2.6

server/src/main/java/org/opensearch/rest/RestRequestFilter.java

@@ -48,6 +48,8 @@
 /**
  * Identifies an object that supplies a filter for the content of a {@link RestRequest}. This interface should be implemented by a
  * {@link org.opensearch.rest.RestHandler} that expects there will be sensitive content in the body of the request such as a password
+ *
+ * @opensearch.api
  */
 public interface RestRequestFilter {
 

server/src/main/java/org/opensearch/rest/RestResponse.java

@@ -42,6 +42,11 @@
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * OpenSearch REST response
+ *
+ * @opensearch.api
+ */
 public abstract class RestResponse {
 
     private Map<String, List<String>> customHeaders;

server/src/main/java/org/opensearch/rest/RestStatus.java

@@ -42,6 +42,11 @@
 
 import static java.util.Collections.unmodifiableMap;
 
+/**
+ * OpenSearch REST status
+ *
+ * @opensearch.api
+ */
 public enum RestStatus {
     /**
      * The client SHOULD continue with its request. This interim response is used to inform the client that the

server/src/main/java/org/opensearch/rest/RestUtils.java

@@ -42,6 +42,11 @@
 import java.util.Map;
 import java.util.regex.Pattern;
 
+/**
+ * REST utility class
+ *
+ * @opensearch.api
+ */
 public class RestUtils {
 
     /**

server/src/main/java/org/opensearch/rest/action/RestActionListener.java

@@ -43,6 +43,8 @@
 /**
  * An action listener that requires {@link #processResponse(Object)} to be implemented
  * and will automatically handle failures.
+ *
+ * @opensearch.api
  */
 public abstract class RestActionListener<Response> implements ActionListener<Response> {
 

server/src/main/java/org/opensearch/rest/action/RestActions.java

@@ -61,6 +61,11 @@
 
 import static org.opensearch.index.query.AbstractQueryBuilder.parseInnerQueryBuilder;
 
+/**
+ * REST actions
+ *
+ * @opensearch.api
+ */
 public class RestActions {
 
     public static final ParseField _SHARDS_FIELD = new ParseField("_shards");

server/src/main/java/org/opensearch/rest/action/RestBuilderListener.java

@@ -38,6 +38,8 @@
 
 /**
  * A REST action listener that builds an {@link XContentBuilder} based response.
+ *
+ * @opensearch.api
  */
 public abstract class RestBuilderListener<Response> extends RestResponseListener<Response> {
 

server/src/main/java/org/opensearch/rest/action/RestCancellableNodeClient.java

@@ -58,6 +58,8 @@
 /**
  * A {@linkplain Client} that cancels tasks executed locally when the provided {@link HttpChannel}
  * is closed before completion.
+ *
+ * @opensearch.api
  */
 public class RestCancellableNodeClient extends FilterClient {
     private static final Map<HttpChannel, CloseListener> httpChannels = new ConcurrentHashMap<>();

server/src/main/java/org/opensearch/rest/action/RestFieldCapabilitiesAction.java

@@ -47,6 +47,11 @@
 import static org.opensearch.rest.RestRequest.Method.GET;
 import static org.opensearch.rest.RestRequest.Method.POST;
 
+/**
+ * Transport action to get field capabilities
+ *
+ * @opensearch.api
+ */
 public class RestFieldCapabilitiesAction extends BaseRestHandler {
 
     @Override

server/src/main/java/org/opensearch/rest/action/RestMainAction.java

@@ -51,6 +51,11 @@
 import static org.opensearch.rest.RestRequest.Method.GET;
 import static org.opensearch.rest.RestRequest.Method.HEAD;
 
+/**
+ * Main OpenSearch Transport action
+ *
+ * @opensearch.api
+ */
 public class RestMainAction extends BaseRestHandler {
 
     @Override

server/src/main/java/org/opensearch/rest/action/RestResponseListener.java

@@ -38,6 +38,8 @@
 /**
  * A REST enabled action listener that has a basic onFailure implementation, and requires
  * sub classes to only implement {@link #buildResponse(Object)}.
+ *
+ * @opensearch.api
  */
 public abstract class RestResponseListener<Response> extends RestActionListener<Response> {
 

server/src/main/java/org/opensearch/rest/action/RestStatusToXContentListener.java

@@ -42,6 +42,8 @@
 
 /**
  * Content listener that extracts that {@link RestStatus} from the response.
+ *
+ * @opensearch.api
  */
 public class RestStatusToXContentListener<Response extends StatusToXContentObject> extends RestToXContentListener<Response> {
     private final Function<Response, String> extractLocation;

server/src/main/java/org/opensearch/rest/action/RestToXContentListener.java

@@ -43,6 +43,8 @@
 /**
  * A REST based action listener that assumes the response is of type {@link ToXContent} and automatically
  * builds an XContent based response (wrapping the toXContent in startObject/endObject).
+ *
+ * @opensearch.api
  */
 public class RestToXContentListener<Response extends ToXContentObject> extends RestResponseListener<Response> {
 

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestAddVotingConfigExclusionAction.java

@@ -49,6 +49,11 @@
 
 import static org.opensearch.rest.RestRequest.Method.POST;
 
+/**
+ * Transport action to add voting config exclusions
+ *
+ * @opensearch.api
+ */
 public class RestAddVotingConfigExclusionAction extends BaseRestHandler {
     private static final TimeValue DEFAULT_TIMEOUT = TimeValue.timeValueSeconds(30L);
     private static final Logger logger = LogManager.getLogger(RestAddVotingConfigExclusionAction.class);

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestCancelTasksAction.java

@@ -49,6 +49,11 @@
 import static org.opensearch.rest.RestRequest.Method.POST;
 import static org.opensearch.rest.action.admin.cluster.RestListTasksAction.listTasksResponseListener;
 
+/**
+ * Transport action to cancel tasks
+ *
+ * @opensearch.api
+ */
 public class RestCancelTasksAction extends BaseRestHandler {
     private final Supplier<DiscoveryNodes> nodesInCluster;
 

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestCleanupRepositoryAction.java

@@ -48,6 +48,8 @@
 
 /**
  * Cleans up a repository
+ *
+ * @opensearch.api
  */
 public class RestCleanupRepositoryAction extends BaseRestHandler {
 

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestClearVotingConfigExclusionsAction.java

@@ -45,6 +45,11 @@
 import static java.util.Collections.singletonList;
 import static org.opensearch.rest.RestRequest.Method.DELETE;
 
+/**
+ * Transport action to clear voting config exclusions
+ *
+ * @opensearch.api
+ */
 public class RestClearVotingConfigExclusionsAction extends BaseRestHandler {
 
     @Override

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestCloneSnapshotAction.java

@@ -50,6 +50,8 @@
 
 /**
  * Clones indices from one snapshot into another snapshot in the same repository
+ *
+ * @opensearch.api
  */
 public class RestCloneSnapshotAction extends BaseRestHandler {
 

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestClusterAllocationExplainAction.java

@@ -55,6 +55,8 @@
 
 /**
  * Class handling cluster allocation explanation at the REST level
+ *
+ * @opensearch.api
  */
 public class RestClusterAllocationExplainAction extends BaseRestHandler {
 

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestClusterGetSettingsAction.java

@@ -58,6 +58,11 @@
 import static java.util.Collections.singletonList;
 import static org.opensearch.rest.RestRequest.Method.GET;
 
+/**
+ * Transport action to get settings
+ *
+ * @opensearch.api
+ */
 public class RestClusterGetSettingsAction extends BaseRestHandler {
 
     private static final DeprecationLogger deprecationLogger = DeprecationLogger.getLogger(RestClusterGetSettingsAction.class);

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestClusterHealthAction.java

@@ -55,6 +55,11 @@
 import static org.opensearch.client.Requests.clusterHealthRequest;
 import static org.opensearch.rest.RestRequest.Method.GET;
 
+/**
+ * Transport action to get cluster health
+ *
+ * @opensearch.api
+ */
 public class RestClusterHealthAction extends BaseRestHandler {
 
     private static final DeprecationLogger deprecationLogger = DeprecationLogger.getLogger(RestClusterHealthAction.class);

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestClusterRerouteAction.java

@@ -58,6 +58,11 @@
 import static java.util.Collections.singletonList;
 import static org.opensearch.rest.RestRequest.Method.POST;
 
+/**
+ * Transport action to reroute documents
+ *
+ * @opensearch.api
+ */
 public class RestClusterRerouteAction extends BaseRestHandler {
     private static final ObjectParser<ClusterRerouteRequest, Void> PARSER = new ObjectParser<>("cluster_reroute");
     static {

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestClusterSearchShardsAction.java

@@ -49,6 +49,11 @@
 import static org.opensearch.rest.RestRequest.Method.GET;
 import static org.opensearch.rest.RestRequest.Method.POST;
 
+/**
+ * Transport action to search shards
+ *
+ * @opensearch.api
+ */
 public class RestClusterSearchShardsAction extends BaseRestHandler {
 
     @Override

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestClusterStateAction.java

@@ -64,6 +64,11 @@
 import static java.util.Collections.unmodifiableList;
 import static org.opensearch.rest.RestRequest.Method.GET;
 
+/**
+ * Transport action to get cluster state
+ *
+ * @opensearch.api
+ */
 public class RestClusterStateAction extends BaseRestHandler {
 
     private final SettingsFilter settingsFilter;

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestClusterStatsAction.java

@@ -45,6 +45,11 @@
 import static java.util.Collections.unmodifiableList;
 import static org.opensearch.rest.RestRequest.Method.GET;
 
+/**
+ * Transport action to get cluster stats
+ *
+ * @opensearch.api
+ */
 public class RestClusterStatsAction extends BaseRestHandler {
 
     @Override

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestClusterUpdateSettingsAction.java

@@ -50,6 +50,11 @@
 import static java.util.Collections.singletonList;
 import static org.opensearch.rest.RestRequest.Method.PUT;
 
+/**
+ * Transport action to update cluster settings
+ *
+ * @opensearch.api
+ */
 public class RestClusterUpdateSettingsAction extends BaseRestHandler {
 
     private static final DeprecationLogger deprecationLogger = DeprecationLogger.getLogger(RestClusterUpdateSettingsAction.class);

server/src/main/java/org/opensearch/rest/action/admin/cluster/RestCreateSnapshotAction.java

@@ -50,6 +50,8 @@
 
 /**
  * Creates a new snapshot
+ *
+ * @opensearch.api
  */
 public class RestCreateSnapshotAction extends BaseRestHandler {