lifecycleGenerator (Jervis 1.6 API)

net.gleske.jervis.lang.lifecycleGenerator

All Implemented Interfaces and Traits:: Serializable

class lifecycleGenerator
extends Object

Generates the build scripts from the Jervis YAML.

Sample usage

To run this example, clone Jervis and execute ./gradlew console to bring up a Groovy Console with the classpath set up.

Please note, if you are writing Job DSL plugin groovy scripts you should not use the relative file paths to access files in the repository where your DSL scripts reside. Instead, use the readFileFromWorkspace method provided by the Job DSL plugin in Jenkins.

import net.gleske.jervis.lang.lifecycleGenerator

String yaml = """
language: ruby
env:
 - hello=world three=four
 - hello=test three=five
rvm: ["1.9.3", "2.1.0", "2.0.0"]
jdk: openjdk8
matrix:
  exclude:
    - env: hello=world three=four
      rvm: 2.1.0
    - rvm: 1.9.3
  include:
    - rvm: 2.1.0
    - rvm: 2.0.0
      env: hello=test three=five
jenkins:
    sudo: false
"""

def generator = new lifecycleGenerator()
generator.loadPlatforms('resources/platforms.json')
generator.preloadYamlString(yaml)
//os_stability requires preloadYamlString() to be called
def os_stability = "${generator.label_os}-${generator.label_stability}"
generator.loadLifecycles("resources/lifecycles-${os_stability}.json")
generator.loadToolchains("resources/toolchains-${os_stability}.json")
generator.loadYamlString(yaml)
generator.folder_listing = ['Gemfile.lock']
println 'Exclude filter is...'
println generator.matrixExcludeFilter()
println 'Matrix axis value for env is...'
println generator.matrixGetAxisValue('env')
println 'Generating the matrix build script.'
println generator.generateAll()
print 'Labels: '
println generator.getLabels()

Properties Summary

Properties
Type	Name and description
`List`	`cipherlist` A list of secrets loaded from the YAML file.
`Map`	`ciphermap` A map of secrets loaded from the YAML file.
`String`	`filter_type` Defines the kind of branch filtering which is in effect.
`List`	`folder_listing` This is a folder listing of the root of the repository so that scripts can be conditionally generated depending on build tool is being used.
`Boolean`	`is_pr` A variable set by any external system relaying to Jervis that this is a peer review build (commonly called a pull request).
`Boolean`	`is_tag` A variable set by any external system relaying to Jervis that this is a build associated with a tag.
`Map`	`jervis_yaml` Contains the Jervis YAML loaded as an object.
`String`	`label_os` An optional label which is used by the `getLabels()` function to generate advanced job labels across different operating systems.
`String`	`label_platform` An optional label which is used by the `getLabels()` function to generate advanced job labels across different platforms.
`String`	`label_stability` An optional label which is used by the `getLabels()` function to generate advanced job labels for agent stability.
`String`	`label_sudo` An optional label which is used by the `getLabels()` function to generate advanced job labels for agents with sudo or nosudo access.
`String`	`lifecycle_key` The value is the key to be looked up in the lifecycles file by default when determining how to generate scripts.
`def`	`lifecycle_obj` An instance of the `lifecycleValidator` class which has loaded a lifecycles file.
`Boolean`	`matrix_build` A variable for determining whether or not this is a matrix build.
`Map`	`matrix_fullName_by_friendly` A map of friendly key names for matrix steps which can be reference to show a full key name as if the friendly name were not needed.
`List`	`plainlist` A list of decrypted values from the `cipherlist`.
`Map`	`plainmap` A list of decrypted values from the `ciphermap`.
`def`	`platform_obj` An instance of the `platformValidator` class which as loaded a platforms file.
`def`	`secret_util` A utility for decrypting RSA encrypted strings in YAML files.
`def`	`toolchain_obj` An instance of the `toolchainValidator` class which has loaded a toolchains file.
`String[]`	`yaml_keys` A quick access variable for what root keys are in the loaded Jervis YAML.
`String`	`yaml_language` A quick access variable for what language is selected for the loaded Jervis YAML.
`List`	`yaml_matrix_axes` A quick access variable for matrix build axes.

Methods Summary

