Installing the AMBSS
You need JDK or JRW 1.8 at least to install the application.
The standard application is packaged in a ZIP file called "ambss-distrib-XXX.zip" which is available in the %ADELIWS%\distrib\AdeliaBrokerSubscribersService directory.
Note: A custom application built by the AMBSS application build template is installed according to the same principles (either from a ZIP file or produced TAR file).
The archive content 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 and Pool.properties).
It also contains the "bean-context.xml" file which is used to customize JSON deserialization and the Adelia subscriber configuration file subscribersConf.yml.
- "lib" directory: contains the application binary file ambss-XXX-exec.jar.
- "Samples" directory: contains an example configuration based on an MQTT subscriber (only available in the standard distribution).
In addition, in the case of a custom configuration, the archive may contain sub-directories containing the binaries of the Adelia programs to execute ("lib" and "class" directories by default).
The application can be started in two ways:
- either in an ad hoc way (started from a command interpreter), via ambss.bat / ambss-dev.bat scripts for Windows or ambss.sh / ambss-dev.sh scripts for Unix,
- or as a service (in Windows only), via the ambssService.bat script.
Start options
The (standard or custom) AMBSS starts via ambss.<bat/sh> or ambss-dev.<bat/sh> startup scripts.
The ambss-dev.<bat/sh> script must be used when developing EADELIA programs: it uses the application-dev.yml configuration file.
The ambss.<bat/sh> script must be used in production: it uses the application.yml configuration file.
General information
To display the command line options, run the startup script with the "-h" option (both scripts offer the same options):
Generation directory
Use the "-Dloader.path" to specify one or more directories containing the Adelia programs to execute (Adelia generation directories) or the artifacts of these programs. A directory may be absolute or relative (in this case it is relative to the parent directory of the "bin" directory, which contains the run startup script). The directory separator is "," (comma).
Example: If you have developed an EADELIA program which calls a VA_B program, which uses an Adelia class, and your Adelia environment is configured to generate the EADELIAs in "d:\adeliaGen\event", the VA_B in "d:\adeliaGen\batch" and the classes in "d:\adeliaGen\pojo", you need to run the following command line:
ambss.bat -JVMoptions "-Dloader.path=d:/adeliaGen/event,d:/adeliaGen/batch,d:/adeliaGen/pojo"
Note: This option is used more in development than production. For production, we recommend using the template for building an AMBSS application as this produces a startup script which includes the "-Dloader.path" option with the directory(ies) specified as a build parameter.
Configuring Adelia subscribers
As the ABMSS can operate without an Adelia subscriber configuration file, a file must be taken into account via the command line using the "–ambss.subscribers.configuration" option. We can specify either a URI or a path in the local file system. This path can be absolute or relative (in this case it is relative to the parent directory of the "bin" directory, which contains the run startup script).
Example: To use the subscribersConf.yml file committed in the "extdConfig" sub-directory, you need to run the following command line:
ambss.bat -APPparams "--ambss.subscribers.configuration=./extdConfig/subscribersConf.yml"
Note: This option is used more in development than production. For production, we recommend using the template for building an AMBSS application as this produces a startup script which includes the "--ambss.subscribers.configuration" option.
Spring Boot parameters
Spring Boot parameters can be specified in the command line using the -JVMoptions "-D<parameter_name>=<value>" option.
For example, the listening port of the Spring Boot application itself can be changed via the "-Dserver.port=<port_number>" option, where "port_number" is the HTTP port number defined for the J2EE application. The default value is 8080.
Generally speaking, a Spring Boot property in the command line takes priority over the one defined in the application(-dev).yml file.
You need to use the ambssServicee.bat script to launch the application as a Windows service.
Windows service management
The ambssService.bat script is used to install, uninstall, start and stop the AMBSS application as a Windows service. This script must be run in a DOS command window run as administrator.
To make the service operational, it needs to be installed then started. Run the ambssService.bat command without parameters to see the available options:
- install: Application installation command. It is during this stage that we can specify configuration files other than the default ones.
- start: Application start command,
- stop: Application stop command,
- uninstall: Application uninstall command (with automatic stop of the application before uninstalling).
Pour installer le service AMBSS avec les options exemples ci-dessus, utilisez les options d'installation comme ceci :
ambssService.bat "mon service ambss" -install -JVMoptions "-Dloader.path=d:/adeliaGen/event,d:/adeliaGen/batch,d:/adeliaGen/pojo" -APPparams "--ambss.subscribers.configuration=./extdConfig/subscribersConf.yml"
By default, two logging files (containing the console's output and error logs) called <service name>_out.log and <service name>_err.log are created in the bin sub-directory (containing the ambssService.bat script). ↑ Top of page
Middleware session pool administration
When executing the AMBSS, you can see the pool state of the Middleware sessions used by EADELIA programs. A URL is provided for this purpose: http://<host ambss>:<port ambss>/ambss/PoAdmin. It provides access to the Middleware session pool administration servlet.
Note: This URL is freely accessible when the AMBSS is started with the development profile (ambss-dev.<bat/sh> script), but can only be accessed with a JWT token with the ADMIN role when the AMBSS is started with the production profile (script ambss.<bat/sh>) and JWT authentication is enabled ("ambss.security.enabled" property). ↑ Top of page
Debug Adelia subscribers
An EADELIA program can be debugged. To do this, you need to:
- make sure you generate the program in DEBUG mode,
- start the AMBSS by adding the
"-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000"and"-Dadelia.debuggingsupport"values to theJVMoptionsparameter.
For example:
ambss.bat -JVMoptions "-Dloader.path=d:/adeliaGen/event,d:/adeliaGen/batch,d:/adeliaGen/pojo" "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000""-Dadelia.debuggingsupport" -APPparams "--ambss.subscribers.configuration=./extdConfig/subscribersConf.yml"
For more details on the parameters required for debugging, see the Debugging an Adelia Cloud or AMBSS application page.
To be able to debug a subscriber, it needs to be started so it can have the Adelia debugger attached to it. This means that it is not possible to debug the Adelia code placed in the onStart paragraph, only in onStop, onError and onMessage paragraphs.
In addition, depending on the message broker and message acknowledgment mode, it may be necessary to modify the subscriber parameters relating to message processing timeouts (as debugging the Adelia code increases the paragraph execution time).
Example environment
The BDCADEL environment contains an example EADELIA program (SUBSCRIBE_MQTT program in the EADELIA application area). This program is an MQTT v3 and v5 subscriber.
To test it, an MQTT message broker such as Mosquitto, available in Windows, Mac OS and Linux, is required.
AMBSS configuration
The standard distribution of AMBSS (available in the %ADELIWS%\distrib\AdeliaBrokerSubscribersService directory) contains an example subscriber configuration file which can be used with the SUBSCRIBE_MQTT program in the "sample" file.
The AMBSS needs to be started with the following options:
ambss.bat -JVMoptions "-Dloader.path=d:/adeliaGen/event/classes" -APPparams "–ambss.subscribers.configuration=./samples/subscribersConf_MQTT_sample.yml"
where "d:/adeliaGen/event/classes" is the SUBSCRIBE_MQTT program object generation directory.
Starting the Mosquitto MQTT ecosystem
Before starting the AMBSS, make sure the Mosquitto message broker has been started using the mosquitto.exe executable (see online help). The broker starts on port 1883 by default. In Windows, it needs to be started with Administrator rights (in a command window in Administrator mode for example).
Example: To start the broker in verbose mode:
mosquitto.exe -v
You need to use the mosquitto_pub executable to send a message (see online help).
Examples:
To send an MQTTv3 message on the "ambssTopicTest/topic1" topic to subscribers "subMQTTv3_1" and "subMQTTv3_3":
mosquitto_pub.exe -t ambssTopicTest/topic1 -m "My first message"
To send an MQTTv3 message on the "ambssTopicTest/topic2" topic to subscribers "subMQTTv3_2" and "subMQTTv3_3":
mosquitto_pub.exe -t ambssTopicTest/topic2 -m "My second message"
To send an MQTTv5 message on the "ambssTopicTest/topic3" topic to subscriber "subMQTTv5_1" (message containing user property pairs):
mosquitto_pub.exe -t ambssTopicTest/topic3 -m "My third message" -V mqttv5 -D PUBLISH user-property "userKey1""userValue1" -D PUBLISH user-property "userKey2""userValue2"
Testing REST APIs
These APIs can be tested with the help of a REST client (not provided) like Insomnia or Postman. The samples sub-directory contains two files: ambss-rest-api-mqtt-sample-insomnia-export.yaml (compatible with Insomnia) and ambss-rest-api-mqtt-sample-http-archive-format-export.har (compatible with Postman or any client supporting the "HTTP Archive Format"). These files contain all the REST APIs to test in the MQTT example execution context (subscribersConf_MQTT_sample.yml).