skip to main content

Gradle Plugin

Livebase provides a Gradle plugin to automate some steps of the build processes.

When we develop an application managing a code base, it’s not uncommon to use continuous integration environments like Jenkins or Travis CI to simplify the development cycle and be more responsive to bug reports or feature requests. This approach is also suitable for low-code solutions like Livebase, which is why we’ve provided a Gradle plugin that you can easily invoke from your continuous integration environment, thus automating some steps of your build process.

Project Configuration #

To get started, create a new Gradle project and delete the contents of its build.gradle. Then enter the following code to import the Livebase plugin:

buildscript {
  repositories {
    mavenCentral()
  }

  dependencies {
    classpath 'com.fhoster.livebase:livebase-gradle-plugin:2.0.+'
  }
}

apply plugin: 'java'
apply plugin: 'com.fhoster.livebase'

Next, configure the plugin by adding the following section:

livebase {
  username = '<accountUsername>'
  password = '<accountPassword>'

  // Mutually exclusive
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Optional
  modelName = '<model>'

  // Optional, available in two formats
  pluginsName = '<jarPath>'          // To locate the plugin by name

  pluginsName '<regex>', true        // To locate plugins from a regular expression

  // Optional
  debugLog = true

  // Optional, default = false
  needsLock = true

  overrideSession = false
}
  • username: username of your livebase account;
  • password: password of your livebase account;
  • cloudletId/cloudletName : global parameters. They indicate the id or name of the Cloudlet that all executed Gradle tasks will refer to. You can specify only one or none of these parameters;
  • modelName: global parameter. Indicates the name of the model that all running Gradle tasks will refer to;
  • PluginsName: indicates the plugin(s) that all running Gradle tasks will refer to. Using the form pluginsName = '<jarPath>', you indicate only one plugin through the path of its .jar file; with the form pluginsName '<regex>', true, you indicate multiple plugins through a regular expression;
  • debugLog : if set to true, sets the log level to DEBUG printing all information;
  • needsLock : if set to true, task execution will reserve the Cloudlet. This is especially useful if the account we use has sub-accounts.

When you have finished specifying the configuration, verify the correct compilation of the plugin by running in the root of the project the command ./gradlew clean build.

Available tasks #

Livebase’s Gradle plugin provides a series of tasks that each act on a different type of element. So we can group them into task Cloudlet, task engine, task database, task plugin and task model.

Task Cloudlet #

The following tasks all operate on the Cloudlet Livebase.

createCloudlet #

Creates a new Cloudlet and deploy it to the Hosting Servant. You can configure the task by adding the following section to build.gradle:

createCloudlet {
  // If missing, use the value specified in the livebase section cloudletName = '<cloudlet>'
}
  • cloudletName : name that will be assigned to the new Cloudlet. If the parameter is omitted, the value of cloudletName specified in the livebase section will be used.

startCloudlet #

Starts a Cloudlet located on the Hosting Servant. You can configure the task by adding the following section to build.gradle:

startCloudlet {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Optional
  strictMode = false
}
  • cloudletId/cloudletName: id or name of the Cloudlet you want to start. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;
  • strictMode: if set to true, the task will fail immediately if the Cloudlet in question is already started. If the parameter is omitted, it is considered true.

stopCloudlet #

Stops a Cloudlet present on the Hosting Servant. You can configure the task by adding the following section to build.gradle:

stopCloudlet {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Optional
  strictMode = false
}
  • CloudletId/cloudletName: id or name of the Cloudlet you want to stop. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;
  • strictMode: if set to true, the task will fail immediately if the Cloudlet in question is already stopped. If the parameter is omitted, it is considered true.

retrieveCloudletInfo #

Prints information about a Cloudlet to an external file. You can configure the task by adding the following section to build.gradle:

retrieveCloudletInfo {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Mandatory
  outputFile = 'info.json'
}
  • CloudletId/cloudletName: id or name of the Cloudlet whose information you want to print. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;
  • outputFile: path to the file where the information will be saved. It must have json extension.

