|
| 1 | += Migration Guide |
| 2 | +:toc: |
| 3 | +:toc-title: |
| 4 | + |
| 5 | +:url-jdk-upgrade: https://docs.oracle.com/en/java/javase/11/migrate/index.html |
| 6 | +:url-tomcat-9: https://tomcat.apache.org/tomcat-9.0-doc/index.html |
| 7 | +:url-pg-upgrade: https://www.postgresql.org/docs/12/upgrading.html |
| 8 | +:url-gradle-docs: https://docs.gradle.org/7.3/userguide/userguide.html |
| 9 | +:url-groovy-upgrade: https://groovy-lang.org/releasenotes/groovy-3.0.html |
| 10 | +:url-graalvm-js: https://www.graalvm.org/reference-manual/js/NashornMigrationGuide/ |
| 11 | +:url-junit-upgrade: https://www.baeldung.com/junit-5-migration |
| 12 | +:url-pac4j-clients: http://www.pac4j.org/4.5.x/docs/clients.html |
| 13 | + |
| 14 | +In this document, we will see the major steps required to migrate from 5.x to 6.0. |
| 15 | + |
| 16 | +== Java 8 to Java 11 |
| 17 | + |
| 18 | +JAVA 11 is now our minimal version to build and run applications. |
| 19 | + |
| 20 | +Install JAVA 11 and then increase the Java version number in the `build.gradle` file: |
| 21 | + |
| 22 | +.build.gradle |
| 23 | +[source,gradle] |
| 24 | +---- |
| 25 | +allprojects { |
| 26 | +
|
| 27 | + java { |
| 28 | + toolchain { |
| 29 | + languageVersion = JavaLanguageVersion.of(11) |
| 30 | + } |
| 31 | + } |
| 32 | +
|
| 33 | +} |
| 34 | +---- |
| 35 | + |
| 36 | +Also make sure to use JDK 11 in the IDE as well as in your terminal (if needed). |
| 37 | + |
| 38 | +In JAVA 8, JAXB was part of standard JDK. It has been removed in JDK 11. To use JAXB API in Java 11, you need to use |
| 39 | +separate library : `javax.xml.bind:jaxb-api`, `com.sun.xml.bind:jaxb-core`, `com.sun.xml.bind:jaxb-impl` and `javax.activation:activation` |
| 40 | + |
| 41 | +See the {url-jdk-upgrade}[JDK 11 migration guide] for details. |
| 42 | + |
| 43 | +== Tomcat 8.5 to Tomcat 9 |
| 44 | + |
| 45 | +Apache Tomcat version 8.5 is no more supported. You need to upgrade to {url-tomcat-9}[Apache Tomcat 9]. |
| 46 | + |
| 47 | +== PostgreSQL 9 to PostgreSQL 12+ |
| 48 | + |
| 49 | +Minimal PostgreSQL 12 is now required to run applications. |
| 50 | + |
| 51 | +Please check the {url-pg-upgrade}[PostgreSQL 12 upgrade guide] for details. |
| 52 | + |
| 53 | +== Gradle 5 to Gradle 7 |
| 54 | + |
| 55 | +---- |
| 56 | +./gradlew wrapper --gradle-version 7.2 |
| 57 | +---- |
| 58 | + |
| 59 | +=== Dependencies |
| 60 | + |
| 61 | +Many transitive dependencies are removed. If you use them, you need to add them in each affected module. |
| 62 | + |
| 63 | +The `compile` configuration is deprecated. Use the `api` configuration to declare dependencies which are exported, and the `implementation` configuration to declare dependencies which are internal to your module. |
| 64 | + |
| 65 | +Example: |
| 66 | + |
| 67 | +.build.gradle |
| 68 | +[source,gradle] |
| 69 | +---- |
| 70 | +dependencies { |
| 71 | + api project(":modules:axelor-base") |
| 72 | + implementation libs.commons_lang3 |
| 73 | +} |
| 74 | +---- |
| 75 | + |
| 76 | +=== Axelor plugin |
| 77 | + |
| 78 | +The Axelor Gradle plugins `com.axelor.app` and `com.axelor.app-module` are merged. |
| 79 | + |
| 80 | +There is now a single `com.axelor.app` plugin, ie. all Axelor modules are Axelor apps. All modules should use the app plugin only. |
| 81 | + |
| 82 | +See the Gradle upgrade guides for details: |
| 83 | + |
| 84 | +* https://docs.gradle.org/7.3/userguide/upgrading_version_5.html |
| 85 | +* https://docs.gradle.org/7.3/userguide/upgrading_version_6.html |
| 86 | +* https://docs.gradle.org/7.3/userguide/upgrading_version_7.html |
| 87 | + |
| 88 | +== Groovy 2 to Groovy 3 |
| 89 | + |
| 90 | +{url-groovy-upgrade}[Groovy 3] improves compatibility with Java and has many other improvements. |
| 91 | + |
| 92 | +== Nashorn to GraalVM JavaScript |
| 93 | + |
| 94 | +Nashorn is replaced by the {url-graalvm-js}[Graal JavaScript Engine]. |
| 95 | + |
| 96 | +The Nashorn script engine is deprecated in Java 11 and has some incompatible changes compared to Java 8. |
| 97 | +The new implementation uses the GraalVM JavaScript Engine, which supports the latest ECMAScript features. |
| 98 | + |
| 99 | +The collection helpers `listOf`, `setOf`, and `mapOf` are removed as corresponding native JavaScript objects |
| 100 | +are passed with appropriate Java equivalent wrapper to the Java calls. |
| 101 | + |
| 102 | +== OpenCSV to Commons CSV |
| 103 | + |
| 104 | +Dependency to OpenCSV has been removed. For ease of migration, you may manually add the dependency in your own module if you wish to continue using it. The desirable end goal is to fully migrate to Commons CSV. |
| 105 | + |
| 106 | +== Reserved keywords |
| 107 | + |
| 108 | +With upgraded database support, more keywords ar now reserved. So you need to rename database |
| 109 | +column of any affected fields. |
| 110 | + |
| 111 | +Some notable new reserved keywords: |
| 112 | + |
| 113 | +* `condition` |
| 114 | +* `file` |
| 115 | +* `key` |
| 116 | +* `message` |
| 117 | +* `rank` |
| 118 | +* `signal` |
| 119 | +* `size` |
| 120 | +* `uid` |
| 121 | + |
| 122 | +== Dropped removable modules |
| 123 | + |
| 124 | +The feature is not used by any axelor apps and had many technical issues. |
| 125 | + |
| 126 | +Run the following SQL script to drop unnecessary columns: |
| 127 | + |
| 128 | +[source,sql] |
| 129 | +---- |
| 130 | +ALTER TABLE meta_module DROP COLUMN installed; |
| 131 | +ALTER TABLE meta_module DROP COLUMN removable; |
| 132 | +ALTER TABLE meta_module DROP COLUMN pending; |
| 133 | +---- |
| 134 | + |
| 135 | +== Dropped deprecated features |
| 136 | + |
| 137 | +Features that were marked as deprecated in AOP v5 are now dropped. |
| 138 | + |
| 139 | +Notable Changes: |
| 140 | + |
| 141 | +* `Context.getParentContext()` → `Context.getParent()` |
| 142 | +* `new ActionHandler(ActionRequest)` → `ActionExecutor.newActionHandler(ActionRequest)` |
| 143 | +* `LoginRedirectException` → `WebUtils.issueRedirect()` |
| 144 | +* `hashKey`/`hashAll` (`hashCode`) → `equalsInclude`/`equalsIncludeAll` (`equals`) |
| 145 | +* `cachable` → `cacheable` |
| 146 | +* `axelor.report.dir` → `reports.design.dir` |
| 147 | + |
| 148 | +== Authentication configuration |
| 149 | + |
| 150 | +Reflection is now used to configure authentication clients. The new syntax is `auth.provider.<providerName>.<configurationName>`. You may use any of the built-in providers (`google`, `facebook`, `azure`, `keycloak`, `apple`, `oauth`, `oidc`, `saml`, `cas`) or configure any other clients supported by {url-pac4j-clients}[pac4j] using your own custom provider name. You may even create and use your own custom authentication clients. |
| 151 | + |
| 152 | +Example using a built-in provider: |
| 153 | + |
| 154 | +.axelor-config.properties |
| 155 | +[source,properties] |
| 156 | +---- |
| 157 | +auth.provider.google.key = 127736102816-tc5mmsfaasa399jhqkfbv48nftoc55ft.apps.googleusercontent.com |
| 158 | +auth.provider.google.secret = qySuozNl72zzM5SKW-0kczwV |
| 159 | +---- |
| 160 | + |
| 161 | +Built-in providers come with preconfigured settings. The above is equivalent to: |
| 162 | + |
| 163 | +.axelor-config.properties |
| 164 | +[source,properties] |
| 165 | +---- |
| 166 | +auth.provider.myprovider.client = org.pac4j.oauth.client.Google2Client |
| 167 | +auth.provider.myprovider.configuration = org.pac4j.oauth.config.OAuth20Configuration |
| 168 | +auth.provider.myprovider.title = Google |
| 169 | +auth.provider.myprovider.icon = img/signin/google.svg |
| 170 | +auth.provider.myprovider.exclusive = false |
| 171 | +auth.provider.myprovider.absoluteUrlRequired = false |
| 172 | +
|
| 173 | +auth.provider.myprovider.key = 127736102816-tc5mmsfaasa399jhqkfbv48nftoc55ft.apps.googleusercontent.com |
| 174 | +auth.provider.myprovider.secret = qySuozNl72zzM5SKW-0kczwV |
| 175 | +---- |
0 commit comments