jenkins/sap-jenkins-library
1
0
Fork 0
mirror of https://github.com/SAP/jenkins-library.git synced 2025-01-30 05:59:39 +02:00
Code Issues Releases Activity

Merge pull request #116 from marcusholl/pr/introducePiperApi

Browse Source 
introduce piper api
This commit is contained in:
Marcus Holl 2018-03-19 09:27:04 +01:00 committed by GitHub
commit 143f9fb389
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 6 additions and 593 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@ -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

155
documentation/docs/scripts/configurationLoader.md
View File

@ -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

123
documentation/docs/scripts/configurationMerger.md
View File

@ -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)
```

64
documentation/docs/scripts/fileUtils.md
View File

@ -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')
```

30
documentation/docs/scripts/jsonUtils.md
View File

@ -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

67
documentation/docs/scripts/utils.md
View File

@ -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
```

147
documentation/docs/scripts/version.md
View File

@ -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 '<major>.<minor>.<patch>'. If no patch version number exists the format is '<major>.<minor>'.
#### 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"
```

7
documentation/mkdocs.yml
View File

@ -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: