Merge remote-tracking branch 'origin/GP-2618_Dan_scriptErrorMessages--SQUASHED'

Ghidra/Debug/Debugger/src/main/java/ghidra/app/plugin/core/debug/gui/objects/DebuggerObjectsProvider.java

@@ -20,6 +20,7 @@ import java.awt.Color;
 import java.awt.event.MouseEvent;
 import java.io.PrintWriter;
 import java.lang.invoke.MethodHandles;
+import java.lang.reflect.InvocationTargetException;
 import java.util.*;
 import java.util.Map.Entry;
 import java.util.concurrent.CompletableFuture;
@@ -1592,7 +1593,7 @@ public class DebuggerObjectsProvider extends ComponentProviderAdapter
 		try {
 			script = provider.getScriptInstance(sourceFile, writer);
 		}
-		catch (ClassNotFoundException | InstantiationException | IllegalAccessException e) {
+		catch (GhidraScriptLoadException e) {
 			Msg.error(this, e.getMessage());
 			return;
 		}

Ghidra/Features/Base/src/main/java/ghidra/app/plugin/core/script/GhidraScriptComponentProvider.java

@@ -19,6 +19,7 @@ import java.awt.BorderLayout;
 import java.awt.Rectangle;
 import java.awt.event.*;
 import java.io.*;
+import java.lang.reflect.InvocationTargetException;
 import java.util.*;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Predicate;
@@ -671,14 +672,9 @@ public class GhidraScriptComponentProvider extends ComponentProviderAdapter {
 		try {
 			return provider.getScriptInstance(scriptFile, console.getStdErr());
 		}
-		catch (IllegalAccessException e) {
+		catch (GhidraScriptLoadException e) {
-			console.addErrorMessage("", "Unable to access script: " + scriptName);
+			console.addErrorMessage("", "Unable to load script: " + scriptName);
-		}
+			console.addErrorMessage("", "  detail: " + e.getMessage());
-		catch (InstantiationException e) {
-			console.addErrorMessage("", "Unable to instantiate script: " + scriptName);
-		}
-		catch (ClassNotFoundException e) {
-			console.addErrorMessage("", "Unable to locate script class: " + scriptName);
 		}
 
 		// show the error icon

Ghidra/Features/Base/src/main/java/ghidra/app/script/GhidraScriptLoadException.java

@@ -0,0 +1,58 @@
+/* ###
+ * IP: GHIDRA
+ *
+ * Licensed 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 ghidra.app.script;
+
+import ghidra.util.exception.UsrException;
+
+/**
+ * An exception for when a script provider cannot create a script instance
+ */
+public class GhidraScriptLoadException extends UsrException {
+	/**
+	 * Construct an exception with a custom message and cause
+	 * 
+	 * <p>
+	 * Note that the error message displayed to the user does not automatically include details from
+	 * the cause. The client must provide details from the cause in the message as needed.
+	 * 
+	 * @param message the error message including details and possible remedies
+	 * @param cause the exception causing this one
+	 */
+	public GhidraScriptLoadException(String message, Throwable cause) {
+		super(message, cause);
+	}
+
+	/**
+	 * Construct an exception with a message
+	 * 
+	 * @param message the error message including details and possible remedies
+	 */
+	public GhidraScriptLoadException(String message) {
+		super(message);
+	}
+
+	/**
+	 * Construct an exception with a cause
+	 * 
+	 * <p>
+	 * This will copy the cause's message into this exception's message.
+	 * 
+	 * @param cause the exception causing this one
+	 */
+	public GhidraScriptLoadException(Throwable cause) {
+		super(cause.getMessage(), cause);
+	}
+}

Ghidra/Features/Base/src/main/java/ghidra/app/script/GhidraScriptProvider.java

@@ -23,9 +23,11 @@ import generic.jar.ResourceFile;
 import ghidra.util.classfinder.ExtensionPoint;
 
 /**
- * NOTE:  ALL GhidraScriptProvider CLASSES MUST END IN "ScriptProvider".  If not,
+ * A provider that can compile, interpret, load, etc., Ghidra Scripts from a given language.
- * the ClassSearcher will not find them.
  * 
+ * <p>
+ * <b>NOTE:</b> ALL GhidraScriptProvider CLASSES MUST END IN "ScriptProvider". If not, the
+ * ClassSearcher will not find them.
  */
 public abstract class GhidraScriptProvider
 		implements ExtensionPoint, Comparable<GhidraScriptProvider> {
@@ -56,6 +58,7 @@ public abstract class GhidraScriptProvider
 
 	/**
 	 * Deletes the script file and unloads the script from the script manager.
+	 * 
 	 * @param scriptSource the script source file
 	 * @return true if the script was completely deleted and cleaned up
 	 */
@@ -65,31 +68,36 @@ public abstract class GhidraScriptProvider
 
 	/**
 	 * Returns a description for this type of script.
+	 * 
 	 * @return a description for this type of script
 	 */
 	public abstract String getDescription();
 
 	/**
 	 * Returns the file extension for this type of script.
+	 * 
+	 * <p>
 	 * For example, ".java" or ".py".
+	 * 
 	 * @return the file extension for this type of script
 	 */
 	public abstract String getExtension();
 
 	/**
 	 * Returns a GhidraScript instance for the specified source file.
+	 * 
 	 * @param sourceFile the source file
-	 * @param writer the print writer to write warning/error messages
+	 * @param writer the print writer to write warning/error messages. If the error prevents
+	 *            success, throw an exception instead. The caller will print the error.
 	 * @return a GhidraScript instance for the specified source file
-	 * @throws ClassNotFoundException if the script class cannot be found
+	 * @throws GhidraScriptLoadException when the script instance cannot be created
-	 * @throws InstantiationException if the construction of the script fails for some reason
-	 * @throws IllegalAccessException if the class constructor is not accessible
 	 */
 	public abstract GhidraScript getScriptInstance(ResourceFile sourceFile, PrintWriter writer)
-			throws ClassNotFoundException, InstantiationException, IllegalAccessException;
+			throws GhidraScriptLoadException;
 
 	/**
 	 * Creates a new script using the specified file.
+	 * 
 	 * @param newScript the new script file
 	 * @param category the script category
 	 * @throws IOException if an error occurs writing the file
@@ -99,7 +107,10 @@ public abstract class GhidraScriptProvider
 
 	/**
 	 * Returns a Pattern that matches block comment openings.
+	 * 
+	 * <p>
 	 * If block comments are not supported by this provider, then this returns null.
+	 * 
 	 * @return the Pattern for block comment openings, null if block comments are not supported
 	 */
 	public Pattern getBlockCommentStart() {
@@ -108,7 +119,10 @@ public abstract class GhidraScriptProvider
 
 	/**
 	 * Returns a Pattern that matches block comment closings.
+	 * 
+	 * <p>
 	 * If block comments are not supported by this provider, then this returns null.
+	 * 
 	 * @return the Pattern for block comment closings, null if block comments are not supported
 	 */
 	public Pattern getBlockCommentEnd() {
@@ -117,14 +131,20 @@ public abstract class GhidraScriptProvider
 
 	/**
 	 * Returns the comment character.
+	 * 
+	 * <p>
 	 * For example, "//" or "#".
+	 * 
 	 * @return the comment character
 	 */
 	public abstract String getCommentCharacter();
 
 	/**
 	 * Writes the script header.
+	 * 
+	 * <p>
 	 * Include a place holder for each meta-data item.
+	 * 
 	 * @param writer the print writer
 	 * @param category the default category
 	 */
@@ -150,6 +170,7 @@ public abstract class GhidraScriptProvider
 
 	/**
 	 * Writes the script body template.
+	 * 
 	 * @param writer the print writer
 	 */
 	protected void writeBody(PrintWriter writer) {
@@ -159,8 +180,9 @@ public abstract class GhidraScriptProvider
 	/**
 	 * Fixup a script name for searching in script directories.
 	 *
-	 * <p>This method is part of a poorly specified behavior that is due for future amendment, 
+	 * <p>
-	 * see {@link GhidraScriptUtil#fixupName(String)}.
+	 * This method is part of a poorly specified behavior that is due for future amendment, see
+	 * {@link GhidraScriptUtil#fixupName(String)}.
 	 * 
 	 * @param scriptName the name of the script, must end with this provider's extension
 	 * @return a (relative) file path to the corresponding script
@@ -172,6 +194,7 @@ public abstract class GhidraScriptProvider
 
 	/**
 	 * Return the start of certification header line if this file type is subject to certification.
+	 * 
 	 * @return start of certification header or null if not supported
 	 */
 	protected String getCertifyHeaderStart() {
@@ -181,6 +204,7 @@ public abstract class GhidraScriptProvider
 	/**
 	 * Return the prefix for each certification header body line if this file is subject to
 	 * certification.
+	 * 
 	 * @return certification header body prefix or null if not supported
 	 */
 	protected String getCertificationBodyPrefix() {
@@ -189,6 +213,7 @@ public abstract class GhidraScriptProvider
 
 	/**
 	 * Return the end of certification header line if this file type is subject to certification.
+	 * 
 	 * @return end of certification header or null if not supported
 	 */
 	protected String getCertifyHeaderEnd() {

Ghidra/Features/Base/src/main/java/ghidra/app/script/JavaScriptProvider.java

@@ -16,6 +16,7 @@
 package ghidra.app.script;
 
 import java.io.*;
+import java.lang.reflect.InvocationTargetException;
 import java.util.Collections;
 import java.util.regex.Pattern;
 
@@ -26,6 +27,9 @@ import ghidra.app.plugin.core.osgi.*;
 import ghidra.util.Msg;
 import ghidra.util.task.TaskMonitor;
 
+/**
+ * The provider for Ghidra Scripts written in Java
+ */
 public class JavaScriptProvider extends GhidraScriptProvider {
 	private static final Pattern BLOCK_COMMENT_START = Pattern.compile("/\\*");
 	private static final Pattern BLOCK_COMMENT_END = Pattern.compile("\\*/");
@@ -33,14 +37,16 @@ public class JavaScriptProvider extends GhidraScriptProvider {
 	private final BundleHost bundleHost;
 
 	/**
-	 * Create a new {@link JavaScriptProvider} associated with the current bundle host used by scripting.
+	 * Create a new {@link JavaScriptProvider} associated with the current bundle host used by
+	 * scripting.
 	 */
 	public JavaScriptProvider() {
 		bundleHost = GhidraScriptUtil.getBundleHost();
 	}
 
 	/**
-	 * Get the {@link GhidraSourceBundle} containing the given source file, assuming it already exists.
+	 * Get the {@link GhidraSourceBundle} containing the given source file, assuming it already
+	 * exists.
 	 * 
 	 * @param sourceFile the source file
 	 * @return the bundle
@@ -80,35 +86,53 @@ public class JavaScriptProvider extends GhidraScriptProvider {
 
 	@Override
 	public GhidraScript getScriptInstance(ResourceFile sourceFile, PrintWriter writer)
-			throws ClassNotFoundException, InstantiationException, IllegalAccessException {
+			throws GhidraScriptLoadException {
 		try {
 			Class<?> clazz = loadClass(sourceFile, writer);
-			Object object;
-			object = clazz.getDeclaredConstructor().newInstance();
 
-			if (object instanceof GhidraScript) {
+			if (GhidraScript.class.isAssignableFrom(clazz)) {
-				GhidraScript script = (GhidraScript) object;
+				GhidraScript script = (GhidraScript) clazz.getDeclaredConstructor().newInstance();
 				script.setSourceFile(sourceFile);
 				return script;
 			}
 
-			String message = "Not a valid Ghidra script: " + sourceFile.getName();
+			throw new GhidraScriptLoadException(
-			writer.println(message);
+				"Ghidra scripts in Java must extend " + GhidraScript.class.getName() + ". " +
-			Msg.error(this, message);
+					sourceFile.getName() + " does not.");
-			return null; // class is not GhidraScript
-
 		}
-		catch (ClassNotFoundException | InstantiationException | IllegalAccessException e) {
+		catch (ClassNotFoundException e) {
-			throw e;
+			throw new GhidraScriptLoadException("The class could not be found. " +
+				"It must be the public class of the .java file: " + e.getMessage(), e);
+		}
+		catch (NoClassDefFoundError e) {
+			throw new GhidraScriptLoadException("The class could not be found or loaded, " +
+				"perhaps due to a previous initialization error: " + e.getMessage(), e);
+		}
+		catch (ExceptionInInitializerError e) {
+			throw new GhidraScriptLoadException(
+				"Error during class initialization: " + e.getException(), e.getException());
+		}
+		catch (InvocationTargetException e) {
+			throw new GhidraScriptLoadException(
+				"Error during class construction: " + e.getTargetException(),
+				e.getTargetException());
+		}
+		catch (NoSuchMethodException e) {
+			throw new GhidraScriptLoadException(
+				"The default constructor does not exist: " + e.getMessage(), e);
+		}
+		catch (IllegalAccessException e) {
+			throw new GhidraScriptLoadException(
+				"The class or its default constructor is not accessible: " + e.getMessage(), e);
 		}
 		catch (Exception e) {
-			throw new ClassNotFoundException("", e);
+			throw new GhidraScriptLoadException("Unexpected error: " + e);
 		}
 	}
 
 	/**
-	 * Activate and build the {@link GhidraSourceBundle} containing {@code sourceFile} 
+	 * Activate and build the {@link GhidraSourceBundle} containing {@code sourceFile} then load the
-	 * then load the script's class from its class loader. 
+	 * script's class from its class loader.
 	 * 
 	 * @param sourceFile the source file
 	 * @param writer the target for build messages
@@ -164,9 +188,10 @@ public class JavaScriptProvider extends GhidraScriptProvider {
 	}
 
 	/**
-	 * Returns a Pattern that matches block comment openings.
+	 * {@inheritDoc}
+	 * 
+	 * <p>
 	 * For Java this is "/*".
-	 * @return the Pattern for Java block comment openings
 	 */
 	@Override
 	public Pattern getBlockCommentStart() {
@@ -174,9 +199,10 @@ public class JavaScriptProvider extends GhidraScriptProvider {
 	}
 
 	/**
-	 * Returns a Pattern that matches block comment closings.
+	 * {@inheritDoc}
+	 * 
+	 * <p>
 	 * In Java this is an asterisk followed by a forward slash.
-	 * @return the Pattern for Java block comment closings
 	 */
 	@Override
 	public Pattern getBlockCommentEnd() {
@@ -204,14 +230,19 @@ public class JavaScriptProvider extends GhidraScriptProvider {
 	}
 
 	/**
+	 * {@inheritDoc}
 	 * 
-	 * Fix script name for search in script directories, such as Java package parts in the name and inner class names.
+	 * <p>
+	 * Fix script name for search in script directories, such as Java package parts in the name and
+	 * inner class names.
 	 *
-	 * <p>This method can handle names with '$' (inner classes) and names with '.' 
+	 * <p>
-	 * characters for package separators
+	 * This method can handle names with '$' (inner classes) and names with '.' characters for
+	 * package separators
 	 *
-	 * <p>It is part of a poorly specified behavior that is due for future amendment, 
+	 * <p>
-	 * see {@link GhidraScriptUtil#fixupName(String)}.
+	 * It is part of a poorly specified behavior that is due for future amendment, see
+	 * {@link GhidraScriptUtil#fixupName(String)}.
 	 *
 	 * @param scriptName the name of the script
 	 * @return the name as a '.java' file path (with '/'s and not '.'s)
@@ -227,5 +258,4 @@ public class JavaScriptProvider extends GhidraScriptProvider {
 		}
 		return path + ".java";
 	}
-
 }

Ghidra/Features/Base/src/main/java/ghidra/test/TestEnv.java

@@ -35,8 +35,7 @@ import ghidra.app.events.OpenProgramPluginEvent;
 import ghidra.app.plugin.core.analysis.AutoAnalysisManager;
 import ghidra.app.plugin.core.progmgr.ProgramManagerPlugin;
 import ghidra.app.plugin.core.script.GhidraScriptMgrPlugin;
-import ghidra.app.script.GhidraScript;
+import ghidra.app.script.*;
-import ghidra.app.script.JavaScriptProvider;
 import ghidra.app.services.ProgramManager;
 import ghidra.base.project.GhidraProject;
 import ghidra.framework.Application;
@@ -564,7 +563,7 @@ public class TestEnv {
 		try {
 			script = scriptProvider.getScriptInstance(resourceFile, writer);
 		}
-		catch (ClassNotFoundException | InstantiationException | IllegalAccessException e) {
+		catch (GhidraScriptLoadException e) {
 			Msg.error(TestEnv.class, "Problem creating script", e);
 
 		}

Ghidra/Features/Python/src/main/java/ghidra/python/PythonScriptProvider.java

@@ -19,8 +19,7 @@ import java.io.*;
 import java.util.regex.Pattern;
 
 import generic.jar.ResourceFile;
-import ghidra.app.script.GhidraScript;
+import ghidra.app.script.*;
-import ghidra.app.script.GhidraScriptProvider;
 
 public class PythonScriptProvider extends GhidraScriptProvider {
 
@@ -37,8 +36,11 @@ public class PythonScriptProvider extends GhidraScriptProvider {
 	}
 
 	/**
-	 * Returns a Pattern that matches block comment openings.
+	 * {@inheritDoc}
+	 * 
+	 * <p>
 	 * In Python this is a triple single quote sequence, "'''".
+	 * 
 	 * @return the Pattern for Python block comment openings
 	 */
 	@Override
@@ -47,8 +49,11 @@ public class PythonScriptProvider extends GhidraScriptProvider {
 	}
 
 	/**
-	 * Returns a Pattern that matches block comment closings.
+	 * {@inheritDoc}
+	 * 
+	 * <p>
 	 * In Python this is a triple single quote sequence, "'''".
+	 * 
 	 * @return the Pattern for Python block comment openings
 	 */
 	@Override
@@ -88,11 +93,16 @@ public class PythonScriptProvider extends GhidraScriptProvider {
 
 	@Override
 	public GhidraScript getScriptInstance(ResourceFile sourceFile, PrintWriter writer)
-			throws ClassNotFoundException, InstantiationException, IllegalAccessException {
+			throws GhidraScriptLoadException {
 
-		Class<?> clazz = Class.forName(PythonScript.class.getName());
+		try {
-		GhidraScript script = (GhidraScript) clazz.newInstance();
+			Class<?> clazz = Class.forName(PythonScript.class.getName());
-		script.setSourceFile(sourceFile);
+			GhidraScript script = (GhidraScript) clazz.getConstructor().newInstance();
-		return script;
+			script.setSourceFile(sourceFile);
+			return script;
+		}
+		catch (Exception e) {
+			throw new GhidraScriptLoadException(e);
+		}
 	}
 }