Projects:BuildValidationsAndModuleScripts

Contents 1 Introduction 2 Objectives 3 Example Use-case 4 Developers Documentation 5 Description 6 Test cases

Introduction

In some cases the need to execute manual actions (java-code) while doing an ERP core or a module update arises to handle special situations.

Those could include checking data for compliance with some rules or doing automated data changes which cannot be done using the normal update.database task.

This project will provide a means to do both types of actions.

Objectives

This project will add a new artifact (java-code) called BuildValidation which can be included in core or a module. It will be executed before the update and can stop the update process with an error message shown to the user. BuildValidations are not supposed to do any data-modifications.

It also adds a second artifact (java-code) called ModuleScript which can be again included in core or a module which is executed inside the update.database process and is allowed to do data changes.

Example Use-case

An update to existing code, either a core ERP maintenance pack or a new module version wants to make an existing database unique constraint stricter by removing one of it fields.

In this case users which have data which is valid with the old version of the constraint but not the new one will be faced with an error on the upgrade.

A new BuildValidation can check the local data verifying that it is complying with the tighter constraint and otherwise stop the update process providing a message to the user, which manual steps need to be done to update the data.

Developers Documentation

A howto explaining how to write and use a BuildValidation or a ModuleScript can be found here.

Description

This project aims to create an infrastructure to support Build Validations (which will be checks executed at the beginning of the Build Process) and Module Scripts (which will be actions executed during the Build Process). Build Validations and Module Scripts can be added both in Openbravo Core, and through modules.

The main tasks which this project will have are:

• Build Validation
  • A new abstract class will be created (with one single method, List<String> execute()).
  • BuildValidationHandler: loads using reflection all the classes (which will implement the interface) contained in the src-util/buildvalidation both in Core and inside the modules folder, and executes them (in a completely safe manner, so that if the validation done by one module crashes, the process doesn't fail).
  • A special compile task will compile all the classes in src-util/buildvalidation (and src-util/modulecript)
  • The Build Process calls the BuildValidationHandler (update.database does it at the beginning). If the system doesn't comply with the validation rules, the build fails.

• Module Script
  • A similar new abstract class will be created (with the method void execute()).
  • A similar ModuleScriptHandler which works the same (executes the methods of the precompiled classes in src-util/modulescript, both in Core and in modules).
  • The Build Process calls the ModuleScriptHandler during the update.database task

• Testing and examples
  • We need to create examples (at least one functional example already known (a more restrictive constraint needs to be validated).
  • Test the examples in several different environments, updating Core and applying modules, ...

Test cases

The main objectives of the test cases are to test the compilation tasks, to verify that the correct validations and modulescripts are executed in each possible situation, and that the correct action is taken in each case.

Taking this objectives into account, several test cases have been defined. In order to execute them, it's necessary to have two modules in the system, in addition to Core.

Test 1: Compilation test

• Create a BuildValidation and a ModuleScript for two different modules, and for Core.
• Test that the compilation tasks compile the BuildValidations and the ModuleScripts, and put the compiled binaries in the correct folder. This means that the following tasks should be executed:

ant compile.buildvalidation -Dmodule=org.openbravo

ant compile.modulescript -Dmodule=org.openbravo

ant compile.buildvalidation -Dmodule=javapackage1

ant compile.modulescript -Dmodule=javapackage1

ant compile.buildvalidation -Dmodule=javapackage2

ant compile.modulescript -Dmodule=javapackage2

And the binaries should be in src-util/buildvalidation/build/classes and src-util/modulescript/build/classes for the Core ones, and in modules/eachmodule/src-util/buildvalidation/build/classes and modules/eachmodule/src-util/modulescript/build/classes for the modules ones.

Test 2: Verify that the correct script is executed

• Execute ant update.database. All defined scripts, both for Core and for every module in the system, should be executed.
• Execute ant update.database.mod -Dmodule=javapackage1. The scripts for module 1 should be executed.
• Execute ant update.database.mod -Dmodule="javapackage1, javapackage2". The scripts for both module 1 and 2 should be executed.

Test 3: Verify that the correct validations are executed, and that the correct action is taken

• Modify the validations so that they "fail" (that is, they 'don't validate').
• Compile the classes, package the modules.
• Install the modules in an Openbravo instance, verify that the validation is done, it fails, and that the build is stopped.
• Compile the validation in Core, and rebuild Core (like it would be done in an update). Verify that the validations are executed, and that the build is stopped.

Test 4: Verify that everything works without validations or scripts

• ant install.source
• Install one module
• Update Core

Test 5: Behaviour with broken validation and script

• Build a validation and a script which, although can be compiled, crash on execution.
• Execute the validation. The build should stop, and an error should be raised.
• Execute the script. The build should stop, and an error should be raised.