This template is a Gradle project model for building a Web application hosting SOAP Adelia web services in the form of a file in WAR format. This build requires the Adelia objects in this application to be grouped in the form of artifacts generated by an Adelia build project.

Via the Gretty plugin, the template is also used to run the Web application in Tomcat and to run integration tests.

These tests must be defined in another Gradle project.

Creating a SOAP web services build project

The project is created by unzipping the %ADELIWS%\Build\templates\ SOAP web services application.zip file: the obtained 'REST Web services application' directory can be moved and renamed as required.

The Web application build machine and Adelia build machine may be two different machines.

↑ Top of page

Configuring a SOAP web services 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 Web application WAR.

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 main package as a value.

appWarName (optional)

Alphanumeric string representing the name of the produced WAR file.

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

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

pathToAdeliaWebSite (optional)

Root path of the Website created via the Adelia generation parameters interface ("Create/Update site" button) from which a copy of the configuration files will be made to replace the files present in the project by default. This copy will be triggered when the Gradle copyWebappConfigurationFilesFromAdeliaWebsite task is called.

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 Parameters

Gretty is a Gradle plugin used to run Web applications in integrated J2EE servlet containers. Gretty supports version 7, 8 and 9 of Jetty and version 8.5 and 9 of Tomcat.

By default, the exact versions of Tomcat used are 8.5.35 and 9.0.13, but these version numbers can be changed.

Gretty and the execution of the Web application must be configured mainly in the build.gradle file of the project.

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

tomcat9Version (optional)

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

Make sure that the change in version value matches the tomcat9ServletApiVersion parameter value.

tomcat9ServletApiVersion (optional)

Alphanumeric string representing the version number of the Servlet API specification used by the Tomcat implementation defined by tomcat9Version.

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

tomcat85Version (optional)

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

Make sure that the change in version value matches the tomcat85ServletApiVersion parameter value.

tomcat85ServletApiVersion (optional)

Alphanumeric string representing the version number of the Servlet API specification used by the Tomcat implementation defined by tomcat85Version.

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

↑ Top of page

Integration test execution parameters

Integration tests can be executed on the Web application after starting up Tomcat.

These tests must be defined in the form of a Gradle project, which will be executed once the Web application has started. For further details, see the help page relating to building integration tests.

pathToIntegrationTestBuildFile (optional)

Defines the path (absolute or relative in relation to the SOAP web services build project directory) of the build.gradle file which declares the tests to execute.

↑ Top of page

Repository manager settings

Artifact repositories are used during the following phases when executing an SOAP web services build:

• In the WAR file creation phase, the build uses a repository to download (download repository) the artifacts required to build the Web application artifact. These artifacts are:

• the Adelia runtime artifacts required to execute SOAP Adelia web services,

• your own Adelia object artifacts comprising the Web 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 runtime),

  • your own Adelia object artifacts comprising your Web application.  The artifacts are those in the release version if you perform the build of your Web application in the release version.

By default, and for example purposes 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 called "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)

Define 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).

When 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 runtime). These artifacts are only available in the release version,

  • your own Adelia object artifacts comprising your Web application. These artifacts are in snapshot version if you build your own web 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)

Define 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).

When 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 WAR artifact built with a release version.

This repository enables the artifacts to be made available in the final version.

uploadArchivesReleaseRepo.username / uploadArchivesReleaseRepo.password (optional)

Define 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 WAR artifact built with a snapshot version.

This repository enables the artifacts under development to be made available.

uploadArchivesReleaseRepo.username / uploadArchivesReleaseRepo.password (optional)

Define the user profile and password used to connect to the artifact upload repository in the snapshot version.

↑ Top of page

Configuring components of the Web application to build

These components are the Adelia object artifacts generated by the execution of an Adelia build project.

They need to be declared in the SOAP web services build project so they can be added to the produced WAR.

To do this:

• open the build.gradle file with a text editor, then

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

