Gradle Plugin for synchronizing models between model-api endpoints

Overview

The bulk-model-sync Gradle plugin synchronizes models between model-api endpoints. A common example would be synchronizing a local MPS project to a model-server.

Bulk Synchronization between MPS and model-server
Figure 1. Bulk Synchronization between MPS and model-server

The plugin allows the definition of sync directions inside of a modelSync block by specifying source and target endpoint. Based on these directions, Gradle tasks will be generated, which can be run to trigger the corresponding synchronization.

Internally, the node data will be bulk exported from the source endpoint and stored as JSON files. After that, these JSON files serve as a specification to incrementally update the target model via the target model-api endpoint. This means that only a minimal amount of write operations is used to update the target model.

Configuration settings

modelSync configuration

method parameter type description

dependsOn

Any

Adds the given task as a dependency of this task.

direction

String, Action<SyncDirection>

Defines a new sync direction with the given name.

SyncDirection configuration

method parameter type description

fromLocal

Action<LocalSource>

Defines a local source (MPS).

toModelServer

Action<ServerTarget>

Defines a model-server target.

fromModelServer

Action<ServerSource>

Defines a model-server source.

toLocal

Action<LocalTarget>

Defines a local target (MPS).

includeModule

String

Includes the module specified by the given fully qualified name in the synchronisation process.

includeModulesByPrefix

String

Includes all modules, whose fully qualified name starts with the given prefix, in the synchronisation process.

excludeModule

String

Excludes the module specified by the fully qualified name from the included modules.

excludeModuleByPrefix

String

Excludes all modules, whose fully qualified name starts with the given prefix, from the included modules.

enableContinueOnError

Boolean

If the sync encounters an error, simply log it and continue instead of terminating. This most likely results in an incomplete sync result. Defaults to false.

LocalSource/-Target configuration

setting type description

mpsHome

File

Location of the MPS to be used for the sync.

Alternatively, you can just specify an MPS version that is then downloaded automatically. This is handled by a different plugin that you can configure like this:

mpsBuild {
    mpsVersion("2021.2.5")
}

mpsLibrary

File

A folder containing MPS modules that the MPS project in repositoryDir depends on. Multiple folders can be specified.

mpsHeapSize

String

MPS heap size specified as a String, e.g. "2g" for 2GB (default: "2g")

repositoryDir

File

Directory in which the modules are stored.

mpsDebugPort

Int

If set, the headless MPS will suspend on startup and wait for a remote debugger on the specified port.

mpsPlugin

PluginSpec

Add a plugin to be loaded when running MPS. jetbrains.mps.core, jetbrains.mps.testing, jetbrains.mps.ide.make are always loaded.

All other plugins, even bundled ones, must be configured explicitly. In general cases, the sync does not rely on concepts (and in turn on languages and plugins) of the synced nodes.

Loading other plugins might become necessary when they provide custom persistence and in other, yet unknown cases. First, try if the sync works for your project without adding plugins.

ServerSource/-Target configuration

In the future you will be required to specify a repositoryId along the revision.
setting type description

url

String

URL of the model-server API endpoint.

repositoryId

String

Id of the target/source model-server repository. If the repository does not exist on the model-server, it will be created including a master branch.

branchName

String

Name of the target/source model-server branch. If the target branch does not exist on the model-server, it will be created.

revision

String

Source model-server revision. Can be used instead of repositoryId and branchName. Only available in ServerSource.

baseRevision

String

Source model-server base revision. If specified, only the subtrees that changed between baseRevision and revision will be synchronized. Only available in ServerSource.

requestTimeoutSeconds

Integer

The request timeout measured in seconds to apply when performing HTTP requests towards the model-server. Default: 5 minutes

metaProperties

MutableMap<String, String>

Custom properties that will be attached to the root node. The mapping is propertyName → propertyValue. Only available in ServerTarget.

Example

mpsBuild {
    mpsVersion("2021.2.5")
}

modelSync {
    dependsOn(someOtherTask)
    direction("pushToMyServer") {
        includeModule("MySolution")
        fromLocal {
            mpsHeapSize = "4g"
            repositoryDir = projectDir.resolve("my-repo")
        }
        toModelServer {
            url = "http://0.0.0.0:28101/v2"
            repositoryId = "my-repo"
            branchName = "dev"
        }
    }
}

Generated Gradle task to perform synchronization: runSyncPushToMyServer.

Logging

The plugin uses the normal Gradle logging. In case progress or debug information is required, run Gradle with --info or --debug command line arguments.