Fixed an issue with pipeline configuration setup, added documentation.

swesteme · swesteme · commit 6506e01c434f · 2023-05-23T23:21:37.000+02:00
diff --git a/README.md b/README.md
@@ -5,38 +5,47 @@
 [![Jenkins Plugin](https://img.shields.io/jenkins/plugin/v/multiselect-parameter.svg)](https://plugins.jenkins.io/multiselect-parameter)
 [![GitHub release](https://img.shields.io/github/release/jenkinsci/multiselect-parameter-plugin.svg?label=changelog)](https://github.com/jenkinsci/multiselect-parameter-plugin/releases/latest)
 [![Jenkins Plugin Installs](https://img.shields.io/jenkins/plugin/i/multiselect-parameter.svg?color=blue)](https://plugins.jenkins.io/multiselect-parameter)
+[![codecov](https://codecov.io/github/swesteme/multiselect-parameter-plugin/branch/main/graph/badge.svg?token=SFXR05LMD4)](https://codecov.io/github/swesteme/multiselect-parameter-plugin)
 
 ## Introduction
 
-The Multiselect parameter plugin is an extension to Jenkins parameterized builds. It allows Jenkins users to 
-create more complex variables consisting of a configurable number of interdependent drop down boxes.
+The Multiselect parameter plugin is an extension to Jenkins parameterized builds. It allows Jenkins users to
+create more complex variables consisting of a configurable number of interdependent drop-down boxes.
 
 ![Example select boxes](images/sample_build.png)
 
 ## Getting started
 
-As soon as the plugin has been installed in Jenkins, freestyle jobs offer a new type of build parameters, 
-named "Multiselect parameter". A simple form allows the configuration of a parameter name, a description
+As soon as the plugin has been installed in Jenkins, parameterized jobs offer a new type of build parameters,
+named "Multiselect parameter".
+
+There are two configuration variants described below: one for *standard* Jenkins jobs, one for the popular *pipelines*,
+which allow for programmatic job configuration.
+
+### "Standard" job configuration
+
+A simple configuration form allows the setup of a parameter name, a description
 and a CSV configuration to use in creation of dependency tree.
 
 There are four different types of rows used to describe the parameter and its values/variables:
 
-* H: header labels for the drop down boxes, one per variable
+* H: header labels for the drop-down boxes, one per variable
 * V: variable names used as environment variables in build process
 * T: titles for the content items in the following row (optional, fallback is the content itself as a label)
 * C: the content items that will be passed in the environment variables upon selection
 
 The rows "H" and "V" only appear once as first and second row. The rows "T" and "C" are repeated.
 
-Note: the "T" rows are optional, but may be useful for more technical content values that need a little bit of extra explanation.
+Note: the "T" rows are optional, but may be useful for more technical content values that need a little bit of extra
+explanation.
 
 ![Example configuration](images/sample_configuration.png)
 
-## Example 
+#### Example
 
 In the following simple example, the "build with parameters" step requests to select a favourite team in
 a number of sports categories and countries.
- 
+
 ```csv
 H,Sport,Team
 V,SELECTED_SPORT,SELECTED_TEAM
@@ -48,7 +57,101 @@ C,Football,FC Rumeln
 C,Wakeboard,WSC Duisburg Rheinhausen
 ```
 
-This will display two drop down boxes. One with the label "Sport", one with the label "Team".
-The first drop down box contains the values "Tennis", "Football" and "Wakeboard", the second will only hold the values "Tennisclub Rumeln-Kaldenhausen e. V." and "Oppumer TC".
-When the first value is switched to "Wakeboard", the second drop down boxes content will change to "WSC Duisburg Rheinhausen".
-As soon as the build is started, the environment variables SELECTED_SPORT and SELECTED_TEAM will contain the selected values.
+This will display two drop-down boxes. One with the label "Sport", one with the label "Team".
+The first drop-down box contains the values "Tennis", "Football" and "Wakeboard", the second will only hold the values "
+Tennisclub Rumeln-Kaldenhausen e. V." and "Oppumer TC".
+When the first value is switched to "Wakeboard", the second drop-down boxes content will change to "WSC Duisburg
+Rheinhausen".
+As soon as the build is started, the environment variables SELECTED_SPORT and SELECTED_TEAM will contain the selected
+values.
+
+### Pipeline job configuration
+
+The same example from above would be configured in a tree-structure, which can be created programmatically and resembles
+the internal structure that would be created from CSV internally.
+
+![Pipeline configuration](images/sample_pipeline_config.png)
+
+The light blue box shows the definition and configuration of the first drop-down box. The purple box shows the
+definition of values for the second drop-down box. Note that this is a simple example with only two combo boxes. It is
+possible to define any number of variable descriptions here, in which case the items in the purple boxes would also
+get "children".
+
+#### Example
+
+The following source code shows the example as complete (very simple) pipeline script.
+
+```groovy
+pipeline {
+    agent any
+    stages {
+        stage('Parameters') {
+            steps {
+                script {
+                    properties([
+                            parameters([
+                                    multiselect(
+                                            decisionTree: [$class              : 'de.westemeyer.plugins.multiselect.MultiselectDecisionTree',
+                                                           variableDescriptions: ([
+                                                                   [$class      : 'de.westemeyer.plugins.multiselect.MultiselectVariableDescriptor',
+                                                                    label       : "Sport",
+                                                                    variableName: "SELECTED_SPORT"
+                                                                   ],
+                                                                   [$class      : 'de.westemeyer.plugins.multiselect.MultiselectVariableDescriptor',
+                                                                    label       : "Team",
+                                                                    variableName: "SELECTED_TEAM"
+                                                                   ]
+                                                           ]),
+                                                           itemList            : ([
+                                                                   [$class  : 'de.westemeyer.plugins.multiselect.MultiselectDecisionItem',
+                                                                    value   : "Tennis",
+                                                                    children: ([
+                                                                            [$class: 'de.westemeyer.plugins.multiselect.MultiselectDecisionItem',
+                                                                             value : "Tennisclub Rumeln-Kaldenhausen e. V."
+                                                                            ],
+                                                                            [$class: 'de.westemeyer.plugins.multiselect.MultiselectDecisionItem',
+                                                                             label : "Alternative label",
+                                                                             value : "Oppumer TC"
+                                                                            ]
+                                                                    ])
+                                                                   ],
+                                                                   [$class  : 'de.westemeyer.plugins.multiselect.MultiselectDecisionItem',
+                                                                    value   : "Football",
+                                                                    children: ([
+                                                                            [$class: 'de.westemeyer.plugins.multiselect.MultiselectDecisionItem',
+                                                                             value : "Rumelner TV"
+                                                                            ],
+                                                                            [$class: 'de.westemeyer.plugins.multiselect.MultiselectDecisionItem',
+                                                                             value : "FC Rumeln"
+                                                                            ]
+                                                                    ])
+                                                                   ],
+                                                                   [$class  : 'de.westemeyer.plugins.multiselect.MultiselectDecisionItem',
+                                                                    value   : "Wakeboard",
+                                                                    children: ([
+                                                                            [$class: 'de.westemeyer.plugins.multiselect.MultiselectDecisionItem',
+                                                                             value : "WSC Duisburg Rheinhausen"
+                                                                            ]
+                                                                    ])
+                                                                   ]
+                                                           ]),
+                                            ],
+                                            description: 'Please select your favourite team!',
+                                            name: 'Favourite team'
+                                    )
+                            ])
+                    ])
+                }
+
+            }
+        }
+
+        stage('Print variables') {
+            steps {
+                sh 'set'
+            }
+        }
+    }
+}
+
+```
diff --git a/images/sample_pipeline_config.png b/images/sample_pipeline_config.png
diff --git a/src/main/java/de/westemeyer/plugins/multiselect/MultiselectDecisionTree.java b/src/main/java/de/westemeyer/plugins/multiselect/MultiselectDecisionTree.java
@@ -2,6 +2,7 @@
 
 import de.westemeyer.plugins.multiselect.parser.ConfigSerialization;
 import edu.umd.cs.findbugs.annotations.NonNull;
+import org.kohsuke.stapler.DataBoundConstructor;
 import org.kohsuke.stapler.DataBoundSetter;
 
 import java.io.ByteArrayInputStream;
@@ -42,6 +43,12 @@ public class MultiselectDecisionTree implements Serializable {
     @NonNull
     private List<MultiselectVariableDescriptor> variableDescriptions = new ArrayList<>();
 
+    @DataBoundConstructor
+    public MultiselectDecisionTree() {
+        // empty constructor is necessary, otherwise pipelines can not create
+        // structured configuration (using setter methods)
+    }
+
     /**
      * Get initial values for column when first displaying list of select boxes in "build with parameters" view.
      * @param column column number
diff --git a/src/main/java/de/westemeyer/plugins/multiselect/MultiselectVariableDescriptor.java b/src/main/java/de/westemeyer/plugins/multiselect/MultiselectVariableDescriptor.java
@@ -30,9 +30,9 @@ public class MultiselectVariableDescriptor implements Serializable {
 
     /**
      * Create new variable description object.
-     * @param label variable label
+     * @param label        variable label
      * @param variableName variable name
-     * @param columnIndex index of this column
+     * @param columnIndex  index of this column
      */
     @DataBoundConstructor
     public MultiselectVariableDescriptor(String label, String variableName, int columnIndex) {
diff --git a/src/main/java/de/westemeyer/plugins/multiselect/parser/CsvParser.java b/src/main/java/de/westemeyer/plugins/multiselect/parser/CsvParser.java
@@ -42,7 +42,7 @@ public MultiselectDecisionTree analyzeConfiguration(InputStream config) {
         InputStreamReader reader = new InputStreamReader(config, StandardCharsets.UTF_8);
 
         // create a new csv reader object
-        try (CSVReader csvReader = new CSVReaderBuilder(reader).build()) {
+        try (CSVReader csvReader = createCsvReader(reader)) {
 
             // references for different kinds of rows
             List<String> headers = null;
@@ -137,11 +137,15 @@ public MultiselectDecisionTree analyzeConfiguration(InputStream config) {
         return decisionTree;
     }
 
+    protected CSVReader createCsvReader(InputStreamReader reader) {
+        return new CSVReaderBuilder(reader).build();
+    }
+
     /**
      * Validate the lists of variable names and values. List of values may not be longer than the list of variable names.
      * @param variableNames list of variable names
-     * @param index current column number
-     * @param subList list of values
+     * @param index         current column number
+     * @param subList       list of values
      */
     private void ensureMatchingListLengths(List<String> variableNames, int index, List<String> subList) {
         if (variableNames != null && subList.size() > variableNames.size()) {
diff --git a/src/main/java/de/westemeyer/plugins/multiselect/parser/CvwWriterVisitor.java b/src/main/java/de/westemeyer/plugins/multiselect/parser/CvwWriterVisitor.java
@@ -82,10 +82,7 @@ private void reverseAndWrite(String type, List<String> values) {
      * @return whether appended value was not null or empty
      */
     boolean appendValue(List<String> columns, String value) {
-        if (value != null) {
-            columns.add(value);
-            return !value.isEmpty();
-        }
-        return false;
+        columns.add(value);
+        return !(value == null || value.isEmpty());
     }
 }
diff --git a/src/test/java/de/westemeyer/plugins/multiselect/MultiselectDecisionTreeTest.java b/src/test/java/de/westemeyer/plugins/multiselect/MultiselectDecisionTreeTest.java
@@ -1,12 +1,14 @@
 package de.westemeyer.plugins.multiselect;
 
 import de.westemeyer.plugins.multiselect.parser.ConfigSerialization;
+import de.westemeyer.plugins.multiselect.parser.CsvWriter;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.CsvSource;
 
+import java.io.ByteArrayOutputStream;
 import java.io.OutputStream;
 import java.util.Arrays;
 import java.util.Collections;
@@ -96,4 +98,47 @@ public List<MultiselectDecisionItem> getItemList() {
 
         Assertions.assertEquals(0, decisionTree.getInitialValuesForColumn(0).size());
     }
+
+    @Test
+    void serializationRoundTripTest() throws Exception {
+        MultiselectDecisionTree decisionTree = new MultiselectDecisionTree();
+        decisionTree.setVariableDescriptions(Arrays.asList(createDescriptor("Sport", "SELECTED_SPORT"), createDescriptor("Team", "SELECTED_TEAM")));
+        decisionTree.setItemList(Arrays.asList(
+                createItem(null, "Tennis", createItem(null, "Tennisclub Rumeln-Kaldenhausen e.V."), createItem("Alternative label", "Oppumer TC")),
+                createItem(null, "Football", createItem(null, "Rumelner TV"), createItem(null, "FC Rumeln")),
+                createItem("Very popular sport", "Wakeboard", createItem(null, "WSC Duisburg Rheinhausen"))));
+        try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
+            decisionTree.serialize(new CsvWriter(), outputStream);
+            Assertions.assertEquals("H,Sport,Team\n" +
+                    "V,SELECTED_SPORT,SELECTED_TEAM\n" +
+                    "C,Tennis,Tennisclub Rumeln-Kaldenhausen e.V.\n" +
+                    "T,,Alternative label\n" +
+                    "C,Tennis,Oppumer TC\n" +
+                    "C,Football,Rumelner TV\n" +
+                    "C,Football,FC Rumeln\n" +
+                    "T,Very popular sport,\n" +
+                    "C,Wakeboard,WSC Duisburg Rheinhausen\n", outputStream.toString());
+        }
+    }
+
+    private MultiselectDecisionItem createItem(String label, String value, MultiselectDecisionItem... children) {
+        MultiselectDecisionItem item = new MultiselectDecisionItem(null, null, null);
+        if (label != null) {
+            item.setLabel(label);
+        }
+        if (value != null) {
+            item.setValue(value);
+        }
+        if (children != null) {
+            item.setChildren(Arrays.asList(children));
+        }
+        return item;
+    }
+
+    private MultiselectVariableDescriptor createDescriptor(String label, String variable) {
+        MultiselectVariableDescriptor descriptor = new MultiselectVariableDescriptor(null, null, 0);
+        descriptor.setLabel(label);
+        descriptor.setVariableName(variable);
+        return descriptor;
+    }
 }
diff --git a/src/test/java/de/westemeyer/plugins/multiselect/parser/CsvParserTest.java b/src/test/java/de/westemeyer/plugins/multiselect/parser/CsvParserTest.java
@@ -1,12 +1,17 @@
 package de.westemeyer.plugins.multiselect.parser;
 
+import com.opencsv.CSVReader;
 import de.westemeyer.plugins.multiselect.MultiselectDecisionTree;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
 
+import java.io.BufferedReader;
+import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStreamReader;
 
 class CsvParserTest {
     /** First input csv for tests. */
@@ -17,10 +22,10 @@ class CsvParserTest {
 
     /** Input from issue JENKINS-66486. */
     private static final String INPUT_QUOTED = "H,Component,Container,Machine\n"
-                                               + "V,SELECTED_COMPONENT,SELECTED_CONTAINER,MACHINES\n"
-                                               + "C,component1,container1,\"machine1,machine2\"\n"
-                                               + "C,component2,container1,\"machine3,machine4\"\n"
-                                               + "C,component3,container2,\"machine1,machine2\"\n";
+            + "V,SELECTED_COMPONENT,SELECTED_CONTAINER,MACHINES\n"
+            + "C,component1,container1,\"machine1,machine2\"\n"
+            + "C,component2,container1,\"machine3,machine4\"\n"
+            + "C,component3,container2,\"machine1,machine2\"\n";
 
     @ParameterizedTest
     @ValueSource(strings = {INPUT_CSV, INPUT_NO_TITLES, "", "V,A,B\n", "H,Hello,World\n", "C,a,b\n", INPUT_QUOTED})
@@ -46,6 +51,24 @@ void invalidColumnCount() throws Exception {
         Assertions.assertTrue(decisionTree.getVariableLabels().isEmpty());
     }
 
+    @Test
+    void testException() throws IOException {
+        try (ByteArrayInputStream inputStream = new ByteArrayInputStream("".getBytes())) {
+            CsvParser csvParser = new CsvParser() {
+                @Override
+                protected CSVReader createCsvReader(InputStreamReader reader) {
+                    return new CSVReader(new BufferedReader(new InputStreamReader(inputStream))) {
+                        @Override
+                        public void close() throws IOException {
+                            throw new IOException("Ooops, I might get caught!");
+                        }
+                    };
+                }
+            };
+            Assertions.assertDoesNotThrow(() -> csvParser.analyzeConfiguration(inputStream));
+        }
+    }
+
     private MultiselectDecisionTree getDecisionTree(String input, boolean assertEquality) throws Exception {
         // parse input stream to tree meta object
         MultiselectDecisionTree decisionTree = MultiselectDecisionTree.parse(input);
diff --git a/src/test/java/de/westemeyer/plugins/multiselect/parser/CvwWriterVisitorTest.java b/src/test/java/de/westemeyer/plugins/multiselect/parser/CvwWriterVisitorTest.java
@@ -19,6 +19,6 @@ void appendValue() {
         assertTrue(cvwWriterVisitor.appendValue(result, "Hello"));
         assertEquals(2, result.size());
         assertFalse(cvwWriterVisitor.appendValue(result, null));
-        assertEquals(2, result.size());
+        assertEquals(3, result.size());
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -82,10 +82,7 @@ private void reverseAndWrite(String type, List<String> values) {`
`82`	`82`	`* @return whether appended value was not null or empty`
`83`	`83`	`*/`
`84`	`84`	`boolean appendValue(List<String> columns, String value) {`
`85`		`- if (value != null) {`
`86`		`- columns.add(value);`
`87`		`- return !value.isEmpty();`
`88`		`- }`
`89`		`- return false;`
	`85`	`+ columns.add(value);`
	`86`	`+ return !(value == null \|\| value.isEmpty());`
`90`	`87`	`}`
`91`	`88`	`}`
Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,6 @@ void appendValue() {`
`19`	`19`	`assertTrue(cvwWriterVisitor.appendValue(result, "Hello"));`
`20`	`20`	`assertEquals(2, result.size());`
`21`	`21`	`assertFalse(cvwWriterVisitor.appendValue(result, null));`
`22`		`- assertEquals(2, result.size());`
	`22`	`+ assertEquals(3, result.size());`
`23`	`23`	`}`
`24`	`24`	`}`