WSSoapJar-type artifacts

These artifacts must be declared by inserting the following instruction:

wsSoapJar 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 WSSoapJar-type artifact with the file name myapp-app_area_1_wssoapjar-1.1.0-SNAPSHOT.jar, enter WSSoapJar group: 'my.company', name: 'myapp-app_area_1_wssoapjar', 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 WSSoapJar-type artifact with the file name prefix_compo_1_wssoapjar-1.1.0-SNAPSHOT.jar, enter wsSoapJar group: 'my.company', name: 'prefix_compo_1_wssoapjar', version: '1.1.0-SNAPSHOT'.

The group value is that of the "groupId" setting of the component which generates the artifact.

WSSoapAar-type artifacts

These artifacts must be declared by inserting the following instruction:

wsSoapAar 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 WSSoapAar-type artifact with the file name myapp-_app_area_2_wssoapaar-1.1.0-SNAPSHOT.aar, enter WSSoapAar group: 'my.company', name: 'myapp-_app_area_2_wssoapaar', 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 WSSoapAar-type artifact with the file name prefix_compo_1_wssoapaar-1.1.0-SNAPSHOT.aar, enter WSSoapAar group: 'my.company', name: 'prefix_compo_1_wssoapaar', version: '1.1.0-SNAPSHOT '.

The group value is that of the "groupId" setting of the component which generates the artifact.

WSSoapRpc-type artifacts

These artifacts must be declared by inserting the following instruction:

wsSoapRpc 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 WSSoapRpc-type artifact with the file name myapp-_app_area_2_wssoaprpc-1.1.0-SNAPSHOT.jar, enter WSSoapRpc group: 'my.company', name: 'myapp-_app_area_2_wssoaprpc', 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 WSSoapRpc-type artifact with the file name prefix_compo_1_wssoaprpc-1.1.0-SNAPSHOT.jar, enter WSSoapRpc group: 'my.company', name: 'prefix_compo_1_wssoaprpc', version: '1.1.0-SNAPSHOT '.

The group value is that of the "groupId" setting of the component which generates the artifact.

XXServer-type artifacts

These artifacts are not part of the produced WAR.

If you need to execute integration tests on a Web application which contains these components, you must deploy them manually before executing them.

↑ Top of page

Configuration files for the Web application to build

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

Some of these files may have been modified by the user in the Web application development phase. The Web application site file modifications therefore need to be propagated to the SOAP web services build project.

This can be carried out either manually or automatically via the Gradle copyWebappConfigurationFilesFromAdeliaWebsite task.

Executing a SOAP web services build project

List of Gradle tasks for SOAP Web services build

copyWebappConfigurationFilesFromAdeliaWebsite

Task copying configuration files (see table 1 above) from an Adelia Web application site.

The site path must be defined by setting a value to the pathToAdeliaWebsite parameter in the gradle.properties file.

All the configuration files in the SOAP web services build project directory are replaced by those in the pathToAdeliaWebsite directory.

This task must be called before the build task.

build

WAR artifact build task. This is placed in the build\libs sub-directory of the build project.

clean

Task used to delete objects created when executing the build task (the build sub-directory is deleted).

appRunWar (Gretty task)

Starts the configured servlet container (Tomcat 9 by default) as well as the Web application. Press a button in the DOS command window which executed this task to stop the servlet container (see http://akhikhl.github.io/gretty-doc/Gretty-tasks.html).

appStartWar (Gretty task)

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

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

farmIntegrationTest (Gretty task)

Triggers the execution of integration tests (if the pathToIntegrationTestBuildFile parameter is entered).

This task is from the Gretty plugin: the configured servlet container (Tomcat 9 by default) is started as well as the Web application, then the integration tests are executed, and finally the servlet container is stopped.

If the WAR artifact does not exist when the farmIntegrationTest task is called, this is created before executing this task.

uploadArchives

This task is used to transfer the built artifact to the upload repository.

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

↑ Top of page