[JENKINS-43507] Documenting SCMNavigatorRequest

jenkinsci · May 3, 2017 · f961638e4b6a30df61739a44d4c9046c247b8f35 · f961638
1 parent 537cf43
commit f961638e4b6a30df61739a44d4c9046c247b8f35
Unified Split

Showing with 96 additions and 19 deletions.

+93 −17 src/main/java/jenkins/scm/api/trait/SCMNavigatorRequest.java

+3 −2 src/test/java/jenkins/scm/impl/mock/MockSCMNavigator.java
diff --git a/src/main/java/jenkins/scm/api/trait/SCMNavigatorRequest.java b/src/main/java/jenkins/scm/api/trait/SCMNavigatorRequest.java
@@ -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}.
     */
@@ -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);
    }
    /**
@@ -139,8 +148,10 @@ protected SCMNavigatorRequest(@NonNull SCMNavigator source, @NonNull SCMNavigato
    @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);
+  
+            }
        }
    }
@@ -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(
@@ -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()) {
@@ -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());
                }
@@ -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);
+  
+
    }
 }
diff --git a/src/test/java/jenkins/scm/impl/mock/MockSCMNavigator.java b/src/test/java/jenkins/scm/impl/mock/MockSCMNavigator.java
@@ -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();