Methods
Type Params	Return Type	Name and description
	`void`	`decryptSecrets()` Decrypts encrypted values stored in `cipherlist`.
	`String`	`generateAll()` Generate the build script which would be used in the Jenkins step.
	`String`	`generateSection(String section)` A generic function to generate code for different sections of the build script.
	`String`	`generateToolchainSection()` Generate the toolchains shell script based on the Jervis YAML or taking defaults from the toolchains file.
	`String`	`getBranchRegexString()` Get the regular expression which is used for branch filtering.
	`List`	`getFilteredBranchesList()` Get a list of static branch names which is used for branch filtering.
	`String`	`getFullBranchRegexString(List branches)` Get the regular expression for all whitelisted branches.
	`String`	`getJenkinsfile()` Get the `Jenkinsfile` for a pipeline.
	`String`	`getLabels()` Returns a groovy expression which Jenkins would use to pin a job to specific nodes.
	`Map`	`getMatrix_fullName_by_friendly()`
	`static Object`	`getObjectValue(Map object, String key, Object defaultValue)` Get an object from a `Map` or return any object from `defaultValue`.
	`Boolean`	`hasRegexFilter()` This method makes it easy to detect if regular expressions are defined for branch filtering.
	`Boolean`	`isFilteredByRegex(String branch)` Detect if this branch is already covered by a regex filter.
	`Boolean`	`isGenerateBranch(String branch)` Is this a branch which will generate a job?
	`static boolean`	`isInstanceFromList(Object object, List<Class> list)` Check if an object is an instance of any of the classes in a list.
	`Boolean`	`isMatrixBuild()` This will check if the loaded YAML is a matrix build.
	`boolean`	`isPipelineJob()` Determine if this instance is compatible with pipeline multibranch jobs.
	`boolean`	`isRestricted(String project)` Given a project combination of `org/project` determine if a project is allowed to be generated for a platform combination.
	`boolean`	`isSupportedPlatform()` Checks if a job that is using a platform and toolchain which is supported in the loaded platforms file.
	`void`	`loadLifecycles(String file)` Load a lifecycles file so that default scripts can be generated.
	`void`	`loadLifecyclesString(String json)` Load a lifecycles JSON `String` so that default scripts can be generated.
	`void`	`loadPlatforms(String file)` Load a platforms file so that advanced labels can be generated for multiple platforms.
	`void`	`loadPlatformsString(String json)` Load a platforms JSON `String` so that advanced labels can be generated for multiple platforms.
	`void`	`loadToolchains(String file)` Load a toolchains file so that default scripts can be generated.
	`void`	`loadToolchainsString(String json)` Load a toolchains JSON `String` so that default scripts can be generated.
	`void`	`loadYamlString(String raw_yaml)` Load Jervis YAML to be interpreted.
	`String`	`matrixExcludeFilter()` This function generates a Jenkins groovy expression from Jervis YAML which will be used to exclude matrix build combinations.
	`String`	`matrixGetAxisValue(String axis)` Get a value for a given axis for matrix building.
	`void`	`preloadYamlString(String raw_yaml)` Preload Jervis YAML for the purpose of loading lifecycles files for other platforms and operating systems.
	`void`	`setFolder_listing(List listing)` This function sets the `folder_listing` and based on the `listing` conditionally sets `lifecycle_key`.
	`void`	`setLabel_stability(String stability)` This function sets the `label_stability` property.
	`void`	`setLabel_sudo(String sudo)` This function sets the `label_sudo` property.
	`void`	`setPrivateKey(String pem)` Load an RSA private key in-memory rather than depending on a file existing on disk.

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class Object`	`wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- Property Detail
  - List cipherlist
    
    A list of secrets loaded from the YAML file.
  - Map ciphermap
    
    A map of secrets loaded from the YAML file.
  - String filter_type
    
    Defines the kind of branch filtering which is in effect. Possible values: empty string, only, except. only is used for whitelist filtering and except is used for blacklist filtering.
  - List folder_listing
    
    This is a folder listing of the root of the repository so that scripts can be conditionally generated depending on build tool is being used. This way we can do neat things like generate different script output depending on if there's a build.gradle, pom.xml, or build.xml. loadYamlString(java.lang.String) should be called before this.
  - Boolean is_pr
    
    A variable set by any external system relaying to Jervis that this is a peer review build (commonly called a pull request).
  - Boolean is_tag
    
    A variable set by any external system relaying to Jervis that this is a build associated with a tag.
  - Map jervis_yaml
    
    Contains the Jervis YAML loaded as an object.
  - String label_os
    
    An optional label which is used by the getLabels() function to generate advanced job labels across different operating systems. This is populated by preloadYamlString(java.lang.String).
  - String label_platform
    
    An optional label which is used by the getLabels() function to generate advanced job labels across different platforms. This is populated by preloadYamlString(java.lang.String).
  - String label_stability
    
    An optional label which is used by the getLabels() function to generate advanced job labels for agent stability. This is populated by preloadYamlString(java.lang.String). The value is always stable or unstable.
  - String label_sudo
    
    An optional label which is used by the getLabels() function to generate advanced job labels for agents with sudo or nosudo access. This is populated by preloadYamlString(java.lang.String). The value is always sudo or nosudo.
  - String lifecycle_key
    
    The value is the key to be looked up in the lifecycles file by default when determining how to generate scripts. This is set when a list of files is set in the folder_listing.
  - def lifecycle_obj
    
    An instance of the lifecycleValidator class which has loaded a lifecycles file.
  - Boolean matrix_build
    
    A variable for determining whether or not this is a matrix build.
  - Map matrix_fullName_by_friendly
    
    A map of friendly key names for matrix steps which can be reference to show a full key name as if the friendly name were not needed. Basically, it allows the unfriendly name to be accessible via the friendly name.
  - List plainlist
    
    A list of decrypted values from the cipherlist.
  - Map plainmap
    
    A list of decrypted values from the ciphermap.
  - def platform_obj
    
    An instance of the platformValidator class which as loaded a platforms file.
  - def secret_util
    
    A utility for decrypting RSA encrypted strings in YAML files. This is an instance of the securityIO.
  - def toolchain_obj
    
    An instance of the toolchainValidator class which has loaded a toolchains file.
  - String[] yaml_keys
    
    A quick access variable for what root keys are in the loaded Jervis YAML.
  - String yaml_language
    
    A quick access variable for what language is selected for the loaded Jervis YAML.
  - List yaml_matrix_axes
    
    A quick access variable for matrix build axes.
