You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by su...@apache.org on 2026/05/09 17:07:48 UTC
(groovy) branch master updated (2cc7c2d89a -> 36a6e6a4fd)
This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git
from 2cc7c2d89a Add missing package-info
new 8d0eaa9f3d Add missing javadoc
new 36a6e6a4fd Add missing package-info
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../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 ++++++
...{JavaCompilerFactory.java => package-info.java} | 11 ++-
.../groovy/tools}/package-info.java | 5 +-
.../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 ++++++++++++++++++++
26 files changed, 736 insertions(+), 13 deletions(-)
copy src/main/java/org/codehaus/groovy/tools/javac/{JavaCompilerFactory.java => package-info.java} (84%)
copy src/main/java/org/{apache/groovy/metaclass => codehaus/groovy/tools}/package-info.java (87%)
(groovy) 02/02: Add missing package-info
Posted by su...@apache.org.
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 36a6e6a4fda13d9b3e597d549611f93d16436ad4
Author: Daniel Sun <su...@apache.org>
AuthorDate: Sun May 10 02:07:31 2026 +0900
Add missing package-info
---
.../codehaus/groovy/tools/javac/package-info.java | 24 ++++++++++++++++++++++
.../org/codehaus/groovy/tools/package-info.java | 24 ++++++++++++++++++++++
2 files changed, 48 insertions(+)
diff --git a/src/main/java/org/codehaus/groovy/tools/javac/package-info.java b/src/main/java/org/codehaus/groovy/tools/javac/package-info.java
new file mode 100644
index 0000000000..54f57f19d5
--- /dev/null
+++ b/src/main/java/org/codehaus/groovy/tools/javac/package-info.java
@@ -0,0 +1,24 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF 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.
+ */
+
+/**
+ * Joint-compilation support integrating Groovy compilation units with Java
+ * stub generation and javac execution.
+ */
+package org.codehaus.groovy.tools.javac;
diff --git a/src/main/java/org/codehaus/groovy/tools/package-info.java b/src/main/java/org/codehaus/groovy/tools/package-info.java
new file mode 100644
index 0000000000..0c7cf342a6
--- /dev/null
+++ b/src/main/java/org/codehaus/groovy/tools/package-info.java
@@ -0,0 +1,24 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF 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.
+ */
+
+/**
+ * Command-line, compilation, and bootstrap utilities used by the Groovy tool
+ * chain.
+ */
+package org.codehaus.groovy.tools;
(groovy) 01/02: Add missing javadoc
Posted by su...@apache.org.
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 <su...@apache.org>
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);
}