Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[JENKINS-43507] Documentation drives code improvements
  • Loading branch information
stephenc committed May 4, 2017
1 parent 4ce900a commit b7c5b5d
Show file tree
Hide file tree
Showing 6 changed files with 161 additions and 7 deletions.
60 changes: 60 additions & 0 deletions src/main/java/jenkins/scm/api/trait/SCMHeadAuthority.java
Expand Up @@ -27,9 +27,14 @@
import edu.umd.cs.findbugs.annotations.CheckForNull;
import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.OverrideMustInvoke;
import hudson.DescriptorExtensionList;
import hudson.model.AbstractDescribableImpl;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import jenkins.model.Jenkins;
import jenkins.scm.api.SCMHead;
import jenkins.scm.api.SCMHeadOrigin;
import jenkins.scm.api.SCMRevision;
import jenkins.scm.api.mixin.SCMHeadMixin;

Expand Down Expand Up @@ -148,4 +153,59 @@ protected boolean checkTrusted(@NonNull S request, @NonNull R revision) throws I
public SCMHeadAuthorityDescriptor getDescriptor() {
return (SCMHeadAuthorityDescriptor) super.getDescriptor();
}

/**
* Returns a list of all {@link SCMHeadAuthorityDescriptor} instances.
*
* @return a list of all {@link SCMHeadAuthorityDescriptor} instances.
*/
@SuppressWarnings("unchecked")
public static DescriptorExtensionList<SCMHeadAuthority<?, ?, ?>, SCMHeadAuthorityDescriptor> all() {
return (DescriptorExtensionList) Jenkins.getActiveInstance().getDescriptorList(SCMHeadAuthority.class);
}

/**
* Retursn the subset of {@link SCMHeadAuthorityDescriptor} instances applicable to the supplied criteria.
*
* @param requestClass the {@link SCMSourceRequest} class (or {@code null} to match any).
* @param headClass the {@link SCMHeadMixin} class (or {@code null} to match any).
* @param revisionClass the {@link SCMRevision} class (or {@code null} to match any).
* @param origins the {@link SCMHeadOrigin} instances.
* @return the list of matching {@link SCMHeadAuthorityDescriptor} instances.
*/
public static List<SCMHeadAuthorityDescriptor> _for(@CheckForNull Class<? extends SCMSourceRequest> requestClass,
@CheckForNull Class<? extends SCMHeadMixin> headClass,
@CheckForNull Class<? extends SCMRevision> revisionClass,
Class<? extends SCMHeadOrigin>... origins) {
if (requestClass == null) {
requestClass = SCMSourceRequest.class;
}
if (headClass == null) {
headClass = SCMHeadMixin.class;
}
if (revisionClass == null) {
revisionClass = SCMRevision.class;
}
List<SCMHeadAuthorityDescriptor> result = new ArrayList<SCMHeadAuthorityDescriptor>();
for (SCMHeadAuthorityDescriptor d : all()) {
if (d.isApplicableToRequest(requestClass)
&& d.isApplicableToHead(headClass)
&& d.isApplicableToRevision(revisionClass)) {
boolean match = origins.length == 0;
if (!match) {
for (Class<? extends SCMHeadOrigin> o : origins) {
if (d.isApplicableToOrigin(o)) {
match = true;
break;
}
}
}
if (match) {
result.add(d);
}
}
}
return result;
}

}
Expand Up @@ -24,10 +24,12 @@

package jenkins.scm.api.trait;