upgradeCloudlet #

Upgrades the API of a Cloudlet to the latest released version. You can configure the task by adding the following section to build.gradle:

upgradeCloudlet {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'
}
  • CloudletId/cloudletName: id or name of the Cloudlet whose API you want to update. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;

enableGraphQL #

Enables or disables the GraphQL API for a Cloudlet. You can configure the task by adding the following section to build.gradle:

enableGraphQL {
  // Mutually exclusive. If omitted, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Mandatory
  enablePlugin = false
}
  • CloudletId/cloudletName: id or name of the Cloudlet whose GraphQLs you want to enable or disable. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;
  • enablePlugin: if true, enable the GraphQL API; if false, disable it.

rebuildGraphQL #

Forces a Cloudlet’s GraphQL API rebuild. You can configure the task by adding the following section to build.gradle:

rebuildGraphQL {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'
}
  • CloudletId/cloudletName: id or name of the Cloudlet you want to rebuild GraphQLs for. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used.

deleteCloudlet #

Deletes a Cloudlet. You can configure the task by adding the following section to build.gradle:

deleteCloudlet {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'
}
  • CloudletId/cloudletName: id or name of the Cloudlet you want to delete. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used.

Task engine #

The following tasks all act on the engine, i.e. the model engines that have been loaded on the Livebase Cloudlets.

deployEngine #

Uploads a model to a Cloudlet. You can configure the task by adding the following section to build.gradle:

deployEngine {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Mutually exclusive
  sourceCloudletName = 'NewCloudlet2'
  sourceModelName = 'Model1'
}
  • CloudletId/cloudletName: id or name of the Cloudlet you want to upload the model to. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;
  • sourceCloudletName/sourceModelName : only one of these parameters can be specified at a time. If the first is specified, the model to be loaded will be taken from the Cloudlet with the given name; if the second is specified, the library model with that name will be taken.

downloadEngine #

Downloads the previously uploaded engine to a Cloudlet. You can configure the task by adding the following section to build.gradle:

downloadEngine {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Mandatory
  outputFile = 'model.xml'
}
  • CloudletId/cloudletName: id or name of the Cloudlet you want to download the engine from. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;
  • outputFile: path where the downloaded engine will be saved. It must have .xml extension.

deleteEngine #

Removes the model previously loaded on a Cloudlet. You can configure the task by adding the following section to build.gradle:

deleteEngine {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'
}
  • CloudletId/cloudletName: id or name of the Cloudlet you want to remove. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used.

Task database #

The following tasks all operate on the Cloudlet databases.

createDatabase #

Creates the empty database according to the model loaded on a Cloudlet. You can configure the task by adding the following section to build.gradle:

createDatabase {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'
}
  • CloudletId/cloudletName: id or name of the Cloudlet for which we want to generate the database. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used.

updateDatabase #

Forces the update of a Cloudlet’s database. You can configure the task by adding the following section to build.gradle:

updateDatabase {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'
}
  • CloudletId/cloudletName: id or name of the Cloudlet whose database you want to update. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used.

checkDatabase #

Performs an alignment check between the model currently loaded on the Cloudlet and the model that originated its database. You can configure the task by adding the following section to build.gradle:

import static com.fhoster.livebase.gradle.tasks.cloudlet.CheckDatabaseTask.FailOn.*

checkDatabase {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Optional
  outputFile = 'issues.csv'

  // Optional
  failOn = HighIssue
}
  • CloudletId/cloudletName: id or name of the Cloudlet you want to check. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;
  • OutputFile: path to the file where to save the list of issues detected during the check; it must have a .csv extension. If the parameter is omitted the issues will be printed on the standard output;
  • FailOn: specifies if the task execution should fail when a high issue (HighIssue) is found, at the first issue of any severity (AllIssues), or never (Never). If the parameter is omitted, the value AllIssues is used by default.