- Method Detail
  - void decryptSecrets()
    
    Decrypts encrypted values stored in cipherlist. All decrypted values will be stored in plainlist which is where they should be accessed. Any malformatted Hash Maps within cipherlist which don't have a secret and key item key in the HashMap will simply be ignored. Decryption errors will throw an exception.
  - String generateAll()
    
    Generate the build script which would be used in the Jenkins step. This function combines the output of: generateToolchainSection(), generateBeforeInstall(), generateInstall(), generateBeforeScript() , and generateScript().
    Returns:
    A shell script which is used to build the application in Jervis.
  - String generateSection(String section)
    
    A generic function to generate code for different sections of the build script. Typical sections include: before_install, install, before_script, script
    Parameters:
    section - A section from the build lifecycle. e.g. before_install, install, before_script, script, etc.
    Returns:
    Code generated from that section in the Jervis YAML, default from the lifecycles file, or returns an empty String.
  - String generateToolchainSection()
    
    Generate the toolchains shell script based on the Jervis YAML or taking defaults from the toolchains file.
    Returns:
    A bash script setting up the toolchains for building.
  - String getBranchRegexString()
    
    Get the regular expression which is used for branch filtering.
    Returns:
    String which is compatible with Pattern. If no filters are found or the loaded Jervis YAML does not filter, then an empty String is returned.
  - List getFilteredBranchesList()
    
    Get a list of static branch names which is used for branch filtering. This is a simple literal list of Strings.
    Returns:
    A List of literal branch names meant to be filtered.
  - String getFullBranchRegexString(List branches)
    
    Get the regular expression for all whitelisted branches. This is the combination of which is the combination of getBranchRegexString() and branches into one regex to cover all cases.
    Parameters:
    branches - A list of branches.
    Returns:
    A String which is a Pattern. The combination of internal regex filters with the branches.
  - String getJenkinsfile()
    
    Get the Jenkinsfile for a pipeline.
    Returns:
    Returns the path to the Jenkinsfile the pipeline multibranch job will use.
    See Also:
    isPipelineJob()
  - String getLabels()
    
    Returns a groovy expression which Jenkins would use to pin a job to specific nodes.
    Returns:
    A String which is a groovy expression of Jenkins node labels.
  - Map getMatrix_fullName_by_friendly()
  - static final Object getObjectValue(Map object, String key, Object defaultValue)
    
    Get an object from a Map or return any object from defaultValue. Guarantees that what is returned is the same type as defaultValue. This is used to get optional keys from YAML or JSON files.
    Parameters:
    object - A Map which was likely created from a YAML or JSON file.
    key - A String with keys and subkeys separated by periods which is used to search the object for a possible value.
    defaultValue - A default value and type that should be returned.
    Returns:
    Returns the value of the key or a defaultValue which is of the same type as defaultValue. This function has three coercion behaviors which is not the same as Groovy:
    
    If the defaultValue is an instance of String and the retrieved key is an instance of Map, then defaultValue is returned rather than converting it to a String.
    
    If the defaultValue is an instance of String and the retrieved key is an instance of List, then defaultValue is returned rather than converting it to a String.
    
    If the defaultValue is an instance of Boolean, the retrieved key is an instance of String and has a value of false, then Boolean false is returned.
  - Boolean hasRegexFilter()
    
    This method makes it easy to detect if regular expressions are defined for branch filtering.
    Returns:
    true if a regex filter for branch filtering is available.
  - Boolean isFilteredByRegex(String branch)
    
    Detect if this branch is already covered by a regex filter.
    Parameters:
    branch - The name of a branch to be compared with the regex.
    Returns:
    true if a regex filter matches the branch.
  - Boolean isGenerateBranch(String branch)
    
    Is this a branch which will generate a job?
    Parameters:
    branch - A branch to check if the job should be generated.
    Returns:
    Returns true if the job should be generated or false if it should not.
  - static final boolean isInstanceFromList(Object object, List<Class> list)
    
    Check if an object is an instance of any of the classes in a list.
    Parameters:
    object - Any kind of object.
    list - A list of classes deriving from type Class.
    Returns:
    true if object is an instance of any one of the items in the list.
  - Boolean isMatrixBuild()
    
    This will check if the loaded YAML is a matrix build. The requirements for it to be a matrix build is that it must be a matrix specifically for the selected language and the array for the section must be greater than 1.
    For example the following YAML would not produce a matrix build.
