Javadoc round 2
diff --git a/src/main/java/org/apache/jenkins/gitpubsub/ASFAvatarMetadataAction.java b/src/main/java/org/apache/jenkins/gitpubsub/ASFAvatarMetadataAction.java
index e206ec0..ed320a1 100644
--- a/src/main/java/org/apache/jenkins/gitpubsub/ASFAvatarMetadataAction.java
+++ b/src/main/java/org/apache/jenkins/gitpubsub/ASFAvatarMetadataAction.java
@@ -18,14 +18,32 @@
import edu.umd.cs.findbugs.annotations.CheckForNull;
import edu.umd.cs.findbugs.annotations.NonNull;
import jenkins.scm.api.metadata.AvatarMetadataAction;
+import org.apache.commons.lang.StringUtils;
+/**
+ * Provides the avatar information for a {@link ASFGitSCMNavigator}.
+ */
public class ASFAvatarMetadataAction extends AvatarMetadataAction {
+ /**
+ * The avatar url.
+ */
+ @NonNull
private final String avatarUrl;
+ /**
+ * The avatar description.
+ */
+ @CheckForNull
private final String avatarDescription;
+ /**
+ * Constructor.
+ *
+ * @param avatarUrl The avatar url.
+ * @param avatarDescription The avatar description.
+ */
public ASFAvatarMetadataAction(@NonNull String avatarUrl, @CheckForNull String avatarDescription) {
this.avatarUrl = avatarUrl;
- this.avatarDescription = avatarDescription;
+ this.avatarDescription = StringUtils.trimToNull(avatarDescription);
}
/**
diff --git a/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMFile.java b/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMFile.java
index ecd3d5b..6ec23a7 100644
--- a/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMFile.java
+++ b/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMFile.java
@@ -35,16 +35,35 @@
import static org.apache.jenkins.gitpubsub.ASFGitSCMFileSystem.TEN_SECONDS_OF_MILLIS;
import static org.apache.jenkins.gitpubsub.ASFGitSCMNavigator.RFC_2822;
+/**
+ * A {@link SCMFile} that is backed by a GitWeb server hosted on {@code apache.org}.
+ */
public class ASFGitSCMFile extends SCMFile {
+ /**
+ * The Git URL from which the project and gitweb server can be derived.
+ */
private final String remote;
+ /**
+ * The ref or hash that the file is being accessed for.
+ */
private final String refOrHash;
+ /**
+ * Root constructor.
+ * @param remote The Git URL from which the project and gitweb server can be derived.
+ * @param refOrHash The ref or hash that the file is being accessed for.
+ */
ASFGitSCMFile(String remote, String refOrHash) {
this.remote = remote;
this.refOrHash = refOrHash;
}
+ /**
+ * Child constructor.
+ * @param parent the parent file.
+ * @param name the name of the child.
+ */
ASFGitSCMFile(@NonNull ASFGitSCMFile parent, String name) {
super(parent, name);
this.remote = parent.remote;
diff --git a/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMFileSystem.java b/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMFileSystem.java
index 7c90dad..11f8586 100644
--- a/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMFileSystem.java
+++ b/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMFileSystem.java
@@ -20,6 +20,7 @@
import edu.umd.cs.findbugs.annotations.NonNull;
import hudson.Extension;
import hudson.plugins.git.GitSCM;
+import hudson.plugins.git.UserRemoteConfig;
import java.io.IOException;
import java.io.OutputStream;
import java.net.URL;
@@ -37,6 +38,7 @@
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import jenkins.plugins.git.AbstractGitSCMSource;
+import jenkins.plugins.git.GitSCMSource;
import jenkins.plugins.git.GitSCMTelescope;
import jenkins.plugins.git.GitTagSCMHead;
import jenkins.plugins.git.GitTagSCMRevision;
@@ -57,15 +59,36 @@
import static org.apache.jenkins.gitpubsub.ASFGitSCMNavigator.RFC_2822;
+/**
+ * A {@link SCMFileSystem} that can browse a git repository exposed by a gitweb server on {@code apache.org}.
+ */
public class ASFGitSCMFileSystem extends SCMFileSystem {
+ /**
+ * Extracts the SHA1 from the {@code h=} portion of a gitweb URL.
+ */
static final Pattern URL_EXTRACT_H = Pattern.compile(".*[;?]h=([a-fA-F0-9]{40})([;?].*)?");
+ /**
+ * The default timeout for remote operations.
+ */
static final int TEN_SECONDS_OF_MILLIS = 10000;
+ /**
+ * Our logger.
+ */
private static final Logger LOGGER = Logger.getLogger(ASFGitSCMFileSystem.class.getName());
+ /**
+ * The GitWeb servers maintained by Apache. (This is a mutable list to support testing)
+ */
static final List<String> GIT_WEB_HOSTS = new ArrayList<>(Arrays.asList(
ASFGitSCMNavigator.GIT_WIP, ASFGitSCMNavigator.GIT_BOX
));
+ /**
+ * The Git URL from which the project and gitweb server can be derived.
+ */
private final String remote;
+ /**
+ * The ref or hash that the file is being accessed for.
+ */
private final String refOrHash;
/**
@@ -264,8 +287,15 @@
return count > 0;
}
+ /**
+ * Builds a {@link UriTemplate} from the supplied template and the {@link GitSCMSource#getRemote()}.
+ * @param template the template, must include {@code {+server}} for the server and {@code {?p}} for the project.
+ * @param remote the {@link GitSCMSource#getRemote()}.
+ * @return the template.
+ * @throws IOException if the remote is unknown.
+ */
static UriTemplate buildTemplateWithRemote(String template, @NonNull String remote) throws IOException {
- UriTemplate commitTemplate;
+ UriTemplate result;
String server = null;
String p = null;
for (String prefix : GIT_WEB_HOSTS) {
@@ -279,12 +309,14 @@
throw new IOException("Unknown remote: " + remote);
}
- commitTemplate = UriTemplate.fromTemplate(template);
- commitTemplate.set("server", server).set("p", p);
- return commitTemplate;
+ result = UriTemplate.fromTemplate(template);
+ result.set("server", server).set("p", p);
+ return result;
}
-
+ /**
+ * A {@link GitSCMTelescope} for GitWeb services on {@code apache.org}.
+ */
@Extension
public static class TelescopeImpl extends GitSCMTelescope {
diff --git a/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigator.java b/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigator.java
index 9bc66c2..5034a5d 100644
--- a/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigator.java
+++ b/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigator.java
@@ -15,6 +15,7 @@
*/
package org.apache.jenkins.gitpubsub;
+import edu.umd.cs.findbugs.annotations.CheckForNull;
import edu.umd.cs.findbugs.annotations.NonNull;
import hudson.Extension;
import hudson.ExtensionList;
@@ -60,30 +61,70 @@
import org.kohsuke.stapler.DataBoundConstructor;
import org.kohsuke.stapler.DataBoundSetter;
+/**
+ * A {@link SCMNavigator} that navigates {@code apache.org} hosted git repositories.
+ */
public class ASFGitSCMNavigator extends SCMNavigator {
+ /**
+ * The date format used by GitWeb.
+ */
static final String RFC_2822 = "EEE, dd MMM yyyy HH:mm:ss Z";
+ /**
+ * The first Git hosting for Apache.
+ */
static final String GIT_WIP = "https://git-wip-us.apache.org/repos/asf";
+ /**
+ * The second Git hosting for Apache.
+ */
static final String GIT_BOX = "https://gitbox.apache.org/repos/asf";
+ /**
+ * The server that we are navigating.
+ */
+ @NonNull
private final String server;
+ /**
+ * The traits to apply.
+ */
private List<SCMTrait<?>> traits = new ArrayList<>();
+ /**
+ * Constructor.
+ *
+ * @param server the server to navigate.
+ */
@DataBoundConstructor
- public ASFGitSCMNavigator(String server) {
+ public ASFGitSCMNavigator(@NonNull String server) {
this.server = server;
}
+ /**
+ * Gets the server to navigate.
+ *
+ * @return the server to navigate.
+ */
+ @NonNull
public String getServer() {
return server;
}
+ /**
+ * Gets the traits.
+ *
+ * @return the traits.
+ */
@NonNull
public List<SCMTrait<?>> getTraits() {
return Collections.unmodifiableList(traits);
}
+ /**
+ * Sets the traits.
+ *
+ * @param traits the traits.
+ */
@DataBoundSetter
- public void setTraits(List<SCMTrait<?>> traits) {
+ public void setTraits(@CheckForNull List<? extends SCMTrait<?>> traits) {
this.traits = new ArrayList<>(Util.fixNull(traits));
}
@@ -124,7 +165,7 @@
@Override
public SCMSource create(@NonNull String projectName) throws IOException, InterruptedException {
return new ASFGitSCMSourceBuilder(getId() + "::" + projectName,
- server , projectName
+ server, projectName
)
.withTraits(traits)
.build();
@@ -171,6 +212,9 @@
return result;
}
+ /**
+ * Our descriptor.
+ */
@Extension
public static class DescriptorImpl extends SCMNavigatorDescriptor {
@@ -183,11 +227,21 @@
return Messages.ASFGitSCMNavigator_displayName();
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public SCMNavigator newInstance(String name) {
- return new ASFGitSCMNavigator(GIT_WIP);
+ ASFGitSCMNavigator result = new ASFGitSCMNavigator(GIT_BOX);
+ result.setTraits(getTraitsDefaults());
+ return result;
}
+ /**
+ * Populates the drop-down for {@link ASFGitSCMNavigator#getServer()}
+ *
+ * @return the drop-down entries.
+ */
public ListBoxModel doFillServerItems() {
ListBoxModel result = new ListBoxModel();
result.add(Messages.ASFGitSCMNavigator_gitWip(), GIT_WIP);
@@ -195,6 +249,11 @@
return result;
}
+ /**
+ * Populates the available trait descriptors.
+ *
+ * @return the available trait descriptors.
+ */
@SuppressWarnings("unused") // jelly
public List<NamedArrayList<? extends SCMTraitDescriptor<?>>> getTraitsDescriptorLists() {
GitSCMSource.DescriptorImpl sourceDescriptor =
@@ -223,14 +282,19 @@
}
},
true, result);
- NamedArrayList.select(all, Messages.ASFGitSCMNavigator_withinRepositories(), NamedArrayList
- .anyOf(NamedArrayList.withAnnotation(Discovery.class),
- NamedArrayList.withAnnotation(Selection.class)),
+ NamedArrayList.select(all, Messages.ASFGitSCMNavigator_withinRepositories(),
+ NamedArrayList.anyOf(NamedArrayList.withAnnotation(Discovery.class),
+ NamedArrayList.withAnnotation(Selection.class)),
true, result);
NamedArrayList.select(all, Messages.ASFGitSCMNavigator_additionalBehaviours(), null, true, result);
return result;
}
+ /**
+ * Populate the default traits for new instances.
+ *
+ * @return the default traits.
+ */
public List<SCMTrait<? extends SCMTrait<?>>> getTraitsDefaults() {
GitSCMSource.DescriptorImpl descriptor =
ExtensionList.lookup(Descriptor.class).get(GitSCMSource.DescriptorImpl.class);
diff --git a/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigatorContext.java b/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigatorContext.java
index b38cefa..58eb702 100644
--- a/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigatorContext.java
+++ b/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigatorContext.java
@@ -20,7 +20,11 @@
import jenkins.scm.api.SCMSourceObserver;
import jenkins.scm.api.trait.SCMNavigatorContext;
-public class ASFGitSCMNavigatorContext extends SCMNavigatorContext<ASFGitSCMNavigatorContext, ASFGitSCMNavigatorRequest>{
+/**
+ * The {@link SCMNavigatorContext} for {@link ASFGitSCMNavigator}.
+ */
+public class ASFGitSCMNavigatorContext
+ extends SCMNavigatorContext<ASFGitSCMNavigatorContext, ASFGitSCMNavigatorRequest> {
private String avatarUrl;
private String avatarDescription;
private String objectDisplayName;
diff --git a/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigatorRequest.java b/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigatorRequest.java
index b2c8b10..38567a1 100644
--- a/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigatorRequest.java
+++ b/src/main/java/org/apache/jenkins/gitpubsub/ASFGitSCMNavigatorRequest.java
@@ -20,6 +20,9 @@
import jenkins.scm.api.SCMSourceObserver;
import jenkins.scm.api.trait.SCMNavigatorRequest;
+/**
+ * A {@link SCMNavigatorRequest} for {@link ASFGitSCMNavigatorContext}.
+ */
public class ASFGitSCMNavigatorRequest extends SCMNavigatorRequest {
/**
* Constructor.
@@ -28,11 +31,11 @@
* @param context the context.
* @param observer the observer.
*/
- public ASFGitSCMNavigatorRequest(@NonNull SCMNavigator source,
- @NonNull
- ASFGitSCMNavigatorContext context,
- @NonNull
- SCMSourceObserver observer) {
+ ASFGitSCMNavigatorRequest(@NonNull SCMNavigator source,
+ @NonNull
+ ASFGitSCMNavigatorContext context,
+ @NonNull
+ SCMSourceObserver observer) {
super(source, context, observer);
}
}
diff --git a/src/main/java/org/apache/jenkins/gitpubsub/ASFMetadataSCMNavigatorTrait.java b/src/main/java/org/apache/jenkins/gitpubsub/ASFMetadataSCMNavigatorTrait.java
index a38dfd6..b6cff82 100644
--- a/src/main/java/org/apache/jenkins/gitpubsub/ASFMetadataSCMNavigatorTrait.java
+++ b/src/main/java/org/apache/jenkins/gitpubsub/ASFMetadataSCMNavigatorTrait.java
@@ -24,6 +24,9 @@
import org.apache.commons.lang.StringUtils;
import org.kohsuke.stapler.DataBoundConstructor;
+/**
+ * A {@link SCMNavigatorTrait} that defines the avatar and object metadata for a {@link ASFGitSCMNavigator}.
+ */
public class ASFMetadataSCMNavigatorTrait extends SCMNavigatorTrait {
private final String avatarUrl;
private final String avatarDescription;
