Hotswap for OpenLMIS microservice.

This manual shows how to implement the functionality of runtime class redefinition using Dynamic Code Evolution Virtual Machine (DCEVM) and Hotswap Agent in the OpenLMIS application.

This allows the user to make quick changes such as adding and modifying methods, fields, adding new classes and reloading the configuration of frameworks (e.g. changing the 'path' for @RequestMapping).

To provide hot reload functionality for the openlmis microservice, follow these steps:

1. In the Dockerfile in a specific microservice (e.g. stockmanagement), change the service-base version to v6.1-dcevm.

FROM openlmis/service-base:6.1-dcevm

2. Add the hotswap-agent.properties file to the resources folder containing the following properties:
   autoHotswap=true
   extraClasspath=${extra.class.path}
   disabledPlugins=${disabled.plugins}

   

3. Build a docker image of the microservice (use commands:
   docker-compose -f docker-compose.builder.yml run builder and
   docker-compose -f docker-compose.builder.yml build image).

4. In the docker-compose.yml file in ref-distro, add the following properties for the microservice:

     environment:
       JAVA_OPTS: "-XXaltjvm=dcevm -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=n -Ddisabled.plugins=Proxy
       -javaagent:/opt/hotswap-agent/hotswap-agent.jar=autoHotswap=true -Dextra.class.path=/extra_class_path"
     volumes:
       - (APP_PATH)/build/classes/java/main:/extra_class_path

   *(APP_PATH) is the path to the application on your system. For example:

   

5. Start the application (run: docker-compose -f docker-compose.yml up --build --remove-orphans --force-recreate command or start-local.sh)

After making changes to the code, use the command:
docker-compose -f docker-compose.builder.yml run builder
to trigger HotSwapAgent and deliver changes to the running container.

Hint:
As the builder process can be very time-consuming because it contains a lot of tasks to perform, we can minimize this time by modifying the build.sh file so that it only performs the compileJava task, e.g.:

We can also customize the process in any way in terms of the steps to be performed, e.g. to omit unit and integration tests, we can exclude them through the following options: -x test -x integrationTest