This is an automated email from the ASF dual-hosted git repository.
jdaugherty pushed a commit to branch wrapper-rewrite
in repository https://gitbox.apache.org/repos/asf/grails-core.git
The following commit(s) were added to refs/heads/wrapper-rewrite by this push:
new 5b58c4f888 Add javadoc & remove reserved html characters
5b58c4f888 is described below
commit 5b58c4f88834a0151ea97e2e261401a7a879c386
Author: James Daugherty <[email protected]>
AuthorDate: Thu May 15 12:04:54 2025 -0400
Add javadoc & remove reserved html characters
---
.../java/grails/init/FindLastReleaseHandler.java | 2 +-
.../java/grails/init/FindLastSnapshotHandler.java | 3 +++
.../main/java/grails/init/GrailsReleaseType.java | 9 +++++++
.../src/main/java/grails/init/GrailsUpdater.java | 29 ++++++++++++++++++---
.../src/main/java/grails/init/GrailsVersion.java | 5 +++-
.../main/java/grails/init/GrailsWrapperHome.java | 3 +++
.../main/java/grails/init/GrailsWrapperRepo.java | 30 ++++++++++++++++++++++
.../src/main/java/grails/init/Start.java | 4 +--
8 files changed, 78 insertions(+), 7 deletions(-)
diff --git
a/grails-wrapper/src/main/java/grails/init/FindLastReleaseHandler.java
b/grails-wrapper/src/main/java/grails/init/FindLastReleaseHandler.java
index 988111edc8..1fbd3482b6 100644
--- a/grails-wrapper/src/main/java/grails/init/FindLastReleaseHandler.java
+++ b/grails-wrapper/src/main/java/grails/init/FindLastReleaseHandler.java
@@ -21,7 +21,7 @@ import org.xml.sax.SAXException;
import org.xml.sax.helpers.DefaultHandler;
/**
- * Created by jameskleeh on 11/2/16.
+ * A SAX handler to parse the metadata-maven.xml file and extract the latest
release version
*/
public class FindLastReleaseHandler extends DefaultHandler {
diff --git
a/grails-wrapper/src/main/java/grails/init/FindLastSnapshotHandler.java
b/grails-wrapper/src/main/java/grails/init/FindLastSnapshotHandler.java
index 0995acd93d..ae51ec6f00 100644
--- a/grails-wrapper/src/main/java/grails/init/FindLastSnapshotHandler.java
+++ b/grails-wrapper/src/main/java/grails/init/FindLastSnapshotHandler.java
@@ -19,6 +19,9 @@ package grails.init;
import org.xml.sax.Attributes;
import org.xml.sax.helpers.DefaultHandler;
+/**
+ * A SAX handler to parse the metadata-maven.xml file and extract the latest
snapshot version
+ */
public class FindLastSnapshotHandler extends DefaultHandler {
private boolean insideSnapshotVersion = false;
diff --git a/grails-wrapper/src/main/java/grails/init/GrailsReleaseType.java
b/grails-wrapper/src/main/java/grails/init/GrailsReleaseType.java
index 3001042ad7..9f303c9499 100644
--- a/grails-wrapper/src/main/java/grails/init/GrailsReleaseType.java
+++ b/grails-wrapper/src/main/java/grails/init/GrailsReleaseType.java
@@ -20,16 +20,25 @@ import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
+/**
+ * The type of releases that a Grails version may represent
+ */
public enum GrailsReleaseType {
RELEASE,
RC,
MILESTONE,
SNAPSHOT;
+ /**
+ * @return true if this is a snapshot release
+ */
boolean isSnapshot() {
return this == SNAPSHOT;
}
+ /**
+ * @return this release type and all higher priority release types
+ */
public List<GrailsReleaseType> upTo() {
return Arrays.stream(GrailsReleaseType.values())
.filter(e -> e.ordinal() <= this.ordinal())
diff --git a/grails-wrapper/src/main/java/grails/init/GrailsUpdater.java
b/grails-wrapper/src/main/java/grails/init/GrailsUpdater.java
index bb0fb0b8d6..ece4007494 100644
--- a/grails-wrapper/src/main/java/grails/init/GrailsUpdater.java
+++ b/grails-wrapper/src/main/java/grails/init/GrailsUpdater.java
@@ -35,21 +35,38 @@ import java.util.List;
import static java.nio.file.StandardCopyOption.REPLACE_EXISTING;
+/**
+ * Handles updating the grails-cli shadowJar under `~/.grails/wrapper`
+ */
public class GrailsUpdater {
private final GrailsWrapperHome grailsWrapperHome;
private final GrailsVersion preferredVersion;
private GrailsVersion updatedVersion;
+ /**
+ * @param allowedTypes the release types that are allowed to be
updated to
+ * @param preferredVersion the preferred version to update to
+ * @throws IOException if canonicalizing the grails home fails
+ */
public GrailsUpdater(List<GrailsReleaseType> allowedTypes, GrailsVersion
preferredVersion) throws IOException {
this(allowedTypes, preferredVersion, null);
}
+ /**
+ * @param allowedTypes the release types that are allowed to be updated to
+ * @param preferredVersion the preferred version to update to
+ * @param possibleGrailsHome a possible directory for the grails home
+ * @throws IOException if canonicalizing the grails home fails
+ */
public GrailsUpdater(List<GrailsReleaseType> allowedTypes, GrailsVersion
preferredVersion, String possibleGrailsHome) throws IOException {
grailsWrapperHome = new GrailsWrapperHome(allowedTypes,
possibleGrailsHome);
this.preferredVersion = preferredVersion;
}
+ /**
+ * @return the `grails-cli` version that was selected by this updater
+ */
public GrailsVersion getSelectedVersion() {
if(preferredVersion != null) {
return preferredVersion;
@@ -62,15 +79,16 @@ public class GrailsUpdater {
return grailsWrapperHome.latestVersion;
}
+ /**
+ * @return the jar file for the `grails-cli` verison that was selected by
this updater`
+ */
public File getExecutedJarFile() {
GrailsVersion selectedVersion = getSelectedVersion();
return grailsWrapperHome.getWrapperImplementation(selectedVersion,
grailsWrapperHome.getVersionDirectory(selectedVersion));
}
/**
- * Reasons the grails wrapper may need updating:
- * 1. the expanded wrapper jar does not exist
- *
+ * @return true if the updater should update the `grails-cli` shadowJar
*/
public boolean needsUpdating() {
File jarFile = grailsWrapperHome.getLatestWrapperImplementation();
@@ -90,6 +108,11 @@ public class GrailsUpdater {
return false;
}
+ /**
+ * Fetches the selectedVersion and if it already exists, replaces the jar
file.
+ *
+ * @return true if an update was performed, false otherwise
+ */
public boolean update() {
GrailsWrapperRepo repo = GrailsWrapperRepo.getSelectedRepo();
diff --git a/grails-wrapper/src/main/java/grails/init/GrailsVersion.java
b/grails-wrapper/src/main/java/grails/init/GrailsVersion.java
index 0c061c78f2..1acf1d40b8 100644
--- a/grails-wrapper/src/main/java/grails/init/GrailsVersion.java
+++ b/grails-wrapper/src/main/java/grails/init/GrailsVersion.java
@@ -21,7 +21,7 @@ import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
- * Assists in parsing grails versions & sorting them by priority
+ * Assists in parsing grails versions and sorting them by priority
*/
public class GrailsVersion implements Comparable<GrailsVersion> {
private static final Pattern VERSION_PATTERN =
Pattern.compile("^(\\d+)[.](\\d+)[.](.*)$");
@@ -38,6 +38,9 @@ public class GrailsVersion implements
Comparable<GrailsVersion> {
public final GrailsReleaseType releaseType;
public final int patchNumber;
+ /**
+ * @param version the grails version number
+ */
GrailsVersion(String version) {
this.version = version;
diff --git a/grails-wrapper/src/main/java/grails/init/GrailsWrapperHome.java
b/grails-wrapper/src/main/java/grails/init/GrailsWrapperHome.java
index 4a00f0931b..25ade71ab5 100644
--- a/grails-wrapper/src/main/java/grails/init/GrailsWrapperHome.java
+++ b/grails-wrapper/src/main/java/grails/init/GrailsWrapperHome.java
@@ -24,6 +24,9 @@ import java.util.List;
import java.util.Objects;
import java.util.stream.Stream;
+/**
+ * Helper class for managing the `grails-cli` jar files in the Grails Wrapper
home directory.
+ */
public class GrailsWrapperHome {
public static final String CLI_COMBINED_PROJECT_NAME = "grails-cli";
diff --git a/grails-wrapper/src/main/java/grails/init/GrailsWrapperRepo.java
b/grails-wrapper/src/main/java/grails/init/GrailsWrapperRepo.java
index 55224018e5..bcab7d15f6 100644
--- a/grails-wrapper/src/main/java/grails/init/GrailsWrapperRepo.java
+++ b/grails-wrapper/src/main/java/grails/init/GrailsWrapperRepo.java
@@ -18,6 +18,9 @@ package grails.init;
import java.io.File;
+/**
+ * Helper class to locate the remote or local repository for the `grails-cli`
+ */
public class GrailsWrapperRepo {
private String baseUrl;
private String repoPath;
@@ -27,18 +30,39 @@ public class GrailsWrapperRepo {
private GrailsWrapperRepo() {
}
+ /**
+ * @return the base url of the given repository
+ */
String getUrl() {
return join(baseUrl, repoPath);
}
+ /**
+ * Get the path to the root metadata file in the configured repository
+ *
+ * @return the url to the root metadata-maven.xml file
+ */
String getRootMetadataUrl() {
return join(getUrl(), metadataName);
}
+ /**
+ * Given a grails version, get the path to the version specific metadata
file in the configured repository
+ *
+ * @param version the desired grails version
+ * @return the url to the version specific metadata-maven.xml file
+ */
String getMetadataUrl(GrailsVersion version) {
return join(getUrl(), version.version, metadataName);
}
+ /**
+ * Given a grails version & a file name, get the path to that file in the
configured repository
+ *
+ * @param version the grails version
+ * @param name the file name of the `grails-cli` jar
+ * @return the file url to the `grails-cli` jar
+ */
String getFileUrl(GrailsVersion version, String name) {
return join(getUrl(), version.version, name);
@@ -48,6 +72,9 @@ public class GrailsWrapperRepo {
return String.join(isFile ? File.separator : "/", elements);
}
+ /**
+ * @return the repo the wrapper should look for the `grails-cli` jar
+ */
static GrailsWrapperRepo getSelectedRepo() {
GrailsWrapperRepo repo = new GrailsWrapperRepo();
repo.repoPath = "org/apache/grails/" +
GrailsWrapperHome.CLI_COMBINED_PROJECT_NAME;
@@ -71,6 +98,9 @@ public class GrailsWrapperRepo {
return repo;
}
+ /**
+ * @return the override maven repository if configured via the property
`grails.repo.url` or environment variable `GRAILS_REPO_URL`
+ */
static String getConfiguredMavenUrl() {
String baseUrl = System.getProperty("grails.repo.url");
if (baseUrl != null) {
diff --git a/grails-wrapper/src/main/java/grails/init/Start.java
b/grails-wrapper/src/main/java/grails/init/Start.java
index 695f0d4fb2..69b9117f6e 100644
--- a/grails-wrapper/src/main/java/grails/init/Start.java
+++ b/grails-wrapper/src/main/java/grails/init/Start.java
@@ -34,9 +34,9 @@ import java.util.stream.Collectors;
* The purpose of this class is to download the expanded Grails wrapper jars
into GRAILS_WRAPPER_HOME (`.grails` in the project root)
* This class is not meant to be distributed as part of SDKMAN since we'll
distribute the expanded jars with it.
* After downloading the jars, it will delegate to the downloaded grails-cli
project.
- *
+ * <p>
* There are 3 ways this class can be used:
- * 1. in testing a grails release (run from a non-project directory) //
requires GRAILS_REPO_URL set to ~/.m2/repository
+ * 1. in testing a grails release (run from a non-project directory) -
requires GRAILS_REPO_URL set to `~/.m2/repository`
* 2. running from a non-project directory (end user usage)
* 3. running from inside a grails project
*/
