Groovy Libraries

Groovy Libraries allow custom Groovy functions and helpers to be shared and reused across all Groovy scripts in FlexDeploy

1 Creating a Library
2 Writing Functions
- 2.1 Testing Functions
- 2.2 Annotating Functions
  - 2.2.1 SuggestionMethodMeta API
3 Rename/Delete a Library
4 Library Compilation
- 4.1 Importing Other Custom Libraries
  - 4.1.1 Static Methods
  - 4.1.2 Circular Imports

Creating a Library

Libraries can be viewed and created by navigating to the Administration->Groovy Libraries page. Next click the Create Library button.

You will be prompted to provide a unique identifier for the library, called the Library Key .

The Library Key is also how your Groovy Library will be referenced from other scripts.

Upon saving the form you will be presented with a blank editor where one or more functions can be defined for your library.

Writing Functions

A function can be any common logic you would like to share across scripts. Lets take a very simple example and say we want to make a function that returns the FlexDeploy REST API URL.

// define any number of helper functions for this library

String getFlexDeployAPIUrl()
{
  def baseURL = FLEXDEPLOY.getFlexDeployBaseUrl()
  return "${baseURL}/flexdeploy/rest/v2"
}

Notice the use of the FLEXDEPLOY helper library as well. EMAIL, FLEXDEPLOY, REST, TOPOLOGY, and LOG helpers are all available for use in your custom library.

Testing Functions

Libraries can be tested at any point right from the editor by clicking the Try It button in the header.

Here you can write a sample script to test one or more functions in your library. Note that code suggestions for your library will not be shown in the try it window. With your test script ready simply hit the Run button or use the default shortcut of ctrl+shift+h to the test the function. In the screen shot we can see the result as http://localhost:8000/flexdeploy/rest/v2

Annotating Functions

By default when accessing library functions from other scripts they will have very basic information as seen below:

Its often beneficial to provide more information such as a description of the method and/or describing any parameters for your method. Both can be accomplished by using the SuggestionMethodMeta annotation.

Now we can see our function description when using it from other scripts:

SuggestionMethodMeta API

Field	Type	Description

Field	Type	Description
description	String	Overall description of the function. Markdown can be used.
params	List of Strings	A list of strings describing the function parameters. See full example below.
deprecated	boolean (default false)	If true this will indicate the function as deprecated. The name will be struckthrough when viewing in other scripts.
depAlternate	String	Optional alternative function name to use if this current function is deprecated.

import flexagon.fd.model2.suggestions.SuggestionMethodMeta;

@SuggestionMethodMeta(
  description = "Surely this function is overkill right?",
  params = ["first - The first param", "second - The second param"],
  deprecated = true,
  depAlternate = "multiply2"
)
Long multiply(Long first, Long second)
{
  return first * second;
}

Long multiply2(Long first, Long second)
{
  return first * second;
}

Rename/Delete a Library

To rename a library simply click the edit pencil icon next to the Library Key.

Changing the Library Key may break existing Groovy scripts using the old key of the Library. It is advised not to change the key once the library is in use.

To delete a library simply click the Delete button next to the edit button. Similar to renaming the library - deleting a library that is in use will break any Groovy script using the deleted library.

Library Compilation

The following section explains in detail how the script code you write is compiled and made available to each FlexDeploy Groovy script. This information can be helpful in more advanced Groovy Libraries.

The authored script code for each library is wrapped in a class declaration like so

package com.flexagon.groovy.custom;
// imports in the script are moved here

public class LIB_MY_LIB {
  // your script code is inserted here  
}

This class is compiled once at server startup and then on each change of the library script.

Finally, when running a Groovy script, an instance of this library class is instantiated and made available to the script as a variable matching the Library Key.

You can think of it as FlexDeploy automatically adding the following lines at the beginning of all of your Groovy scripts:

Importing Other Custom Libraries

Importing other custom libraries is only supported in version 9.0.0.2+

Custom libraries are not made available in other custom libraries by default, however they can be imported as needed. The below code snippet shows how the custom LIB_PIPELINE_UTILS imports and uses another custom library LIB_LOGGER.

Static Methods

Methods can be called statically, without an instance created, if they have the static modifier. Note - this only applies when importing other custom libraries since other Groovy scripts have instances created behind the scenes. See Library Compilation above.

For example:

LIB_LOGGER

LIB_PIPELINE_UTILS

Circular Imports

The below example demonstrates a circular library import and why its a problem:

LIB_ONE

LIB_TWO

Lets look at what happens when FlexDeploy compiles and creates instances of your custom libraries for other Groovy scripts to use.

FlexDeploy will iterate through all your Groovy Libraries and create an instance of each.
A new instance of LIB_ONE is created.
During initialization of LIB_ONE it will create a new instance of LIB_TWO as declared on line 1 of LIB_ONE
An instance of LIB_TWO is created during step 3. This in turn creates an instance of LIB_ONE as declared on line 1 of LIB_TWO.
1. We are now stuck in a loop between steps 3 and 4, infinitely creating new instances. This is what is known as a circular dependency and will result in an error being thrown.