Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[JENKINS-43507] Documenting SCMNavigatorRequest
  • Loading branch information
stephenc committed May 4, 2017
1 parent 537cf43 commit f961638
Show file tree
Hide file tree
Showing 2 changed files with 96 additions and 19 deletions.
110 changes: 93 additions & 17 deletions src/main/java/jenkins/scm/api/trait/SCMNavigatorRequest.java
Expand Up @@ -49,7 +49,6 @@
*/
public abstract class SCMNavigatorRequest implements Closeable {

private static final Witness[] NO_WITNESSES = new Witness[0];
/**
* The {@link SCMNavigator} to use when applying the {@link #prefilters}.
*/
Expand Down Expand Up @@ -119,14 +118,24 @@ protected SCMNavigatorRequest(@NonNull SCMNavigator source, @NonNull SCMNavigato
this.decorators = new ArrayList<SCMSourceDecorator<?, ?>>(context.decorators());
}

/**
* Returns the {@link SCMSourceTrait} instances to apply to every {@link SCMSource}.
*
* @return the {@link SCMSourceTrait} instances to apply to every {@link SCMSource}.
*/
@NonNull
public final List<SCMSourceTrait> traits() {
return traits;
return Collections.unmodifiableList(traits);
}

/**
* Returns the {@link SCMSourceDecorator} instances to apply to {@link SCMSource} instances.
*
* @return the {@link SCMSourceDecorator} instances to apply to {@link SCMSource} instances.
*/
@NonNull
public final List<SCMSourceDecorator<?, ?>> decorators() {
return decorators;
return Collections.unmodifiableList(decorators);
}

/**
Expand All @@ -139,8 +148,10 @@ public final List<SCMSourceTrait> traits() {
@SuppressWarnings("unchecked")
private static void record(@NonNull String projectName, boolean isMatch,
@NonNull Witness... witnesses) {
for (Witness witness : witnesses) {
witness.record(projectName, isMatch);
if (witnesses.length > 0) {
for (Witness witness : witnesses) {
witness.record(projectName, isMatch);
}
}
}

Expand Down Expand Up @@ -174,8 +185,22 @@ public final boolean isExcluded(@NonNull String projectName) throws IOException,
return false;
}

public boolean process(@NonNull String projectName, @NonNull SourceFactory sourceFactory,
@CheckForNull AttributeFactory attributeFactory,
/**
* Processes a named project in the scope of the current request.
*
* @param projectName the name of the project.
* @param sourceFactory the factory for instantiating a {@link SCMSource}.
* @param attributeFactory (optional) factory for instantiating the attribute map.
* @param witnesses the witnesses to record the processing result.
* @return {@code true} if and only if the request is completed, {@code false} if the request can process
* additional named projects.
* @throws IllegalArgumentException if the attribute factory provides attribute names that are unrecognized, or
* repeats already added attribues.
* @throws IOException if there is an I/O error.
* @throws InterruptedException if the operation was interrupted.
*/
public boolean process(@NonNull String projectName, @NonNull SourceLambda sourceFactory,
@CheckForNull AttributeLambda attributeFactory,
Witness... witnesses)
throws IllegalArgumentException, IOException, InterruptedException {
return process(
Expand All @@ -186,8 +211,22 @@ public boolean process(@NonNull String projectName, @NonNull SourceFactory sourc
);
}

public boolean process(@NonNull String projectName, @NonNull List<SourceFactory> sourceFactories,
@CheckForNull List<AttributeFactory> attributeFactories,
/**
* Processes a named project in the scope of the current request.
*
* @param projectName the name of the project.
* @param sourceFactories the factories for instantiating the {@link SCMSource} instances.
* @param attributeFactories (optional) factories for instantiating the attribute maps.
* @param witnesses the witnesses to record the processing result.
* @return {@code true} if and only if the request is completed, {@code false} if the request can process
* additional named projects.
* @throws IllegalArgumentException if an attribute factory provides attribute names that are unrecognized, or
* repeats already added attribues.
* @throws IOException if there is an I/O error.
* @throws InterruptedException if the operation was interrupted.
*/
public boolean process(@NonNull String projectName, @NonNull List<SourceLambda> sourceFactories,
@CheckForNull List<AttributeLambda> attributeFactories,
Witness... witnesses)
throws IllegalArgumentException, IOException, InterruptedException {
if (Thread.interrupted()) {
Expand All @@ -204,11 +243,11 @@ public boolean process(@NonNull String projectName, @NonNull List<SourceFactory>
// we know this is safe to break contract with
return !observer.isObserving();
}
for (SourceFactory s: sourceFactories) {
for (SourceLambda s : sourceFactories) {
po.addSource(s.create(projectName));
}
if (attributeFactories != null) {
for (AttributeFactory attributeFactory: attributeFactories) {
for (AttributeLambda attributeFactory : attributeFactories) {
for (Map.Entry<String, Object> entry : attributeFactory.create(projectName).entrySet()) {
po.addAttribute(entry.getKey(), entry.getValue());
}
Expand Down Expand Up @@ -261,15 +300,52 @@ public void close() throws IOException {
}
}

public interface Witness {
void record(@NonNull String projectName, boolean isMatch);
/**
* A lambda that will create the {@link SCMSource} instance for a specific project name.
*/
public interface SourceLambda {
/**
* Creates the {@link SCMSource} for the named project.
*
* @param projectName the named project.
* @return the {@link SCMSource} instance.
* @throws IOException if there is an I/O error.
* @throws InterruptedException if the operation was interrupted.
*/
@NonNull
SCMSource create(@NonNull String projectName) throws IOException, InterruptedException;
}

public interface SourceFactory {
SCMSource create(String projectName);
/**
* A lambda that will create the map of attributes for a specific project name.
*/
public interface AttributeLambda {
/**
* Creates the attributes map for the named project.
*
* @param projectName the named project.
* @return the attributes map.
* @throws IOException if there is an I/O error.
* @throws InterruptedException if the operation was interrupted.
*/
@NonNull
Map<String, Object> create(@NonNull String projectName) throws IOException, InterruptedException;
}

public interface AttributeFactory {
Map<String,Object> create(String projectName);
/**
* Callback lambda to track the results of
* {@link #process(String, SourceLambda, AttributeLambda, Witness...)} or
* {@link #process(String, List, List, Witness...)}
*/
public interface Witness {

/**
* Records the result of the named project.
*
* @param projectName the project name.
* @param isMatch {@code true} if the project matched.
*/
void record(@NonNull String projectName, boolean isMatch);

}
}
5 changes: 3 additions & 2 deletions src/test/java/jenkins/scm/impl/mock/MockSCMNavigator.java
Expand Up @@ -109,9 +109,10 @@ public void visitSources(@NonNull SCMSourceObserver observer) throws IOException
if (!request.isExcluded(name)) { // hack to allow the latency and faults to work
controller().applyLatency();
controller().checkFaults(name, null, null, false);
if (request.process(name, new SCMNavigatorRequest.SourceFactory() {
if (request.process(name, new SCMNavigatorRequest.SourceLambda() {
@NonNull
@Override
public SCMSource create(String name) {
public SCMSource create(@NonNull String name) {
return new MockSCMSourceBuilder(getId() + "::" + name, controller, name)
.withRequest(request)
.build();
Expand Down

0 comments on commit f961638

Please sign in to comment.