io.github.intisy.gradle.github.api.capability

Interface Releases

All Known Implementing Classes:

GitHub

public interface Releases

Resolves and downloads GitHub release artifacts.

Method Summary

Modifier and Type	Method and Description
java.util.List<DeclaredDependency>	declaredDependencies(java.io.File jar)
java.util.List<java.io.File>	downloadAllModuleJars(java.lang.String owner, java.lang.String repo, java.lang.String version) Downloads every module asset published under the reserved :all classifier, so a consumer of a multi-module release can pull every module jar without naming each one.
java.util.Optional<java.io.File>	downloadJar(java.lang.String owner, java.lang.String repo, java.lang.String version) Downloads the default release jar, matching repo.jar, repo-version.jar, repo-standalone.jar, or the first plain .jar asset in that order.
java.util.Optional<java.io.File>	downloadJar(java.lang.String owner, java.lang.String repo, java.lang.String version, java.lang.String classifier) Downloads a specific classifier asset, matching repo-classifier.jar exactly.
Release	latestRelease(java.lang.String owner, java.lang.String repo)
java.lang.String	latestVersion(java.lang.String owner, java.lang.String repo)
Release	releaseByTag(java.lang.String owner, java.lang.String repo, java.lang.String tag)
java.util.List<java.io.File>	resolveWithDependencies(java.lang.String owner, java.lang.String repo, java.lang.String version) Resolves owner:repo:version and its full transitive closure of GitHub-hosted dependencies declared via each jar's embedded META-INF/github-dependencies.json, including the root jar itself.

Method Detail

latestVersion

java.lang.String latestVersion(java.lang.String owner,
                               java.lang.String repo)

Parameters:

owner - the GitHub account or organization that owns the repository.

repo - the repository name, without the owner prefix.

Returns:

the latest release's tag, or null if the repository has no releases.

Throws:

RateLimitException - if the GitHub API rate limit has been exceeded.

releaseByTag

Release releaseByTag(java.lang.String owner,
                     java.lang.String repo,
                     java.lang.String tag)

Parameters:

owner - the GitHub account or organization that owns the repository.

repo - the repository name, without the owner prefix.

tag - the release tag to resolve (a "v" prefix is tried both with and without).

Returns:

the release identified by tag.

Throws:

java.lang.RuntimeException - if no release matches tag (unchecked; the tag is looked up, not I/O).

RateLimitException - if the GitHub API rate limit has been exceeded.

latestRelease

Release latestRelease(java.lang.String owner,
                      java.lang.String repo)

Parameters:

owner - the GitHub account or organization that owns the repository.

repo - the repository name, without the owner prefix.

Returns:

the latest release, or null if the repository has no releases.

Throws:

RateLimitException - if the GitHub API rate limit has been exceeded.

downloadJar

java.util.Optional<java.io.File> downloadJar(java.lang.String owner,
                                             java.lang.String repo,
                                             java.lang.String version)

Downloads the default release jar, matching repo.jar, repo-version.jar, repo-standalone.jar, or the first plain .jar asset in that order.

Parameters:

owner - the GitHub account or organization that owns the repository.

repo - the repository name, without the owner prefix.

version - the release tag to resolve (a "v" prefix is tried both with and without).

Returns:

the downloaded (or cached) jar file, or an empty Optional if the release exists but has no matching jar asset. A release that does not exist at all is a different kind of absence and is never represented this way (see @throws below): the two are not the same thing, since a missing release is almost always a caller mistake (a typo'd version, a deleted or renamed tag) while a missing asset within a release that does exist is a normal outcome.

Throws:

ReleaseNotFoundException - if no release matches version.

java.lang.RuntimeException - thrown unchecked by the underlying client if the download itself fails or another API error occurs.

RateLimitException - if the GitHub API rate limit has been exceeded.

downloadJar

java.util.Optional<java.io.File> downloadJar(java.lang.String owner,
                                             java.lang.String repo,
                                             java.lang.String version,
                                             java.lang.String classifier)

Downloads a specific classifier asset, matching repo-classifier.jar exactly.

Parameters:

owner - the GitHub account or organization that owns the repository.

repo - the repository name, without the owner prefix.

version - the release tag to resolve (a "v" prefix is tried both with and without).

classifier - the artifact classifier identifying the asset (e.g. "api").

Returns:

the classifier asset's jar, or an empty Optional if the release exists but has no asset named repo-classifier.jar. As with the 3-argument overload above, a release that does not exist at all is a different kind of absence and is never represented this way.

Throws:

ReleaseNotFoundException - if no release matches version.

java.lang.RuntimeException - thrown unchecked by the underlying client if the download itself fails or another API error occurs.

RateLimitException - if the GitHub API rate limit has been exceeded.

downloadAllModuleJars

java.util.List<java.io.File> downloadAllModuleJars(java.lang.String owner,
                                                   java.lang.String repo,
                                                   java.lang.String version)

Downloads every module asset published under the reserved :all classifier, so a consumer of a multi-module release can pull every module jar without naming each one.

Parameters:

owner - the GitHub account or organization that owns the repository.

repo - the repository name, without the owner prefix.

version - the release tag to resolve (a "v" prefix is tried both with and without).

Returns:

the downloaded module jars; never null or empty (a release with no module assets throws).

Throws:

java.lang.RuntimeException - thrown unchecked by the underlying client if no release matches version or if the release has no module assets.

RateLimitException - if the GitHub API rate limit has been exceeded.

resolveWithDependencies

java.util.List<java.io.File> resolveWithDependencies(java.lang.String owner,
                                                     java.lang.String repo,
                                                     java.lang.String version)

Resolves owner:repo:version and its full transitive closure of GitHub-hosted dependencies declared via each jar's embedded META-INF/github-dependencies.json, including the root jar itself.

Cycle detection is local to a single call. A caller resolving many independent coordinates that may share transitive dependencies (for example, one call per declared dependency across several build configurations) must deduplicate the combined results itself if it wants each distinct jar added only once.

Parameters:

owner - the GitHub account or organization that owns the root repository.

repo - the root repository name, without the owner prefix.

version - the release tag to resolve (a "v" prefix is tried both with and without).

Returns:

the root jar followed by every transitively resolved jar, each appearing once.

Throws:

java.lang.RuntimeException - thrown unchecked by the underlying client if the root or any transitive dependency fails to resolve: no release matches its version, the release has no matching jar asset, or the download itself fails. Unlike downloadJar(String, String, String), this method has no way to represent one transitive dependency's absence without abandoning the whole resolution, so it always throws rather than reporting absence in its return type.

RateLimitException - if the GitHub API rate limit has been exceeded.

declaredDependencies

java.util.List<DeclaredDependency> declaredDependencies(java.io.File jar)

Parameters:

jar - the jar file to inspect; not modified.

Returns:

the dependencies declared by jar's embedded META-INF/github-dependencies.json, or an empty list if the jar has no such entry, or if the entry exists but is unreadable or malformed. The unreadable case logs a warning naming jar so a corrupt artifact is not silently treated as having no dependencies.