This template is a Gradle project model for building an Adelia Message Broker Subscriber Service application in the form of a file in ZIP and/or TAR format (Unix archive format).
This build can take into account the Adelia objects of EADELIA programs needed to execute Adelia subscribers.
Creating an Adelia AMBSS build project
The project is created by decompressing the %ADELIWS%\Build\templates\ambss application.zip file: the obtained "ambss application" directory can be moved and renamed as required.
The Adelia AMBSS application machine and Adelia build machine may be two different machines.
Configuring an Adelia AMBSS build project
After creating a project, it needs to be configured before it can be executed. Build project configuration and initialization are based on the settings entered in the gradle.properties file, namely:
General settings
adeliaVersion (mandatory)
Alphanumeric string representing the version number of the Adelia runtime included in the Adelia AMBSS application ZIP/TAR.
This runtime version must be higher than or equal to the one used by the Adelia build machine to generate artifacts.
version (mandatory)
Alphanumeric string representing the application version number. Each artifact built will have the same version number. There are several version types:
The release (or final) versions representing the official versions of the application (e.g. 1.0.0).
The snapshot (or instantaneous) versions representing the versions of the application that are under development (e.g. 1.0.1-SNAPSHOT).
The pre-release (or release-candidate) versions representing the versions which are candidates for being final versions (e.g. 1.0.1-RC01).
group (mandatory)
Alphanumeric string representing the identifier of the group or organization instigating the project. The value follows the same naming rules as the Java packages (e.g. com.hardis) and we generally choose the name of the project's top package as a value.
AMBSS application parameters
ambssAppName (optional)
Alphanumeric string representing the name of the produced ZIP/ TAR file. By default, the name of this file is <project directory name>-<version parameter value>.< zip/tar.
If this parameter is entered, the file name will be <ambssAppName parameter value>-<version parameter value>.< zip/tar.
Note:
If the artifact produced when running the build needs to be published in a repository (using publishXXX publication tasks), the value of this parameter must not contain space characters.
addApplicationYamlFiles (optional)
Adds Spring boot YAML configuration files src/main/ambss/config/application.yml and src/main/ambss/config/application-dev.yml to the application. These files are in the config sub-directory of the built archive. This parameter has an alphanumeric 'Y' value (files added) or "N" value (no files added). This parameter is "Y" by default.
addSubscribersConfigurationYamlFile (optional)
Adds the src/main/ambss/extdConfig/subscribersConf.yml file to the application. This file is in the extdConfig sub-directory of the built archive. This parameter has an alphanumeric 'Y' value (file added) or "N" value (no file added). This parameter is "Y" by default.
nonEmbeddedAdeliaPgmsCompo.defaultDir (optional)
Default sub-directory for storing Adelia object artifacts (from an Adelia build of EADELIA, VA_B programs, Adelia classes) defined by a nonEmbeddedAdeliaPgmsCompo Gradle dependency. The sub-directory relates to the root of the built archive. This parameter has an alphanumeric value. This parameter is "lib" by default.
nonEmbeddedAdeliaPgmsClass.defaultDir (optional)
Default sub-directory for storing Adelia objects (from an EADELIA, VA_B program, Adelia class generation) defined by a nonEmbeddedAdeliaPgmsClass Gradle dependency (this dependency is used to defined a source directory). The sub-directory relates to the root of the built archive. This parameter has an alphanumeric value. This parameter is "class" by default.
ambssBrokers (mandatory)
List of target brokers.
Repository manager settings
Artifact repositories are used during the following phases when executing an Adelia AMBSS build:
In the ZIP/TAR file creation phase, the build uses a repository to download (download repository) the artifacts required to build the AMBSS application artifact. These artifacts are:
the Adelia runtime artifacts required to execute an Adelia AMBSS application,
your own Adelia object artifacts comprising the AMBSS application: these are generated by the execution of an Adelia build project.
In the final storage phase for the built artifact, a repository (upload repository) can be defined to transfer this versioned artifact. According to the version type (release or snapshot), the associated repository can be defined.
downloadArtifactsReleaseRepo (mandatory)
Access URL to the download repository of the dependent artifacts needed for the build. This repository should make it possible to access:
Hardis repository artifacts (Adelia AMBSS runtime),
your own Adelia object artifacts comprising your AMBSS application. These artifacts are in release version if you build your AMBSS application in the release version.
By default, and by way of example only, the value of this parameter is the URL of the repository provided by Hardis.
In its place, in your Nexus, you need to create your own private repository so the Hardis repository and your private repository are grouped together in the release version. Depending on your own Nexus configuration used for your Adelia build projects, it is either the repository created by default by Nexus and Releases", or another "hosted repository" with a "Repository policy" set to Release and created by you).
To do this, after logging in to Nexus, in the "Repositories" view, add a new repository defined as a group of repositories described above:
- Open the repository definition window via the "Add repository group" command,
- From the "Available Repositories" section, add, in the "Ordered Group Repositories" section, the private repository which is a proxy of the Hardis repository as well as the private "hosted" repository used to store your artifacts in release version.
To finish, replace the downloadArtifactsReleaseRepo parameter value with the "Repository Path" URL of the newly created group repository.
downloadArtifactsReleaseRepo.username / downloadArtifactsReleaseRepo.password (optional)
Defines the user profile and password used to connect to the download repository.
By default, and by way of example, these identifiers are those of the Hardis download repository but they need to be replaced by those of your own group private repository (see "downloadArtifactsReleaseRepo" above). As you access this repository in read-only mode, Nexus authorizes an anonymous connection: in this case, leave the "username" and "password" fields blank.
downloadArtifactsSnapshotRepo (optional)
Access URL to the download repository of the dependent artifacts needed for the build. This repository should make it possible to access:
Hardis repository artifacts (Adelia AMBSS runtime). These artifacts are only available in release version.
your own Adelia object artifacts comprising your AMBSS application. These artifacts are in snapshot version if you build your own AMBSS application in snapshot version.
In your Nexus, you need to create your own private repository so the Hardis repository and your private repository are grouped together in the snapshot version. Depending on your own Nexus configuration used for your Adelia build projects, it is either the repository created by default by Nexus and called "Snapshots", or another "hosted repository" with a "Repository policy" set to Snapshot and created by you).
To do this, after logging in to Nexus, in the "Repositories" view, add a new repository defined as a group of repositories described above:
Open the repository definition window via the "Add repository group" command,
From the "Available Repositories" section, add, in the "Ordered Group Repositories" section, the private repository which is a proxy of the Hardis repository as well as the private "hosted repository" used to store your artifacts in snapshot version.
To finish, replace the downloadArtifactsSnapshotRepo parameter value with the "Repository Path" URL of the newly created group repository.
downloadArtifactsSnapshotRepo.username / downloadArtifactsSnapshotRepo.password (optional)
Defines the user profile and password used to connect to the download repository. This profile should enable you to access your own private group repository (see "downloadArtifactsSnapshotRepo" above). As you access this repository in read-only mode, Nexus authorizes an anonymous connection: in this case, leave the "username" and "password" fields blank.
uploadArchivesReleaseRepo (optional)
Access URL to the upload repository used to store the ZIP / TAR artifact built with a release version. This repository enables the artifacts to be made available in the final version.
uploadArchivesReleaseRepo.username / uploadArchivesReleaseRepo.password (optional)
Defines the user profile and password used to connect to the artifact upload repository in the release version.
uploadArchivesSnapshotRepo (optional)
Access URL to the upload repository used to store the ZIP / TAR artifact built with a snapshot version. This repository enables the artifacts under development to be made available.
uploadArchivesReleaseRepo.username / uploadArchivesReleaseRepo.password (optional)
Defines the user profile and password used to connect to the artifact upload repository in the snapshot version.
Configuring the components of the Adelia AMBSS application to build
These components are Adelia object artifacts generated by the execution of an Adelia build project, or Adelia objects resulting from an interactive generation.
They need to be declared in the Adelia AMBSS build project so they can be added to the produced ZIP/TAR.
To do this:
open the build.gradle file with a text editor, then,
in the "dependencies" section (Declare your artifacts needed to build the AMBSS application here), declare your artifacts.
Embedded artifacts
An embedded artifact is included directly in the binary of the build AMBSS application (bin/ambss-XXX-exec.jar JAR file in the produced archive).
These artifacts must be declared by inserting the following instruction:
embeddedAdeliaPgmsCompo group: '<artifact group name>', name: '<artifact file name without version>', version: '<artifact version number>'
Example of declaration of artifact generated by an application area-based build:
For the Event-type artifact with the file name myapp-app_area_1_event-1.1.0-SNAPSHOT.jar, enter embeddedAdeliaPgmsCompo group:'my.company', name: 'myapp-app_area_1_event', version: '1.1.0-SNAPSHOT'.
The group value is that of the "group" setting in the gradle.properties file of the Adelia build project which built the artifact.
Example of declaration of artifact generated by a component-based build:
For the Event-type artifact with the file name prefix_compo_1_event-1.1.0-SNAPSHOT.jar, enter embeddedAdeliaPgmsCompo group:'my.company', name: 'prefix_compo_1_event', version: '1.1.0-SNAPSHOT'.
The group value is that of the "groupId" setting of the component which generates the artifact.
Non-embedded artifacts
A non-embedded artifact is included in a sub-directory of the produced archive (the default sub-directory is the value of the nonEmbeddedAdeliaPgmsCompo.defaultDir property, or "lib" if it is not entered).
These artifacts must be declared by inserting the following instruction:
nonEmbeddedAdeliaPgmsCompo group: '<artifact group name>', name: '<artifact file name without version>', version: '<artifact version number>'
A destination sub-directory of the declared artifacts can be forced by inserting the following instruction:
nonEmbeddedAdeliaPgmsCompo (group: '<artifact group name>', name: '<artifact file name without version>', version: '<artifact version number>') {ext.destinationDir = 'mySubDirForJar'
}
Example of declaration of artifact generated by an application area-based build:
For the Event-type artifact with the file name myapp-app_area_1_event-1.1.0-SNAPSHOT.jar, enter nonEmbeddedAdeliaPgmsCompo group:'my.company', name: 'myapp-app_area_1_event', version: '1.1.0-SNAPSHOT'.
The group value is that of the "group" setting in the gradle.properties file of the Adelia build project which built the artifact.
Example of declaration of artifact generated by a component-based build to the 'adeliaCompo' sub-directory:
For the Event-type artifact with the file name prefix_compo_1_event-1.1.0-SNAPSHOT.jar, enter :
nonEmbeddedAdeliaPgmsCompo (group:'my.company', name : 'prefix_compo_1_event', version: '1.1.0-SNAPSHOT') {
ext.destinationDir = 'adeliaCompo'
}
The group value is that of the "groupId" setting of the component which generates the artifact.
Adelia objects
To package Adelia objects resulting from an interactive generation in the built archive, the following instruction needs to be inserted:
nonEmbeddedAdeliaPgmsClass fileTree('<Adelia objects generation path>')The path can be absolute (e.g. 'C:/my/java/classes/generation/directory') or relative in relation to the Gradle build project directory (e.g. './my/java/classes/generation/subDirectory') .
All the objects contained in this directory (as well as the sub-directories) will be copied into a sub-directory of the produced archive (the default sub-directory is the value of the nonEmbeddedAdeliaPgmsClass.defaultDir property, or "class" if it is not entered).
A destination sub-directory of the declared objects can be forced by inserting the following instruction:
nonEmbeddedAdeliaPgmsClass (fileTree('<Adelia objects generation path>')) {ext.destinationDir = 'mySubDirForClasses'
}
Configuration files for the Adelia AMBSS application to build
By default, a number of configuration files are delivered with this template. These files are described in the following table:
File name |
Path in built archive |
Path in the Adelia AMBSS build project |
Comment |
| application.yml | <ZIP/TAR>\config\application.yml | <AMBSS build project>\src\main\ambss\config\application.yml | According to the addApplicationYamlFiles property value |
| application-dev.yml | <ZIP/TAR>\config\application-dev.yml | <AMBSS build project>\src\main\ambss\config\application-dev.yml | According to the addApplicationYamlFiles property value |
| beans-context.xml | <ZIP/TAR>\extdConfig\beans-context.xml | <AMBSS build project>\src\main\ambss\extdConfig\beans-context.xml | |
| subscribersConf.yml | <ZIP/TAR>\extdConfig\subscribersConf.yml | <AMBSS build project>\src\main\ambss\extdConfig\subscribersConf.yml | According to the addSubscribersConfigurationYamlFile property value |
CfgConfiguration.properties |
<ZIP/TAR>\extdConfig\CfgConfiguration.properties |
<AMBSS build project>\src\main\ambss\extdConfig\CfgConfiguration.properties |
|
wagon.key |
<ZIP/TAR>\extdConfig\wagon.key |
<AMBSS build project>\src\main\ambss\extdConfig\wagon.key |
|
wagon.xml |
<ZIP/TAR>\extdConfig\wagon.xml |
<AMBSS build project>\src\main\ambss\extdConfig\wagon.xml |
|
wicfgvla.ini |
<ZIP/TAR>\extdConfig\wicfgvla.ini |
<AMBSS build project>\src\main\ambss\extdConfig\wicfgvla.ini |
|
| Pool.properties | <ZIP/TAR>\extdConfig\Pool.properties | <AMBSS build project>\src\main\ambss\extdConfig\Pool.properties | In addition to this default configuration file, you can add your own pool files called poolSession_<poolName>.properties |
↑ Top of page
Executing an Adelia AMBSS build project
List of Gradle tasks for Adelia AMBSS build
build
ZIP and TAR artifact build task These are placed in the build\distributions sub-directory of the build project.
distZip
ZIP artifact build task only. This is placed in the build\distributions sub-directory of the build project.
distTar
TAR artifact build task only. This is placed in the build\distributions sub-directory of the build project.
clean
Task used to delete objects created when executing the build task (the build sub-directory is deleted).
publish
This task is used to transfer the built artifact(s) to the upload repository.
You must specify the uploadArchivesReleaseRepo or uploadArchivesSnapshotRepo key, depending on the artifact version type.
Note:
This task can cause an error if the ambssAppName property is entered and contains space characters or if it is not entered but the project directory name ("ambss application" by default) contains space characters.
publishToMavenLocal
This task is used to move the built artifacts to the machine's local Maven repository (%USERPROFILE%\.m2 directory).
Note:
This task can cause an error if the ambssAppName property is entered and contains space characters or if it is not entered but the project directory name ("ambss application" by default) contains space characters. ↑ Top of page
Structure of produced archive
The two custom ZIP and TAR archives have the same structure, which is as follows:
- bin directory: contains the scripts for starting the application,
- config directory: contains the application.yml and application-dev.yml configuration files used to externalize the configuration of the Spring Boot Adelia Message Broker Subscriber Service application (log level, listening port, etc.) as well as the AMBSS runtime configuration,
extdConfig directory: contains the Adelia runtime configuration files (wagon.xml, wagon.key, CfgConfiguration.properties, wicfgvla.ini, Pool.properties and any poolSession_<nomPool>.properties).
It also contains the bean-context.xml file which is used to customize JSON deserialization and the Adelia subscriber configuration file subscribersConf.yml,
- b directory: contains the application binary ambss-XXX-exec.jar.
In addition, according to the dependencies configuration, the archive may contain sub-directories containing the binaries of the Adelia programs to execute ("lib" and "class" directories by default).
Startup scripts
Unlike a standard distribution (available in the %ADELIWS%\distrib\AdeliaBrokerSubscribersService directory), the startup scripts in the "bin" ambss.<bat/sh> and ambss-dev.<bat/sh> sub-directory were customized:
- the -Dloader.path= option was set with the values of the sub-directories associated with the (Adelia object) dependencies defined in the build.gradle file,
- the -ambss.subscribers.configuration= option was set with the subscribersConf.yml file path if the addSubscribersConfigurationYamlFile property was set to "Y".
Therefore, these options do not need to be called in the command line of these scripts. ↑ Top of page