From 303dd703d673ddb922f400fac1769135049e5eaa Mon Sep 17 00:00:00 2001 From: carm Date: Sat, 22 Jan 2022 05:37:54 +0800 Subject: [PATCH] =?UTF-8?q?[v1.2.0]=20=E8=A1=A5=E5=85=85Javadoc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .documentation/JAVADOC-README.md | 9 +++ pom.xml | 2 +- .../lib/githubreleases4j/GitHubHttpUtils.java | 1 + .../lib/githubreleases4j/GithubAsset.java | 19 +++++ .../lib/githubreleases4j/GithubRelease.java | 10 +++ .../githubreleases4j/GithubReleases4J.java | 80 ++++++++++++++++++- 6 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 .documentation/JAVADOC-README.md diff --git a/.documentation/JAVADOC-README.md b/.documentation/JAVADOC-README.md new file mode 100644 index 0000000..dd99a39 --- /dev/null +++ b/.documentation/JAVADOC-README.md @@ -0,0 +1,9 @@ +# GithubReleases4J Javadoc + +基于 [Github Pages](https://pages.github.com/) 搭建，请访问 [JavaDoc](https://CarmJos.github.io/GithubReleases4J) 。 + +## 如何实现？ + +若您也想通过 [Github Actions](https://docs.github.com/en/actions/learn-github-actions) +自动部署项目的Javadoc到 [Github Pages](https://pages.github.com/) ， +可以参考我的文章 [《自动部署Javadoc到Github Pages》](https://pages.carm.cc/doc/javadoc-in-github.html) 。 \ No newline at end of file diff --git a/pom.xml b/pom.xml index 9747af0..5caa68c 100644 --- a/pom.xml +++ b/pom.xml @@ -14,7 +14,7 @@ cc.carm.lib githubreleases4j - 1.1.0 + 1.2.0 GithubReleases4J Github Releases for Java diff --git a/src/main/java/cc/carm/lib/githubreleases4j/GitHubHttpUtils.java b/src/main/java/cc/carm/lib/githubreleases4j/GitHubHttpUtils.java index b3566ac..71f6f42 100644 --- a/src/main/java/cc/carm/lib/githubreleases4j/GitHubHttpUtils.java +++ b/src/main/java/cc/carm/lib/githubreleases4j/GitHubHttpUtils.java @@ -18,6 +18,7 @@ import java.util.stream.Collectors; public class GitHubHttpUtils { private GitHubHttpUtils() { + // Should not be the instance or use by other codes. } protected static JSONObject getObject(@NotNull String urlString, @Nullable String token) throws IOException { diff --git a/src/main/java/cc/carm/lib/githubreleases4j/GithubAsset.java b/src/main/java/cc/carm/lib/githubreleases4j/GithubAsset.java index 51f7ade..0f2b1e0 100644 --- a/src/main/java/cc/carm/lib/githubreleases4j/GithubAsset.java +++ b/src/main/java/cc/carm/lib/githubreleases4j/GithubAsset.java @@ -81,15 +81,34 @@ public class GithubAsset { return GithubReleases4J.parseDate(getContents().getString("updated_at")); } + /** + * Download this asset to current path with original name. + * + * @return Downloaded file. + * @throws IOException Throws when has any io exception + */ public File download() throws IOException { return download(null); } + /** + * Download this asset with provided path and name. + * + * @param path target path, e.g. "cache/build.zip" + * @param options Copy options + * @return Downloaded file. + * @throws IOException Throws when has any io exception + */ public File download(@Nullable String path, CopyOption... options) throws IOException { path = path == null ? getName() : path; return GitHubHttpUtils.download(getBrowserDownloadURL(), getSource().getAuthToken(), path, options); } + /** + * Get the uploader of this asset. + * + * @return The author user {@link GithubUser} + */ public GithubUser getUploader() { return Optional.ofNullable(getContents().getJSONObject("uploader")) .map(GithubUser::of) diff --git a/src/main/java/cc/carm/lib/githubreleases4j/GithubRelease.java b/src/main/java/cc/carm/lib/githubreleases4j/GithubRelease.java index 279a0dc..46ee95f 100644 --- a/src/main/java/cc/carm/lib/githubreleases4j/GithubRelease.java +++ b/src/main/java/cc/carm/lib/githubreleases4j/GithubRelease.java @@ -130,12 +130,22 @@ public class GithubRelease { return getContents().getString("discussion_url"); } + /** + * Get the author of this release. + * + * @return The author user {@link GithubUser} + */ public GithubUser getAuthor() { return Optional.ofNullable(getContents().getJSONObject("author")) .map(GithubUser::of) .orElse(null); } + /** + * Get the assets of this release. + * + * @return {@link GithubAsset} + */ public List getAssets() { JSONArray assetsArray = getContents().getJSONArray("assets"); if (assetsArray == null) return new ArrayList<>(); diff --git a/src/main/java/cc/carm/lib/githubreleases4j/GithubReleases4J.java b/src/main/java/cc/carm/lib/githubreleases4j/GithubReleases4J.java index 5e654f2..34f28c6 100644 --- a/src/main/java/cc/carm/lib/githubreleases4j/GithubReleases4J.java +++ b/src/main/java/cc/carm/lib/githubreleases4j/GithubReleases4J.java @@ -14,14 +14,31 @@ import java.util.List; import java.util.stream.Collectors; import java.util.stream.IntStream; +/** + * GitHub Releases for Java + *
To provide an easy way to fetch updates and download assets. + *
Based on GitHub REST API (Releases) . + * + * @author CarmJos + */ public class GithubReleases4J { private GithubReleases4J() { + // Should not be the instance. } public static String GITHUB_API_URL = "https://api.github.com"; public static SimpleDateFormat GH_TIME_FORMAT = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'"); + /** + * List repository's current existing releases. + * + * @param owner Repository's Owner + * @param repository Repository's Name + * @param token OAuth Access Token + *
Necessary when this repository is private. + * @return {@link GithubRelease} + */ public static @NotNull List listReleases(@NotNull String owner, @NotNull String repository, @Nullable String token) { try { @@ -38,10 +55,28 @@ public class GithubReleases4J { } } + /** + * List a public repository's current existing releases. + * + * @param owner Repository's Owner + * @param repository Repository's Name + * @return {@link GithubRelease} + */ public static @NotNull List listReleases(@NotNull String owner, @NotNull String repository) { return listReleases(owner, repository, null); } + + /** + * Get a repository's release by the id . + * + * @param owner Repository's Owner + * @param repository Repository's Name + * @param releaseID Release ID + * @param token OAuth Access Token + *
Necessary when this repository is private. + * @return {@link GithubRelease} + */ public static @Nullable GithubRelease getRelease(@NotNull String owner, @NotNull String repository, @NotNull String releaseID, @Nullable String token) { @@ -57,27 +92,70 @@ public class GithubReleases4J { } + + /** + * Get a public repository's release by the id . + * + * @param owner Repository's Owner + * @param repository Repository's Name + * @param releaseID Release ID + * @return {@link GithubRelease} + */ public static @Nullable GithubRelease getRelease(@NotNull String owner, @NotNull String repository, @NotNull String releaseID) { return getRelease(owner, repository, releaseID, null); } + + /** + * Get a repository's release by the tag name . + * + * @param owner Repository's Owner + * @param repository Repository's Name + * @param tagName Release Tag Name + * @param token OAuth Access Token + *
Necessary when this repository is private. + * @return {@link GithubRelease} + */ public static @Nullable GithubRelease getReleaseByTag(@NotNull String owner, @NotNull String repository, @NotNull String tagName, @Nullable String token) { return getRelease(owner, repository, "tags/" + tagName, token); } - + /** + * Get a public repository's release by the tag name . + * + * @param owner Repository's Owner + * @param repository Repository's Name + * @param tagName Release Tag Name + * @return {@link GithubRelease} + */ public static @Nullable GithubRelease getReleaseByTag(@NotNull String owner, @NotNull String repository, @NotNull String tagName) { return getReleaseByTag(owner, repository, tagName, null); } + /** + * Get a repository's latest release. + * + * @param owner Repository's Owner + * @param repository Repository's Name + * @param token OAuth Access Token + *
Necessary when this repository is private. + * @return {@link GithubRelease} + */ public static @Nullable GithubRelease getLatestRelease(@NotNull String owner, @NotNull String repository, @Nullable String token) { return getRelease(owner, repository, "latest", token); } + /** + * Get a public repository's latest release. + * + * @param owner Repository's Owner + * @param repository Repository's Name + * @return {@link GithubRelease} + */ public static @Nullable GithubRelease getLatestRelease(@NotNull String owner, @NotNull String repository) { return getLatestRelease(owner, repository, null); }