From 056f128568a147756838ac18bc47c71be3480b3e Mon Sep 17 00:00:00 2001 From: Marcus Holl Date: Tue, 6 Mar 2018 09:59:58 +0100 Subject: [PATCH] Introduce piper API --- README.md | 6 + .../docs/scripts/configurationLoader.md | 155 ------------------ .../docs/scripts/configurationMerger.md | 123 -------------- documentation/docs/scripts/fileUtils.md | 64 -------- documentation/docs/scripts/jsonUtils.md | 30 ---- documentation/docs/scripts/utils.md | 67 -------- documentation/docs/scripts/version.md | 147 ----------------- documentation/mkdocs.yml | 7 - 8 files changed, 6 insertions(+), 593 deletions(-) delete mode 100644 documentation/docs/scripts/configurationLoader.md delete mode 100644 documentation/docs/scripts/configurationMerger.md delete mode 100644 documentation/docs/scripts/fileUtils.md delete mode 100644 documentation/docs/scripts/jsonUtils.md delete mode 100644 documentation/docs/scripts/utils.md delete mode 100644 documentation/docs/scripts/version.md diff --git a/README.md b/README.md index 044868b4c..6dac02487 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,12 @@ Custom library steps can be added using a custom library according to the groovy coding to the `Jenkinsfile`. Your custom library can coexist next to the provided pipeline library. +## API + +All steps are intended to be used by Pipelines. All the classes / groovy-scripts +contained in the `src` folder are not part of the API and are subjected to change +without prior notice. + # Requirements * Java Runtime Environment 8 diff --git a/documentation/docs/scripts/configurationLoader.md b/documentation/docs/scripts/configurationLoader.md deleted file mode 100644 index 459fc3df8..000000000 --- a/documentation/docs/scripts/configurationLoader.md +++ /dev/null @@ -1,155 +0,0 @@ -# ConfigurationLoader - -## Description -Loads configuration values from the global configuration. -The global configuration is stored in the commonPipelineEnvironment and should be loaded before by calling setupCommonPipelineEnvironment. - -## Static Method Details - -### stepConfiguration - -#### Description - -Returns the configuration for a specific step as map. - -#### Parameters - -* `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the `this` parameter, as in `script: this`. This allows the function to access the [`commonPipelineEnvironment`][commonPipelineEnvironment] for retrieving, for example, configuration parameters. -* `stepName` - The name of the step - -#### Side effects - -none - -#### Example - -In your `config.yml` you define the following: - -``` -#Steps Specific Configuration -steps: - mavenExecute: - dockerImage: 'maven:3.5-jdk-7' -``` - -To get the map containing the key `dockerImage` and the value `maven:3.5-jdk-7` you have to execute the following: - -```groovy -Map configuration = ConfigurationLoader.stepConfiguration(script, 'mavenExecute') -``` - -### defaultStepConfiguration - -#### Description - -Returns the default configuration for a specific step as map. - -#### Parameters - -* `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the `this` parameter, as in `script: this`. This allows the function to access the [`commonPipelineEnvironment`][commonPipelineEnvironment] for retrieving, for example, configuration parameters. -* `stepName` - The name of the step - -#### Side effects - -none - -#### Example - -To get the map of the default values defined in the file `resources/default_pipeline_environment.yml` you have to execute the following: - -```groovy -Map configuration = ConfigurationLoader.defaultStepConfiguration(script, 'mavenExecute') -``` -### generalConfiguration - -#### Description - -Returns the configuration in the section general of the configuration file. - -#### Parameters - -* `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the `this` parameter, as in `script: this`. This allows the function to access the [`commonPipelineEnvironment`][commonPipelineEnvironment] for retrieving, for example, configuration parameters. - -#### Side effects - -none - -#### Example - -In your `config.yml` you define the following: - -``` -#Project Setup -general: - productiveBranch: 'master' -``` - -To get the map containing the key `productiveBranch` and the value `master` you have to execute the following: - -```groovy -Map configuration = ConfigurationLoader.generalConfiguration(script) -``` - -### defaultGeneralConfiguration - -#### Description - -Returns the default configuration in the section general of the default configuration file. - -#### Parameters - -* `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the `this` parameter, as in `script: this`. This allows the function to access the [`commonPipelineEnvironment`][commonPipelineEnvironment] for retrieving, for example, configuration parameters. - -#### Side effects - -none - -#### Example - -To get the map of the default values defined in the file `resources/default_pipeline_environment.yml` you have to execute the following: - -```groovy -Map configuration = ConfigurationLoader.defaultGeneralConfiguration(script) -``` - -### stageConfiguration - -#### Description - -Returns the configuration for a specific stage as map. -This is useful if you decide to have a central pipeline and want to give all your projects the possibility to configure the stages in the central pipeline. -Thus, the central pipeline can define how to deploy and read the configuration. -In the their configuration files, all the projects can configure the location where to deploy. - -#### Parameters - -* `script` - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the `this` parameter, as in `script: this`. This allows the function to access the [`commonPipelineEnvironment`][commonPipelineEnvironment] for retrieving, for example, configuration parameters. -* `script` - Name of the stage as defined in the configuration file. - -#### Side effects - -none - -#### Example - -In your `config.yml` you define the following: - -``` -#Project Setup -#Stage Specific Configurations -stages: - productionDeployment: - targets: - - apiEndpoint: 'https://api.cf.sap.hana.ondemand.com' - org: 'myOrg' - manifest: 'manifest.yml' - appName: 'my-app' -``` - -To get the map containing the key `targets` and the list of the deployment locations. - -```groovy -Map configuration = ConfigurationLoader.stageConfiguration(script, 'productionDeployment') -``` - -[commonPipelineEnvironment]: /steps/commonPipelineEnvironment.md \ No newline at end of file diff --git a/documentation/docs/scripts/configurationMerger.md b/documentation/docs/scripts/configurationMerger.md deleted file mode 100644 index 8f2d708cb..000000000 --- a/documentation/docs/scripts/configurationMerger.md +++ /dev/null @@ -1,123 +0,0 @@ -# ConfigurationMerger - -## Description -A helper script that can merge the configurations from multiple sources. - -## Static Method Details - -### merge - -#### Description - -A step is usually configured by default values, configuration values from the configuration file and the parameters. -The method can merge these sources. -Default values are overwritten by configuration file values. -These are overwritten by parameters. - -#### Parameters - -| parameter | mandatory | Class | -| -------------------|-----------|-----------------------------------| -| `parameters` | yes | Map | -| `parameterKeys` | yes | List | -| `configurationMap` | yes | Map | -| `configurationKeys`| yes | List | -| `defaults` | yes | Map | - -* `parameters` Parameters map given to the step -* `parameterKeys` List of parameter names (keys) that should be considered while merging. -* `configurationMap` Configuration map loaded from the configuration file. -* `configurationKeys` List of configuration keys that should be considered while merging. -* `defaults` Map of default values, e.g. loaded from the default value configuration file. - -#### Side effects - -none - -#### Example - -```groovy -prepareDefaultValues script: script -final Map stepDefaults = ConfigurationLoader.defaultStepConfiguration(script, 'mavenExecute') - -final Map stepConfiguration = ConfigurationLoader.stepConfiguration(script, 'mavenExecute') - -List parameterKeys = [ - 'dockerImage', - 'globalSettingsFile', - 'projectSettingsFile', - 'pomPath', - 'flags', - 'goals', - 'm2Path', - 'defines' -] -List stepConfigurationKeys = [ - 'dockerImage', - 'globalSettingsFile', - 'projectSettingsFile', - 'pomPath', - 'm2Path' -] - -Map configuration = ConfigurationMerger.merge(parameters, parameterKeys, stepConfiguration, stepConfigurationKeys, stepDefaults) -``` - -### mergeWithPipelineData - -#### Description - -A step is usually configured by default values, configuration values from the configuration file and the parameters. -In certain cases also information previously generated in the pipeline should be mixed in, like for example an artifactVersion created earlier. -The method can merge these sources. -Default values are overwritten by configuration file values. -Those are overwritten by information previously generated in the pipeline (e.g. stored in [commonPipelineEnvironment](../steps/commonPipelineEnvironment.md)). -These are overwritten by parameters passed directly to the step. - -#### Parameters - -| parameter | mandatory | Class | -| -------------------|-----------|-----------------------------------| -| `parameters` | yes | Map | -| `parameterKeys` | yes | List | -| `pipelineDataMap` | yes | Map | -| `configurationMap` | yes | Map | -| `configurationKeys`| yes | List | -| `defaults` | yes | Map | - -* `parameters` Parameters map given to the step -* `parameterKeys` List of parameter names (keys) that should be considered while merging. -* `configurationMap` Configuration map loaded from the configuration file. -* `pipelineDataMap` Values available to the step during pipeline run. -* `configurationKeys` List of configuration keys that should be considered while merging. -* `defaults` Map of default values, e.g. loaded from the default value configuration file. - -#### Side effects - -none - -#### Example - -```groovy -def stepName = 'influxWriteData' -prepareDefaultValues script: script - -final Map stepDefaults = ConfigurationLoader.defaultStepConfiguration(script, stepName) -final Map stepConfiguration = ConfigurationLoader.stepConfiguration(script, stepName) -final Map generalConfiguration = ConfigurationLoader.generalConfiguration(script) - -List parameterKeys = [ - 'artifactVersion', - 'influxServer', - 'influxPrefix' -] -Map pipelineDataMap = [ - artifactVersion: commonPipelineEnvironment.getArtifactVersion() -] -List stepConfigurationKeys = [ - 'influxServer', - 'influxPrefix' -] - -Map configuration = ConfigurationMerger.mergeWithPipelineData(parameters, parameterKeys, pipelineDataMap, stepConfiguration, stepConfigurationKeys, stepDefaults) -``` diff --git a/documentation/docs/scripts/fileUtils.md b/documentation/docs/scripts/fileUtils.md deleted file mode 100644 index 9b76c2048..000000000 --- a/documentation/docs/scripts/fileUtils.md +++ /dev/null @@ -1,64 +0,0 @@ -# FileUtils - -## Description -Provides file system related utility functions. - -## Constructor -Since there are only static utility methods there is no need for instantiating objects. - - -## Method Details - -### validateDirectory(dir) - -#### Description -Checks whether a file exists and is a directory. - -#### Parameters -* `dir` - The directory to be checked. In case it is relative path it is checked against the -current working directory. In case of doubt use the absolute path (prefix the directory with `pwd`). - -#### Return value -none - -#### Side effects -none - -#### Exceptions -* `IllegalArgumentException`: - * If the parameter `dir` is null or empty. -* `AbortException`: - * If the directory does not exist or is not a directory. - -#### Example -```groovy -FileUtils.validateDirectory('/path/to/dir') -``` - - -### validateDirectoryIsNotEmpty(dir) - -#### Description -Check whether a directory is not empty. Before the directory is checked, `validateDirectory(dir)` is executed. - -#### Parameters -* `dir` - The directory to be checked. In case it is relative path it is checked against the -current working directory. In case of doubt use the absolute path (prefix the directory with `pwd`). - -#### Return value -none - -#### Side effects -none - -#### Exceptions -* `IllegalArgumentException`: - * If the parameter `dir` is null or empty. -* `AbortException`: - * If the directory does not exist or is not a directory or the directory is empty. - -#### Example -```groovy -FileUtils.validateDirectoryIsNotEmpty('/path/to/dir') -``` - diff --git a/documentation/docs/scripts/jsonUtils.md b/documentation/docs/scripts/jsonUtils.md deleted file mode 100644 index f414fa0b9..000000000 --- a/documentation/docs/scripts/jsonUtils.md +++ /dev/null @@ -1,30 +0,0 @@ -# JsonUtils - -## Description -Provides json related utility functions. - -## Constructors - -### JsonUtils() -Default no-argument constructor. Instances of the Utils class does not hold any instance specific state. - -#### Example -```groovy -new JsonUtils() -``` - -## Method Details - -### getPrettyJsonString(object) - -#### Description -Creates a pretty-printed json string. - -#### Parameters -* `object` - A object (e.g. Map or List). - -#### Return value -A pretty printed `String`. - -#### Side effects -none diff --git a/documentation/docs/scripts/utils.md b/documentation/docs/scripts/utils.md deleted file mode 100644 index 5b69bae95..000000000 --- a/documentation/docs/scripts/utils.md +++ /dev/null @@ -1,67 +0,0 @@ -# Utils - -## Description -Provides utility functions. - -## Constructors - -### Utils() -Default no-argument constructor. Instances of the Utils class does not hold any instance specific state. - -#### Example -```groovy -new Utils() -``` - - -## Method Details - -### getMandatoryParameter(map, paramName, defaultValue) - -#### Description -Retrieves the parameter value for parameter `paramName` from parameter map `map`. In case there is no parameter with the given key contained in parameter map `map` `defaultValue` is returned. In case there no such parameter contained in `map` and `defaultValue` is `null` an exception is thrown. - -#### Parameters -* `map` - A map containing configuration parameters. -* `paramName` - The key of the parameter which should be looked up. -* optional: `defaultValue` - The value which is returned in case there is no parameter with key `paramName` contained in `map`. If it is not provided the default is `null`. - -#### Return value -The value to the parameter to be retrieved, or the default value if the former is `null`, either since there is no such key or the key is associated with value `null`. In case the parameter is not defined or the value for that parameter is `null`and there is no default value an exception is thrown. - -#### Side effects -none - -#### Exceptions -* `Exception`: - * If the value to be retrieved and the default value are both `null`. - -#### Example -```groovy -def utils = new Utils() -def parameters = [DEPLOY_ACCOUNT: 'deploy-account'] -assert utils.getMandatoryParameter(parameters, 'DEPLOY_ACCOUNT', null) == 'deploy-account' -assert utils.getMandatoryParameter(parameters, 'DEPLOY_USER', 'john_doe') == 'john_doe' -``` - -### retrieveGitCoordinates(script) - -#### Description -Retrieves the git-remote-url and git-branch. The parameters 'GIT_URL' and 'GIT_BRANCH' are retrieved from Jenkins job configuration. If these are not set, the git-url and git-branch are retrieved from the same repository where the Jenkinsfile resides. - -#### Parameters -* `script` - The script calling the method. Basically the `Jenkinsfile`. It is assumed that the script provides access to the parameters defined when launching the build, especially `GIT_URL` and `GIT_BRANCH`. - -#### Return value -A map containing git-url and git-branch: `[url: gitUrl, branch: gitBranch]` - -## Exceptions -* `AbortException`: - * If only one of `GIT_URL`, `GIT_BRANCH` is set in the Jenkins job configuration. - -#### Example -```groovy -def gitCoordinates = new Utils().retrieveGitCoordinates(this) -def gitUrl = gitCoordinates.url -def gitBranch = gitCoordinates.branch -``` diff --git a/documentation/docs/scripts/version.md b/documentation/docs/scripts/version.md deleted file mode 100644 index 9d0639c06..000000000 --- a/documentation/docs/scripts/version.md +++ /dev/null @@ -1,147 +0,0 @@ -# Version - -## Description -Handles version numbers. - - -## Constructors - -### Version(major, minor, patch) - -#### Parameters -| parameter | mandatory | default | possible values | -| ----------|-----------|---------|-----------------| -| major | yes | | | -| minor | yes | | | -| patch | no | `-1` | | - -* `major` - The major version number. -* `minor` - The minor version number. -* `patch` - The patch version number. - -#### Exceptions -* `IllegalArgumentException`: - * If the `major` or `minor` version number is less than `0`. - -#### Example -```groovy -def toolVersion = new Version(1, 2, 3) -``` - - -### Version(text) - -#### Parameters -| parameter | mandatory | default | possible values | -| ----------|-----------|---------|-----------------| -| text | yes | | | - -* `text` - As an alternative to calling the constructor with `major`, `minor`, and `patch` version numbers, you can pass this as a String of format 'major.minor.patch'. - -#### Exceptions -* `IllegalArgumentException`: - * If the `text` parameter is `null` or empty. -* `AbortException`: - * If the version `text` has an unexpected format. - -#### Example -```groovy -def toolVersion = new Version('1.2.3') -``` - - -## Method Details - -### equals(version) - -#### Description -Indicates whether some other version instance is equal to this one. The two versions are considered equal when they have the same `major`, `minor` and `patch` version number. - -#### Parameters -* `version` - The Version instance to compare to this Version instance. - -#### Return value -`true` if `major`, `minor` and `patch` version numbers are equal to each other. Otherwise `false`. - -#### Side effects -none - -#### Exceptions -* `AbortException`: - * If the parameter `version` is `null`. - -#### Example -```groovy -assert new Version('1.2.3').equals(new Version('1.2.3')) -``` - - -### isCompatibleVersion(version) - -#### Description -Checks whether a version is compatible. Two versions are compatible if the major version number is the same, while the minor and patch version number are the same or higher. - -#### Parameters -* `version` - The Version instance to compare to this Version instance. - -#### Return value -`true` if this Version instance is compatible to the other Version instance. Otherwise `false`. - -#### Side effects -none - -#### Exceptions -* `AbortException`: - * If the parameter `version` is `null`. - -#### Example -```groovy -assert new Version('1.2.3').isCompatibleVersion(new Version('1.3.1')) -``` - - -### isHigher(version) - -#### Description -Checks whether this Version instance is higher than the other Version instance. - -#### Parameters -* `version` - The Version instance to compare to this Version instance. - -#### Return value -`true` if this Version instance is higher than the other Version instance. Otherwise `false`. - -#### Side effects -none - -#### Exceptions -* `AbortException`: - * If the parameter `version` is `null`. - -#### Example -```groovy -assert new Version('1.2.3').isHigher(new Version('1.1.6')) -``` - - -### toString() - -#### Description -Print the version number in format '..'. If no patch version number exists the format is '.'. - -#### Parameters -none - -#### Return value -A String consisting of `major`, `minor` and if available `patch`, separated by dots. - -#### Side effects -none - -#### Exceptions -none - -#### Example -```groovy -assert "${new Version('1.2.3')}" == "1.2.3" -``` diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index ccd7d3f99..43e3ca87c 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -15,13 +15,6 @@ pages: - prepareDefaultValues: steps/prepareDefaultValues.md - setupCommonPipelineEnvironment: steps/setupCommonPipelineEnvironment.md - toolValidate: steps/toolValidate.md - - 'Library scripts': - - FileUtils: scripts/fileUtils.md - - JsonUtils: scripts/jsonUtils.md - - Utils: scripts/utils.md - - Version: scripts/version.md - - ConfigurationLoader: scripts/configurationLoader.md - - ConfigurationMerger: scripts/configurationMerger.md - 'Required Plugins': jenkins/requiredPlugins.md theme: