Add javadocs to example-plugins:painless-allowlist

Signed-off-by: Daniel Widdis <widdis@gmail.com>
opensearch-project · dblock · Sep 19, 2022 · Sep 17, 2022 · Sep 17, 2022 · Sep 17, 2022
commit 1191cdbef1518b3a2d86f91694667c3349604ed4
@@ -96,7 +96,6 @@ configure([
   project(":client:rest-high-level"),
   project(":client:test"),
   project(":doc-tools"),
-  project(":example-plugins:painless-allowlist"),
   project(":example-plugins:rescore"),
   project(":example-plugins:rest-handler"),
   project(":example-plugins:script-expert-scoring"),

@@ -36,13 +36,17 @@
 
 import java.util.Map;
 
+/**
+ * A singleton class to parse Allowlist Annotations.
+ */
 public class ExampleAllowlistAnnotationParser implements AllowlistAnnotationParser {
 
+    /**
+     * The singleton instance of this class.
+     */
     public static final ExampleAllowlistAnnotationParser INSTANCE = new ExampleAllowlistAnnotationParser();
 
-    private ExampleAllowlistAnnotationParser() {
-
-    }
+    private ExampleAllowlistAnnotationParser() {}
 
     @Override
     public Object parse(Map<String, String> arguments) {

@@ -49,6 +49,11 @@
 /** An extension of painless which adds an allowlist. */
 public class ExampleAllowlistExtension implements PainlessExtension {
 
+    /**
+     * Instantiate this class.
+     */
+    public ExampleAllowlistExtension() {}
+
     @Override
     public Map<ScriptContext<?>, List<Allowlist>> getContextAllowlists() {
         Map<String, AllowlistAnnotationParser> parsers = new HashMap<>(AllowlistAnnotationParser.BASE_ANNOTATION_PARSERS);

@@ -40,35 +40,67 @@
  */
 public class ExampleAllowlistedClass {
 
+    /**
+     * An example constant.
+     */
     public static final int CONSTANT = 42;
 
+    /**
+     * An example public member.
+     */
     public int publicMember;
 
     private int privateMember;
 
+    /**
+     * Construct this example class with the given public and private members.
+     *
+     * @param publicMember The value for the public member.
+     * @param privateMember The value for the private member.
+     */
     public ExampleAllowlistedClass(int publicMember, int privateMember) {
         this.publicMember = publicMember;
         this.privateMember = privateMember;
     }
 
+    /**
+     * Get the value of the private member.
+     *
+     * @return the value of the private member.
+     */
     public int getPrivateMemberAccessor() {
         return this.privateMember;
     }
 
+    /**
+     * Set the value of the private member.
+     *
+     * @param privateMember the value to set.
+     */
     public void setPrivateMemberAccessor(int privateMember) {
         this.privateMember = privateMember;
     }
 
+    /**
+     * An example static method. You may be shocked, but it does nothing.
+     */
     public static void staticMethod() {
         // electricity
     }
 
-    // example augmentation method
+    /**
+     * An example static augmentation method that takes the object to operate on as the first argument to a static method.
+     *
+     * @param x The String to be operated on.
+     * @return an integer parsed from the input.
+     */
     public static int toInt(String x) {
         return Integer.parseInt(x);
     }
 
-    // example method to attach annotations in allowlist
+    /**
+     * An example method to attach annotations in allowlist.
+     */
     public void annotate() {
         // some logic here
     }

@@ -32,17 +32,38 @@
 
 package org.opensearch.example.painlessallowlist;
 
+/**
+ * An example of an instance to be allowlisted for use by painless scripts.
+ *
+ * Each of the members and methods below are allowlisted for use in search scripts but only from this instance.
+ */
 public class ExampleAllowlistedInstance {
     private final int value;
 
+    /**
+     * Instantiate this instance with a value.
+     *
+     * @param value A base value to set.
+     */
     public ExampleAllowlistedInstance(int value) {
         this.value = value;
     }
 
+    /**
+     * A method that can be allowlisted to add an input value to the stored base value.
+     *
+     * @param value The value to add.
+     * @return The sum of the base value and the new value. The base value remains unchanged.
+     */
     public int addValue(int value) {
         return this.value + value;
     }
 
+    /**
+     * Get the stored base value.
+     *
+     * @return The base value.
+     */
     public int getValue() {
         return value;
     }

@@ -32,22 +32,53 @@
 
 package org.opensearch.example.painlessallowlist;
 
+/**
+ * An example of an annotation to be allowlisted for use by painless scripts
+ *
+ * The annotation below is allowlisted for use in search scripts.
+ * See <a href="file:example_allowlist.txt">example_allowlist.txt</a>.
+ */
 public class ExamplePainlessAnnotation {
 
+    /**
+     * The annotation name.
+     */
     public static final String NAME = "example_annotation";
 
+    /**
+     * The category field of the annotation.
+     */
     public int category;
+    /**
+     * The message field of the annotation.
+     */
     public String message;
 
+    /**
+     * Create this annotation with the given category and message.
+     *
+     * @param category The category of the annotation..
+     * @param message The message for the annotation.
+     */
     public ExamplePainlessAnnotation(int category, String message) {
         this.category = category;
         this.message = message;
     }
 
+    /**
+     * Gets the category.
+     *
+     * @return the category.
+     */
     public int getCategory() {
         return category;
     }
 
+    /**
+     * Gets the message.
+     *
+     * @return the message.
+     */
     public String getMessage() {
         return message;
     }

@@ -32,7 +32,23 @@
 
 package org.opensearch.example.painlessallowlist;
 
+/**
+ * An example of a class with static methods to be allowlisted for use by painless scripts
+ *
+ * The method below is allowlisted for use in search scripts.
+ * See <a href="file:example_allowlist.txt">example_allowlist.txt</a>.
+ */
 public class ExampleStaticMethodClass {
+
+    private ExampleStaticMethodClass() {}
+
+    /**
+     * An example static method to add integers.
+     *
+     * @param x A number to add.
+     * @param y Another number to add.
+     * @return The sum of x and y.
+     */
     public static int exampleAddInts(int x, int y) {
         return x + y;
     }

@@ -34,6 +34,14 @@
 
 import org.opensearch.plugins.Plugin;
 
+/**
+ * A class extending {@link Plugin} intended as a signpost.
+ * Does nothing and should not be instantiated, since allowlists are extended through SPI.
+ * See {@link ExampleAllowlistExtension} for implementation details.
+ */
 public class MyAllowlistPlugin extends Plugin {
-    // we don't actually need anything here, since allowlists are extended through SPI
+
+    private MyAllowlistPlugin() {}
+
+    // we don't actually need anything here,
 }
@@ -0,0 +1,12 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ */
+
+/**
+ * Example classes demonstrating addition of classes to a Painless allowlist.
+ */
+package org.opensearch.example.painlessallowlist;