Module Build Tool

Concepts

General

This tool exists in order to simplify the build process of a module.

It provides the possibilty to build a module jar from a simplified developer directory. This developer directory has several advantages compared to a standard java project folder structure:

  • Can be used like a module, without the need of building a separate JAR.
  • Allows changes on a module at runtime.
  • Only contains necessary files and folders for a module.
  • Doesn't make use of UUIDs.

The build tool is used to create the technical structure of a module Java project from the logical structure of a developer directory. This Java directory can be used to build a module JAR using Maven. A build can be reproduced by saving and comparing all of its mapped UUIDs in a separate hidden file. A module build using the tool only creates complete modules. This means that each built module JAR works independently from other versions of the JAR. If you want to support several module versions (e.g. because there exist running instances of certain versions of a task), you need to keep these supported JARs in your module directory. The tool also supports the developer by validating a directory before building and can be used to create a skeleton as inital set up for a new developer directory. The validation can also be executed seperately. To create patches for specific forms as described in Form Development the tool also provides a JSON-diff functionality.

Functionality

Validate

Each time before executing the build process, the whole developer directory will be validated first. The tool will return an error statement if one of the following inspections fails:

  1. Validate directory and files
    • Does the module configuration file moduleConfig.yml exist?
    • Do all textresources have unique file names?
  2. Validate module configuration file
    • Do the parameters module, version, package exist?
    • Do these paramaters match the correct form?
      • module: Digits, Words (Lower & Upper Case), -, _
      • version: Following SemVer syntax. {Digits}.{Digits}.{Digits}
      • package: Digits, Words (Lower Case), ., _
    • Do the files referenced by action scripts exist?
    • Are all action names of every task unqiue?
    • Does an action predecessor exits for every action?
    • Does an action exist for every action and predecessor?
    • Do action and predecessor belong to the same task?

Build

  1. Generate the Java project directory needed to build a module JAR.
  2. Generate the module configuration file containing UUIDs (using UUID v1) and copy the resource files to the new directory.
  3. Generate the Java class.
  4. Generate the pom.xml.

Create Skeleton

Builds an empty developer directory, if the given project name doesn't already exist.

The created directory contains all needed folders and files. The meta configuration file will be preset with passed values, the module configuration will contain dummy text as inline documentation of its structure.

JSON-diff

Compares two JSON files and creates a JSON-patch at the given directory.

Installation

TODO: The installation is currently done manually by copying the sources of the tool to any directory of your choice.

Requirements

Node.js is required in order to run the tool.

Usage

Call the tool by using the following expression:

node buildmodule.js {command} [args]

Commands

build

node buildmodule.js build

Use this command to generate a complete java project directory. This directory can be used to build a module jar using maven. The command doesn't expect any arguments. It will create a build subfolder in your developer directory. If the build folder already exists, it will be deleted automatically before building the new one. In order to provide the correct module-context to the tool, call this command from the root of your developer directory. The build command will run a validation on the whole developer directory (As described in Concepts - Functionality -Validate) every time you call it before executing any other actions.

In order to reproduce the result of a build, a hidden .uuids.json file is created. This contains the UUIDs for all resources and entries in every known version of the generated module configuration. This file shouldn't be edited by a developer. If you delete it for example, the next build will create completely new UUIDs for every resource. If you want to use version control, you must also upload this hidden .uuids.json file

devdir

node buildmodule.js devdir [args]

Use this command to create an initial developer directory for a new module project at your current location. A module name must be passed to the command. The directory won't be created if the given module name already exists.

arguments:

  • -mn, --moduleName: Name of the module. Will be set as directory name as well as in the meta configuration.
  • -mv, --moduleVersion: [Optional] Version of the module. Will be set in the meta configuration. If not provided, it is set to 1.0.0
  • -mp, --modulePackage: [Optional] Package of the module. Will be set in the meta configuration. If not provided, it is set to de.ecm4u.sbcs.faw.module

validate

node buildmodule.js validate

Use this command to validate an existing developer directory (including moduleConfig.yml) at your current location.

jsondiff

node buildmodule.js jsondiff [args]

Use this command to Create a JSON-patch by diffing two JSON-files. The paths to the two JSON files which should be compared aswell as the name of the output file from the diff must be passed to the command. An optinal indentation for the created JSON file can be passed too.

arguments:

  • -jf, --jsonFrom: Path to the first JSON file.
  • -jt, --jsonTo: Path to the second JSON file.
  • -jd, --jsonDiff: Path to the result JSON-patch of the JSON-diff.
  • -i, --indentation: [Optional] Indentation to use for the created JSON-patch file. If not provided, it is set to 2.

Examples

Developer directory

If you run the devdir command, this structure will be created automatically:

└── sbcs-select-filing-case
    ├── action
    │   ├── action-file.json
    ├── form
    │   └── form-file.json
    ├── textresource
    │   ├── filterable-properties-types
    │   │   └── types.json
    │   ├── i18n
    │   │   └── i18n-file.json
    │   ├── jsonpatch
    │   │   └── jsonpatch-file.json
    │   ├── lib
    │   │   └── lib-file.js
    │   ├── script
    │   │   ├── script-file.js
    │   └── transfer-mapping
    │       └── mapping-file.json
    └── moduleConfig.yml

Developer directory files

If you run the devdir command, the file moduleConfig.yml will be created automatically.

module: sbcs-select-filing-case
version: 1.0.1
author: ecm4u GmbH
package: de.ecm4u.sbcs.faw.module

actionScripts:
    "{action script name}": "{action script file}"

tasks:
    "{task name}":
        actions:
          - name: "{action name 1}"
            impl: "{action implementation 1}"
            predecessors: []

          - name: "{action name 2}"
            impl: "{action implementation 2}"
            predecessors: ["{action name 1}"]
  • module: the name of the module
  • version: the version of the module
  • author: the author of the module
  • actionScripts: mapping from action script names script textresource names
  • tasks: mapping of task names to task details
    • actions: ordered list of the actions that the task contains
      • name: the name of the action
      • impl: the fully quallified name of the Java class that implements the action
      • predecessors: a list containing the names of the actions of the same task that must preceed the action
      • args: a mapping of arguments for the action (optional)
      • argsConfig: the name of the JSON file uder MODULE_HOME/actions that contains the arguments (optional)