checkEngineDatabaseMismatch #

Compares the database you would get from the model currently installed on the Cloudlet with the structure of the current database, allowing you to highlight problems due to direct interventions on the latter (which would not be signaled by running checkDatabase). You can configure the task by adding the following section to the build.gradle:

checkEngineDatabaseMismatch {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Optional
  outputFile = 'issues.csv'

  // Optional
  failIfAny = true
}
  • CloudletId/cloudletName: id or name of the Cloudlet you want to check. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;
  • outputFile : path to the file where to save the list of issues detected during the check. It must have .csv extension. If the parameter is omitted the issues will be printed on the standard output;
  • FailIfAny: specifies whether the task execution should fail if issues are found. If the parameter is omitted, false is used as default value.

clearDatabase #

Removes all records contained in the database of a Cloudlet. You can configure the task by adding the following section to build.gradle:

clearDatabase {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'
}
  • CloudletId/cloudletName: id or name of the Cloudlet whose database you want to empty. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;

downloadDatabase #

Dumps the database of a Cloudlet and download the resulting sql file. You can configure the task by adding the following section to build.gradle.

downloadDatabase {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Mandatory
  outputFile = 'db.sql'
}
  • CloudletId/cloudletName: id or name of the Cloudlet whose database you want to download. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;
  • outputFile: path to the sql file where the dump will be saved. It must have .sql extension.

uploadDatabase #

Loads the database generated from a sql dump onto a Cloudlet. You can configure the task by adding the following section to build.gradle:

uploadDatabase {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Mandatory
  inputFile = 'db.sql'
}
  • CloudletId/cloudletName: id or name of the Cloudlet on which we want to load the database. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used;
  • inputFile: path to the sql file to be loaded. It must have .sql extension.

createAdmin #

Creates the default administrative user for a Cloudlet. You can configure the task by adding the following section to build.gradle:

createAdmin {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'
}
  • CloudletId/cloudletName: id or name of the Cloudlet for which we want to create the administrative user. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used.

Task plugin #

The following tasks all operate on plugins installed on Cloudlets.

listPlugins #

Lists all plugins installed on a Cloudlet, saving the list to file. You can configure the task by adding the following section to build.gradle:

listPlugins {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Mandatory
  outputFile = 'plugins.txt'
}
  • CloudletId/cloudletName: id or name of the Cloudlet whose plugins we want to list. You can specify only one of these parameters at a time. If both are omitted, the values ofcloudletIdorcloudletNamespecified inlivebase section will be used.
  • OutputFile: path to the file where the list of plugins will be saved. It must have extension.txt.

downloadEngineSpi #

Downloads the SPI of a Cloudlet. You can configure the task by adding the following section to build.gradle:

downloadEngineSpi {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Mandatory
  outputFile = 'plugins/test.jar'
}
  • (optional) cloudletId/cloudletName : id or name of the Cloudlet whose SPI you want to download. You can specify only one of these parameters at a time. If both are omitted, the values of cloudletId or cloudletName specified in the livebase section will be used.
  • outputFile: path to the file where the downloaded SPI will be saved; it must have .jar extension.

uploadPlugins #

Uploads one or more plugins to a Cloudlet. You can configure the task by adding the following section to build.gradle:

uploadPlugins {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Mutually exclusive.
  inputFile = 'plugins/test.jar'
  inputDirectory = 'plugins/'

  //Optional. Valid only if inputDirectory is specified
  includes = 'test.*\\.jar'
}
  • cloudletId/cloudletName: id or name of the Cloudlet where you want to load the plugins. You can specify only one of these parameters at a time. If both are omitted, the values ofcloudletIdorcloudletNamespecified inlivebase section will be used;
  • inputFile/inputDirectory: only one of these parameters can be specified at a time. Valorizing inputFile, the task will load the plugin with the specified path; valorizing inputDirectory, all plugins contained in the specified directory will be loaded;
  • includes: can be specified only if the parameter inputDirectory is present; it must be set to a regular expression that filters the plugins to load inside the directory.

