From 72fc7733ac8f35130ef774707fc1707884a380a5 Mon Sep 17 00:00:00 2001 From: Schalk Cronje Date: Sat, 1 Jun 2019 10:32:18 +0200 Subject: [PATCH] Ensure all new classes have reasonable groovydoc/javadoc (#364) --- .../jrubygradle/core/ApiException.groovy | 1 + .../jrubygradle/core/GemDependency.java | 13 + .../com/github/jrubygradle/core/GemInfo.java | 4 + .../github/jrubygradle/core/GemVersion.groovy | 423 ++++++++++-------- .../core/GemVersionException.groovy | 1 + .../jrubygradle/core/IvyXmlProxyServer.java | 26 ++ .../core/RepositoryHandlerExtension.groovy | 25 ++ .../core/internal/DefaultGemDependency.groovy | 8 + .../core/internal/DefaultGemInfo.groovy | 2 + .../internal/DefaultRubyGemRestApi.groovy | 33 +- .../jrubygradle/core/internal/GemToIvy.groovy | 21 + .../jrubygradle/core/internal/IvyUtils.groovy | 1 + .../internal/IvyXmlGlobalProxyRegistry.groovy | 13 +- .../internal/IvyXmlRatpackProxyServer.groovy | 41 +- 14 files changed, 410 insertions(+), 202 deletions(-) diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/ApiException.groovy b/core-plugin/src/main/groovy/com/github/jrubygradle/core/ApiException.groovy index 390029bc..f0edbcac 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/ApiException.groovy +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/ApiException.groovy @@ -5,6 +5,7 @@ import groovy.transform.InheritConstructors /** Throws when there are issues with the RubyGems REST API. * + * @since 2.0 */ @InheritConstructors @CompileStatic diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemDependency.java b/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemDependency.java index 2c9624fd..6373d7cb 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemDependency.java +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemDependency.java @@ -1,7 +1,20 @@ package com.github.jrubygradle.core; +/** Description of a transitive GEM dependency. + * + * @since 2.0 + */ public interface GemDependency { + + /** Name of transitive GEM dependency. + * + * @return GEM name + */ String getName(); + /** Version requirements that is requested upon this transitive dependency. + * + * @return Version requirements in GEM format. + */ String getRequirements(); } diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemInfo.java b/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemInfo.java index 1082220f..77e2c615 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemInfo.java +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemInfo.java @@ -3,6 +3,10 @@ import java.net.URI; import java.util.List; +/** GEM metadata. + * + * @since 2.0 + */ public interface GemInfo { /** GEM name. diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemVersion.groovy b/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemVersion.groovy index f940e562..e6e5f8f6 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemVersion.groovy +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemVersion.groovy @@ -31,6 +31,8 @@ import java.util.regex.Pattern * pattern. * * @author Christian Meier + * + * @since 2.0 (Moved here from base plugin where it existed since 0.4.0) */ @CompileStatic class GemVersion implements Comparable { @@ -68,6 +70,8 @@ class GemVersion implements Comparable { * * @param singleRequirement Gradle version string. * @return GemVersion instance. + * + * @since 2.0 */ static GemVersion gemVersionFromGradleRequirement(String singleRequirement) { new GemVersion(singleRequirement) @@ -77,6 +81,8 @@ class GemVersion implements Comparable { * * @param singleRequirement Single GEM requirement string. * @return GemVersion instance. + * + * @since 2.0 */ @SuppressWarnings('DuplicateStringLiteral') static GemVersion gemVersionFromGemRequirement(String singleRequirement) { @@ -128,228 +134,261 @@ class GemVersion implements Comparable { "${base}${('.' + MAX_VERSION) * adds}", true ) - } else { - throw new GemVersionException("Do not not how to process ${singleRequirement} as a version string") + } else { + throw new GemVersionException("Do not not how to process ${singleRequirement} as a version string") + } } -} - -boolean isHighInclusive() { - prefix == LOW_IN -} - -boolean isLowInclusive() { - postfix == UP_IN -} -boolean isOpenHigh() { - high == MAX_VERSION -} - -/** - * since GemVersion is version range with lower bound and upper bound - * this method just calculates the intersection of this version range - * with the given other version range. it also honors whether the boundary - * itself is included or excluded by the respective ranges. - * - * @param The other version range to be intersected with this version range - * @return GemVersion the intersected version range - */ -GemVersion intersect(String otherVersion) { - intersect(gemVersionFromGradleRequirement(otherVersion)) -} + /** Is the low version specification inclusive? + * + * @return {@code true} if inclusive. + * + * @since 2.0 + */ + boolean isLowInclusive() { + prefix == LOW_IN + } -/** - * since GemVersion is version range with lower bound and upper bound - * this method just calculates the intersection of this version range - * with the given other version range. it also honors whether the boundary - * itself is included or excluded by the respective ranges. - * - * @param The other version range to be intersected with this version range - * @return GemVersion the intersected version range - */ -GemVersion intersect(GemVersion other) { - String newPrefix - String newLow - switch (compare(low, other.low)) { - case -1: - newLow = other.low - newPrefix = other.prefix - break - case 0: - newPrefix = prefix == LOW_EX || other.prefix == LOW_EX ? LOW_EX : LOW_IN - newLow = low - break - case 1: - newLow = low - newPrefix = prefix + /** Is the high version specification inclusive? + * + * @return {@code true} if inclusive. + * + * @since 2.0 + */ + boolean isHighInclusive() { + postfix == UP_IN } - String newPostfix - String newHigh - - switch (compare(high, other.high)) { - case 1: - newHigh = other.high - newPostfix = other.postfix - break - case 0: - newPostfix = postfix == UP_EX || other.postfix == UP_EX ? UP_EX : UP_IN - newHigh = high - break - case -1: - newHigh = high - newPostfix = postfix + /** Is the high version unspecified? + * + * @return {@code true} if the high version is unspecified in the original GEM specification. + * + * @since 2.0 + */ + boolean isOpenHigh() { + high == MAX_VERSION } - return new GemVersion(newPrefix, newLow, newHigh, newPostfix) -} -GemVersion union(GemVersion other) { - List pair = [this, other] - GemVersion min = pair.min() - GemVersion max = pair.max() + /** + * since GemVersion is version range with lower bound and upper bound + * this method just calculates the intersection of this version range + * with the given other version range. it also honors whether the boundary + * itself is included or excluded by the respective ranges. + * + * @param The other version range to be intersected with this version range + * @return GemVersion the intersected version range + */ + GemVersion intersect(String otherVersion) { + intersect(gemVersionFromGradleRequirement(otherVersion)) + } - new GemVersion(min.prefix, min.low, max.high, max.postfix) -} + /** + * since GemVersion is version range with lower bound and upper bound + * this method just calculates the intersection of this version range + * with the given other version range. it also honors whether the boundary + * itself is included or excluded by the respective ranges. + * + * @param The other version range to be intersected with this version range + * @return GemVersion the intersected version range + * + * @since 2.0 + */ + GemVersion intersect(GemVersion other) { + String newPrefix + String newLow + switch (compare(low, other.low)) { + case -1: + newLow = other.low + newPrefix = other.prefix + break + case 0: + newPrefix = prefix == LOW_EX || other.prefix == LOW_EX ? LOW_EX : LOW_IN + newLow = low + break + case 1: + newLow = low + newPrefix = prefix + } -@Override -int compareTo(GemVersion o) { - int loCompare = compare(low, o.low) - if (loCompare) { - return loCompare + String newPostfix + String newHigh + + switch (compare(high, other.high)) { + case 1: + newHigh = other.high + newPostfix = other.postfix + break + case 0: + newPostfix = postfix == UP_EX || other.postfix == UP_EX ? UP_EX : UP_IN + newHigh = high + break + case -1: + newHigh = high + newPostfix = postfix + } + return new GemVersion(newPrefix, newLow, newHigh, newPostfix) } - if (prefix != o.prefix) { - return prefix == LOW_IN ? -1 : 1 + /** Creates a new GEM version requirement which that the lowest of two requirements and the highest + * of those same requirement + * + * @param other Other GEM to combine with + * @return New GEM version requirement. + * + * @since 2.0 + */ + GemVersion union(GemVersion other) { + List pair = [this, other] + GemVersion min = pair.min() + GemVersion max = pair.max() + + new GemVersion(min.prefix, min.low, max.high, max.postfix) } - int hiCompare = compare(high, o.high) + /** Allows for versions to be compared and sorted. + * + * @param other Other GEM version to compare to. + * @return -1, 0 or 1. + * + * @since 2.0 + */ + @Override + int compareTo(GemVersion other) { + int loCompare = compare(low, other.low) + if (loCompare) { + return loCompare + } - if (hiCompare) { - return hiCompare - } + if (prefix != other.prefix) { + return prefix == LOW_IN ? -1 : 1 + } - if (postfix != o.postfix) { - return postfix == UP_IN ? 1 : -1 - } + int hiCompare = compare(high, other.high) - 0 -} + if (hiCompare) { + return hiCompare + } -/** - * examines the version range on conflict, i.e. lower bound bigger then - * upper bound. - * @return boolean true if lower bound bigger then upper bound - */ -boolean conflict() { - return (compare(low, high) == 1) -} + if (postfix != other.postfix) { + return postfix == UP_IN ? 1 : -1 + } -/** - * string of the underlying data as maven version range. for prereleased - * versions with ranges like [1.pre, 1.pre] the to range will be replaced - * by the single boundary of the range. - * - * @return String maven version range - */ -String toString() { - if (prefix == LOW_IN && postfix == UP_IN && low == high && low =~ /[a-zA-Z]/) { - return low + 0 } - return "${prefix}${low},${high}${postfix}" -} -@CompileDynamic -@SuppressWarnings('NoDef') -private static String getVersionFromRequirement(String gemRevision, Pattern matchPattern) { - def matcher = gemRevision =~ matchPattern - matcher[0][1] -} - -private GemVersion(Boolean lowInclusive, String low, String high, Boolean highInclusive) { - this.prefix = lowInclusive ? LOW_IN : LOW_EX - this.low = low - this.high = high - this.postfix = highInclusive ? UP_IN : UP_EX -} + /** + * examines the version range on conflict, i.e. lower bound bigger then + * upper bound. -private GemVersion(String pre, String low, String high, String post) { - this.prefix = pre - this.low = low - this.high = high - this.postfix = post -} + * @return boolean true if lower bound bigger then upper bound + */ + boolean conflict() { + return (compare(low, high) == 1) + } -/** - * converts the given string to a version range with inclusive or - * exclusive boundaries. - * - * @param String gradleVersionPattern - */ -private GemVersion(final String gradleVersionPattern) { -// // workaround a bug in gem proxy which can not handle != operators -// version = version.replace('=', '') - if (gradleVersionPattern.contains('+')) { - low = ZEROS.matcher(PLUS.matcher(DOT_PLUS.matcher(gradleVersionPattern).replaceFirst('.0')).replaceFirst('')).replaceFirst('') - high = DIGITS_PLUS.matcher(DOT_PLUS.matcher(gradleVersionPattern).replaceFirst('.99999')).replaceFirst(MAX_VERSION) - } else if (gradleVersionPattern.contains(LOW_IN) || gradleVersionPattern.contains(LOW_EX) || - gradleVersionPattern.contains(UP_IN) || gradleVersionPattern.contains(UP_EX)) { - prefix = gradleVersionPattern.charAt(0).toString() - postfix = gradleVersionPattern.charAt(gradleVersionPattern.size() - 1).toString() - low = ZEROS.matcher(FIRST.matcher(TAIL.matcher(gradleVersionPattern).replaceFirst('')).replaceFirst('')).replaceFirst('') - high = LAST.matcher(HEAD.matcher(gradleVersionPattern).replaceFirst('')).replaceFirst('') - - if (high == '') { - high = MAX_VERSION + /** + * string of the underlying data as maven version range. for prereleased + * versions with ranges like [1.pre, 1.pre] the to range will be replaced + * by the single boundary of the range. + * + * @return String maven version range + */ + String toString() { + if (prefix == LOW_IN && postfix == UP_IN && low == high && low =~ /[a-zA-Z]/) { + return low } - } else { - low = gradleVersionPattern - high = gradleVersionPattern + return "${prefix}${low},${high}${postfix}" } -} -/** - * compares two version strings. first it splits the version - * into parts on their ".". if one version has more parts then - * the other, then the number of parts is used for comparison. - * otherwise we find a part which differs between the versions - * and compare them. this last comparision converts the parts to - * integers if both contains only digits. otherwise a lexical - * string comparision is used. - * - * @param String aObject first version - * @param String bObject second version - * @return int -1 if aObject < bObject, 0 if both are equal and 1 if aObject > bObject - */ -private int compare(String aObject, String bObject) { - String[] aDigits = aObject.split(VERSION_SPLIT) - String[] bDigits = bObject.split(VERSION_SPLIT) - int index = -1 - - for (int i = 0; i < aDigits.length && i < bDigits.length; i++) { - if (aDigits[i] != bDigits[i]) { - index = i - break + @CompileDynamic + @SuppressWarnings('NoDef') + private static String getVersionFromRequirement(String gemRevision, Pattern matchPattern) { + def matcher = gemRevision =~ matchPattern + matcher[0][1] + } + + private GemVersion(Boolean lowInclusive, String low, String high, Boolean highInclusive) { + this.prefix = lowInclusive ? LOW_IN : LOW_EX + this.low = low + this.high = high + this.postfix = highInclusive ? UP_IN : UP_EX + } + + private GemVersion(String pre, String low, String high, String post) { + this.prefix = pre + this.low = low + this.high = high + this.postfix = post + } + + /** + * converts the given string to a version range with inclusive or + * exclusive boundaries. + * + * @param String gradleVersionPattern + */ + private GemVersion(final String gradleVersionPattern) { + if (gradleVersionPattern.contains('+')) { + low = ZEROS.matcher(PLUS.matcher(DOT_PLUS.matcher(gradleVersionPattern).replaceFirst('.0')).replaceFirst('')).replaceFirst('') + high = DIGITS_PLUS.matcher(DOT_PLUS.matcher(gradleVersionPattern).replaceFirst('.99999')).replaceFirst(MAX_VERSION) + } else if (gradleVersionPattern.contains(LOW_IN) || gradleVersionPattern.contains(LOW_EX) || + gradleVersionPattern.contains(UP_IN) || gradleVersionPattern.contains(UP_EX)) { + prefix = gradleVersionPattern.charAt(0).toString() + postfix = gradleVersionPattern.charAt(gradleVersionPattern.size() - 1).toString() + low = ZEROS.matcher(FIRST.matcher(TAIL.matcher(gradleVersionPattern).replaceFirst('')).replaceFirst('')).replaceFirst('') + high = LAST.matcher(HEAD.matcher(gradleVersionPattern).replaceFirst('')).replaceFirst('') + + if (high == '') { + high = MAX_VERSION + } + } else { + low = gradleVersionPattern + high = gradleVersionPattern } } - if (index == -1) { - // one contains the other - so look at the length - if (aDigits.length < bDigits.length) { - return -1 + /** + * compares two version strings. first it splits the version + * into parts on their ".". if one version has more parts then + * the other, then the number of parts is used for comparison. + * otherwise we find a part which differs between the versions + * and compare them. this last comparision converts the parts to + * integers if both contains only digits. otherwise a lexical + * string comparision is used. + * + * @param String aObject first version + * @param String bObject second version + * @return int -1 if aObject < bObject, 0 if both are equal and 1 if aObject > bObject + */ + private int compare(String aObject, String bObject) { + String[] aDigits = aObject.split(VERSION_SPLIT) + String[] bDigits = bObject.split(VERSION_SPLIT) + int index = -1 + + for (int i = 0; i < aDigits.length && i < bDigits.length; i++) { + if (aDigits[i] != bDigits[i]) { + index = i + break + } } - if (aDigits.length == bDigits.length) { - return 0 + + if (index == -1) { + // one contains the other - so look at the length + if (aDigits.length < bDigits.length) { + return -1 + } + if (aDigits.length == bDigits.length) { + return 0 + } + return 1 } - return 1 - } - if (aDigits[index].isInteger() && bDigits[index].isInteger()) { - // compare them as number - aDigits[index] as int <=> bDigits[index] as int - } else { - // compare them as string - aDigits[index] <=> bDigits[index] + if (aDigits[index].isInteger() && bDigits[index].isInteger()) { + // compare them as number + aDigits[index] as int <=> bDigits[index] as int + } else { + // compare them as string + aDigits[index] <=> bDigits[index] + } } } - -} diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemVersionException.groovy b/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemVersionException.groovy index e09c5d67..0275c77a 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemVersionException.groovy +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/GemVersionException.groovy @@ -5,6 +5,7 @@ import groovy.transform.InheritConstructors /** Thrown when GEM version strings cannot be correctly parsed. * + * @since 2.0 */ @InheritConstructors @CompileStatic diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/IvyXmlProxyServer.java b/core-plugin/src/main/groovy/com/github/jrubygradle/core/IvyXmlProxyServer.java index d93538c4..4cb8453f 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/IvyXmlProxyServer.java +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/IvyXmlProxyServer.java @@ -3,8 +3,34 @@ import java.net.URI; import java.nio.file.Path; +/** + * Proxy service which can translate RubyGems structures into Ivy structures + * and vice-versa. + * + * @since 2.0 + */ public interface IvyXmlProxyServer extends Runnable { + + /** Local bind address of the proxy server. + * + * @return URI of service. + */ URI getBindAddress(); + + /** Location of cached {@code ivy.xml} file. + * + * @param group Group associated with GEMs. This is the group that will be used inside Gradle + * as a Maven group or an Ivy organisation. As Rubygems does not have this concept + * it is purely for usage inside Gradle. + * @param name Name of GEM. + * @param revision Verison of GEM. + * @return Location of cached file (even if file does not exist yet). + */ Path ivyFile(String group, String name, String revision); + + /** Set proxy service to refresh dependencies on a subsequent run. + * + * @param refresh {@code true} if service should refresh dependencies. + */ void setRefreshDependencies(boolean refresh); } diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/RepositoryHandlerExtension.groovy b/core-plugin/src/main/groovy/com/github/jrubygradle/core/RepositoryHandlerExtension.groovy index 2c3b42ca..5268fcfa 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/RepositoryHandlerExtension.groovy +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/RepositoryHandlerExtension.groovy @@ -17,19 +17,44 @@ class RepositoryHandlerExtension { public static final String NAME = 'ruby' public static final String DEFAULT_GROUP_NAME = 'rubygems' + /** Creates an extension and associate it with a project. + * + * @param project Gradle project. + */ RepositoryHandlerExtension(final Project project) { this.project = project this.ivyProxies = new IvyXmlGlobalProxyRegistry((project)) } + /** Create an artifact repository which will use {@link https://rubygems.org} and + * associate group {@code rubygems} with it. + * + * @return Artifact repository. + */ ArtifactRepository gems() { bindRepositoryToProxyServer('https://rubygems.org'.toURI(), DEFAULT_GROUP_NAME) } + /** Create an artifact repository which will use specified URI and + * associate group {@code rubygems} with it. + * + * @param uri URI of remote repository that serves up Rubygems. Any object convertible + * with {@code project.uri} can be provided. + * + * @return Artifact repository. + */ ArtifactRepository gems(Object uri) { bindRepositoryToProxyServer(project.uri(uri), DEFAULT_GROUP_NAME) } + /** Create an artifact repository which will use specified URI and + * associate a specified group with it. + * + * @param group Group to associate this server with. + * @param uri URI of remote repository that serves up Rubygems. Any object convertible + * with {@code project.uri} can be provided. + * @return Artifact repository. + */ ArtifactRepository gems(String group, Object uri) { bindRepositoryToProxyServer(project.uri(uri), group) } diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultGemDependency.groovy b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultGemDependency.groovy index 678a16b9..5074d5a9 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultGemDependency.groovy +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultGemDependency.groovy @@ -9,6 +9,14 @@ import groovy.transform.CompileStatic */ @CompileStatic class DefaultGemDependency implements GemDependency { + + /** Name of transitive dependency. + * + */ String name + + /** Version requirements upon this transitive dependency. + * + */ String requirements } diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultGemInfo.groovy b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultGemInfo.groovy index fa5b6cde..9bc1dc82 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultGemInfo.groovy +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultGemInfo.groovy @@ -5,6 +5,8 @@ import com.github.jrubygradle.core.GemInfo import groovy.transform.CompileStatic /** An implementation of GEM metadata. + * + * Elements in this class match directly to the Rubgems REST API. * * @since 2.0 */ diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultRubyGemRestApi.groovy b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultRubyGemRestApi.groovy index 0d7af8d2..0e525ce2 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultRubyGemRestApi.groovy +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/DefaultRubyGemRestApi.groovy @@ -13,20 +13,38 @@ import static groovyx.net.http.ContentTypes.JSON import static groovyx.net.http.NativeHandlers.Parsers.json import static groovyx.net.http.OkHttpBuilder.configure -/** +/** Implementation for a RubyGems REST API client based upon + * HttpBuilder-ng. + * * @since 2.0 */ @CompileStatic class DefaultRubyGemRestApi implements RubyGemQueryRestApi { + /** Creates a client from a URI + * + * @param serverUri URI as a String. ONly the scheme plus host + * parts should be provided. + */ DefaultRubyGemRestApi(final String serverUri) { this.httpBuilder = getHttpBuilder(serverUri.toURI()) } + /** Creates a client from a URI + * + * @param serverUri Only the scheme plus host + * parts should be provided. + */ DefaultRubyGemRestApi(final URI serverUri) { this.httpBuilder = getHttpBuilder(serverUri) } + /** Returns all versions of a specific GEM. + * + * @param gemName Name of GEM. + * @return List of versions + * @throw {@link ApiException} if a networking error occurred. + */ @Override @SuppressWarnings('CatchThrowable') List allVersions(String gemName) { @@ -37,6 +55,12 @@ class DefaultRubyGemRestApi implements RubyGemQueryRestApi { } } + /** Returns the latest version for a specific GEM. + * + * @param gemName Name of GEM. + * @return Latest version. + * @throw {@link ApiException} if a networking error occurred or the GEM does not exist. + */ @Override @SuppressWarnings('CatchThrowable') String latestVersion(String gemName) { @@ -52,6 +76,13 @@ class DefaultRubyGemRestApi implements RubyGemQueryRestApi { version } + /** Retrieves the GEM metadata. + * + * @param gemName Name of GEM. + * @param gemVersion Version of the GEM. + * @return {@link GemInfo} instance. + * @throw {@link ApiException} if a networking error occurred or the GEM does not exist. + */ @Override @SuppressWarnings('CatchThrowable') GemInfo metadata(String gemName, String gemVersion) { diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/GemToIvy.groovy b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/GemToIvy.groovy index 12347800..074a7275 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/GemToIvy.groovy +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/GemToIvy.groovy @@ -15,15 +15,31 @@ import static com.github.jrubygradle.core.GemVersion.gemVersionFromGemRequiremen @CompileStatic class GemToIvy { + /** Create a converter from GEM metadata to Ivy metadata. + * + * This constructor version assumes that the group is called {@code rubygems}. + * @param serverUri URI of the RubyGems server. + */ GemToIvy(URI serverUri) { this.serverUri = serverUri.toString() } + /** Create a converter from GEM metadata to Ivy metadata. + * + * @param serverUri URI of the RubyGems server. + * @param group Use a group name other than {@code rubygems}. + */ GemToIvy(URI serverUri, String group) { this.serverUri = serverUri.toString() this.org = group } + /** Write the Ivy metadata. + * + * @param writer Writer for output + * @param gem GEM metadata + * @return {@code writer} after population with Ivy metadata in XML format. + */ @CompileDynamic @SuppressWarnings('NoDef') Writer writeTo(Writer writer, GemInfo gem) { @@ -65,6 +81,11 @@ class GemToIvy { writer } + /** Write the Ivy metadata to a string. + * + * @param gem GEM metadata. + * @return String containing the Ivy metadata in XML format. + */ String write(GemInfo gem) { StringWriter writer = new StringWriter() writeTo(writer, gem) diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyUtils.groovy b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyUtils.groovy index 3ca657c6..dc56fe1a 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyUtils.groovy +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyUtils.groovy @@ -6,6 +6,7 @@ import groovy.xml.MarkupBuilder /** Utilities for dealing with Ivy formats. * + * @since 2.0 */ @CompileStatic class IvyUtils { diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyXmlGlobalProxyRegistry.groovy b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyXmlGlobalProxyRegistry.groovy index b2ef5a4c..e68e44f6 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyXmlGlobalProxyRegistry.groovy +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyXmlGlobalProxyRegistry.groovy @@ -8,17 +8,28 @@ import java.security.MessageDigest import java.util.concurrent.ConcurrentHashMap import java.util.concurrent.ConcurrentMap -/** Allow only one version of the proxy to run +/** Allow only one version of the proxy to run. * + * @Since 2.0 */ @CompileStatic class IvyXmlGlobalProxyRegistry { + /** Create the registry and associate it with a Gradle project. + * + * @param project Associated project. + */ IvyXmlGlobalProxyRegistry(Project project) { rootCacheDir = new File(project.gradle.gradleUserHomeDir, 'rubygems-ivyxml-cache') refresh = project.gradle.startParameter.refreshDependencies } + /** Registers a URI and group to be server via the proxy. + * + * @param remoteURI URI of remote Rubygems server. + * @param group Group name for GEMs that will be fected from the remote. + * @return Access to a proxy sever. If the server does not exist it will be created. + */ IvyXmlProxyServer registerProxy(URI remoteURI, String group) { IvyXmlProxyServer proxy = getOrCreateServer(remoteURI, group, new File(rootCacheDir, uriHash(remoteURI))) proxy.refreshDependencies = refresh diff --git a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyXmlRatpackProxyServer.groovy b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyXmlRatpackProxyServer.groovy index 75ec3155..3eeb6834 100644 --- a/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyXmlRatpackProxyServer.groovy +++ b/core-plugin/src/main/groovy/com/github/jrubygradle/core/internal/IvyXmlRatpackProxyServer.groovy @@ -31,6 +31,13 @@ import static java.nio.file.StandardCopyOption.REPLACE_EXISTING @CompileStatic @Slf4j class IvyXmlRatpackProxyServer implements IvyXmlProxyServer { + + /** Implementation of a proxy server based upon Ratpack. + * + * @param cache Root directory for local Ivy XML cache. + * @param serverUri URI of remote Rubygems proxy. + * @param group Group that will be associated with the Rubygems proxy. + */ IvyXmlRatpackProxyServer(File cache, URI serverUri, String group) { localCachePath = cache gemToIvy = new GemToIvy(serverUri) @@ -38,24 +45,27 @@ class IvyXmlRatpackProxyServer implements IvyXmlProxyServer { this.group = group } - void debug(String text) { - log.debug(text) - } - - void debug(String text, Object context) { - log.debug(text, context) - } - + /** Tell the server to refresh dependencies upon a next run. + * + * @param refresh {@code true} to reload dependencies. + */ @Override void setRefreshDependencies(boolean refresh) { refreshDependencies = refresh ? 1 : 0 } + /** Get the address of the local proxy. + * + * @return Local address as a URI. + */ @Override URI getBindAddress() { "http://localhost:${server.bindPort}".toURI() } + /** Start the proxy. + * + */ @Override @SuppressWarnings('DuplicateStringLiteral') void run() { @@ -102,6 +112,13 @@ class IvyXmlRatpackProxyServer implements IvyXmlProxyServer { server } + /** Returns the cache location for a specific GEM. + * + * @param group Group associated with GEM. + * @param name GEM name. + * @param revision GEM revision. + * @return Location of {@code ivy.xml} file. + */ @SuppressWarnings('UnusedMethodParameter') Path ivyFile(String group, String name, String revision) { new File(localCachePath, "${name}/${revision}/ivy.xml").toPath() @@ -127,6 +144,14 @@ class IvyXmlRatpackProxyServer implements IvyXmlProxyServer { version.openHigh ? api.latestVersion(gemName) : version.high } + private void debug(String text) { + log.debug(text) + } + + private void debug(String text, Object context) { + log.debug(text, context) + } + private volatile int refreshDependencies = 0 private RatpackServer server private final File localCachePath