Painless: Restructure Definition/Whitelist (#31879)

Create lookup package
rename Definition to PainlessLookup and move to lookup package
rename Definition.Method to PainlessMethod
rename Definition.MethodKey to PainlessMethod
rename Definition.Field to PainlessField
rename Definition.Struct to PainlessClass
rename Definition.Cast to PainlessCast
rename Whitelist.Struct to WhitelistClass
rename Whitelist.Constructor to WhitelistConstructor
rename Whitelist.Method to WhitelistMethod
rename Whitelist.Field to WhitelistField

Author: jdconrad

modules/lang-painless/spi/src/main/java/org/elasticsearch/painless/spi/Whitelist.java

@@ -24,13 +24,14 @@
 import java.util.Objects;
 
 /**
- * Whitelist contains data structures designed to be used to generate a white-list of Java classes,
+ * Whitelist contains data structures designed to be used to generate a whitelist of Java classes,
  * constructors, methods, and fields that can be used within a Painless script at both compile-time
  * and run-time.
  *
- * A white-list consists of several pieces with {@link Struct}s as the top level.  Each {@link Struct}
- * will contain zero-to-many {@link Constructor}s, {@link Method}s, and {@link Field}s which are what
- * will be available with a Painless script.  See each individual white-list object for more detail.
+ * A whitelist consists of several pieces with {@link WhitelistClass}s as the top level.  Each
+ * {@link WhitelistClass} will contain zero-to-many {@link WhitelistConstructor}s, {@link WhitelistMethod}s, and
+ * {@link WhitelistField}s which are what will be available with a Painless script.  See each individual
+ * whitelist object for more detail.
  */
 public final class Whitelist {
 
@@ -54,166 +55,14 @@ public final class Whitelist {
     public static final List<Whitelist> BASE_WHITELISTS =
         Collections.singletonList(WhitelistLoader.loadFromResourceFiles(Whitelist.class, BASE_WHITELIST_FILES));
 
-    /**
-     * Struct represents the equivalent of a Java class in Painless complete with super classes,
-     * constructors, methods, and fields.  In Painless a class is known as a struct primarily to avoid
-     * naming conflicts internally.  There must be a one-to-one mapping of struct names to Java classes.
-     * Though, since multiple white-lists may be combined into a single white-list for a specific
-     * {@link org.elasticsearch.script.ScriptContext}, as long as multiple structs representing the same
-     * Java class have the same Painless type name and have legal constructor/method overloading they
-     * can be merged together.
-     *
-     * Structs in Painless allow for arity overloading for constructors and methods.  Arity overloading
-     * means that multiple constructors are allowed for a single struct as long as they have a different
-     * number of parameter types, and multiples methods with the same name are allowed for a single struct
-     * as long as they have the same return type and a different number of parameter types.
-     *
-     * Structs will automatically extend other white-listed structs if the Java class they represent is a
-     * subclass of other structs including Java interfaces.
-     */
-    public static final class Struct {
-
-        /** Information about where this struct was white-listed from.  Can be used for error messages. */
-        public final String origin;
-
-        /** The Java class name this struct represents. */
-        public final String javaClassName;
-
-        /**
-         * Allow the Java class name to only be specified as the fully-qualified name.
-         */
-        public final boolean onlyFQNJavaClassName;
-
-        /** The {@link List} of white-listed ({@link Constructor}s) available to this struct. */
-        public final List<Constructor> whitelistConstructors;
-
-        /** The {@link List} of white-listed ({@link Method}s) available to this struct. */
-        public final List<Method> whitelistMethods;
-
-        /** The {@link List} of white-listed ({@link Field}s) available to this struct. */
-        public final List<Field> whitelistFields;
-
-        /** Standard constructor. All values must be not {@code null}. */
-        public Struct(String origin, String javaClassName, boolean onlyFQNJavaClassName,
-                      List<Constructor> whitelistConstructors, List<Method> whitelistMethods, List<Field> whitelistFields) {
-            this.origin = Objects.requireNonNull(origin);
-            this.javaClassName = Objects.requireNonNull(javaClassName);
-            this.onlyFQNJavaClassName = onlyFQNJavaClassName;
-
-            this.whitelistConstructors = Collections.unmodifiableList(Objects.requireNonNull(whitelistConstructors));
-            this.whitelistMethods = Collections.unmodifiableList(Objects.requireNonNull(whitelistMethods));
-            this.whitelistFields = Collections.unmodifiableList(Objects.requireNonNull(whitelistFields));
-        }
-    }
-
-    /**
-     * Constructor represents the equivalent of a Java constructor available as a white-listed struct
-     * constructor within Painless.  Constructors for Painless structs may be accessed exactly as
-     * constructors for Java classes are using the 'new' keyword.  Painless structs may have multiple
-     * constructors as long as they comply with arity overloading described for {@link Struct}.
-     */
-    public static final class Constructor {
-
-        /** Information about where this constructor was white-listed from.  Can be used for error messages. */
-        public final String origin;
-
-        /**
-         * A {@link List} of {@link String}s that are the Painless type names for the parameters of the
-         * constructor which can be used to look up the Java constructor through reflection.
-         */
-        public final List<String> painlessParameterTypeNames;
-
-        /** Standard constructor. All values must be not {@code null}. */
-        public Constructor(String origin, List<String> painlessParameterTypeNames) {
-            this.origin = Objects.requireNonNull(origin);
-            this.painlessParameterTypeNames = Collections.unmodifiableList(Objects.requireNonNull(painlessParameterTypeNames));
-        }
-    }
-
-    /**
-     * Method represents the equivalent of a Java method available as a white-listed struct method
-     * within Painless.  Methods for Painless structs may be accessed exactly as methods for Java classes
-     * are using the '.' operator on an existing struct variable/field.  Painless structs may have multiple
-     * methods with the same name as long as they comply with arity overloading described for {@link Method}.
-     *
-     * Structs may also have additional methods that are not part of the Java class the struct represents -
-     * these are known as augmented methods.  An augmented method can be added to a struct as a part of any
-     * Java class as long as the method is static and the first parameter of the method is the Java class
-     * represented by the struct.  Note that the augmented method's parent Java class does not need to be
-     * white-listed.
-     */
-    public static class Method {
-
-        /** Information about where this method was white-listed from.  Can be used for error messages. */
-        public final String origin;
-
-        /**
-         * The Java class name for the owner of an augmented method.  If the method is not augmented
-         * this should be {@code null}.
-         */
-        public final String javaAugmentedClassName;
-
-        /** The Java method name used to look up the Java method through reflection. */
-        public final String javaMethodName;
-
-        /**
-         * The Painless type name for the return type of the method which can be used to look up the Java
-         * method through reflection.
-         */
-        public final String painlessReturnTypeName;
-
-        /**
-         * A {@link List} of {@link String}s that are the Painless type names for the parameters of the
-         * method which can be used to look up the Java method through reflection.
-         */
-        public final List<String> painlessParameterTypeNames;
-
-        /**
-         * Standard constructor. All values must be not {@code null} with the exception of jAugmentedClass;
-         * jAugmentedClass will be {@code null} unless the method is augmented as described in the class documentation.
-         */
-        public Method(String origin, String javaAugmentedClassName, String javaMethodName,
-                      String painlessReturnTypeName, List<String> painlessParameterTypeNames) {
-            this.origin = Objects.requireNonNull(origin);
-            this.javaAugmentedClassName = javaAugmentedClassName;
-            this.javaMethodName = javaMethodName;
-            this.painlessReturnTypeName = Objects.requireNonNull(painlessReturnTypeName);
-            this.painlessParameterTypeNames = Collections.unmodifiableList(Objects.requireNonNull(painlessParameterTypeNames));
-        }
-    }
-
-    /**
-     * Field represents the equivalent of a Java field available as a white-listed struct field
-     * within Painless.  Fields for Painless structs may be accessed exactly as fields for Java classes
-     * are using the '.' operator on an existing struct variable/field.
-     */
-    public static class Field {
-
-        /** Information about where this method was white-listed from.  Can be used for error messages. */
-        public final String origin;
-
-        /** The Java field name used to look up the Java field through reflection. */
-        public final String javaFieldName;
-
-        /** The Painless type name for the field which can be used to look up the Java field through reflection. */
-        public final String painlessFieldTypeName;
-
-        /** Standard constructor.  All values must be not {@code null}. */
-        public Field(String origin, String javaFieldName, String painlessFieldTypeName) {
-            this.origin = Objects.requireNonNull(origin);
-            this.javaFieldName = Objects.requireNonNull(javaFieldName);
-            this.painlessFieldTypeName = Objects.requireNonNull(painlessFieldTypeName);
-        }
-    }
-
-    /** The {@link ClassLoader} used to look up the white-listed Java classes, constructors, methods, and fields. */
+    /** The {@link ClassLoader} used to look up the whitelisted Java classes, constructors, methods, and fields. */
     public final ClassLoader javaClassLoader;
 
-    /** The {@link List} of all the white-listed Painless structs. */
-    public final List<Struct> whitelistStructs;
+    /** The {@link List} of all the whitelisted Painless classes. */
+    public final List<WhitelistClass> whitelistStructs;
 
     /** Standard constructor.  All values must be not {@code null}. */
-    public Whitelist(ClassLoader javaClassLoader, List<Struct> whitelistStructs) {
+    public Whitelist(ClassLoader javaClassLoader, List<WhitelistClass> whitelistStructs) {
         this.javaClassLoader = Objects.requireNonNull(javaClassLoader);
         this.whitelistStructs = Collections.unmodifiableList(Objects.requireNonNull(whitelistStructs));
     }

modules/lang-painless/spi/src/main/java/org/elasticsearch/painless/spi/WhitelistClass.java

@@ -0,0 +1,76 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.painless.spi;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Class represents the equivalent of a Java class in Painless complete with super classes,
+ * constructors, methods, and fields. There must be a one-to-one mapping of class names to Java
+ * classes. Though, since multiple whitelists may be combined into a single whitelist for a
+ * specific context, as long as multiple classes representing the same Java class have the same
+ * class name and have legal constructor/method overloading they can be merged together.
+ *
+ * Classes in Painless allow for arity overloading for constructors and methods.  Arity overloading
+ * means that multiple constructors are allowed for a single class as long as they have a different
+ * number of parameters, and multiples methods with the same name are allowed for a single class
+ * as long as they have the same return type and a different number of parameters.
+ *
+ * Classes will automatically extend other whitelisted classes if the Java class they represent is a
+ * subclass of other classes including Java interfaces.
+ */
+public final class WhitelistClass {
+
+    /** Information about where this class was white-listed from.  Can be used for error messages. */
+    public final String origin;
+
+    /** The Java class name this class represents. */
+    public final String javaClassName;
+
+    /**
+     * Allow the Java class name to only be specified as the fully-qualified name.
+     */
+    public final boolean onlyFQNJavaClassName;
+
+    /** The {@link List} of whitelisted ({@link WhitelistConstructor}s) available to this class. */
+    public final List<WhitelistConstructor> whitelistConstructors;
+
+    /** The {@link List} of whitelisted ({@link WhitelistMethod}s) available to this class. */
+    public final List<WhitelistMethod> whitelistMethods;
+
+    /** The {@link List} of whitelisted ({@link WhitelistField}s) available to this class. */
+    public final List<WhitelistField> whitelistFields;
+
+    /** Standard constructor. All values must be not {@code null}. */
+    public WhitelistClass(String origin, String javaClassName, boolean onlyFQNJavaClassName,
+                          List<WhitelistConstructor> whitelistConstructors,
+                          List<WhitelistMethod> whitelistMethods,
+                          List<WhitelistField> whitelistFields) {
+        this.origin = Objects.requireNonNull(origin);
+        this.javaClassName = Objects.requireNonNull(javaClassName);
+        this.onlyFQNJavaClassName = onlyFQNJavaClassName;
+
+        this.whitelistConstructors = Collections.unmodifiableList(Objects.requireNonNull(whitelistConstructors));
+        this.whitelistMethods = Collections.unmodifiableList(Objects.requireNonNull(whitelistMethods));
+        this.whitelistFields = Collections.unmodifiableList(Objects.requireNonNull(whitelistFields));
+    }
+}

modules/lang-painless/spi/src/main/java/org/elasticsearch/painless/spi/WhitelistConstructor.java

@@ -0,0 +1,48 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.painless.spi;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Constructor represents the equivalent of a Java constructor available as a whitelisted class
+ * constructor within Painless.  Constructors for Painless classes may be accessed exactly as
+ * constructors for Java classes are using the 'new' keyword.  Painless classes may have multiple
+ * constructors as long as they comply with arity overloading described for {@link WhitelistClass}.
+ */
+public final class WhitelistConstructor {
+
+    /** Information about where this constructor was whitelisted from.  Can be used for error messages. */
+    public final String origin;
+
+    /**
+     * A {@link List} of {@link String}s that are the Painless type names for the parameters of the
+     * constructor which can be used to look up the Java constructor through reflection.
+     */
+    public final List<String> painlessParameterTypeNames;
+
+    /** Standard constructor. All values must be not {@code null}. */
+    public WhitelistConstructor(String origin, List<String> painlessParameterTypeNames) {
+        this.origin = Objects.requireNonNull(origin);
+        this.painlessParameterTypeNames = Collections.unmodifiableList(Objects.requireNonNull(painlessParameterTypeNames));
+    }
+}

modules/lang-painless/spi/src/main/java/org/elasticsearch/painless/spi/WhitelistField.java

@@ -0,0 +1,46 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.painless.spi;
+
+import java.util.Objects;
+
+/**
+ * Field represents the equivalent of a Java field available as a whitelisted class field
+ * within Painless.  Fields for Painless classes may be accessed exactly as fields for Java classes
+ * are using the '.' operator on an existing class variable/field.
+ */
+public class WhitelistField {
+
+    /** Information about where this method was whitelisted from.  Can be used for error messages. */
+    public final String origin;
+
+    /** The Java field name used to look up the Java field through reflection. */
+    public final String javaFieldName;
+
+    /** The Painless type name for the field which can be used to look up the Java field through reflection. */
+    public final String painlessFieldTypeName;
+
+    /** Standard constructor.  All values must be not {@code null}. */
+    public WhitelistField(String origin, String javaFieldName, String painlessFieldTypeName) {
+        this.origin = Objects.requireNonNull(origin);
+        this.javaFieldName = Objects.requireNonNull(javaFieldName);
+        this.painlessFieldTypeName = Objects.requireNonNull(painlessFieldTypeName);
+    }
+}