downloadPlugins #

Downloads one or more plugins installed on a Cloudlet. You can configure the task by adding the following section to build.gradle:

downloadPlugins {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Optional, present in two formats. If missing, use the value specified in the livebase section
  pluginsName = '<jarPath>'          // To locate the plugin by name
  pluginsName '<regex>', true        // To locate plugins from a regular expression

  // Mandatory
  outputDirectory = 'plugins/'
}
  • cloudletId/cloudletName: id or name of the Cloudlet from which we want to download plugins. You can specify only one of these parameters at a time. If both are omitted, the values ofcloudletIdorcloudletNamespecified inlivebase section will be used;
  • PluginsName: name or regular expression indicating plugin(s) to download. If you want to indicate a regular expression you have to add true parameter as shown in the example. If the directive is omitted, the global one specified in the livebase section will be used;
  • outputDirectory : path to the directory where downloaded plugins will be saved.

startPlugins #

Starts one or more plugins previously installed on a Cloudlet. You can configure the task by adding the following section to build.gradle:

startPlugins {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Optional, present in two formats. If missing, use the value specified in the livebase section
  pluginsName = '<jarPath>'          // To locate the plugin by name
  pluginsName '<regex>', true        // To locate plugins from a regular expression
}
  • cloudletId/cloudletName: id or name of the Cloudlet you want to start the plugins of. You can specify only one of these parameters at a time. If both are omitted, the values ofcloudletIdorcloudletNamespecified inlivebase section will be used;
  • PluginsName: name or regular expression indicating plugin(s) to be started. If you want to indicate a regular expression you have to add true parameter as shown in the example. If the directive is omitted, the global one specified in the livebase section will be used;

stopPlugins #

Stops one or more plugins previously installed on a Cloudlet. You can configure the task by adding the following section to build.gradle:

stopPlugins {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Optional, present in two formats. If missing, use the value specified in the livebase section
  pluginsName = '<jarPath>'          // To locate the plugin by name
  pluginsName '<regex>', true        // To locate plugins from a regular expression
}
  • cloudletId/cloudletName: id or name of the Cloudlet whose plugins you want to stop. You can specify only one of these parameters at a time. If both are omitted, the values ofcloudletIdorcloudletNamespecified inlivebase section will be used;
  • PluginsName: name or regular expression indicating plugin(s) to be stopped. If you want to indicate a regular expression you have to add true parameter as shown in the example. If the directive is omitted, the global one specified in the livebase section will be used;

deletePlugins #

Removes one or more plugins previously installed on a Cloudlet. You can configure the task by adding the following section to build.gradle:

deletePlugins {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Optional, present in two formats. If missing, use the value specified in the livebase section
  pluginsName = '<jarPath>'          // To locate the plugin by name
  pluginsName '<regex>', true        // To locate plugins from a regular expression
}
  • cloudletId/cloudletName: id or name of the Cloudlet whose plugins you want to remove. You can specify only one of these parameters at a time. If both are omitted, the values ofcloudletIdorcloudletNamespecified inlivebase section will be used;
  • PluginsName: name or regular expression indicating plugin(s) to be removed. If you want to indicate a regular expression you have to add true parameter as shown in the example. If the directive is omitted, the global one specified in livebase section will be used;

printPluginsState #

Prints to a file the list of plugins installed on a Cloudlet, including their current status. The print format is as follows:

- <plugin1Name>: <STATE>
- <plugin2Name>: <STATE>
...

You can configure the task by adding the following section to build.gradle:

