02. Basics

In this page we describe the basics of a SCD4J project

The Project Structure

Every SCD4J project has the following structure:

build.gradle
modules/
       example-module1/..
       example-module2/..
config/
       example-development.conf
       example-testing.conf
       example-staging.conf
       example-production.conf

The file build.gradle is where you must configure your project. For example:

plugins {
  id "com.datamaio.scd4j" version "PUT_HERE_THE_LATEST_SCD4J_VERSION"
}

scd4j {
	install {
		modules "example-module1", "example-module2"
		config "example-staging.conf"		
	}
}

The modules configuration represents the modules you want to install. Each provided entry must be a directory inside of modules/ folder.

The config configuration must contains the properties file that you would like to use during the installation (the provided file must exists in the directory config/). These properties files are used mainly to differentiate environments. For example, the user name and the password of a database will be different from staging to production. In order to ensure the correct installation in each stage you will need to have, at least, one config file for each environment.

It is important to say that there is only one required property in this file. If you do not provide it, development is assumed.

######## Required Property ###########
# Must contain one of the following: #
#    - development                   #
#    - testing                       #
#    - staging                       #
#    - production                    #
###################################### 
env=development

This is super important to tell SCD4J in which environment your running. In order to avoid running a development configuration against a production environment, for example, check the session Defining environments in Packaging and Distribution.

A Module

A module is directory inside of modules folder. Each module has the following structure:

Module.hook (optional)
opt/
    scd4j/
         examples/              
                 file_2_delete.txt.del
                 file_2_resolve_template.txt.tmpl
         file_2_copy.txt

A module should contain, optionally, a Module.hook file (where you should implement pre and post module scripts) and the files you would like to copy or delete in the operational system (OS). Note that the files must be exactly in the same directory structure they are in the OS. For example, looking at the above module content we are installing a file called file_2_copy.txt in the folder /opt/scd4j/examples/.

The files you want to copy during the installation have the simplest config ever. It is enough to put them in the right directory inside of a module (take a look at file file_2_copy.txt). However, frequently it is required that a file be modified during the installation. This is the case of database's user name and password we mentioned before. In those cases, it is necessary to provide the extension .tmpl to such file (for example, file file_2_resolve_template.txt.tmpl). Doing that, SCD4J will resolve the template before coping the resultant file to the destination folder.

By default, files which end up with .tmpl are actually Groovy Templates. But if you are not happy with this engine, you can pick another one. For more details, take a look at Advanced Features

To finish, if you want to delete a file from the operational system, you must put the file in the right directory inside of a module and append .del at the end of its name. This is required to tell to SCD4J to delete such file. Take file_2_delete.txt.del as an example. We are actually deleting the file /opt/scd4j/examples/file_2_delete.txt

The Module.hook file

Although this file is not mandatory, in any slightly complex installation you will be required to implement it. Every Module.hook file have the following structure:

pre {
    ...
}		
post {
    ...
}

A Module.hook is a groovy script in which you can define pre and post implementations. It is important to say that the pre definition must return a constant CONTINUE or ABORT. If nothing is returned CONTINUE is assumed. Take the bellow code as an example:

pre {
    if( isLinux() ) {
        return CONTINUE
    }
    return ABORT
}

The above example is saying that the module will be executed only on Linux boxes. If you run this module against any other operational system the installation will be aborted.

SCD4J provides many helper functions which can be used in Module.hook file. Those functions are related to set/get properties, install a package, change file permissions and so one. To have a complete understanding of which helpers can be used, take a look at ModuleHook public API.

File Hooks

Similarly to a module that may or may not contain a Module.hook file, each file being copied or deleted may or may not contain a file hook. The difference here is that a file hook must be put in the same directory of the file being hooked. Moreover, it must have the same file name appending .hook at the end. For example:

Module.hook
opt/
    scd4j/
         examples/              
                 file_2_delete.txt.del
                 file_2_delete.txt.del.hook
                 file_2_resolve_template.txt.tmpl
                 file_2_resolve_template.txt.tmpl.hook
         file_2_copy.txt
         file_2_copy.txt.hook

We have used the same example we used before, only adding a hook for every existing file. The content of a file hook is similar to the Module.hook file. But, it is important to say that besides continue or abort the entire installation the pre definition, in a file hook, can return SKIP_FILE. Moreover, the helper functions are slightly different. To have a complete understanding of all of them take a look at FileHook public API.

A note about Hooks pre definition return

Any return that differentiate from the constants below will be considered as CONTINUE. It includes, providing no return at all.

• Module.hook : CONTINUE or ABORT
• FILENAME.hook : CONTINUE, ABORT or SKIP_FILE