1
0
mirror of https://github.com/SAP/jenkins-library.git synced 2025-01-04 04:07:16 +02:00
sap-jenkins-library/documentation/docs/scripts/utils.md
Oliver Nocon 749aa5e7ed
InfluxDB support (#52)
* adding step for writing metrics to InfluxDB including dependencies
* added documentation
* incorporated PR feedback
2018-01-24 09:55:38 +01:00

68 lines
2.5 KiB
Markdown

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