printPluginsState {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  cloudletId = '<id>'
  cloudletName = '<cloudlet>'

  // Optional, present in two formats. If missing, use the value specified in the livebase section
  pluginsName = '<jarPath>'          // To locate the plugin by name
  pluginsName '<regex>', true        // To locate plugins from a regular expression

  //Mandatory
  outputFile = 'plugins.txt'
}
  • cloudletId/cloudletName: id or name of the Cloudlet whose plugins information you want to print. You can specify only one of these parameters at a time. If both are omitted, the values ofcloudletIdorcloudletNamespecified inlivebase section will be used;
  • PluginsName: name or regular expression indicating plugin(s) to print information about. If you want to indicate a regular expression you have to add true parameter as shown in the example. If the directive is omitted, the global one specified in the livebase section will be used;
  • outputFile: path to the file where plugin information will be saved. It must have extension.txt.

Task model #

The following tasks all operate on models stored in the library.

uploadModel #

Loads a model saved on a local file into the library. You can configure the task by adding the following section to build.gradle:

uploadModel {
  // Optional. If missing, use the value specified in the livebase section
  modelName = 'Model1'

  // Mandatory
  modelDescription = 'MyModel'
  modelComments = 'MyModel'
  inputFile = 'model.xml'
}
  • modelName: name to assign to the model once loaded in the library; if the parameter is omitted, the global one specified in the livebase section will be used;
  • modelDescription: description to assign to the model once loaded in the library;
  • modelComments: version comments to be assigned to the model once loaded in the library;
  • inputFile: path to the file containing the model to be loaded; it must have .xml extension.

downloadModel #

Downloads a model present in the library. You can configure the task by adding the following section to build.gradle:

downloadModel {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  modelId = '<id>'
  modelName = 'Model1'

  // Mandatory
  outputFile = 'model.xml'
}
  • modelId/modelName: id or name of the library model to download; if both are omitted the value ofmodelNameparameter specified inlivebase section will be used;
  • outputFile: path to the file where to save the downloaded model; it must have .xml extension.

downloadModelSpi #

Downloads the SPI of a model in the library. You can configure the task by adding the following section to build.gradle.

downloadModelSpi {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  modelId = '<id>'
  modelName = 'Model1'

  // Mandatory
  outputFile = 'modelSpi.jar'
}
  • modelId/modelName: id or model name of the library whose SPI we want to download. If both are omitted the value of modelName parameter specified in livebase section will be used;
  • outputFile: path to the file where to save the downloaded SPI; it must have .jar extension.

deleteModel #

Removes a model from the library. You can configure the task by adding the following section to the buildGradle.

deleteModel {
  // Mutually exclusive. If missing, use the value specified in the livebase section
  modelId = '<id>'
  modelName = 'Model1'
}
  • modelId/modelName: id or name of the library model you want to remove. If both are omitted the value of the modelName parameter specified in the livebase section will be used;

Create custom tasks #

Gradle tasks already included in the Livebase plugin can be configured to act on only one item at a time. If you need to perform the same operations on more than one element, you can define new custom tasks by overriding the default ones.

To do that, first import the type of task you want to override by inserting this directive in build.gradle:

import com.fhoster.livebase.gradle.tasks.cloudlet.<taskToOverride>

Replace <taskToOverride> with the name of the task in camel case, followed by the word Task; for example, if you want to override the startCloudlet task, you would write StartCloudletTask.

Next, define the custom task as follows, replacing _customTask with the name you want to assign to it:

task _customTask(type: <taskToOverride>) {
  // Configuration parameters overwritten by the original task
}

You can reference configuration parameters defined in another task with the syntax <gradleTaskName>.<parameterName>. The following example assigns as the value of inputFile for the custom task that of outputFile of the downloadEngineSpi task:

task _customUploadSpi(type: UploadPluginsTask) {
  inputFile = downloadEngineSpi.outputFile
}

You can also determine the execution order of this new task with respect to the previous ones by introducing the dependsOn argument. The following example defines a task that depends on downloadEngineSpi and will therefore be executed after it:

task _afterDownloadEngineSpi(type: <anyType>, dependsOn: downloadEngineSpi) {
  // Configuration parameters overwritten by the original task
}

References #