You are viewing the documentation for Blueriq 14. Documentation for other versions is available in our documentation directory.

The purpose of this guide is to provide a basic action plan for migrating your custom webapp to release 10.0. This guide will not cover every aspect of the migration as this will differ from customer to customer, but rather provide pointers for the situations that most customers will encounter.

With release 10.0, the Runtime completely relies on Spring Boot. Also, the Runtime now adheres to the Servlet 3.0 specification, which makes it possible to run without a web.xml. All the configuration of the Runtime is now Java configuration instead of XML configuration.

When you migrate your custom webapp, you need to migrate your web.xml to Java configuration. It is advised to also migrate your Spring XML configuration to Java configuration. This will help you in developing faster on your platform, as well as minimize the effort for future migrations.

Table of contents

1 Import required dependencies

You start largely the same as if you would setup an entirely new project, as described in Setup development environment. You need to configure a connection to the artifactory and also need the Projectstarter contents for your application server from the release zip.

Instead of using the Projectstarter POM, you need to change your custom POM file. You need to import the parent POM of the application server that you are targeting as a Bill of Materials in your custom POM. Below is an example for Tomcat, taken from the pom.xml in the Tomcat Projectstarter. Place this in your custom pom.xml. This will ensure that all required dependencies will be pulled in.

pom.xml
<dependencyManagement>
	<dependencies>
		<dependency>
			<groupId>com.blueriq</groupId>
			<artifactId>blueriq-runtime-tomcat-parent</artifactId>
			<version>${com.blueriq.version}</version>
			<scope>import</scope>
			<type>pom</type>
		</dependency>
	</dependencies>
</dependencyManagement>

<dependencies>
	<dependency>
		<groupId>javax.servlet</groupId>
		<artifactId>javax.servlet-api</artifactId>
		<scope>provided</scope>
	</dependency>
 
	<!-- Project specific third-party dependencies -->
	<!--
		Add dependencies here 
	-->
 
	<!-- Spring dependencies -->
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot</artifactId>
	</dependency>

	<!-- Blueriq dependencies -->
	<dependency>
		<groupId>com.blueriq</groupId>
		<artifactId>blueriq-runtime</artifactId>
	</dependency>

	<!-- Dependency to create Blueriq war-file -->
	<dependency>
		<groupId>com.blueriq</groupId>
		<artifactId>blueriq-runtime-boot-starter</artifactId>
	</dependency>
</dependencies>
 
 

You also need the resources and webapp specific resources from the Projectstarter in your webapp.

2 Update Blueriq dependencies

If you depend on artifacts from previous Blueriq releases, update them as described in changes to runtime artifacts and changes to plugin artifacts.

You need to check all your other dependencies as well to see if they are still necessary, need to be upgraded etc.

Once you have updated all your artifacts, you probably will see some compile errors. Some packages in Blueriq have been renamed and/or moved. See the R10.0 API changes for a complete overview of all the changes.

3 Update properties

A lot of properties changed or have been added. Use the property conversion script to migrate all the properties to the new structure.

4 Bootstrap your webapp

Once you have all the dependencies in order, you need to bootstrap your webapp with all the Spring magic for everything to work. Assuming that you build a WAR, you can start with this:

WarApplication.java
import com.example.config.CustomConfig;
import com.aquima.web.boot.RootConfig;

public class WarApplication extends AbstractWarApplication {

  @Override
  protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
	// first initialize the Blueriq configuration, than load your custom configuration
    return RootConfig.configure(application).sources(CustomConfig.class);
  }  
}

Note that the application is bootstrapped with the Blueriq configuration (RootConfig), as wel as your custom configuration (CustomConfig), which is detailed in the next section.

5 Move your custom configuration to Java

The CustomConfig class is below. This class contains the custom configuration that you previously had defined in XML. So it contains component scanning for your custom controllers/services/containers and defines custom beans used in your application.

Note that in this example it implements ServletContextAware, to be able to use the ServletContext in your custom beans. If that is not necessary, you can leave it out.

CustomConfig.java
package com.example.config;

import javax.servlet.ServletContext;

import org.springframework.web.context.ServletContextAware;

@ComponentScan(basePackages = { "com.example.config", "com.example.controller", "com.example.feature" })
public class CustomConfig implements ServletContextAware {
	
  private ServletContext servletContext;

  @Override
  public void setServletContext(ServletContext servletContext) {
    this.servletContext = servletContext;
  }
  
  // add your custom beans here
}

Preferably all XML configuration is migrated to Java configuration. You can start by importing your XML configuration in the Java configuration, using:

@ImportResource({"classpath:custom-config.xml"})

From there on you can move your XML configuration to the Java config class.

6 Spring security

Below is an example of a Spring Security configuration that overrides the defaults from Blueriq. Note that the defaults are still applied where they are not overridden.

CustomWebSecurityConfigurer.java
package com.example.config

import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
@Order(Ordered.HIGHEST_PRECEDENCE)
public class CustomWebSecurityConfigurer extends WebSecurityConfigurerAdapter {

	@Override
	protected void configure(HttpSecurity http) throws Exception {
		http //
			.formLogin() //
				.loginPage("/customlogin") //
				.failureUrl("/customlogin?login_error=true") //
			.and() //
			.logout() //
				.logoutUrl("/customlogin?logout=true") //
			.and() //
			.authorizeRequests() //
				.antMatchers("/custompath/*") //
				.permitAll() //
				.antMatchers("/users-only/*") //
				.access("isAuthenticated() AND hasRole('USER')") //
		;
	}
}

To make sure this config "wins" from the default configuration, this annotation is added:

@Order(Ordered.HIGHEST_PRECEDENCE)

7 Further steps

  • No labels