import edu.umd.cs.findbugs.annotations.NonNull;
import hudson.model.Descriptor;
import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import jenkins.scm.api.SCMHead;
import jenkins.scm.api.SCMHeadOrigin;
import jenkins.scm.api.SCMRevision;
import jenkins.scm.api.mixin.SCMHeadMixin;
import org.jvnet.tiger_types.Types;
Expand Down Expand Up @@ -113,8 +115,8 @@ protected SCMHeadAuthorityDescriptor() {
* @param head the {@link SCMHead}.
* @return {@code true} if applicable.
*/
public boolean isApplicableToHead(SCMHead head) {
return isApplicableToHead(head.getClass());
public boolean isApplicableToHead(@NonNull SCMHead head) {
return isApplicableToHead(head.getClass()) && isApplicableToOrigin(head.getOrigin());
}

/**
Expand All @@ -123,7 +125,7 @@ public boolean isApplicableToHead(SCMHead head) {
* @param headClass the type of {@link SCMHead}.
* @return {@code true} if applicable.
*/
public boolean isApplicableToHead(Class<? extends SCMHead> headClass) {
public boolean isApplicableToHead(@NonNull Class<? extends SCMHeadMixin> headClass) {
return this.headClass.isAssignableFrom(headClass);
}

Expand All @@ -133,7 +135,7 @@ public boolean isApplicableToHead(Class<? extends SCMHead> headClass) {
* @param revision the {@link SCMRevision}.
* @return {@code true} if applicable.
*/
public boolean isApplicableToRevision(SCMRevision revision) {
public boolean isApplicableToRevision(@NonNull SCMRevision revision) {
return isApplicableToHead(revision.getHead()) && isApplicableToRevision(revision.getClass());
}

Expand All @@ -143,7 +145,7 @@ public boolean isApplicableToRevision(SCMRevision revision) {
* @param revisionClass the type of {@link SCMRevision}.
* @return {@code true} if applicable.
*/
public boolean isApplicableToRevision(Class<? extends SCMRevision> revisionClass) {
public boolean isApplicableToRevision(@NonNull Class<? extends SCMRevision> revisionClass) {
return this.revisionClass.isAssignableFrom(revisionClass);
}

Expand All @@ -153,7 +155,7 @@ public boolean isApplicableToRevision(Class<? extends SCMRevision> revisionClass
* @param request the {@link SCMSourceRequest}.
* @return {@code true} if applicable.
*/
public boolean isApplicableToRequest(SCMSourceRequest request) {
public boolean isApplicableToRequest(@NonNull SCMSourceRequest request) {
return requestClass.isInstance(request);
}

Expand All @@ -163,7 +165,27 @@ public boolean isApplicableToRequest(SCMSourceRequest request) {
* @param requestClass the type of {@link SCMSourceRequest}.
* @return {@code true} if applicable.
*/
public boolean isApplicableToRequest(Class<? extends SCMSourceRequest> requestClass) {
public boolean isApplicableToRequest(@NonNull Class<? extends SCMSourceRequest> requestClass) {
return this.requestClass.isAssignableFrom(requestClass);
}

/**
* Checks if this {@link SCMHeadAuthorityDescriptor} is applicable to the supplied {@link SCMHeadOrigin}.
*
* @param origin the {@link SCMHeadOrigin}.
* @return {@code true} if applicable.
*/
public boolean isApplicableToOrigin(@NonNull SCMHeadOrigin origin) {
return isApplicableToOrigin(origin.getClass());
}

/**
* Checks if this {@link SCMHeadAuthorityDescriptor} is applicable to the supplied {@link SCMHeadOrigin}.
*
* @param originClass the type of {@link SCMHeadOrigin}.
* @return {@code true} if applicable.
*/
public boolean isApplicableToOrigin(@NonNull Class<? extends SCMHeadOrigin> originClass) {
return true;
}
}
18 changes: 18 additions & 0 deletions src/main/java/jenkins/scm/api/trait/SCMHeadFilter.java
Expand Up @@ -28,8 +28,26 @@
import java.io.IOException;
import jenkins.scm.api.SCMHead;

/**
* A {@link SCMSourceRequest} dependent filter of {@link SCMHead} instances. Typically these filters may need to
* make remote requests in order to determine exclusion.
* If multiple filters are used, if any exclude then the head is excluded.
*
* @see SCMHeadPrefilter for {@link SCMSourceRequest} independent filters / filters that can perform completely
* off-line.
* @since 3.4.0
*/
public abstract class SCMHeadFilter {

/**
* Checks if the supplied {@link SCMHead} is excluded from the specified {@link SCMSourceRequest}.
*
* @param request the {@link SCMSourceRequest}.
* @param head the {@link SCMHead}.
* @return {@code true} if and only if the {@link SCMHead} is excluded from the request.
* @throws IOException if there was an I/O error when determining exclusion.
* @throws InterruptedException if interrupted while determining exclusion.
*/
public abstract boolean isExcluded(@NonNull SCMSourceRequest request, @NonNull SCMHead head)
throws IOException, InterruptedException;

Expand Down
17 changes: 17 additions & 0 deletions src/main/java/jenkins/scm/api/trait/SCMHeadPrefilter.java
Expand Up @@ -28,8 +28,25 @@
import jenkins.scm.api.SCMHead;
import jenkins.scm.api.SCMSource;

/**
* A {@link SCMSourceRequest} independent filter of {@link SCMHead} instances. These filters may not make remote
* requests in order to determine exclusion.
* If multiple filters are used, if any exclude then the head is excluded.
* The {@link SCMHeadPrefilter} instances are applied before {@link SCMHeadFilter} instances in order to minimize
* remote requests.
*
* @see SCMHeadFilter for {@link SCMSourceRequest} dependent filters / filters that can may require on-line operation.
* @since 3.4.0
*/
public abstract class SCMHeadPrefilter {

/**
* Checks if the supplied {@link SCMHead} is excluded from the specified {@link SCMSource}.
*
* @param source the {@link SCMSource}.
* @param head the {@link SCMHead}.
* @return {@code true} if and only if the {@link SCMHead} is excluded from the request.
*/
public abstract boolean isExcluded(@NonNull SCMSource source, @NonNull SCMHead head);

}
18 changes: 18 additions & 0 deletions src/main/java/jenkins/scm/api/trait/SCMSourceFilter.java
Expand Up @@ -27,8 +27,26 @@
import edu.umd.cs.findbugs.annotations.NonNull;
import java.io.IOException;

/**
* A {@link SCMNavigatorRequest} dependent filter of project names. Typically these filters may need to
* make remote requests in order to determine exclusion.
* If multiple filters are used, if any exclude then the project name is excluded.
*
* @see SCMSourcePrefilter for {@link SCMSourceRequest} independent filters / filters that can perform completely
* off-line.
* @since 3.4.0
*/
public abstract class SCMSourceFilter {

/**
* Checks if the supplied project name is excluded from the specified {@link SCMNavigatorRequest}.
*
* @param request the {@link SCMNavigatorRequest}.
* @param projectName the project name.
* @return {@code true} if and only if the project name is excluded from the request.
* @throws IOException if there was an I/O error when determining exclusion.
* @throws InterruptedException if interrupted while determining exclusion.
*/
public abstract boolean isExcluded(@NonNull SCMNavigatorRequest request, @NonNull String projectName)
throws IOException, InterruptedException;

Expand Down
19 changes: 19 additions & 0 deletions src/main/java/jenkins/scm/api/trait/SCMSourcePrefilter.java
Expand Up @@ -25,10 +25,29 @@
package jenkins.scm.api.trait;

import edu.umd.cs.findbugs.annotations.NonNull;
import jenkins.scm.api.SCMHead;
import jenkins.scm.api.SCMNavigator;

/**
* A {@link SCMNavigatorRequest} independent filter of project names. These filters may not make remote
* requests in order to determine exclusion.
* If multiple filters are used, if any exclude then the project name is excluded.
* The {@link SCMSourcePrefilter} instances are applied before {@link SCMSourceFilter} instances in order to minimize
* remote requests.
*
* @see SCMSourceFilter for {@link SCMNavigatorRequest} dependent filters / filters that can may require on-line
* operation.
* @since 3.4.0
*/
public abstract class SCMSourcePrefilter {

/**
* Checks if the supplied project name is excluded from the specified {@link SCMNavigator}.
*
* @param source the {@link SCMNavigator}.
* @param projectName the project name.
* @return {@code true} if and only if the {@link SCMHead} is excluded from the request.
*/
public abstract boolean isExcluded(@NonNull SCMNavigator source, @NonNull String projectName);

}

0 comments on commit b7c5b5d

Please sign in to comment.