Converting Java DXA Webapp to Spring Boot APP

In this article, I would like to present the steps for converting the Java DXA (v2.2.1) application into a Spring Boot application.

Executable Artifact

As stated in Spring Boot’s documentation (https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-jsp-limitations), when running a Spring Boot application that uses an embedded servlet container (and is packaged as an executable archive), there are some limitations in the JSP support. The recommended approach is to build the solution as an executable WAR file, which can be launched with java -jar just like a normal jar executable.

Spring Boot dependencies

I have utilized an alternative to the starter spring-boot-starter-parent project since many implementations have a custom Maven parent. It is still possible to benefit from the spring-boot-starter-parent project's dependency tree by adding a dependency spring-boot-dependencies into our project in import scope.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-dependencies</artifactId>
  <version>1.5.21.RELEASE</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

The chosen Spring Boot version (1.5.21.RELEASE) automatically provides all the Spring dependencies in the version (v4.3.24.RELEASE) required by the DXA 2.2.1 framework. This way no other Spring Framework dependencies are needed in the Maven pom file.

The other required Spring Boot dependencies are:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
  <version>1.5.21.RELEASE</version>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-tomcat</artifactId>
  <version>1.5.21.RELEASE</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>org.apache.tomcat.embed</groupId>
  <artifactId>tomcat-embed-jasper</artifactId>
  <version>8.5.40</version>
  <scope>provided</scope>
</dependency>

The spring-boot-starter-tomcat and tomcat-embed-jasper dependencies are added to enable running the built executable WAR file inside an embedded Tomcat application server.

The spring-boot-maven-plugin is utilized to repackage the standard WAR build into an executable WAR file.

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <version>1.5.21.RELEASE</version>
  <configuration>
    <executable>true</executable>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>repackage</goal>
      </goals>
      <configuration>
        <classifier>spring-boot</classifier>
        <mainClass>com.sdl.webapp.main.WebAppInitializer</mainClass>
      </configuration>
    </execution>
  </executions>
</plugin>

A full pom example can be viewed here.

Initializing the Application

The WebAppInitializer class is the starting point of the Spring Boot application.

package com.sdl.webapp.main;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class WebAppInitializer {
  public static void main(String[] args) {
    SpringApplication.run(WebAppInitializer.class, args);
  }
}

This class is annotated with @SpringBootApplication, which among other things, tells Spring to look for other components, configurations and services inside the same package. Therefore, I placed the SpringInitializer class inside the same package annotated with @Import(DxaSpringInitialization.class) in order to kick off the DXA initialization process.

package com.sdl.webapp.main;

import com.sdl.dxa.DxaSpringInitialization;

import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;

@Import(DxaSpringInitialization.class)
@Configuration
public class SpringInitializer {
}

Application Properties

The spring.profiles.active property had to be moved from the dxa.properties file into Spring Boot's application.properties file.

Here are the contents of the application.properties file.

logging.config=classpath:logback.xml
spring.profiles.active=cil.providers.active,search.solr

Deploying the Application

The built executable WAR file is deployed from the command-line using:

java -jar dxaSpringBoot-2.2.1-spring-boot.war

The DXA application is started inside an embedded Tomcat application server.

Resources

For completeness, the supporting code and property extracts can be found here.