This is an automated email from the ASF dual-hosted git repository. asf-gitbox-commits pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/groovy.git
commit 8d0eaa9f3d17973cae8eb24fe0163c557e4906c8 Author: Daniel Sun <[email protected]> AuthorDate: Sun May 10 02:07:05 2026 +0900 Add missing javadoc --- .../java/org/codehaus/groovy/tools/Compiler.java | 7 +- .../org/codehaus/groovy/tools/DgmConverter.java | 18 +++++ .../org/codehaus/groovy/tools/ErrorReporter.java | 6 ++ .../codehaus/groovy/tools/FileSystemCompiler.java | 91 ++++++++++++++++++++++ .../java/org/codehaus/groovy/tools/GrapeUtil.java | 11 +++ .../org/codehaus/groovy/tools/GroovyClass.java | 23 +++++- .../org/codehaus/groovy/tools/GroovyStarter.java | 10 +++ .../org/codehaus/groovy/tools/StringHelper.java | 3 + .../groovy/tools/gse/DependencyTracker.java | 84 ++++++++++++++++++++ .../codehaus/groovy/tools/gse/StringSetMap.java | 20 +++++ .../tools/javac/JavaAwareCompilationUnit.java | 56 +++++++++++++ .../tools/javac/JavaAwareResolveVisitor.java | 28 +++++++ .../codehaus/groovy/tools/javac/JavaCompiler.java | 11 +++ .../groovy/tools/javac/JavaCompilerFactory.java | 9 +++ .../tools/javac/JavaStubCompilationUnit.java | 45 +++++++++++ .../groovy/tools/javac/JavaStubGenerator.java | 34 ++++++++ .../groovy/tools/javac/JavacCompilerFactory.java | 9 +++ .../groovy/tools/javac/JavacJavaCompiler.java | 16 ++++ .../groovy/tools/javac/MemJavaFileObject.java | 23 ++++++ .../groovy/tools/javac/RawJavaFileObject.java | 25 ++++++ .../java/org/codehaus/groovy/tools/shell/IO.java | 35 +++++++++ .../codehaus/groovy/tools/shell/util/Logger.java | 62 +++++++++++++++ .../groovy/tools/shell/util/MessageSource.java | 22 ++++++ .../groovy/tools/shell/util/Preferences.java | 85 ++++++++++++++++++++ 24 files changed, 728 insertions(+), 5 deletions(-) diff --git a/src/main/java/org/codehaus/groovy/tools/Compiler.java b/src/main/java/org/codehaus/groovy/tools/Compiler.java index 6c887e5bcd..d2b7ed3697 100644 --- a/src/main/java/org/codehaus/groovy/tools/Compiler.java +++ b/src/main/java/org/codehaus/groovy/tools/Compiler.java @@ -31,6 +31,9 @@ import java.io.File; */ public class Compiler { // TODO: delete this constant? + /** + * Shared compiler instance using the default configuration. + */ public static final Compiler DEFAULT = new Compiler(); private final CompilerConfiguration configuration; // Optional configuration data @@ -91,7 +94,3 @@ public class Compiler { } } - - - - diff --git a/src/main/java/org/codehaus/groovy/tools/DgmConverter.java b/src/main/java/org/codehaus/groovy/tools/DgmConverter.java index 04e74e7c39..59639388ee 100644 --- a/src/main/java/org/codehaus/groovy/tools/DgmConverter.java +++ b/src/main/java/org/codehaus/groovy/tools/DgmConverter.java @@ -57,10 +57,20 @@ import static org.objectweb.asm.Opcodes.INVOKEVIRTUAL; import static org.objectweb.asm.Opcodes.IRETURN; import static org.objectweb.asm.Opcodes.RETURN; +/** + * Generates {@code GeneratedMetaMethod} adapter classes and metadata for the + * default Groovy methods. + */ public class DgmConverter { private static final System.Logger LOGGER = System.getLogger(DgmConverter.class.getName()); + /** + * Generates DGM adapter classes into the target directory. + * + * @param args optional {@code --info} flag and target directory + * @throws IOException if generated classes or metadata cannot be written + */ public static void main(String[] args) throws IOException { String targetDirectory = "build/classes/"; boolean info = (args.length == 1 && "--info".equals(args[0])) @@ -239,6 +249,14 @@ public class DgmConverter { mv.visitEnd(); } + /** + * Loads and casts the non-receiver arguments for the supplied cached + * method from an {@code Object[]} local variable. + * + * @param method the cached method whose parameters are being loaded + * @param argumentIndex the local-variable slot containing the argument array + * @param mv the visitor receiving the bytecode instructions + */ protected static void loadParameters(CachedMethod method, int argumentIndex, MethodVisitor mv) { CachedClass[] parameters = method.getParameterTypes(); int size = parameters.length - 1; diff --git a/src/main/java/org/codehaus/groovy/tools/ErrorReporter.java b/src/main/java/org/codehaus/groovy/tools/ErrorReporter.java index 7aac8bcd73..ca83af0705 100644 --- a/src/main/java/org/codehaus/groovy/tools/ErrorReporter.java +++ b/src/main/java/org/codehaus/groovy/tools/ErrorReporter.java @@ -155,6 +155,12 @@ public class ErrorReporter { } } + /** + * Prints a line to the underlying output target using a mutable character + * buffer. + * + * @param line the line to print + */ protected void println(StringBuffer line) { if (output instanceof PrintStream) { ((PrintStream) output).println(line); diff --git a/src/main/java/org/codehaus/groovy/tools/FileSystemCompiler.java b/src/main/java/org/codehaus/groovy/tools/FileSystemCompiler.java index f8fc8e13e4..a7bdbcbd4c 100644 --- a/src/main/java/org/codehaus/groovy/tools/FileSystemCompiler.java +++ b/src/main/java/org/codehaus/groovy/tools/FileSystemCompiler.java @@ -61,10 +61,25 @@ public class FileSystemCompiler { private static boolean displayStackTraceOnError = false; private final CompilationUnit unit; + /** + * Creates a file-system compiler using the supplied configuration. + * + * @param configuration the compiler configuration to apply + * @throws ConfigurationException if the compilation unit cannot be created + */ public FileSystemCompiler(CompilerConfiguration configuration) throws ConfigurationException { this(configuration, null); } + /** + * Creates a file-system compiler using the supplied configuration and + * optional prebuilt compilation unit. + * + * @param configuration the compiler configuration to apply + * @param cu an existing compilation unit to reuse, or {@code null} to build + * a suitable one + * @throws ConfigurationException if the compilation unit cannot be created + */ public FileSystemCompiler(CompilerConfiguration configuration, CompilationUnit cu) throws ConfigurationException { if (cu != null) { unit = cu; @@ -114,6 +129,12 @@ public class FileSystemCompiler { } } + /** + * Counts unreadable or missing source files in the supplied list. + * + * @param filenames the file names to validate + * @return the number of invalid file entries + */ public static int checkFiles(String[] filenames) { int errors = 0; @@ -131,6 +152,12 @@ public class FileSystemCompiler { return errors; } + /** + * Returns whether all supplied file names resolve to readable files. + * + * @param filenames the file names to validate + * @return {@code true} if every file exists and can be read + */ public static boolean validateFiles(String[] filenames) { return checkFiles(filenames) == 0; } @@ -172,6 +199,12 @@ public class FileSystemCompiler { } } + /** + * Creates and configures the command-line parser for compilation options. + * + * @param options the options object to bind parser results to + * @return the configured parser + */ public static CommandLine configureParser(CompilationOptions options) { CommandLine parser = new CommandLine(options); parser.getCommandSpec().parser() @@ -215,10 +248,30 @@ public class FileSystemCompiler { } } + /** + * Compiles the supplied source files using the given configuration. + * + * @param configuration the compiler configuration to use + * @param unit an existing compilation unit to reuse, or {@code null} + * @param filenames the source files to compile + * @throws Exception if compilation fails + */ public static void doCompilation(CompilerConfiguration configuration, CompilationUnit unit, String[] filenames) throws Exception { doCompilation(configuration, unit, filenames, true); } + /** + * Compiles the supplied source files using the given configuration and + * controls whether unnamed Groovy sources are searched relative to the + * provided file list. + * + * @param configuration the compiler configuration to use + * @param unit an existing compilation unit to reuse, or {@code null} + * @param filenames the source files to compile + * @param lookupUnnamedFiles whether to search for unnamed Groovy sources + * beside the listed files + * @throws Exception if compilation fails + */ public static void doCompilation(CompilerConfiguration configuration, CompilationUnit unit, String[] filenames, boolean lookupUnnamedFiles) throws Exception { File tmpDir = null; // if there are any joint compilation options set stubDir if not set @@ -297,6 +350,11 @@ public class FileSystemCompiler { } } + /** + * Deletes the supplied file or directory tree if it exists. + * + * @param file the file or directory to delete + */ public static void deleteRecursive(File file) { if (!file.exists()) { return; @@ -312,20 +370,39 @@ public class FileSystemCompiler { } } + /** + * Compiles the sources at the supplied paths. + * + * @param paths the source paths to compile + * @throws Exception if compilation fails + */ public void compile(String[] paths) throws Exception { unit.addSources(paths); unit.compile(); } + /** + * Compiles the supplied source files. + * + * @param files the source files to compile + * @throws Exception if compilation fails + */ public void compile(File[] files) throws Exception { unit.addSources(files); unit.compile(); } /** + * Supplies version text for the {@code groovyc} command line. + * * @since 2.5 */ public static class VersionProvider implements IVersionProvider { + /** + * Returns the version banner displayed by the command line parser. + * + * @return the version banner lines + */ @Override public String[] getVersion() { return new String[]{ @@ -337,6 +414,8 @@ public class FileSystemCompiler { } /** + * Command-line options accepted by the {@code groovyc} launcher. + * * @since 2.5 */ @Command(name = "groovyc", @@ -418,6 +497,12 @@ public class FileSystemCompiler { @Option(names = {"--type-checked"}, description = "Use TypeChecked") private boolean typeChecked; + /** + * Builds a compiler configuration from the parsed command-line options. + * + * @return the configured compiler configuration + * @throws IOException if a configuration script cannot be read + */ public CompilerConfiguration toCompilerConfiguration() throws IOException { // Setup the configuration data CompilerConfiguration configuration = new CompilerConfiguration(); @@ -496,6 +581,12 @@ public class FileSystemCompiler { return configuration; } + /** + * Expands the parsed source-file arguments, including {@code @}-files, + * into the list of file names to compile. + * + * @return the source file names, or {@code null} if expansion failed + */ public String[] generateFileNames() { return generateFileNamesFromOptions(files); } diff --git a/src/main/java/org/codehaus/groovy/tools/GrapeUtil.java b/src/main/java/org/codehaus/groovy/tools/GrapeUtil.java index c6e002ff88..7a0ed4f793 100644 --- a/src/main/java/org/codehaus/groovy/tools/GrapeUtil.java +++ b/src/main/java/org/codehaus/groovy/tools/GrapeUtil.java @@ -21,7 +21,18 @@ package org.codehaus.groovy.tools; import java.util.LinkedHashMap; import java.util.Map; +/** + * Utility methods for parsing compact Grape dependency coordinates. + */ public class GrapeUtil { + /** + * Parses a dependency coordinate in Ivy/Grape shorthand form into its + * component parts. + * + * @param allstr the dependency coordinate to parse + * @return a map containing any parsed {@code group}, {@code module}, + * {@code version}, {@code classifier}, and {@code ext} entries + */ public static Map<String, Object> getIvyParts(String allstr) { Map<String, Object> result = new LinkedHashMap<String, Object>(); String ext = ""; diff --git a/src/main/java/org/codehaus/groovy/tools/GroovyClass.java b/src/main/java/org/codehaus/groovy/tools/GroovyClass.java index 4dd12dd93c..b2dbf70424 100644 --- a/src/main/java/org/codehaus/groovy/tools/GroovyClass.java +++ b/src/main/java/org/codehaus/groovy/tools/GroovyClass.java @@ -18,23 +18,44 @@ */ package org.codehaus.groovy.tools; +/** + * Holds the binary form of a compiled Groovy class. + */ public class GroovyClass { + /** + * Shared empty array instance. + */ public static final GroovyClass[] EMPTY_ARRAY = {}; private final String name; private final byte[] bytes; + /** + * Creates a compiled-class holder. + * + * @param name the binary class name + * @param bytes the compiled class bytes + */ public GroovyClass(String name, byte[] bytes) { this.name = name; this.bytes = bytes; } + /** + * Returns the binary class name. + * + * @return the class name + */ public String getName() { return this.name; } + /** + * Returns the compiled class bytes. + * + * @return the class bytes + */ public byte[] getBytes() { return this.bytes; } } - diff --git a/src/main/java/org/codehaus/groovy/tools/GroovyStarter.java b/src/main/java/org/codehaus/groovy/tools/GroovyStarter.java index 4e0f94856a..c86c8d10fe 100644 --- a/src/main/java/org/codehaus/groovy/tools/GroovyStarter.java +++ b/src/main/java/org/codehaus/groovy/tools/GroovyStarter.java @@ -42,6 +42,11 @@ public class GroovyStarter { System.exit(1); } + /** + * Bootstraps the requested Groovy launcher from command-line arguments. + * + * @param args launcher arguments + */ public static void main(String[] args) { try { rootLoader(args); @@ -50,6 +55,11 @@ public class GroovyStarter { } } + /** + * Configures the root loader and invokes the selected main class. + * + * @param args starter arguments + */ public static void rootLoader(String[] args) { String conf = System.getProperty("groovy.starter.conf",null); final LoaderConfiguration lc = new LoaderConfiguration(); diff --git a/src/main/java/org/codehaus/groovy/tools/StringHelper.java b/src/main/java/org/codehaus/groovy/tools/StringHelper.java index d5cfc9be16..7145f4622c 100644 --- a/src/main/java/org/codehaus/groovy/tools/StringHelper.java +++ b/src/main/java/org/codehaus/groovy/tools/StringHelper.java @@ -21,6 +21,9 @@ package org.codehaus.groovy.tools; import java.util.LinkedList; import java.util.List; +/** + * String utility methods used by Groovy command-line tooling. + */ public class StringHelper { private static final char SPACE = ' ', SINGLE_QUOTE = '\'', DOUBLE_QUOTE = '"'; diff --git a/src/main/java/org/codehaus/groovy/tools/gse/DependencyTracker.java b/src/main/java/org/codehaus/groovy/tools/gse/DependencyTracker.java index daaac1cdfd..d93599b24d 100644 --- a/src/main/java/org/codehaus/groovy/tools/gse/DependencyTracker.java +++ b/src/main/java/org/codehaus/groovy/tools/gse/DependencyTracker.java @@ -37,16 +37,35 @@ import java.util.HashMap; import java.util.Map; import java.util.Set; +/** + * Tracks type dependencies referenced from a source unit and stores them in a + * {@link StringSetMap}. + */ public class DependencyTracker extends ClassCodeVisitorSupport { private Set<String> current; private final Map<String, ?> precompiledDependencies; private final SourceUnit source; private final StringSetMap cache; + /** + * Creates a dependency tracker for a source unit. + * + * @param source the source unit being analyzed + * @param cache the dependency cache to populate + */ public DependencyTracker(SourceUnit source, StringSetMap cache) { this(source, cache, new HashMap()); } + /** + * Creates a dependency tracker for a source unit with an explicit set of + * precompiled dependency entries. + * + * @param source the source unit being analyzed + * @param cache the dependency cache to populate + * @param precompiledEntries precompiled classes considered valid + * dependencies + */ public DependencyTracker(SourceUnit source, StringSetMap cache, Map<String, ?> precompiledEntries) { this.source = source; this.cache = cache; @@ -71,6 +90,11 @@ public class DependencyTracker extends ClassCodeVisitorSupport { for (ClassNode node : nodes) addToCache(node); } + /** + * Visits a class and records its direct type dependencies. + * + * @param node the class being visited + */ @Override public void visitClass(ClassNode node) { Set<String> old = current; @@ -79,20 +103,44 @@ public class DependencyTracker extends ClassCodeVisitorSupport { super.visitClass(node); current = old; } + + /** + * Returns the source unit whose dependencies are being tracked. + * + * @return the current source unit + */ @Override protected SourceUnit getSourceUnit() { return source; } + + /** + * Records the type referenced by a class literal expression. + * + * @param expression the class expression being visited + */ @Override public void visitClassExpression(ClassExpression expression) { super.visitClassExpression(expression); addToCache(expression.getType()); } + + /** + * Records the declared type of a visited field. + * + * @param node the field being visited + */ @Override public void visitField(FieldNode node) { super.visitField(node); addToCache(node.getType()); } + + /** + * Records parameter, return, and exception types referenced by a method. + * + * @param node the method being visited + */ @Override public void visitMethod(MethodNode node) { for (Parameter p : node.getParameters()) { @@ -102,26 +150,56 @@ public class DependencyTracker extends ClassCodeVisitorSupport { addToCache(node.getExceptions()); super.visitMethod(node); } + + /** + * Records the array type referenced by an array expression. + * + * @param expression the array expression being visited + */ @Override public void visitArrayExpression(ArrayExpression expression) { super.visitArrayExpression(expression); addToCache(expression.getType()); } + + /** + * Records the target type referenced by a cast expression. + * + * @param expression the cast expression being visited + */ @Override public void visitCastExpression(CastExpression expression) { super.visitCastExpression(expression); addToCache(expression.getType()); } + + /** + * Records the type referenced by a variable expression. + * + * @param expression the variable expression being visited + */ @Override public void visitVariableExpression(VariableExpression expression) { super.visitVariableExpression(expression); addToCache(expression.getType()); } + + /** + * Records the exception-variable type referenced by a catch statement. + * + * @param statement the catch statement being visited + */ @Override public void visitCatchStatement(CatchStatement statement) { super.visitCatchStatement(statement); addToCache(statement.getVariable().getType()); } + + /** + * Records the types of annotations attached to the supplied node. + * + * @param node the annotated node being visited + */ @Override public void visitAnnotations(AnnotatedNode node) { super.visitAnnotations(node); @@ -129,6 +207,12 @@ public class DependencyTracker extends ClassCodeVisitorSupport { addToCache(an.getClassNode()); } } + + /** + * Records the constructed type referenced by a constructor call. + * + * @param call the constructor call expression being visited + */ @Override public void visitConstructorCallExpression(ConstructorCallExpression call) { super.visitConstructorCallExpression(call); diff --git a/src/main/java/org/codehaus/groovy/tools/gse/StringSetMap.java b/src/main/java/org/codehaus/groovy/tools/gse/StringSetMap.java index 1da9716a9f..ca695a672d 100644 --- a/src/main/java/org/codehaus/groovy/tools/gse/StringSetMap.java +++ b/src/main/java/org/codehaus/groovy/tools/gse/StringSetMap.java @@ -24,20 +24,37 @@ import java.util.LinkedHashSet; import java.util.Set; import java.util.TreeSet; +/** + * Map from string keys to lazily created sets of strings. + */ public class StringSetMap extends LinkedHashMap<String,Set<String>> { @Serial private static final long serialVersionUID = -8603734698633884431L; + /** + * Creates an empty map. + */ public StringSetMap() { super(); } + /** + * Creates a copy of another string-set map. + * + * @param other the map to copy + */ public StringSetMap(StringSetMap other) { for (String key : other.keySet()) { get(key).addAll(other.get(key)); } } + /** + * Returns the set for the supplied key, creating it if necessary. + * + * @param o the key whose set should be returned + * @return the existing or newly created set + */ @Override public Set<String> get(Object o){ String name = (String) o; @@ -49,6 +66,9 @@ public class StringSetMap extends LinkedHashMap<String,Set<String>> { return set; } + /** + * Expands the relation represented by this map to its transitive closure. + */ public void makeTransitiveHull() { Set<String> nameSet = new TreeSet<String>(keySet()); diff --git a/src/main/java/org/codehaus/groovy/tools/javac/JavaAwareCompilationUnit.java b/src/main/java/org/codehaus/groovy/tools/javac/JavaAwareCompilationUnit.java index f9d7e9046a..e615654919 100644 --- a/src/main/java/org/codehaus/groovy/tools/javac/JavaAwareCompilationUnit.java +++ b/src/main/java/org/codehaus/groovy/tools/javac/JavaAwareCompilationUnit.java @@ -56,18 +56,41 @@ public class JavaAwareCompilationUnit extends CompilationUnit { private final boolean keepStubs; private final boolean memStubEnabled; + /** + * Creates a joint compilation unit with the default configuration. + */ public JavaAwareCompilationUnit() { this(null, null, null); } + /** + * Creates a joint compilation unit with the supplied configuration. + * + * @param configuration the compiler configuration to use + */ public JavaAwareCompilationUnit(final CompilerConfiguration configuration) { this(configuration, null, null); } + /** + * Creates a joint compilation unit with the supplied configuration and + * class loader. + * + * @param configuration the compiler configuration to use + * @param groovyClassLoader the Groovy class loader to use + */ public JavaAwareCompilationUnit(final CompilerConfiguration configuration, final GroovyClassLoader groovyClassLoader) { this(configuration, groovyClassLoader, null); } + /** + * Creates a joint compilation unit with explicit Groovy and transform class + * loaders. + * + * @param configuration the compiler configuration to use + * @param groovyClassLoader the Groovy class loader to use + * @param transformClassLoader the class loader used for AST transforms + */ public JavaAwareCompilationUnit(final CompilerConfiguration configuration, final GroovyClassLoader groovyClassLoader, final GroovyClassLoader transformClassLoader) { super(configuration, /*codeSource*/null, groovyClassLoader, transformClassLoader); @@ -129,6 +152,13 @@ public class JavaAwareCompilationUnit extends CompilationUnit { }, Phases.CONVERSION); } + /** + * Advances the compilation unit to the requested phase and triggers javac + * when the semantic analysis boundary is reached. + * + * @param phase the target compilation phase + * @throws CompilationFailedException if compilation fails + */ @Override public void gotoPhase(final int phase) throws CompilationFailedException { super.gotoPhase(phase); @@ -148,6 +178,12 @@ public class JavaAwareCompilationUnit extends CompilationUnit { } } + /** + * Configures the compilation unit and ensures the target directory is on + * the Groovy class loader classpath. + * + * @param configuration the compiler configuration to apply + */ @Override public void configure(final CompilerConfiguration configuration) { super.configure(configuration); @@ -171,6 +207,11 @@ public class JavaAwareCompilationUnit extends CompilationUnit { javaSources.add(file.getAbsolutePath()); } + /** + * Adds Groovy or Java sources from the supplied path strings. + * + * @param paths the source paths to add + */ @Override public void addSources(final String[] paths) { for (String path : paths) { @@ -178,6 +219,11 @@ public class JavaAwareCompilationUnit extends CompilationUnit { } } + /** + * Adds Groovy or Java sources from the supplied files. + * + * @param files the source files to add + */ @Override public void addSources(final File[] files) { for (File file : files) { @@ -185,10 +231,20 @@ public class JavaAwareCompilationUnit extends CompilationUnit { } } + /** + * Returns the factory used to create the backing Java compiler. + * + * @return the Java compiler factory + */ public JavaCompilerFactory getCompilerFactory() { return compilerFactory; } + /** + * Sets the factory used to create the backing Java compiler. + * + * @param compilerFactory the Java compiler factory to use + */ public void setCompilerFactory(final JavaCompilerFactory compilerFactory) { this.compilerFactory = compilerFactory; } diff --git a/src/main/java/org/codehaus/groovy/tools/javac/JavaAwareResolveVisitor.java b/src/main/java/org/codehaus/groovy/tools/javac/JavaAwareResolveVisitor.java index 729e3cbc93..2420388722 100644 --- a/src/main/java/org/codehaus/groovy/tools/javac/JavaAwareResolveVisitor.java +++ b/src/main/java/org/codehaus/groovy/tools/javac/JavaAwareResolveVisitor.java @@ -27,12 +27,27 @@ import org.codehaus.groovy.control.ResolveVisitor; import static org.apache.groovy.ast.tools.ConstructorNodeUtils.getFirstIfSpecialConstructorCall; +/** + * Resolve visitor variant used during joint compilation to revisit special + * constructor calls and track missing imports for Java sources. + */ public class JavaAwareResolveVisitor extends ResolveVisitor { + /** + * Creates a resolve visitor for the supplied compilation unit. + * + * @param cu the compilation unit being resolved + */ public JavaAwareResolveVisitor(final CompilationUnit cu) { super(cu); } + /** + * Resolves a constructor and then revisits any leading special constructor + * call expression. + * + * @param node the constructor being visited + */ @Override public void visitConstructor(final ConstructorNode node) { super.visitConstructor(node); @@ -42,11 +57,24 @@ public class JavaAwareResolveVisitor extends ResolveVisitor { cce.visit(this); } + /** + * Suppresses class-code-container traversal so normal resolution logic can + * handle the statements. + * + * @param stmt the statement container being considered + */ @Override protected void visitClassCodeContainer(final Statement stmt) { // do nothing here; leave it to the normal resolving } + /** + * Marks the source unit when a type resolution error indicates imports may + * need to be reconsidered. + * + * @param error the error message + * @param node the node that triggered the error + */ @Override public void addError(final String error, final ASTNode node) { if (error.startsWith("unable to resolve")) // GROOVY-11806 diff --git a/src/main/java/org/codehaus/groovy/tools/javac/JavaCompiler.java b/src/main/java/org/codehaus/groovy/tools/javac/JavaCompiler.java index 17fcf2f0fe..561bc90c31 100644 --- a/src/main/java/org/codehaus/groovy/tools/javac/JavaCompiler.java +++ b/src/main/java/org/codehaus/groovy/tools/javac/JavaCompiler.java @@ -22,6 +22,17 @@ import org.codehaus.groovy.control.CompilationUnit; import java.util.List; +/** + * Strategy interface for compiling Java sources during Groovy joint + * compilation. + */ public interface JavaCompiler { + /** + * Compiles the supplied Java source files into the context of the provided + * Groovy compilation unit. + * + * @param files the Java source files to compile + * @param cu the owning Groovy compilation unit + */ void compile(List<String> files, CompilationUnit cu); } diff --git a/src/main/java/org/codehaus/groovy/tools/javac/JavaCompilerFactory.java b/src/main/java/org/codehaus/groovy/tools/javac/JavaCompilerFactory.java index dd1c5ef88a..7a433d6e3d 100644 --- a/src/main/java/org/codehaus/groovy/tools/javac/JavaCompilerFactory.java +++ b/src/main/java/org/codehaus/groovy/tools/javac/JavaCompilerFactory.java @@ -20,6 +20,15 @@ package org.codehaus.groovy.tools.javac; import org.codehaus.groovy.control.CompilerConfiguration; +/** + * Factory for creating Java compiler instances used by joint compilation. + */ public interface JavaCompilerFactory { + /** + * Creates a Java compiler for the supplied configuration. + * + * @param config the compiler configuration + * @return a Java compiler instance + */ JavaCompiler createCompiler(CompilerConfiguration config); } diff --git a/src/main/java/org/codehaus/groovy/tools/javac/JavaStubCompilationUnit.java b/src/main/java/org/codehaus/groovy/tools/javac/JavaStubCompilationUnit.java index 34fe86a9c5..d89e21b685 100644 --- a/src/main/java/org/codehaus/groovy/tools/javac/JavaStubCompilationUnit.java +++ b/src/main/java/org/codehaus/groovy/tools/javac/JavaStubCompilationUnit.java @@ -42,6 +42,14 @@ public class JavaStubCompilationUnit extends CompilationUnit { private int stubCount; + /** + * Creates a compilation unit that generates Java stubs into the supplied + * destination directory. + * + * @param config the compiler configuration + * @param gcl the Groovy class loader to use + * @param destDir the destination directory for generated stubs + */ public JavaStubCompilationUnit(final CompilerConfiguration config, final GroovyClassLoader gcl, File destDir) { super(config, null, gcl); @@ -67,20 +75,43 @@ public class JavaStubCompilationUnit extends CompilationUnit { }, Phases.CONVERSION); } + /** + * Creates a compilation unit that generates Java stubs into the configured + * stub directory. + * + * @param config the compiler configuration + * @param gcl the Groovy class loader to use + */ public JavaStubCompilationUnit(final CompilerConfiguration config, final GroovyClassLoader gcl) { this(config, gcl, null); } + /** + * Returns the number of stubs generated during the last compilation run. + * + * @return the generated stub count + */ public int getStubCount() { return stubCount; } + /** + * Compiles sources through the conversion phase to generate stubs only. + * + * @throws CompilationFailedException if stub generation fails + */ @Override public void compile() throws CompilationFailedException { stubCount = 0; super.compile(Phases.CONVERSION); } + /** + * Configures the compilation unit and makes the target directory visible to + * the Groovy class loader. + * + * @param config the compiler configuration to apply + */ @Override public void configure(final CompilerConfiguration config) { super.configure(config); @@ -92,6 +123,13 @@ public class JavaStubCompilationUnit extends CompilationUnit { } } + /** + * Adds a source file when its extension is accepted for stub generation. + * + * @param file the source file to add + * @return the created source unit, or {@code null} if the extension is not + * accepted + */ @Override public SourceUnit addSource(final File file) { if (hasAcceptedFileExtension(file.getName())) { @@ -100,6 +138,13 @@ public class JavaStubCompilationUnit extends CompilationUnit { return null; } + /** + * Adds a source URL when its extension is accepted for stub generation. + * + * @param url the source URL to add + * @return the created source unit, or {@code null} if the extension is not + * accepted + */ @Override public SourceUnit addSource(URL url) { if (hasAcceptedFileExtension(url.getPath())) { diff --git a/src/main/java/org/codehaus/groovy/tools/javac/JavaStubGenerator.java b/src/main/java/org/codehaus/groovy/tools/javac/JavaStubGenerator.java index b3e89c8a41..2e930e5367 100644 --- a/src/main/java/org/codehaus/groovy/tools/javac/JavaStubGenerator.java +++ b/src/main/java/org/codehaus/groovy/tools/javac/JavaStubGenerator.java @@ -114,6 +114,9 @@ import static org.codehaus.groovy.ast.tools.GenericsUtils.createGenericsSpec; import static org.codehaus.groovy.ast.tools.WideningCategories.isFloatingCategory; import static org.codehaus.groovy.ast.tools.WideningCategories.isLongCategory; +/** + * Generates Java stub source for Groovy classes during joint compilation. + */ public class JavaStubGenerator { private final String encoding; @@ -125,10 +128,26 @@ public class JavaStubGenerator { private ModuleNode currentModule; + /** + * Creates a stub generator that writes to the supplied output directory + * using the default charset. + * + * @param outputPath the destination directory, or {@code null} for + * in-memory stubs + */ public JavaStubGenerator(final File outputPath) { this(outputPath, false, Charset.defaultCharset().name()); } + /** + * Creates a stub generator with explicit output options. + * + * @param outputPath the destination directory, or {@code null} for + * in-memory stubs + * @param requireSuperResolved whether generation should wait until the + * superclass is resolved + * @param encoding the source encoding to use for generated files + */ public JavaStubGenerator(final File outputPath, final boolean requireSuperResolved, final String encoding) { this.requireSuperResolved = requireSuperResolved; this.outputPath = outputPath; @@ -145,6 +164,13 @@ public class JavaStubGenerator { dir.mkdirs(); } + /** + * Generates a Java stub for the supplied class when it is eligible for + * stub generation. + * + * @param classNode the class to generate a stub for + * @throws FileNotFoundException if a file-based stub cannot be created + */ public void generateClass(final ClassNode classNode) throws FileNotFoundException { // only attempt to render if super-class is resolved; else wait for it if (requireSuperResolved && !classNode.getSuperClass().isResolved()) { @@ -1195,10 +1221,18 @@ public class JavaStubGenerator { private final Set<JavaFileObject> javaStubCompilationUnitSet = new HashSet<>(); + /** + * Returns the generated in-memory or file-backed Java file objects. + * + * @return the current set of generated Java stub compilation units + */ public Set<JavaFileObject> getJavaStubCompilationUnitSet() { return javaStubCompilationUnitSet; } + /** + * Deletes generated stub files and clears the tracked stub set. + */ public void clean() { Stream<JavaFileObject> javaFileObjectStream = javaStubCompilationUnitSet.size() < 2 diff --git a/src/main/java/org/codehaus/groovy/tools/javac/JavacCompilerFactory.java b/src/main/java/org/codehaus/groovy/tools/javac/JavacCompilerFactory.java index acb405647f..31a79abc65 100644 --- a/src/main/java/org/codehaus/groovy/tools/javac/JavacCompilerFactory.java +++ b/src/main/java/org/codehaus/groovy/tools/javac/JavacCompilerFactory.java @@ -20,7 +20,16 @@ package org.codehaus.groovy.tools.javac; import org.codehaus.groovy.control.CompilerConfiguration; +/** + * Factory creating the default {@link JavacJavaCompiler} implementation. + */ public class JavacCompilerFactory implements JavaCompilerFactory { + /** + * Creates a javac-backed compiler for the supplied configuration. + * + * @param config the compiler configuration + * @return a javac-backed compiler + */ @Override public JavaCompiler createCompiler(CompilerConfiguration config) { return new JavacJavaCompiler(config); diff --git a/src/main/java/org/codehaus/groovy/tools/javac/JavacJavaCompiler.java b/src/main/java/org/codehaus/groovy/tools/javac/JavacJavaCompiler.java index a104800d19..8cded088e2 100644 --- a/src/main/java/org/codehaus/groovy/tools/javac/JavacJavaCompiler.java +++ b/src/main/java/org/codehaus/groovy/tools/javac/JavacJavaCompiler.java @@ -43,16 +43,32 @@ import java.util.Set; import static java.lang.System.Logger.Level.INFO; +/** + * {@link JavaCompiler} implementation that delegates to the JDK system Java + * compiler. + */ public class JavacJavaCompiler implements JavaCompiler { private static final System.Logger LOGGER = System.getLogger(JavacJavaCompiler.class.getName()); private final CompilerConfiguration config; + /** + * Creates a javac-backed compiler for the supplied configuration. + * + * @param config the compiler configuration to use + */ public JavacJavaCompiler(final CompilerConfiguration config) { this.config = Objects.requireNonNull(config); } + /** + * Compiles the supplied Java source files with javac and reports any + * errors back to the Groovy compilation unit. + * + * @param files the Java source files to compile + * @param cu the owning Groovy compilation unit + */ @Override public void compile(final List<String> files, final CompilationUnit cu) { List<String> javacParameters = makeParameters(cu.getClassLoader()); diff --git a/src/main/java/org/codehaus/groovy/tools/javac/MemJavaFileObject.java b/src/main/java/org/codehaus/groovy/tools/javac/MemJavaFileObject.java index 8c96b99242..0d24e5d326 100644 --- a/src/main/java/org/codehaus/groovy/tools/javac/MemJavaFileObject.java +++ b/src/main/java/org/codehaus/groovy/tools/javac/MemJavaFileObject.java @@ -64,11 +64,24 @@ public class MemJavaFileObject extends SimpleJavaFileObject { } } + /** + * Returns the in-memory source content. + * + * @param ignoreEncodingErrors ignored because the content is already a + * character sequence + * @return the source content + */ @Override public CharSequence getCharContent(boolean ignoreEncodingErrors) { return src; } + /** + * Compares this file object by its class name. + * + * @param o the object to compare against + * @return {@code true} if the other object represents the same class name + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -76,11 +89,21 @@ public class MemJavaFileObject extends SimpleJavaFileObject { return Objects.equals(className, that.className); } + /** + * Returns the hash code derived from the class name. + * + * @return the hash code + */ @Override public int hashCode() { return Objects.hash(className); } + /** + * Returns a diagnostic string for this in-memory Java file object. + * + * @return a string representation of this file object + */ @Override public String toString() { return "MemJavaFileObject{" + diff --git a/src/main/java/org/codehaus/groovy/tools/javac/RawJavaFileObject.java b/src/main/java/org/codehaus/groovy/tools/javac/RawJavaFileObject.java index d3925f331e..d3de9cd23e 100644 --- a/src/main/java/org/codehaus/groovy/tools/javac/RawJavaFileObject.java +++ b/src/main/java/org/codehaus/groovy/tools/javac/RawJavaFileObject.java @@ -51,6 +51,15 @@ public class RawJavaFileObject extends SimpleJavaFileObject { this.javaFilePath = Paths.get(uri); } + /** + * Returns the source content of the underlying file, caching it after the + * first read. + * + * @param ignoreEncodingErrors ignored because the file is read using the + * configured default charset + * @return the source content + * @throws IOException if the file cannot be read + */ @Override public CharSequence getCharContent(boolean ignoreEncodingErrors) throws IOException { return null != src ? src : (src = Files.readString(javaFilePath, DEFAULT_CHARSET)); @@ -65,6 +74,12 @@ public class RawJavaFileObject extends SimpleJavaFileObject { return new File(uri).delete(); } + /** + * Compares this file object by URI. + * + * @param o the object to compare against + * @return {@code true} if the other object represents the same URI + */ @Override public boolean equals(Object o) { if (this == o) return true; @@ -72,11 +87,21 @@ public class RawJavaFileObject extends SimpleJavaFileObject { return Objects.equals(uri, that.uri); } + /** + * Returns the hash code derived from the URI. + * + * @return the hash code + */ @Override public int hashCode() { return Objects.hash(uri); } + /** + * Returns a diagnostic string for this file-backed Java file object. + * + * @return a string representation of this file object + */ @Override public String toString() { return "RawJavaFileObject{" + diff --git a/src/main/java/org/codehaus/groovy/tools/shell/IO.java b/src/main/java/org/codehaus/groovy/tools/shell/IO.java index b103c33442..513277e000 100644 --- a/src/main/java/org/codehaus/groovy/tools/shell/IO.java +++ b/src/main/java/org/codehaus/groovy/tools/shell/IO.java @@ -106,6 +106,13 @@ public class IO implements Closeable { this.err = err; } + /** + * Attempts to create an ANSI-aware writer for the supplied stream. + * + * @param stream the output stream to wrap + * @return an ANSI render writer, or {@code null} if ANSI support is + * unavailable + */ protected PrintWriter tryConstructRenderWriter(OutputStream stream) { // load via reflection to avoid hard-coded dependency on jansi jar try { @@ -191,25 +198,53 @@ public class IO implements Closeable { * Verbosity for simple logging: QUIET, INFO, VERBOSE, DEBUG */ public static final class Verbosity { + /** + * Minimal output. + */ public static final Verbosity QUIET = new Verbosity("QUIET"); + /** + * Normal informational output. + */ public static final Verbosity INFO = new Verbosity("INFO"); + /** + * Extra informational output. + */ public static final Verbosity VERBOSE = new Verbosity("VERBOSE"); + /** + * Debug-level output. + */ public static final Verbosity DEBUG = new Verbosity("DEBUG"); + /** + * The symbolic name of this verbosity level. + */ public final String name; private Verbosity(final String name) { this.name = name; } + /** + * Returns the symbolic name of this verbosity level. + * + * @return the verbosity name + */ @Override public String toString() { return name; } + /** + * Resolves a verbosity level by name. + * + * @param name the name to resolve + * @return the matching verbosity level + * @throws IllegalArgumentException if the name does not match a known + * level + */ public static Verbosity forName(final String name) { assert name != null; diff --git a/src/main/java/org/codehaus/groovy/tools/shell/util/Logger.java b/src/main/java/org/codehaus/groovy/tools/shell/util/Logger.java index 4bab8e4173..bd498c35fe 100644 --- a/src/main/java/org/codehaus/groovy/tools/shell/util/Logger.java +++ b/src/main/java/org/codehaus/groovy/tools/shell/util/Logger.java @@ -30,7 +30,13 @@ import static org.jline.jansi.Ansi.ansi; * Provides a very, very basic logging API. */ public final class Logger { + /** + * Shared shell I/O used to emit log messages. + */ public static volatile IO io; + /** + * Logger name shown in rendered log messages. + */ public final String name; private Logger(final String name) { @@ -89,20 +95,41 @@ public final class Logger { private static final String DEBUG = "DEBUG"; + /** + * Returns whether debug-level logging is currently enabled. + * + * @return {@code true} if debug messages should be emitted + */ public boolean isDebugEnabled() { return Preferences.verbosity == IO.Verbosity.DEBUG; } + /** + * Alias for {@link #isDebugEnabled()}. + * + * @return {@code true} if debug messages should be emitted + */ public boolean isDebug() { return isDebugEnabled(); } + /** + * Logs a debug message when debug output is enabled. + * + * @param msg the message to log + */ public void debug(final Object msg) { if (isDebugEnabled()) { log(DEBUG, msg, null); } } + /** + * Logs a debug message and cause when debug output is enabled. + * + * @param msg the message to log + * @param cause the associated cause + */ public void debug(final Object msg, final Throwable cause) { if (isDebugEnabled()) { log(DEBUG, msg, cause); @@ -111,20 +138,42 @@ public final class Logger { private static final String WARN = "WARN"; + /** + * Logs a warning message. + * + * @param msg the message to log + */ public void warn(final Object msg) { log(WARN, msg, null); } + /** + * Logs a warning message and cause. + * + * @param msg the message to log + * @param cause the associated cause + */ public void warn(final Object msg, final Throwable cause) { log(WARN, msg, cause); } private static final String ERROR = "ERROR"; + /** + * Logs an error message. + * + * @param msg the message to log + */ public void error(final Object msg) { log(ERROR, msg, null); } + /** + * Logs an error message and cause. + * + * @param msg the message to log + * @param cause the associated cause + */ public void error(final Object msg, final Throwable cause) { log(ERROR, msg, cause); } @@ -133,10 +182,23 @@ public final class Logger { // Factory access // + /** + * Creates a logger named after the supplied type. + * + * @param type the type whose name should be used + * @return a logger for the type + */ public static Logger create(final Class type) { return new Logger(type.getName()); } + /** + * Creates a logger named after the supplied type plus a suffix. + * + * @param type the base type whose name should be used + * @param suffix the suffix to append + * @return a logger for the type and suffix + */ public static Logger create(final Class type, final String suffix) { return new Logger(type.getName() + "." + suffix); } diff --git a/src/main/java/org/codehaus/groovy/tools/shell/util/MessageSource.java b/src/main/java/org/codehaus/groovy/tools/shell/util/MessageSource.java index 8fba88c9ad..3c87c88ae2 100644 --- a/src/main/java/org/codehaus/groovy/tools/shell/util/MessageSource.java +++ b/src/main/java/org/codehaus/groovy/tools/shell/util/MessageSource.java @@ -35,6 +35,11 @@ public class MessageSource private ResourceBundle[] cachedBundles; + /** + * Creates a message source backed by the named resource bundles. + * + * @param names the bundle base names to search + */ public MessageSource(final String[] names) { assert names != null; assert names.length != 0; @@ -42,6 +47,11 @@ public class MessageSource this.bundleNames = names; } + /** + * Creates a message source backed by a single named resource bundle. + * + * @param name the bundle base name + */ public MessageSource(final String name) { this(new String[] { name }); } @@ -61,10 +71,22 @@ public class MessageSource return names; } + /** + * Creates a message source backed by bundles named after the supplied + * types. + * + * @param types the types whose names identify resource bundles + */ public MessageSource(final Class[] types) { this(classNames(types)); } + /** + * Creates a message source backed by the bundle named after the supplied + * type. + * + * @param type the type whose name identifies a resource bundle + */ public MessageSource(final Class type) { this(new String[] { type.getName() }); } diff --git a/src/main/java/org/codehaus/groovy/tools/shell/util/Preferences.java b/src/main/java/org/codehaus/groovy/tools/shell/util/Preferences.java index 78a5c17afa..c120d52d6d 100644 --- a/src/main/java/org/codehaus/groovy/tools/shell/util/Preferences.java +++ b/src/main/java/org/codehaus/groovy/tools/shell/util/Preferences.java @@ -30,15 +30,39 @@ import java.util.prefs.PreferenceChangeListener; public class Preferences { private static final java.util.prefs.Preferences STORE = java.util.prefs.Preferences.userRoot().node("/org/codehaus/groovy/tools/shell"); + /** + * Current shell verbosity preference. + */ public static IO.Verbosity verbosity; + /** + * Preference key storing the selected verbosity level. + */ public static final String VERBOSITY_KEY = "verbosity"; + /** + * Preference key controlling whether the last result is shown. + */ public static final String SHOW_LAST_RESULT_KEY = "show-last-result"; + /** + * Preference key controlling stack-trace sanitization. + */ public static final String SANITIZE_STACK_TRACE_KEY = "sanitize-stack-trace"; + /** + * Preference key storing the preferred editor command. + */ public static final String EDITOR_KEY = "editor"; + /** + * Preference key storing the parser flavor. + */ public static final String PARSER_FLAVOR_KEY = "parser-flavor"; + /** + * Parser flavor value selecting rigid parsing. + */ public static final String PARSER_RIGID = "rigid"; + /** + * Parser flavor value selecting relaxed parsing. + */ public static final String PARSER_RELAXED = "relaxed"; @@ -53,6 +77,11 @@ public class Preferences { } addChangeListener(new PreferenceChangeListener() { + /** + * Updates cached verbosity when the stored preference changes. + * + * @param event the preference change event + */ @Override public void preferenceChange(final PreferenceChangeEvent event) { if (event.getKey().equals(VERBOSITY_KEY)) { @@ -73,18 +102,39 @@ public class Preferences { }); } + /** + * Returns whether the shell should display the last evaluation result. + * + * @return {@code true} if the last result should be shown + */ public static boolean getShowLastResult() { return STORE.getBoolean(SHOW_LAST_RESULT_KEY, true); } + /** + * Returns whether stack traces should be sanitized before display. + * + * @return {@code true} if stack traces should be sanitized + */ public static boolean getSanitizeStackTrace() { return STORE.getBoolean(SANITIZE_STACK_TRACE_KEY, true); } + /** + * Returns the configured editor command. + * + * @return the configured editor command, or the {@code EDITOR} + * environment variable if none is stored + */ public static String getEditor() { return STORE.get(EDITOR_KEY, System.getenv("EDITOR")); } + /** + * Returns the configured parser flavor. + * + * @return the parser flavor name + */ public static String getParserFlavor() { return STORE.get(PARSER_FLAVOR_KEY, PARSER_RIGID); } @@ -93,26 +143,61 @@ public class Preferences { // Store Access // + /** + * Returns all stored preference keys. + * + * @return the stored preference keys + * @throws BackingStoreException if the backing store cannot be queried + */ public static String[] keys() throws BackingStoreException { return STORE.keys(); } + /** + * Returns a preference value with a fallback. + * + * @param name the preference key + * @param defaultValue the fallback value to return when the key is absent + * @return the stored or fallback value + */ public static String get(final String name, final String defaultValue) { return STORE.get(name, defaultValue); } + /** + * Returns a preference value or {@code null} when absent. + * + * @param name the preference key + * @return the stored value, or {@code null} if absent + */ public static String get(final String name) { return get(name, null); } + /** + * Stores a preference value. + * + * @param name the preference key + * @param value the value to store + */ public static void put(final String name, final String value) { STORE.put(name, value); } + /** + * Clears all stored shell preferences. + * + * @throws BackingStoreException if the backing store cannot be updated + */ public static void clear() throws BackingStoreException { STORE.clear(); } + /** + * Registers a listener for preference changes. + * + * @param listener the listener to register + */ public static void addChangeListener(final PreferenceChangeListener listener) { STORE.addPreferenceChangeListener(listener); }
