diff --git a/src/main/java/org/kohsuke/github/AbuseLimitHandler.java b/src/main/java/org/kohsuke/github/AbuseLimitHandler.java index a30969da8..44847c3c3 100644 --- a/src/main/java/org/kohsuke/github/AbuseLimitHandler.java +++ b/src/main/java/org/kohsuke/github/AbuseLimitHandler.java @@ -8,7 +8,7 @@ import java.net.HttpURLConnection; * Pluggable strategy to determine what to do when the API abuse limit is hit. * * @author Kohsuke Kawaguchi - * @see GitHubBuilder#withAbuseLimitHandler(AbuseLimitHandler) + * @see GitHubBuilder#withAbuseLimitHandler(AbuseLimitHandler) GitHubBuilder#withAbuseLimitHandler(AbuseLimitHandler) * @see documentation * @see RateLimitHandler */ @@ -21,7 +21,6 @@ public abstract class AbuseLimitHandler { * an exception. If this method returns normally, another request will be attempted. For that to make sense, the * implementation needs to wait for some time. * - * @see API documentation from GitHub * @param e * Exception from Java I/O layer. If you decide to fail the processing, you can throw this exception (or * wrap this exception into another exception and throw it). @@ -29,6 +28,7 @@ public abstract class AbuseLimitHandler { * Connection that resulted in an error. Useful for accessing other response headers. * @throws IOException * on failure + * @see API documentation from GitHub */ public abstract void onError(IOException e, HttpURLConnection uc) throws IOException; diff --git a/src/main/java/org/kohsuke/github/GHApp.java b/src/main/java/org/kohsuke/github/GHApp.java index e1386e72f..6c587ce08 100644 --- a/src/main/java/org/kohsuke/github/GHApp.java +++ b/src/main/java/org/kohsuke/github/GHApp.java @@ -13,10 +13,8 @@ import static org.kohsuke.github.Previews.MACHINE_MAN; * A Github App. * * @author Paulo Miguel Almeida - * - * @see GitHub#getApp() + * @see GitHub#getApp() GitHub#getApp() */ - public class GHApp extends GHObject { private GitHub root; @@ -32,50 +30,116 @@ public class GHApp extends GHObject { @JsonProperty("html_url") private String htmlUrl; + /** + * Gets owner. + * + * @return the owner + */ public GHUser getOwner() { return owner; } + /** + * Sets owner. + * + * @param owner + * the owner + */ public void setOwner(GHUser owner) { this.owner = owner; } + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } + /** + * Sets name. + * + * @param name + * the name + */ public void setName(String name) { this.name = name; } + /** + * Gets description. + * + * @return the description + */ public String getDescription() { return description; } + /** + * Sets description. + * + * @param description + * the description + */ public void setDescription(String description) { this.description = description; } + /** + * Gets external url. + * + * @return the external url + */ public String getExternalUrl() { return externalUrl; } + /** + * Sets external url. + * + * @param externalUrl + * the external url + */ public void setExternalUrl(String externalUrl) { this.externalUrl = externalUrl; } + /** + * Gets events. + * + * @return the events + */ public List getEvents() { return events; } + /** + * Sets events. + * + * @param events + * the events + */ public void setEvents(List events) { this.events = events; } + /** + * Gets installations count. + * + * @return the installations count + */ public long getInstallationsCount() { return installationsCount; } + /** + * Sets installations count. + * + * @param installationsCount + * the installations count + */ public void setInstallationsCount(long installationsCount) { this.installationsCount = installationsCount; } @@ -84,10 +148,21 @@ public class GHApp extends GHObject { return GitHub.parseURL(htmlUrl); } + /** + * Gets permissions. + * + * @return the permissions + */ public Map getPermissions() { return permissions; } + /** + * Sets permissions. + * + * @param permissions + * the permissions + */ public void setPermissions(Map permissions) { this.permissions = permissions; } diff --git a/src/main/java/org/kohsuke/github/GHAppCreateTokenBuilder.java b/src/main/java/org/kohsuke/github/GHAppCreateTokenBuilder.java index e677e634c..4570cae5b 100644 --- a/src/main/java/org/kohsuke/github/GHAppCreateTokenBuilder.java +++ b/src/main/java/org/kohsuke/github/GHAppCreateTokenBuilder.java @@ -10,8 +10,7 @@ import static org.kohsuke.github.Previews.MACHINE_MAN; * Creates a access token for a GitHub App Installation * * @author Paulo Miguel Almeida - * - * @see GHAppInstallation#createToken(Map) + * @see GHAppInstallation#createToken(Map) GHAppInstallation#createToken(Map) */ public class GHAppCreateTokenBuilder { private final GitHub root; @@ -34,7 +33,6 @@ public class GHAppCreateTokenBuilder { * * @param repositoryIds * Array containing the repositories Ids - * * @return a GHAppCreateTokenBuilder */ @Preview @@ -46,9 +44,9 @@ public class GHAppCreateTokenBuilder { /** * Creates an app token with all the parameters. - * + *

* You must use a JWT to access this endpoint. - * + * * @return a GHAppInstallationToken * @throws IOException * on error diff --git a/src/main/java/org/kohsuke/github/GHAppInstallation.java b/src/main/java/org/kohsuke/github/GHAppInstallation.java index 96e2633c0..a9f2043c3 100644 --- a/src/main/java/org/kohsuke/github/GHAppInstallation.java +++ b/src/main/java/org/kohsuke/github/GHAppInstallation.java @@ -13,14 +13,12 @@ import static org.kohsuke.github.Previews.GAMBIT; * A Github App Installation. * * @author Paulo Miguel Almeida - * - * @see GHApp#listInstallations() - * @see GHApp#getInstallationById(long) - * @see GHApp#getInstallationByOrganization(String) - * @see GHApp#getInstallationByRepository(String, String) - * @see GHApp#getInstallationByUser(String) + * @see GHApp#listInstallations() GHApp#listInstallations() + * @see GHApp#getInstallationById(long) GHApp#getInstallationById(long) + * @see GHApp#getInstallationByOrganization(String) GHApp#getInstallationByOrganization(String) + * @see GHApp#getInstallationByRepository(String, String) GHApp#getInstallationByRepository(String, String) + * @see GHApp#getInstallationByUser(String) GHApp#getInstallationByUser(String) */ - public class GHAppInstallation extends GHObject { private GitHub root; private GHUser account; @@ -47,90 +45,211 @@ public class GHAppInstallation extends GHObject { return GitHub.parseURL(htmlUrl); } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Sets root. + * + * @param root + * the root + */ public void setRoot(GitHub root) { this.root = root; } + /** + * Gets account. + * + * @return the account + */ public GHUser getAccount() { return account; } + /** + * Sets account. + * + * @param account + * the account + */ public void setAccount(GHUser account) { this.account = account; } + /** + * Gets access token url. + * + * @return the access token url + */ public String getAccessTokenUrl() { return accessTokenUrl; } + /** + * Sets access token url. + * + * @param accessTokenUrl + * the access token url + */ public void setAccessTokenUrl(String accessTokenUrl) { this.accessTokenUrl = accessTokenUrl; } + /** + * Gets repositories url. + * + * @return the repositories url + */ public String getRepositoriesUrl() { return repositoriesUrl; } + /** + * Sets repositories url. + * + * @param repositoriesUrl + * the repositories url + */ public void setRepositoriesUrl(String repositoriesUrl) { this.repositoriesUrl = repositoriesUrl; } + /** + * Gets app id. + * + * @return the app id + */ public long getAppId() { return appId; } + /** + * Sets app id. + * + * @param appId + * the app id + */ public void setAppId(long appId) { this.appId = appId; } + /** + * Gets target id. + * + * @return the target id + */ public long getTargetId() { return targetId; } + /** + * Sets target id. + * + * @param targetId + * the target id + */ public void setTargetId(long targetId) { this.targetId = targetId; } + /** + * Gets target type. + * + * @return the target type + */ public GHTargetType getTargetType() { return targetType; } + /** + * Sets target type. + * + * @param targetType + * the target type + */ public void setTargetType(GHTargetType targetType) { this.targetType = targetType; } + /** + * Gets permissions. + * + * @return the permissions + */ public Map getPermissions() { return permissions; } + /** + * Sets permissions. + * + * @param permissions + * the permissions + */ public void setPermissions(Map permissions) { this.permissions = permissions; } + /** + * Gets events. + * + * @return the events + */ public List getEvents() { return events; } + /** + * Sets events. + * + * @param events + * the events + */ public void setEvents(List events) { this.events = events; } + /** + * Gets single file name. + * + * @return the single file name + */ public String getSingleFileName() { return singleFileName; } + /** + * Sets single file name. + * + * @param singleFileName + * the single file name + */ public void setSingleFileName(String singleFileName) { this.singleFileName = singleFileName; } + /** + * Gets repository selection. + * + * @return the repository selection + */ public GHRepositorySelection getRepositorySelection() { return repositorySelection; } + /** + * Sets repository selection. + * + * @param repositorySelection + * the repository selection + */ public void setRepositorySelection(GHRepositorySelection repositorySelection) { this.repositorySelection = repositorySelection; } @@ -142,7 +261,7 @@ public class GHAppInstallation extends GHObject { /** * Delete a Github App installation - * + *

* You must use a JWT to access this endpoint. * * @throws IOException diff --git a/src/main/java/org/kohsuke/github/GHAppInstallationToken.java b/src/main/java/org/kohsuke/github/GHAppInstallationToken.java index 992e7ee34..61e5b54e9 100644 --- a/src/main/java/org/kohsuke/github/GHAppInstallationToken.java +++ b/src/main/java/org/kohsuke/github/GHAppInstallationToken.java @@ -13,10 +13,8 @@ import java.util.Map; * A Github App Installation Token. * * @author Paulo Miguel Almeida - * - * @see GHAppInstallation#createToken(Map) + * @see GHAppInstallation#createToken(Map) GHAppInstallation#createToken(Map) */ - public class GHAppInstallationToken { private GitHub root; @@ -27,47 +25,104 @@ public class GHAppInstallationToken { @JsonProperty("repository_selection") private GHRepositorySelection repositorySelection; + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Sets root. + * + * @param root + * the root + */ public void setRoot(GitHub root) { this.root = root; } + /** + * Gets permissions. + * + * @return the permissions + */ public Map getPermissions() { return permissions; } + /** + * Sets permissions. + * + * @param permissions + * the permissions + */ public void setPermissions(Map permissions) { this.permissions = permissions; } + /** + * Gets token. + * + * @return the token + */ public String getToken() { return token; } + /** + * Sets token. + * + * @param token + * the token + */ public void setToken(String token) { this.token = token; } + /** + * Gets repositories. + * + * @return the repositories + */ public List getRepositories() { return repositories; } + /** + * Sets repositories. + * + * @param repositories + * the repositories + */ public void setRepositories(List repositories) { this.repositories = repositories; } + /** + * Gets repository selection. + * + * @return the repository selection + */ public GHRepositorySelection getRepositorySelection() { return repositorySelection; } + /** + * Sets repository selection. + * + * @param repositorySelection + * the repository selection + */ public void setRepositorySelection(GHRepositorySelection repositorySelection) { this.repositorySelection = repositorySelection; } /** + * Gets expires at. + * * @return date when this token expires * @throws IOException * on error diff --git a/src/main/java/org/kohsuke/github/GHAsset.java b/src/main/java/org/kohsuke/github/GHAsset.java index 877d85fbc..cd7001d25 100644 --- a/src/main/java/org/kohsuke/github/GHAsset.java +++ b/src/main/java/org/kohsuke/github/GHAsset.java @@ -6,7 +6,7 @@ import java.net.URL; /** * Asset in a release. * - * @see GHRelease#getAssets() + * @see GHRelease#getAssets() GHRelease#getAssets() */ public class GHAsset extends GHObject { GitHub root; @@ -19,44 +19,100 @@ public class GHAsset extends GHObject { private long download_count; private String browser_download_url; + /** + * Gets content type. + * + * @return the content type + */ public String getContentType() { return content_type; } + /** + * Sets content type. + * + * @param contentType + * the content type + * @throws IOException + * the io exception + */ public void setContentType(String contentType) throws IOException { edit("content_type", contentType); this.content_type = contentType; } + /** + * Gets download count. + * + * @return the download count + */ public long getDownloadCount() { return download_count; } + /** + * Gets label. + * + * @return the label + */ public String getLabel() { return label; } + /** + * Sets label. + * + * @param label + * the label + * @throws IOException + * the io exception + */ public void setLabel(String label) throws IOException { edit("label", label); this.label = label; } + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } + /** + * Gets owner. + * + * @return the owner + */ public GHRepository getOwner() { return owner; } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Gets size. + * + * @return the size + */ public long getSize() { return size; } + /** + * Gets state. + * + * @return the state + */ public String getState() { return state; } @@ -69,6 +125,11 @@ public class GHAsset extends GHObject { return null; } + /** + * Gets browser download url. + * + * @return the browser download url + */ public String getBrowserDownloadUrl() { return browser_download_url; } @@ -77,6 +138,12 @@ public class GHAsset extends GHObject { new Requester(root)._with(key, value).method("PATCH").to(getApiRoute()); } + /** + * Delete. + * + * @throws IOException + * the io exception + */ public void delete() throws IOException { new Requester(root).method("DELETE").to(getApiRoute()); } @@ -91,6 +158,15 @@ public class GHAsset extends GHObject { return this; } + /** + * Wrap gh asset [ ]. + * + * @param assets + * the assets + * @param release + * the release + * @return the gh asset [ ] + */ public static GHAsset[] wrap(GHAsset[] assets, GHRelease release) { for (GHAsset aTo : assets) { aTo.wrap(release); diff --git a/src/main/java/org/kohsuke/github/GHAuthorization.java b/src/main/java/org/kohsuke/github/GHAuthorization.java index 033beda0a..1cc469c98 100644 --- a/src/main/java/org/kohsuke/github/GHAuthorization.java +++ b/src/main/java/org/kohsuke/github/GHAuthorization.java @@ -10,7 +10,7 @@ import java.util.List; * Generated OAuth token * * @author janinko - * @see GitHub#createToken(Collection, String, String) + * @see GitHub#createToken(Collection, String, String) GitHub#createToken(Collection, String, String) * @see API documentation */ public class GHAuthorization extends GHObject { @@ -45,34 +45,74 @@ public class GHAuthorization extends GHObject { // TODO add some user class for https://developer.github.com/v3/oauth_authorizations/#check-an-authorization ? // private GHUser user; + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Gets scopes. + * + * @return the scopes + */ public List getScopes() { return scopes; } + /** + * Gets token. + * + * @return the token + */ public String getToken() { return token; } + /** + * Gets token last eight. + * + * @return the token last eight + */ public String getTokenLastEight() { return token_last_eight; } + /** + * Gets hashed token. + * + * @return the hashed token + */ public String getHashedToken() { return hashed_token; } + /** + * Gets app url. + * + * @return the app url + */ public URL getAppUrl() { return GitHub.parseURL(app.url); } + /** + * Gets app name. + * + * @return the app name + */ public String getAppName() { return app.name; } + /** + * Gets api url. + * + * @return the api url + */ @SuppressFBWarnings(value = "NM_CONFUSING", justification = "It's a part of the library API, cannot be changed") public URL getApiURL() { return GitHub.parseURL(url); @@ -86,14 +126,29 @@ public class GHAuthorization extends GHObject { return null; } + /** + * Gets note. + * + * @return the note + */ public String getNote() { return note; } + /** + * Gets note url. + * + * @return the note url + */ public URL getNoteUrl() { return GitHub.parseURL(note_url); } + /** + * Gets fingerprint. + * + * @return the fingerprint + */ public String getFingerprint() { return fingerprint; } diff --git a/src/main/java/org/kohsuke/github/GHBlob.java b/src/main/java/org/kohsuke/github/GHBlob.java index d881fd848..f2f80d8dc 100644 --- a/src/main/java/org/kohsuke/github/GHBlob.java +++ b/src/main/java/org/kohsuke/github/GHBlob.java @@ -8,10 +8,12 @@ import java.io.UnsupportedEncodingException; import java.net.URL; /** + * The type GHBlob. + * * @author Kanstantsin Shautsou * @author Kohsuke Kawaguchi - * @see GHTreeEntry#asBlob() - * @see GHRepository#getBlob(String) + * @see GHTreeEntry#asBlob() GHTreeEntry#asBlob() + * @see GHRepository#getBlob(String) GHRepository#getBlob(String) * @see Get a blob */ public class GHBlob { @@ -19,28 +21,44 @@ public class GHBlob { private long size; /** + * Gets url. + * * @return API URL of this blob. */ public URL getUrl() { return GitHub.parseURL(url); } + /** + * Gets sha. + * + * @return the sha + */ public String getSha() { return sha; } /** + * Gets size. + * * @return Number of bytes in this blob. */ public long getSize() { return size; } + /** + * Gets encoding. + * + * @return the encoding + */ public String getEncoding() { return encoding; } /** + * Gets content. + * * @return Encoded content. You probably want {@link #read()} */ public String getContent() { @@ -48,6 +66,8 @@ public class GHBlob { } /** + * Read input stream. + * * @return the actual bytes of the blob. */ public InputStream read() { diff --git a/src/main/java/org/kohsuke/github/GHBlobBuilder.java b/src/main/java/org/kohsuke/github/GHBlobBuilder.java index 9397fe89b..6326525dc 100644 --- a/src/main/java/org/kohsuke/github/GHBlobBuilder.java +++ b/src/main/java/org/kohsuke/github/GHBlobBuilder.java @@ -49,7 +49,7 @@ public class GHBlobBuilder { /** * Creates a blob based on the parameters specified thus far. - * + * * @return a GHBlob * @throws IOException * if the blob cannot be created. diff --git a/src/main/java/org/kohsuke/github/GHBranch.java b/src/main/java/org/kohsuke/github/GHBranch.java index 64c62c9d2..19df9ed04 100644 --- a/src/main/java/org/kohsuke/github/GHBranch.java +++ b/src/main/java/org/kohsuke/github/GHBranch.java @@ -26,6 +26,9 @@ public class GHBranch { private boolean protection; private String protection_url; + /** + * The type Commit. + */ public static class Commit { String sha; @@ -33,22 +36,36 @@ public class GHBranch { String url; } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } /** + * Gets owner. + * * @return the repository that this branch is in. */ public GHRepository getOwner() { return owner; } + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } /** + * Is protected boolean. + * * @return true if the push to this branch is restricted via branch protection. */ @Preview @@ -58,6 +75,8 @@ public class GHBranch { } /** + * Gets protection url. + * * @return API URL that deals with the protection of this branch. */ @Preview @@ -66,11 +85,20 @@ public class GHBranch { return GitHub.parseURL(protection_url); } + /** + * Gets protection. + * + * @return the protection + * @throws IOException + * the io exception + */ public GHBranchProtection getProtection() throws IOException { return root.retrieve().to(protection_url, GHBranchProtection.class).wrap(this); } /** + * Gets sha 1. + * * @return The SHA1 of the commit that this branch currently points to. */ public String getSHA1() { @@ -91,7 +119,7 @@ public class GHBranch { * Enables branch protection to control what commit statuses are required to push. * * @return GHBranchProtectionBuilder for enabling protection - * @see GHCommitStatus#getContext() + * @see GHCommitStatus#getContext() GHCommitStatus#getContext() */ @Preview @Deprecated @@ -99,6 +127,16 @@ public class GHBranch { return new GHBranchProtectionBuilder(this); } + /** + * Enable protection. + * + * @param level + * the level + * @param contexts + * the contexts + * @throws IOException + * the io exception + */ // backward compatibility with previous signature @Deprecated public void enableProtection(EnforcementLevel level, Collection contexts) throws IOException { diff --git a/src/main/java/org/kohsuke/github/GHBranchProtection.java b/src/main/java/org/kohsuke/github/GHBranchProtection.java index 41f5dda10..e9b8b1861 100644 --- a/src/main/java/org/kohsuke/github/GHBranchProtection.java +++ b/src/main/java/org/kohsuke/github/GHBranchProtection.java @@ -8,6 +8,9 @@ import static org.kohsuke.github.Previews.ZZZAX; import java.io.IOException; import java.util.Collection; +/** + * The type GHBranchProtection. + */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD", "URF_UNREAD_FIELD" }, justification = "JSON API") public class GHBranchProtection { @@ -30,40 +33,84 @@ public class GHBranchProtection { @JsonProperty private String url; + /** + * Enabled signed commits. + * + * @throws IOException + * the io exception + */ @Preview @Deprecated public void enabledSignedCommits() throws IOException { requester().method("POST").to(url + REQUIRE_SIGNATURES_URI, RequiredSignatures.class); } + /** + * Disable signed commits. + * + * @throws IOException + * the io exception + */ @Preview @Deprecated public void disableSignedCommits() throws IOException { requester().method("DELETE").to(url + REQUIRE_SIGNATURES_URI); } + /** + * Gets enforce admins. + * + * @return the enforce admins + */ public EnforceAdmins getEnforceAdmins() { return enforceAdmins; } + /** + * Gets required reviews. + * + * @return the required reviews + */ public RequiredReviews getRequiredReviews() { return requiredReviews; } + /** + * Gets required signatures. + * + * @return the required signatures + * @throws IOException + * the io exception + */ @Preview @Deprecated public boolean getRequiredSignatures() throws IOException { return requester().method("GET").to(url + REQUIRE_SIGNATURES_URI, RequiredSignatures.class).enabled; } + /** + * Gets required status checks. + * + * @return the required status checks + */ public RequiredStatusChecks getRequiredStatusChecks() { return requiredStatusChecks; } + /** + * Gets restrictions. + * + * @return the restrictions + */ public Restrictions getRestrictions() { return restrictions; } + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } @@ -77,6 +124,9 @@ public class GHBranchProtection { return new Requester(root).withPreview(ZZZAX); } + /** + * The type EnforceAdmins. + */ public static class EnforceAdmins { @JsonProperty private boolean enabled; @@ -84,15 +134,28 @@ public class GHBranchProtection { @JsonProperty private String url; + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Is enabled boolean. + * + * @return the boolean + */ public boolean isEnabled() { return enabled; } } + /** + * The type RequiredReviews. + */ public static class RequiredReviews { @JsonProperty("dismissal_restrictions") private Restrictions dismissalRestriction; @@ -109,22 +172,47 @@ public class GHBranchProtection { @JsonProperty private String url; + /** + * Gets dismissal restrictions. + * + * @return the dismissal restrictions + */ public Restrictions getDismissalRestrictions() { return dismissalRestriction; } + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Is dismiss stale reviews boolean. + * + * @return the boolean + */ public boolean isDismissStaleReviews() { return dismissStaleReviews; } + /** + * Is require code owner reviews boolean. + * + * @return the boolean + */ public boolean isRequireCodeOwnerReviews() { return requireCodeOwnerReviews; } + /** + * Gets required reviewers. + * + * @return the required reviewers + */ public int getRequiredReviewers() { return requiredReviewers; } @@ -137,15 +225,28 @@ public class GHBranchProtection { @JsonProperty private String url; + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Is enabled boolean. + * + * @return the boolean + */ public boolean isEnabled() { return enabled; } } + /** + * The type RequiredStatusChecks. + */ public static class RequiredStatusChecks { @JsonProperty private Collection contexts; @@ -156,19 +257,37 @@ public class GHBranchProtection { @JsonProperty private String url; + /** + * Gets contexts. + * + * @return the contexts + */ public Collection getContexts() { return contexts; } + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Is requires branch up to date boolean. + * + * @return the boolean + */ public boolean isRequiresBranchUpToDate() { return strict; } } + /** + * The type Restrictions. + */ public static class Restrictions { @JsonProperty private Collection teams; @@ -185,22 +304,47 @@ public class GHBranchProtection { @JsonProperty("users_url") private String usersUrl; + /** + * Gets teams. + * + * @return the teams + */ public Collection getTeams() { return teams; } + /** + * Gets teams url. + * + * @return the teams url + */ public String getTeamsUrl() { return teamsUrl; } + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Gets users. + * + * @return the users + */ public Collection getUsers() { return users; } + /** + * Gets users url. + * + * @return the users url + */ public String getUsersUrl() { return usersUrl; } diff --git a/src/main/java/org/kohsuke/github/GHBranchProtectionBuilder.java b/src/main/java/org/kohsuke/github/GHBranchProtectionBuilder.java index fd819d59d..33db4aa93 100644 --- a/src/main/java/org/kohsuke/github/GHBranchProtectionBuilder.java +++ b/src/main/java/org/kohsuke/github/GHBranchProtectionBuilder.java @@ -17,7 +17,7 @@ import static org.kohsuke.github.Previews.*; /** * Builder to configure the branch protection settings. * - * @see GHBranch#enableProtection() + * @see GHBranch#enableProtection() GHBranch#enableProtection() */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD", "URF_UNREAD_FIELD" }, justification = "JSON API") @@ -33,25 +33,58 @@ public class GHBranchProtectionBuilder { this.branch = branch; } + /** + * Add required checks gh branch protection builder. + * + * @param checks + * the checks + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder addRequiredChecks(Collection checks) { getStatusChecks().contexts.addAll(checks); return this; } + /** + * Add required checks gh branch protection builder. + * + * @param checks + * the checks + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder addRequiredChecks(String... checks) { addRequiredChecks(Arrays.asList(checks)); return this; } + /** + * Dismiss stale reviews gh branch protection builder. + * + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder dismissStaleReviews() { return dismissStaleReviews(true); } + /** + * Dismiss stale reviews gh branch protection builder. + * + * @param v + * the v + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder dismissStaleReviews(boolean v) { getPrReviews().put("dismiss_stale_reviews", v); return this; } + /** + * Enable gh branch protection. + * + * @return the gh branch protection + * @throws IOException + * the io exception + */ public GHBranchProtection enable() throws IOException { return requester().method("PUT").withNullable("required_status_checks", statusChecks) .withNullable("required_pull_request_reviews", prReviews).withNullable("restrictions", restrictions) @@ -59,43 +92,96 @@ public class GHBranchProtectionBuilder { .to(branch.getProtectionUrl().toString(), GHBranchProtection.class).wrap(branch); } + /** + * Include admins gh branch protection builder. + * + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder includeAdmins() { return includeAdmins(true); } + /** + * Include admins gh branch protection builder. + * + * @param v + * the v + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder includeAdmins(boolean v) { enforceAdmins = v; return this; } + /** + * Required reviewers gh branch protection builder. + * + * @param v + * the v + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder requiredReviewers(int v) { getPrReviews().put("required_approving_review_count", v); return this; } + /** + * Require branch is up to date gh branch protection builder. + * + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder requireBranchIsUpToDate() { return requireBranchIsUpToDate(true); } + /** + * Require branch is up to date gh branch protection builder. + * + * @param v + * the v + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder requireBranchIsUpToDate(boolean v) { getStatusChecks().strict = v; return this; } + /** + * Require code own reviews gh branch protection builder. + * + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder requireCodeOwnReviews() { return requireCodeOwnReviews(true); } + /** + * Require code own reviews gh branch protection builder. + * + * @param v + * the v + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder requireCodeOwnReviews(boolean v) { getPrReviews().put("require_code_owner_reviews", v); return this; } + /** + * Require reviews gh branch protection builder. + * + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder requireReviews() { getPrReviews(); return this; } + /** + * Restrict review dismissals gh branch protection builder. + * + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder restrictReviewDismissals() { getPrReviews(); @@ -106,11 +192,23 @@ public class GHBranchProtectionBuilder { return this; } + /** + * Restrict push access gh branch protection builder. + * + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder restrictPushAccess() { getRestrictions(); return this; } + /** + * Team push access gh branch protection builder. + * + * @param teams + * the teams + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder teamPushAccess(Collection teams) { for (GHTeam team : teams) { teamPushAccess(team); @@ -118,6 +216,13 @@ public class GHBranchProtectionBuilder { return this; } + /** + * Team push access gh branch protection builder. + * + * @param teams + * the teams + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder teamPushAccess(GHTeam... teams) { for (GHTeam team : teams) { getRestrictions().teams.add(team.getSlug()); @@ -125,6 +230,13 @@ public class GHBranchProtectionBuilder { return this; } + /** + * Team review dismissals gh branch protection builder. + * + * @param teams + * the teams + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder teamReviewDismissals(Collection teams) { for (GHTeam team : teams) { teamReviewDismissals(team); @@ -132,6 +244,13 @@ public class GHBranchProtectionBuilder { return this; } + /** + * Team review dismissals gh branch protection builder. + * + * @param teams + * the teams + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder teamReviewDismissals(GHTeam... teams) { for (GHTeam team : teams) { addReviewRestriction(team.getSlug(), true); @@ -139,6 +258,13 @@ public class GHBranchProtectionBuilder { return this; } + /** + * User push access gh branch protection builder. + * + * @param users + * the users + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder userPushAccess(Collection users) { for (GHUser user : users) { userPushAccess(user); @@ -146,6 +272,13 @@ public class GHBranchProtectionBuilder { return this; } + /** + * User push access gh branch protection builder. + * + * @param users + * the users + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder userPushAccess(GHUser... users) { for (GHUser user : users) { getRestrictions().users.add(user.getLogin()); @@ -153,6 +286,13 @@ public class GHBranchProtectionBuilder { return this; } + /** + * User review dismissals gh branch protection builder. + * + * @param users + * the users + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder userReviewDismissals(Collection users) { for (GHUser team : users) { userReviewDismissals(team); @@ -160,6 +300,13 @@ public class GHBranchProtectionBuilder { return this; } + /** + * User review dismissals gh branch protection builder. + * + * @param users + * the users + * @return the gh branch protection builder + */ public GHBranchProtectionBuilder userReviewDismissals(GHUser... users) { for (GHUser user : users) { addReviewRestriction(user.getLogin(), false); diff --git a/src/main/java/org/kohsuke/github/GHCommit.java b/src/main/java/org/kohsuke/github/GHCommit.java index f8d56d66e..5f381bfc9 100644 --- a/src/main/java/org/kohsuke/github/GHCommit.java +++ b/src/main/java/org/kohsuke/github/GHCommit.java @@ -15,8 +15,8 @@ import java.util.List; * A commit in a repository. * * @author Kohsuke Kawaguchi - * @see GHRepository#getCommit(String) - * @see GHCommitComment#getCommit() + * @see GHRepository#getCommit(String) GHRepository#getCommit(String) + * @see GHCommitComment#getCommit() GHCommitComment#getCommit() */ @SuppressFBWarnings(value = { "NP_UNWRITTEN_FIELD", "UWF_UNWRITTEN_FIELD" }, justification = "JSON API") public class GHCommit { @@ -43,43 +43,75 @@ public class GHCommit { private Tree tree; + /** + * Gets author. + * + * @return the author + */ @WithBridgeMethods(value = GHAuthor.class, castRequired = true) public GitUser getAuthor() { return author; } + /** + * Gets authored date. + * + * @return the authored date + */ public Date getAuthoredDate() { return GitHub.parseDate(author.date); } + /** + * Gets committer. + * + * @return the committer + */ @WithBridgeMethods(value = GHAuthor.class, castRequired = true) public GitUser getCommitter() { return committer; } + /** + * Gets commit date. + * + * @return the commit date + */ public Date getCommitDate() { return GitHub.parseDate(committer.date); } /** + * Gets message. + * * @return Commit message. */ public String getMessage() { return message; } + /** + * Gets comment count. + * + * @return the comment count + */ public int getCommentCount() { return comment_count; } } /** + * The type GHAuthor. + * * @deprecated Use {@link GitUser} instead. */ public static class GHAuthor extends GitUser { private String date; } + /** + * The type Stats. + */ public static class Stats { int total, additions, deletions; } @@ -95,6 +127,8 @@ public class GHCommit { String filename, previous_filename; /** + * Gets lines changed. + * * @return Number of lines added + removed. */ public int getLinesChanged() { @@ -102,6 +136,8 @@ public class GHCommit { } /** + * Gets lines added. + * * @return Number of lines added. */ public int getLinesAdded() { @@ -109,6 +145,8 @@ public class GHCommit { } /** + * Gets lines deleted. + * * @return Number of lines removed. */ public int getLinesDeleted() { @@ -116,6 +154,8 @@ public class GHCommit { } /** + * Gets status. + * * @return "modified", "added", or "removed" */ public String getStatus() { @@ -123,6 +163,8 @@ public class GHCommit { } /** + * Gets file name. + * * @return Full path in the repository. */ @SuppressFBWarnings(value = "NM_CONFUSING", justification = "It's a part of the library's API and cannot be renamed") @@ -131,6 +173,8 @@ public class GHCommit { } /** + * Gets previous filename. + * * @return Previous path, in case file has moved. */ public String getPreviousFilename() { @@ -138,6 +182,8 @@ public class GHCommit { } /** + * Gets patch. + * * @return The actual change. */ public String getPatch() { @@ -145,6 +191,8 @@ public class GHCommit { } /** + * Gets raw url. + * * @return URL like * 'https://raw.github.com/jenkinsci/jenkins/4eb17c197dfdcf8ef7ff87eb160f24f6a20b7f0e/core/pom.xml' that * resolves to the actual content of the file. @@ -154,6 +202,8 @@ public class GHCommit { } /** + * Gets blob url. + * * @return URL like * 'https://github.com/jenkinsci/jenkins/blob/1182e2ebb1734d0653142bd422ad33c21437f7cf/core/pom.xml' * that resolves to the HTML page that describes this file. @@ -163,13 +213,18 @@ public class GHCommit { } /** - * @return [0-9a-f]{40} SHA1 checksum. + * Gets sha. + * + * @return [0 -9a-f]{40} SHA1 checksum. */ public String getSha() { return sha; } } + /** + * The type Parent. + */ public static class Parent { @SuppressFBWarnings(value = "UUF_UNUSED_FIELD", justification = "We don't provide it in API now") String url; @@ -192,6 +247,13 @@ public class GHCommit { List parents; User author, committer; + /** + * Gets commit short info. + * + * @return the commit short info + * @throws IOException + * the io exception + */ public ShortInfo getCommitShortInfo() throws IOException { if (commit == null) populate(); @@ -199,6 +261,8 @@ public class GHCommit { } /** + * Gets owner. + * * @return the repository that contains the commit. */ public GHRepository getOwner() { @@ -206,6 +270,8 @@ public class GHCommit { } /** + * Gets lines changed. + * * @return the number of lines added + removed. * @throws IOException * if the field was not populated and refresh fails @@ -216,6 +282,8 @@ public class GHCommit { } /** + * Gets lines added. + * * @return Number of lines added. * @throws IOException * if the field was not populated and refresh fails @@ -226,6 +294,8 @@ public class GHCommit { } /** + * Gets lines deleted. + * * @return Number of lines removed. * @throws IOException * if the field was not populated and refresh fails @@ -247,6 +317,8 @@ public class GHCommit { } /** + * Gets html url. + * * @return URL of this commit like * "https://github.com/kohsuke/sandbox-ant/commit/8ae38db0ea5837313ab5f39d43a6f73de3bd9000" */ @@ -255,7 +327,9 @@ public class GHCommit { } /** - * @return [0-9a-f]{40} SHA1 checksum. + * Gets sha 1. + * + * @return [0 -9a-f]{40} SHA1 checksum. */ public String getSHA1() { return sha; @@ -274,6 +348,8 @@ public class GHCommit { } /** + * Gets parent sha 1 s. + * * @return SHA1 of parent commit objects. */ public List getParentSHA1s() { @@ -306,13 +382,20 @@ public class GHCommit { return r; } + /** + * Gets author. + * + * @return the author + * @throws IOException + * the io exception + */ public GHUser getAuthor() throws IOException { return resolveUser(author); } /** * Gets the date the change was authored on. - * + * * @return the date the change was authored on. * @throws IOException * if the information was not already fetched and an attempt at fetching the information failed. @@ -321,6 +404,13 @@ public class GHCommit { return getCommitShortInfo().getAuthoredDate(); } + /** + * Gets committer. + * + * @return the committer + * @throws IOException + * the io exception + */ public GHUser getCommitter() throws IOException { return resolveUser(committer); } @@ -343,6 +433,8 @@ public class GHCommit { } /** + * List comments paged iterable. + * * @return {@link PagedIterable} with all the commit comments in this repository. */ public PagedIterable listComments() { @@ -353,7 +445,7 @@ public class GHCommit { /** * Creates a commit comment. - * + *

* I'm not sure how path/line/position parameters interact with each other. * * @param body @@ -364,7 +456,6 @@ public class GHCommit { * target line for comment * @param position * position on line - * * @return created GHCommitComment * @throws IOException * if comment is not created @@ -377,11 +468,22 @@ public class GHCommit { return r.wrap(owner); } + /** + * Create comment gh commit comment. + * + * @param body + * the body + * @return the gh commit comment + * @throws IOException + * the io exception + */ public GHCommitComment createComment(String body) throws IOException { return createComment(body, null, null, null); } /** + * List statuses paged iterable. + * * @return status of this commit, newer ones first. * @throws IOException * if statuses cannot be read @@ -391,6 +493,8 @@ public class GHCommit { } /** + * Gets last status. + * * @return the last status of this commit, which is what gets shown in the UI. * @throws IOException * on error diff --git a/src/main/java/org/kohsuke/github/GHCommitBuilder.java b/src/main/java/org/kohsuke/github/GHCommitBuilder.java index 01a35fa16..0b8c0fff2 100644 --- a/src/main/java/org/kohsuke/github/GHCommitBuilder.java +++ b/src/main/java/org/kohsuke/github/GHCommitBuilder.java @@ -38,8 +38,11 @@ public class GHCommitBuilder { } /** + * Message gh commit builder. + * * @param message * the commit message + * @return the gh commit builder */ public GHCommitBuilder message(String message) { req.with("message", message); @@ -47,8 +50,11 @@ public class GHCommitBuilder { } /** + * Tree gh commit builder. + * * @param tree * the SHA of the tree object this commit points to + * @return the gh commit builder */ public GHCommitBuilder tree(String tree) { req.with("tree", tree); @@ -56,8 +62,11 @@ public class GHCommitBuilder { } /** + * Parent gh commit builder. + * * @param parent * the SHA of a parent commit. + * @return the gh commit builder */ public GHCommitBuilder parent(String parent) { parents.add(parent); @@ -66,6 +75,14 @@ public class GHCommitBuilder { /** * Configures the author of this commit. + * + * @param name + * the name + * @param email + * the email + * @param date + * the date + * @return the gh commit builder */ public GHCommitBuilder author(String name, String email, Date date) { req._with("author", new UserInfo(name, email, date)); @@ -74,6 +91,14 @@ public class GHCommitBuilder { /** * Configures the committer of this commit. + * + * @param name + * the name + * @param email + * the email + * @param date + * the date + * @return the gh commit builder */ public GHCommitBuilder committer(String name, String email, Date date) { req._with("committer", new UserInfo(name, email, date)); @@ -86,6 +111,10 @@ public class GHCommitBuilder { /** * Creates a blob based on the parameters specified thus far. + * + * @return the gh commit + * @throws IOException + * the io exception */ public GHCommit create() throws IOException { req._with("parents", parents); diff --git a/src/main/java/org/kohsuke/github/GHCommitComment.java b/src/main/java/org/kohsuke/github/GHCommitComment.java index 56eb9a93b..9ee1843a7 100644 --- a/src/main/java/org/kohsuke/github/GHCommitComment.java +++ b/src/main/java/org/kohsuke/github/GHCommitComment.java @@ -11,9 +11,10 @@ import static org.kohsuke.github.Previews.*; * A comment attached to a commit (or a specific line in a specific file of a commit.) * * @author Kohsuke Kawaguchi - * @see GHRepository#listCommitComments() - * @see GHCommit#listComments() - * @see GHCommit#createComment(String, String, Integer, Integer) + * @see GHRepository#listCommitComments() GHRepository#listCommitComments() + * @see GHCommit#listComments() GHCommit#listComments() + * @see GHCommit#createComment(String, String, Integer, Integer) GHCommit#createComment(String, String, Integer, + * Integer) */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD" }, justification = "JSON API") @@ -25,6 +26,11 @@ public class GHCommitComment extends GHObject implements Reactable { String path; GHUser user; // not fully populated. beware. + /** + * Gets owner. + * + * @return the owner + */ public GHRepository getOwner() { return owner; } @@ -38,12 +44,19 @@ public class GHCommitComment extends GHObject implements Reactable { return GitHub.parseURL(html_url); } + /** + * Gets sha 1. + * + * @return the sha 1 + */ public String getSHA1() { return commit_id; } /** * Commit comment in the GitHub flavored markdown format. + * + * @return the body */ public String getBody() { return body; @@ -52,6 +65,8 @@ public class GHCommitComment extends GHObject implements Reactable { /** * A commit comment can be on a specific line of a specific file, if so, this field points to a file. Otherwise * null. + * + * @return the path */ public String getPath() { return path; @@ -60,6 +75,8 @@ public class GHCommitComment extends GHObject implements Reactable { /** * A commit comment can be on a specific line of a specific file, if so, this field points to the line number in the * file. Otherwise -1. + * + * @return the line */ public int getLine() { return line != null ? line : -1; @@ -67,6 +84,10 @@ public class GHCommitComment extends GHObject implements Reactable { /** * Gets the user who put this comment. + * + * @return the user + * @throws IOException + * the io exception */ public GHUser getUser() throws IOException { return owner == null || owner.root.isOffline() ? user : owner.root.getUser(user.login); @@ -74,6 +95,10 @@ public class GHCommitComment extends GHObject implements Reactable { /** * Gets the commit to which this comment is associated with. + * + * @return the commit + * @throws IOException + * the io exception */ public GHCommit getCommit() throws IOException { return getOwner().getCommit(getSHA1()); @@ -81,6 +106,11 @@ public class GHCommitComment extends GHObject implements Reactable { /** * Updates the body of the commit message. + * + * @param body + * the body + * @throws IOException + * the io exception */ public void update(String body) throws IOException { new Requester(owner.root).with("body", body).method("PATCH").to(getApiTail(), GHCommitComment.class); @@ -103,6 +133,9 @@ public class GHCommitComment extends GHObject implements Reactable { /** * Deletes this comment. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { new Requester(owner.root).method("DELETE").to(getApiTail()); diff --git a/src/main/java/org/kohsuke/github/GHCommitPointer.java b/src/main/java/org/kohsuke/github/GHCommitPointer.java index 3f0fb3cc3..15ed6b936 100644 --- a/src/main/java/org/kohsuke/github/GHCommitPointer.java +++ b/src/main/java/org/kohsuke/github/GHCommitPointer.java @@ -37,6 +37,10 @@ public class GHCommitPointer { /** * This points to the user who owns the {@link #getRepository()}. + * + * @return the user + * @throws IOException + * the io exception */ public GHUser getUser() throws IOException { if (user != null) @@ -46,6 +50,8 @@ public class GHCommitPointer { /** * The repository that contains the commit. + * + * @return the repository */ public GHRepository getRepository() { return repo; @@ -53,6 +59,8 @@ public class GHCommitPointer { /** * Named ref to the commit. This appears to be a "short ref" that doesn't include "refs/heads/" portion. + * + * @return the ref */ public String getRef() { return ref; @@ -60,6 +68,8 @@ public class GHCommitPointer { /** * SHA1 of the commit. + * + * @return the sha */ public String getSha() { return sha; @@ -67,6 +77,8 @@ public class GHCommitPointer { /** * String that looks like "USERNAME:REF". + * + * @return the label */ public String getLabel() { return label; @@ -74,6 +86,10 @@ public class GHCommitPointer { /** * Obtains the commit that this pointer is referring to. + * + * @return the commit + * @throws IOException + * the io exception */ public GHCommit getCommit() throws IOException { return getRepository().getCommit(getSha()); diff --git a/src/main/java/org/kohsuke/github/GHCommitQueryBuilder.java b/src/main/java/org/kohsuke/github/GHCommitQueryBuilder.java index 32d1d964a..dc544b390 100644 --- a/src/main/java/org/kohsuke/github/GHCommitQueryBuilder.java +++ b/src/main/java/org/kohsuke/github/GHCommitQueryBuilder.java @@ -16,7 +16,7 @@ import java.util.Date; * * * @author Kohsuke Kawaguchi - * @see GHRepository#queryCommits() + * @see GHRepository#queryCommits() GHRepository#queryCommits() */ public class GHCommitQueryBuilder { private final Requester req; @@ -29,6 +29,10 @@ public class GHCommitQueryBuilder { /** * GItHub login or email address by which to filter by commit author. + * + * @param author + * the author + * @return the gh commit query builder */ public GHCommitQueryBuilder author(String author) { req.with("author", author); @@ -37,6 +41,10 @@ public class GHCommitQueryBuilder { /** * Only commits containing this file path will be returned. + * + * @param path + * the path + * @return the gh commit query builder */ public GHCommitQueryBuilder path(String path) { req.with("path", path); @@ -46,12 +54,22 @@ public class GHCommitQueryBuilder { /** * Specifies the SHA1 commit / tag / branch / etc to start listing commits from. * + * @param ref + * the ref + * @return the gh commit query builder */ public GHCommitQueryBuilder from(String ref) { req.with("sha", ref); return this; } + /** + * Page size gh commit query builder. + * + * @param pageSize + * the page size + * @return the gh commit query builder + */ public GHCommitQueryBuilder pageSize(int pageSize) { req.with("per_page", pageSize); return this; @@ -59,6 +77,10 @@ public class GHCommitQueryBuilder { /** * Only commits after this date will be returned + * + * @param dt + * the dt + * @return the gh commit query builder */ public GHCommitQueryBuilder since(Date dt) { req.with("since", GitHub.printDate(dt)); @@ -67,6 +89,10 @@ public class GHCommitQueryBuilder { /** * Only commits after this date will be returned + * + * @param timestamp + * the timestamp + * @return the gh commit query builder */ public GHCommitQueryBuilder since(long timestamp) { return since(new Date(timestamp)); @@ -74,6 +100,10 @@ public class GHCommitQueryBuilder { /** * Only commits before this date will be returned + * + * @param dt + * the dt + * @return the gh commit query builder */ public GHCommitQueryBuilder until(Date dt) { req.with("until", GitHub.printDate(dt)); @@ -82,6 +112,10 @@ public class GHCommitQueryBuilder { /** * Only commits before this date will be returned + * + * @param timestamp + * the timestamp + * @return the gh commit query builder */ public GHCommitQueryBuilder until(long timestamp) { return until(new Date(timestamp)); @@ -89,6 +123,8 @@ public class GHCommitQueryBuilder { /** * Lists up the commits with the criteria built so far. + * + * @return the paged iterable */ public PagedIterable list() { return req.asPagedIterable(repo.getApiTailUrl("commits"), GHCommit[].class, item -> item.wrapUp(repo)); diff --git a/src/main/java/org/kohsuke/github/GHCommitSearchBuilder.java b/src/main/java/org/kohsuke/github/GHCommitSearchBuilder.java index 5d75afbb3..b62bc2b1b 100644 --- a/src/main/java/org/kohsuke/github/GHCommitSearchBuilder.java +++ b/src/main/java/org/kohsuke/github/GHCommitSearchBuilder.java @@ -8,7 +8,7 @@ import java.io.IOException; * Search commits. * * @author Marc de Verdelhan - * @see GitHub#searchCommits() + * @see GitHub#searchCommits() GitHub#searchCommits() */ @Preview @Deprecated @@ -26,80 +26,209 @@ public class GHCommitSearchBuilder extends GHSearchBuilder { return this; } + /** + * Author gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder author(String v) { return q("author:" + v); } + /** + * Committer gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder committer(String v) { return q("committer:" + v); } + /** + * Author name gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder authorName(String v) { return q("author-name:" + v); } + /** + * Committer name gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder committerName(String v) { return q("committer-name:" + v); } + /** + * Author email gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder authorEmail(String v) { return q("author-email:" + v); } + /** + * Committer email gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder committerEmail(String v) { return q("committer-email:" + v); } + /** + * Author date gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder authorDate(String v) { return q("author-date:" + v); } + /** + * Committer date gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder committerDate(String v) { return q("committer-date:" + v); } + /** + * Merge gh commit search builder. + * + * @param merge + * the merge + * @return the gh commit search builder + */ public GHCommitSearchBuilder merge(boolean merge) { return q("merge:" + Boolean.valueOf(merge).toString().toLowerCase()); } + /** + * Hash gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder hash(String v) { return q("hash:" + v); } + /** + * Parent gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder parent(String v) { return q("parent:" + v); } + /** + * Tree gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder tree(String v) { return q("tree:" + v); } + /** + * Is gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder is(String v) { return q("is:" + v); } + /** + * User gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder user(String v) { return q("user:" + v); } + /** + * Org gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder org(String v) { return q("org:" + v); } + /** + * Repo gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder repo(String v) { return q("repo:" + v); } + /** + * Order gh commit search builder. + * + * @param v + * the v + * @return the gh commit search builder + */ public GHCommitSearchBuilder order(GHDirection v) { req.with("order", v); return this; } + /** + * Sort gh commit search builder. + * + * @param sort + * the sort + * @return the gh commit search builder + */ public GHCommitSearchBuilder sort(Sort sort) { req.with("sort", sort); return this; } + /** + * The enum Sort. + */ public enum Sort { AUTHOR_DATE, COMMITTER_DATE } diff --git a/src/main/java/org/kohsuke/github/GHCommitStatus.java b/src/main/java/org/kohsuke/github/GHCommitStatus.java index 148a2a17b..d1ac12bba 100644 --- a/src/main/java/org/kohsuke/github/GHCommitStatus.java +++ b/src/main/java/org/kohsuke/github/GHCommitStatus.java @@ -7,9 +7,10 @@ import java.net.URL; * Represents a status of a commit. * * @author Kohsuke Kawaguchi - * @see GHRepository#getLastCommitStatus(String) - * @see GHCommit#getLastStatus() - * @see GHRepository#createCommitStatus(String, GHCommitState, String, String) + * @see GHRepository#getLastCommitStatus(String) GHRepository#getLastCommitStatus(String) + * @see GHCommit#getLastStatus() GHCommit#getLastStatus() + * @see GHRepository#createCommitStatus(String, GHCommitState, String, String) GHRepository#createCommitStatus(String, + * GHCommitState, String, String) */ public class GHCommitStatus extends GHObject { String state; @@ -26,6 +27,11 @@ public class GHCommitStatus extends GHObject { return this; } + /** + * Gets state. + * + * @return the state + */ public GHCommitState getState() { for (GHCommitState s : GHCommitState.values()) { if (s.name().equalsIgnoreCase(state)) @@ -36,21 +42,40 @@ public class GHCommitStatus extends GHObject { /** * The URL that this status is linked to. - * + *

* This is the URL specified when creating a commit status. + * + * @return the target url */ public String getTargetUrl() { return target_url; } + /** + * Gets description. + * + * @return the description + */ public String getDescription() { return description; } + /** + * Gets creator. + * + * @return the creator + * @throws IOException + * the io exception + */ public GHUser getCreator() throws IOException { return root.intern(creator); } + /** + * Gets context. + * + * @return the context + */ public String getContext() { return context; } diff --git a/src/main/java/org/kohsuke/github/GHCompare.java b/src/main/java/org/kohsuke/github/GHCompare.java index bfcc9423e..d01cb6734 100644 --- a/src/main/java/org/kohsuke/github/GHCompare.java +++ b/src/main/java/org/kohsuke/github/GHCompare.java @@ -21,53 +21,108 @@ public class GHCompare { private GHRepository owner; + /** + * Gets url. + * + * @return the url + */ public URL getUrl() { return GitHub.parseURL(url); } + /** + * Gets html url. + * + * @return the html url + */ public URL getHtmlUrl() { return GitHub.parseURL(html_url); } + /** + * Gets permalink url. + * + * @return the permalink url + */ public URL getPermalinkUrl() { return GitHub.parseURL(permalink_url); } + /** + * Gets diff url. + * + * @return the diff url + */ public URL getDiffUrl() { return GitHub.parseURL(diff_url); } + /** + * Gets patch url. + * + * @return the patch url + */ public URL getPatchUrl() { return GitHub.parseURL(patch_url); } + /** + * Gets status. + * + * @return the status + */ public Status getStatus() { return status; } + /** + * Gets ahead by. + * + * @return the ahead by + */ public int getAheadBy() { return ahead_by; } + /** + * Gets behind by. + * + * @return the behind by + */ public int getBehindBy() { return behind_by; } + /** + * Gets total commits. + * + * @return the total commits + */ public int getTotalCommits() { return total_commits; } + /** + * Gets base commit. + * + * @return the base commit + */ public Commit getBaseCommit() { return base_commit; } + /** + * Gets merge base commit. + * + * @return the merge base commit + */ public Commit getMergeBaseCommit() { return merge_base_commit; } /** * Gets an array of commits. - * + * * @return A copy of the array being stored in the class. */ public Commit[] getCommits() { @@ -78,7 +133,7 @@ public class GHCompare { /** * Gets an array of commits. - * + * * @return A copy of the array being stored in the class. */ public GHCommit.File[] getFiles() { @@ -87,6 +142,13 @@ public class GHCompare { return newValue; } + /** + * Wrap gh compare. + * + * @param owner + * the owner + * @return the gh compare + */ public GHCompare wrap(GHRepository owner) { this.owner = owner; for (Commit commit : commits) { @@ -107,61 +169,117 @@ public class GHCompare { private InnerCommit commit; + /** + * Gets commit. + * + * @return the commit + */ public InnerCommit getCommit() { return commit; } } + /** + * The type InnerCommit. + */ public static class InnerCommit { private String url, sha, message; private User author, committer; private Tree tree; + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Gets sha. + * + * @return the sha + */ public String getSha() { return sha; } + /** + * Gets message. + * + * @return the message + */ public String getMessage() { return message; } + /** + * Gets author. + * + * @return the author + */ @WithBridgeMethods(value = User.class, castRequired = true) public GitUser getAuthor() { return author; } + /** + * Gets committer. + * + * @return the committer + */ @WithBridgeMethods(value = User.class, castRequired = true) public GitUser getCommitter() { return committer; } + /** + * Gets tree. + * + * @return the tree + */ public Tree getTree() { return tree; } } + /** + * The type Tree. + */ public static class Tree { private String url, sha; + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Gets sha. + * + * @return the sha + */ public String getSha() { return sha; } } /** + * The type User. + * * @deprecated use {@link GitUser} instead. */ public static class User extends GitUser { } + /** + * The enum Status. + */ public static enum Status { behind, ahead, identical, diverged } diff --git a/src/main/java/org/kohsuke/github/GHContent.java b/src/main/java/org/kohsuke/github/GHContent.java index 2be7016fd..41429b6d2 100644 --- a/src/main/java/org/kohsuke/github/GHContent.java +++ b/src/main/java/org/kohsuke/github/GHContent.java @@ -13,7 +13,7 @@ import java.io.UnsupportedEncodingException; * A Content of a repository. * * @author Alexandre COLLIGNON - * @see GHRepository#getFileContent(String) + * @see GHRepository#getFileContent(String) GHRepository#getFileContent(String) */ @SuppressWarnings({ "UnusedDeclaration" }) public class GHContent implements Refreshable { @@ -37,30 +37,65 @@ public class GHContent implements Refreshable { private String html_url; // this is the UI private String download_url; + /** + * Gets owner. + * + * @return the owner + */ public GHRepository getOwner() { return repository; } + /** + * Gets type. + * + * @return the type + */ public String getType() { return type; } + /** + * Gets encoding. + * + * @return the encoding + */ public String getEncoding() { return encoding; } + /** + * Gets size. + * + * @return the size + */ public long getSize() { return size; } + /** + * Gets sha. + * + * @return the sha + */ public String getSha() { return sha; } + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } + /** + * Gets path. + * + * @return the path + */ public String getPath() { return path; } @@ -72,6 +107,9 @@ public class GHContent implements Refreshable { * Due to the nature of GitHub's API, you're not guaranteed that the content will already be populated, so this may * trigger network activity, and can throw an IOException. * + * @return the content + * @throws IOException + * the io exception * @deprecated Use {@link #read()} */ @SuppressFBWarnings("DM_DEFAULT_ENCODING") @@ -86,6 +124,9 @@ public class GHContent implements Refreshable { * Due to the nature of GitHub's API, you're not guaranteed that the content will already be populated, so this may * trigger network activity, and can throw an IOException. * + * @return the encoded content + * @throws IOException + * the io exception * @deprecated Use {@link #read()} */ public String getEncodedContent() throws IOException { @@ -93,14 +134,29 @@ public class GHContent implements Refreshable { return content; } + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Gets git url. + * + * @return the git url + */ public String getGitUrl() { return git_url; } + /** + * Gets html url. + * + * @return the html url + */ public String getHtmlUrl() { return html_url; } @@ -110,6 +166,10 @@ public class GHContent implements Refreshable { */ /** * Retrieves the actual bytes of the blob. + * + * @return the input stream + * @throws IOException + * the io exception */ public InputStream read() throws IOException { refresh(content); @@ -126,24 +186,41 @@ public class GHContent implements Refreshable { /** * URL to retrieve the raw content of the file. Null if this is a directory. + * + * @return the download url + * @throws IOException + * the io exception */ public String getDownloadUrl() throws IOException { refresh(download_url); return download_url; } + /** + * Is file boolean. + * + * @return the boolean + */ public boolean isFile() { return "file".equals(type); } + /** + * Is directory boolean. + * + * @return the boolean + */ public boolean isDirectory() { return "dir".equals(type); } /** * Fully populate the data by retrieving missing data. - * + *

* Depending on the original API call where this object is created, it may not contain everything. + * + * @throws IOException + * the io exception */ protected synchronized void populate() throws IOException { root.retrieve().to(url, this); @@ -151,6 +228,10 @@ public class GHContent implements Refreshable { /** * List immediate children of this directory. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listDirectoryContent() throws IOException { if (!isDirectory()) @@ -159,20 +240,68 @@ public class GHContent implements Refreshable { return root.retrieve().asPagedIterable(url, GHContent[].class, item -> item.wrap(repository)); } + /** + * Update gh content update response. + * + * @param newContent + * the new content + * @param commitMessage + * the commit message + * @return the gh content update response + * @throws IOException + * the io exception + */ @SuppressFBWarnings("DM_DEFAULT_ENCODING") public GHContentUpdateResponse update(String newContent, String commitMessage) throws IOException { return update(newContent.getBytes(), commitMessage, null); } + /** + * Update gh content update response. + * + * @param newContent + * the new content + * @param commitMessage + * the commit message + * @param branch + * the branch + * @return the gh content update response + * @throws IOException + * the io exception + */ @SuppressFBWarnings("DM_DEFAULT_ENCODING") public GHContentUpdateResponse update(String newContent, String commitMessage, String branch) throws IOException { return update(newContent.getBytes(), commitMessage, branch); } + /** + * Update gh content update response. + * + * @param newContentBytes + * the new content bytes + * @param commitMessage + * the commit message + * @return the gh content update response + * @throws IOException + * the io exception + */ public GHContentUpdateResponse update(byte[] newContentBytes, String commitMessage) throws IOException { return update(newContentBytes, commitMessage, null); } + /** + * Update gh content update response. + * + * @param newContentBytes + * the new content bytes + * @param commitMessage + * the commit message + * @param branch + * the branch + * @return the gh content update response + * @throws IOException + * the io exception + */ public GHContentUpdateResponse update(byte[] newContentBytes, String commitMessage, String branch) throws IOException { String encodedContent = Base64.encodeBase64String(newContentBytes); @@ -193,10 +322,30 @@ public class GHContent implements Refreshable { return response; } + /** + * Delete gh content update response. + * + * @param message + * the message + * @return the gh content update response + * @throws IOException + * the io exception + */ public GHContentUpdateResponse delete(String message) throws IOException { return delete(message, null); } + /** + * Delete gh content update response. + * + * @param commitMessage + * the commit message + * @param branch + * the branch + * @return the gh content update response + * @throws IOException + * the io exception + */ public GHContentUpdateResponse delete(String commitMessage, String branch) throws IOException { Requester requester = new Requester(root).with("path", path).with("message", commitMessage).with("sha", sha) .method("DELETE"); @@ -228,6 +377,15 @@ public class GHContent implements Refreshable { return this; } + /** + * Wrap gh content [ ]. + * + * @param contents + * the contents + * @param repository + * the repository + * @return the gh content [ ] + */ public static GHContent[] wrap(GHContent[] contents, GHRepository repository) { for (GHContent unwrappedContent : contents) { unwrappedContent.wrap(repository); diff --git a/src/main/java/org/kohsuke/github/GHContentBuilder.java b/src/main/java/org/kohsuke/github/GHContentBuilder.java index d31a73d83..85fdc6522 100644 --- a/src/main/java/org/kohsuke/github/GHContentBuilder.java +++ b/src/main/java/org/kohsuke/github/GHContentBuilder.java @@ -12,7 +12,7 @@ import java.io.UnsupportedEncodingException; * Call various methods to build up parameters, then call {@link #commit()} to make the change effective. * * @author Kohsuke Kawaguchi - * @see GHRepository#createContent() + * @see GHRepository#createContent() GHRepository#createContent() */ public final class GHContentBuilder { private final GHRepository repo; @@ -24,12 +24,26 @@ public final class GHContentBuilder { this.req = new Requester(repo.root).method("PUT"); } + /** + * Path gh content builder. + * + * @param path + * the path + * @return the gh content builder + */ public GHContentBuilder path(String path) { this.path = path; req.with("path", path); return this; } + /** + * Branch gh content builder. + * + * @param branch + * the branch + * @return the gh content builder + */ public GHContentBuilder branch(String branch) { req.with("branch", branch); return this; @@ -37,17 +51,35 @@ public final class GHContentBuilder { /** * Used when updating (but not creating a new content) to specify Thetblob SHA of the file being replaced. + * + * @param sha + * the sha + * @return the gh content builder */ public GHContentBuilder sha(String sha) { req.with("sha", sha); return this; } + /** + * Content gh content builder. + * + * @param content + * the content + * @return the gh content builder + */ public GHContentBuilder content(byte[] content) { req.with("content", Base64.encodeBase64String(content)); return this; } + /** + * Content gh content builder. + * + * @param content + * the content + * @return the gh content builder + */ public GHContentBuilder content(String content) { try { return content(content.getBytes("UTF-8")); @@ -56,6 +88,13 @@ public final class GHContentBuilder { } } + /** + * Message gh content builder. + * + * @param commitMessage + * the commit message + * @return the gh content builder + */ public GHContentBuilder message(String commitMessage) { req.with("message", commitMessage); return this; @@ -63,6 +102,10 @@ public final class GHContentBuilder { /** * Commits a new content. + * + * @return the gh content update response + * @throws IOException + * the io exception */ public GHContentUpdateResponse commit() throws IOException { GHContentUpdateResponse response = req.to(repo.getApiTailUrl("contents/" + path), diff --git a/src/main/java/org/kohsuke/github/GHContentSearchBuilder.java b/src/main/java/org/kohsuke/github/GHContentSearchBuilder.java index f7438d2bb..b4b93880f 100644 --- a/src/main/java/org/kohsuke/github/GHContentSearchBuilder.java +++ b/src/main/java/org/kohsuke/github/GHContentSearchBuilder.java @@ -4,7 +4,7 @@ package org.kohsuke.github; * Search code for {@link GHContent}. * * @author Kohsuke Kawaguchi - * @see GitHub#searchContent() + * @see GitHub#searchContent() GitHub#searchContent() */ public class GHContentSearchBuilder extends GHSearchBuilder { GHContentSearchBuilder(GitHub root) { @@ -19,38 +19,101 @@ public class GHContentSearchBuilder extends GHSearchBuilder { return this; } + /** + * In gh content search builder. + * + * @param v + * the v + * @return the gh content search builder + */ public GHContentSearchBuilder in(String v) { return q("in:" + v); } + /** + * Language gh content search builder. + * + * @param v + * the v + * @return the gh content search builder + */ public GHContentSearchBuilder language(String v) { return q("language:" + v); } + /** + * Fork gh content search builder. + * + * @param v + * the v + * @return the gh content search builder + */ public GHContentSearchBuilder fork(String v) { return q("fork:" + v); } + /** + * Size gh content search builder. + * + * @param v + * the v + * @return the gh content search builder + */ public GHContentSearchBuilder size(String v) { return q("size:" + v); } + /** + * Path gh content search builder. + * + * @param v + * the v + * @return the gh content search builder + */ public GHContentSearchBuilder path(String v) { return q("path:" + v); } + /** + * Filename gh content search builder. + * + * @param v + * the v + * @return the gh content search builder + */ public GHContentSearchBuilder filename(String v) { return q("filename:" + v); } + /** + * Extension gh content search builder. + * + * @param v + * the v + * @return the gh content search builder + */ public GHContentSearchBuilder extension(String v) { return q("extension:" + v); } + /** + * User gh content search builder. + * + * @param v + * the v + * @return the gh content search builder + */ public GHContentSearchBuilder user(String v) { return q("user:" + v); } + /** + * Repo gh content search builder. + * + * @param v + * the v + * @return the gh content search builder + */ public GHContentSearchBuilder repo(String v) { return q("repo:" + v); } diff --git a/src/main/java/org/kohsuke/github/GHContentUpdateResponse.java b/src/main/java/org/kohsuke/github/GHContentUpdateResponse.java index cd66091e6..d53bce50e 100644 --- a/src/main/java/org/kohsuke/github/GHContentUpdateResponse.java +++ b/src/main/java/org/kohsuke/github/GHContentUpdateResponse.java @@ -2,15 +2,25 @@ package org.kohsuke.github; /** * The response that is returned when updating repository content. - **/ + */ public class GHContentUpdateResponse { private GHContent content; private GHCommit commit; + /** + * Gets content. + * + * @return the content + */ public GHContent getContent() { return content; } + /** + * Gets commit. + * + * @return the commit + */ public GHCommit getCommit() { return commit; } diff --git a/src/main/java/org/kohsuke/github/GHCreateRepositoryBuilder.java b/src/main/java/org/kohsuke/github/GHCreateRepositoryBuilder.java index 8c33e9efb..268bfa8ef 100644 --- a/src/main/java/org/kohsuke/github/GHCreateRepositoryBuilder.java +++ b/src/main/java/org/kohsuke/github/GHCreateRepositoryBuilder.java @@ -25,7 +25,6 @@ public class GHCreateRepositoryBuilder { * * @param description * description of repository - * * @return a builder to continue with building */ public GHCreateRepositoryBuilder description(String description) { @@ -38,7 +37,6 @@ public class GHCreateRepositoryBuilder { * * @param homepage * homepage of repository - * * @return a builder to continue with building */ public GHCreateRepositoryBuilder homepage(URL homepage) { @@ -47,10 +45,9 @@ public class GHCreateRepositoryBuilder { /** * Homepage for repository - * + * * @param homepage * homepage of repository - * * @return a builder to continue with building */ public GHCreateRepositoryBuilder homepage(String homepage) { @@ -72,7 +69,7 @@ public class GHCreateRepositoryBuilder { /** * Enables issue tracker - * + * * @param enabled * true if enabled * @return a builder to continue with building @@ -84,7 +81,7 @@ public class GHCreateRepositoryBuilder { /** * Enables wiki - * + * * @param enabled * true if enabled * @return a builder to continue with building @@ -96,7 +93,7 @@ public class GHCreateRepositoryBuilder { /** * Enables downloads - * + * * @param enabled * true if enabled * @return a builder to continue with building @@ -108,7 +105,7 @@ public class GHCreateRepositoryBuilder { /** * If true, create an initial commit with empty README. - * + * * @param enabled * true if enabled * @return a builder to continue with building @@ -120,7 +117,7 @@ public class GHCreateRepositoryBuilder { /** * Allow or disallow squash-merging pull requests. - * + * * @param enabled * true if enabled * @return a builder to continue with building @@ -132,7 +129,7 @@ public class GHCreateRepositoryBuilder { /** * Allow or disallow merging pull requests with a merge commit. - * + * * @param enabled * true if enabled * @return a builder to continue with building @@ -144,7 +141,7 @@ public class GHCreateRepositoryBuilder { /** * Allow or disallow rebase-merging pull requests. - * + * * @param enabled * true if enabled * @return a builder to continue with building @@ -156,12 +153,10 @@ public class GHCreateRepositoryBuilder { /** * Creates a default .gitignore - * + * * @param language * template to base the ignore file on - * @return a builder to continue with building - * - * See https://developer.github.com/v3/repos/#create + * @return a builder to continue with building See https://developer.github.com/v3/repos/#create */ public GHCreateRepositoryBuilder gitignoreTemplate(String language) { this.builder.with("gitignore_template", language); @@ -170,12 +165,10 @@ public class GHCreateRepositoryBuilder { /** * Desired license template to apply - * + * * @param license * template to base the license file on - * @return a builder to continue with building - * - * See https://developer.github.com/v3/repos/#create + * @return a builder to continue with building See https://developer.github.com/v3/repos/#create */ public GHCreateRepositoryBuilder licenseTemplate(String license) { this.builder.with("license_template", license); @@ -184,7 +177,7 @@ public class GHCreateRepositoryBuilder { /** * The team that gets granted access to this repository. Only valid for creating a repository in an organization. - * + * * @param team * team to grant access to * @return a builder to continue with building @@ -197,7 +190,8 @@ public class GHCreateRepositoryBuilder { /** * Creates a repository with all the parameters. - * + * + * @return the gh repository * @throws IOException * if repsitory cannot be created */ diff --git a/src/main/java/org/kohsuke/github/GHDeployKey.java b/src/main/java/org/kohsuke/github/GHDeployKey.java index 4b7487560..f9bd1acd5 100644 --- a/src/main/java/org/kohsuke/github/GHDeployKey.java +++ b/src/main/java/org/kohsuke/github/GHDeployKey.java @@ -4,6 +4,9 @@ import org.apache.commons.lang3.builder.ToStringBuilder; import java.io.IOException; +/** + * The type GHDeployKey. + */ public class GHDeployKey { protected String url, key, title; @@ -11,26 +14,58 @@ public class GHDeployKey { protected long id; private GHRepository owner; + /** + * Gets id. + * + * @return the id + */ public long getId() { return id; } + /** + * Gets key. + * + * @return the key + */ public String getKey() { return key; } + /** + * Gets title. + * + * @return the title + */ public String getTitle() { return title; } + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Is verified boolean. + * + * @return the boolean + */ public boolean isVerified() { return verified; } + /** + * Wrap gh deploy key. + * + * @param repo + * the repo + * @return the gh deploy key + */ public GHDeployKey wrap(GHRepository repo) { this.owner = repo; return this; @@ -40,6 +75,12 @@ public class GHDeployKey { return new ToStringBuilder(this).append("title", title).append("id", id).append("key", key).toString(); } + /** + * Delete. + * + * @throws IOException + * the io exception + */ public void delete() throws IOException { new Requester(owner.root).method("DELETE") .to(String.format("/repos/%s/%s/keys/%d", owner.getOwnerName(), owner.getName(), id)); diff --git a/src/main/java/org/kohsuke/github/GHDeployment.java b/src/main/java/org/kohsuke/github/GHDeployment.java index ddff6158d..601bf258d 100644 --- a/src/main/java/org/kohsuke/github/GHDeployment.java +++ b/src/main/java/org/kohsuke/github/GHDeployment.java @@ -7,8 +7,9 @@ import java.net.URL; * Represents a deployment * * @see documentation - * @see GHRepository#listDeployments(String, String, String, String) - * @see GHRepository#getDeployment(long) + * @see GHRepository#listDeployments(String, String, String, String) GHRepository#listDeployments(String, String, + * String, String) + * @see GHRepository#getDeployment(long) GHRepository#getDeployment(long) */ public class GHDeployment extends GHObject { private GHRepository owner; @@ -31,34 +32,76 @@ public class GHDeployment extends GHObject { return this; } + /** + * Gets statuses url. + * + * @return the statuses url + */ public URL getStatusesUrl() { return GitHub.parseURL(statuses_url); } + /** + * Gets repository url. + * + * @return the repository url + */ public URL getRepositoryUrl() { return GitHub.parseURL(repository_url); } + /** + * Gets task. + * + * @return the task + */ public String getTask() { return task; } + /** + * Gets payload. + * + * @return the payload + */ public String getPayload() { return (String) payload; } + /** + * Gets environment. + * + * @return the environment + */ public String getEnvironment() { return environment; } + /** + * Gets creator. + * + * @return the creator + * @throws IOException + * the io exception + */ public GHUser getCreator() throws IOException { return root.intern(creator); } + /** + * Gets ref. + * + * @return the ref + */ public String getRef() { return ref; } + /** + * Gets sha. + * + * @return the sha + */ public String getSha() { return sha; } @@ -71,10 +114,22 @@ public class GHDeployment extends GHObject { return null; } + /** + * Create status gh deployment status builder. + * + * @param state + * the state + * @return the gh deployment status builder + */ public GHDeploymentStatusBuilder createStatus(GHDeploymentState state) { return new GHDeploymentStatusBuilder(owner, id, state); } + /** + * List statuses paged iterable. + * + * @return the paged iterable + */ public PagedIterable listStatuses() { return root.retrieve().asPagedIterable(statuses_url, GHDeploymentStatus[].class, item -> item.wrap(owner)); } diff --git a/src/main/java/org/kohsuke/github/GHDeploymentBuilder.java b/src/main/java/org/kohsuke/github/GHDeploymentBuilder.java index ed13e1424..c04153806 100644 --- a/src/main/java/org/kohsuke/github/GHDeploymentBuilder.java +++ b/src/main/java/org/kohsuke/github/GHDeploymentBuilder.java @@ -3,56 +3,129 @@ package org.kohsuke.github; import java.io.IOException; import java.util.List; -//Based on https://developer.github.com/v3/repos/deployments/#create-a-deployment +/** + * The type GHDeploymentBuilder. + */ +// Based on https://developer.github.com/v3/repos/deployments/#create-a-deployment public class GHDeploymentBuilder { private final GHRepository repo; private final Requester builder; + /** + * Instantiates a new Gh deployment builder. + * + * @param repo + * the repo + */ public GHDeploymentBuilder(GHRepository repo) { this.repo = repo; this.builder = new Requester(repo.root); } + /** + * Instantiates a new Gh deployment builder. + * + * @param repo + * the repo + * @param ref + * the ref + */ public GHDeploymentBuilder(GHRepository repo, String ref) { this(repo); ref(ref); } + /** + * Ref gh deployment builder. + * + * @param branch + * the branch + * @return the gh deployment builder + */ public GHDeploymentBuilder ref(String branch) { builder.with("ref", branch); return this; } + /** + * Task gh deployment builder. + * + * @param task + * the task + * @return the gh deployment builder + */ public GHDeploymentBuilder task(String task) { builder.with("task", task); return this; } + /** + * Auto merge gh deployment builder. + * + * @param autoMerge + * the auto merge + * @return the gh deployment builder + */ public GHDeploymentBuilder autoMerge(boolean autoMerge) { builder.with("auto_merge", autoMerge); return this; } + /** + * Required contexts gh deployment builder. + * + * @param requiredContexts + * the required contexts + * @return the gh deployment builder + */ public GHDeploymentBuilder requiredContexts(List requiredContexts) { builder.with("required_contexts", requiredContexts); return this; } + /** + * Payload gh deployment builder. + * + * @param payload + * the payload + * @return the gh deployment builder + */ public GHDeploymentBuilder payload(String payload) { builder.with("payload", payload); return this; } + /** + * Environment gh deployment builder. + * + * @param environment + * the environment + * @return the gh deployment builder + */ public GHDeploymentBuilder environment(String environment) { builder.with("environment", environment); return this; } + /** + * Description gh deployment builder. + * + * @param description + * the description + * @return the gh deployment builder + */ public GHDeploymentBuilder description(String description) { builder.with("description", description); return this; } + /** + * Create gh deployment. + * + * @return the gh deployment + * @throws IOException + * the io exception + */ public GHDeployment create() throws IOException { return builder.to(repo.getApiTailUrl("deployments"), GHDeployment.class).wrap(repo); } diff --git a/src/main/java/org/kohsuke/github/GHDeploymentStatus.java b/src/main/java/org/kohsuke/github/GHDeploymentStatus.java index b8c751bbc..c20657368 100644 --- a/src/main/java/org/kohsuke/github/GHDeploymentStatus.java +++ b/src/main/java/org/kohsuke/github/GHDeploymentStatus.java @@ -3,6 +3,9 @@ package org.kohsuke.github; import java.net.URL; import java.util.Locale; +/** + * The type GHDeploymentStatus. + */ public class GHDeploymentStatus extends GHObject { private GHRepository owner; private GitHub root; @@ -13,6 +16,13 @@ public class GHDeploymentStatus extends GHObject { protected String deployment_url; protected String repository_url; + /** + * Wrap gh deployment status. + * + * @param owner + * the owner + * @return the gh deployment status + */ public GHDeploymentStatus wrap(GHRepository owner) { this.owner = owner; this.root = owner.root; @@ -21,18 +31,38 @@ public class GHDeploymentStatus extends GHObject { return this; } + /** + * Gets target url. + * + * @return the target url + */ public URL getTargetUrl() { return GitHub.parseURL(target_url); } + /** + * Gets deployment url. + * + * @return the deployment url + */ public URL getDeploymentUrl() { return GitHub.parseURL(deployment_url); } + /** + * Gets repository url. + * + * @return the repository url + */ public URL getRepositoryUrl() { return GitHub.parseURL(repository_url); } + /** + * Gets state. + * + * @return the state + */ public GHDeploymentState getState() { return GHDeploymentState.valueOf(state.toUpperCase(Locale.ENGLISH)); } diff --git a/src/main/java/org/kohsuke/github/GHDeploymentStatusBuilder.java b/src/main/java/org/kohsuke/github/GHDeploymentStatusBuilder.java index c842c8ddd..31e54e64b 100644 --- a/src/main/java/org/kohsuke/github/GHDeploymentStatusBuilder.java +++ b/src/main/java/org/kohsuke/github/GHDeploymentStatusBuilder.java @@ -5,7 +5,7 @@ import java.io.IOException; /** * Creates a new deployment status. * - * @see GHDeployment#createStatus(GHDeploymentState) + * @see GHDeployment#createStatus(GHDeploymentState) GHDeployment#createStatus(GHDeploymentState) */ public class GHDeploymentStatusBuilder { private final Requester builder; @@ -13,6 +13,14 @@ public class GHDeploymentStatusBuilder { private long deploymentId; /** + * Instantiates a new Gh deployment status builder. + * + * @param repo + * the repo + * @param deploymentId + * the deployment id + * @param state + * the state * @deprecated Use {@link GHDeployment#createStatus(GHDeploymentState)} */ public GHDeploymentStatusBuilder(GHRepository repo, int deploymentId, GHDeploymentState state) { @@ -26,16 +34,37 @@ public class GHDeploymentStatusBuilder { this.builder.with("state", state); } + /** + * Description gh deployment status builder. + * + * @param description + * the description + * @return the gh deployment status builder + */ public GHDeploymentStatusBuilder description(String description) { this.builder.with("description", description); return this; } + /** + * Target url gh deployment status builder. + * + * @param targetUrl + * the target url + * @return the gh deployment status builder + */ public GHDeploymentStatusBuilder targetUrl(String targetUrl) { this.builder.with("target_url", targetUrl); return this; } + /** + * Create gh deployment status. + * + * @return the gh deployment status + * @throws IOException + * the io exception + */ public GHDeploymentStatus create() throws IOException { return builder.to(repo.getApiTailUrl("deployments/" + deploymentId + "/statuses"), GHDeploymentStatus.class) .wrap(repo); diff --git a/src/main/java/org/kohsuke/github/GHEmail.java b/src/main/java/org/kohsuke/github/GHEmail.java index 76246dab7..796aa3aae 100644 --- a/src/main/java/org/kohsuke/github/GHEmail.java +++ b/src/main/java/org/kohsuke/github/GHEmail.java @@ -38,14 +38,29 @@ public class GHEmail { protected boolean primary; protected boolean verified; + /** + * Gets email. + * + * @return the email + */ public String getEmail() { return email; } + /** + * Is primary boolean. + * + * @return the boolean + */ public boolean isPrimary() { return primary; } + /** + * Is verified boolean. + * + * @return the boolean + */ public boolean isVerified() { return verified; } diff --git a/src/main/java/org/kohsuke/github/GHEventInfo.java b/src/main/java/org/kohsuke/github/GHEventInfo.java index 4e139c94d..830ab3f80 100644 --- a/src/main/java/org/kohsuke/github/GHEventInfo.java +++ b/src/main/java/org/kohsuke/github/GHEventInfo.java @@ -40,6 +40,11 @@ public class GHEventInfo { private String name; // owner/repo } + /** + * Gets type. + * + * @return the type + */ public GHEvent getType() { String t = type; if (t.endsWith("Event")) @@ -56,15 +61,27 @@ public class GHEventInfo { return this; } + /** + * Gets id. + * + * @return the id + */ public long getId() { return id; } + /** + * Gets created at. + * + * @return the created at + */ public Date getCreatedAt() { return GitHub.parseDate(created_at); } /** + * Gets repository. + * * @return Repository where the change was made. * @throws IOException * on error @@ -76,6 +93,8 @@ public class GHEventInfo { } /** + * Gets actor. + * * @return the {@link GHUser} actor for this event. * @throws IOException * on error @@ -87,6 +106,8 @@ public class GHEventInfo { } /** + * Gets actor login. + * * @return the login of the actor. * @throws IOException * on error @@ -95,6 +116,13 @@ public class GHEventInfo { return actor.getLogin(); } + /** + * Gets organization. + * + * @return the organization + * @throws IOException + * the io exception + */ @SuppressFBWarnings(value = { "UWF_FIELD_NOT_INITIALIZED_IN_CONSTRUCTOR" }, justification = "The field comes from JSON deserialization") public GHOrganization getOrganization() throws IOException { @@ -104,10 +132,11 @@ public class GHEventInfo { /** * Retrieves the payload. * + * @param + * the type parameter * @param type * Specify one of the {@link GHEventPayload} subtype that defines a type-safe access to the payload. This * must match the {@linkplain #getType() event type}. - * * @return parsed event payload * @throws IOException * if payload cannot be parsed diff --git a/src/main/java/org/kohsuke/github/GHEventPayload.java b/src/main/java/org/kohsuke/github/GHEventPayload.java index 01b29c88e..4806f5626 100644 --- a/src/main/java/org/kohsuke/github/GHEventPayload.java +++ b/src/main/java/org/kohsuke/github/GHEventPayload.java @@ -10,8 +10,8 @@ import java.util.List; /** * Base type for types used in databinding of the event payload. * - * @see GitHub#parseEventPayload(Reader, Class) - * @see GHEventInfo#getPayload(Class) + * @see GitHub#parseEventPayload(Reader, Class) GitHub#parseEventPayload(Reader, Class) + * @see GHEventInfo#getPayload(Class) GHEventInfo#getPayload(Class) */ @SuppressWarnings("UnusedDeclaration") public abstract class GHEventPayload { @@ -24,13 +24,19 @@ public abstract class GHEventPayload { /** * Gets the sender or {@code null} if accessed via the events API. - * + * * @return the sender or {@code null} if accessed via the events API. */ public GHUser getSender() { return sender; } + /** + * Sets sender. + * + * @param sender + * the sender + */ public void setSender(GHUser sender) { this.sender = sender; } @@ -55,19 +61,39 @@ public abstract class GHEventPayload { private GHPullRequest pull_request; private GHRepository repository; + /** + * Gets action. + * + * @return the action + */ public String getAction() { return action; } + /** + * Gets number. + * + * @return the number + */ public int getNumber() { return number; } + /** + * Gets pull request. + * + * @return the pull request + */ public GHPullRequest getPullRequest() { pull_request.root = root; return pull_request; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } @@ -99,18 +125,38 @@ public abstract class GHEventPayload { private GHPullRequest pull_request; private GHRepository repository; + /** + * Gets action. + * + * @return the action + */ public String getAction() { return action; } + /** + * Gets review. + * + * @return the review + */ public GHPullRequestReview getReview() { return review; } + /** + * Gets pull request. + * + * @return the pull request + */ public GHPullRequest getPullRequest() { return pull_request; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } @@ -145,18 +191,38 @@ public abstract class GHEventPayload { private GHPullRequest pull_request; private GHRepository repository; + /** + * Gets action. + * + * @return the action + */ public String getAction() { return action; } + /** + * Gets comment. + * + * @return the comment + */ public GHPullRequestReviewComment getComment() { return comment; } + /** + * Gets pull request. + * + * @return the pull request + */ public GHPullRequest getPullRequest() { return pull_request; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } @@ -192,23 +258,50 @@ public abstract class GHEventPayload { private GHIssue issue; private GHRepository repository; + /** + * Gets action. + * + * @return the action + */ @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Comes from JSON deserialization") public String getAction() { return action; } + /** + * Gets issue. + * + * @return the issue + */ public GHIssue getIssue() { return issue; } + /** + * Sets issue. + * + * @param issue + * the issue + */ public void setIssue(GHIssue issue) { this.issue = issue; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } @@ -238,31 +331,69 @@ public abstract class GHEventPayload { private GHIssue issue; private GHRepository repository; + /** + * Gets action. + * + * @return the action + */ @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Comes from JSON deserialization") public String getAction() { return action; } + /** + * Gets comment. + * + * @return the comment + */ public GHIssueComment getComment() { return comment; } + /** + * Sets comment. + * + * @param comment + * the comment + */ public void setComment(GHIssueComment comment) { this.comment = comment; } + /** + * Gets issue. + * + * @return the issue + */ public GHIssue getIssue() { return issue; } + /** + * Sets issue. + * + * @param issue + * the issue + */ public void setIssue(GHIssue issue) { this.issue = issue; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } @@ -292,23 +423,50 @@ public abstract class GHEventPayload { private GHCommitComment comment; private GHRepository repository; + /** + * Gets action. + * + * @return the action + */ @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Comes from JSON deserialization") public String getAction() { return action; } + /** + * Gets comment. + * + * @return the comment + */ public GHCommitComment getComment() { return comment; } + /** + * Sets comment. + * + * @param comment + * the comment + */ public void setComment(GHCommitComment comment) { this.comment = comment; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } @@ -339,30 +497,61 @@ public abstract class GHEventPayload { private String description; private GHRepository repository; + /** + * Gets ref. + * + * @return the ref + */ @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Comes from JSON deserialization") public String getRef() { return ref; } + /** + * Gets ref type. + * + * @return the ref type + */ @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Comes from JSON deserialization") public String getRefType() { return refType; } + /** + * Gets master branch. + * + * @return the master branch + */ @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Comes from JSON deserialization") public String getMasterBranch() { return masterBranch; } + /** + * Gets description. + * + * @return the description + */ @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Comes from JSON deserialization") public String getDescription() { return description; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } @@ -389,20 +578,41 @@ public abstract class GHEventPayload { private String refType; private GHRepository repository; + /** + * Gets ref. + * + * @return the ref + */ @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Comes from JSON deserialization") public String getRef() { return ref; } + /** + * Gets ref type. + * + * @return the ref type + */ @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Comes from JSON deserialization") public String getRefType() { return refType; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } @@ -427,18 +637,40 @@ public abstract class GHEventPayload { private GHDeployment deployment; private GHRepository repository; + /** + * Gets deployment. + * + * @return the deployment + */ public GHDeployment getDeployment() { return deployment; } + /** + * Sets deployment. + * + * @param deployment + * the deployment + */ public void setDeployment(GHDeployment deployment) { this.deployment = deployment; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } @@ -467,26 +699,59 @@ public abstract class GHEventPayload { private GHDeployment deployment; private GHRepository repository; + /** + * Gets deployment status. + * + * @return the deployment status + */ public GHDeploymentStatus getDeploymentStatus() { return deploymentStatus; } + /** + * Sets deployment status. + * + * @param deploymentStatus + * the deployment status + */ public void setDeploymentStatus(GHDeploymentStatus deploymentStatus) { this.deploymentStatus = deploymentStatus; } + /** + * Gets deployment. + * + * @return the deployment + */ public GHDeployment getDeployment() { return deployment; } + /** + * Sets deployment. + * + * @param deployment + * the deployment + */ public void setDeployment(GHDeployment deployment) { this.deployment = deployment; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } @@ -513,18 +778,40 @@ public abstract class GHEventPayload { private GHRepository forkee; private GHRepository repository; + /** + * Gets forkee. + * + * @return the forkee + */ public GHRepository getForkee() { return forkee; } + /** + * Sets forkee. + * + * @param forkee + * the forkee + */ public void setForkee(GHRepository forkee) { this.forkee = forkee; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } @@ -546,18 +833,40 @@ public abstract class GHEventPayload { private GHRepository repository; private GHOrganization organization; + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Gets organization. + * + * @return the organization + */ public GHOrganization getOrganization() { return organization; } + /** + * Sets organization. + * + * @param organization + * the organization + */ public void setOrganization(GHOrganization organization) { this.organization = organization; } @@ -582,10 +891,21 @@ public abstract class GHEventPayload { public static class Public extends GHEventPayload { private GHRepository repository; + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } @@ -617,6 +937,8 @@ public abstract class GHEventPayload { /** * The SHA of the HEAD commit on the repository + * + * @return the head */ public String getHead() { return head; @@ -625,6 +947,8 @@ public abstract class GHEventPayload { /** * This is undocumented, but it looks like this captures the commit that the ref was pointing to before the * push. + * + * @return the before */ public String getBefore() { return before; @@ -637,6 +961,8 @@ public abstract class GHEventPayload { /** * The full Git ref that was pushed. Example: “refs/heads/master” + * + * @return the ref */ public String getRef() { return ref; @@ -644,38 +970,73 @@ public abstract class GHEventPayload { /** * The number of commits in the push. Is this always the same as {@code getCommits().size()}? + * + * @return the size */ public int getSize() { return size; } + /** + * Is created boolean. + * + * @return the boolean + */ public boolean isCreated() { return created; } + /** + * Is deleted boolean. + * + * @return the boolean + */ public boolean isDeleted() { return deleted; } + /** + * Is forced boolean. + * + * @return the boolean + */ public boolean isForced() { return forced; } /** * The list of pushed commits. + * + * @return the commits */ public List getCommits() { return commits; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Gets pusher. + * + * @return the pusher + */ public Pusher getPusher() { return pusher; } + /** + * Sets pusher. + * + * @param pusher + * the pusher + */ public void setPusher(Pusher pusher) { this.pusher = pusher; } @@ -687,21 +1048,46 @@ public abstract class GHEventPayload { repository.wrap(root); } + /** + * The type Pusher. + */ public static class Pusher { private String name, email; + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } + /** + * Sets name. + * + * @param name + * the name + */ public void setName(String name) { this.name = name; } + /** + * Gets email. + * + * @return the email + */ public String getEmail() { return email; } + /** + * Sets email. + * + * @param email + * the email + */ public void setEmail(String email) { this.email = email; } @@ -717,21 +1103,38 @@ public abstract class GHEventPayload { private boolean distinct; private List added, removed, modified; + /** + * Gets author. + * + * @return the author + */ public GitUser getAuthor() { return author; } + /** + * Gets committer. + * + * @return the committer + */ public GitUser getCommitter() { return committer; } /** * Points to the commit API resource. + * + * @return the url */ public String getUrl() { return url; } + /** + * Gets sha. + * + * @return the sha + */ public String getSha() { return sha; } @@ -741,25 +1144,47 @@ public abstract class GHEventPayload { sha = id; } + /** + * Gets message. + * + * @return the message + */ public String getMessage() { return message; } /** * Whether this commit is distinct from any that have been pushed before. + * + * @return the boolean */ public boolean isDistinct() { return distinct; } + /** + * Gets added. + * + * @return the added + */ public List getAdded() { return added; } + /** + * Gets removed. + * + * @return the removed + */ public List getRemoved() { return removed; } + /** + * Gets modified. + * + * @return the modified + */ public List getModified() { return modified; } @@ -778,23 +1203,50 @@ public abstract class GHEventPayload { private GHRelease release; private GHRepository repository; + /** + * Gets action. + * + * @return the action + */ @SuppressFBWarnings(value = "UWF_UNWRITTEN_FIELD", justification = "Comes from JSON deserialization") public String getAction() { return action; } + /** + * Gets release. + * + * @return the release + */ public GHRelease getRelease() { return release; } + /** + * Sets release. + * + * @param release + * the release + */ public void setRelease(GHRelease release) { this.release = release; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } @@ -820,22 +1272,49 @@ public abstract class GHEventPayload { private GHRepository repository; private GHOrganization organization; + /** + * Gets action. + * + * @return the action + */ public String getAction() { return action; } + /** + * Sets repository. + * + * @param repository + * the repository + */ public void setRepository(GHRepository repository) { this.repository = repository; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } + /** + * Gets organization. + * + * @return the organization + */ public GHOrganization getOrganization() { return organization; } + /** + * Sets organization. + * + * @param organization + * the organization + */ public void setOrganization(GHOrganization organization) { this.organization = organization; } diff --git a/src/main/java/org/kohsuke/github/GHException.java b/src/main/java/org/kohsuke/github/GHException.java index c238e53c9..32534d40d 100644 --- a/src/main/java/org/kohsuke/github/GHException.java +++ b/src/main/java/org/kohsuke/github/GHException.java @@ -1,13 +1,29 @@ package org.kohsuke.github; /** + * The type GHException. + * * @author Kohsuke Kawaguchi */ public class GHException extends RuntimeException { + /** + * Instantiates a new Gh exception. + * + * @param message + * the message + */ public GHException(String message) { super(message); } + /** + * Instantiates a new Gh exception. + * + * @param message + * the message + * @param cause + * the cause + */ public GHException(String message, Throwable cause) { super(message, cause); } diff --git a/src/main/java/org/kohsuke/github/GHFileNotFoundException.java b/src/main/java/org/kohsuke/github/GHFileNotFoundException.java index b8ebadddf..4db5b5b05 100644 --- a/src/main/java/org/kohsuke/github/GHFileNotFoundException.java +++ b/src/main/java/org/kohsuke/github/GHFileNotFoundException.java @@ -14,13 +14,27 @@ import java.util.Map; public class GHFileNotFoundException extends FileNotFoundException { protected Map> responseHeaderFields; + /** + * Instantiates a new Gh file not found exception. + */ public GHFileNotFoundException() { } + /** + * Instantiates a new Gh file not found exception. + * + * @param s + * the s + */ public GHFileNotFoundException(String s) { super(s); } + /** + * Gets response header fields. + * + * @return the response header fields + */ @CheckForNull public Map> getResponseHeaderFields() { return responseHeaderFields; diff --git a/src/main/java/org/kohsuke/github/GHGist.java b/src/main/java/org/kohsuke/github/GHGist.java index c8681f5c0..d772d3dd7 100644 --- a/src/main/java/org/kohsuke/github/GHGist.java +++ b/src/main/java/org/kohsuke/github/GHGist.java @@ -14,9 +14,9 @@ import java.util.Map.Entry; * Gist * * @author Kohsuke Kawaguchi - * @see GHUser#listGists() - * @see GitHub#getGist(String) - * @see GitHub#createGist() + * @see GHUser#listGists() GHUser#listGists() + * @see GitHub#getGist(String) GitHub#getGist(String) + * @see GitHub#createGist() GitHub#createGist() * @see documentation */ public class GHGist extends GHObject { @@ -37,27 +37,48 @@ public class GHGist extends GHObject { private Map files = new HashMap(); /** + * Gets owner. + * * @return User that owns this Gist. + * @throws IOException + * the io exception */ public GHUser getOwner() throws IOException { return root.intern(owner); } + /** + * Gets forks url. + * + * @return the forks url + */ public String getForksUrl() { return forks_url; } + /** + * Gets commits url. + * + * @return the commits url + */ public String getCommitsUrl() { return commits_url; } /** + * Gets git pull url. + * * @return URL like https://gist.github.com/gists/12345.git */ public String getGitPullUrl() { return git_pull_url; } + /** + * Gets git push url. + * + * @return the git push url + */ public String getGitPushUrl() { return git_push_url; } @@ -66,29 +87,58 @@ public class GHGist extends GHObject { return GitHub.parseURL(html_url); } + /** + * Is public boolean. + * + * @return the boolean + */ public boolean isPublic() { return _public; } + /** + * Gets description. + * + * @return the description + */ public String getDescription() { return description; } + /** + * Gets comment count. + * + * @return the comment count + */ public int getCommentCount() { return comments; } /** + * Gets comments url. + * * @return API URL of listing comments. */ public String getCommentsUrl() { return comments_url; } + /** + * Gets file. + * + * @param name + * the name + * @return the file + */ public GHGistFile getFile(String name) { return files.get(name); } + /** + * Gets files. + * + * @return the files + */ public Map getFiles() { return Collections.unmodifiableMap(files); } @@ -125,31 +175,62 @@ public class GHGist extends GHObject { return result; } + /** + * Star. + * + * @throws IOException + * the io exception + */ public void star() throws IOException { new Requester(root).method("PUT").to(getApiTailUrl("star")); } + /** + * Unstar. + * + * @throws IOException + * the io exception + */ public void unstar() throws IOException { new Requester(root).method("DELETE").to(getApiTailUrl("star")); } + /** + * Is starred boolean. + * + * @return the boolean + * @throws IOException + * the io exception + */ public boolean isStarred() throws IOException { return root.retrieve().asHttpStatusCode(getApiTailUrl("star")) / 100 == 2; } /** * Forks this gist into your own. + * + * @return the gh gist + * @throws IOException + * the io exception */ public GHGist fork() throws IOException { return new Requester(root).to(getApiTailUrl("forks"), GHGist.class).wrapUp(root); } + /** + * List forks paged iterable. + * + * @return the paged iterable + */ public PagedIterable listForks() { return root.retrieve().asPagedIterable(getApiTailUrl("forks"), GHGist[].class, item -> item.wrapUp(root)); } /** * Deletes this gist. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { new Requester(root).method("DELETE").to("/gists/" + id); @@ -157,6 +238,10 @@ public class GHGist extends GHObject { /** * Updates this gist via a builder. + * + * @return the gh gist updater + * @throws IOException + * the io exception */ public GHGistUpdater update() throws IOException { return new GHGistUpdater(this); diff --git a/src/main/java/org/kohsuke/github/GHGistBuilder.java b/src/main/java/org/kohsuke/github/GHGistBuilder.java index c8742ad61..5b2fbb9cb 100644 --- a/src/main/java/org/kohsuke/github/GHGistBuilder.java +++ b/src/main/java/org/kohsuke/github/GHGistBuilder.java @@ -8,29 +8,55 @@ import java.util.LinkedHashMap; * Builder pattern for creating a new Gist. * * @author Kohsuke Kawaguchi - * @see GitHub#createGist() + * @see GitHub#createGist() GitHub#createGist() */ public class GHGistBuilder { private final GitHub root; private final Requester req; private final LinkedHashMap files = new LinkedHashMap(); + /** + * Instantiates a new Gh gist builder. + * + * @param root + * the root + */ public GHGistBuilder(GitHub root) { this.root = root; req = new Requester(root); } + /** + * Description gh gist builder. + * + * @param desc + * the desc + * @return the gh gist builder + */ public GHGistBuilder description(String desc) { req.with("description", desc); return this; } + /** + * Public gh gist builder. + * + * @param v + * the v + * @return the gh gist builder + */ public GHGistBuilder public_(boolean v) { req.with("public", v); return this; } /** + * File gh gist builder. + * + * @param fileName + * the file name + * @param content + * the content * @return Adds a new file. */ public GHGistBuilder file(String fileName, String content) { @@ -40,7 +66,7 @@ public class GHGistBuilder { /** * Creates a Gist based on the parameters specified thus far. - * + * * @return created Gist * @throws IOException * if Gist cannot be created. diff --git a/src/main/java/org/kohsuke/github/GHGistFile.java b/src/main/java/org/kohsuke/github/GHGistFile.java index 4f8084de1..c143bf2a1 100644 --- a/src/main/java/org/kohsuke/github/GHGistFile.java +++ b/src/main/java/org/kohsuke/github/GHGistFile.java @@ -4,8 +4,8 @@ package org.kohsuke.github; * A file inside {@link GHGist} * * @author Kohsuke Kawaguchi - * @see GHGist#getFile(String) - * @see GHGist#getFiles() + * @see GHGist#getFile(String) GHGist#getFile(String) + * @see GHGist#getFiles() GHGist#getFiles() */ public class GHGistFile { /* package almost final */ String fileName; @@ -14,12 +14,19 @@ public class GHGistFile { private String raw_url, type, language, content; private boolean truncated; + /** + * Gets file name. + * + * @return the file name + */ public String getFileName() { return fileName; } /** * File size in bytes. + * + * @return the size */ public int getSize() { return size; @@ -27,6 +34,8 @@ public class GHGistFile { /** * URL that serves this file as-is. + * + * @return the raw url */ public String getRawUrl() { return raw_url; @@ -34,17 +43,26 @@ public class GHGistFile { /** * Content type of this Gist, such as "text/plain" + * + * @return the type */ public String getType() { return type; } + /** + * Gets language. + * + * @return the language + */ public String getLanguage() { return language; } /** * Content of this file. + * + * @return the content */ public String getContent() { return content; @@ -52,6 +70,8 @@ public class GHGistFile { /** * (?) indicates if {@link #getContent()} contains a truncated content. + * + * @return the boolean */ public boolean isTruncated() { return truncated; diff --git a/src/main/java/org/kohsuke/github/GHGistUpdater.java b/src/main/java/org/kohsuke/github/GHGistUpdater.java index 40c37bded..fd9db2a65 100644 --- a/src/main/java/org/kohsuke/github/GHGistUpdater.java +++ b/src/main/java/org/kohsuke/github/GHGistUpdater.java @@ -21,6 +21,17 @@ public class GHGistUpdater { files = new LinkedHashMap<>(); } + /** + * Add file gh gist updater. + * + * @param fileName + * the file name + * @param content + * the content + * @return the gh gist updater + * @throws IOException + * the io exception + */ public GHGistUpdater addFile(String fileName, String content) throws IOException { updateFile(fileName, content); return this; @@ -32,16 +43,45 @@ public class GHGistUpdater { // return this; // } + /** + * Rename file gh gist updater. + * + * @param fileName + * the file name + * @param newFileName + * the new file name + * @return the gh gist updater + * @throws IOException + * the io exception + */ public GHGistUpdater renameFile(String fileName, String newFileName) throws IOException { files.put(fileName, Collections.singletonMap("filename", newFileName)); return this; } + /** + * Update file gh gist updater. + * + * @param fileName + * the file name + * @param content + * the content + * @return the gh gist updater + * @throws IOException + * the io exception + */ public GHGistUpdater updateFile(String fileName, String content) throws IOException { files.put(fileName, Collections.singletonMap("content", content)); return this; } + /** + * Description gh gist updater. + * + * @param desc + * the desc + * @return the gh gist updater + */ public GHGistUpdater description(String desc) { builder.with("description", desc); return this; @@ -49,6 +89,10 @@ public class GHGistUpdater { /** * Updates the Gist based on the parameters specified thus far. + * + * @return the gh gist + * @throws IOException + * the io exception */ public GHGist update() throws IOException { builder._with("files", files); diff --git a/src/main/java/org/kohsuke/github/GHHook.java b/src/main/java/org/kohsuke/github/GHHook.java index 4ede438bb..4b56fb1c4 100644 --- a/src/main/java/org/kohsuke/github/GHHook.java +++ b/src/main/java/org/kohsuke/github/GHHook.java @@ -11,6 +11,8 @@ import java.util.Locale; import java.util.Map; /** + * The type GHHook. + * * @author Kohsuke Kawaguchi */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", @@ -21,10 +23,20 @@ public abstract class GHHook extends GHObject { boolean active; Map config; + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } + /** + * Gets events. + * + * @return the events + */ public EnumSet getEvents() { EnumSet s = EnumSet.noneOf(GHEvent.class); for (String e : events) { @@ -36,15 +48,29 @@ public abstract class GHHook extends GHObject { return s; } + /** + * Is active boolean. + * + * @return the boolean + */ public boolean isActive() { return active; } + /** + * Gets config. + * + * @return the config + */ public Map getConfig() { return Collections.unmodifiableMap(config); } /** + * Ping. + * + * @throws IOException + * the io exception * @see Ping hook */ public void ping() throws IOException { @@ -53,6 +79,9 @@ public abstract class GHHook extends GHObject { /** * Deletes this hook. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { new Requester(getRoot()).method("DELETE").to(getApiRoute()); diff --git a/src/main/java/org/kohsuke/github/GHHooks.java b/src/main/java/org/kohsuke/github/GHHooks.java index 5b994b141..2d2d9af48 100644 --- a/src/main/java/org/kohsuke/github/GHHooks.java +++ b/src/main/java/org/kohsuke/github/GHHooks.java @@ -19,6 +19,13 @@ class GHHooks { this.root = root; } + /** + * Gets hooks. + * + * @return the hooks + * @throws IOException + * the io exception + */ public List getHooks() throws IOException { GHHook[] hookArray = root.retrieve().to(collection(), collectionClass()); // jdk/eclipse bug requires this @@ -29,11 +36,35 @@ class GHHooks { return list; } + /** + * Gets hook. + * + * @param id + * the id + * @return the hook + * @throws IOException + * the io exception + */ public GHHook getHook(int id) throws IOException { GHHook hook = root.retrieve().to(collection() + "/" + id, clazz()); return wrap(hook); } + /** + * Create hook gh hook. + * + * @param name + * the name + * @param config + * the config + * @param events + * the events + * @param active + * the active + * @return the gh hook + * @throws IOException + * the io exception + */ public GHHook createHook(String name, Map config, Collection events, boolean active) throws IOException { List ea = null; diff --git a/src/main/java/org/kohsuke/github/GHIOException.java b/src/main/java/org/kohsuke/github/GHIOException.java index 45dc3404e..bb792ec1a 100644 --- a/src/main/java/org/kohsuke/github/GHIOException.java +++ b/src/main/java/org/kohsuke/github/GHIOException.java @@ -14,13 +14,27 @@ import java.util.Map; public class GHIOException extends IOException { protected Map> responseHeaderFields; + /** + * Instantiates a new Ghio exception. + */ public GHIOException() { } + /** + * Instantiates a new Ghio exception. + * + * @param message + * the message + */ public GHIOException(String message) { super(message); } + /** + * Gets response header fields. + * + * @return the response header fields + */ @CheckForNull public Map> getResponseHeaderFields() { return responseHeaderFields; diff --git a/src/main/java/org/kohsuke/github/GHInvitation.java b/src/main/java/org/kohsuke/github/GHInvitation.java index 5db4eb428..c28c7419b 100644 --- a/src/main/java/org/kohsuke/github/GHInvitation.java +++ b/src/main/java/org/kohsuke/github/GHInvitation.java @@ -6,8 +6,10 @@ import java.io.IOException; import java.net.URL; /** - * @see GitHub#getMyInvitations() - * @see GHRepository#listInvitations() + * The type GHInvitation. + * + * @see GitHub#getMyInvitations() GitHub#getMyInvitations() + * @see GHRepository#listInvitations() GHRepository#listInvitations() */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD", "UUF_UNUSED_FIELD" }, justification = "JSON API") @@ -27,6 +29,9 @@ public class GHInvitation extends GHObject { /** * Accept a repository invitation. + * + * @throws IOException + * the io exception */ public void accept() throws IOException { root.retrieve().method("PATCH").to("/user/repository_invitations/" + id); @@ -34,6 +39,9 @@ public class GHInvitation extends GHObject { /** * Decline a repository invitation. + * + * @throws IOException + * the io exception */ public void decline() throws IOException { root.retrieve().method("DELETE").to("/user/repository_invitations/" + id); diff --git a/src/main/java/org/kohsuke/github/GHIssue.java b/src/main/java/org/kohsuke/github/GHIssue.java index dfd810237..c5eddbdc2 100644 --- a/src/main/java/org/kohsuke/github/GHIssue.java +++ b/src/main/java/org/kohsuke/github/GHIssue.java @@ -45,8 +45,8 @@ import java.util.Set; * * @author Eric Maupin * @author Kohsuke Kawaguchi - * @see GHRepository#getIssue(int) - * @see GitHub#searchIssues() + * @see GHRepository#getIssue(int) GHRepository#getIssue(int) + * @see GitHub#searchIssues() GitHub#searchIssues() * @see GHIssueSearchBuilder */ public class GHIssue extends GHObject implements Reactable { @@ -74,6 +74,8 @@ public class GHIssue extends GHObject implements Reactable { protected boolean locked; /** + * The type Label. + * * @deprecated use {@link GHLabel} */ public static class Label extends GHLabel { @@ -107,6 +109,8 @@ public class GHIssue extends GHObject implements Reactable { /** * Repository to which the issue belongs. + * + * @return the repository */ public GHRepository getRepository() { return owner; @@ -114,6 +118,8 @@ public class GHIssue extends GHObject implements Reactable { /** * The description of this pull request. + * + * @return the body */ public String getBody() { return body; @@ -121,6 +127,8 @@ public class GHIssue extends GHObject implements Reactable { /** * ID. + * + * @return the number */ public int getNumber() { return number; @@ -133,18 +141,40 @@ public class GHIssue extends GHObject implements Reactable { return GitHub.parseURL(html_url); } + /** + * Gets title. + * + * @return the title + */ public String getTitle() { return title; } + /** + * Is locked boolean. + * + * @return the boolean + */ public boolean isLocked() { return locked; } + /** + * Gets state. + * + * @return the state + */ public GHIssueState getState() { return Enum.valueOf(GHIssueState.class, state.toUpperCase(Locale.ENGLISH)); } + /** + * Gets labels. + * + * @return the labels + * @throws IOException + * the io exception + */ public Collection getLabels() throws IOException { if (labels == null) { return Collections.emptyList(); @@ -152,18 +182,40 @@ public class GHIssue extends GHObject implements Reactable { return Collections. unmodifiableList(labels); } + /** + * Gets closed at. + * + * @return the closed at + */ public Date getClosedAt() { return GitHub.parseDate(closed_at); } + /** + * Gets api url. + * + * @return the api url + */ public URL getApiURL() { return GitHub.parseURL(url); } + /** + * Lock. + * + * @throws IOException + * the io exception + */ public void lock() throws IOException { new Requester(root).method("PUT").to(getApiRoute() + "/lock"); } + /** + * Unlock. + * + * @throws IOException + * the io exception + */ public void unlock() throws IOException { new Requester(root).method("PUT").to(getApiRoute() + "/lock"); } @@ -171,7 +223,11 @@ public class GHIssue extends GHObject implements Reactable { /** * Updates the issue by adding a comment. * + * @param message + * the message * @return Newly posted comment. + * @throws IOException + * the io exception */ @WithBridgeMethods(void.class) public GHIssueComment comment(String message) throws IOException { @@ -190,6 +246,9 @@ public class GHIssue extends GHObject implements Reactable { /** * Closes this issue. + * + * @throws IOException + * the io exception */ public void close() throws IOException { edit("state", "closed"); @@ -197,27 +256,70 @@ public class GHIssue extends GHObject implements Reactable { /** * Reopens this issue. + * + * @throws IOException + * the io exception */ public void reopen() throws IOException { edit("state", "open"); } + /** + * Sets title. + * + * @param title + * the title + * @throws IOException + * the io exception + */ public void setTitle(String title) throws IOException { edit("title", title); } + /** + * Sets body. + * + * @param body + * the body + * @throws IOException + * the io exception + */ public void setBody(String body) throws IOException { edit("body", body); } + /** + * Sets milestone. + * + * @param milestone + * the milestone + * @throws IOException + * the io exception + */ public void setMilestone(GHMilestone milestone) throws IOException { edit("milestone", milestone.getNumber()); } + /** + * Assign to. + * + * @param user + * the user + * @throws IOException + * the io exception + */ public void assignTo(GHUser user) throws IOException { setAssignees(user); } + /** + * Sets labels. + * + * @param labels + * the labels + * @throws IOException + * the io exception + */ public void setLabels(String... labels) throws IOException { editIssue("labels", labels); } @@ -227,15 +329,33 @@ public class GHIssue extends GHObject implements Reactable { * * @param names * Names of the label + * @throws IOException + * the io exception */ public void addLabels(String... names) throws IOException { _addLabels(Arrays.asList(names)); } + /** + * Add labels. + * + * @param labels + * the labels + * @throws IOException + * the io exception + */ public void addLabels(GHLabel... labels) throws IOException { addLabels(Arrays.asList(labels)); } + /** + * Add labels. + * + * @param labels + * the labels + * @throws IOException + * the io exception + */ public void addLabels(Collection labels) throws IOException { _addLabels(GHLabel.toNames(labels)); } @@ -256,18 +376,37 @@ public class GHIssue extends GHObject implements Reactable { /** * Remove a given label by name from this issue. + * + * @param names + * the names + * @throws IOException + * the io exception */ public void removeLabels(String... names) throws IOException { _removeLabels(Arrays.asList(names)); } /** - * @see #removeLabels(String...) + * Remove labels. + * + * @param labels + * the labels + * @throws IOException + * the io exception + * @see #removeLabels(String...) #removeLabels(String...) */ public void removeLabels(GHLabel... labels) throws IOException { removeLabels(Arrays.asList(labels)); } + /** + * Remove labels. + * + * @param labels + * the labels + * @throws IOException + * the io exception + */ public void removeLabels(Collection labels) throws IOException { _removeLabels(GHLabel.toNames(labels)); } @@ -287,7 +426,10 @@ public class GHIssue extends GHObject implements Reactable { /** * Obtains all the comments associated with this issue. * - * @see #listComments() + * @return the comments + * @throws IOException + * the io exception + * @see #listComments() #listComments() */ public List getComments() throws IOException { return listComments().asList(); @@ -295,6 +437,10 @@ public class GHIssue extends GHObject implements Reactable { /** * Obtains all the comments associated with this issue. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listComments() throws IOException { return root.retrieve().asPagedIterable(getIssuesApiRoute() + "/comments", GHIssueComment[].class, @@ -315,49 +461,123 @@ public class GHIssue extends GHObject implements Reactable { GHReaction[].class, item -> item.wrap(owner.root)); } + /** + * Add assignees. + * + * @param assignees + * the assignees + * @throws IOException + * the io exception + */ public void addAssignees(GHUser... assignees) throws IOException { addAssignees(Arrays.asList(assignees)); } + /** + * Add assignees. + * + * @param assignees + * the assignees + * @throws IOException + * the io exception + */ public void addAssignees(Collection assignees) throws IOException { root.retrieve().method("POST").withLogins(ASSIGNEES, assignees).to(getIssuesApiRoute() + "/assignees", this); } + /** + * Sets assignees. + * + * @param assignees + * the assignees + * @throws IOException + * the io exception + */ public void setAssignees(GHUser... assignees) throws IOException { setAssignees(Arrays.asList(assignees)); } + /** + * Sets assignees. + * + * @param assignees + * the assignees + * @throws IOException + * the io exception + */ public void setAssignees(Collection assignees) throws IOException { new Requester(root).withLogins(ASSIGNEES, assignees).method("PATCH").to(getIssuesApiRoute()); } + /** + * Remove assignees. + * + * @param assignees + * the assignees + * @throws IOException + * the io exception + */ public void removeAssignees(GHUser... assignees) throws IOException { removeAssignees(Arrays.asList(assignees)); } + /** + * Remove assignees. + * + * @param assignees + * the assignees + * @throws IOException + * the io exception + */ public void removeAssignees(Collection assignees) throws IOException { root.retrieve().method("DELETE").withLogins(ASSIGNEES, assignees).inBody() .to(getIssuesApiRoute() + "/assignees", this); } + /** + * Gets api route. + * + * @return the api route + */ protected String getApiRoute() { return getIssuesApiRoute(); } + /** + * Gets issues api route. + * + * @return the issues api route + */ protected String getIssuesApiRoute() { return "/repos/" + owner.getOwnerName() + "/" + owner.getName() + "/issues/" + number; } + /** + * Gets assignee. + * + * @return the assignee + * @throws IOException + * the io exception + */ public GHUser getAssignee() throws IOException { return root.intern(assignee); } + /** + * Gets assignees. + * + * @return the assignees + */ public List getAssignees() { return Collections.unmodifiableList(Arrays.asList(assignees)); } /** * User who submitted the issue. + * + * @return the user + * @throws IOException + * the io exception */ public GHUser getUser() throws IOException { return root.intern(user); @@ -369,6 +589,10 @@ public class GHIssue extends GHObject implements Reactable { *

* Note that GitHub doesn't always seem to report this information even for an issue that's already closed. See * https://github.com/kohsuke/github-api/issues/60. + * + * @return the closed by + * @throws IOException + * the io exception */ public GHUser getClosedBy() throws IOException { if (!"closed".equals(state)) @@ -381,38 +605,73 @@ public class GHIssue extends GHObject implements Reactable { return root.intern(closed_by); } + /** + * Gets comments count. + * + * @return the comments count + */ public int getCommentsCount() { return comments; } /** * Returns non-null if this issue is a shadow of a pull request. + * + * @return the pull request */ public PullRequest getPullRequest() { return pull_request; } + /** + * Is pull request boolean. + * + * @return the boolean + */ public boolean isPullRequest() { return pull_request != null; } + /** + * Gets milestone. + * + * @return the milestone + */ public GHMilestone getMilestone() { return milestone; } + /** + * The type PullRequest. + */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD" }, justification = "JSON API") public static class PullRequest { private String diff_url, patch_url, html_url; + /** + * Gets diff url. + * + * @return the diff url + */ public URL getDiffUrl() { return GitHub.parseURL(diff_url); } + /** + * Gets patch url. + * + * @return the patch url + */ public URL getPatchUrl() { return GitHub.parseURL(patch_url); } + /** + * Gets url. + * + * @return the url + */ public URL getUrl() { return GitHub.parseURL(html_url); } @@ -420,6 +679,10 @@ public class GHIssue extends GHObject implements Reactable { /** * Lists events for this issue. See https://developer.github.com/v3/issues/events/ + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listEvents() throws IOException { return root.retrieve().asPagedIterable(owner.getApiTailUrl(String.format("/issues/%s/events", number)), diff --git a/src/main/java/org/kohsuke/github/GHIssueBuilder.java b/src/main/java/org/kohsuke/github/GHIssueBuilder.java index e1dbba012..7475d77a1 100644 --- a/src/main/java/org/kohsuke/github/GHIssueBuilder.java +++ b/src/main/java/org/kohsuke/github/GHIssueBuilder.java @@ -5,6 +5,8 @@ import java.util.ArrayList; import java.util.List; /** + * The type GHIssueBuilder. + * * @author Kohsuke Kawaguchi */ public class GHIssueBuilder { @@ -21,30 +23,62 @@ public class GHIssueBuilder { /** * Sets the main text of an issue, which is arbitrary multi-line text. + * + * @param str + * the str + * @return the gh issue builder */ public GHIssueBuilder body(String str) { builder.with("body", str); return this; } + /** + * Assignee gh issue builder. + * + * @param user + * the user + * @return the gh issue builder + */ public GHIssueBuilder assignee(GHUser user) { if (user != null) assignees.add(user.getLogin()); return this; } + /** + * Assignee gh issue builder. + * + * @param user + * the user + * @return the gh issue builder + */ public GHIssueBuilder assignee(String user) { if (user != null) assignees.add(user); return this; } + /** + * Milestone gh issue builder. + * + * @param milestone + * the milestone + * @return the gh issue builder + */ public GHIssueBuilder milestone(GHMilestone milestone) { if (milestone != null) builder.with("milestone", milestone.getNumber()); return this; } + /** + * Label gh issue builder. + * + * @param label + * the label + * @return the gh issue builder + */ public GHIssueBuilder label(String label) { if (label != null) labels.add(label); @@ -53,6 +87,10 @@ public class GHIssueBuilder { /** * Creates a new issue. + * + * @return the gh issue + * @throws IOException + * the io exception */ public GHIssue create() throws IOException { return builder.with("labels", labels).with("assignees", assignees) diff --git a/src/main/java/org/kohsuke/github/GHIssueComment.java b/src/main/java/org/kohsuke/github/GHIssueComment.java index cddc2e02f..d04164b84 100644 --- a/src/main/java/org/kohsuke/github/GHIssueComment.java +++ b/src/main/java/org/kohsuke/github/GHIssueComment.java @@ -32,8 +32,8 @@ import static org.kohsuke.github.Previews.*; * Comment to the issue * * @author Kohsuke Kawaguchi - * @see GHIssue#comment(String) - * @see GHIssue#listComments() + * @see GHIssue#comment(String) GHIssue#comment(String) + * @see GHIssue#listComments() GHIssue#listComments() */ public class GHIssueComment extends GHObject implements Reactable { GHIssue owner; @@ -48,6 +48,8 @@ public class GHIssueComment extends GHObject implements Reactable { /** * Gets the issue to which this comment is associated. + * + * @return the parent */ public GHIssue getParent() { return owner; @@ -55,6 +57,8 @@ public class GHIssueComment extends GHObject implements Reactable { /** * The comment itself. + * + * @return the body */ public String getBody() { return body; @@ -62,6 +66,8 @@ public class GHIssueComment extends GHObject implements Reactable { /** * Gets the ID of the user who posted this comment. + * + * @return the user name */ @Deprecated public String getUserName() { @@ -70,6 +76,10 @@ public class GHIssueComment extends GHObject implements Reactable { /** * Gets the user who posted this comment. + * + * @return the user + * @throws IOException + * the io exception */ public GHUser getUser() throws IOException { return owner == null || owner.root.isOffline() ? user : owner.root.getUser(user.getLogin()); @@ -80,12 +90,22 @@ public class GHIssueComment extends GHObject implements Reactable { return GitHub.parseURL(html_url); } + /** + * Gets author association. + * + * @return the author association + */ public GHCommentAuthorAssociation getAuthorAssociation() { return GHCommentAuthorAssociation.valueOf(author_association); } /** * Updates the body of the issue comment. + * + * @param body + * the body + * @throws IOException + * the io exception */ public void update(String body) throws IOException { new Requester(owner.root).with("body", body).method("PATCH").to(getApiRoute(), GHIssueComment.class); @@ -94,6 +114,9 @@ public class GHIssueComment extends GHObject implements Reactable { /** * Deletes this issue comment. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { new Requester(owner.root).method("DELETE").to(getApiRoute()); diff --git a/src/main/java/org/kohsuke/github/GHIssueEvent.java b/src/main/java/org/kohsuke/github/GHIssueEvent.java index 3f618414c..f74ce20ea 100644 --- a/src/main/java/org/kohsuke/github/GHIssueEvent.java +++ b/src/main/java/org/kohsuke/github/GHIssueEvent.java @@ -3,6 +3,8 @@ package org.kohsuke.github; import java.util.Date; /** + * The type GHIssueEvent. + * * @author Martin van Zijl */ public class GHIssueEvent { @@ -19,42 +21,92 @@ public class GHIssueEvent { private GHIssue issue; + /** + * Gets id. + * + * @return the id + */ public long getId() { return id; } + /** + * Gets node id. + * + * @return the node id + */ public String getNodeId() { return node_id; } + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Gets actor. + * + * @return the actor + */ public GHUser getActor() { return actor; } + /** + * Gets event. + * + * @return the event + */ public String getEvent() { return event; } + /** + * Gets commit id. + * + * @return the commit id + */ public String getCommitId() { return commit_id; } + /** + * Gets commit url. + * + * @return the commit url + */ public String getCommitUrl() { return commit_url; } + /** + * Gets created at. + * + * @return the created at + */ public Date getCreatedAt() { return GitHub.parseDate(created_at); } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Gets issue. + * + * @return the issue + */ public GHIssue getIssue() { return issue; } diff --git a/src/main/java/org/kohsuke/github/GHIssueSearchBuilder.java b/src/main/java/org/kohsuke/github/GHIssueSearchBuilder.java index 49c58aff3..3553ab88a 100644 --- a/src/main/java/org/kohsuke/github/GHIssueSearchBuilder.java +++ b/src/main/java/org/kohsuke/github/GHIssueSearchBuilder.java @@ -4,7 +4,7 @@ package org.kohsuke.github; * Search issues. * * @author Kohsuke Kawaguchi - * @see GitHub#searchIssues() + * @see GitHub#searchIssues() GitHub#searchIssues() */ public class GHIssueSearchBuilder extends GHSearchBuilder { GHIssueSearchBuilder(GitHub root) { @@ -19,36 +19,82 @@ public class GHIssueSearchBuilder extends GHSearchBuilder { return this; } + /** + * Mentions gh issue search builder. + * + * @param u + * the u + * @return the gh issue search builder + */ public GHIssueSearchBuilder mentions(GHUser u) { return mentions(u.getLogin()); } + /** + * Mentions gh issue search builder. + * + * @param login + * the login + * @return the gh issue search builder + */ public GHIssueSearchBuilder mentions(String login) { return q("mentions:" + login); } + /** + * Is open gh issue search builder. + * + * @return the gh issue search builder + */ public GHIssueSearchBuilder isOpen() { return q("is:open"); } + /** + * Is closed gh issue search builder. + * + * @return the gh issue search builder + */ public GHIssueSearchBuilder isClosed() { return q("is:closed"); } + /** + * Is merged gh issue search builder. + * + * @return the gh issue search builder + */ public GHIssueSearchBuilder isMerged() { return q("is:merged"); } + /** + * Order gh issue search builder. + * + * @param v + * the v + * @return the gh issue search builder + */ public GHIssueSearchBuilder order(GHDirection v) { req.with("order", v); return this; } + /** + * Sort gh issue search builder. + * + * @param sort + * the sort + * @return the gh issue search builder + */ public GHIssueSearchBuilder sort(Sort sort) { req.with("sort", sort); return this; } + /** + * The enum Sort. + */ public enum Sort { COMMENTS, CREATED, UPDATED } diff --git a/src/main/java/org/kohsuke/github/GHIssueState.java b/src/main/java/org/kohsuke/github/GHIssueState.java index 4377ea596..603885365 100644 --- a/src/main/java/org/kohsuke/github/GHIssueState.java +++ b/src/main/java/org/kohsuke/github/GHIssueState.java @@ -25,7 +25,9 @@ package org.kohsuke.github; /** - * @see GHPullRequestQueryBuilder#state(GHIssueState) + * The enum GHIssueState. + * + * @see GHPullRequestQueryBuilder#state(GHIssueState) GHPullRequestQueryBuilder#state(GHIssueState) */ public enum GHIssueState { OPEN, CLOSED, ALL diff --git a/src/main/java/org/kohsuke/github/GHKey.java b/src/main/java/org/kohsuke/github/GHKey.java index 8d46b34f6..a8e6477be 100644 --- a/src/main/java/org/kohsuke/github/GHKey.java +++ b/src/main/java/org/kohsuke/github/GHKey.java @@ -16,29 +16,56 @@ public class GHKey { protected boolean verified; protected int id; + /** + * Gets id. + * + * @return the id + */ public int getId() { return id; } + /** + * Gets key. + * + * @return the key + */ public String getKey() { return key; } + /** + * Gets title. + * + * @return the title + */ public String getTitle() { return title; } /** * Something like "https://api.github.com/user/keys/73593" + * + * @return the url */ public String getUrl() { return url; } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Is verified boolean. + * + * @return the boolean + */ public boolean isVerified() { return verified; } diff --git a/src/main/java/org/kohsuke/github/GHLabel.java b/src/main/java/org/kohsuke/github/GHLabel.java index fd737e3d8..608902cec 100644 --- a/src/main/java/org/kohsuke/github/GHLabel.java +++ b/src/main/java/org/kohsuke/github/GHLabel.java @@ -9,24 +9,38 @@ import java.util.Objects; import static org.kohsuke.github.Previews.SYMMETRA; /** + * The type GHLabel. + * * @author Kohsuke Kawaguchi - * @see GHIssue#getLabels() - * @see GHRepository#listLabels() + * @see GHIssue#getLabels() GHIssue#getLabels() + * @see GHRepository#listLabels() GHRepository#listLabels() */ public class GHLabel { private String url, name, color, description; private GHRepository repo; + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } /** * Color code without leading '#', such as 'f29513' + * + * @return the color */ public String getColor() { return color; @@ -34,6 +48,8 @@ public class GHLabel { /** * Purpose of Label + * + * @return the description */ @Preview @Deprecated @@ -46,13 +62,23 @@ public class GHLabel { return this; } + /** + * Delete. + * + * @throws IOException + * the io exception + */ public void delete() throws IOException { repo.root.retrieve().method("DELETE").to(url); } /** + * Sets color. + * * @param newColor * 6-letter hex color code, like "f29513" + * @throws IOException + * the io exception */ public void setColor(String newColor) throws IOException { repo.root.retrieve().method("PATCH").withPreview(SYMMETRA).with("name", name).with("color", newColor) @@ -60,8 +86,12 @@ public class GHLabel { } /** + * Sets description. + * * @param newDescription * Description of label + * @throws IOException + * the io exception */ @Preview @Deprecated diff --git a/src/main/java/org/kohsuke/github/GHLicense.java b/src/main/java/org/kohsuke/github/GHLicense.java index 1cfba97fe..e05a934b2 100644 --- a/src/main/java/org/kohsuke/github/GHLicense.java +++ b/src/main/java/org/kohsuke/github/GHLicense.java @@ -36,8 +36,8 @@ import java.util.List; * The GitHub Preview API's license information * * @author Duncan Dickinson - * @see GitHub#getLicense(String) - * @see GHRepository#getLicense() + * @see GitHub#getLicense(String) GitHub#getLicense(String) + * @see GHRepository#getLicense() GHRepository#getLicense() * @see https://developer.github.com/v3/licenses/ */ @SuppressWarnings({ "UnusedDeclaration" }) @@ -61,6 +61,8 @@ public class GHLicense extends GHObject { protected List forbidden = new ArrayList(); /** + * Gets key. + * * @return a mnemonic for the license */ public String getKey() { @@ -68,6 +70,8 @@ public class GHLicense extends GHObject { } /** + * Gets name. + * * @return the license name */ public String getName() { @@ -86,6 +90,8 @@ public class GHLicense extends GHObject { * Featured licenses are bold in the new repository drop-down * * @return True if the license is featured, false otherwise + * @throws IOException + * the io exception */ public Boolean isFeatured() throws IOException { populate(); @@ -97,36 +103,85 @@ public class GHLicense extends GHObject { return GitHub.parseURL(html_url); } + /** + * Gets description. + * + * @return the description + * @throws IOException + * the io exception + */ public String getDescription() throws IOException { populate(); return description; } + /** + * Gets category. + * + * @return the category + * @throws IOException + * the io exception + */ public String getCategory() throws IOException { populate(); return category; } + /** + * Gets implementation. + * + * @return the implementation + * @throws IOException + * the io exception + */ public String getImplementation() throws IOException { populate(); return implementation; } + /** + * Gets required. + * + * @return the required + * @throws IOException + * the io exception + */ public List getRequired() throws IOException { populate(); return required; } + /** + * Gets permitted. + * + * @return the permitted + * @throws IOException + * the io exception + */ public List getPermitted() throws IOException { populate(); return permitted; } + /** + * Gets forbidden. + * + * @return the forbidden + * @throws IOException + * the io exception + */ public List getForbidden() throws IOException { populate(); return forbidden; } + /** + * Gets body. + * + * @return the body + * @throws IOException + * the io exception + */ public String getBody() throws IOException { populate(); return body; @@ -134,8 +189,11 @@ public class GHLicense extends GHObject { /** * Fully populate the data by retrieving missing data. - * + *

* Depending on the original API call where this object is created, it may not contain everything. + * + * @throws IOException + * the io exception */ protected synchronized void populate() throws IOException { if (description != null) diff --git a/src/main/java/org/kohsuke/github/GHMembership.java b/src/main/java/org/kohsuke/github/GHMembership.java index d5e29ea01..666e229fa 100644 --- a/src/main/java/org/kohsuke/github/GHMembership.java +++ b/src/main/java/org/kohsuke/github/GHMembership.java @@ -8,7 +8,7 @@ import java.util.Locale; * Represents a membership of a user in an organization. * * @author Kohsuke Kawaguchi - * @see GHMyself#listOrgMemberships() + * @see GHMyself#listOrgMemberships() GHMyself#listOrgMemberships() */ public class GHMembership /* extends GHObject --- but it doesn't have id, created_at, etc. */ { GitHub root; @@ -19,22 +19,47 @@ public class GHMembership /* extends GHObject --- but it doesn't have id, create GHUser user; GHOrganization organization; + /** + * Gets url. + * + * @return the url + */ public URL getUrl() { return GitHub.parseURL(url); } + /** + * Gets state. + * + * @return the state + */ public State getState() { return Enum.valueOf(State.class, state.toUpperCase(Locale.ENGLISH)); } + /** + * Gets role. + * + * @return the role + */ public Role getRole() { return Enum.valueOf(Role.class, role.toUpperCase(Locale.ENGLISH)); } + /** + * Gets user. + * + * @return the user + */ public GHUser getUser() { return user; } + /** + * Gets organization. + * + * @return the organization + */ public GHOrganization getOrganization() { return organization; } @@ -42,7 +67,9 @@ public class GHMembership /* extends GHObject --- but it doesn't have id, create /** * Accepts a pending invitation to an organization. * - * @see GHMyself#getMembership(GHOrganization) + * @throws IOException + * the io exception + * @see GHMyself#getMembership(GHOrganization) GHMyself#getMembership(GHOrganization) */ public void activate() throws IOException { root.retrieve().method("PATCH").with("state", State.ACTIVE).to(url, this); diff --git a/src/main/java/org/kohsuke/github/GHMeta.java b/src/main/java/org/kohsuke/github/GHMeta.java index b2a9e22fe..dae6eef3c 100644 --- a/src/main/java/org/kohsuke/github/GHMeta.java +++ b/src/main/java/org/kohsuke/github/GHMeta.java @@ -10,11 +10,9 @@ import java.util.List; * Class that wraps the list of GitHub's IP addresses. * * @author Paulo Miguel Almeida - * - * @see GitHub#getMeta() + * @see GitHub#getMeta() GitHub#getMeta() * @see Get Meta */ - public class GHMeta { @JsonProperty("verifiable_password_authentication") @@ -26,30 +24,65 @@ public class GHMeta { private List pages; private List importer = new ArrayList<>(); + /** + * Is verifiable password authentication boolean. + * + * @return the boolean + */ public boolean isVerifiablePasswordAuthentication() { return verifiablePasswordAuthentication; } + /** + * Gets hooks. + * + * @return the hooks + */ public List getHooks() { return Collections.unmodifiableList(hooks); } + /** + * Gets git. + * + * @return the git + */ public List getGit() { return Collections.unmodifiableList(git); } + /** + * Gets web. + * + * @return the web + */ public List getWeb() { return Collections.unmodifiableList(web); } + /** + * Gets api. + * + * @return the api + */ public List getApi() { return Collections.unmodifiableList(api); } + /** + * Gets pages. + * + * @return the pages + */ public List getPages() { return Collections.unmodifiableList(pages); } + /** + * Gets importer. + * + * @return the importer + */ public List getImporter() { return Collections.unmodifiableList(importer); } diff --git a/src/main/java/org/kohsuke/github/GHMilestone.java b/src/main/java/org/kohsuke/github/GHMilestone.java index 40d5a1eea..fe127fbf2 100644 --- a/src/main/java/org/kohsuke/github/GHMilestone.java +++ b/src/main/java/org/kohsuke/github/GHMilestone.java @@ -6,9 +6,9 @@ import java.util.Date; import java.util.Locale; /** + * The type GHMilestone. * * @author Yusuke Kokubo - * */ public class GHMilestone extends GHObject { GitHub root; @@ -19,18 +19,40 @@ public class GHMilestone extends GHObject { private int closed_issues, open_issues, number; protected String closed_at; + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Gets owner. + * + * @return the owner + */ public GHRepository getOwner() { return owner; } + /** + * Gets creator. + * + * @return the creator + * @throws IOException + * the io exception + */ public GHUser getCreator() throws IOException { return root.intern(creator); } + /** + * Gets due on. + * + * @return the due on + */ public Date getDueOn() { if (due_on == null) return null; @@ -39,27 +61,56 @@ public class GHMilestone extends GHObject { /** * When was this milestone closed? + * + * @return the closed at + * @throws IOException + * the io exception */ public Date getClosedAt() throws IOException { return GitHub.parseDate(closed_at); } + /** + * Gets title. + * + * @return the title + */ public String getTitle() { return title; } + /** + * Gets description. + * + * @return the description + */ public String getDescription() { return description; } + /** + * Gets closed issues. + * + * @return the closed issues + */ public int getClosedIssues() { return closed_issues; } + /** + * Gets open issues. + * + * @return the open issues + */ public int getOpenIssues() { return open_issues; } + /** + * Gets number. + * + * @return the number + */ public int getNumber() { return number; } @@ -68,12 +119,20 @@ public class GHMilestone extends GHObject { return GitHub.parseURL(html_url); } + /** + * Gets state. + * + * @return the state + */ public GHMilestoneState getState() { return Enum.valueOf(GHMilestoneState.class, state.toUpperCase(Locale.ENGLISH)); } /** * Closes this milestone. + * + * @throws IOException + * the io exception */ public void close() throws IOException { edit("state", "closed"); @@ -81,6 +140,9 @@ public class GHMilestone extends GHObject { /** * Reopens this milestone. + * + * @throws IOException + * the io exception */ public void reopen() throws IOException { edit("state", "open"); @@ -88,6 +150,9 @@ public class GHMilestone extends GHObject { /** * Deletes this milestone. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { root.retrieve().method("DELETE").to(getApiRoute()); @@ -97,22 +162,58 @@ public class GHMilestone extends GHObject { new Requester(root)._with(key, value).method("PATCH").to(getApiRoute()); } + /** + * Sets title. + * + * @param title + * the title + * @throws IOException + * the io exception + */ public void setTitle(String title) throws IOException { edit("title", title); } + /** + * Sets description. + * + * @param description + * the description + * @throws IOException + * the io exception + */ public void setDescription(String description) throws IOException { edit("description", description); } + /** + * Sets due on. + * + * @param dueOn + * the due on + * @throws IOException + * the io exception + */ public void setDueOn(Date dueOn) throws IOException { edit("due_on", GitHub.printDate(dueOn)); } + /** + * Gets api route. + * + * @return the api route + */ protected String getApiRoute() { return "/repos/" + owner.getOwnerName() + "/" + owner.getName() + "/milestones/" + number; } + /** + * Wrap gh milestone. + * + * @param repo + * the repo + * @return the gh milestone + */ public GHMilestone wrap(GHRepository repo) { this.owner = repo; this.root = repo.root; diff --git a/src/main/java/org/kohsuke/github/GHMilestoneState.java b/src/main/java/org/kohsuke/github/GHMilestoneState.java index ce4504818..4beb5e34c 100644 --- a/src/main/java/org/kohsuke/github/GHMilestoneState.java +++ b/src/main/java/org/kohsuke/github/GHMilestoneState.java @@ -1,9 +1,9 @@ package org.kohsuke.github; /** + * The enum GHMilestoneState. * * @author Yusuke Kokubo - * */ public enum GHMilestoneState { OPEN, CLOSED diff --git a/src/main/java/org/kohsuke/github/GHMyself.java b/src/main/java/org/kohsuke/github/GHMyself.java index f370aa7c1..d728d7ed8 100644 --- a/src/main/java/org/kohsuke/github/GHMyself.java +++ b/src/main/java/org/kohsuke/github/GHMyself.java @@ -44,6 +44,11 @@ public class GHMyself extends GHUser { } /** + * Gets emails. + * + * @return the emails + * @throws IOException + * the io exception * @deprecated Use {@link #getEmails2()} */ public List getEmails() throws IOException { @@ -57,11 +62,13 @@ public class GHMyself extends GHUser { /** * Returns the read-only list of e-mail addresses configured for you. - * + *

* This corresponds to the stuff you configure in https://github.com/settings/emails, and not to be confused with * {@link #getEmail()} that shows your public e-mail address set in https://github.com/settings/profile * * @return Always non-null. + * @throws IOException + * the io exception */ public List getEmails2() throws IOException { GHEmail[] addresses = root.retrieve().to("/user/emails", GHEmail[].class); @@ -70,11 +77,13 @@ public class GHMyself extends GHUser { /** * Returns the read-only list of all the pulic keys of the current user. - * + *

* NOTE: When using OAuth authenticaiton, the READ/WRITE User scope is required by the GitHub APIs, otherwise you * will get a 404 NOT FOUND. * * @return Always non-null. + * @throws IOException + * the io exception */ public List getPublicKeys() throws IOException { return Collections.unmodifiableList(Arrays.asList(root.retrieve().to("/user/keys", GHKey[].class))); @@ -82,11 +91,13 @@ public class GHMyself extends GHUser { /** * Returns the read-only list of all the public verified keys of the current user. - * + *

* Differently from the getPublicKeys() method, the retrieval of the user's verified public keys does not require * any READ/WRITE OAuth Scope to the user's profile. * * @return Always non-null. + * @throws IOException + * the io exception */ public List getPublicVerifiedKeys() throws IOException { return Collections.unmodifiableList( @@ -95,6 +106,10 @@ public class GHMyself extends GHUser { /** * Gets the organization that this user belongs to. + * + * @return the all organizations + * @throws IOException + * the io exception */ public GHPersonSet getAllOrganizations() throws IOException { GHPersonSet orgs = new GHPersonSet(); @@ -108,6 +123,10 @@ public class GHMyself extends GHUser { /** * Gets the all repositories this user owns (public and private). + * + * @return the all repositories + * @throws IOException + * the io exception */ public synchronized Map getAllRepositories() throws IOException { Map repositories = new TreeMap(); @@ -153,6 +172,7 @@ public class GHMyself extends GHUser { * size for each page of items returned by GitHub. Maximum page size is 100. * @param repoType * type of repository returned in the listing + * @return the paged iterable */ public PagedIterable listRepositories(final int pageSize, final RepositoryListFilter repoType) { return root.retrieve().with("type", repoType) @@ -160,6 +180,9 @@ public class GHMyself extends GHUser { } /** + * List all repositories paged iterable. + * + * @return the paged iterable * @deprecated Use {@link #listRepositories()} */ public PagedIterable listAllRepositories() { @@ -168,6 +191,8 @@ public class GHMyself extends GHUser { /** * List your organization memberships + * + * @return the paged iterable */ public PagedIterable listOrgMemberships() { return listOrgMemberships(null); @@ -178,6 +203,7 @@ public class GHMyself extends GHUser { * * @param state * Filter by a specific state + * @return the paged iterable */ public PagedIterable listOrgMemberships(final GHMembership.State state) { return root.retrieve().with("state", state).asPagedIterable("/user/memberships/orgs", GHMembership[].class, @@ -186,6 +212,12 @@ public class GHMyself extends GHUser { /** * Gets your membership in a specific organization. + * + * @param o + * the o + * @return the membership + * @throws IOException + * the io exception */ public GHMembership getMembership(GHOrganization o) throws IOException { return root.retrieve().to("/user/memberships/orgs/" + o.getLogin(), GHMembership.class).wrap(root); diff --git a/src/main/java/org/kohsuke/github/GHNotificationStream.java b/src/main/java/org/kohsuke/github/GHNotificationStream.java index 4a8e73319..71dd0a3de 100644 --- a/src/main/java/org/kohsuke/github/GHNotificationStream.java +++ b/src/main/java/org/kohsuke/github/GHNotificationStream.java @@ -20,8 +20,8 @@ import java.util.NoSuchElementException; * then quit. This is useful for a batch application to process the current set of notifications. * * @author Kohsuke Kawaguchi - * @see GitHub#listNotifications() - * @see GHRepository#listNotifications() + * @see GitHub#listNotifications() GitHub#listNotifications() + * @see GHRepository#listNotifications() GHRepository#listNotifications() */ public class GHNotificationStream implements Iterable { private final GitHub root; @@ -38,6 +38,10 @@ public class GHNotificationStream implements Iterable { /** * Should the stream include notifications that are already read? + * + * @param v + * the v + * @return the gh notification stream */ public GHNotificationStream read(boolean v) { all = v; @@ -46,16 +50,34 @@ public class GHNotificationStream implements Iterable { /** * Should the stream be restricted to notifications in which the user is directly participating or mentioned? + * + * @param v + * the v + * @return the gh notification stream */ public GHNotificationStream participating(boolean v) { participating = v; return this; } + /** + * Since gh notification stream. + * + * @param timestamp + * the timestamp + * @return the gh notification stream + */ public GHNotificationStream since(long timestamp) { return since(new Date(timestamp)); } + /** + * Since gh notification stream. + * + * @param dt + * the dt + * @return the gh notification stream + */ public GHNotificationStream since(Date dt) { since = GitHub.printDate(dt); return this; @@ -64,6 +86,10 @@ public class GHNotificationStream implements Iterable { /** * If set to true, {@link #iterator()} will stop iterating instead of blocking and waiting for the updates to * arrive. + * + * @param v + * the v + * @return the gh notification stream */ public GHNotificationStream nonBlocking(boolean v) { this.nonBlocking = v; @@ -185,12 +211,23 @@ public class GHNotificationStream implements Iterable { }; } + /** + * Mark as read. + * + * @throws IOException + * the io exception + */ public void markAsRead() throws IOException { markAsRead(-1); } /** * Marks all the notifications as read. + * + * @param timestamp + * the timestamp + * @throws IOException + * the io exception */ public void markAsRead(long timestamp) throws IOException { final Requester req = new Requester(root).method("PUT"); diff --git a/src/main/java/org/kohsuke/github/GHOTPRequiredException.java b/src/main/java/org/kohsuke/github/GHOTPRequiredException.java index 3bfd2e115..64e95e3cc 100644 --- a/src/main/java/org/kohsuke/github/GHOTPRequiredException.java +++ b/src/main/java/org/kohsuke/github/GHOTPRequiredException.java @@ -4,7 +4,6 @@ package org.kohsuke.github; * This exception is thrown when GitHub is requesting an OTP from the user * * @author Kevin Harrington mad.hephaestus@gmail.com - * */ public class GHOTPRequiredException extends GHIOException { // ... diff --git a/src/main/java/org/kohsuke/github/GHObject.java b/src/main/java/org/kohsuke/github/GHObject.java index 425116225..8c657ea69 100644 --- a/src/main/java/org/kohsuke/github/GHObject.java +++ b/src/main/java/org/kohsuke/github/GHObject.java @@ -38,7 +38,7 @@ public abstract class GHObject { *

* Some of the HTTP headers have nothing to do with the object, for example "Cache-Control" and others are different * depending on how this object was retrieved. - * + *

* This method was added as a kind of hack to allow the caller to retrieve OAuth scopes and such. Use with caution. * The method might be removed in the future. * @@ -68,6 +68,8 @@ public abstract class GHObject { } /** + * Gets url. + * * @return API URL of this object. */ @WithBridgeMethods(value = String.class, adapterMethod = "urlToString") @@ -76,6 +78,8 @@ public abstract class GHObject { } /** + * Gets html url. + * * @return URL of this object for humans, which renders some HTML. * @throws IOException * on error @@ -95,6 +99,8 @@ public abstract class GHObject { } /** + * Gets id. + * * @return Unique ID number of this resource. */ @WithBridgeMethods(value = { String.class, int.class }, adapterMethod = "longToStringOrInt") diff --git a/src/main/java/org/kohsuke/github/GHOrganization.java b/src/main/java/org/kohsuke/github/GHOrganization.java index a2366136d..3ed363d3e 100644 --- a/src/main/java/org/kohsuke/github/GHOrganization.java +++ b/src/main/java/org/kohsuke/github/GHOrganization.java @@ -12,6 +12,8 @@ import java.util.TreeMap; import static org.kohsuke.github.Previews.INERTIA; /** + * The type GHOrganization. + * * @author Kohsuke Kawaguchi */ public class GHOrganization extends GHPerson { @@ -22,7 +24,19 @@ public class GHOrganization extends GHPerson { /** * Creates a new repository. * + * @param name + * the name + * @param description + * the description + * @param homepage + * the homepage + * @param team + * the team + * @param isPublic + * the is public * @return Newly created repository. + * @throws IOException + * the io exception * @deprecated Use {@link #createRepository(String)} that uses a builder pattern to let you control every aspect. */ public GHRepository createRepository(String name, String description, String homepage, String team, @@ -34,6 +48,21 @@ public class GHOrganization extends GHPerson { } /** + * Create repository gh repository. + * + * @param name + * the name + * @param description + * the description + * @param homepage + * the homepage + * @param team + * the team + * @param isPublic + * the is public + * @return the gh repository + * @throws IOException + * the io exception * @deprecated Use {@link #createRepository(String)} that uses a builder pattern to let you control every aspect. */ public GHRepository createRepository(String name, String description, String homepage, GHTeam team, @@ -50,6 +79,10 @@ public class GHOrganization extends GHPerson { *

* You use the returned builder to set various properties, then call {@link GHCreateRepositoryBuilder#create()} to * finally createa repository. + * + * @param name + * the name + * @return the gh create repository builder */ public GHCreateRepositoryBuilder createRepository(String name) { return new GHCreateRepositoryBuilder(root, "/orgs/" + login + "/repos", name); @@ -57,6 +90,10 @@ public class GHOrganization extends GHPerson { /** * Teams by their names. + * + * @return the teams + * @throws IOException + * the io exception */ public Map getTeams() throws IOException { Map r = new TreeMap(); @@ -68,6 +105,10 @@ public class GHOrganization extends GHPerson { /** * List up all the teams. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listTeams() throws IOException { return root.retrieve().asPagedIterable(String.format("/orgs/%s/teams", login), GHTeam[].class, @@ -76,6 +117,12 @@ public class GHOrganization extends GHPerson { /** * Finds a team that has the given name in its {@link GHTeam#getName()} + * + * @param name + * the name + * @return the team by name + * @throws IOException + * the io exception */ public GHTeam getTeamByName(String name) throws IOException { for (GHTeam t : listTeams()) { @@ -87,6 +134,12 @@ public class GHOrganization extends GHPerson { /** * Finds a team that has the given slug in its {@link GHTeam#getSlug()} + * + * @param slug + * the slug + * @return the team by slug + * @throws IOException + * the io exception */ public GHTeam getTeamBySlug(String slug) throws IOException { for (GHTeam t : listTeams()) { @@ -96,7 +149,9 @@ public class GHOrganization extends GHPerson { return null; } - /** Member's role in an organization */ + /** + * Member's role in an organization + */ public enum Role { ADMIN, /** The user is an owner of the organization. */ @@ -105,7 +160,13 @@ public class GHOrganization extends GHPerson { /** * Adds (invites) a user to the organization. - * + * + * @param user + * the user + * @param role + * the role + * @throws IOException + * the io exception * @see documentation */ @@ -116,6 +177,10 @@ public class GHOrganization extends GHPerson { /** * Checks if this organization has the specified user as a member. + * + * @param user + * the user + * @return the boolean */ public boolean hasMember(GHUser user) { try { @@ -129,6 +194,11 @@ public class GHOrganization extends GHPerson { /** * Remove a member of the organisation - which will remove them from all teams, and remove their access to the * organization’s repositories. + * + * @param user + * the user + * @throws IOException + * the io exception */ public void remove(GHUser user) throws IOException { root.retrieve().method("DELETE").to("/orgs/" + login + "/members/" + user.getLogin()); @@ -136,6 +206,10 @@ public class GHOrganization extends GHPerson { /** * Checks if this organization has the specified user as a public member. + * + * @param user + * the user + * @return the boolean */ public boolean hasPublicMember(GHUser user) { try { @@ -148,12 +222,22 @@ public class GHOrganization extends GHPerson { /** * Publicizes the membership. + * + * @param u + * the u + * @throws IOException + * the io exception */ public void publicize(GHUser u) throws IOException { root.retrieve().method("PUT").to("/orgs/" + login + "/public_members/" + u.getLogin(), null); } /** + * Gets members. + * + * @return the members + * @throws IOException + * the io exception * @deprecated use {@link #listMembers()} */ public List getMembers() throws IOException { @@ -162,6 +246,10 @@ public class GHOrganization extends GHPerson { /** * All the members of this organization. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listMembers() throws IOException { return listMembers("members"); @@ -169,6 +257,10 @@ public class GHOrganization extends GHPerson { /** * All the public members of this organization. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listPublicMembers() throws IOException { return listMembers("public_members"); @@ -178,6 +270,15 @@ public class GHOrganization extends GHPerson { return listMembers(suffix, null); } + /** + * List members with filter paged iterable. + * + * @param filter + * the filter + * @return the paged iterable + * @throws IOException + * the io exception + */ public PagedIterable listMembersWithFilter(String filter) throws IOException { return listMembers("members", filter); } @@ -190,6 +291,11 @@ public class GHOrganization extends GHPerson { /** * Conceals the membership. + * + * @param u + * the u + * @throws IOException + * the io exception */ public void conceal(GHUser u) throws IOException { root.retrieve().method("DELETE").to("/orgs/" + login + "/public_members/" + u.getLogin(), null); @@ -197,9 +303,12 @@ public class GHOrganization extends GHPerson { /** * Returns the projects for this organization. - * + * * @param status * The status filter (all, open or closed). + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listProjects(final GHProject.ProjectStateFilter status) throws IOException { return root.retrieve().withPreview(INERTIA).with("state", status) @@ -208,6 +317,10 @@ public class GHOrganization extends GHPerson { /** * Returns all open projects for the organization. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listProjects() throws IOException { return listProjects(GHProject.ProjectStateFilter.OPEN); @@ -215,18 +328,39 @@ public class GHOrganization extends GHPerson { /** * Creates a project for the organization. + * + * @param name + * the name + * @param body + * the body + * @return the gh project + * @throws IOException + * the io exception */ public GHProject createProject(String name, String body) throws IOException { return root.retrieve().method("POST").withPreview(INERTIA).with("name", name).with("body", body) .to(String.format("/orgs/%s/projects", login), GHProject.class).wrap(root); } + /** + * The enum Permission. + */ public enum Permission { ADMIN, PUSH, PULL } /** * Creates a new team and assigns the repositories. + * + * @param name + * the name + * @param p + * the p + * @param repositories + * the repositories + * @return the gh team + * @throws IOException + * the io exception */ public GHTeam createTeam(String name, Permission p, Collection repositories) throws IOException { Requester post = new Requester(root).with("name", name).with("permission", p); @@ -238,15 +372,32 @@ public class GHOrganization extends GHPerson { return post.method("POST").to("/orgs/" + login + "/teams", GHTeam.class).wrapUp(this); } + /** + * Create team gh team. + * + * @param name + * the name + * @param p + * the p + * @param repositories + * the repositories + * @return the gh team + * @throws IOException + * the io exception + */ public GHTeam createTeam(String name, Permission p, GHRepository... repositories) throws IOException { return createTeam(name, p, Arrays.asList(repositories)); } /** * List up repositories that has some open pull requests. - * + *

* This used to be an efficient method that didn't involve traversing every repository, but now it doesn't do any * optimization. + * + * @return the repositories with open pull requests + * @throws IOException + * the io exception */ public List getRepositoriesWithOpenPullRequests() throws IOException { List r = new ArrayList(); @@ -262,6 +413,10 @@ public class GHOrganization extends GHPerson { /** * Gets all the open pull requests in this organizataion. + * + * @return the pull requests + * @throws IOException + * the io exception */ public List getPullRequests() throws IOException { List all = new ArrayList(); @@ -296,17 +451,29 @@ public class GHOrganization extends GHPerson { /** * Retrieves the currently configured hooks. + * + * @return the hooks + * @throws IOException + * the io exception */ public List getHooks() throws IOException { return GHHooks.orgContext(this).getHooks(); } + /** + * Gets hook. + * + * @param id + * the id + * @return the hook + * @throws IOException + * the io exception + */ public GHHook getHook(int id) throws IOException { return GHHooks.orgContext(this).getHook(id); } /** - * * See https://api.github.com/hooks for possible names and their configuration scheme. TODO: produce type-safe * binding * @@ -316,16 +483,41 @@ public class GHOrganization extends GHPerson { * The configuration hash. * @param events * Can be null. Types of events to hook into. + * @param active + * the active + * @return the gh hook + * @throws IOException + * the io exception */ public GHHook createHook(String name, Map config, Collection events, boolean active) throws IOException { return GHHooks.orgContext(this).createHook(name, config, events, active); } + /** + * Create web hook gh hook. + * + * @param url + * the url + * @param events + * the events + * @return the gh hook + * @throws IOException + * the io exception + */ public GHHook createWebHook(URL url, Collection events) throws IOException { return createHook("web", Collections.singletonMap("url", url.toExternalForm()), events, true); } + /** + * Create web hook gh hook. + * + * @param url + * the url + * @return the gh hook + * @throws IOException + * the io exception + */ public GHHook createWebHook(URL url) throws IOException { return createWebHook(url, null); } diff --git a/src/main/java/org/kohsuke/github/GHPermission.java b/src/main/java/org/kohsuke/github/GHPermission.java index 2f97576e6..53c5226b8 100644 --- a/src/main/java/org/kohsuke/github/GHPermission.java +++ b/src/main/java/org/kohsuke/github/GHPermission.java @@ -37,16 +37,28 @@ class GHPermission { private GHUser user; /** + * Gets permission. + * * @return one of {@code admin}, {@code write}, {@code read}, or {@code none} */ public String getPermission() { return permission; } + /** + * Gets permission type. + * + * @return the permission type + */ public GHPermissionType getPermissionType() { return Enum.valueOf(GHPermissionType.class, permission.toUpperCase(Locale.ENGLISH)); } + /** + * Gets user. + * + * @return the user + */ public GHUser getUser() { return user; } diff --git a/src/main/java/org/kohsuke/github/GHPermissionType.java b/src/main/java/org/kohsuke/github/GHPermissionType.java index b3f4664f3..26892f3f7 100644 --- a/src/main/java/org/kohsuke/github/GHPermissionType.java +++ b/src/main/java/org/kohsuke/github/GHPermissionType.java @@ -1,6 +1,8 @@ package org.kohsuke.github; /** + * The enum GHPermissionType. + * * @author Kohsuke Kawaguchi */ public enum GHPermissionType { diff --git a/src/main/java/org/kohsuke/github/GHPerson.java b/src/main/java/org/kohsuke/github/GHPerson.java index d93d6f9f4..ffc69ba41 100644 --- a/src/main/java/org/kohsuke/github/GHPerson.java +++ b/src/main/java/org/kohsuke/github/GHPerson.java @@ -34,8 +34,11 @@ public abstract class GHPerson extends GHObject { /** * Fully populate the data by retrieving missing data. - * + *

* Depending on the original API call where this object is created, it may not contain everything. + * + * @throws IOException + * the io exception */ protected synchronized void populate() throws IOException { if (created_at != null) { @@ -52,6 +55,10 @@ public abstract class GHPerson extends GHObject { * *

* To list your own repositories, including private repositories, use {@link GHMyself#listRepositories()} + * + * @return the repositories + * @throws IOException + * the io exception */ public synchronized Map getRepositories() throws IOException { Map repositories = new TreeMap(); @@ -63,8 +70,10 @@ public abstract class GHPerson extends GHObject { /** * Lists up all the repositories using a 30 items page size. - * + *

* Unlike {@link #getRepositories()}, this does not wait until all the repositories are returned. + * + * @return the paged iterable */ public PagedIterable listRepositories() { return listRepositories(30); @@ -74,9 +83,9 @@ public abstract class GHPerson extends GHObject { * Lists up all the repositories using the specified page size. * * @param pageSize - * size for each page of items returned by GitHub. Maximum page size is 100. - * - * Unlike {@link #getRepositories()}, this does not wait until all the repositories are returned. + * size for each page of items returned by GitHub. Maximum page size is 100. Unlike + * {@link #getRepositories()}, this does not wait until all the repositories are returned. + * @return the paged iterable */ public PagedIterable listRepositories(final int pageSize) { return root.retrieve() @@ -90,10 +99,13 @@ public abstract class GHPerson extends GHObject { *

* For a person with a lot of repositories, GitHub returns the list of repositories in a paginated fashion. Unlike * {@link #getRepositories()}, this method allows the caller to start processing data as it arrives. - * + *

* Every {@link Iterator#next()} call results in I/O. Exceptions that occur during the processing is wrapped into * {@link Error}. * + * @param pageSize + * the page size + * @return the iterable * @deprecated Use {@link #listRepositories()} */ @Deprecated @@ -124,8 +136,13 @@ public abstract class GHPerson extends GHObject { } /** + * Gets repository. * + * @param name + * the name * @return null if the repository was not found + * @throws IOException + * the io exception */ public GHRepository getRepository(String name) throws IOException { try { @@ -137,12 +154,17 @@ public abstract class GHPerson extends GHObject { /** * Lists events for an organization or an user. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public abstract PagedIterable listEvents() throws IOException; /** * Gravatar ID of this user, like 0cb9832a01c22c083390f3c5dcb64105 * + * @return the gravatar id * @deprecated No longer available in the v3 API. */ public String getGravatarId() { @@ -152,6 +174,8 @@ public abstract class GHPerson extends GHObject { /** * Returns a string like 'https://secure.gravatar.com/avatar/0cb9832a01c22c083390f3c5dcb64105' that indicates the * avatar image URL. + * + * @return the avatar url */ public String getAvatarUrl() { if (avatar_url != null) @@ -163,6 +187,8 @@ public abstract class GHPerson extends GHObject { /** * Gets the login ID of this user, like 'kohsuke' + * + * @return the login */ public String getLogin() { return login; @@ -170,6 +196,10 @@ public abstract class GHPerson extends GHObject { /** * Gets the human-readable name of the user, like "Kohsuke Kawaguchi" + * + * @return the name + * @throws IOException + * the io exception */ public String getName() throws IOException { populate(); @@ -178,6 +208,10 @@ public abstract class GHPerson extends GHObject { /** * Gets the company name of this user, like "Sun Microsystems, Inc." + * + * @return the company + * @throws IOException + * the io exception */ public String getCompany() throws IOException { populate(); @@ -186,6 +220,10 @@ public abstract class GHPerson extends GHObject { /** * Gets the location of this user, like "Santa Clara, California" + * + * @return the location + * @throws IOException + * the io exception */ public String getLocation() throws IOException { populate(); @@ -204,6 +242,10 @@ public abstract class GHPerson extends GHObject { /** * Gets the blog URL of this user. + * + * @return the blog + * @throws IOException + * the io exception */ public String getBlog() throws IOException { populate(); @@ -217,27 +259,59 @@ public abstract class GHPerson extends GHObject { /** * Gets the e-mail address of the user. + * + * @return the email + * @throws IOException + * the io exception */ public String getEmail() throws IOException { populate(); return email; } + /** + * Gets public gist count. + * + * @return the public gist count + * @throws IOException + * the io exception + */ public int getPublicGistCount() throws IOException { populate(); return public_gists; } + /** + * Gets public repo count. + * + * @return the public repo count + * @throws IOException + * the io exception + */ public int getPublicRepoCount() throws IOException { populate(); return public_repos; } + /** + * Gets following count. + * + * @return the following count + * @throws IOException + * the io exception + */ public int getFollowingCount() throws IOException { populate(); return following; } + /** + * Gets followers count. + * + * @return the followers count + * @throws IOException + * the io exception + */ public int getFollowersCount() throws IOException { populate(); return followers; diff --git a/src/main/java/org/kohsuke/github/GHPersonSet.java b/src/main/java/org/kohsuke/github/GHPersonSet.java index 2a68a3ff5..f0cc5d77a 100644 --- a/src/main/java/org/kohsuke/github/GHPersonSet.java +++ b/src/main/java/org/kohsuke/github/GHPersonSet.java @@ -7,32 +7,67 @@ import java.util.HashSet; /** * Set of {@link GHPerson} with helper lookup methods. * + * @param + * the type parameter * @author Kohsuke Kawaguchi */ public class GHPersonSet extends HashSet { private static final long serialVersionUID = 1L; + /** + * Instantiates a new Gh person set. + */ public GHPersonSet() { } + /** + * Instantiates a new Gh person set. + * + * @param c + * the c + */ public GHPersonSet(Collection c) { super(c); } + /** + * Instantiates a new Gh person set. + * + * @param c + * the c + */ public GHPersonSet(T... c) { super(Arrays.asList(c)); } + /** + * Instantiates a new Gh person set. + * + * @param initialCapacity + * the initial capacity + * @param loadFactor + * the load factor + */ public GHPersonSet(int initialCapacity, float loadFactor) { super(initialCapacity, loadFactor); } + /** + * Instantiates a new Gh person set. + * + * @param initialCapacity + * the initial capacity + */ public GHPersonSet(int initialCapacity) { super(initialCapacity); } /** * Finds the item by its login. + * + * @param login + * the login + * @return the t */ public T byLogin(String login) { for (T t : this) diff --git a/src/main/java/org/kohsuke/github/GHProject.java b/src/main/java/org/kohsuke/github/GHProject.java index 35198666e..c822f6895 100644 --- a/src/main/java/org/kohsuke/github/GHProject.java +++ b/src/main/java/org/kohsuke/github/GHProject.java @@ -32,9 +32,9 @@ import static org.kohsuke.github.Previews.INERTIA; /** * A GitHub project. - * - * @see Projects + * * @author Martin van Zijl + * @see Projects */ public class GHProject extends GHObject { protected GitHub root; @@ -54,10 +54,22 @@ public class GHProject extends GHObject { return GitHub.parseURL(html_url); } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Gets owner. + * + * @return the owner + * @throws IOException + * the io exception + */ public GHObject getOwner() throws IOException { if (owner == null) { try { @@ -75,40 +87,89 @@ public class GHProject extends GHObject { return owner; } + /** + * Gets owner url. + * + * @return the owner url + */ public URL getOwnerUrl() { return GitHub.parseURL(owner_url); } + /** + * Gets node id. + * + * @return the node id + */ public String getNode_id() { return node_id; } + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } + /** + * Gets body. + * + * @return the body + */ public String getBody() { return body; } + /** + * Gets number. + * + * @return the number + */ public int getNumber() { return number; } + /** + * Gets state. + * + * @return the state + */ public ProjectState getState() { return Enum.valueOf(ProjectState.class, state.toUpperCase(Locale.ENGLISH)); } + /** + * Gets creator. + * + * @return the creator + */ public GHUser getCreator() { return creator; } + /** + * Wrap gh project. + * + * @param repo + * the repo + * @return the gh project + */ public GHProject wrap(GHRepository repo) { this.owner = repo; this.root = repo.root; return this; } + /** + * Wrap gh project. + * + * @param root + * the root + * @return the gh project + */ public GHProject wrap(GitHub root) { this.root = root; return this; @@ -118,26 +179,61 @@ public class GHProject extends GHObject { new Requester(root).withPreview(INERTIA)._with(key, value).method("PATCH").to(getApiRoute()); } + /** + * Gets api route. + * + * @return the api route + */ protected String getApiRoute() { return "/projects/" + id; } + /** + * Sets name. + * + * @param name + * the name + * @throws IOException + * the io exception + */ public void setName(String name) throws IOException { edit("name", name); } + /** + * Sets body. + * + * @param body + * the body + * @throws IOException + * the io exception + */ public void setBody(String body) throws IOException { edit("body", body); } + /** + * The enum ProjectState. + */ public enum ProjectState { OPEN, CLOSED } + /** + * Sets state. + * + * @param state + * the state + * @throws IOException + * the io exception + */ public void setState(ProjectState state) throws IOException { edit("state", state.toString().toLowerCase()); } + /** + * The enum ProjectStateFilter. + */ public static enum ProjectStateFilter { ALL, OPEN, CLOSED } @@ -145,6 +241,11 @@ public class GHProject extends GHObject { /** * Set the permission level that all members of the project's organization will have on this project. Only * applicable for organization-owned projects. + * + * @param permission + * the permission + * @throws IOException + * the io exception */ public void setOrganizationPermission(GHPermissionType permission) throws IOException { edit("organization_permission", permission.toString().toLowerCase()); @@ -152,21 +253,48 @@ public class GHProject extends GHObject { /** * Sets visibility of the project within the organization. Only applicable for organization-owned projects. + * + * @param isPublic + * the is public + * @throws IOException + * the io exception */ public void setPublic(boolean isPublic) throws IOException { edit("public", isPublic); } + /** + * Delete. + * + * @throws IOException + * the io exception + */ public void delete() throws IOException { new Requester(root).withPreview(INERTIA).method("DELETE").to(getApiRoute()); } + /** + * List columns paged iterable. + * + * @return the paged iterable + * @throws IOException + * the io exception + */ public PagedIterable listColumns() throws IOException { final GHProject project = this; return root.retrieve().withPreview(INERTIA).asPagedIterable(String.format("/projects/%d/columns", id), GHProjectColumn[].class, item -> item.wrap(project)); } + /** + * Create column gh project column. + * + * @param name + * the name + * @return the gh project column + * @throws IOException + * the io exception + */ public GHProjectColumn createColumn(String name) throws IOException { return root.retrieve().method("POST").withPreview(INERTIA).with("name", name) .to(String.format("/projects/%d/columns", id), GHProjectColumn.class).wrap(this); diff --git a/src/main/java/org/kohsuke/github/GHProjectCard.java b/src/main/java/org/kohsuke/github/GHProjectCard.java index 574c01642..e7cbcbf3f 100644 --- a/src/main/java/org/kohsuke/github/GHProjectCard.java +++ b/src/main/java/org/kohsuke/github/GHProjectCard.java @@ -9,6 +9,8 @@ import java.net.URL; import static org.kohsuke.github.Previews.INERTIA; /** + * The type GHProjectCard. + * * @author Gunnar Skjold */ public class GHProjectCard extends GHObject { @@ -25,11 +27,25 @@ public class GHProjectCard extends GHObject { return null; } + /** + * Wrap gh project card. + * + * @param root + * the root + * @return the gh project card + */ public GHProjectCard wrap(GitHub root) { this.root = root; return this; } + /** + * Wrap gh project card. + * + * @param column + * the column + * @return the gh project card + */ public GHProjectCard wrap(GHProjectColumn column) { this.column = column; this.project = column.project; @@ -37,10 +53,22 @@ public class GHProjectCard extends GHObject { return this; } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Gets project. + * + * @return the project + * @throws IOException + * the io exception + */ public GHProject getProject() throws IOException { if (project == null) { try { @@ -52,6 +80,13 @@ public class GHProjectCard extends GHObject { return project; } + /** + * Gets column. + * + * @return the column + * @throws IOException + * the io exception + */ public GHProjectColumn getColumn() throws IOException { if (column == null) { try { @@ -63,6 +98,13 @@ public class GHProjectCard extends GHObject { return column; } + /** + * Gets content. + * + * @return the content + * @throws IOException + * the io exception + */ public GHIssue getContent() throws IOException { if (StringUtils.isEmpty(content_url)) return null; @@ -77,34 +119,80 @@ public class GHProjectCard extends GHObject { } } + /** + * Gets note. + * + * @return the note + */ public String getNote() { return note; } + /** + * Gets creator. + * + * @return the creator + */ public GHUser getCreator() { return creator; } + /** + * Gets content url. + * + * @return the content url + */ public URL getContentUrl() { return GitHub.parseURL(content_url); } + /** + * Gets project url. + * + * @return the project url + */ public URL getProjectUrl() { return GitHub.parseURL(project_url); } + /** + * Gets column url. + * + * @return the column url + */ public URL getColumnUrl() { return GitHub.parseURL(column_url); } + /** + * Is archived boolean. + * + * @return the boolean + */ public boolean isArchived() { return archived; } + /** + * Sets note. + * + * @param note + * the note + * @throws IOException + * the io exception + */ public void setNote(String note) throws IOException { edit("note", note); } + /** + * Sets archived. + * + * @param archived + * the archived + * @throws IOException + * the io exception + */ public void setArchived(boolean archived) throws IOException { edit("archived", archived); } @@ -113,10 +201,21 @@ public class GHProjectCard extends GHObject { new Requester(root).withPreview(INERTIA)._with(key, value).method("PATCH").to(getApiRoute()); } + /** + * Gets api route. + * + * @return the api route + */ protected String getApiRoute() { return String.format("/projects/columns/cards/%d", id); } + /** + * Delete. + * + * @throws IOException + * the io exception + */ public void delete() throws IOException { new Requester(root).withPreview(INERTIA).method("DELETE").to(getApiRoute()); } diff --git a/src/main/java/org/kohsuke/github/GHProjectColumn.java b/src/main/java/org/kohsuke/github/GHProjectColumn.java index 3846e402d..ac956a5ee 100644 --- a/src/main/java/org/kohsuke/github/GHProjectColumn.java +++ b/src/main/java/org/kohsuke/github/GHProjectColumn.java @@ -7,6 +7,8 @@ import java.net.URL; import static org.kohsuke.github.Previews.INERTIA; /** + * The type GHProjectColumn. + * * @author Gunnar Skjold */ public class GHProjectColumn extends GHObject { @@ -21,21 +23,47 @@ public class GHProjectColumn extends GHObject { return null; } + /** + * Wrap gh project column. + * + * @param root + * the root + * @return the gh project column + */ public GHProjectColumn wrap(GitHub root) { this.root = root; return this; } + /** + * Wrap gh project column. + * + * @param project + * the project + * @return the gh project column + */ public GHProjectColumn wrap(GHProject project) { this.project = project; this.root = project.root; return this; } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Gets project. + * + * @return the project + * @throws IOException + * the io exception + */ public GHProject getProject() throws IOException { if (project == null) { try { @@ -47,14 +75,32 @@ public class GHProjectColumn extends GHObject { return project; } + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } + /** + * Gets project url. + * + * @return the project url + */ public URL getProjectUrl() { return GitHub.parseURL(project_url); } + /** + * Sets name. + * + * @param name + * the name + * @throws IOException + * the io exception + */ public void setName(String name) throws IOException { edit("name", name); } @@ -63,25 +109,61 @@ public class GHProjectColumn extends GHObject { new Requester(root).withPreview(INERTIA)._with(key, value).method("PATCH").to(getApiRoute()); } + /** + * Gets api route. + * + * @return the api route + */ protected String getApiRoute() { return String.format("/projects/columns/%d", id); } + /** + * Delete. + * + * @throws IOException + * the io exception + */ public void delete() throws IOException { new Requester(root).withPreview(INERTIA).method("DELETE").to(getApiRoute()); } + /** + * List cards paged iterable. + * + * @return the paged iterable + * @throws IOException + * the io exception + */ public PagedIterable listCards() throws IOException { final GHProjectColumn column = this; return root.retrieve().withPreview(INERTIA).asPagedIterable(String.format("/projects/columns/%d/cards", id), GHProjectCard[].class, item -> item.wrap(column)); } + /** + * Create card gh project card. + * + * @param note + * the note + * @return the gh project card + * @throws IOException + * the io exception + */ public GHProjectCard createCard(String note) throws IOException { return root.retrieve().method("POST").withPreview(INERTIA).with("note", note) .to(String.format("/projects/columns/%d/cards", id), GHProjectCard.class).wrap(this); } + /** + * Create card gh project card. + * + * @param issue + * the issue + * @return the gh project card + * @throws IOException + * the io exception + */ public GHProjectCard createCard(GHIssue issue) throws IOException { return root.retrieve().method("POST").withPreview(INERTIA) .with("content_type", issue instanceof GHPullRequest ? "PullRequest" : "Issue") diff --git a/src/main/java/org/kohsuke/github/GHPullRequest.java b/src/main/java/org/kohsuke/github/GHPullRequest.java index 3b7e3e120..0ff047b9e 100644 --- a/src/main/java/org/kohsuke/github/GHPullRequest.java +++ b/src/main/java/org/kohsuke/github/GHPullRequest.java @@ -39,7 +39,7 @@ import static org.kohsuke.github.Previews.SHADOW_CAT; * A pull request. * * @author Kohsuke Kawaguchi - * @see GHRepository#getPullRequest(int) + * @see GHRepository#getPullRequest(int) GHRepository#getPullRequest(int) */ @SuppressWarnings({ "UnusedDeclaration" }) public class GHPullRequest extends GHIssue implements Refreshable { @@ -103,6 +103,8 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * The URL of the patch file. like https://github.com/jenkinsci/jenkins/pull/100.patch + * + * @return the patch url */ public URL getPatchUrl() { return GitHub.parseURL(patch_url); @@ -110,6 +112,8 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * The URL of the patch file. like https://github.com/jenkinsci/jenkins/pull/100.patch + * + * @return the issue url */ public URL getIssueUrl() { return GitHub.parseURL(issue_url); @@ -117,6 +121,8 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * This points to where the change should be pulled into, but I'm not really sure what exactly it means. + * + * @return the base */ public GHCommitPointer getBase() { return base; @@ -124,11 +130,20 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * The change that should be pulled. The tip of the commits to merge. + * + * @return the head */ public GHCommitPointer getHead() { return head; } + /** + * Gets issue updated at. + * + * @return the issue updated at + * @throws IOException + * the io exception + */ @Deprecated public Date getIssueUpdatedAt() throws IOException { return super.getUpdatedAt(); @@ -136,11 +151,18 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * The diff file, like https://github.com/jenkinsci/jenkins/pull/100.diff + * + * @return the diff url */ public URL getDiffUrl() { return GitHub.parseURL(diff_url); } + /** + * Gets merged at. + * + * @return the merged at + */ public Date getMergedAt() { return GitHub.parseDate(merged_at); } @@ -165,36 +187,85 @@ public class GHPullRequest extends GHIssue implements Refreshable { // details that are only available via get with ID // + /** + * Gets merged by. + * + * @return the merged by + * @throws IOException + * the io exception + */ public GHUser getMergedBy() throws IOException { populate(); return merged_by; } + /** + * Gets review comments. + * + * @return the review comments + * @throws IOException + * the io exception + */ public int getReviewComments() throws IOException { populate(); return review_comments; } + /** + * Gets additions. + * + * @return the additions + * @throws IOException + * the io exception + */ public int getAdditions() throws IOException { populate(); return additions; } + /** + * Gets commits. + * + * @return the commits + * @throws IOException + * the io exception + */ public int getCommits() throws IOException { populate(); return commits; } + /** + * Is merged boolean. + * + * @return the boolean + * @throws IOException + * the io exception + */ public boolean isMerged() throws IOException { populate(); return merged; } + /** + * Can maintainer modify boolean. + * + * @return the boolean + * @throws IOException + * the io exception + */ public boolean canMaintainerModify() throws IOException { populate(); return maintainer_can_modify; } + /** + * Is draft boolean. + * + * @return the boolean + * @throws IOException + * the io exception + */ public boolean isDraft() throws IOException { populate(); return draft; @@ -206,6 +277,8 @@ public class GHPullRequest extends GHIssue implements Refreshable { * @return null if the state has not been determined yet, for example when a PR is newly created. If this method is * called on an instance whose mergeable state is not yet known, API call is made to retrieve the latest * state. + * @throws IOException + * the io exception */ public Boolean getMergeable() throws IOException { refresh(mergeable); @@ -220,16 +293,37 @@ public class GHPullRequest extends GHIssue implements Refreshable { return mergeable; } + /** + * Gets deletions. + * + * @return the deletions + * @throws IOException + * the io exception + */ public int getDeletions() throws IOException { populate(); return deletions; } + /** + * Gets mergeable state. + * + * @return the mergeable state + * @throws IOException + * the io exception + */ public String getMergeableState() throws IOException { populate(); return mergeable_state; } + /** + * Gets changed files. + * + * @return the changed files + * @throws IOException + * the io exception + */ public int getChangedFiles() throws IOException { populate(); return changed_files; @@ -237,17 +331,35 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * See GitHub blog post + * + * @return the merge commit sha + * @throws IOException + * the io exception */ public String getMergeCommitSha() throws IOException { populate(); return merge_commit_sha; } + /** + * Gets requested reviewers. + * + * @return the requested reviewers + * @throws IOException + * the io exception + */ public List getRequestedReviewers() throws IOException { refresh(requested_reviewers); return Collections.unmodifiableList(Arrays.asList(requested_reviewers)); } + /** + * Gets requested teams. + * + * @return the requested teams + * @throws IOException + * the io exception + */ public List getRequestedTeams() throws IOException { refresh(requested_teams); return Collections.unmodifiableList(Arrays.asList(requested_teams)); @@ -276,6 +388,8 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * Retrieves all the files associated to this pull request. + * + * @return the paged iterable */ public PagedIterable listFiles() { return root.retrieve().asPagedIterable(String.format("%s/files", getApiRoute()), @@ -284,6 +398,8 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * Retrieves all the reviews associated to this pull request. + * + * @return the paged iterable */ public PagedIterable listReviews() { return root.retrieve().asPagedIterable(String.format("%s/reviews", getApiRoute()), GHPullRequestReview[].class, @@ -292,6 +408,10 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * Obtains all the review comments associated with this pull request. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listReviewComments() throws IOException { return root.retrieve().asPagedIterable(getApiRoute() + COMMENTS_ACTION, GHPullRequestReviewComment[].class, @@ -300,6 +420,8 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * Retrieves all the commits associated to this pull request. + * + * @return the paged iterable */ public PagedIterable listCommits() { return root.retrieve().asPagedIterable(String.format("%s/commits", getApiRoute()), @@ -307,6 +429,17 @@ public class GHPullRequest extends GHIssue implements Refreshable { } /** + * Create review gh pull request review. + * + * @param body + * the body + * @param event + * the event + * @param comments + * the comments + * @return the gh pull request review + * @throws IOException + * the io exception * @deprecated Use {@link #createReview()} */ public GHPullRequestReview createReview(String body, @CheckForNull GHPullRequestReviewState event, @@ -315,6 +448,17 @@ public class GHPullRequest extends GHIssue implements Refreshable { } /** + * Create review gh pull request review. + * + * @param body + * the body + * @param event + * the event + * @param comments + * the comments + * @return the gh pull request review + * @throws IOException + * the io exception * @deprecated Use {@link #createReview()} */ public GHPullRequestReview createReview(String body, @CheckForNull GHPullRequestReviewState event, @@ -326,10 +470,30 @@ public class GHPullRequest extends GHIssue implements Refreshable { return b.create(); } + /** + * Create review gh pull request review builder. + * + * @return the gh pull request review builder + */ public GHPullRequestReviewBuilder createReview() { return new GHPullRequestReviewBuilder(this); } + /** + * Create review comment gh pull request review comment. + * + * @param body + * the body + * @param sha + * the sha + * @param path + * the path + * @param position + * the position + * @return the gh pull request review comment + * @throws IOException + * the io exception + */ public GHPullRequestReviewComment createReviewComment(String body, String sha, String path, int position) throws IOException { return new Requester(root).method("POST").with("body", body).with("commit_id", sha).with("path", path) @@ -337,10 +501,26 @@ public class GHPullRequest extends GHIssue implements Refreshable { .wrapUp(this); } + /** + * Request reviewers. + * + * @param reviewers + * the reviewers + * @throws IOException + * the io exception + */ public void requestReviewers(List reviewers) throws IOException { new Requester(root).method("POST").withLogins("reviewers", reviewers).to(getApiRoute() + REQUEST_REVIEWERS); } + /** + * Request team reviewers. + * + * @param teams + * the teams + * @throws IOException + * the io exception + */ public void requestTeamReviewers(List teams) throws IOException { List teamReviewers = new ArrayList(teams.size()); for (GHTeam team : teams) { @@ -351,11 +531,13 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * Merge this pull request. - * + *

* The equivalent of the big green "Merge pull request" button. * * @param msg * Commit message. If null, the default one will be used. + * @throws IOException + * the io exception */ public void merge(String msg) throws IOException { merge(msg, null); @@ -363,13 +545,15 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * Merge this pull request. - * + *

* The equivalent of the big green "Merge pull request" button. * * @param msg * Commit message. If null, the default one will be used. * @param sha * SHA that pull request head must match to allow merge. + * @throws IOException + * the io exception */ public void merge(String msg, String sha) throws IOException { merge(msg, sha, null); @@ -377,19 +561,26 @@ public class GHPullRequest extends GHIssue implements Refreshable { /** * Merge this pull request, using the specified merge method. - * + *

* The equivalent of the big green "Merge pull request" button. * * @param msg * Commit message. If null, the default one will be used. + * @param sha + * the sha * @param method * SHA that pull request head must match to allow merge. + * @throws IOException + * the io exception */ public void merge(String msg, String sha, MergeMethod method) throws IOException { new Requester(root).method("PUT").with("commit_message", msg).with("sha", sha).with("merge_method", method) .to(getApiRoute() + "/merge"); } + /** + * The enum MergeMethod. + */ public enum MergeMethod { MERGE, SQUASH, REBASE } diff --git a/src/main/java/org/kohsuke/github/GHPullRequestCommitDetail.java b/src/main/java/org/kohsuke/github/GHPullRequestCommitDetail.java index cc2311e1d..77528ee99 100644 --- a/src/main/java/org/kohsuke/github/GHPullRequestCommitDetail.java +++ b/src/main/java/org/kohsuke/github/GHPullRequestCommitDetail.java @@ -32,7 +32,7 @@ import java.net.URL; * Commit detail inside a {@link GHPullRequest}. * * @author Luca Milanesio - * @see GHPullRequest#listCommits() + * @see GHPullRequest#listCommits() GHPullRequest#listCommits() */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD", "URF_UNREAD_FIELD" }, justification = "JSON API") @@ -44,24 +44,42 @@ public class GHPullRequestCommitDetail { } /** + * The type Authorship. + * * @deprecated Use {@link GitUser} */ public static class Authorship extends GitUser { } + /** + * The type Tree. + */ public static class Tree { String sha; String url; + /** + * Gets sha. + * + * @return the sha + */ public String getSha() { return sha; } + /** + * Gets url. + * + * @return the url + */ public URL getUrl() { return GitHub.parseURL(url); } } + /** + * The type Commit. + */ public static class Commit { Authorship author; Authorship committer; @@ -70,46 +88,94 @@ public class GHPullRequestCommitDetail { String url; int comment_count; + /** + * Gets author. + * + * @return the author + */ @WithBridgeMethods(value = Authorship.class, castRequired = true) public GitUser getAuthor() { return author; } + /** + * Gets committer. + * + * @return the committer + */ @WithBridgeMethods(value = Authorship.class, castRequired = true) public GitUser getCommitter() { return committer; } + /** + * Gets message. + * + * @return the message + */ public String getMessage() { return message; } + /** + * Gets url. + * + * @return the url + */ public URL getUrl() { return GitHub.parseURL(url); } + /** + * Gets comment count. + * + * @return the comment count + */ public int getComment_count() { return comment_count; } + /** + * Gets tree. + * + * @return the tree + */ public Tree getTree() { return tree; } } + /** + * The type CommitPointer. + */ public static class CommitPointer { String sha; String url; String html_url; + /** + * Gets url. + * + * @return the url + */ public URL getUrl() { return GitHub.parseURL(url); } + /** + * Gets html url. + * + * @return the html url + */ public URL getHtml_url() { return GitHub.parseURL(html_url); } + /** + * Gets sha. + * + * @return the sha + */ public String getSha() { return sha; } @@ -122,26 +188,56 @@ public class GHPullRequestCommitDetail { String comments_url; CommitPointer[] parents; + /** + * Gets sha. + * + * @return the sha + */ public String getSha() { return sha; } + /** + * Gets commit. + * + * @return the commit + */ public Commit getCommit() { return commit; } + /** + * Gets api url. + * + * @return the api url + */ public URL getApiUrl() { return GitHub.parseURL(url); } + /** + * Gets url. + * + * @return the url + */ public URL getUrl() { return GitHub.parseURL(html_url); } + /** + * Gets comments url. + * + * @return the comments url + */ public URL getCommentsUrl() { return GitHub.parseURL(comments_url); } + /** + * Get parents commit pointer [ ]. + * + * @return the commit pointer [ ] + */ public CommitPointer[] getParents() { CommitPointer[] newValue = new CommitPointer[parents.length]; System.arraycopy(parents, 0, newValue, 0, parents.length); diff --git a/src/main/java/org/kohsuke/github/GHPullRequestFileDetail.java b/src/main/java/org/kohsuke/github/GHPullRequestFileDetail.java index d0129e282..17f5780ea 100644 --- a/src/main/java/org/kohsuke/github/GHPullRequestFileDetail.java +++ b/src/main/java/org/kohsuke/github/GHPullRequestFileDetail.java @@ -29,7 +29,7 @@ import java.net.URL; * File detail inside a {@link GHPullRequest}. * * @author Julien Henry - * @see GHPullRequest#listFiles() + * @see GHPullRequest#listFiles() GHPullRequest#listFiles() */ public class GHPullRequestFileDetail { @@ -45,46 +45,101 @@ public class GHPullRequestFileDetail { String patch; String previous_filename; + /** + * Gets sha. + * + * @return the sha + */ public String getSha() { return sha; } + /** + * Gets filename. + * + * @return the filename + */ public String getFilename() { return filename; } + /** + * Gets status. + * + * @return the status + */ public String getStatus() { return status; } + /** + * Gets additions. + * + * @return the additions + */ public int getAdditions() { return additions; } + /** + * Gets deletions. + * + * @return the deletions + */ public int getDeletions() { return deletions; } + /** + * Gets changes. + * + * @return the changes + */ public int getChanges() { return changes; } + /** + * Gets blob url. + * + * @return the blob url + */ public URL getBlobUrl() { return GitHub.parseURL(blob_url); } + /** + * Gets raw url. + * + * @return the raw url + */ public URL getRawUrl() { return GitHub.parseURL(raw_url); } + /** + * Gets contents url. + * + * @return the contents url + */ public URL getContentsUrl() { return GitHub.parseURL(contents_url); } + /** + * Gets patch. + * + * @return the patch + */ public String getPatch() { return patch; } + /** + * Gets previous filename. + * + * @return the previous filename + */ public String getPreviousFilename() { return previous_filename; } diff --git a/src/main/java/org/kohsuke/github/GHPullRequestQueryBuilder.java b/src/main/java/org/kohsuke/github/GHPullRequestQueryBuilder.java index 10d1bc276..787503d43 100644 --- a/src/main/java/org/kohsuke/github/GHPullRequestQueryBuilder.java +++ b/src/main/java/org/kohsuke/github/GHPullRequestQueryBuilder.java @@ -6,7 +6,7 @@ import static org.kohsuke.github.Previews.SHADOW_CAT; * Lists up pull requests with some filtering and sorting. * * @author Kohsuke Kawaguchi - * @see GHRepository#queryPullRequests() + * @see GHRepository#queryPullRequests() GHRepository#queryPullRequests() */ public class GHPullRequestQueryBuilder extends GHQueryBuilder { private final GHRepository repo; @@ -16,11 +16,25 @@ public class GHPullRequestQueryBuilder extends GHQueryBuilder { this.repo = repo; } + /** + * State gh pull request query builder. + * + * @param state + * the state + * @return the gh pull request query builder + */ public GHPullRequestQueryBuilder state(GHIssueState state) { req.with("state", state); return this; } + /** + * Head gh pull request query builder. + * + * @param head + * the head + * @return the gh pull request query builder + */ public GHPullRequestQueryBuilder head(String head) { if (head != null && !head.contains(":")) { head = repo.getOwnerName() + ":" + head; @@ -29,20 +43,44 @@ public class GHPullRequestQueryBuilder extends GHQueryBuilder { return this; } + /** + * Base gh pull request query builder. + * + * @param base + * the base + * @return the gh pull request query builder + */ public GHPullRequestQueryBuilder base(String base) { req.with("base", base); return this; } + /** + * Sort gh pull request query builder. + * + * @param sort + * the sort + * @return the gh pull request query builder + */ public GHPullRequestQueryBuilder sort(Sort sort) { req.with("sort", sort); return this; } + /** + * The enum Sort. + */ public enum Sort { CREATED, UPDATED, POPULARITY, LONG_RUNNING } + /** + * Direction gh pull request query builder. + * + * @param d + * the d + * @return the gh pull request query builder + */ public GHPullRequestQueryBuilder direction(GHDirection d) { req.with("direction", d); return this; diff --git a/src/main/java/org/kohsuke/github/GHPullRequestReview.java b/src/main/java/org/kohsuke/github/GHPullRequestReview.java index 9ea06dd2b..ecf8a51cf 100644 --- a/src/main/java/org/kohsuke/github/GHPullRequestReview.java +++ b/src/main/java/org/kohsuke/github/GHPullRequestReview.java @@ -33,7 +33,7 @@ import java.net.URL; /** * Review to a pull request. * - * @see GHPullRequest#listReviews() + * @see GHPullRequest#listReviews() GHPullRequest#listReviews() * @see GHPullRequestReviewBuilder */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_FIELD" }, justification = "JSON API") @@ -53,6 +53,8 @@ public class GHPullRequestReview extends GHObject { /** * Gets the pull request to which this review is associated. + * + * @return the parent */ public GHPullRequest getParent() { return owner; @@ -60,6 +62,8 @@ public class GHPullRequestReview extends GHObject { /** * The comment itself. + * + * @return the body */ public String getBody() { return body; @@ -67,15 +71,29 @@ public class GHPullRequestReview extends GHObject { /** * Gets the user who posted this review. + * + * @return the user + * @throws IOException + * the io exception */ public GHUser getUser() throws IOException { return owner.root.getUser(user.getLogin()); } + /** + * Gets commit id. + * + * @return the commit id + */ public String getCommitId() { return commit_id; } + /** + * Gets state. + * + * @return the state + */ @CheckForNull public GHPullRequestReviewState getState() { return state; @@ -86,12 +104,21 @@ public class GHPullRequestReview extends GHObject { return null; } + /** + * Gets api route. + * + * @return the api route + */ protected String getApiRoute() { return owner.getApiRoute() + "/reviews/" + id; } /** * When was this resource created? + * + * @return the submitted at + * @throws IOException + * the io exception */ public Date getSubmittedAt() throws IOException { return GitHub.parseDate(submitted_at); @@ -106,6 +133,14 @@ public class GHPullRequestReview extends GHObject { } /** + * Submit. + * + * @param body + * the body + * @param state + * the state + * @throws IOException + * the io exception * @deprecated Former preview method that changed when it got public. Left here for backward compatibility. Use * {@link #submit(String, GHPullRequestReviewEvent)} */ @@ -115,6 +150,13 @@ public class GHPullRequestReview extends GHObject { /** * Updates the comment. + * + * @param body + * the body + * @param event + * the event + * @throws IOException + * the io exception */ public void submit(String body, GHPullRequestReviewEvent event) throws IOException { new Requester(owner.root).method("POST").with("body", body).with("event", event.action()) @@ -125,6 +167,9 @@ public class GHPullRequestReview extends GHObject { /** * Deletes this review. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { new Requester(owner.root).method("DELETE").to(getApiRoute()); @@ -132,6 +177,11 @@ public class GHPullRequestReview extends GHObject { /** * Dismisses this review. + * + * @param message + * the message + * @throws IOException + * the io exception */ public void dismiss(String message) throws IOException { new Requester(owner.root).method("PUT").with("message", message).to(getApiRoute() + "/dismissals"); @@ -140,6 +190,10 @@ public class GHPullRequestReview extends GHObject { /** * Obtains all the review comments associated with this pull request review. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listReviewComments() throws IOException { return owner.root.retrieve().asPagedIterable(getApiRoute() + "/comments", GHPullRequestReviewComment[].class, diff --git a/src/main/java/org/kohsuke/github/GHPullRequestReviewBuilder.java b/src/main/java/org/kohsuke/github/GHPullRequestReviewBuilder.java index 4649d1f1f..80a54cf58 100644 --- a/src/main/java/org/kohsuke/github/GHPullRequestReviewBuilder.java +++ b/src/main/java/org/kohsuke/github/GHPullRequestReviewBuilder.java @@ -8,7 +8,7 @@ import java.util.List; * Builds up a creation of new {@link GHPullRequestReview}. * * @author Kohsuke Kawaguchi - * @see GHPullRequest#createReview() + * @see GHPullRequest#createReview() GHPullRequest#createReview() */ public class GHPullRequestReviewBuilder { private final GHPullRequest pr; @@ -27,6 +27,10 @@ public class GHPullRequestReviewBuilder { * The SHA of the commit that needs a review. Not using the latest commit SHA may render your review comment * outdated if a subsequent commit modifies the line you specify as the position. Defaults to the most recent commit * in the pull request when you do not specify a value. + * + * @param commitId + * the commit id + * @return the gh pull request review builder */ public GHPullRequestReviewBuilder commitId(String commitId) { builder.with("commit_id", commitId); @@ -35,6 +39,10 @@ public class GHPullRequestReviewBuilder { /** * Required when using REQUEST_CHANGES or COMMENT for the event parameter. The body text of the pull request review. + * + * @param body + * the body + * @return the gh pull request review builder */ public GHPullRequestReviewBuilder body(String body) { builder.with("body", body); @@ -46,6 +54,10 @@ public class GHPullRequestReviewBuilder { * leaving this blank, you set the review action state to PENDING, which means you will need to * {@linkplain GHPullRequestReview#submit(String, GHPullRequestReviewEvent) submit the pull request review} when you * are ready. + * + * @param event + * the event + * @return the gh pull request review builder */ public GHPullRequestReviewBuilder event(GHPullRequestReviewEvent event) { builder.with("event", event.action()); @@ -53,6 +65,8 @@ public class GHPullRequestReviewBuilder { } /** + * Comment gh pull request review builder. + * * @param body * The relative path to the file that necessitates a review comment. * @param path @@ -60,12 +74,20 @@ public class GHPullRequestReviewBuilder { * the line number in the file. For help finding the position value, read the note below. * @param position * Text of the review comment. + * @return the gh pull request review builder */ public GHPullRequestReviewBuilder comment(String body, String path, int position) { comments.add(new DraftReviewComment(body, path, position)); return this; } + /** + * Create gh pull request review. + * + * @return the gh pull request review + * @throws IOException + * the io exception + */ public GHPullRequestReview create() throws IOException { return builder.method("POST")._with("comments", comments) .to(pr.getApiRoute() + "/reviews", GHPullRequestReview.class).wrapUp(pr); @@ -82,14 +104,29 @@ public class GHPullRequestReviewBuilder { this.position = position; } + /** + * Gets body. + * + * @return the body + */ public String getBody() { return body; } + /** + * Gets path. + * + * @return the path + */ public String getPath() { return path; } + /** + * Gets position. + * + * @return the position + */ public int getPosition() { return position; } diff --git a/src/main/java/org/kohsuke/github/GHPullRequestReviewComment.java b/src/main/java/org/kohsuke/github/GHPullRequestReviewComment.java index 1804d47e9..108747112 100644 --- a/src/main/java/org/kohsuke/github/GHPullRequestReviewComment.java +++ b/src/main/java/org/kohsuke/github/GHPullRequestReviewComment.java @@ -33,8 +33,9 @@ import static org.kohsuke.github.Previews.*; * Review comment to the pull request * * @author Julien Henry - * @see GHPullRequest#listReviewComments() - * @see GHPullRequest#createReviewComment(String, String, String, int) + * @see GHPullRequest#listReviewComments() GHPullRequest#listReviewComments() + * @see GHPullRequest#createReviewComment(String, String, String, int) GHPullRequest#createReviewComment(String, String, + * String, int) */ public class GHPullRequestReviewComment extends GHObject implements Reactable { GHPullRequest owner; @@ -47,6 +48,15 @@ public class GHPullRequestReviewComment extends GHObject implements Reactable { private long in_reply_to_id = -1L; /** + * Draft gh pull request review comment. + * + * @param body + * the body + * @param path + * the path + * @param position + * the position + * @return the gh pull request review comment * @deprecated You should be using {@link GHPullRequestReviewBuilder#comment(String, String, int)} */ public static GHPullRequestReviewComment draft(String body, String path, int position) { @@ -64,6 +74,8 @@ public class GHPullRequestReviewComment extends GHObject implements Reactable { /** * Gets the pull request to which this review comment is associated. + * + * @return the parent */ public GHPullRequest getParent() { return owner; @@ -71,6 +83,8 @@ public class GHPullRequestReviewComment extends GHObject implements Reactable { /** * The comment itself. + * + * @return the body */ public String getBody() { return body; @@ -78,24 +92,48 @@ public class GHPullRequestReviewComment extends GHObject implements Reactable { /** * Gets the user who posted this comment. + * + * @return the user + * @throws IOException + * the io exception */ public GHUser getUser() throws IOException { return owner.root.getUser(user.getLogin()); } + /** + * Gets path. + * + * @return the path + */ public String getPath() { return path; } + /** + * Gets position. + * + * @return the position + */ @CheckForNull public int getPosition() { return position; } + /** + * Gets original position. + * + * @return the original position + */ public int getOriginalPosition() { return original_position; } + /** + * Gets in reply to id. + * + * @return the in reply to id + */ @CheckForNull public long getInReplyToId() { return in_reply_to_id; @@ -106,12 +144,22 @@ public class GHPullRequestReviewComment extends GHObject implements Reactable { return null; } + /** + * Gets api route. + * + * @return the api route + */ protected String getApiRoute() { return "/repos/" + owner.getRepository().getFullName() + "/pulls/comments/" + id; } /** * Updates the comment. + * + * @param body + * the body + * @throws IOException + * the io exception */ public void update(String body) throws IOException { new Requester(owner.root).method("PATCH").with("body", body).to(getApiRoute(), this); @@ -120,6 +168,9 @@ public class GHPullRequestReviewComment extends GHObject implements Reactable { /** * Deletes this review comment. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { new Requester(owner.root).method("DELETE").to(getApiRoute()); @@ -127,6 +178,12 @@ public class GHPullRequestReviewComment extends GHObject implements Reactable { /** * Create a new comment that replies to this comment. + * + * @param body + * the body + * @return the gh pull request review comment + * @throws IOException + * the io exception */ public GHPullRequestReviewComment reply(String body) throws IOException { return new Requester(owner.root).method("POST").with("body", body).with("in_reply_to", getId()) diff --git a/src/main/java/org/kohsuke/github/GHPullRequestReviewState.java b/src/main/java/org/kohsuke/github/GHPullRequestReviewState.java index 5f1c0c06e..7403992bb 100644 --- a/src/main/java/org/kohsuke/github/GHPullRequestReviewState.java +++ b/src/main/java/org/kohsuke/github/GHPullRequestReviewState.java @@ -12,6 +12,9 @@ public enum GHPullRequestReviewState { REQUEST_CHANGES, COMMENTED, DISMISSED; /** + * Action string. + * + * @return the string * @deprecated This was an internal method accidentally exposed. Left here for compatibility. */ public String action() { diff --git a/src/main/java/org/kohsuke/github/GHQueryBuilder.java b/src/main/java/org/kohsuke/github/GHQueryBuilder.java index bf26fa567..be63c7b32 100644 --- a/src/main/java/org/kohsuke/github/GHQueryBuilder.java +++ b/src/main/java/org/kohsuke/github/GHQueryBuilder.java @@ -3,6 +3,8 @@ package org.kohsuke.github; /** * Used to specify filters, sort order, etc for listing items in a collection. * + * @param + * the type parameter * @author Kohsuke Kawaguchi */ public abstract class GHQueryBuilder { @@ -16,6 +18,8 @@ public abstract class GHQueryBuilder { /** * Start listing items by using the settings built up on this object. + * + * @return the paged iterable */ public abstract PagedIterable list(); } diff --git a/src/main/java/org/kohsuke/github/GHRateLimit.java b/src/main/java/org/kohsuke/github/GHRateLimit.java index f99c848fa..251b54fa3 100644 --- a/src/main/java/org/kohsuke/github/GHRateLimit.java +++ b/src/main/java/org/kohsuke/github/GHRateLimit.java @@ -204,10 +204,10 @@ public class GHRateLimit { /** * A limit record used as a placeholder when the the actual limit is not known. - * + *

* Has a large limit and long duration so that it will doesn't expire too often. * - * @since 1.100* + * @since 1.100 */ public static class UnknownLimitRecord extends Record { @@ -224,7 +224,7 @@ public class GHRateLimit { /** * A rate limit record. - * + * * @since 1.100 */ public static class Record { @@ -255,12 +255,34 @@ public class GHRateLimit { @Nonnull private Date resetDate; + /** + * Instantiates a new Record. + * + * @param limit + * the limit + * @param remaining + * the remaining + * @param resetEpochSeconds + * the reset epoch seconds + */ @JsonCreator public Record(@JsonProperty("limit") int limit, @JsonProperty("remaining") int remaining, @JsonProperty("reset") long resetEpochSeconds) { this(limit, remaining, resetEpochSeconds, null); } + /** + * Instantiates a new Record. + * + * @param limit + * the limit + * @param remaining + * the remaining + * @param resetEpochSeconds + * the reset epoch seconds + * @param updatedAt + * the updated at + */ @SuppressFBWarnings(value = "URF_UNREAD_PUBLIC_OR_PROTECTED_FIELD", justification = "Deprecated") public Record(int limit, int remaining, long resetEpochSeconds, String updatedAt) { this.limit = limit; diff --git a/src/main/java/org/kohsuke/github/GHReaction.java b/src/main/java/org/kohsuke/github/GHReaction.java index e809516ca..ced6792b4 100644 --- a/src/main/java/org/kohsuke/github/GHReaction.java +++ b/src/main/java/org/kohsuke/github/GHReaction.java @@ -27,6 +27,8 @@ public class GHReaction extends GHObject { /** * The kind of reaction left. + * + * @return the content */ public ReactionContent getContent() { return content; @@ -34,6 +36,8 @@ public class GHReaction extends GHObject { /** * User who left the reaction. + * + * @return the user */ public GHUser getUser() { return user; @@ -49,6 +53,9 @@ public class GHReaction extends GHObject { /** * Removes this reaction. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { new Requester(root).method("DELETE").withPreview(SQUIRREL_GIRL).to("/reactions/" + id); diff --git a/src/main/java/org/kohsuke/github/GHRef.java b/src/main/java/org/kohsuke/github/GHRef.java index f8ff99751..529eacc3c 100644 --- a/src/main/java/org/kohsuke/github/GHRef.java +++ b/src/main/java/org/kohsuke/github/GHRef.java @@ -18,6 +18,8 @@ public class GHRef { /** * Name of the ref, such as "refs/tags/abc" + * + * @return the ref */ public String getRef() { return ref; @@ -25,6 +27,8 @@ public class GHRef { /** * The API URL of this tag, such as https://api.github.com/repos/jenkinsci/jenkins/git/refs/tags/1.312 + * + * @return the url */ public URL getUrl() { return GitHub.parseURL(url); @@ -32,6 +36,8 @@ public class GHRef { /** * The object that this ref points to. + * + * @return the object */ public GHObject getObject() { return object; @@ -42,6 +48,8 @@ public class GHRef { * * @param sha * The SHA1 value to set this reference to + * @throws IOException + * the io exception */ public void updateTo(String sha) throws IOException { updateTo(sha, false); @@ -54,6 +62,8 @@ public class GHRef { * The SHA1 value to set this reference to * @param force * Whether or not to force this ref update. + * @throws IOException + * the io exception */ public void updateTo(String sha, Boolean force) throws IOException { new Requester(root).with("sha", sha).with("force", force).method("PATCH").to(url, GHRef.class).wrap(root); @@ -61,6 +71,9 @@ public class GHRef { /** * Deletes this ref from the repository using the GitHub API. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { new Requester(root).method("DELETE").to(url); @@ -78,6 +91,9 @@ public class GHRef { return in; } + /** + * The type GHObject. + */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD" }, justification = "JSON API") public static class GHObject { @@ -85,6 +101,8 @@ public class GHRef { /** * Type of the object, such as "commit" + * + * @return the type */ public String getType() { return type; @@ -92,6 +110,8 @@ public class GHRef { /** * SHA1 of this object. + * + * @return the sha */ public String getSha() { return sha; @@ -100,6 +120,8 @@ public class GHRef { /** * API URL to this Git data, such as * https://api.github.com/repos/jenkinsci/jenkins/git/commits/b72322675eb0114363a9a86e9ad5a170d1d07ac0 + * + * @return the url */ public URL getUrl() { return GitHub.parseURL(url); diff --git a/src/main/java/org/kohsuke/github/GHRelease.java b/src/main/java/org/kohsuke/github/GHRelease.java index f7e81e218..5f5ed2aed 100644 --- a/src/main/java/org/kohsuke/github/GHRelease.java +++ b/src/main/java/org/kohsuke/github/GHRelease.java @@ -14,8 +14,8 @@ import static java.lang.String.*; /** * Release in a github repository. * - * @see GHRepository#getReleases() - * @see GHRepository#createRelease(String) + * @see GHRepository#getReleases() GHRepository#getReleases() + * @see GHRepository#createRelease(String) GHRepository#createRelease(String) */ public class GHRelease extends GHObject { GitHub root; @@ -34,19 +34,41 @@ public class GHRelease extends GHObject { private String tarball_url; private String zipball_url; + /** + * Gets assets url. + * + * @return the assets url + */ public String getAssetsUrl() { return assets_url; } + /** + * Gets body. + * + * @return the body + */ public String getBody() { return body; } + /** + * Is draft boolean. + * + * @return the boolean + */ public boolean isDraft() { return draft; } /** + * Sets draft. + * + * @param draft + * the draft + * @return the draft + * @throws IOException + * the io exception * @deprecated Use {@link #update()} */ public GHRelease setDraft(boolean draft) throws IOException { @@ -57,50 +79,112 @@ public class GHRelease extends GHObject { return GitHub.parseURL(html_url); } + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } + /** + * Sets name. + * + * @param name + * the name + */ public void setName(String name) { this.name = name; } + /** + * Gets owner. + * + * @return the owner + */ public GHRepository getOwner() { return owner; } + /** + * Sets owner. + * + * @param owner + * the owner + */ public void setOwner(GHRepository owner) { this.owner = owner; } + /** + * Is prerelease boolean. + * + * @return the boolean + */ public boolean isPrerelease() { return prerelease; } + /** + * Gets published at. + * + * @return the published at + */ public Date getPublished_at() { return new Date(published_at.getTime()); } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Gets tag name. + * + * @return the tag name + */ public String getTagName() { return tag_name; } + /** + * Gets target commitish. + * + * @return the target commitish + */ public String getTargetCommitish() { return target_commitish; } + /** + * Gets upload url. + * + * @return the upload url + */ public String getUploadUrl() { return upload_url; } + /** + * Gets zipball url. + * + * @return the zipball url + */ public String getZipballUrl() { return zipball_url; } + /** + * Gets tarball url. + * + * @return the tarball url + */ public String getTarballUrl() { return tarball_url; } @@ -123,6 +207,14 @@ public class GHRelease extends GHObject { * Java 7 or greater. Options for fixing this for earlier JVMs can be found here * http://stackoverflow.com/questions/12361090/server-name-indication-sni-on-java but involve more complicated * handling of the HTTP requests to github's API. + * + * @param file + * the file + * @param contentType + * the content type + * @return the gh asset + * @throws IOException + * the io exception */ public GHAsset uploadAsset(File file, String contentType) throws IOException { FileInputStream s = new FileInputStream(file); @@ -133,6 +225,19 @@ public class GHRelease extends GHObject { } } + /** + * Upload asset gh asset. + * + * @param filename + * the filename + * @param stream + * the stream + * @param contentType + * the content type + * @return the gh asset + * @throws IOException + * the io exception + */ public GHAsset uploadAsset(String filename, InputStream stream, String contentType) throws IOException { Requester builder = new Requester(owner.root); @@ -141,6 +246,13 @@ public class GHRelease extends GHObject { return builder.contentType(contentType).with(stream).to(url, GHAsset.class).wrap(this); } + /** + * Gets assets. + * + * @return the assets + * @throws IOException + * the io exception + */ public List getAssets() throws IOException { Requester builder = new Requester(owner.root); @@ -150,6 +262,9 @@ public class GHRelease extends GHObject { /** * Deletes this release. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { new Requester(root).method("DELETE").to(owner.getApiTailUrl("releases/" + id)); @@ -157,6 +272,8 @@ public class GHRelease extends GHObject { /** * Updates this release via a builder. + * + * @return the gh release updater */ public GHReleaseUpdater update() { return new GHReleaseUpdater(this); diff --git a/src/main/java/org/kohsuke/github/GHReleaseBuilder.java b/src/main/java/org/kohsuke/github/GHReleaseBuilder.java index d35943b57..19dbafd6b 100644 --- a/src/main/java/org/kohsuke/github/GHReleaseBuilder.java +++ b/src/main/java/org/kohsuke/github/GHReleaseBuilder.java @@ -5,12 +5,20 @@ import java.io.IOException; /** * Builder pattern for creating a {@link GHRelease} * - * @see GHRepository#createRelease(String) + * @see GHRepository#createRelease(String) GHRepository#createRelease(String) */ public class GHReleaseBuilder { private final GHRepository repo; private final Requester builder; + /** + * Instantiates a new Gh release builder. + * + * @param ghRepository + * the gh repository + * @param tag + * the tag + */ public GHReleaseBuilder(GHRepository ghRepository, String tag) { this.repo = ghRepository; this.builder = new Requester(repo.root); @@ -18,8 +26,11 @@ public class GHReleaseBuilder { } /** + * Body gh release builder. + * * @param body * The release notes body. + * @return the gh release builder */ public GHReleaseBuilder body(String body) { builder.with("body", body); @@ -31,6 +42,7 @@ public class GHReleaseBuilder { * * @param commitish * Defaults to the repository’s default branch (usually "master"). Unused if the Git tag already exists. + * @return the gh release builder */ public GHReleaseBuilder commitish(String commitish) { builder.with("target_commitish", commitish); @@ -43,6 +55,7 @@ public class GHReleaseBuilder { * @param draft * {@code true} to create a draft (unpublished) release, {@code false} to create a published one. Default * is {@code false}. + * @return the gh release builder */ public GHReleaseBuilder draft(boolean draft) { builder.with("draft", draft); @@ -50,8 +63,11 @@ public class GHReleaseBuilder { } /** + * Name gh release builder. + * * @param name * the name of the release + * @return the gh release builder */ public GHReleaseBuilder name(String name) { builder.with("name", name); @@ -64,12 +80,20 @@ public class GHReleaseBuilder { * @param prerelease * {@code true} to identify the release as a prerelease. {@code false} to identify the release as a full * release. Default is {@code false}. + * @return the gh release builder */ public GHReleaseBuilder prerelease(boolean prerelease) { builder.with("prerelease", prerelease); return this; } + /** + * Create gh release. + * + * @return the gh release + * @throws IOException + * the io exception + */ public GHRelease create() throws IOException { return builder.to(repo.getApiTailUrl("releases"), GHRelease.class).wrap(repo); } diff --git a/src/main/java/org/kohsuke/github/GHReleaseUpdater.java b/src/main/java/org/kohsuke/github/GHReleaseUpdater.java index e3905f03e..7f4b1c6f5 100644 --- a/src/main/java/org/kohsuke/github/GHReleaseUpdater.java +++ b/src/main/java/org/kohsuke/github/GHReleaseUpdater.java @@ -6,7 +6,7 @@ import java.io.IOException; * Modifies {@link GHRelease}. * * @author Kohsuke Kawaguchi - * @see GHRelease#update() + * @see GHRelease#update() GHRelease#update() */ public class GHReleaseUpdater { private final GHRelease base; @@ -17,14 +17,24 @@ public class GHReleaseUpdater { this.builder = new Requester(base.root); } + /** + * Tag gh release updater. + * + * @param tag + * the tag + * @return the gh release updater + */ public GHReleaseUpdater tag(String tag) { builder.with("tag_name", tag); return this; } /** + * Body gh release updater. + * * @param body * The release notes body. + * @return the gh release updater */ public GHReleaseUpdater body(String body) { builder.with("body", body); @@ -36,6 +46,7 @@ public class GHReleaseUpdater { * * @param commitish * Defaults to the repository’s default branch (usually "master"). Unused if the Git tag already exists. + * @return the gh release updater */ public GHReleaseUpdater commitish(String commitish) { builder.with("target_commitish", commitish); @@ -48,6 +59,7 @@ public class GHReleaseUpdater { * @param draft * {@code true} to create a draft (unpublished) release, {@code false} to create a published one. Default * is {@code false}. + * @return the gh release updater */ public GHReleaseUpdater draft(boolean draft) { builder.with("draft", draft); @@ -55,8 +67,11 @@ public class GHReleaseUpdater { } /** + * Name gh release updater. + * * @param name * the name of the release + * @return the gh release updater */ public GHReleaseUpdater name(String name) { builder.with("name", name); @@ -69,12 +84,20 @@ public class GHReleaseUpdater { * @param prerelease * {@code true} to identify the release as a prerelease. {@code false} to identify the release as a full * release. Default is {@code false}. + * @return the gh release updater */ public GHReleaseUpdater prerelease(boolean prerelease) { builder.with("prerelease", prerelease); return this; } + /** + * Update gh release. + * + * @return the gh release + * @throws IOException + * the io exception + */ public GHRelease update() throws IOException { return builder.method("PATCH").to(base.owner.getApiTailUrl("releases/" + base.id), GHRelease.class) .wrap(base.owner); diff --git a/src/main/java/org/kohsuke/github/GHRepository.java b/src/main/java/org/kohsuke/github/GHRepository.java index 2565c30f8..e6dd1e715 100644 --- a/src/main/java/org/kohsuke/github/GHRepository.java +++ b/src/main/java/org/kohsuke/github/GHRepository.java @@ -103,17 +103,44 @@ public class GHRepository extends GHObject { private GHRepository source, parent; + /** + * Create deployment gh deployment builder. + * + * @param ref + * the ref + * @return the gh deployment builder + */ public GHDeploymentBuilder createDeployment(String ref) { return new GHDeploymentBuilder(this, ref); } /** + * Gets deployment statuses. + * + * @param id + * the id + * @return the deployment statuses + * @throws IOException + * the io exception * @deprecated Use {@code getDeployment(id).listStatuses()} */ public PagedIterable getDeploymentStatuses(final int id) throws IOException { return getDeployment(id).listStatuses(); } + /** + * List deployments paged iterable. + * + * @param sha + * the sha + * @param ref + * the ref + * @param task + * the task + * @param environment + * the environment + * @return the paged iterable + */ public PagedIterable listDeployments(String sha, String ref, String task, String environment) { List params = Arrays.asList(getParam("sha", sha), getParam("ref", ref), getParam("task", task), getParam("environment", environment)); @@ -124,6 +151,12 @@ public class GHRepository extends GHObject { /** * Obtains a single {@link GHDeployment} by its ID. + * + * @param id + * the id + * @return the deployment + * @throws IOException + * the io exception */ public GHDeployment getDeployment(long id) throws IOException { return root.retrieve().to(getApiTailUrl("deployments/" + id), GHDeployment.class).wrap(this); @@ -144,6 +177,15 @@ public class GHRepository extends GHObject { } /** + * Gets deploy status. + * + * @param deploymentId + * the deployment id + * @param ghDeploymentState + * the gh deployment state + * @return the deploy status + * @throws IOException + * the io exception * @deprecated Use {@code getDeployment(deploymentId).createStatus(ghDeploymentState)} */ public GHDeploymentStatusBuilder createDeployStatus(int deploymentId, GHDeploymentState ghDeploymentState) @@ -155,16 +197,28 @@ public class GHRepository extends GHObject { boolean pull, push, admin; } + /** + * Gets description. + * + * @return the description + */ public String getDescription() { return description; } + /** + * Gets homepage. + * + * @return the homepage + */ public String getHomepage() { return homepage; } /** * Gets the git:// URL to this repository, such as "git://github.com/kohsuke/jenkins.git" This URL is read-only. + * + * @return the git transport url */ public String getGitTransportUrl() { return git_url; @@ -172,12 +226,17 @@ public class GHRepository extends GHObject { /** * Gets the HTTPS URL to this repository, such as "https://github.com/kohsuke/jenkins.git" This URL is read-only. + * + * @return the http transport url */ public String getHttpTransportUrl() { return clone_url; } /** + * Git http transport url string. + * + * @return the string * @deprecated Typo of {@link #getHttpTransportUrl()} */ public String gitHttpTransportUrl() { @@ -186,6 +245,8 @@ public class GHRepository extends GHObject { /** * Gets the Subversion URL to access this repository: https://github.com/rails/rails + * + * @return the svn url */ public String getSvnUrl() { return svn_url; @@ -194,6 +255,8 @@ public class GHRepository extends GHObject { /** * Gets the Mirror URL to access this repository: https://github.com/apache/tomee mirrored from * git://git.apache.org/tomee.git + * + * @return the mirror url */ public String getMirrorUrl() { return mirror_url; @@ -201,6 +264,8 @@ public class GHRepository extends GHObject { /** * Gets the SSH URL to access this repository, such as git@github.com:rails/rails.git + * + * @return the ssh url */ public String getSshUrl() { return ssh_url; @@ -212,6 +277,8 @@ public class GHRepository extends GHObject { /** * Short repository name without the owner. For example 'jenkins' in case of http://github.com/jenkinsci/jenkins + * + * @return the name */ public String getName() { return name; @@ -220,46 +287,108 @@ public class GHRepository extends GHObject { /** * Full repository name including the owner or organization. For example 'jenkinsci/jenkins' in case of * http://github.com/jenkinsci/jenkins + * + * @return the full name */ public String getFullName() { return full_name; } + /** + * Has pull access boolean. + * + * @return the boolean + */ public boolean hasPullAccess() { return permissions != null && permissions.pull; } + /** + * Has push access boolean. + * + * @return the boolean + */ public boolean hasPushAccess() { return permissions != null && permissions.push; } + /** + * Has admin access boolean. + * + * @return the boolean + */ public boolean hasAdminAccess() { return permissions != null && permissions.admin; } /** * Gets the primary programming language. + * + * @return the language */ public String getLanguage() { return language; } + /** + * Gets owner. + * + * @return the owner + * @throws IOException + * the io exception + */ public GHUser getOwner() throws IOException { return root.isOffline() ? owner : root.getUser(getOwnerName()); // because 'owner' isn't fully populated } + /** + * Gets issue. + * + * @param id + * the id + * @return the issue + * @throws IOException + * the io exception + */ public GHIssue getIssue(int id) throws IOException { return root.retrieve().to(getApiTailUrl("issues/" + id), GHIssue.class).wrap(this); } + /** + * Create issue gh issue builder. + * + * @param title + * the title + * @return the gh issue builder + */ public GHIssueBuilder createIssue(String title) { return new GHIssueBuilder(this, title); } + /** + * Gets issues. + * + * @param state + * the state + * @return the issues + * @throws IOException + * the io exception + */ public List getIssues(GHIssueState state) throws IOException { return listIssues(state).asList(); } + /** + * Gets issues. + * + * @param state + * the state + * @param milestone + * the milestone + * @return the issues + * @throws IOException + * the io exception + */ public List getIssues(GHIssueState state, GHMilestone milestone) throws IOException { return Arrays.asList(GHIssue.wrap(root.retrieve().with("state", state) .with("milestone", milestone == null ? "none" : "" + milestone.getNumber()) @@ -268,12 +397,23 @@ public class GHRepository extends GHObject { /** * Lists up all the issues in this repository. + * + * @param state + * the state + * @return the paged iterable */ public PagedIterable listIssues(final GHIssueState state) { return root.retrieve().with("state", state).asPagedIterable(getApiTailUrl("issues"), GHIssue[].class, item -> item.wrap(GHRepository.this)); } + /** + * Create release gh release builder. + * + * @param tag + * the tag + * @return the gh release builder + */ public GHReleaseBuilder createRelease(String tag) { return new GHReleaseBuilder(this, tag); } @@ -286,6 +426,9 @@ public class GHRepository extends GHObject { * have at least two slashes, it will be rejected. * @param sha * The SHA1 value to set this reference to + * @return the gh ref + * @throws IOException + * the io exception */ public GHRef createRef(String name, String sha) throws IOException { return new Requester(root).with("ref", name).with("sha", sha).method("POST") @@ -293,12 +436,26 @@ public class GHRepository extends GHObject { } /** + * Gets releases. + * + * @return the releases + * @throws IOException + * the io exception * @deprecated use {@link #listReleases()} */ public List getReleases() throws IOException { return listReleases().asList(); } + /** + * Gets release. + * + * @param id + * the id + * @return the release + * @throws IOException + * the io exception + */ public GHRelease getRelease(long id) throws IOException { try { return root.retrieve().to(getApiTailUrl("releases/" + id), GHRelease.class).wrap(this); @@ -307,6 +464,15 @@ public class GHRepository extends GHObject { } } + /** + * Gets release by tag name. + * + * @param tag + * the tag + * @return the release by tag name + * @throws IOException + * the io exception + */ public GHRelease getReleaseByTagName(String tag) throws IOException { try { return root.retrieve().to(getApiTailUrl("releases/tags/" + tag), GHRelease.class).wrap(this); @@ -315,6 +481,13 @@ public class GHRepository extends GHObject { } } + /** + * Gets latest release. + * + * @return the latest release + * @throws IOException + * the io exception + */ public GHRelease getLatestRelease() throws IOException { try { return root.retrieve().to(getApiTailUrl("releases/latest"), GHRelease.class).wrap(this); @@ -323,11 +496,25 @@ public class GHRepository extends GHObject { } } + /** + * List releases paged iterable. + * + * @return the paged iterable + * @throws IOException + * the io exception + */ public PagedIterable listReleases() throws IOException { return root.retrieve().asPagedIterable(getApiTailUrl("releases"), GHRelease[].class, item -> item.wrap(GHRepository.this)); } + /** + * List tags paged iterable. + * + * @return the paged iterable + * @throws IOException + * the io exception + */ public PagedIterable listTags() throws IOException { return root.retrieve().asPagedIterable(getApiTailUrl("tags"), GHTag[].class, item -> item.wrap(GHRepository.this)); @@ -336,11 +523,20 @@ public class GHRepository extends GHObject { /** * List languages for the specified repository. The value on the right of a language is the number of bytes of code * written in that language. { "C": 78769, "Python": 7769 } + * + * @return the map + * @throws IOException + * the io exception */ public Map listLanguages() throws IOException { return root.retrieve().to(getApiTailUrl("languages"), HashMap.class); } + /** + * Gets owner name. + * + * @return the owner name + */ public String getOwnerName() { // consistency of the GitHub API is super... some serialized forms of GHRepository populate // a full GHUser while others populate only the owner and email. This later form is super helpful @@ -349,30 +545,65 @@ public class GHRepository extends GHObject { return owner.login != null ? owner.login : owner.name; } + /** + * Has issues boolean. + * + * @return the boolean + */ public boolean hasIssues() { return has_issues; } + /** + * Has wiki boolean. + * + * @return the boolean + */ public boolean hasWiki() { return has_wiki; } + /** + * Is fork boolean. + * + * @return the boolean + */ public boolean isFork() { return fork; } + /** + * Is archived boolean. + * + * @return the boolean + */ public boolean isArchived() { return archived; } + /** + * Is allow squash merge boolean. + * + * @return the boolean + */ public boolean isAllowSquashMerge() { return allow_squash_merge; } + /** + * Is allow merge commit boolean. + * + * @return the boolean + */ public boolean isAllowMergeCommit() { return allow_merge_commit; } + /** + * Is allow rebase merge boolean. + * + * @return the boolean + */ public boolean isAllowRebaseMerge() { return allow_rebase_merge; } @@ -380,47 +611,88 @@ public class GHRepository extends GHObject { /** * Returns the number of all forks of this repository. This not only counts direct forks, but also forks of forks, * and so on. + * + * @return the forks */ public int getForks() { return forks_count; } + /** + * Gets stargazers count. + * + * @return the stargazers count + */ public int getStargazersCount() { return stargazers_count; } + /** + * Is private boolean. + * + * @return the boolean + */ public boolean isPrivate() { return _private; } + /** + * Has downloads boolean. + * + * @return the boolean + */ public boolean hasDownloads() { return has_downloads; } + /** + * Has pages boolean. + * + * @return the boolean + */ public boolean hasPages() { return has_pages; } + /** + * Gets watchers. + * + * @return the watchers + */ public int getWatchers() { return watchers_count; } + /** + * Gets open issue count. + * + * @return the open issue count + */ public int getOpenIssueCount() { return open_issues_count; } /** + * Gets network count. + * + * @return the network count * @deprecated This no longer exists in the official API documentation. Use {@link #getForks()} */ public int getNetworkCount() { return forks_count; } + /** + * Gets subscribers count. + * + * @return the subscribers count + */ public int getSubscribersCount() { return subscribers_count; } /** + * Gets pushed at. * * @return null if the repository was never pushed at. */ @@ -438,18 +710,30 @@ public class GHRepository extends GHObject { } /** + * Gets master branch. + * + * @return the master branch * @deprecated Renamed to {@link #getDefaultBranch()} */ public String getMasterBranch() { return default_branch; } + /** + * Gets size. + * + * @return the size + */ public int getSize() { return size; } /** * Gets the collaborators on this repository. This set always appear to include the owner. + * + * @return the collaborators + * @throws IOException + * the io exception */ @WithBridgeMethods(Set.class) public GHPersonSet getCollaborators() throws IOException { @@ -459,7 +743,9 @@ public class GHRepository extends GHObject { /** * Lists up the collaborators on this repository. * - * @return Users + * @return Users paged iterable + * @throws IOException + * the io exception */ public PagedIterable listCollaborators() throws IOException { return listUsers("collaborators"); @@ -469,6 +755,10 @@ public class GHRepository extends GHObject { * Lists all * the * available assignees to which issues may be assigned. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listAssignees() throws IOException { return listUsers("assignees"); @@ -476,6 +766,12 @@ public class GHRepository extends GHObject { /** * Checks if the given user is an assignee for this repository. + * + * @param u + * the u + * @return the boolean + * @throws IOException + * the io exception */ public boolean hasAssignee(GHUser u) throws IOException { return root.retrieve().asHttpStatusCode(getApiTailUrl("assignees/" + u.getLogin())) / 100 == 2; @@ -484,6 +780,10 @@ public class GHRepository extends GHObject { /** * Gets the names of the collaborators on this repository. This method deviates from the principle of this library * but it works a lot faster than {@link #getCollaborators()}. + * + * @return the collaborator names + * @throws IOException + * the io exception */ public Set getCollaboratorNames() throws IOException { Set r = new HashSet(); @@ -494,13 +794,12 @@ public class GHRepository extends GHObject { /** * Obtain permission for a given user in this repository. - * + * * @param user * a {@link GHUser#getLogin} - * @throws FileNotFoundException - * under some conditions (e.g., private repo you can see but are not an admin of); treat as unknown - * @throws HttpException - * with a 403 under other conditions (e.g., public repo you have no special rights to); treat as unknown + * @return the permission + * @throws IOException + * the io exception */ public GHPermissionType getPermission(String user) throws IOException { GHPermission perm = root.retrieve().to(getApiTailUrl("collaborators/" + user + "/permission"), @@ -511,11 +810,12 @@ public class GHRepository extends GHObject { /** * Obtain permission for a given user in this repository. - * - * @throws FileNotFoundException - * under some conditions (e.g., private repo you can see but are not an admin of); treat as unknown - * @throws HttpException - * with a 403 under other conditions (e.g., public repo you have no special rights to); treat as unknown + * + * @param u + * the u + * @return the permission + * @throws IOException + * the io exception */ public GHPermissionType getPermission(GHUser u) throws IOException { return getPermission(u.getLogin()); @@ -523,24 +823,60 @@ public class GHRepository extends GHObject { /** * If this repository belongs to an organization, return a set of teams. + * + * @return the teams + * @throws IOException + * the io exception */ public Set getTeams() throws IOException { return Collections.unmodifiableSet(new HashSet(Arrays.asList(GHTeam.wrapUp( root.retrieve().to(getApiTailUrl("teams"), GHTeam[].class), root.getOrganization(getOwnerName()))))); } + /** + * Add collaborators. + * + * @param users + * the users + * @throws IOException + * the io exception + */ public void addCollaborators(GHUser... users) throws IOException { addCollaborators(asList(users)); } + /** + * Add collaborators. + * + * @param users + * the users + * @throws IOException + * the io exception + */ public void addCollaborators(Collection users) throws IOException { modifyCollaborators(users, "PUT"); } + /** + * Remove collaborators. + * + * @param users + * the users + * @throws IOException + * the io exception + */ public void removeCollaborators(GHUser... users) throws IOException { removeCollaborators(asList(users)); } + /** + * Remove collaborators. + * + * @param users + * the users + * @throws IOException + * the io exception + */ public void removeCollaborators(Collection users) throws IOException { modifyCollaborators(users, "DELETE"); } @@ -551,6 +887,14 @@ public class GHRepository extends GHObject { } } + /** + * Sets email service hook. + * + * @param address + * the address + * @throws IOException + * the io exception + */ public void setEmailServiceHook(String address) throws IOException { Map config = new HashMap(); config.put("address", address); @@ -567,6 +911,11 @@ public class GHRepository extends GHObject { /** * Enables or disables the issue tracker for this repository. + * + * @param v + * the v + * @throws IOException + * the io exception */ public void enableIssueTracker(boolean v) throws IOException { edit("has_issues", String.valueOf(v)); @@ -574,52 +923,129 @@ public class GHRepository extends GHObject { /** * Enables or disables Wiki for this repository. + * + * @param v + * the v + * @throws IOException + * the io exception */ public void enableWiki(boolean v) throws IOException { edit("has_wiki", String.valueOf(v)); } + /** + * Enable downloads. + * + * @param v + * the v + * @throws IOException + * the io exception + */ public void enableDownloads(boolean v) throws IOException { edit("has_downloads", String.valueOf(v)); } /** * Rename this repository. + * + * @param name + * the name + * @throws IOException + * the io exception */ public void renameTo(String name) throws IOException { edit("name", name); } + /** + * Sets description. + * + * @param value + * the value + * @throws IOException + * the io exception + */ public void setDescription(String value) throws IOException { edit("description", value); } + /** + * Sets homepage. + * + * @param value + * the value + * @throws IOException + * the io exception + */ public void setHomepage(String value) throws IOException { edit("homepage", value); } + /** + * Sets default branch. + * + * @param value + * the value + * @throws IOException + * the io exception + */ public void setDefaultBranch(String value) throws IOException { edit("default_branch", value); } + /** + * Sets private. + * + * @param value + * the value + * @throws IOException + * the io exception + */ public void setPrivate(boolean value) throws IOException { edit("private", Boolean.toString(value)); } + /** + * Allow squash merge. + * + * @param value + * the value + * @throws IOException + * the io exception + */ public void allowSquashMerge(boolean value) throws IOException { edit("allow_squash_merge", Boolean.toString(value)); } + /** + * Allow merge commit. + * + * @param value + * the value + * @throws IOException + * the io exception + */ public void allowMergeCommit(boolean value) throws IOException { edit("allow_merge_commit", Boolean.toString(value)); } + /** + * Allow rebase merge. + * + * @param value + * the value + * @throws IOException + * the io exception + */ public void allowRebaseMerge(boolean value) throws IOException { edit("allow_rebase_merge", Boolean.toString(value)); } /** * Deletes this repository. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { try { @@ -664,7 +1090,9 @@ public class GHRepository extends GHObject { /** * Lists all the direct forks of this repository, sorted by github api default, currently {@link ForkSort#NEWEST - * ForkSort.NEWEST}. + * ForkSort.NEWEST}*. + * + * @return the paged iterable */ public PagedIterable listForks() { return listForks(null); @@ -672,10 +1100,11 @@ public class GHRepository extends GHObject { /** * Lists all the direct forks of this repository, sorted by the given sort order. - * + * * @param sort * the sort order. If null, defaults to github api default, currently {@link ForkSort#NEWEST * ForkSort.NEWEST}. + * @return the paged iterable */ public PagedIterable listForks(final ForkSort sort) { return root.retrieve().with("sort", sort).asPagedIterable(getApiTailUrl("forks"), GHRepository[].class, @@ -686,6 +1115,8 @@ public class GHRepository extends GHObject { * Forks this repository as your repository. * * @return Newly forked repository that belong to you. + * @throws IOException + * the io exception */ public GHRepository fork() throws IOException { new Requester(root).method("POST").to(getApiTailUrl("forks"), null); @@ -707,7 +1138,11 @@ public class GHRepository extends GHObject { /** * Forks this repository into an organization. * + * @param org + * the org * @return Newly forked repository that belong to you. + * @throws IOException + * the io exception */ public GHRepository forkTo(GHOrganization org) throws IOException { new Requester(root).to(getApiTailUrl("forks?org=" + org.getLogin())); @@ -728,6 +1163,12 @@ public class GHRepository extends GHObject { /** * Retrieves a specified pull request. + * + * @param i + * the + * @return the pull request + * @throws IOException + * the io exception */ public GHPullRequest getPullRequest(int i) throws IOException { return root.retrieve().withPreview(SHADOW_CAT).to(getApiTailUrl("pulls/" + i), GHPullRequest.class) @@ -737,7 +1178,12 @@ public class GHRepository extends GHObject { /** * Retrieves all the pull requests of a particular state. * - * @see #listPullRequests(GHIssueState) + * @param state + * the state + * @return the pull requests + * @throws IOException + * the io exception + * @see #listPullRequests(GHIssueState) #listPullRequests(GHIssueState) */ public List getPullRequests(GHIssueState state) throws IOException { return queryPullRequests().state(state).list().asList(); @@ -746,6 +1192,9 @@ public class GHRepository extends GHObject { /** * Retrieves all the pull requests of a particular state. * + * @param state + * the state + * @return the paged iterable * @deprecated Use {@link #queryPullRequests()} */ public PagedIterable listPullRequests(GHIssueState state) { @@ -754,6 +1203,8 @@ public class GHRepository extends GHObject { /** * Retrieves pull requests. + * + * @return the gh pull request query builder */ public GHPullRequestQueryBuilder queryPullRequests() { return new GHPullRequestQueryBuilder(this); @@ -772,6 +1223,9 @@ public class GHRepository extends GHObject { * on the current repository. * @param body * The contents of the pull request. This is the markdown description of a pull request. + * @return the gh pull request + * @throws IOException + * the io exception */ public GHPullRequest createPullRequest(String title, String head, String base, String body) throws IOException { return createPullRequest(title, head, base, body, true); @@ -792,6 +1246,9 @@ public class GHRepository extends GHObject { * The contents of the pull request. This is the markdown description of a pull request. * @param maintainerCanModify * Indicates whether maintainers can modify the pull request. + * @return the gh pull request + * @throws IOException + * the io exception */ public GHPullRequest createPullRequest(String title, String head, String base, String body, boolean maintainerCanModify) throws IOException { @@ -815,6 +1272,9 @@ public class GHRepository extends GHObject { * Indicates whether maintainers can modify the pull request. * @param draft * Indicates whether to create a draft pull request or not. + * @return the gh pull request + * @throws IOException + * the io exception */ public GHPullRequest createPullRequest(String title, String head, String base, String body, boolean maintainerCanModify, boolean draft) throws IOException { @@ -825,11 +1285,24 @@ public class GHRepository extends GHObject { /** * Retrieves the currently configured hooks. + * + * @return the hooks + * @throws IOException + * the io exception */ public List getHooks() throws IOException { return GHHooks.repoContext(this, owner).getHooks(); } + /** + * Gets hook. + * + * @param id + * the id + * @return the hook + * @throws IOException + * the io exception + */ public GHHook getHook(int id) throws IOException { return GHHooks.repoContext(this, owner).getHook(id); } @@ -837,7 +1310,7 @@ public class GHRepository extends GHObject { /** * Gets a comparison between 2 points in the repository. This would be similar to calling * git log id1...id2 against a local repository. - * + * * @param id1 * an identifier for the first point to compare from, this can be a sha1 ID (for a commit, tag etc) or a * direct tag name @@ -853,10 +1326,32 @@ public class GHRepository extends GHObject { return compare.wrap(this); } + /** + * Gets compare. + * + * @param id1 + * the id 1 + * @param id2 + * the id 2 + * @return the compare + * @throws IOException + * the io exception + */ public GHCompare getCompare(GHCommit id1, GHCommit id2) throws IOException { return getCompare(id1.getSHA1(), id2.getSHA1()); } + /** + * Gets compare. + * + * @param id1 + * the id 1 + * @param id2 + * the id 2 + * @return the compare + * @throws IOException + * the io exception + */ public GHCompare getCompare(GHBranch id1, GHBranch id2) throws IOException { GHRepository owner1 = id1.getOwner(); @@ -879,7 +1374,7 @@ public class GHRepository extends GHObject { /** * Retrieves all refs for the github repository. - * + * * @return an array of GHRef elements coresponding with the refs in the remote repository. * @throws IOException * on failure communicating with GitHub @@ -903,7 +1398,7 @@ public class GHRepository extends GHObject { /** * Retrieves all refs of the given type for the current GitHub repository. - * + * * @param refType * the type of reg to search for e.g. tags or commits * @return an array of all refs matching the request type @@ -955,6 +1450,8 @@ public class GHRepository extends GHObject { * @param sha * the sha of the tag object * @return the annotated tag object + * @throws IOException + * the io exception */ public GHTagObject getTagObject(String sha) throws IOException { return root.retrieve().to(getApiTailUrl("git/tags/" + sha), GHTagObject.class).wrap(this); @@ -974,6 +1471,11 @@ public class GHRepository extends GHObject { return root.retrieve().to(url, GHTree.class).wrap(this); } + /** + * Create tree gh tree builder. + * + * @return the gh tree builder + */ public GHTreeBuilder createTree() { return new GHTreeBuilder(this); } @@ -986,6 +1488,7 @@ public class GHRepository extends GHObject { * sha number or branch name ex: "master" * @param recursive * use 1 + * @return the tree recursive * @throws IOException * on failure communicating with GitHub, potentially due to an invalid tree type being requested */ @@ -1000,14 +1503,24 @@ public class GHRepository extends GHObject { *

* This method retrieves the whole content in memory, so beware when you are dealing with large BLOB. * + * @param blobSha + * the blob sha + * @return the blob + * @throws IOException + * the io exception * @see Get a blob - * @see #readBlob(String) + * @see #readBlob(String) #readBlob(String) */ public GHBlob getBlob(String blobSha) throws IOException { String target = getApiTailUrl("git/blobs/" + blobSha); return root.retrieve().to(target, GHBlob.class); } + /** + * Create blob gh blob builder. + * + * @return the gh blob builder + */ public GHBlobBuilder createBlob() { return new GHBlobBuilder(this); } @@ -1015,8 +1528,13 @@ public class GHRepository extends GHObject { /** * Reads the content of a blob as a stream for better efficiency. * + * @param blobSha + * the blob sha + * @return the input stream + * @throws IOException + * the io exception * @see Get a blob - * @see #getBlob(String) + * @see #getBlob(String) #getBlob(String) */ public InputStream readBlob(String blobSha) throws IOException { String target = getApiTailUrl("git/blobs/" + blobSha); @@ -1025,6 +1543,12 @@ public class GHRepository extends GHObject { /** * Gets a commit object in this repository. + * + * @param sha1 + * the sha 1 + * @return the commit + * @throws IOException + * the io exception */ public GHCommit getCommit(String sha1) throws IOException { GHCommit c = commits.get(sha1); @@ -1036,12 +1560,19 @@ public class GHRepository extends GHObject { return c; } + /** + * Create commit gh commit builder. + * + * @return the gh commit builder + */ public GHCommitBuilder createCommit() { return new GHCommitBuilder(this); } /** * Lists all the commits. + * + * @return the paged iterable */ public PagedIterable listCommits() { return root.retrieve().asPagedIterable(String.format("/repos/%s/%s/commits", getOwnerName(), name), @@ -1050,6 +1581,8 @@ public class GHRepository extends GHObject { /** * Search commits by specifying filters through a builder pattern. + * + * @return the gh commit query builder */ public GHCommitQueryBuilder queryCommits() { return new GHCommitQueryBuilder(this); @@ -1057,6 +1590,8 @@ public class GHRepository extends GHObject { /** * Lists up all the commit comments in this repository. + * + * @return the paged iterable */ public PagedIterable listCommitComments() { return root.retrieve().asPagedIterable(String.format("/repos/%s/%s/comments", getOwnerName(), name), @@ -1067,9 +1602,9 @@ public class GHRepository extends GHObject { * Gets the basic license details for the repository. *

* + * @return null if there's no license. * @throws IOException * as usual but also if you don't use the preview connector - * @return null if there's no license. */ public GHLicense getLicense() throws IOException { GHContentWithLicense lic = getLicenseContent_(); @@ -1097,8 +1632,13 @@ public class GHRepository extends GHObject { } /** - * * /** Lists all the commit statues attached to the given commit, newer ones first. + * + * @param sha1 + * the sha 1 + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listCommitStatuses(final String sha1) throws IOException { return root.retrieve().asPagedIterable(String.format("/repos/%s/%s/statuses/%s", getOwnerName(), name, sha1), @@ -1107,6 +1647,12 @@ public class GHRepository extends GHObject { /** * Gets the last status of this commit, which is what gets shown in the UI. + * + * @param sha1 + * the sha 1 + * @return the last commit status + * @throws IOException + * the io exception */ public GHCommitStatus getLastCommitStatus(String sha1) throws IOException { List v = listCommitStatuses(sha1).asList(); @@ -1116,12 +1662,19 @@ public class GHRepository extends GHObject { /** * Creates a commit status * + * @param sha1 + * the sha 1 + * @param state + * the state * @param targetUrl * Optional parameter that points to the URL that has more details. * @param description * Optional short description. * @param context * Optinal commit status context. + * @return the gh commit status + * @throws IOException + * the io exception */ public GHCommitStatus createCommitStatus(String sha1, GHCommitState state, String targetUrl, String description, String context) throws IOException { @@ -1132,7 +1685,21 @@ public class GHRepository extends GHObject { } /** - * @see #createCommitStatus(String, GHCommitState,String,String,String) + * Create commit status gh commit status. + * + * @param sha1 + * the sha 1 + * @param state + * the state + * @param targetUrl + * the target url + * @param description + * the description + * @return the gh commit status + * @throws IOException + * the io exception + * @see #createCommitStatus(String, GHCommitState, String, String, String) #createCommitStatus(String, + * GHCommitState,String,String,String) */ public GHCommitStatus createCommitStatus(String sha1, GHCommitState state, String targetUrl, String description) throws IOException { @@ -1141,6 +1708,10 @@ public class GHRepository extends GHObject { /** * Lists repository events. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listEvents() throws IOException { return root.retrieve().asPagedIterable(String.format("/repos/%s/%s/events", getOwnerName(), name), @@ -1149,30 +1720,58 @@ public class GHRepository extends GHObject { /** * Lists labels in this repository. - * + *

* https://developer.github.com/v3/issues/labels/#list-all-labels-for-this-repository + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listLabels() throws IOException { return root.retrieve().withPreview(SYMMETRA).asPagedIterable(getApiTailUrl("labels"), GHLabel[].class, item -> item.wrapUp(GHRepository.this)); } + /** + * Gets label. + * + * @param name + * the name + * @return the label + * @throws IOException + * the io exception + */ public GHLabel getLabel(String name) throws IOException { return root.retrieve().withPreview(SYMMETRA).to(getApiTailUrl("labels/" + name), GHLabel.class).wrapUp(this); } + /** + * Create label gh label. + * + * @param name + * the name + * @param color + * the color + * @return the gh label + * @throws IOException + * the io exception + */ public GHLabel createLabel(String name, String color) throws IOException { return createLabel(name, color, ""); } /** * Description is still in preview. - * + * * @param name + * the name * @param color + * the color * @param description - * @return + * the description + * @return gh label * @throws IOException + * the io exception */ @Preview @Deprecated @@ -1183,6 +1782,8 @@ public class GHRepository extends GHObject { /** * Lists all the invitations. + * + * @return the paged iterable */ public PagedIterable listInvitations() { return root.retrieve().asPagedIterable(String.format("/repos/%s/%s/invitations", getOwnerName(), name), @@ -1191,8 +1792,10 @@ public class GHRepository extends GHObject { /** * Lists all the subscribers (aka watchers.) - * + *

* https://developer.github.com/v3/activity/watching/ + * + * @return the paged iterable */ public PagedIterable listSubscribers() { return listUsers("subscribers"); @@ -1201,6 +1804,8 @@ public class GHRepository extends GHObject { /** * Lists all the users who have starred this repo based on the old version of the API. For additional information, * like date when the repository was starred, see {@link #listStargazers2()} + * + * @return the paged iterable */ public PagedIterable listStargazers() { return listUsers("stargazers"); @@ -1209,6 +1814,8 @@ public class GHRepository extends GHObject { /** * Lists all the users who have starred this repo based on new version of the API, having extended information like * the time when the repository was starred. For compatibility with the old API see {@link #listStargazers()} + * + * @return the paged iterable */ public PagedIterable listStargazers2() { return root.retrieve().withPreview("application/vnd.github.v3.star+json").asPagedIterable( @@ -1220,7 +1827,6 @@ public class GHRepository extends GHObject { } /** - * * See https://api.github.com/hooks for possible names and their configuration scheme. TODO: produce type-safe * binding * @@ -1230,16 +1836,41 @@ public class GHRepository extends GHObject { * The configuration hash. * @param events * Can be null. Types of events to hook into. + * @param active + * the active + * @return the gh hook + * @throws IOException + * the io exception */ public GHHook createHook(String name, Map config, Collection events, boolean active) throws IOException { return GHHooks.repoContext(this, owner).createHook(name, config, events, active); } + /** + * Create web hook gh hook. + * + * @param url + * the url + * @param events + * the events + * @return the gh hook + * @throws IOException + * the io exception + */ public GHHook createWebHook(URL url, Collection events) throws IOException { return createHook("web", Collections.singletonMap("url", url.toExternalForm()), events, true); } + /** + * Create web hook gh hook. + * + * @param url + * the url + * @return the gh hook + * @throws IOException + * the io exception + */ public GHHook createWebHook(URL url) throws IOException { return createWebHook(url, null); } @@ -1256,6 +1887,7 @@ public class GHRepository extends GHObject { * Returns a set that represents the post-commit hook URLs. The returned set is live, and changes made to them are * reflected to GitHub. * + * @return the post commit hooks * @deprecated Use {@link #getHooks()} and {@link #createHook(String, Map, Collection, boolean)} */ @SuppressFBWarnings(value = "DMI_COLLECTION_OF_URLS", justification = "It causes a performance degradation, but we have already exposed it to the API") @@ -1330,6 +1962,10 @@ public class GHRepository extends GHObject { /** * Gets branches by {@linkplain GHBranch#getName() their names}. + * + * @return the branches + * @throws IOException + * the io exception */ public Map getBranches() throws IOException { Map r = new TreeMap(); @@ -1359,11 +1995,25 @@ public class GHRepository extends GHObject { return value; } + /** + * Gets branch. + * + * @param name + * the name + * @return the branch + * @throws IOException + * the io exception + */ public GHBranch getBranch(String name) throws IOException { return root.retrieve().to(getApiTailUrl("branches/" + UrlEncode(name)), GHBranch.class).wrap(this); } /** + * Gets milestones. + * + * @return the milestones + * @throws IOException + * the io exception * @deprecated Use {@link #listMilestones(GHIssueState)} */ public Map getMilestones() throws IOException { @@ -1376,12 +2026,25 @@ public class GHRepository extends GHObject { /** * Lists up all the milestones in this repository. + * + * @param state + * the state + * @return the paged iterable */ public PagedIterable listMilestones(final GHIssueState state) { return root.retrieve().with("state", state).asPagedIterable(getApiTailUrl("milestones"), GHMilestone[].class, item -> item.wrap(GHRepository.this)); } + /** + * Gets milestone. + * + * @param number + * the number + * @return the milestone + * @throws IOException + * the io exception + */ public GHMilestone getMilestone(int number) throws IOException { GHMilestone m = milestones.get(number); if (m == null) { @@ -1393,10 +2056,30 @@ public class GHRepository extends GHObject { return m; } + /** + * Gets file content. + * + * @param path + * the path + * @return the file content + * @throws IOException + * the io exception + */ public GHContent getFileContent(String path) throws IOException { return getFileContent(path, null); } + /** + * Gets file content. + * + * @param path + * the path + * @param ref + * the ref + * @return the file content + * @throws IOException + * the io exception + */ public GHContent getFileContent(String path, String ref) throws IOException { Requester requester = root.retrieve(); String target = getApiTailUrl("contents/" + path); @@ -1404,10 +2087,30 @@ public class GHRepository extends GHObject { return requester.with("ref", ref).to(target, GHContent.class).wrap(this); } + /** + * Gets directory content. + * + * @param path + * the path + * @return the directory content + * @throws IOException + * the io exception + */ public List getDirectoryContent(String path) throws IOException { return getDirectoryContent(path, null); } + /** + * Gets directory content. + * + * @param path + * the path + * @param ref + * the ref + * @return the directory content + * @throws IOException + * the io exception + */ public List getDirectoryContent(String path, String ref) throws IOException { Requester requester = root.retrieve(); while (path.endsWith("/")) { @@ -1424,6 +2127,10 @@ public class GHRepository extends GHObject { /** * https://developer.github.com/v3/repos/contents/#get-the-readme + * + * @return the readme + * @throws IOException + * the io exception */ public GHContent getReadme() throws IOException { Requester requester = root.retrieve(); @@ -1432,6 +2139,8 @@ public class GHRepository extends GHObject { /** * Creates a new content, or update an existing content. + * + * @return the gh content builder */ public GHContentBuilder createContent() { return new GHContentBuilder(this); @@ -1439,6 +2148,16 @@ public class GHRepository extends GHObject { /** * Use {@link #createContent()}. + * + * @param content + * the content + * @param commitMessage + * the commit message + * @param path + * the path + * @return the gh content update response + * @throws IOException + * the io exception */ @Deprecated public GHContentUpdateResponse createContent(String content, String commitMessage, String path) throws IOException { @@ -1447,6 +2166,18 @@ public class GHRepository extends GHObject { /** * Use {@link #createContent()}. + * + * @param content + * the content + * @param commitMessage + * the commit message + * @param path + * the path + * @param branch + * the branch + * @return the gh content update response + * @throws IOException + * the io exception */ @Deprecated public GHContentUpdateResponse createContent(String content, String commitMessage, String path, String branch) @@ -1456,6 +2187,16 @@ public class GHRepository extends GHObject { /** * Use {@link #createContent()}. + * + * @param contentBytes + * the content bytes + * @param commitMessage + * the commit message + * @param path + * the path + * @return the gh content update response + * @throws IOException + * the io exception */ @Deprecated public GHContentUpdateResponse createContent(byte[] contentBytes, String commitMessage, String path) @@ -1465,6 +2206,18 @@ public class GHRepository extends GHObject { /** * Use {@link #createContent()}. + * + * @param contentBytes + * the content bytes + * @param commitMessage + * the commit message + * @param path + * the path + * @param branch + * the branch + * @return the gh content update response + * @throws IOException + * the io exception */ @Deprecated public GHContentUpdateResponse createContent(byte[] contentBytes, String commitMessage, String path, String branch) @@ -1472,17 +2225,46 @@ public class GHRepository extends GHObject { return createContent().content(contentBytes).message(commitMessage).path(path).branch(branch).commit(); } + /** + * Create milestone gh milestone. + * + * @param title + * the title + * @param description + * the description + * @return the gh milestone + * @throws IOException + * the io exception + */ public GHMilestone createMilestone(String title, String description) throws IOException { return new Requester(root).with("title", title).with("description", description).method("POST") .to(getApiTailUrl("milestones"), GHMilestone.class).wrap(this); } + /** + * Add deploy key gh deploy key. + * + * @param title + * the title + * @param key + * the key + * @return the gh deploy key + * @throws IOException + * the io exception + */ public GHDeployKey addDeployKey(String title, String key) throws IOException { return new Requester(root).with("title", title).with("key", key).method("POST") .to(getApiTailUrl("keys"), GHDeployKey.class).wrap(this); } + /** + * Gets deploy keys. + * + * @return the deploy keys + * @throws IOException + * the io exception + */ public List getDeployKeys() throws IOException { List list = new ArrayList( Arrays.asList(root.retrieve().to(getApiTailUrl("keys"), GHDeployKey[].class))); @@ -1496,7 +2278,9 @@ public class GHRepository extends GHObject { * * @return {@link GHRepository} that points to the root repository where this repository is forked (indirectly or * directly) from. Otherwise null. - * @see #getParent() + * @throws IOException + * the io exception + * @see #getParent() #getParent() */ public GHRepository getSource() throws IOException { if (source == null) @@ -1512,7 +2296,9 @@ public class GHRepository extends GHObject { * * @return {@link GHRepository} that points to the repository where this repository is forked directly from. * Otherwise null. - * @see #getSource() + * @throws IOException + * the io exception + * @see #getSource() #getSource() */ public GHRepository getParent() throws IOException { if (parent == null) @@ -1524,6 +2310,14 @@ public class GHRepository extends GHObject { /** * Subscribes to this repository to get notifications. + * + * @param subscribed + * the subscribed + * @param ignored + * the ignored + * @return the gh subscription + * @throws IOException + * the io exception */ public GHSubscription subscribe(boolean subscribed, boolean ignored) throws IOException { return new Requester(root).with("subscribed", subscribed).with("ignored", ignored).method("PUT") @@ -1534,6 +2328,8 @@ public class GHRepository extends GHObject { * Returns the current subscription. * * @return null if no subscription exists. + * @throws IOException + * the io exception */ public GHSubscription getSubscription() throws IOException { try { @@ -1543,14 +2339,29 @@ public class GHRepository extends GHObject { } } + /** + * List contributors paged iterable. + * + * @return the paged iterable + * @throws IOException + * the io exception + */ public PagedIterable listContributors() throws IOException { return root.retrieve().asPagedIterable(getApiTailUrl("contributors"), Contributor[].class, item -> item.wrapUp(root)); } + /** + * The type Contributor. + */ public static class Contributor extends GHUser { private int contributions; + /** + * Gets contributions. + * + * @return the contributions + */ public int getContributions() { return contributions; } @@ -1570,6 +2381,8 @@ public class GHRepository extends GHObject { /** * Returns the statistics for this repository. + * + * @return the statistics */ public GHRepositoryStatistics getStatistics() { // TODO: Use static object and introduce refresh() method, @@ -1579,6 +2392,14 @@ public class GHRepository extends GHObject { /** * Create a project for this repository. + * + * @param name + * the name + * @param body + * the body + * @return the gh project + * @throws IOException + * the io exception */ public GHProject createProject(String name, String body) throws IOException { return root.retrieve().method("POST").withPreview(INERTIA).with("name", name).with("body", body) @@ -1587,9 +2408,12 @@ public class GHRepository extends GHObject { /** * Returns the projects for this repository. - * + * * @param status * The status filter (all, open or closed). + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listProjects(final GHProject.ProjectStateFilter status) throws IOException { return root.retrieve().withPreview(INERTIA).with("state", status).asPagedIterable(getApiTailUrl("projects"), @@ -1598,6 +2422,10 @@ public class GHRepository extends GHObject { /** * Returns open projects for this repository. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listProjects() throws IOException { return listProjects(GHProject.ProjectStateFilter.OPEN); @@ -1605,10 +2433,17 @@ public class GHRepository extends GHObject { /** * Render a Markdown document. - * + *

* In {@linkplain MarkdownMode#GFM GFM mode}, issue numbers and user mentions are linked accordingly. * - * @see GitHub#renderMarkdown(String) + * @param text + * the text + * @param mode + * the mode + * @return the reader + * @throws IOException + * the io exception + * @see GitHub#renderMarkdown(String) GitHub#renderMarkdown(String) */ public Reader renderMarkdown(String text, MarkdownMode mode) throws IOException { return new InputStreamReader( @@ -1619,6 +2454,8 @@ public class GHRepository extends GHObject { /** * List all the notifications in a repository for the current user. + * + * @return the gh notification stream */ public GHNotificationStream listNotifications() { return new GHNotificationStream(root, getApiTailUrl("/notifications")); @@ -1627,6 +2464,10 @@ public class GHRepository extends GHObject { /** * https://developer.github.com/v3/repos/traffic/#views + * + * @return the view traffic + * @throws IOException + * the io exception */ public GHRepositoryViewTraffic getViewTraffic() throws IOException { return root.retrieve().to(getApiTailUrl("/traffic/views"), GHRepositoryViewTraffic.class); @@ -1635,6 +2476,10 @@ public class GHRepository extends GHObject { /** * https://developer.github.com/v3/repos/traffic/#clones + * + * @return the clone traffic + * @throws IOException + * the io exception */ public GHRepositoryCloneTraffic getCloneTraffic() throws IOException { return root.retrieve().to(getApiTailUrl("/traffic/clones"), GHRepositoryCloneTraffic.class); @@ -1663,6 +2508,10 @@ public class GHRepository extends GHObject { /** * Get all issue events for this repository. See * https://developer.github.com/v3/issues/events/#list-events-for-a-repository + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listIssueEvents() throws IOException { return root.retrieve().asPagedIterable(getApiTailUrl("issues/events"), GHIssueEvent[].class, @@ -1671,6 +2520,12 @@ public class GHRepository extends GHObject { /** * Get a single issue event. See https://developer.github.com/v3/issues/events/#get-a-single-event + * + * @param id + * the id + * @return the issue event + * @throws IOException + * the io exception */ public GHIssueEvent getIssueEvent(long id) throws IOException { return root.retrieve().to(getApiTailUrl("issues/events/" + id), GHIssueEvent.class).wrapUp(root); @@ -1684,6 +2539,10 @@ public class GHRepository extends GHObject { /** * Return the topics for this repository. See * https://developer.github.com/v3/repos/#list-all-topics-for-a-repository + * + * @return the list + * @throws IOException + * the io exception */ public List listTopics() throws IOException { Topics topics = root.retrieve().withPreview(MERCY).to(getApiTailUrl("topics"), Topics.class); @@ -1693,6 +2552,11 @@ public class GHRepository extends GHObject { /** * Set the topics for this repository. See * https://developer.github.com/v3/repos/#replace-all-topics-for-a-repository + * + * @param topics + * the topics + * @throws IOException + * the io exception */ public void setTopics(List topics) throws IOException { Requester requester = new Requester(root); diff --git a/src/main/java/org/kohsuke/github/GHRepositoryCloneTraffic.java b/src/main/java/org/kohsuke/github/GHRepositoryCloneTraffic.java index f7f4f1f7f..4b5ce1c7d 100644 --- a/src/main/java/org/kohsuke/github/GHRepositoryCloneTraffic.java +++ b/src/main/java/org/kohsuke/github/GHRepositoryCloneTraffic.java @@ -5,7 +5,7 @@ import java.util.List; /** * Repository clone statistics. * - * @see GHRepository#getCloneTraffic() + * @see GHRepository#getCloneTraffic() GHRepository#getCloneTraffic() */ public class GHRepositoryCloneTraffic extends GHRepositoryTraffic { private List clones; @@ -18,6 +18,11 @@ public class GHRepositoryCloneTraffic extends GHRepositoryTraffic { this.clones = clones; } + /** + * Gets clones. + * + * @return the clones + */ public List getClones() { return clones; } @@ -26,6 +31,9 @@ public class GHRepositoryCloneTraffic extends GHRepositoryTraffic { return getClones(); } + /** + * The type DailyInfo. + */ public static class DailyInfo extends GHRepositoryTraffic.DailyInfo { DailyInfo() { } diff --git a/src/main/java/org/kohsuke/github/GHRepositorySearchBuilder.java b/src/main/java/org/kohsuke/github/GHRepositorySearchBuilder.java index c60a610fd..3103bd031 100644 --- a/src/main/java/org/kohsuke/github/GHRepositorySearchBuilder.java +++ b/src/main/java/org/kohsuke/github/GHRepositorySearchBuilder.java @@ -4,7 +4,7 @@ package org.kohsuke.github; * Search repositories. * * @author Kohsuke Kawaguchi - * @see GitHub#searchRepositories() + * @see GitHub#searchRepositories() GitHub#searchRepositories() */ public class GHRepositorySearchBuilder extends GHSearchBuilder { GHRepositorySearchBuilder(GitHub root) { @@ -19,56 +19,143 @@ public class GHRepositorySearchBuilder extends GHSearchBuilder { return this; } + /** + * In gh repository search builder. + * + * @param v + * the v + * @return the gh repository search builder + */ public GHRepositorySearchBuilder in(String v) { return q("in:" + v); } + /** + * Size gh repository search builder. + * + * @param v + * the v + * @return the gh repository search builder + */ public GHRepositorySearchBuilder size(String v) { return q("size:" + v); } + /** + * Forks gh repository search builder. + * + * @param v + * the v + * @return the gh repository search builder + */ public GHRepositorySearchBuilder forks(String v) { return q("forks:" + v); } + /** + * Created gh repository search builder. + * + * @param v + * the v + * @return the gh repository search builder + */ public GHRepositorySearchBuilder created(String v) { return q("created:" + v); } + /** + * Pushed gh repository search builder. + * + * @param v + * the v + * @return the gh repository search builder + */ public GHRepositorySearchBuilder pushed(String v) { return q("pushed:" + v); } + /** + * User gh repository search builder. + * + * @param v + * the v + * @return the gh repository search builder + */ public GHRepositorySearchBuilder user(String v) { return q("user:" + v); } + /** + * Repo gh repository search builder. + * + * @param v + * the v + * @return the gh repository search builder + */ public GHRepositorySearchBuilder repo(String v) { return q("repo:" + v); } + /** + * Language gh repository search builder. + * + * @param v + * the v + * @return the gh repository search builder + */ public GHRepositorySearchBuilder language(String v) { return q("language:" + v); } + /** + * Stars gh repository search builder. + * + * @param v + * the v + * @return the gh repository search builder + */ public GHRepositorySearchBuilder stars(String v) { return q("stars:" + v); } + /** + * Topic gh repository search builder. + * + * @param v + * the v + * @return the gh repository search builder + */ public GHRepositorySearchBuilder topic(String v) { return q("topic:" + v); } + /** + * Order gh repository search builder. + * + * @param v + * the v + * @return the gh repository search builder + */ public GHRepositorySearchBuilder order(GHDirection v) { req.with("order", v); return this; } + /** + * Sort gh repository search builder. + * + * @param sort + * the sort + * @return the gh repository search builder + */ public GHRepositorySearchBuilder sort(Sort sort) { req.with("sort", sort); return this; } + /** + * The enum Sort. + */ public enum Sort { STARS, FORKS, UPDATED } diff --git a/src/main/java/org/kohsuke/github/GHRepositorySelection.java b/src/main/java/org/kohsuke/github/GHRepositorySelection.java index 95ca72b85..503954521 100644 --- a/src/main/java/org/kohsuke/github/GHRepositorySelection.java +++ b/src/main/java/org/kohsuke/github/GHRepositorySelection.java @@ -6,7 +6,6 @@ import java.util.Locale; * App installation repository selection. * * @author Paulo Miguel Almeida - * * @see GHAppInstallation */ public enum GHRepositorySelection { diff --git a/src/main/java/org/kohsuke/github/GHRepositoryStatistics.java b/src/main/java/org/kohsuke/github/GHRepositoryStatistics.java index 2371dacf8..41f43ec4f 100644 --- a/src/main/java/org/kohsuke/github/GHRepositoryStatistics.java +++ b/src/main/java/org/kohsuke/github/GHRepositoryStatistics.java @@ -24,6 +24,12 @@ public class GHRepositoryStatistics { private static final int MAX_WAIT_ITERATIONS = 3; private static final int WAIT_SLEEP_INTERVAL = 5000; + /** + * Instantiates a new Gh repository statistics. + * + * @param repo + * the repo + */ public GHRepositoryStatistics(GHRepository repo) { this.repo = repo; this.root = repo.root; @@ -32,14 +38,27 @@ public class GHRepositoryStatistics { /** * Get contributors list with additions, deletions, and commit count. See * https://developer.github.com/v3/repos/statistics/#get-contributors-list-with-additions-deletions-and-commit-counts + * + * @return the contributor stats + * @throws IOException + * the io exception + * @throws InterruptedException + * the interrupted exception */ public PagedIterable getContributorStats() throws IOException, InterruptedException { return getContributorStats(true); } /** + * Gets contributor stats. + * * @param waitTillReady * Whether to sleep the thread if necessary until the statistics are ready. This is true by default. + * @return the contributor stats + * @throws IOException + * the io exception + * @throws InterruptedException + * the interrupted exception */ @Preview @Deprecated @@ -71,6 +90,9 @@ public class GHRepositoryStatistics { item -> item.wrapUp(root)); } + /** + * The type ContributorStats. + */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD", "URF_UNREAD_FIELD" }, justification = "JSON API") public static class ContributorStats extends GHObject { @@ -84,11 +106,18 @@ public class GHRepositoryStatistics { throw new UnsupportedOperationException("Not supported yet."); } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } /** + * Gets author. + * * @return The author described by these statistics. */ public GHUser getAuthor() { @@ -96,6 +125,8 @@ public class GHRepositoryStatistics { } /** + * Gets total. + * * @return The total number of commits authored by the contributor. */ public int getTotal() { @@ -109,6 +140,7 @@ public class GHRepositoryStatistics { * The timestamp to look for. * @return The week starting with the given timestamp. Throws an exception if it is not found. * @throws NoSuchElementException + * the no such element exception */ public Week getWeek(long timestamp) throws NoSuchElementException { // maybe store the weeks in a map to make this more efficient? @@ -123,6 +155,8 @@ public class GHRepositoryStatistics { } /** + * Gets weeks. + * * @return The total number of commits authored by the contributor. */ public List getWeeks() { @@ -135,6 +169,9 @@ public class GHRepositoryStatistics { + String.valueOf(weeks.size()) + " weeks"; } + /** + * The type Week. + */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD", "URF_UNREAD_FIELD" }, justification = "JSON API") public static class Week { @@ -145,6 +182,8 @@ public class GHRepositoryStatistics { private int c; /** + * Gets week timestamp. + * * @return Start of the week, as a UNIX timestamp. */ public long getWeekTimestamp() { @@ -152,6 +191,8 @@ public class GHRepositoryStatistics { } /** + * Gets number of additions. + * * @return The number of additions for the week. */ public int getNumberOfAdditions() { @@ -159,6 +200,8 @@ public class GHRepositoryStatistics { } /** + * Gets number of deletions. + * * @return The number of deletions for the week. */ public int getNumberOfDeletions() { @@ -166,6 +209,8 @@ public class GHRepositoryStatistics { } /** + * Gets number of commits. + * * @return The number of commits for the week. */ public int getNumberOfCommits() { @@ -187,12 +232,19 @@ public class GHRepositoryStatistics { /** * Get the last year of commit activity data. See * https://developer.github.com/v3/repos/statistics/#get-the-last-year-of-commit-activity-data + * + * @return the commit activity + * @throws IOException + * the io exception */ public PagedIterable getCommitActivity() throws IOException { return root.retrieve().asPagedIterable(getApiTailUrl("commit_activity"), CommitActivity[].class, item -> item.wrapUp(root)); } + /** + * The type CommitActivity. + */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD" }, justification = "JSON API") public static class CommitActivity extends GHObject { @@ -202,6 +254,8 @@ public class GHRepositoryStatistics { private long week; /** + * Gets days. + * * @return The number of commits for each day of the week. 0 = Sunday, 1 = Monday, etc. */ public List getDays() { @@ -209,6 +263,8 @@ public class GHRepositoryStatistics { } /** + * Gets total. + * * @return The total number of commits for the week. */ public int getTotal() { @@ -216,6 +272,8 @@ public class GHRepositoryStatistics { } /** + * Gets week. + * * @return The start of the week as a UNIX timestamp. */ public long getWeek() { @@ -227,6 +285,11 @@ public class GHRepositoryStatistics { return this; } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } @@ -240,6 +303,10 @@ public class GHRepositoryStatistics { /** * Get the number of additions and deletions per week. See * https://developer.github.com/v3/repos/statistics/#get-the-number-of-additions-and-deletions-per-week + * + * @return the code frequency + * @throws IOException + * the io exception */ public List getCodeFrequency() throws IOException { // Map to ArrayLists first, since there are no field names in the @@ -268,6 +335,9 @@ public class GHRepositoryStatistics { } } + /** + * The type CodeFrequency. + */ public static class CodeFrequency { private int week; private int additions; @@ -280,6 +350,8 @@ public class GHRepositoryStatistics { } /** + * Gets week timestamp. + * * @return The start of the week as a UNIX timestamp. */ public int getWeekTimestamp() { @@ -287,6 +359,8 @@ public class GHRepositoryStatistics { } /** + * Gets additions. + * * @return The number of additions for the week. */ public long getAdditions() { @@ -294,6 +368,8 @@ public class GHRepositoryStatistics { } /** + * Gets deletions. + * * @return The number of deletions for the week. NOTE: This will be a NEGATIVE number. */ public long getDeletions() { @@ -312,11 +388,18 @@ public class GHRepositoryStatistics { /** * Get the weekly commit count for the repository owner and everyone else. See * https://developer.github.com/v3/repos/statistics/#get-the-weekly-commit-count-for-the-repository-owner-and-everyone-else + * + * @return the participation + * @throws IOException + * the io exception */ public Participation getParticipation() throws IOException { return root.retrieve().to(getApiTailUrl("participation"), Participation.class); } + /** + * The type Participation. + */ public static class Participation extends GHObject { /* package almost final */ private GitHub root; private List all; @@ -327,11 +410,18 @@ public class GHRepositoryStatistics { throw new UnsupportedOperationException("Not supported yet."); } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } /** + * Gets all commits. + * * @return The list of commit counts for everyone combined, for the last 52 weeks. */ public List getAllCommits() { @@ -339,6 +429,8 @@ public class GHRepositoryStatistics { } /** + * Gets owner commits. + * * @return The list of commit counts for the owner, for the last 52 weeks. */ public List getOwnerCommits() { @@ -354,6 +446,10 @@ public class GHRepositoryStatistics { /** * Get the number of commits per hour in each day. See * https://developer.github.com/v3/repos/statistics/#get-the-number-of-commits-per-hour-in-each-day + * + * @return the punch card + * @throws IOException + * the io exception */ public List getPunchCard() throws IOException { // Map to ArrayLists first, since there are no field names in the @@ -375,6 +471,9 @@ public class GHRepositoryStatistics { return returnList; } + /** + * The type PunchCardItem. + */ public static class PunchCardItem { private int dayOfWeek; private int hourOfDay; @@ -387,6 +486,8 @@ public class GHRepositoryStatistics { } /** + * Gets day of week. + * * @return The day of the week. 0 = Sunday, 1 = Monday, etc. */ public int getDayOfWeek() { @@ -394,6 +495,8 @@ public class GHRepositoryStatistics { } /** + * Gets hour of day. + * * @return The hour of the day from 0 to 23. */ public long getHourOfDay() { @@ -401,6 +504,8 @@ public class GHRepositoryStatistics { } /** + * Gets number of commits. + * * @return The number of commits for the day and hour. */ public long getNumberOfCommits() { diff --git a/src/main/java/org/kohsuke/github/GHRepositoryTraffic.java b/src/main/java/org/kohsuke/github/GHRepositoryTraffic.java index 8efb74083..9b4be50a7 100644 --- a/src/main/java/org/kohsuke/github/GHRepositoryTraffic.java +++ b/src/main/java/org/kohsuke/github/GHRepositoryTraffic.java @@ -3,6 +3,9 @@ package org.kohsuke.github; import java.util.Date; import java.util.List; +/** + * The type GHRepositoryTraffic. + */ public abstract class GHRepositoryTraffic implements TrafficInfo { private int count; private int uniques; @@ -23,13 +26,26 @@ public abstract class GHRepositoryTraffic implements TrafficInfo { return uniques; } + /** + * Gets daily info. + * + * @return the daily info + */ public abstract List getDailyInfo(); + /** + * The type DailyInfo. + */ public static abstract class DailyInfo implements TrafficInfo { private String timestamp; private int count; private int uniques; + /** + * Gets timestamp. + * + * @return the timestamp + */ public Date getTimestamp() { return GitHub.parseDate(timestamp); } diff --git a/src/main/java/org/kohsuke/github/GHRepositoryViewTraffic.java b/src/main/java/org/kohsuke/github/GHRepositoryViewTraffic.java index 1f897baf4..ee6916a5d 100644 --- a/src/main/java/org/kohsuke/github/GHRepositoryViewTraffic.java +++ b/src/main/java/org/kohsuke/github/GHRepositoryViewTraffic.java @@ -5,7 +5,7 @@ import java.util.List; /** * Repository view statistics. * - * @see GHRepository#getViewTraffic() + * @see GHRepository#getViewTraffic() GHRepository#getViewTraffic() */ public class GHRepositoryViewTraffic extends GHRepositoryTraffic { private List views; @@ -18,6 +18,11 @@ public class GHRepositoryViewTraffic extends GHRepositoryTraffic { this.views = views; } + /** + * Gets views. + * + * @return the views + */ public List getViews() { return views; } @@ -26,6 +31,9 @@ public class GHRepositoryViewTraffic extends GHRepositoryTraffic { return getViews(); } + /** + * The type DailyInfo. + */ public static class DailyInfo extends GHRepositoryTraffic.DailyInfo { DailyInfo() { } diff --git a/src/main/java/org/kohsuke/github/GHSearchBuilder.java b/src/main/java/org/kohsuke/github/GHSearchBuilder.java index 17a035b2a..a1c9e7c89 100644 --- a/src/main/java/org/kohsuke/github/GHSearchBuilder.java +++ b/src/main/java/org/kohsuke/github/GHSearchBuilder.java @@ -8,6 +8,8 @@ import java.util.List; /** * Base class for various search builders. * + * @param + * the type parameter * @author Kohsuke Kawaguchi */ public abstract class GHSearchBuilder extends GHQueryBuilder { @@ -25,6 +27,10 @@ public abstract class GHSearchBuilder extends GHQueryBuilder { /** * Search terms. + * + * @param term + * the term + * @return the gh query builder */ public GHQueryBuilder q(String term) { terms.add(term); @@ -48,5 +54,10 @@ public abstract class GHSearchBuilder extends GHQueryBuilder { }; } + /** + * Gets api url. + * + * @return the api url + */ protected abstract String getApiUrl(); } diff --git a/src/main/java/org/kohsuke/github/GHSubscription.java b/src/main/java/org/kohsuke/github/GHSubscription.java index 40939fa42..a8ddc81dd 100644 --- a/src/main/java/org/kohsuke/github/GHSubscription.java +++ b/src/main/java/org/kohsuke/github/GHSubscription.java @@ -7,8 +7,8 @@ import java.util.Date; * Represents your subscribing to a repository / conversation thread.. * * @author Kohsuke Kawaguchi - * @see GHRepository#getSubscription() - * @see GHThread#getSubscription() + * @see GHRepository#getSubscription() GHRepository#getSubscription() + * @see GHThread#getSubscription() GHThread#getSubscription() */ public class GHSubscription { private String created_at, url, repository_url, reason; @@ -17,36 +17,74 @@ public class GHSubscription { private GitHub root; private GHRepository repo; + /** + * Gets created at. + * + * @return the created at + */ public Date getCreatedAt() { return GitHub.parseDate(created_at); } + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Gets repository url. + * + * @return the repository url + */ public String getRepositoryUrl() { return repository_url; } + /** + * Gets reason. + * + * @return the reason + */ public String getReason() { return reason; } + /** + * Is subscribed boolean. + * + * @return the boolean + */ public boolean isSubscribed() { return subscribed; } + /** + * Is ignored boolean. + * + * @return the boolean + */ public boolean isIgnored() { return ignored; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repo; } /** * Removes this subscription. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { new Requester(root).method("DELETE").to(repo.getApiTailUrl("subscription")); diff --git a/src/main/java/org/kohsuke/github/GHTag.java b/src/main/java/org/kohsuke/github/GHTag.java index 2f5703107..8281af2ea 100644 --- a/src/main/java/org/kohsuke/github/GHTag.java +++ b/src/main/java/org/kohsuke/github/GHTag.java @@ -5,7 +5,7 @@ import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; /** * Represents a tag in {@link GHRepository} * - * @see GHRepository#listTags() + * @see GHRepository#listTags() GHRepository#listTags() */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD" }, justification = "JSON API") @@ -24,18 +24,38 @@ public class GHTag { return this; } + /** + * Gets owner. + * + * @return the owner + */ public GHRepository getOwner() { return owner; } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } + /** + * Gets commit. + * + * @return the commit + */ public GHCommit getCommit() { return commit; } diff --git a/src/main/java/org/kohsuke/github/GHTagObject.java b/src/main/java/org/kohsuke/github/GHTagObject.java index cafe4ceac..e880e8e47 100644 --- a/src/main/java/org/kohsuke/github/GHTagObject.java +++ b/src/main/java/org/kohsuke/github/GHTagObject.java @@ -5,7 +5,7 @@ import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; /** * Represents an annotated tag in a {@link GHRepository} * - * @see GHRepository#getTagObject(String) + * @see GHRepository#getTagObject(String) GHRepository#getTagObject(String) */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD" }, justification = "JSON API") @@ -26,34 +26,74 @@ public class GHTagObject { return this; } + /** + * Gets owner. + * + * @return the owner + */ public GHRepository getOwner() { return owner; } + /** + * Gets root. + * + * @return the root + */ public GitHub getRoot() { return root; } + /** + * Gets tag. + * + * @return the tag + */ public String getTag() { return tag; } + /** + * Gets sha. + * + * @return the sha + */ public String getSha() { return sha; } + /** + * Gets url. + * + * @return the url + */ public String getUrl() { return url; } + /** + * Gets message. + * + * @return the message + */ public String getMessage() { return message; } + /** + * Gets tagger. + * + * @return the tagger + */ public GitUser getTagger() { return tagger; } + /** + * Gets object. + * + * @return the object + */ public GHRef.GHObject getObject() { return object; } diff --git a/src/main/java/org/kohsuke/github/GHTargetType.java b/src/main/java/org/kohsuke/github/GHTargetType.java index 23f7800c4..050c27e4f 100644 --- a/src/main/java/org/kohsuke/github/GHTargetType.java +++ b/src/main/java/org/kohsuke/github/GHTargetType.java @@ -8,7 +8,6 @@ import java.util.Locale; * App installation target type. * * @author Paulo Miguel Almeida - * * @see GHAppInstallation */ public enum GHTargetType { diff --git a/src/main/java/org/kohsuke/github/GHTeam.java b/src/main/java/org/kohsuke/github/GHTeam.java index 49e66a6d5..9e3c0612c 100644 --- a/src/main/java/org/kohsuke/github/GHTeam.java +++ b/src/main/java/org/kohsuke/github/GHTeam.java @@ -18,7 +18,9 @@ public class GHTeam implements Refreshable { protected /* final */ GitHub root; - /** Member's role in a team */ + /** + * Member's role in a team + */ public enum Role { /** * A normal member of the team @@ -56,43 +58,91 @@ public class GHTeam implements Refreshable { return teams; } + /** + * Gets name. + * + * @return the name + */ public String getName() { return name; } + /** + * Gets permission. + * + * @return the permission + */ public String getPermission() { return permission; } + /** + * Gets slug. + * + * @return the slug + */ public String getSlug() { return slug; } + /** + * Gets description. + * + * @return the description + */ public String getDescription() { return description; } + /** + * Sets description. + * + * @param description + * the description + * @throws IOException + * the io exception + */ public void setDescription(String description) throws IOException { root.retrieve().method("PATCH").with("description", description).to(api("")); } + /** + * Gets id. + * + * @return the id + */ public int getId() { return id; } /** * Retrieves the current members. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listMembers() throws IOException { return root.retrieve().asPagedIterable(api("/members"), GHUser[].class, item -> item.wrapUp(root)); } + /** + * Gets members. + * + * @return the members + * @throws IOException + * the io exception + */ public Set getMembers() throws IOException { return Collections.unmodifiableSet(listMembers().asSet()); } /** * Checks if this team has the specified user as a member. + * + * @param user + * the user + * @return the boolean */ public boolean hasMember(GHUser user) { try { @@ -103,6 +153,13 @@ public class GHTeam implements Refreshable { } } + /** + * Gets repositories. + * + * @return the repositories + * @throws IOException + * the io exception + */ public Map getRepositories() throws IOException { Map m = new TreeMap(); for (GHRepository r : listRepositories()) { @@ -111,15 +168,24 @@ public class GHTeam implements Refreshable { return m; } + /** + * List repositories paged iterable. + * + * @return the paged iterable + */ public PagedIterable listRepositories() { return root.retrieve().asPagedIterable(api("/repos"), GHRepository[].class, item -> item.wrap(root)); } /** * Adds a member to the team. - * + *

* The user will be invited to the organization if required. * + * @param u + * the u + * @throws IOException + * the io exception * @since 1.59 */ public void add(GHUser u) throws IOException { @@ -128,15 +194,15 @@ public class GHTeam implements Refreshable { /** * Adds a member to the team - * + *

* The user will be invited to the organization if required. * * @param user * github user * @param role * role for the new member - * * @throws IOException + * the io exception */ public void add(GHUser user, Role role) throws IOException { root.retrieve().method("PUT").with("role", role).to(api("/memberships/" + user.getLogin()), null); @@ -144,26 +210,60 @@ public class GHTeam implements Refreshable { /** * Removes a member to the team. + * + * @param u + * the u + * @throws IOException + * the io exception */ public void remove(GHUser u) throws IOException { root.retrieve().method("DELETE").to(api("/members/" + u.getLogin()), null); } + /** + * Add. + * + * @param r + * the r + * @throws IOException + * the io exception + */ public void add(GHRepository r) throws IOException { add(r, null); } + /** + * Add. + * + * @param r + * the r + * @param permission + * the permission + * @throws IOException + * the io exception + */ public void add(GHRepository r, GHOrganization.Permission permission) throws IOException { root.retrieve().method("PUT").with("permission", permission) .to(api("/repos/" + r.getOwnerName() + '/' + r.getName()), null); } + /** + * Remove. + * + * @param r + * the r + * @throws IOException + * the io exception + */ public void remove(GHRepository r) throws IOException { root.retrieve().method("DELETE").to(api("/repos/" + r.getOwnerName() + '/' + r.getName()), null); } /** * Deletes this team. + * + * @throws IOException + * the io exception */ public void delete() throws IOException { root.retrieve().method("DELETE").to(api("")); @@ -173,6 +273,13 @@ public class GHTeam implements Refreshable { return "/teams/" + id + tail; } + /** + * Gets organization. + * + * @return the organization + * @throws IOException + * the io exception + */ public GHOrganization getOrganization() throws IOException { refresh(organization); return organization; diff --git a/src/main/java/org/kohsuke/github/GHThread.java b/src/main/java/org/kohsuke/github/GHThread.java index 1375d6680..240c4084f 100644 --- a/src/main/java/org/kohsuke/github/GHThread.java +++ b/src/main/java/org/kohsuke/github/GHThread.java @@ -10,9 +10,9 @@ import java.util.Date; /** * A conversation in the notification API. * + * @author Kohsuke Kawaguchi * @see documentation * @see GHNotificationStream - * @author Kohsuke Kawaguchi */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", "NP_UNWRITTEN_FIELD" }, justification = "JSON API") @@ -37,6 +37,8 @@ public class GHThread extends GHObject { /** * Returns null if the entire thread has never been read. + * + * @return the last read at */ public Date getLastReadAt() { return GitHub.parseDate(last_read_at); @@ -50,28 +52,58 @@ public class GHThread extends GHObject { return null; } + /** + * Gets reason. + * + * @return the reason + */ public String getReason() { return reason; } + /** + * Gets repository. + * + * @return the repository + */ public GHRepository getRepository() { return repository; } // TODO: how to expose the subject? + /** + * Is read boolean. + * + * @return the boolean + */ public boolean isRead() { return !unread; } + /** + * Gets title. + * + * @return the title + */ public String getTitle() { return subject.title; } + /** + * Gets type. + * + * @return the type + */ public String getType() { return subject.type; } + /** + * Gets last comment url. + * + * @return the last comment url + */ public String getLastCommentUrl() { return subject.latest_comment_url; } @@ -80,6 +112,8 @@ public class GHThread extends GHObject { * If this thread is about an issue, return that issue. * * @return null if this thread is not about an issue. + * @throws IOException + * the io exception */ public GHIssue getBoundIssue() throws IOException { if (!"Issue".equals(subject.type) && "PullRequest".equals(subject.type)) @@ -91,6 +125,8 @@ public class GHThread extends GHObject { * If this thread is about a pull request, return that pull request. * * @return null if this thread is not about a pull request. + * @throws IOException + * the io exception */ public GHPullRequest getBoundPullRequest() throws IOException { if (!"PullRequest".equals(subject.type)) @@ -102,6 +138,8 @@ public class GHThread extends GHObject { * If this thread is about a commit, return that commit. * * @return null if this thread is not about a commit. + * @throws IOException + * the io exception */ public GHCommit getBoundCommit() throws IOException { if (!"Commit".equals(subject.type)) @@ -118,6 +156,9 @@ public class GHThread extends GHObject { /** * Marks this thread as read. + * + * @throws IOException + * the io exception */ public void markAsRead() throws IOException { new Requester(root).method("PATCH").to(url); @@ -125,6 +166,14 @@ public class GHThread extends GHObject { /** * Subscribes to this conversation to get notifications. + * + * @param subscribed + * the subscribed + * @param ignored + * the ignored + * @return the gh subscription + * @throws IOException + * the io exception */ public GHSubscription subscribe(boolean subscribed, boolean ignored) throws IOException { return new Requester(root).with("subscribed", subscribed).with("ignored", ignored).method("PUT") @@ -135,6 +184,8 @@ public class GHThread extends GHObject { * Returns the current subscription for this thread. * * @return null if no subscription exists. + * @throws IOException + * the io exception */ public GHSubscription getSubscription() throws IOException { try { diff --git a/src/main/java/org/kohsuke/github/GHTree.java b/src/main/java/org/kohsuke/github/GHTree.java index 7981d55f7..f23ead9fe 100644 --- a/src/main/java/org/kohsuke/github/GHTree.java +++ b/src/main/java/org/kohsuke/github/GHTree.java @@ -9,9 +9,9 @@ import java.util.List; * Provides information for Git Trees https://developer.github.com/v3/git/trees/ * * @author Daniel Teixeira - https://github.com/ddtxra - * @see GHCommit#getTree() - * @see GHRepository#getTree(String) - * @see GHTreeEntry#asTree() + * @see GHCommit#getTree() GHCommit#getTree() + * @see GHRepository#getTree(String) GHRepository#getTree(String) + * @see GHTreeEntry#asTree() GHTreeEntry#asTree() */ public class GHTree { /* package almost final */GHRepository repo; @@ -22,6 +22,8 @@ public class GHTree { /** * The SHA for this trees + * + * @return the sha */ public String getSha() { return sha; @@ -29,6 +31,8 @@ public class GHTree { /** * Return an array of entries of the trees + * + * @return the tree */ public List getTree() { return Collections.unmodifiableList(Arrays.asList(tree)); @@ -36,8 +40,12 @@ public class GHTree { /** * Finds a tree entry by its name. - * + *

* IOW, find a directory entry by a file name. + * + * @param path + * the path + * @return the entry */ public GHTreeEntry getEntry(String path) { for (GHTreeEntry e : tree) { @@ -49,7 +57,7 @@ public class GHTree { /** * Returns true if the number of items in the tree array exceeded the GitHub maximum limit. - * + * * @return true true if the number of items in the tree array exceeded the GitHub maximum limit otherwise false. */ public boolean isTruncated() { @@ -59,6 +67,8 @@ public class GHTree { /** * The API URL of this tag, such as "url": * "https://api.github.com/repos/octocat/Hello-World/trees/fc6274d15fa3ae2ab983129fb037999f264ba9a7", + * + * @return the url */ public URL getUrl() { return GitHub.parseURL(url); diff --git a/src/main/java/org/kohsuke/github/GHTreeBuilder.java b/src/main/java/org/kohsuke/github/GHTreeBuilder.java index e308ed134..d6c81b930 100644 --- a/src/main/java/org/kohsuke/github/GHTreeBuilder.java +++ b/src/main/java/org/kohsuke/github/GHTreeBuilder.java @@ -36,8 +36,11 @@ public class GHTreeBuilder { } /** + * Base tree gh tree builder. + * * @param baseTree * the SHA of tree you want to update with new data + * @return the gh tree builder */ public GHTreeBuilder baseTree(String baseTree) { req.with("base_tree", baseTree); @@ -46,6 +49,18 @@ public class GHTreeBuilder { /** * Adds a new entry to the tree. Exactly one of the parameters {@code sha} and {@code content} must be non-null. + * + * @param path + * the path + * @param mode + * the mode + * @param type + * the type + * @param sha + * the sha + * @param content + * the content + * @return the gh tree builder */ public GHTreeBuilder entry(String path, String mode, String type, String sha, String content) { TreeEntry entry = new TreeEntry(path, mode, type); @@ -58,6 +73,14 @@ public class GHTreeBuilder { /** * Specialized version of {@link #entry(String, String, String, String, String)} for adding an existing blob * referred by its SHA. + * + * @param path + * the path + * @param sha + * the sha + * @param executable + * the executable + * @return the gh tree builder */ public GHTreeBuilder shaEntry(String path, String sha, boolean executable) { TreeEntry entry = new TreeEntry(path, executable ? "100755" : "100644", "blob"); @@ -69,6 +92,14 @@ public class GHTreeBuilder { /** * Specialized version of {@link #entry(String, String, String, String, String)} for adding a text file with the * specified {@code content}. + * + * @param path + * the path + * @param content + * the content + * @param executable + * the executable + * @return the gh tree builder */ public GHTreeBuilder textEntry(String path, String content, boolean executable) { TreeEntry entry = new TreeEntry(path, executable ? "100755" : "100644", "blob"); @@ -83,6 +114,10 @@ public class GHTreeBuilder { /** * Creates a tree based on the parameters specified thus far. + * + * @return the gh tree + * @throws IOException + * the io exception */ public GHTree create() throws IOException { req._with("tree", treeEntries); diff --git a/src/main/java/org/kohsuke/github/GHTreeEntry.java b/src/main/java/org/kohsuke/github/GHTreeEntry.java index b4d9b576c..58cfe366c 100644 --- a/src/main/java/org/kohsuke/github/GHTreeEntry.java +++ b/src/main/java/org/kohsuke/github/GHTreeEntry.java @@ -36,7 +36,7 @@ public class GHTreeEntry { /** * Gets the size of the file, such as 132 - * + * * @return The size of the path or 0 if it is a directory */ public long getSize() { @@ -54,6 +54,8 @@ public class GHTreeEntry { /** * SHA1 of this object. + * + * @return the sha */ public String getSha() { return sha; @@ -62,6 +64,8 @@ public class GHTreeEntry { /** * API URL to this Git data, such as https://api.github.com/repos/jenkinsci * /jenkins/git/commits/b72322675eb0114363a9a86e9ad5a170d1d07ac0 + * + * @return the url */ public URL getUrl() { return GitHub.parseURL(url); @@ -69,6 +73,10 @@ public class GHTreeEntry { /** * If this tree entry represents a file, then return its information. Otherwise null. + * + * @return the gh blob + * @throws IOException + * the io exception */ public GHBlob asBlob() throws IOException { if (type.equals("blob")) @@ -79,6 +87,10 @@ public class GHTreeEntry { /** * If this tree entry represents a file, then return its content. Otherwise null. + * + * @return the input stream + * @throws IOException + * the io exception */ public InputStream readAsBlob() throws IOException { if (type.equals("blob")) @@ -89,6 +101,10 @@ public class GHTreeEntry { /** * If this tree entry represents a directory, then return it. Otherwise null. + * + * @return the gh tree + * @throws IOException + * the io exception */ public GHTree asTree() throws IOException { if (type.equals("tree")) diff --git a/src/main/java/org/kohsuke/github/GHUser.java b/src/main/java/org/kohsuke/github/GHUser.java index 7e46c096f..332721be5 100644 --- a/src/main/java/org/kohsuke/github/GHUser.java +++ b/src/main/java/org/kohsuke/github/GHUser.java @@ -35,12 +35,22 @@ import java.util.*; */ public class GHUser extends GHPerson { + /** + * Gets keys. + * + * @return the keys + * @throws IOException + * the io exception + */ public List getKeys() throws IOException { return Collections.unmodifiableList(Arrays.asList(root.retrieve().to(getApiTailUrl("keys"), GHKey[].class))); } /** * Follow this user. + * + * @throws IOException + * the io exception */ public void follow() throws IOException { new Requester(root).method("PUT").to("/user/following/" + login); @@ -48,6 +58,9 @@ public class GHUser extends GHPerson { /** * Unfollow this user. + * + * @throws IOException + * the io exception */ public void unfollow() throws IOException { new Requester(root).method("DELETE").to("/user/following/" + login); @@ -55,6 +68,10 @@ public class GHUser extends GHPerson { /** * Lists the users that this user is following + * + * @return the follows + * @throws IOException + * the io exception */ @WithBridgeMethods(Set.class) public GHPersonSet getFollows() throws IOException { @@ -63,6 +80,8 @@ public class GHUser extends GHPerson { /** * Lists the users that this user is following + * + * @return the paged iterable */ public PagedIterable listFollows() { return listUser("following"); @@ -70,6 +89,10 @@ public class GHUser extends GHPerson { /** * Lists the users who are following this user. + * + * @return the followers + * @throws IOException + * the io exception */ @WithBridgeMethods(Set.class) public GHPersonSet getFollowers() throws IOException { @@ -78,6 +101,8 @@ public class GHUser extends GHPerson { /** * Lists the users who are following this user. + * + * @return the paged iterable */ public PagedIterable listFollowers() { return listUser("followers"); @@ -89,8 +114,10 @@ public class GHUser extends GHPerson { /** * Lists all the subscribed (aka watched) repositories. - * + *

* https://developer.github.com/v3/activity/watching/ + * + * @return the paged iterable */ public PagedIterable listSubscriptions() { return listRepositories("subscriptions"); @@ -98,6 +125,8 @@ public class GHUser extends GHPerson { /** * Lists all the repositories that this user has starred. + * + * @return the paged iterable */ public PagedIterable listStarredRepositories() { return listRepositories("starred"); @@ -109,6 +138,10 @@ public class GHUser extends GHPerson { /** * Returns true if this user belongs to the specified organization. + * + * @param org + * the org + * @return the boolean */ public boolean isMemberOf(GHOrganization org) { return org.hasMember(this); @@ -116,6 +149,10 @@ public class GHUser extends GHPerson { /** * Returns true if this user belongs to the specified team. + * + * @param team + * the team + * @return the boolean */ public boolean isMemberOf(GHTeam team) { return team.hasMember(this); @@ -123,6 +160,10 @@ public class GHUser extends GHPerson { /** * Returns true if this user belongs to the specified organization as a public member. + * + * @param org + * the org + * @return the boolean */ public boolean isPublicMemberOf(GHOrganization org) { return org.hasPublicMember(this); @@ -136,6 +177,10 @@ public class GHUser extends GHPerson { /** * Gets the organization that this user belongs to publicly. + * + * @return the organizations + * @throws IOException + * the io exception */ @WithBridgeMethods(Set.class) public GHPersonSet getOrganizations() throws IOException { @@ -158,6 +203,10 @@ public class GHUser extends GHPerson { /** * Lists Gists created by this user. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listGists() throws IOException { return root.retrieve().asPagedIterable(String.format("/users/%s/gists", login), GHGist[].class, diff --git a/src/main/java/org/kohsuke/github/GHUserSearchBuilder.java b/src/main/java/org/kohsuke/github/GHUserSearchBuilder.java index c2c2d61ee..616a3b785 100644 --- a/src/main/java/org/kohsuke/github/GHUserSearchBuilder.java +++ b/src/main/java/org/kohsuke/github/GHUserSearchBuilder.java @@ -4,7 +4,7 @@ package org.kohsuke.github; * Search users. * * @author Kohsuke Kawaguchi - * @see GitHub#searchUsers() + * @see GitHub#searchUsers() GitHub#searchUsers() */ public class GHUserSearchBuilder extends GHSearchBuilder { GHUserSearchBuilder(GitHub root) { @@ -19,44 +19,110 @@ public class GHUserSearchBuilder extends GHSearchBuilder { return this; } + /** + * Type gh user search builder. + * + * @param v + * the v + * @return the gh user search builder + */ public GHUserSearchBuilder type(String v) { return q("type:" + v); } + /** + * In gh user search builder. + * + * @param v + * the v + * @return the gh user search builder + */ public GHUserSearchBuilder in(String v) { return q("in:" + v); } + /** + * Repos gh user search builder. + * + * @param v + * the v + * @return the gh user search builder + */ public GHUserSearchBuilder repos(String v) { return q("repos:" + v); } + /** + * Location gh user search builder. + * + * @param v + * the v + * @return the gh user search builder + */ public GHUserSearchBuilder location(String v) { return q("location:" + v); } + /** + * Language gh user search builder. + * + * @param v + * the v + * @return the gh user search builder + */ public GHUserSearchBuilder language(String v) { return q("language:" + v); } + /** + * Created gh user search builder. + * + * @param v + * the v + * @return the gh user search builder + */ public GHUserSearchBuilder created(String v) { return q("created:" + v); } + /** + * Followers gh user search builder. + * + * @param v + * the v + * @return the gh user search builder + */ public GHUserSearchBuilder followers(String v) { return q("followers:" + v); } + /** + * Order gh user search builder. + * + * @param v + * the v + * @return the gh user search builder + */ public GHUserSearchBuilder order(GHDirection v) { req.with("order", v); return this; } + /** + * Sort gh user search builder. + * + * @param sort + * the sort + * @return the gh user search builder + */ public GHUserSearchBuilder sort(Sort sort) { req.with("sort", sort); return this; } + /** + * The enum Sort. + */ public enum Sort { FOLLOWERS, REPOSITORIES, JOINED } diff --git a/src/main/java/org/kohsuke/github/GHVerifiedKey.java b/src/main/java/org/kohsuke/github/GHVerifiedKey.java index 65e2ec86e..24dfbdbfa 100644 --- a/src/main/java/org/kohsuke/github/GHVerifiedKey.java +++ b/src/main/java/org/kohsuke/github/GHVerifiedKey.java @@ -1,7 +1,13 @@ package org.kohsuke.github; +/** + * The type GHVerifiedKey. + */ public class GHVerifiedKey extends GHKey { + /** + * Instantiates a new Gh verified key. + */ public GHVerifiedKey() { this.verified = true; } diff --git a/src/main/java/org/kohsuke/github/GitHub.java b/src/main/java/org/kohsuke/github/GitHub.java index 875cb314c..78b9885c0 100644 --- a/src/main/java/org/kohsuke/github/GitHub.java +++ b/src/main/java/org/kohsuke/github/GitHub.java @@ -164,6 +164,10 @@ public class GitHub { /** * Obtains the credential from "~/.github" or from the System Environment Properties. + * + * @return the git hub + * @throws IOException + * the io exception */ public static GitHub connect() throws IOException { return GitHubBuilder.fromCredentials().build(); @@ -172,6 +176,13 @@ public class GitHub { /** * Version that connects to GitHub Enterprise. * + * @param apiUrl + * the api url + * @param oauthAccessToken + * the oauth access token + * @return the git hub + * @throws IOException + * the io exception * @deprecated Use {@link #connectToEnterpriseWithOAuth(String, String, String)} */ @Deprecated @@ -187,6 +198,13 @@ public class GitHub { * "http://ghe.acme.com/api/v3". Note that GitHub Enterprise has /api/v3 in the URL. For * historical reasons, this parameter still accepts the bare domain name, but that's considered * deprecated. + * @param login + * the login + * @param oauthAccessToken + * the oauth access token + * @return the git hub + * @throws IOException + * the io exception */ public static GitHub connectToEnterpriseWithOAuth(String apiUrl, String login, String oauthAccessToken) throws IOException { @@ -196,6 +214,15 @@ public class GitHub { /** * Version that connects to GitHub Enterprise. * + * @param apiUrl + * the api url + * @param login + * the login + * @param password + * the password + * @return the git hub + * @throws IOException + * the io exception * @deprecated Use with caution. Login with password is not a preferred method. */ @Deprecated @@ -203,11 +230,33 @@ public class GitHub { return new GitHubBuilder().withEndpoint(apiUrl).withPassword(login, password).build(); } + /** + * Connect git hub. + * + * @param login + * the login + * @param oauthAccessToken + * the oauth access token + * @return the git hub + * @throws IOException + * the io exception + */ public static GitHub connect(String login, String oauthAccessToken) throws IOException { return new GitHubBuilder().withOAuthToken(oauthAccessToken, login).build(); } /** + * Connect git hub. + * + * @param login + * the login + * @param oauthAccessToken + * the oauth access token + * @param password + * the password + * @return the git hub + * @throws IOException + * the io exception * @deprecated Either OAuth token or password is sufficient, so there's no point in passing both. Use * {@link #connectUsingPassword(String, String)} or {@link #connectUsingOAuth(String)}. */ @@ -216,22 +265,57 @@ public class GitHub { return new GitHubBuilder().withOAuthToken(oauthAccessToken, login).withPassword(login, password).build(); } + /** + * Connect using password git hub. + * + * @param login + * the login + * @param password + * the password + * @return the git hub + * @throws IOException + * the io exception + */ public static GitHub connectUsingPassword(String login, String password) throws IOException { return new GitHubBuilder().withPassword(login, password).build(); } + /** + * Connect using o auth git hub. + * + * @param oauthAccessToken + * the oauth access token + * @return the git hub + * @throws IOException + * the io exception + */ public static GitHub connectUsingOAuth(String oauthAccessToken) throws IOException { return new GitHubBuilder().withOAuthToken(oauthAccessToken).build(); } + /** + * Connect using o auth git hub. + * + * @param githubServer + * the github server + * @param oauthAccessToken + * the oauth access token + * @return the git hub + * @throws IOException + * the io exception + */ public static GitHub connectUsingOAuth(String githubServer, String oauthAccessToken) throws IOException { return new GitHubBuilder().withEndpoint(githubServer).withOAuthToken(oauthAccessToken).build(); } /** * Connects to GitHub anonymously. - * + *

* All operations that require authentication will fail. + * + * @return the git hub + * @throws IOException + * the io exception */ public static GitHub connectAnonymously() throws IOException { return new GitHubBuilder().build(); @@ -239,8 +323,14 @@ public class GitHub { /** * Connects to GitHub Enterprise anonymously. - * + *

* All operations that require authentication will fail. + * + * @param apiUrl + * the api url + * @return the git hub + * @throws IOException + * the io exception */ public static GitHub connectToEnterpriseAnonymously(String apiUrl) throws IOException { return new GitHubBuilder().withEndpoint(apiUrl).build(); @@ -248,7 +338,7 @@ public class GitHub { /** * An offline-only {@link GitHub} useful for parsing event notification from an unknown source. - * + *

* All operations that require a connection will fail. * * @return An offline-only {@link GitHub}. @@ -280,16 +370,29 @@ public class GitHub { return connector == HttpConnector.OFFLINE; } + /** + * Gets connector. + * + * @return the connector + */ public HttpConnector getConnector() { return connector; } + /** + * Gets api url. + * + * @return the api url + */ public String getApiUrl() { return apiUrl; } /** * Sets the custom connector used to make requests to GitHub. + * + * @param connector + * the connector */ public void setConnector(HttpConnector connector) { this.connector = connector; @@ -319,6 +422,10 @@ public class GitHub { /** * Gets the current rate limit. + * + * @return the rate limit + * @throws IOException + * the io exception */ public GHRateLimit getRateLimit() throws IOException { GHRateLimit rateLimit; @@ -417,6 +524,10 @@ public class GitHub { /** * Gets the {@link GHUser} that represents yourself. + * + * @return the myself + * @throws IOException + * the io exception */ @WithBridgeMethods(GHUser.class) public GHMyself getMyself() throws IOException { @@ -435,6 +546,12 @@ public class GitHub { /** * Obtains the object that represents the named user. + * + * @param login + * the login + * @return the user + * @throws IOException + * the io exception */ public GHUser getUser(String login) throws IOException { GHUser u = users.get(login); @@ -456,6 +573,10 @@ public class GitHub { /** * Interns the given {@link GHUser}. + * + * @param orig + * the orig + * @return the user */ protected GHUser getUser(GHUser orig) { GHUser u = users.get(orig.getLogin()); @@ -469,6 +590,12 @@ public class GitHub { /** * Gets {@link GHOrganization} specified by name. + * + * @param name + * the name + * @return the organization + * @throws IOException + * the io exception */ public GHOrganization getOrganization(String name) throws IOException { GHOrganization o = orgs.get(name); @@ -481,6 +608,8 @@ public class GitHub { /** * Gets a list of all organizations. + * + * @return the paged iterable */ public PagedIterable listOrganizations() { return listOrganizations(null); @@ -489,6 +618,9 @@ public class GitHub { /** * Gets a list of all organizations starting after the organization identifier specified by 'since'. * + * @param since + * the since + * @return the paged iterable * @see List All Orgs - Parameters */ public PagedIterable listOrganizations(final String since) { @@ -499,7 +631,12 @@ public class GitHub { /** * Gets the repository object from 'user/reponame' string that GitHub calls as "repository name" * - * @see GHRepository#getName() + * @param name + * the name + * @return the repository + * @throws IOException + * the io exception + * @see GHRepository#getName() GHRepository#getName() */ public GHRepository getRepository(String name) throws IOException { String[] tokens = name.split("/"); @@ -508,6 +645,12 @@ public class GitHub { /** * Gets the repository object from its ID + * + * @param id + * the id + * @return the repository by id + * @throws IOException + * the io exception */ public GHRepository getRepositoryById(String id) throws IOException { return retrieve().to("/repositories/" + id, GHRepository.class).wrap(this); @@ -516,9 +659,10 @@ public class GitHub { /** * Returns a list of popular open source licenses * - * @see GitHub API - Licenses - * * @return a list of popular open source licenses + * @throws IOException + * the io exception + * @see GitHub API - Licenses */ public PagedIterable listLicenses() throws IOException { return retrieve().asPagedIterable("/licenses", GHLicense[].class, item -> item.wrap(GitHub.this)); @@ -526,6 +670,10 @@ public class GitHub { /** * Returns a list of all users. + * + * @return the paged iterable + * @throws IOException + * the io exception */ public PagedIterable listUsers() throws IOException { return retrieve().asPagedIterable("/users", GHUser[].class, item -> item.wrapUp(GitHub.this)); @@ -537,7 +685,9 @@ public class GitHub { * @param key * The license key provided from the API * @return The license details - * @see GHLicense#getKey() + * @throws IOException + * the io exception + * @see GHLicense#getKey() GHLicense#getKey() */ public GHLicense getLicense(String key) throws IOException { return retrieve().to("/licenses/" + key, GHLicense.class); @@ -545,6 +695,10 @@ public class GitHub { /** * Gets complete list of open invitations for current user. + * + * @return the my invitations + * @throws IOException + * the io exception */ public List getMyInvitations() throws IOException { GHInvitation[] invitations = retrieve().to("/user/repository_invitations", GHInvitation[].class); @@ -556,9 +710,13 @@ public class GitHub { /** * This method returns shallowly populated organizations. - * + *

* To retrieve full organization details, you need to call {@link #getOrganization(String)} TODO: make this * automatic. + * + * @return the my organizations + * @throws IOException + * the io exception */ public Map getMyOrganizations() throws IOException { GHOrganization[] orgs = retrieve().to("/user/orgs", GHOrganization[].class); @@ -572,6 +730,12 @@ public class GitHub { /** * Alias for {@link #getUserPublicOrganizations(String)}. + * + * @param user + * the user + * @return the user public organizations + * @throws IOException + * the io exception */ public Map getUserPublicOrganizations(GHUser user) throws IOException { return getUserPublicOrganizations(user.getLogin()); @@ -579,13 +743,14 @@ public class GitHub { /** * This method returns a shallowly populated organizations. - * + *

* To retrieve full organization details, you need to call {@link #getOrganization(String)} * * @param login * the user to retrieve public Organization membership information for - * * @return the public Organization memberships for the user + * @throws IOException + * the io exception */ public Map getUserPublicOrganizations(String login) throws IOException { GHOrganization[] orgs = retrieve().to("/users/" + login + "/orgs", GHOrganization[].class); @@ -599,9 +764,13 @@ public class GitHub { /** * Gets complete map of organizations/teams that current user belongs to. - * + *

* Leverages the new GitHub API /user/teams made available recently to get in a single call the complete set of * organizations, teams and permissions in a single call. + * + * @return the my teams + * @throws IOException + * the io exception */ public Map> getMyTeams() throws IOException { Map> allMyTeams = new HashMap>(); @@ -620,6 +789,12 @@ public class GitHub { /** * Gets a sigle team by ID. + * + * @param id + * the id + * @return the team + * @throws IOException + * the io exception */ public GHTeam getTeam(int id) throws IOException { return retrieve().to("/teams/" + id, GHTeam.class).wrapUp(this); @@ -627,6 +802,10 @@ public class GitHub { /** * Public events visible to you. Equivalent of what's displayed on https://github.com/ + * + * @return the events + * @throws IOException + * the io exception */ public List getEvents() throws IOException { GHEventInfo[] events = retrieve().to("/events", GHEventInfo[].class); @@ -637,20 +816,41 @@ public class GitHub { /** * Gets a single gist by ID. + * + * @param id + * the id + * @return the gist + * @throws IOException + * the io exception */ public GHGist getGist(String id) throws IOException { return retrieve().to("/gists/" + id, GHGist.class).wrapUp(this); } + /** + * Create gist gh gist builder. + * + * @return the gh gist builder + */ public GHGistBuilder createGist() { return new GHGistBuilder(this); } /** * Parses the GitHub event object. - * + *

* This is primarily intended for receiving a POST HTTP call from a hook. Unfortunately, hook script payloads aren't * self-descriptive, so you need to know the type of the payload you are expecting. + * + * @param + * the type parameter + * @param r + * the r + * @param type + * the type + * @return the t + * @throws IOException + * the io exception */ public T parseEventPayload(Reader r, Class type) throws IOException { T t = MAPPER.readValue(r, type); @@ -661,7 +861,17 @@ public class GitHub { /** * Creates a new repository. * + * @param name + * the name + * @param description + * the description + * @param homepage + * the homepage + * @param isPublic + * the is public * @return Newly created repository. + * @throws IOException + * the io exception * @deprecated Use {@link #createRepository(String)} that uses a builder pattern to let you control every aspect. */ @Deprecated @@ -680,6 +890,10 @@ public class GitHub { *

* To create a repository in an organization, see * {@link GHOrganization#createRepository(String, String, String, GHTeam, boolean)} + * + * @param name + * the name + * @return the gh create repository builder */ public GHCreateRepositoryBuilder createRepository(String name) { return new GHCreateRepositoryBuilder(this, "/user/repos", name); @@ -687,9 +901,18 @@ public class GitHub { /** * Creates a new authorization. - * + *

* The token created can be then used for {@link GitHub#connectUsingOAuth(String)} in the future. * + * @param scope + * the scope + * @param note + * the note + * @param noteUrl + * the note url + * @return the gh authorization + * @throws IOException + * the io exception * @see Documentation */ public GHAuthorization createToken(Collection scope, String note, String noteUrl) throws IOException { @@ -700,13 +923,24 @@ public class GitHub { /** * Creates a new authorization using an OTP. - * + *

* Start by running createToken, if exception is thrown, prompt for OTP from user - * + *

* Once OTP is received, call this token request - * + *

* The token created can be then used for {@link GitHub#connectUsingOAuth(String)} in the future. * + * @param scope + * the scope + * @param note + * the note + * @param noteUrl + * the note url + * @param OTP + * the otp + * @return the gh authorization + * @throws IOException + * the io exception * @see Documentation */ public GHAuthorization createToken(Collection scope, String note, String noteUrl, Supplier OTP) @@ -724,6 +958,21 @@ public class GitHub { } /** + * Create or get auth gh authorization. + * + * @param clientId + * the client id + * @param clientSecret + * the client secret + * @param scopes + * the scopes + * @param note + * the note + * @param note_url + * the note url + * @return the gh authorization + * @throws IOException + * the io exception * @see docs */ @@ -736,6 +985,12 @@ public class GitHub { } /** + * Delete auth. + * + * @param id + * the id + * @throws IOException + * the io exception * @see Delete an * authorization */ @@ -744,6 +999,15 @@ public class GitHub { } /** + * Check auth gh authorization. + * + * @param clientId + * the client id + * @param accessToken + * the access token + * @return the gh authorization + * @throws IOException + * the io exception * @see Check an * authorization */ @@ -752,6 +1016,15 @@ public class GitHub { } /** + * Reset auth gh authorization. + * + * @param clientId + * the client id + * @param accessToken + * the access token + * @return the gh authorization + * @throws IOException + * the io exception * @see Reset an * authorization */ @@ -763,6 +1036,9 @@ public class GitHub { /** * Returns a list of all authorizations. * + * @return the paged iterable + * @throws IOException + * the io exception * @see List your * authorizations */ @@ -772,9 +1048,12 @@ public class GitHub { /** * Returns the GitHub App associated with the authentication credentials used. - * + *

* You must use a JWT to access this endpoint. * + * @return the app + * @throws IOException + * the io exception * @see Get the authenticated * GitHub App */ @@ -786,6 +1065,8 @@ public class GitHub { /** * Ensures that the credential is valid. + * + * @return the boolean */ public boolean isCredentialValid() { try { @@ -803,12 +1084,11 @@ public class GitHub { /** * Provides a list of GitHub's IP addresses. * - * @see Get Meta - * * @return an instance of {@link GHMeta} * @throws IOException * if the credentials supplied are invalid or if you're trying to access it as a GitHub App via the JWT * authentication + * @see Get Meta */ public GHMeta getMeta() throws IOException { return retrieve().to("/meta", GHMeta.class); @@ -828,14 +1108,41 @@ public class GitHub { return user; } + /** + * Gets project. + * + * @param id + * the id + * @return the project + * @throws IOException + * the io exception + */ public GHProject getProject(long id) throws IOException { return retrieve().withPreview(INERTIA).to("/projects/" + id, GHProject.class).wrap(this); } + /** + * Gets project column. + * + * @param id + * the id + * @return the project column + * @throws IOException + * the io exception + */ public GHProjectColumn getProjectColumn(long id) throws IOException { return retrieve().withPreview(INERTIA).to("/projects/columns/" + id, GHProjectColumn.class).wrap(this); } + /** + * Gets project card. + * + * @param id + * the id + * @return the project card + * @throws IOException + * the io exception + */ public GHProjectCard getProjectCard(long id) throws IOException { return retrieve().withPreview(INERTIA).to("/projects/columns/cards/" + id, GHProjectCard.class).wrap(this); } @@ -861,6 +1168,9 @@ public class GitHub { *

* This method returns normally if the endpoint is reachable and verified to be GitHub API URL. Otherwise this * method throws {@link IOException} to indicate the problem. + * + * @throws IOException + * the io exception */ public void checkApiUrlValidity() throws IOException { try { @@ -923,6 +1233,8 @@ public class GitHub { /** * Search commits. + * + * @return the gh commit search builder */ @Preview @Deprecated @@ -932,6 +1244,8 @@ public class GitHub { /** * Search issues. + * + * @return the gh issue search builder */ public GHIssueSearchBuilder searchIssues() { return new GHIssueSearchBuilder(this); @@ -939,6 +1253,8 @@ public class GitHub { /** * Search users. + * + * @return the gh user search builder */ public GHUserSearchBuilder searchUsers() { return new GHUserSearchBuilder(this); @@ -946,6 +1262,8 @@ public class GitHub { /** * Search repositories. + * + * @return the gh repository search builder */ public GHRepositorySearchBuilder searchRepositories() { return new GHRepositorySearchBuilder(this); @@ -953,6 +1271,8 @@ public class GitHub { /** * Search content. + * + * @return the gh content search builder */ public GHContentSearchBuilder searchContent() { return new GHContentSearchBuilder(this); @@ -960,6 +1280,8 @@ public class GitHub { /** * List all the notifications. + * + * @return the gh notification stream */ public GHNotificationStream listNotifications() { return new GHNotificationStream(this, "/notifications"); @@ -968,6 +1290,7 @@ public class GitHub { /** * This provides a dump of every public repository, in the order that they were created. * + * @return the paged iterable * @see documentation */ public PagedIterable listAllPublicRepositories() { @@ -979,6 +1302,7 @@ public class GitHub { * * @param since * The numeric ID of the last Repository that you’ve seen. See {@link GHRepository#getId()} + * @return the paged iterable * @see documentation */ public PagedIterable listAllPublicRepositories(final String since) { @@ -993,7 +1317,12 @@ public class GitHub { * It takes a Markdown document as plaintext and renders it as plain Markdown without a repository context (just * like a README.md file is rendered – this is the simplest way to preview a readme online). * - * @see GHRepository#renderMarkdown(String, MarkdownMode) + * @param text + * the text + * @return the reader + * @throws IOException + * the io exception + * @see GHRepository#renderMarkdown(String, MarkdownMode) GHRepository#renderMarkdown(String, MarkdownMode) */ public Reader renderMarkdown(String text) throws IOException { return new InputStreamReader(new Requester(this).with(new ByteArrayInputStream(text.getBytes("UTF-8"))) diff --git a/src/main/java/org/kohsuke/github/GitHubBuilder.java b/src/main/java/org/kohsuke/github/GitHubBuilder.java index 3a498ebe2..3fe8cb7ec 100644 --- a/src/main/java/org/kohsuke/github/GitHubBuilder.java +++ b/src/main/java/org/kohsuke/github/GitHubBuilder.java @@ -33,6 +33,9 @@ public class GitHubBuilder implements Cloneable { private RateLimitHandler rateLimitHandler = RateLimitHandler.WAIT; private AbuseLimitHandler abuseLimitHandler = AbuseLimitHandler.WAIT; + /** + * Instantiates a new Git hub builder. + */ public GitHubBuilder() { } @@ -73,6 +76,17 @@ public class GitHubBuilder implements Cloneable { } /** + * From environment git hub builder. + * + * @param loginVariableName + * the login variable name + * @param passwordVariableName + * the password variable name + * @param oauthVariableName + * the oauth variable name + * @return the git hub builder + * @throws IOException + * the io exception * @deprecated Use {@link #fromEnvironment()} to pick up standard set of environment variables, so that different * clients of this library will all recognize one consistent set of coordinates. */ @@ -88,6 +102,19 @@ public class GitHubBuilder implements Cloneable { } /** + * From environment git hub builder. + * + * @param loginVariableName + * the login variable name + * @param passwordVariableName + * the password variable name + * @param oauthVariableName + * the oauth variable name + * @param endpointVariableName + * the endpoint variable name + * @return the git hub builder + * @throws IOException + * the io exception * @deprecated Use {@link #fromEnvironment()} to pick up standard set of environment variables, so that different * clients of this library will all recognize one consistent set of coordinates. */ @@ -121,6 +148,10 @@ public class GitHubBuilder implements Cloneable { *

* For backward compatibility, the following environment variables are recognized but discouraged: login, password, * oauth + * + * @return the git hub builder + * @throws IOException + * the io exception */ public static GitHubBuilder fromEnvironment() throws IOException { Properties props = new Properties(); @@ -133,12 +164,28 @@ public class GitHubBuilder implements Cloneable { return fromProperties(props); } + /** + * From property file git hub builder. + * + * @return the git hub builder + * @throws IOException + * the io exception + */ public static GitHubBuilder fromPropertyFile() throws IOException { File homeDir = new File(System.getProperty("user.home")); File propertyFile = new File(homeDir, ".github"); return fromPropertyFile(propertyFile.getPath()); } + /** + * From property file git hub builder. + * + * @param propertyFileName + * the property file name + * @return the git hub builder + * @throws IOException + * the io exception + */ public static GitHubBuilder fromPropertyFile(String propertyFileName) throws IOException { Properties props = new Properties(); FileInputStream in = null; @@ -152,6 +199,13 @@ public class GitHubBuilder implements Cloneable { return fromProperties(props); } + /** + * From properties git hub builder. + * + * @param props + * the props + * @return the git hub builder + */ public static GitHubBuilder fromProperties(Properties props) { GitHubBuilder self = new GitHubBuilder(); self.withOAuthToken(props.getProperty("oauth"), props.getProperty("login")); @@ -162,27 +216,55 @@ public class GitHubBuilder implements Cloneable { } /** + * With endpoint git hub builder. + * * @param endpoint * The URL of GitHub (or GitHub enterprise) API endpoint, such as "https://api.github.com" or * "http://ghe.acme.com/api/v3". Note that GitHub Enterprise has /api/v3 in the URL. For * historical reasons, this parameter still accepts the bare domain name, but that's considered * deprecated. + * @return the git hub builder */ public GitHubBuilder withEndpoint(String endpoint) { this.endpoint = endpoint; return this; } + /** + * With password git hub builder. + * + * @param user + * the user + * @param password + * the password + * @return the git hub builder + */ public GitHubBuilder withPassword(String user, String password) { this.user = user; this.password = password; return this; } + /** + * With o auth token git hub builder. + * + * @param oauthToken + * the oauth token + * @return the git hub builder + */ public GitHubBuilder withOAuthToken(String oauthToken) { return withOAuthToken(oauthToken, null); } + /** + * With o auth token git hub builder. + * + * @param oauthToken + * the oauth token + * @param user + * the user + * @return the git hub builder + */ public GitHubBuilder withOAuthToken(String oauthToken, String user) { this.oauthToken = oauthToken; this.user = user; @@ -195,27 +277,55 @@ public class GitHubBuilder implements Cloneable { * @param appInstallationToken * A string containing the GitHub App installation token * @return the configured Builder from given GitHub App installation token. - * @see GHAppInstallation#createToken(java.util.Map) + * @see GHAppInstallation#createToken(java.util.Map) GHAppInstallation#createToken(java.util.Map) */ public GitHubBuilder withAppInstallationToken(String appInstallationToken) { return withOAuthToken(appInstallationToken, ""); } + /** + * With jwt token git hub builder. + * + * @param jwtToken + * the jwt token + * @return the git hub builder + */ public GitHubBuilder withJwtToken(String jwtToken) { this.jwtToken = jwtToken; return this; } + /** + * With connector git hub builder. + * + * @param connector + * the connector + * @return the git hub builder + */ public GitHubBuilder withConnector(HttpConnector connector) { this.connector = connector; return this; } + /** + * With rate limit handler git hub builder. + * + * @param handler + * the handler + * @return the git hub builder + */ public GitHubBuilder withRateLimitHandler(RateLimitHandler handler) { this.rateLimitHandler = handler; return this; } + /** + * With abuse limit handler git hub builder. + * + * @param handler + * the handler + * @return the git hub builder + */ public GitHubBuilder withAbuseLimitHandler(AbuseLimitHandler handler) { this.abuseLimitHandler = handler; return this; @@ -224,6 +334,10 @@ public class GitHubBuilder implements Cloneable { /** * Configures {@linkplain #withConnector(HttpConnector) connector} that uses HTTP library in JRE but use a specific * proxy, instead of the system default one. + * + * @param p + * the p + * @return the git hub builder */ public GitHubBuilder withProxy(final Proxy p) { return withConnector(new ImpatientHttpConnector(new HttpConnector() { @@ -233,6 +347,13 @@ public class GitHubBuilder implements Cloneable { })); } + /** + * Build git hub. + * + * @return the git hub + * @throws IOException + * the io exception + */ public GitHub build() throws IOException { return new GitHub(endpoint, user, oauthToken, jwtToken, password, connector, rateLimitHandler, abuseLimitHandler); diff --git a/src/main/java/org/kohsuke/github/GitUser.java b/src/main/java/org/kohsuke/github/GitUser.java index 1311916ad..8c32ae6de 100644 --- a/src/main/java/org/kohsuke/github/GitUser.java +++ b/src/main/java/org/kohsuke/github/GitUser.java @@ -6,7 +6,7 @@ import java.util.Date; /** * Represents a user in Git who authors/commits a commit. - * + *

* In contrast, {@link GHUser} is an user of GitHub. Because Git allows a person to use multiple e-mail addresses and * names when creating a commit, there's generally no meaningful mapping between {@link GHUser} and {@link GitUser}. * @@ -18,6 +18,8 @@ public class GitUser { private String name, email, date; /** + * Gets name. + * * @return Human readable name of the user, such as "Kohsuke Kawaguchi" */ public String getName() { @@ -25,13 +27,17 @@ public class GitUser { } /** - * @return E-mail address, such as "foo@example.com" + * Gets email. + * + * @return E -mail address, such as "foo@example.com" */ public String getEmail() { return email; } /** + * Gets date. + * * @return This field doesn't appear to be consistently available in all the situations where this class is used. */ public Date getDate() { diff --git a/src/main/java/org/kohsuke/github/HttpConnector.java b/src/main/java/org/kohsuke/github/HttpConnector.java index 2d87c148c..c88340066 100644 --- a/src/main/java/org/kohsuke/github/HttpConnector.java +++ b/src/main/java/org/kohsuke/github/HttpConnector.java @@ -17,6 +17,12 @@ import java.net.URL; public interface HttpConnector { /** * Opens a connection to the given URL. + * + * @param url + * the url + * @return the http url connection + * @throws IOException + * the io exception */ HttpURLConnection connect(URL url) throws IOException; diff --git a/src/main/java/org/kohsuke/github/HttpException.java b/src/main/java/org/kohsuke/github/HttpException.java index a11df26c0..8367fbe57 100644 --- a/src/main/java/org/kohsuke/github/HttpException.java +++ b/src/main/java/org/kohsuke/github/HttpException.java @@ -19,6 +19,8 @@ public class HttpException extends IOException { private final String url; /** + * Instantiates a new Http exception. + * * @param message * The detail message (which is saved for later retrieval by the {@link #getMessage()} method) * @param responseCode @@ -27,8 +29,8 @@ public class HttpException extends IOException { * Http response message * @param url * The url that was invoked - * @see HttpURLConnection#getResponseCode() - * @see HttpURLConnection#getResponseMessage() + * @see HttpURLConnection#getResponseCode() HttpURLConnection#getResponseCode() + * @see HttpURLConnection#getResponseMessage() HttpURLConnection#getResponseMessage() */ public HttpException(String message, int responseCode, String responseMessage, String url) { super(message); @@ -38,6 +40,8 @@ public class HttpException extends IOException { } /** + * Instantiates a new Http exception. + * * @param message * The detail message (which is saved for later retrieval by the {@link #getMessage()} method) * @param responseCode @@ -49,8 +53,8 @@ public class HttpException extends IOException { * @param cause * The cause (which is saved for later retrieval by the {@link #getCause()} method). (A null value is * permitted, and indicates that the cause is nonexistent or unknown.) - * @see HttpURLConnection#getResponseCode() - * @see HttpURLConnection#getResponseMessage() + * @see HttpURLConnection#getResponseCode() HttpURLConnection#getResponseCode() + * @see HttpURLConnection#getResponseMessage() HttpURLConnection#getResponseMessage() */ public HttpException(String message, int responseCode, String responseMessage, String url, Throwable cause) { super(message); @@ -61,6 +65,8 @@ public class HttpException extends IOException { } /** + * Instantiates a new Http exception. + * * @param responseCode * Http response code. {@code -1} if no code can be discerned. * @param responseMessage @@ -70,8 +76,8 @@ public class HttpException extends IOException { * @param cause * The cause (which is saved for later retrieval by the {@link #getCause()} method). (A null value is * permitted, and indicates that the cause is nonexistent or unknown.) - * @see HttpURLConnection#getResponseCode() - * @see HttpURLConnection#getResponseMessage() + * @see HttpURLConnection#getResponseCode() HttpURLConnection#getResponseCode() + * @see HttpURLConnection#getResponseMessage() HttpURLConnection#getResponseMessage() */ public HttpException(int responseCode, String responseMessage, String url, Throwable cause) { super("Server returned HTTP response code: " + responseCode + ", message: '" + responseMessage + "'" @@ -83,6 +89,8 @@ public class HttpException extends IOException { } /** + * Instantiates a new Http exception. + * * @param responseCode * Http response code. {@code -1} if no code can be discerned. * @param responseMessage @@ -92,8 +100,8 @@ public class HttpException extends IOException { * @param cause * The cause (which is saved for later retrieval by the {@link #getCause()} method). (A null value is * permitted, and indicates that the cause is nonexistent or unknown.) - * @see HttpURLConnection#getResponseCode() - * @see HttpURLConnection#getResponseMessage() + * @see HttpURLConnection#getResponseCode() HttpURLConnection#getResponseCode() + * @see HttpURLConnection#getResponseMessage() HttpURLConnection#getResponseMessage() */ public HttpException(int responseCode, String responseMessage, @CheckForNull URL url, Throwable cause) { this(responseCode, responseMessage, url == null ? null : url.toString(), cause); @@ -120,7 +128,7 @@ public class HttpException extends IOException { /** * The http URL that caused the exception * - * @return url + * @return url url */ public String getUrl() { return url; diff --git a/src/main/java/org/kohsuke/github/MarkdownMode.java b/src/main/java/org/kohsuke/github/MarkdownMode.java index f986a3d55..a4cb87f60 100644 --- a/src/main/java/org/kohsuke/github/MarkdownMode.java +++ b/src/main/java/org/kohsuke/github/MarkdownMode.java @@ -6,8 +6,8 @@ import java.util.Locale; * Rendering mode of markdown. * * @author Kohsuke Kawaguchi - * @see GitHub#renderMarkdown(String) - * @see GHRepository#renderMarkdown(String, MarkdownMode) + * @see GitHub#renderMarkdown(String) GitHub#renderMarkdown(String) + * @see GHRepository#renderMarkdown(String, MarkdownMode) GHRepository#renderMarkdown(String, MarkdownMode) */ public enum MarkdownMode { /** diff --git a/src/main/java/org/kohsuke/github/PagedIterable.java b/src/main/java/org/kohsuke/github/PagedIterable.java index e90ec27fe..536922e03 100644 --- a/src/main/java/org/kohsuke/github/PagedIterable.java +++ b/src/main/java/org/kohsuke/github/PagedIterable.java @@ -8,6 +8,8 @@ import java.util.Set; /** * {@link Iterable} that returns {@link PagedIterator} * + * @param + * the type parameter * @author Kohsuke Kawaguchi */ public abstract class PagedIterable implements Iterable { @@ -21,6 +23,10 @@ public abstract class PagedIterable implements Iterable { * *

* When set to non-zero, each API call will retrieve this many entries. + * + * @param size + * the size + * @return the paged iterable */ public PagedIterable withPageSize(int size) { this.size = size; @@ -31,10 +37,19 @@ public abstract class PagedIterable implements Iterable { return _iterator(size); } + /** + * Iterator paged iterator. + * + * @param pageSize + * the page size + * @return the paged iterator + */ public abstract PagedIterator _iterator(int pageSize); /** * Eagerly walk {@link Iterable} and return the result in a list. + * + * @return the list */ public List asList() { List r = new ArrayList(); @@ -46,6 +61,8 @@ public abstract class PagedIterable implements Iterable { /** * Eagerly walk {@link Iterable} and return the result in a set. + * + * @return the set */ public Set asSet() { LinkedHashSet r = new LinkedHashSet(); diff --git a/src/main/java/org/kohsuke/github/PagedIterator.java b/src/main/java/org/kohsuke/github/PagedIterator.java index 28b2360b3..e63273a3a 100644 --- a/src/main/java/org/kohsuke/github/PagedIterator.java +++ b/src/main/java/org/kohsuke/github/PagedIterator.java @@ -7,10 +7,12 @@ import java.util.NoSuchElementException; /** * Iterator over a paginated data source. - * + *

* Aside from the normal iterator operation, this method exposes {@link #nextPage()} that allows the caller to retrieve * items per page. * + * @param + * the type parameter * @author Kohsuke Kawaguchi */ public abstract class PagedIterator implements Iterator { @@ -26,6 +28,12 @@ public abstract class PagedIterator implements Iterator { this.base = base; } + /** + * Wrap up. + * + * @param page + * the page + */ protected abstract void wrapUp(T[] page); public boolean hasNext() { @@ -61,6 +69,8 @@ public abstract class PagedIterator implements Iterator { /** * Gets the next page worth of data. + * + * @return the list */ public List nextPage() { fetch(); diff --git a/src/main/java/org/kohsuke/github/PagedSearchIterable.java b/src/main/java/org/kohsuke/github/PagedSearchIterable.java index 974cf4676..d79b74332 100644 --- a/src/main/java/org/kohsuke/github/PagedSearchIterable.java +++ b/src/main/java/org/kohsuke/github/PagedSearchIterable.java @@ -7,6 +7,8 @@ import java.util.Iterator; /** * {@link PagedIterable} enhanced to report search result specific information. * + * @param + * the type parameter * @author Kohsuke Kawaguchi */ @SuppressFBWarnings(value = { "UWF_UNWRITTEN_PUBLIC_OR_PROTECTED_FIELD", "UWF_UNWRITTEN_FIELD", @@ -30,12 +32,19 @@ public abstract class PagedSearchIterable extends PagedIterable { /** * Returns the total number of hit, including the results that's not yet fetched. + * + * @return the total count */ public int getTotalCount() { populate(); return result.total_count; } + /** + * Is incomplete boolean. + * + * @return the boolean + */ public boolean isIncomplete() { populate(); return result.incomplete_results; @@ -48,6 +57,10 @@ public abstract class PagedSearchIterable extends PagedIterable { /** * Adapts {@link Iterator}. + * + * @param base + * the base + * @return the iterator */ protected Iterator adapt(final Iterator> base) { return new Iterator() { diff --git a/src/main/java/org/kohsuke/github/Preview.java b/src/main/java/org/kohsuke/github/Preview.java index dec90e9cb..69b029044 100644 --- a/src/main/java/org/kohsuke/github/Preview.java +++ b/src/main/java/org/kohsuke/github/Preview.java @@ -6,7 +6,7 @@ import java.lang.annotation.RetentionPolicy; /** * Indicates that the method/class/etc marked maps to GitHub API in the preview period. - * + *

* These APIs are subject to change and not a part of the backward compatibility commitment. Always used in conjunction * with 'deprecated' to raise awareness to clients. * diff --git a/src/main/java/org/kohsuke/github/RateLimitHandler.java b/src/main/java/org/kohsuke/github/RateLimitHandler.java index 0395aadff..20c3390b0 100644 --- a/src/main/java/org/kohsuke/github/RateLimitHandler.java +++ b/src/main/java/org/kohsuke/github/RateLimitHandler.java @@ -8,7 +8,7 @@ import java.net.HttpURLConnection; * Pluggable strategy to determine what to do when the API rate limit is reached. * * @author Kohsuke Kawaguchi - * @see GitHubBuilder#withRateLimitHandler(RateLimitHandler) + * @see GitHubBuilder#withRateLimitHandler(RateLimitHandler) GitHubBuilder#withRateLimitHandler(RateLimitHandler) * @see AbuseLimitHandler */ public abstract class RateLimitHandler { @@ -20,12 +20,14 @@ public abstract class RateLimitHandler { * an exception. If this method returns normally, another request will be attempted. For that to make sense, the * implementation needs to wait for some time. * - * @see API documentation from GitHub * @param e * Exception from Java I/O layer. If you decide to fail the processing, you can throw this exception (or * wrap this exception into another exception and throw it.) * @param uc * Connection that resulted in an error. Useful for accessing other response headers. + * @throws IOException + * the io exception + * @see API documentation from GitHub */ public abstract void onError(IOException e, HttpURLConnection uc) throws IOException; diff --git a/src/main/java/org/kohsuke/github/Reactable.java b/src/main/java/org/kohsuke/github/Reactable.java index f0beddca1..82908f28d 100644 --- a/src/main/java/org/kohsuke/github/Reactable.java +++ b/src/main/java/org/kohsuke/github/Reactable.java @@ -12,6 +12,8 @@ import java.io.IOException; public interface Reactable { /** * List all the reactions left to this object. + * + * @return the paged iterable */ @Preview @Deprecated @@ -19,6 +21,12 @@ public interface Reactable { /** * Leaves a reaction to this object. + * + * @param content + * the content + * @return the gh reaction + * @throws IOException + * the io exception */ @Preview @Deprecated diff --git a/src/main/java/org/kohsuke/github/ReactionContent.java b/src/main/java/org/kohsuke/github/ReactionContent.java index b9dc3e9ad..d1f1a01ed 100644 --- a/src/main/java/org/kohsuke/github/ReactionContent.java +++ b/src/main/java/org/kohsuke/github/ReactionContent.java @@ -19,11 +19,23 @@ public enum ReactionContent { this.content = content; } + /** + * Gets content. + * + * @return the content + */ @JsonValue public String getContent() { return content; } + /** + * For content reaction content. + * + * @param content + * the content + * @return the reaction content + */ @JsonCreator public static ReactionContent forContent(String content) { for (ReactionContent c : ReactionContent.values()) { diff --git a/src/main/java/org/kohsuke/github/Refreshable.java b/src/main/java/org/kohsuke/github/Refreshable.java index 05299dc7f..1f92457c1 100644 --- a/src/main/java/org/kohsuke/github/Refreshable.java +++ b/src/main/java/org/kohsuke/github/Refreshable.java @@ -7,19 +7,26 @@ import java.net.HttpURLConnection; import java.net.URL; /** - * - * + * The interface Refreshable. * * @author Liam Newman */ public interface Refreshable { /** * Opens a connection to the given URL. + * + * @throws IOException + * the io exception */ void refresh() throws IOException; /** * Calls refresh if the provided value is null + * + * @param value + * the value + * @throws IOException + * the io exception */ default void refresh(Object value) throws IOException { if (value == null) { diff --git a/src/main/java/org/kohsuke/github/Requester.java b/src/main/java/org/kohsuke/github/Requester.java index 0d3aa6495..fcb8f44a0 100644 --- a/src/main/java/org/kohsuke/github/Requester.java +++ b/src/main/java/org/kohsuke/github/Requester.java @@ -105,13 +105,27 @@ class Requester { /** * Sets the request HTTP header. - * + *

* If a header of the same name is already set, this method overrides it. + * + * @param name + * the name + * @param value + * the value */ public void setHeader(String name, String value) { headers.put(name, value); } + /** + * With header requester. + * + * @param name + * the name + * @param value + * the value + * @return the requester + */ public Requester withHeader(String name, String value) { setHeader(name, value); return this; @@ -123,6 +137,8 @@ class Requester { /** * Makes a request with authentication credential. + * + * @return the requester */ @Deprecated public Requester withCredential() { @@ -131,42 +147,123 @@ class Requester { return this; } + /** + * With requester. + * + * @param key + * the key + * @param value + * the value + * @return the requester + */ public Requester with(String key, int value) { return _with(key, value); } + /** + * With requester. + * + * @param key + * the key + * @param value + * the value + * @return the requester + */ public Requester with(String key, long value) { return _with(key, value); } + /** + * With requester. + * + * @param key + * the key + * @param value + * the value + * @return the requester + */ public Requester with(String key, Integer value) { if (value != null) _with(key, value); return this; } + /** + * With requester. + * + * @param key + * the key + * @param value + * the value + * @return the requester + */ public Requester with(String key, boolean value) { return _with(key, value); } + /** + * With requester. + * + * @param key + * the key + * @param value + * the value + * @return the requester + */ public Requester with(String key, Boolean value) { return _with(key, value); } + /** + * With requester. + * + * @param key + * the key + * @param e + * the e + * @return the requester + */ public Requester with(String key, Enum e) { if (e == null) return _with(key, null); return with(key, transformEnum(e)); } + /** + * With requester. + * + * @param key + * the key + * @param value + * the value + * @return the requester + */ public Requester with(String key, String value) { return _with(key, value); } + /** + * With requester. + * + * @param key + * the key + * @param value + * the value + * @return the requester + */ public Requester with(String key, Collection value) { return _with(key, value); } + /** + * With logins requester. + * + * @param key + * the key + * @param users + * the users + * @return the requester + */ public Requester withLogins(String key, Collection users) { List names = new ArrayList(users.size()); for (GHUser a : users) { @@ -175,10 +272,28 @@ class Requester { return with(key, names); } + /** + * With requester. + * + * @param key + * the key + * @param value + * the value + * @return the requester + */ public Requester with(String key, Map value) { return _with(key, value); } + /** + * With permissions requester. + * + * @param key + * the key + * @param value + * the value + * @return the requester + */ public Requester withPermissions(String key, Map value) { Map retMap = new HashMap(); for (Map.Entry entry : value.entrySet()) { @@ -187,16 +302,41 @@ class Requester { return _with(key, retMap); } + /** + * With requester. + * + * @param body + * the body + * @return the requester + */ public Requester with(@WillClose /* later */ InputStream body) { this.body = body; return this; } + /** + * With nullable requester. + * + * @param key + * the key + * @param value + * the value + * @return the requester + */ public Requester withNullable(String key, Object value) { args.add(new Entry(key, value)); return this; } + /** + * With requester. + * + * @param key + * the key + * @param value + * the value + * @return the requester + */ public Requester _with(String key, Object value) { if (value != null) { args.add(new Entry(key, value)); @@ -206,6 +346,12 @@ class Requester { /** * Unlike {@link #with(String, String)}, overrides the existing value + * + * @param key + * the key + * @param value + * the value + * @return the requester */ public Requester set(String key, Object value) { for (Entry e : args) { @@ -217,11 +363,25 @@ class Requester { return _with(key, value); } + /** + * Method requester. + * + * @param method + * the method + * @return the requester + */ public Requester method(String method) { this.method = method; return this; } + /** + * Content type requester. + * + * @param contentType + * the content type + * @return the requester + */ public Requester contentType(String contentType) { this.contentType = contentType; return this; @@ -237,6 +397,14 @@ class Requester { return this; } + /** + * To. + * + * @param tailApiUrl + * the tail api url + * @throws IOException + * the io exception + */ public void to(String tailApiUrl) throws IOException { to(tailApiUrl, null); } @@ -244,9 +412,15 @@ class Requester { /** * Sends a request to the specified URL, and parses the response into the given type via databinding. * + * @param + * the type parameter + * @param tailApiUrl + * the tail api url + * @param type + * the type + * @return {@link Reader} that reads the response. * @throws IOException * if the server returns 4xx/5xx responses. - * @return {@link Reader} that reads the response. */ public T to(String tailApiUrl, Class type) throws IOException { return _to(tailApiUrl, type, null); @@ -254,6 +428,16 @@ class Requester { /** * Like {@link #to(String, Class)} but updates an existing object instead of creating a new instance. + * + * @param + * the type parameter + * @param tailApiUrl + * the tail api url + * @param existingInstance + * the existing instance + * @return the t + * @throws IOException + * the io exception */ public T to(String tailApiUrl, T existingInstance) throws IOException { return _to(tailApiUrl, null, existingInstance); @@ -261,6 +445,18 @@ class Requester { /** * Short for {@code method(method).to(tailApiUrl,type)} + * + * @param + * the type parameter + * @param tailApiUrl + * the tail api url + * @param type + * the type + * @param method + * the method + * @return the t + * @throws IOException + * the io exception */ @Deprecated public T to(String tailApiUrl, Class type, String method) throws IOException { @@ -318,6 +514,12 @@ class Requester { /** * Makes a request and just obtains the HTTP status code. + * + * @param tailApiUrl + * the tail api url + * @return the int + * @throws IOException + * the io exception */ public int asHttpStatusCode(String tailApiUrl) throws IOException { while (true) {// loop while API rate limit is hit @@ -336,6 +538,15 @@ class Requester { } } + /** + * As stream input stream. + * + * @param tailApiUrl + * the tail api url + * @return the input stream + * @throws IOException + * the io exception + */ public InputStream asStream(String tailApiUrl) throws IOException { while (true) {// loop while API rate limit is hit setupConnection(root.getApiURL(tailApiUrl)); @@ -406,6 +617,13 @@ class Requester { root.updateCoreRateLimit(observed); } + /** + * Gets response header. + * + * @param header + * the header + * @return the response header + */ public String getResponseHeader(String header) { return uc.getHeaderField(header); } diff --git a/src/main/java/org/kohsuke/github/TrafficInfo.java b/src/main/java/org/kohsuke/github/TrafficInfo.java index 9b232e9f1..a23e6c033 100644 --- a/src/main/java/org/kohsuke/github/TrafficInfo.java +++ b/src/main/java/org/kohsuke/github/TrafficInfo.java @@ -1,16 +1,22 @@ package org.kohsuke.github; /** + * The interface TrafficInfo. + * * @author Kohsuke Kawaguchi */ public interface TrafficInfo { /** * Total count of hits. + * + * @return the count */ int getCount(); /** * Unique visitors. + * + * @return the uniques */ int getUniques(); } diff --git a/src/main/java/org/kohsuke/github/example/dataobject/ReadOnlyObjects.java b/src/main/java/org/kohsuke/github/example/dataobject/ReadOnlyObjects.java index e56f40597..ea39c8e00 100644 --- a/src/main/java/org/kohsuke/github/example/dataobject/ReadOnlyObjects.java +++ b/src/main/java/org/kohsuke/github/example/dataobject/ReadOnlyObjects.java @@ -23,11 +23,9 @@ import java.util.List; * * * @author Liam Newman - * * @see org.kohsuke.github.GHMeta * @see Get Meta */ - public final class ReadOnlyObjects { /** @@ -36,18 +34,53 @@ public final class ReadOnlyObjects { * @author Liam Newman */ public interface GHMetaExample { + /** + * Is verifiable password authentication boolean. + * + * @return the boolean + */ boolean isVerifiablePasswordAuthentication(); + /** + * Gets hooks. + * + * @return the hooks + */ List getHooks(); + /** + * Gets git. + * + * @return the git + */ List getGit(); + /** + * Gets web. + * + * @return the web + */ List getWeb(); + /** + * Gets api. + * + * @return the api + */ List getApi(); + /** + * Gets pages. + * + * @return the pages + */ List getPages(); + /** + * Gets importer. + * + * @return the importer + */ List getImporter(); } @@ -70,7 +103,6 @@ public final class ReadOnlyObjects { * @author Paulo Miguel Almeida * @see org.kohsuke.github.GHMeta */ - public static class GHMetaPublic implements GHMetaExample { @JsonProperty("verifiable_password_authentication") @@ -86,6 +118,12 @@ public final class ReadOnlyObjects { return verifiablePasswordAuthentication; } + /** + * Sets verifiable password authentication. + * + * @param verifiablePasswordAuthentication + * the verifiable password authentication + */ public void setVerifiablePasswordAuthentication(boolean verifiablePasswordAuthentication) { this.verifiablePasswordAuthentication = verifiablePasswordAuthentication; } @@ -94,6 +132,12 @@ public final class ReadOnlyObjects { return hooks; } + /** + * Sets hooks. + * + * @param hooks + * the hooks + */ public void setHooks(List hooks) { this.hooks = hooks; } @@ -102,6 +146,12 @@ public final class ReadOnlyObjects { return git; } + /** + * Sets git. + * + * @param git + * the git + */ public void setGit(List git) { this.git = git; } @@ -110,6 +160,12 @@ public final class ReadOnlyObjects { return web; } + /** + * Sets web. + * + * @param web + * the web + */ public void setWeb(List web) { this.web = web; } @@ -118,6 +174,12 @@ public final class ReadOnlyObjects { return api; } + /** + * Sets api. + * + * @param api + * the api + */ public void setApi(List api) { this.api = api; } @@ -126,6 +188,12 @@ public final class ReadOnlyObjects { return pages; } + /** + * Sets pages. + * + * @param pages + * the pages + */ public void setPages(List pages) { this.pages = pages; } @@ -134,6 +202,12 @@ public final class ReadOnlyObjects { return importer; } + /** + * Sets importer. + * + * @param importer + * the importer + */ public void setImporter(List importer) { this.importer = importer; } @@ -160,7 +234,6 @@ public final class ReadOnlyObjects { * @author Liam Newman * @see org.kohsuke.github.GHMeta */ - public static class GHMetaPackage implements GHMetaExample { private boolean verifiablePasswordAuthentication; diff --git a/src/main/java/org/kohsuke/github/extras/ImpatientHttpConnector.java b/src/main/java/org/kohsuke/github/extras/ImpatientHttpConnector.java index 9513b3d6f..c02d75bdf 100644 --- a/src/main/java/org/kohsuke/github/extras/ImpatientHttpConnector.java +++ b/src/main/java/org/kohsuke/github/extras/ImpatientHttpConnector.java @@ -18,6 +18,10 @@ public class ImpatientHttpConnector implements HttpConnector { private final int readTimeout, connectTimeout; /** + * Instantiates a new Impatient http connector. + * + * @param base + * the base * @param connectTimeout * HTTP connection timeout in milliseconds * @param readTimeout @@ -29,10 +33,24 @@ public class ImpatientHttpConnector implements HttpConnector { this.readTimeout = readTimeout; } + /** + * Instantiates a new Impatient http connector. + * + * @param base + * the base + * @param timeout + * the timeout + */ public ImpatientHttpConnector(HttpConnector base, int timeout) { this(base, timeout, timeout); } + /** + * Instantiates a new Impatient http connector. + * + * @param base + * the base + */ public ImpatientHttpConnector(HttpConnector base) { this(base, CONNECT_TIMEOUT, READ_TIMEOUT); } diff --git a/src/main/java/org/kohsuke/github/extras/OkHttp3Connector.java b/src/main/java/org/kohsuke/github/extras/OkHttp3Connector.java index 4edfd460e..7e9dabe35 100644 --- a/src/main/java/org/kohsuke/github/extras/OkHttp3Connector.java +++ b/src/main/java/org/kohsuke/github/extras/OkHttp3Connector.java @@ -10,18 +10,24 @@ import java.net.URL; /** * {@link HttpConnector} for {@link OkHttpClient}. - * + *

* Unlike {@link #DEFAULT}, OkHttp does response caching. Making a conditional request against GitHubAPI and receiving a * 304 response does not count against the rate limit. See http://developer.github.com/v3/#conditional-requests * - * @see org.kohsuke.github.extras.okhttp3.OkHttpConnector * @author Roberto Tyley * @author Kohsuke Kawaguchi + * @see org.kohsuke.github.extras.okhttp3.OkHttpConnector */ @Deprecated public class OkHttp3Connector implements HttpConnector { private final OkUrlFactory urlFactory; + /** + * Instantiates a new Ok http 3 connector. + * + * @param urlFactory + * the url factory + */ /* * @see org.kohsuke.github.extras.okhttp3.OkHttpConnector */ diff --git a/src/main/java/org/kohsuke/github/extras/OkHttpConnector.java b/src/main/java/org/kohsuke/github/extras/OkHttpConnector.java index 1cb38e9f6..43c2da4c1 100644 --- a/src/main/java/org/kohsuke/github/extras/OkHttpConnector.java +++ b/src/main/java/org/kohsuke/github/extras/OkHttpConnector.java @@ -24,7 +24,7 @@ import javax.net.ssl.SSLSocketFactory; /** * {@link HttpConnector} for {@link OkHttpClient}. - * + *

* Unlike {@link #DEFAULT}, OkHttp does response caching. Making a conditional request against GitHubAPI and receiving a * 304 response does not count against the rate limit. See http://developer.github.com/v3/#conditional-requests * @@ -37,6 +37,12 @@ public class OkHttpConnector implements HttpConnector { private final String maxAgeHeaderValue; + /** + * Instantiates a new Ok http connector. + * + * @param urlFactory + * the url factory + */ public OkHttpConnector(OkUrlFactory urlFactory) { this(urlFactory, 0); } diff --git a/src/main/java/org/kohsuke/github/extras/okhttp3/ObsoleteUrlFactory.java b/src/main/java/org/kohsuke/github/extras/okhttp3/ObsoleteUrlFactory.java index a071e7e72..39fca925d 100644 --- a/src/main/java/org/kohsuke/github/extras/okhttp3/ObsoleteUrlFactory.java +++ b/src/main/java/org/kohsuke/github/extras/okhttp3/ObsoleteUrlFactory.java @@ -111,14 +111,32 @@ public final class ObsoleteUrlFactory implements URLStreamHandlerFactory, Clonea private OkHttpClient client; + /** + * Instantiates a new Obsolete url factory. + * + * @param client + * the client + */ public ObsoleteUrlFactory(OkHttpClient client) { this.client = client; } + /** + * Client ok http client. + * + * @return the ok http client + */ public OkHttpClient client() { return client; } + /** + * Sets client. + * + * @param client + * the client + * @return the client + */ public ObsoleteUrlFactory setClient(OkHttpClient client) { this.client = client; return this; @@ -133,6 +151,13 @@ public final class ObsoleteUrlFactory implements URLStreamHandlerFactory, Clonea return new ObsoleteUrlFactory(client); } + /** + * Open http url connection. + * + * @param url + * the url + * @return the http url connection + */ public HttpURLConnection open(URL url) { return open(url, client.proxy()); } @@ -752,6 +777,9 @@ public final class ObsoleteUrlFactory implements URLStreamHandlerFactory, Clonea // Guarded by HttpUrlConnection.this. private boolean proceed; + /** + * Proceed. + */ public void proceed() { synchronized (lock) { this.proceed = true; @@ -867,6 +895,15 @@ public final class ObsoleteUrlFactory implements URLStreamHandlerFactory, Clonea return null; // Let the caller provide this in a regular header. } + /** + * Prepare to send request request. + * + * @param request + * the request + * @return the request + * @throws IOException + * the io exception + */ public Request prepareToSendRequest(Request request) throws IOException { return request; } @@ -930,6 +967,11 @@ public final class ObsoleteUrlFactory implements URLStreamHandlerFactory, Clonea this.delegate = delegate; } + /** + * Handshake handshake. + * + * @return the handshake + */ protected abstract Handshake handshake(); @Override diff --git a/src/main/java/org/kohsuke/github/extras/okhttp3/OkHttpConnector.java b/src/main/java/org/kohsuke/github/extras/okhttp3/OkHttpConnector.java index e60b3455c..d9bd2b027 100644 --- a/src/main/java/org/kohsuke/github/extras/okhttp3/OkHttpConnector.java +++ b/src/main/java/org/kohsuke/github/extras/okhttp3/OkHttpConnector.java @@ -16,7 +16,7 @@ import java.util.concurrent.TimeUnit; /** * {@link HttpConnector} for {@link OkHttpClient}. - * + *

* Unlike {@link #DEFAULT}, OkHttp does response caching. Making a conditional request against GitHubAPI and receiving a * 304 response does not count against the rate limit. See http://developer.github.com/v3/#conditional-requests * @@ -30,10 +30,24 @@ public class OkHttpConnector implements HttpConnector { private final OkHttpClient client; private final ObsoleteUrlFactory urlFactory; + /** + * Instantiates a new Ok http connector. + * + * @param client + * the client + */ public OkHttpConnector(OkHttpClient client) { this(client, 0); } + /** + * Instantiates a new Ok http connector. + * + * @param client + * the client + * @param cacheMaxAge + * the cache max age + */ public OkHttpConnector(OkHttpClient client, int cacheMaxAge) { OkHttpClient.Builder builder = client.newBuilder();