Migration guide: platform 2.1.x to 3.0.x

Platform 3.0.0 binds to Across 4.0.0, which is built on top of Spring Boot 2.0.x and Spring Framework 5.0.x. This is a major upgrade with a lot of breaking changes, mostly due to changes inside Spring dependencies.

This guide is not a full overview of all new features and changes in Across or any of its modules. It mainly focuses on upgrade related changes: usually breaking changes or new features that impact application/module configuration.

State of the migration guide

Current Platform development version is 3.0.0-SNAPSHOT, slated to become 3.0.0.M1.

General breaking changes

https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.0-Release-Notes

https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-Security-2.0

https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.0-Migration-Guide

https://spring.io/blog/2017/11/01/spring-security-5-0-0-rc1-released#password-encoding

Module developers

Property renaming

A lot of Spring Boot properties have been renamed for consistency and to differ between Servlet and Webflux setups. See the Boot 2.0 migration guide for more information on the new properties.

The following Across module properties have been modified:

Table 1. Property prefix modifications
Module Old prefix New prefix

Across Web

acrossWebModule

across.web

Spring libraries

  • The behavior or spring.config.location has been changed, to get the old behavior spring.config.additional-location should be used instead: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.0-Migration-Guide#configuration-location

  • Spring ORM JPA uses Oracle12c dialect by default instead of 10

    • users might need to specify Oracle10gDialect as Hibernate dialect specifically

  • Several Spring Data Repository interfaces have been modified. Certain often used methods have been removed altogether and replaced with new alternatives (with a different signature).

    • findOne(id) has been replaced by findById(id) and now returns an Optional.

    • delete(List) has been replaced by deleteAll(Iterable). The same goes for save(List).

  • Spring data commons has renamed QueryDslPredicateExecutor to QuerydslPredicateExecutor (in the same package).

    • when using Cache annotations be aware that #result on an Optional returning method refers to the actual content of the Optional if it is not empty

  • Hibernate upgrades to 5.2, see migration guide: https://github.com/hibernate/hibernate-orm/blob/5.2/migration-guide.adoc

  • Date classes in json responses are not serialized as timestamps anymore, if you want the older behaviour, set spring.jackson.serialization.write_dates_as_timestamps: true

  • The behaviour of UriComponentsBuilder has been changed somewhat in Spring 5. Calls to .queryParam are now seen as literals and will not be url encoded anymore. If you want query parameters to be encoded you must use templated variables as seen on https://docs.spring.io/spring/docs/5.0.8.BUILD-SNAPSHOT/spring-framework-reference/web.html#web-uri-encoding. It is advisable to search your code for .queryParam( calls and change them to templated variables if they contain characters like: + or / (e.g. urls).

Auto-configuration support

  • across.configuration has been dropped in favour of across-configuration.yml which allows more advanced configuration

Modules

In general most modules have breaking changes regarding Spring Data repositories, where single instance queries will now always return Optional.

AcrossHibernateModule

  • some properties (default-timeout) have been changed of type, a duration is now sometimes required (eg. 5s instead of 5)

SpringSecurityModule

Most security configurations that used Spring Boot 1.5 defaults (for example for Actuator stuff) will need to be reviewed.

  • Spring Boot no longer applies custom security to any endpoint, meaning that you will now have to manually apply the security you want by providing WebSecurityConfigurerAdapter

  • if there is no WebSecurityConfigurerAdapter the default Spring security adapter will secure everything

    • if you have SpringSecurityModule but do not want to have security applied, you should manually add a configuration that ignores everything

  • Password encoding features have been modified, if you want to specify in memory users with a default password, you probably have to migrate your old code and prefix the password with {noop} to avoid a no PasswordEncoder exception

See https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-Security-2.0

EntityModule

Mostly Spring Data related changes. In previous version a Sort could be null whereas now a Sort.unsorted() is used in Spring Data. According changes in EntityModule have been done, passing null as a Sort should be avoided.

SpringMobileModule

Device specific Thymeleaf view resolving only works with the .html extension out of the box. The previous .thtml extension is no longer supported.

Spring Mobile is no longer part of Spring Platform Cairo, this indicates the project is probably not as much up-to-date as other Spring projects and its future might be uncertain.