This Gradle project template lets you build a Web application hosting Adelia REST services, in the form of a .WAR file. This building process requires the Adelia objects used in the application to be grouped together in the form of artifacts produced by an Adelia build project.

Additionally, this template can be used to execute the Web application in Tomcat, via the Gretty plugin (https://github.com/akhikhl/gretty), and to execute integration tests.

These tests must be defined in another Gradle project.

Creating a REST web services build project

Create the project by decompressing the file %ADELIWS%\Build\templates\Rest web services application.zip . You can move and rename the resulting web services application REST directory as desired.

The workstation used to build the Web application does not have to be the same as the Adelia build workstation.

↑ Top of page

Configuring a REST web services build project

When you have created a project, you must configure it before it can be executed.

Build projects are configured and initialized based on the settings specified in the gradle.properties file, namely:

General settings

adeliaVersion (mandatory)

String representing the version number of the Adelia runtime included in the WAR file that contains the Web application.

This runtime version must be greater than or equal to the version used to generate the artifacts on the Adelia build workstation.

version (mandatory)

String representing the application's version number. Each built artifact will have the same version number. There are several types of version:

• • Release (or final) versions, representing the application's official versions (e.g.: 1.0.0

  • Snapshot versions, representing versions of the application during development (e.g.: 1.0 = 1-SNAPSHOT

  • Pre-release (or release-candidate) versions, representing potential candidates for final versions (e.g.: 1.0 = 1-RC01

group (mandatory)

String representing the ID of the group or organization initiating the project.

The value obeys the same naming rules as Java packages (for example, com.hardis). The name of the project's top package is generally used.

appWarName (optional)

String representing the name of the generated WAR file.

By default, this file is named <project directory name>-<version parameter value>.war.

If this parameter is specified, the file will be named <appWarName parameter value>-<version parameter value>.war.

jwtProviderSupport (optional)

Add the authentication token management feature based on the JWT technology. This parameter has two alphanumeric values: 'Y' (support added) or 'N' (support non added). The default value is 'Y'.

toolboxDocxToolBx (optional)

Adds the Adelia runtime required to execute DocxToolBx DLL functions to the built application. This manual addition by the user is mandatory when Adelia programs dynamically call these functions (by calling CALL_DLL / CALL_CLASS instructions, where "/", DLLNameorClass and Method_Function parameters are not alphanumeric literals but alphanumeric variables. In the case of a standard call to the DocxToolBx (via CALL_DLL 'DocxToolBx' 'XXX'...), the runtime is added automatically (and this parameter is not taken into account).

This parameter has an alphanumeric value "Y" (runtime add-on) or "N" (no runtime add-on). This parameter is "N" by default.

toolboxXlsxToolBx (optional)

Adds the Adelia runtime required to execute XlsxToolBx DLL functions to the built application. This manual addition by the user is mandatory when Adelia programs dynamically call these functions (by calling CALL_DLL / CALL_CLASS instructions, where "/", DLLNameorClass and Method_Function parameters are not alphanumeric literals but alphanumeric variables. In the case of a standard call to the XlsxToolBx (via CALL_DLL 'XlsxToolBx' 'XXX'...), the runtime is added automatically (and this parameter is not taken into account).

This parameter has an alphanumeric value "Y" (runtime add-on) or "N" (no runtime add-on). This parameter is "N" by default.

toolboxVaToolBxKafka (optional)

Adds the Adelia runtime required to execute VaToolBx DLL Kafka functions to the built application. This manual addition by the user is mandatory when Adelia programs dynamically call these functions (by calling CALL_DLL / CALL_CLASS instructions, where "/", DLLNameorClass and Method_Function parameters are not alphanumeric literals but alphanumeric variables. In the case of a standard call to Kafka functions (via CALL_DLL 'VaToolBx' 'VaToolBxSendToAvroKafkaXXX'...), the runtime is added automatically (and this parameter is not taken into account).

This parameter has an alphanumeric value "Y" (runtime add-on) or "N" (no runtime add-on). This parameter is "N" by default.

toolboxVaToolBxAmqp (optional)

Adds the Adelia runtime required to execute VaToolBx DLL AMQP functions to the built application. This manual addition by the user is mandatory when Adelia programs dynamically call these functions (by calling CALL_DLL / CALL_CLASS instructions, where "/", DLLNameorClass and Method_Function parameters are not alphanumeric literals but alphanumeric variables. In the case of a standard call to AMQP functions (via CALL_DLL 'VaToolBx' 'VaToolBxAMQPXXX XXX'...), the runtime is added automatically (and this parameter is not taken into account).

This parameter has an alphanumeric value "Y" (runtime add-on) or "N" (no runtime add-on). This parameter is "N" by default.

toolboxVaToolBxApe (optional)

Adds the Adelia runtime required to execute VaToolBx DLL Adelia Print Engine functions to the built application. This manual addition by the user is mandatory when Adelia programs dynamically call these functions (by calling CALL_DLL / CALL_CLASS instructions, where "/", DLLNameorClass and Method_Function parameters are not alphanumeric literals but alphanumeric variables. In the case of a standard call to APE functions (via CALL_DLL 'VaToolBx' 'VaToolBxAPEXXX'...), the runtime is added automatically (and this parameter is not taken into account).

This parameter has an alphanumeric value "Y" (runtime add-on) or "N" (no runtime add-on). This parameter is "N" by default.

↑ Top of page

Gretty settings

Gretty (http://akhikhl.github.io/gretty-doc/index.html) is a Gradle plugin that enables Web applications to be executed inside integrated J2EE servlet containers. Gretty supports Jetty (versions 7, 8 and 9) and Tomcat (versions  8.5 and 9).

By default, the precise versions of Tomcat used are 8.5.35 and 9.0.13, but it is possible to change these version numbers.

The task of configuring Gretty (http://akhikhl.github.io/gretty-doc/Gretty-configuration.html) and configuring execution of the Web application must be performed primarily in the project's build.gradle file.

In this template, Tomcat 9 is configured as the servlet container.

tomcat9Version (optional)

String representing the version number of Tomcat 9 to use (https://archive.apache.org/dist/tomcat/tomcat-9/).

Ensure that any changed version value remains consistent with the value of the tomcat9ServletApiVersion parameter.

tomcat9ServletApiVersion (optional)

String representing the version number of the specification for the Servlet API used by the Tomcat implementation defined by tomcat9Version.

This value is given in the table available at the following address: https://tomcat.apache.org/whichversion.html.

tomcat85Version (optional)

String representing the version number of Tomcat 8.5 to use (https://archive.apache.org/dist/tomcat/tomcat-8/).

Ensure that any changed version value remains consistent with the value of the tomcat85ServletApiVersion parameter.

tomcat85ServletApiVersion (optional)

String representing the version number of the specification for the Servlet API used by the Tomcat implementation defined by tomcat85Version.

This value is given in the table available at the following address: https://tomcat.apache.org/whichversion.html.

↑ Top of page

Integration test execution settings

It is possible to execute the integration tests for the Web application after Tomcat has been started.

These tests must be defined in the form of a Gradle project, which will be executed when the Web application has been started. For more details, refer to the Help page on building integration tests.

pathToIntegrationTestBuildFile (optional)

Defines the path (which may be either absolute or relative to the REST web services build project directory) of the build.gradle file that declares the tests to be executed.

↑ Top of page

Repository manager settings

When executing a REST web services build, the artifact repositories are used during the following phases:

• During the WAR file creation phase, the build process uses a repository (the download repository) to download the necessary artifacts to enable the Web application's artifacts to be built, These artifacts are:

• • Adelia runtime artifacts required in order to execute Adelia REST web services,

  • Your own Adelia object artifacts used in the Web application: these artifacts are generated by executing an Adelia build project.

• In the final phase, during which the built artifacts are stored, it is possible to define a repository (the upload repository) to use when transferring these versioned artifacts.
  Depending on the version type (i.e. release or snapshot), the related repository can be defined.

downloadArtifactsReleaseRepo (mandatory)

URL of the download repository for the dependent artifacts required for the build. This repository must enable access to:

• • Artifacts in the Hardis repository (Adelia runtime),

  • Your own Adelia object artifacts used in your Web application.  These artifacts will be a release version if you are building a release version of your Web application.

By default, and for example purposes only, this value's parameter is the URL pointing to the repository supplied by Hardis.

In its place, in your Nexus, you must create your own private repository to group the Hardis repository and your private repository in the release version. Depending how you have configured the Nexus used for your Adelia build projects, this may either be the default repository created by Nexus, named "Releases", or else another "hosted repository" created by you with its "Repository policy" set to Release.

To do this, log in to Nexus, open the "Repositories" view and add the new repository defined as a group of the repositories described above:

• • Open the repository definition screen via the "Add repository group" command,

  • In the "Available Repositories" section, select the private repository used as a proxy of the Hardis repository and the private hosted repository used to store the release version of your artifacts, then add them to the "Ordered Group Repositories" section.

End by replacing the value of the downloadArtifcatsReleaseRepo parameter with the "Repository Path" URL of the newly created group.

downloadArtifactsReleaseRepo.username / downloadArtifactsReleaseRepo.password (optional)

Defines the user profile and password used to log in to the download repository.

By default, and for example purposes only, these login details are those used for the Hardis download repository, but you must replace them with the login details for your own private group repository (cf. downloadArtifactsReleaseRepo above).

As this repository is accessed in read only mode, Nexus allows anonymous connections. If you want to allow anonymous connections, leave the "username" and "password" fields blank.

downloadArtifactsSnapshotRepo (optional)

URL of the download repository for the dependent artifacts required for the build. This repository must enable access to:

• • Artifacts in the Hardis repository (Adelia runtime). These artifacts are only available in a release version,

  • Your own Adelia object artifacts used in your Web application. These artifacts will be a snapshot version if you are building a snapshot version of your Web application.

In your Nexus, you must create your own private repository to group the Hardis repository and your private repository in the snapshot version. Depending how you have configured the Nexus used for your Adelia build projects, this may either be the default repository created by Nexus, named "Snapshots", or else another "hosted repository" created by you with its "Repository policy" set to Snapshot.

To do this, log in to Nexus, open the "Repositories" view and add the new repository defined as a group of the repositories described above:

• • Open the repository definition screen via the "Add repository group" command,

  • In the "Available Repositories" section, select the private repository used as a proxy of the Hardis repository and the private hosted repository used to store the snapshot version of your artifacts, then add them to the "Ordered Group Repositories" section.

End by replacing the value of the downloadArtifcatsSnapshotRepo parameter with the "Repository Path" URL of the newly created group.

downloadArtifactsSnapshotRepo.username / downloadArtifactsSnapshotRepo.password (optional)

Defines the user profile and password used to log in to the download repository. This profile must allow access to your own private group repository (cf. downloadArtifactsSnapshotRepo above).

As this repository is accessed in read only mode, Nexus allows anonymous connections. If you want to allow anonymous connections, leave the "username" and "password" fields blank.

uploadArchivesReleaseRepo (optional)

URL of the upload repository used to store WAR artifacts built with a release version.

This repository will enable artifacts to be provided in the final version.

uploadArchivesReleaseRepo.username / uploadArchivesReleaseRepo.password (optional)

Defines the user profile and password used to log in to the upload repository for the release version of artifacts.

uploadArchivesSnapshotRepo (optional)

URL of the upload repository used to store WAR artifacts built with a snapshot version.

This repository will enable artifacts to be provided during development.

uploadArchivesReleaseRepo.username / uploadArchivesReleaseRepo.password (optional)

Defines the user profile and password used to log in to the upload repository for the snapshot version of artifacts.

↑ Top of page

Configuring the components of the Web application to be built

These are Adelia object artifacts generated by executing an Adelia build project.

They must be declared in the REST web services project in order for them to be added to the generated WAR file.

To do this:

• Open the build.gradle file in a text editor and then

• declare your artifacts in the "dependencies" section (Declare your artifacts needed to build the web application here).

Pojo artifacts

These artifacts must be declared by inserting the following instruction:

runtimeOnly group: '<artifact group name>', name: '<artifact file name without the version>', version: '<artifact version number>'

Example of artifact declaration from a build by application area:

For the Pojo artifact with the file name myapp-app_area_1_pojo-1.1.0-SNAPSHOT.jar, you must enter runtimeOnly group: 'my.company', name: 'myapp-app_area_1_pojo', version: '1.1.0-SNAPSHOT'.

The group value is the value of the "group" parameter in the gradle.properties file of the Adelia build project that built the artifact.

Example of artifact declaration from a build by component:

For the Pojo artifact artifact with the file prefix_compo_1_pojo-1.1.0-SNAPSHOT.jar, you must enter runtimeOnly group: 'my.company', name : 'prefix_compo_1_pojo', version: '1.1.0-SNAPSHOT'.

The group value is the value of the "groupId" parameter of the component from which the artifact is produced.

WSRest artifacts

These artifacts must be declared by inserting the following instruction:

runtimeOnly group: '<artifact group name>', name: '<artifact file name without the version>', version: '<artifact version number>'

Example of artifact declaration from a build by application area:

For the WSRest artifact with the file name myapp-_app_area_2_wsrest-1.1.0-SNAPSHOT.zip, you must enter runtimeOnly group: 'my.company', name: 'myapp-_app_area_2_wsrest', version: '1.1.0-SNAPSHOT'.

The group value is the value of the "group" parameter in the gradle.properties file of the Adelia build project that built the artifact.

Example of artifact declaration from a build by component:

For the WSRest artifact artifact with the file prefix_compo_1_wsrest-1.1.0-SNAPSHOT.zip, you must enter runtimeOnly group: 'my.company', name : 'prefix_compo_1_wsrest', version: '1.1.0-SNAPSHOT '.

The group value is the value of the "groupId" parameter of the component from which the artifact is produced.

XXServer artifacts

These artifacts are not included in the generated WAR file.

If you need to execute integration tests on a Web application containing such components, you must deploy them manually prior to execution.

↑ Top of page

Setup files for the Web application to be built

By default, a number of configuration files are supplied with this template. These files are described in the following table:

Some of these files may have been modified by the user during development of the Web application. The modifications in the files must therefore be propagated from the Web application site to the REST web services build project files.

They may be propagated either manually or automatically, via the Gradle task named copyWebappConfigurationFilesFromAdeliaWebsite.

Executing a REST web services build project

List of Gradle tasks for the REST web services build

copyWebappConfigurationFilesFromAdeliaWebsite

This task copies the configuration files (cf. table 1 above) from an Adelia Web application site.

The site's path must be defined by specifying the pathToAdeliaWebsite parameter in the gradle.properties file.

All configuration files in the REST web services build project directory are replaced by their counterparts located in the pathToAdeliaWebsite directory.

This task must be called before the build task

build

This task builds the WAR artifact. The artifact is placed in the build project's build\libs subdirectory.

clean

This task is used to delete the objects created while the build task is executed (the build subdirectory is deleted).

appRunWar (Gretty task)

Starts the configured servlet container (Tomcat 9 by default) and the Web application. To stop the servlet container, press any key in the DOS command window that executed this task (cf. http://akhikhl.github.io/gretty-doc/Gretty-tasks.html).

appStartWar (Gretty task)

Starts the configured servlet container (Tomcat 9 by default) and the Web application.

In this case, the appStop task must be executed to stop the servlet container (cf. http://akhikhl.github.io/gretty-doc/Gretty-tasks.html).

farmIntegrationTest (Gretty task)

Triggers execution of the integration tests (if the pathToIntegrationTestBuildFile parameter has been specified).

This task is from the Gretty plugin: the specified servlet container (Tomcat 9, by default) is started, together with the Web application. The integration tests are then executed and lastly, the servlet container is stopped.

If the WAR artifact does not already exist when the farmIntegrationTest task is called, it is created before the task is executed.

uploadArchives

This task transfers the built artifact to the upload repository.

You must specify the uploadArchivesReleaseRepo or uploadArchivesSnapshotRepo key, depending on the version type of the artifact.

↑ Top of page