```
language: groovy
env: foo=bar
```
```
language: groovy
env:
  - foo=bar
```
    However, the following YAML will produce a matrix build. This assumes that matrix: disabled is not set for env in the toolchains file.
```
language: groovy
env:
  - foobar=foo
  - foobar=bar
```
    Returns:
    true if a matrix build will be generated or false if it will just be a regular build.
  - boolean isPipelineJob()
    
    Determine if this instance is compatible with pipeline multibranch jobs.
    Returns:
    Returns true if this instance is compatible with pipeline multibranch jobs.
    See Also:
    getJenkinsfile()
  - boolean isRestricted(String project)
    
    Given a project combination of org/project determine if a project is allowed to be generated for a platform combination. The platform combination is determined by label_platform and label_os. A Jenkins job should not be generated if it is restricted via the restrictions section of the platforms file.
    Returns:
    Returns true if not allowed or false if it is allowed. That is, it is not restricted.
  - boolean isSupportedPlatform()
    
    Checks if a job that is using a platform and toolchain which is supported in the loaded platforms file.
    Returns:
    Returns true if a job can be generated from the requested platform.
  - void loadLifecycles(String file)
    
    Load a lifecycles file so that default scripts can be generated. Lifecycles provide the build portions of the script. This project comes with a lifecycles file. The lifecycles file in this repository relative to the repository root is /src/main/resources/lifecycles.json.
    Parameters:
    file - A path to a lifecycles file.
  - void loadLifecyclesString(String json)
    
    Load a lifecycles JSON String so that default scripts can be generated. Lifecycles provide the build portions of the script. This project comes with a lifecycles file. The lifecycles file in this repository relative to the repository root is /src/main/resources/lifecycles.json.
    Parameters:
    json - A String containing JSON which is from a lifecycles file.
  - void loadPlatforms(String file)
    
    Load a platforms file so that advanced labels can be generated for multiple platforms. A platform could be a local datacenter or a cloud providor. The platforms file allows labels to be generated which include stability, sudo access, and even operating system. This could be used to load lifecycles and toolchains by platform and OS. This project comes with a platforms file. The platforms file in this repository relative to the repository root is /src/main/resources/platforms.json.
    Parameters:
    file - A path to a platforms file.
  - void loadPlatformsString(String json)
    
    Load a platforms JSON String so that advanced labels can be generated for multiple platforms. A platform could be a local datacenter or a cloud providor. The platforms file allows labels to be generated which include stability, sudo access, and even operating system. This could be used to load lifecycles and toolchains by platform and OS. This project comes with a platforms file. The platforms file in this repository relative to the repository root is /src/main/resources/platforms.json.
    Parameters:
    json - A String containing JSON which is from a platforms file.
  - void loadToolchains(String file)
    
    Load a toolchains file so that default scripts can be generated. Toolchains provide the default tool setup of the script (e.g. what version of Java will be used). This project comes with a toolchains file. The toolchains file in this repository relative to the repository root is /src/main/resources/toolchains.json.
    Parameters:
    file - A path to a toolchains file.
  - void loadToolchainsString(String json)
    
    Load a toolchains JSON String so that default scripts can be generated. Toolchains provide the default tool setup of the script (e.g. what version of Java will be used). This project comes with a toolchains file. The toolchains file in this repository relative to the repository root is /src/main/resources/toolchains.json.
    Parameters:
    json - A String containing JSON which is from a toolchains file.
  - void loadYamlString(String raw_yaml)
    
    Load Jervis YAML to be interpreted. This YAML will be used to generate the build scripts and components of a Jenkins job. Please note: you must call loadToolchains(java.lang.String) and loadLifecycles(java.lang.String) before calling this function.
    Parameters:
    raw_yaml - A String which contains Jervis YAML to be parsed.
  - String matrixExcludeFilter()
    
    This function generates a Jenkins groovy expression from Jervis YAML which will be used to exclude matrix build combinations. This is typically done from a matrix exclusion in the form of a whitelist or blacklist.
    Returns:
    A String which is a simple groovy expression.
  - String matrixGetAxisValue(String axis)
    
    Get a value for a given axis for matrix building. Each matrix job has multiple axes. This function is designed to return the value of the axis if given a name.
    Parameters:
    axis - A matrix building axis. e.g. env
    Returns:
    A String which is the value of the given axis in a matrix build.
  - void preloadYamlString(String raw_yaml)
    
    Preload Jervis YAML for the purpose of loading lifecycles files for other platforms and operating systems. Please note: you must call loadPlatformsString(java.lang.String) or loadPlatforms(java.lang.String) before calling this function.
    Parameters:
    raw_yaml - A String which contains Jervis YAML to be parsed.
  - void setFolder_listing(List listing)
    
    This function sets the folder_listing and based on the listing conditionally sets lifecycle_key. This uses the fileExistsCondition and fallbackKey from the lifecycles file to determine the contents of lifecycle_key. loadYamlString(java.lang.String) should be called before this.
    Parameters:
    listing - An List which is a list of files from a directory path in a repository.
  - void setLabel_stability(String stability)
    
    This function sets the label_stability property. It forces the value to always be stable or unstable.
    Parameters:
    stability - A String which determines the stability. A value of unstable or true will set the property as unstable. All other values set the property as stable.
  - void setLabel_sudo(String sudo)
    
    This function sets the label_sudo property. It forces the value to always be sudo or nosudo.
    Parameters:
    sudo - A String which determines sudo access required. A value of sudo or true will set the property as sudo. All other values set the property as nosudo.
  - void setPrivateKey(String pem)
    
    Load an RSA private key in-memory rather than depending on a file existing on disk. This is required to decrypt secrets in a YAML file. Call this function before decryptSecrets() if expecting encrypted YAML keys.
    Parameters:
    pem - A String whose contents is an X.509 PEM encoded RSA private key.

Summary:
Property
Method

| Detail:
Property
Method

Jervis API documentation.

[Groovy] Class lifecycleGenerator

Sample usage

Properties Summary

Methods Summary

Inherited Methods Summary

Property Detail

List cipherlist

Map ciphermap

String filter_type

List folder_listing

Boolean is_pr

Boolean is_tag

Map jervis_yaml

String label_os

String label_platform

String label_stability

String label_sudo

String lifecycle_key

def lifecycle_obj

Boolean matrix_build

Map matrix_fullName_by_friendly

List plainlist

Map plainmap

def platform_obj

def secret_util

def toolchain_obj

String[] yaml_keys

String yaml_language

List yaml_matrix_axes

Method Detail

void decryptSecrets()

String generateAll()

String generateSection(String section)

String generateToolchainSection()

String getBranchRegexString()

List getFilteredBranchesList()

String getFullBranchRegexString(List branches)

String getJenkinsfile()

String getLabels()

Map getMatrix_fullName_by_friendly()

static final Object getObjectValue(Map object, String key, Object defaultValue)

Boolean hasRegexFilter()

Boolean isFilteredByRegex(String branch)

Boolean isGenerateBranch(String branch)

static final boolean isInstanceFromList(Object object, List<Class> list)

Boolean isMatrixBuild()

boolean isPipelineJob()

boolean isRestricted(String project)

boolean isSupportedPlatform()

void loadLifecycles(String file)

void loadLifecyclesString(String json)

void loadPlatforms(String file)

void loadPlatformsString(String json)

void loadToolchains(String file)

void loadToolchainsString(String json)

void loadYamlString(String raw_yaml)

String matrixExcludeFilter()

String matrixGetAxisValue(String axis)

void preloadYamlString(String raw_yaml)

void setFolder_listing(List listing)

void setLabel_stability(String stability)

void setLabel_sudo(String sudo)

void setPrivateKey(String pem)