Related Documents
Document Properties
Kbid
298A87
Last Modified
14-Jun-2021
Added to KB
01-Jun-2021
Public Access
Everyone
Status
Online
Doc Type
Guidelines, Concepts & Cookbooks
Product
ICM 7.10

Guide - 7.10.31.0 Migration to Tomcat 9

1 Introduction

This guide provides information about the migration from Tomcat 7 to Tomcat 9. This major update might cause migration efforts on custom source projects.

1.1 Library Updates

To support the usage of the newest Tomcat application, several libraries were updated, which can potentially break the implementation.

LibraryOld VersionNew Version
com.fasterxml.jackson.core.*:*2.9.102.12.1
com.googlecode.owasp-java-html-sanitizer:owasp-java-html-sanitizerr13620200713.1
io.swagger.core.v3:*2.0.72.1.6
io.swagger.codegen.v3:swagger-codegen-cli(new)3.0.24
javax.annotation:javax.annotation-api1.3(removed)
javax.servlet:javax.servlet-api3.1.04.0.1
javax.servlet.jsp:jsp-api(new)2.2.1-b03
org.apache.tomcat:*7.0.429.0.41
org.codehaus.janino:commons-compiler3.0.63.1.3
org.glassfish.hk2:*2.5.0-b322.6.1
org.glassfish.jersey.*:*2.25.12.33
jakarta.annotation:jakarta.annotation-api(new)1.3.5
jakarta.inject:jakarta.inject-api(new)2.0.0
jakarta.ws.rs:jakarta.ws.rs-api(new)2.1.6
jakarta.servlet:jakarta.servlet-api(new)5.0.0
jakarta.validation:jakarta.validation-api(new)2.0.2

2  Migration Steps

2.1 Migration of Source Cartridges

2.1.1 Apply JSP for ISML Dependencies

To minimize the declaration for each sub-project, it is possible to apply steps for all subprojects in the root build.gradle script.

Especially the usage of the tomcat-servlet-api instead of the javax.servlet-api needs to be considered. Please remove the javax.servlet-api dependencies also from the build.gradle files of all sub-projects.

Dependencies
subprojects {
	apply plugin: 'com.intershop.gradle.buildinfo'
 
    		// setup source and target compatibility for isml and add default dependencies    
			plugins.withId('com.intershop.gradle.isml') {
				tasks.withType(com.intershop.gradle.isml.task.IsmlCompile) {
					sourceCompatibility = 1.8
					targetCompatibility = 1.8
					jspPackage = "org.apache.jsp.${project.name}"
				}
				
				dependencies {
					compile 'com.intershop.platform:servletengine'
					compile 'org.apache.tomcat:tomcat-jsp-api'
				}
			}
			dependencies {
				compile 'org.apache.tomcat:tomcat-el-api'
				// compile 'javax.servlet:javax.servlet-api'
				compile 'org.apache.tomcat:tomcat-servlet-api'
			}
     }
}

2.1.2 Replacement of Dependencies

Dependency ScopeOld LibraryNew LibraryComment
compilejavax.ws.rs:javax.ws.rs-apijakarta.ws.rs:jakarta.ws.rs-api
compilejavax.servlet:javax.servlet-apiorg.apache.tomcat:tomcat-servlet-api
compilejavax.validation:validation-apijakarta.validation:jakarta.validation-api
compilecom.intershop.platform:servletengine(can be moved to root build.gradle, because is used for all projects with isml)
exclude

compile org.glassfish.jersey.core;*

 {
 exclude group:'org.glassfish.hk2.external', module:'javax.inject'
 exclude group:'org.glassfish.hk2.external', module:'aopalliance-repackaged'
 }

compile org.glassfish.jersey.core;*

{
 exclude group:'org.glassfish.hk2.external'
 exclude group:'jakarta.annotation', module:'jakarta.annotation-api'
 exclude group:'jakarta.validation', module:'jakarta.validation-api'
}

The jersey client contains many other dependencies. Please verify the usage.
excludecompile 'org.hibernate:hibernate-validator'compile ('org.hibernate:hibernate-validator') {
  exclude group: 'javax.validation', module: 'validation-api'
}

exclude
def jerseyExcludes = {
 exclude group:'org.glassfish.hk2.external', module:'javax.inject'
 exclude group:'org.glassfish.hk2.external', module:'aopalliance-repackaged'
 exclude group:'org.glassfish.hk2.external', module:'jakarta.inject'
 exclude group:'jakarta.annotation', module:'jakarta.annotation-api'
 exclude group:'jakarta.validation', module:'jakarta.validation-api'
}
compile 'org.glassfish.jersey.core:jersey-client', jerseyExcludes
The jersey client contains many other dependencies. Please verify the usage.

2.1.3 Cartridges with ISML

Include the generated sources for isml-jsp-class files.

build.gradle
apply plugin: 'static-cartridge'
apply plugin: 'com.intershop.gradle.cartridge-resourcelist'
apply plugin: 'com.intershop.gradle.isml'
 
intershop {
    displayName = 'Contains isml templates'

	packages {
        cartridge {
            srcDir(isml2classMain)
        }
    }
 } 

2.1.4 Cartridges with Dependencies to Jasper

Please exclude the groups org.eclipse.jdt and org.apache.tomcat to avoid any class collisions and unnecessary indirect dependencies.

tomcat-jasper
compile ('org.apache.tomcat:tomcat-jasper') 
{
    exclude group:'org.eclipse.jdt'
	exclude group:'org.apache.tomcat'
}

2.1.5 Stronger Type System in ISML Templates and Modules

Since ISML-templates will be translated to Java source code with source level 1.8, some code in JSP-sections might cause an unexpected runtime exception. Of particular interest is String.valueOf(...). As this method has multiple overloads, the version String.valueOf(char[]) can get chosen by the compiler if generics are used, even if the passed object is not a character array.

The following code would cause a ClassCastException, which can be avoided by using a cast, e.g. (Object)dict.get("name"):

Using a cast
- // causes ClassCastException because of the generic return type of <T> T PipelineDictionary.get(String key);
- String name = String.valueOf(dict.get("name")); 
+	String name = String.valueOf((Object)dict.get("name"));

2.2 Migration of Deployment Scripts

2.2.1  Adaption of tomcat.sh

With the introduction of Tomcat 9, an "external" standard Tomcat installation is no longer required to run the Intershop Commerce Management application server. The new ICM application server can be started with the main() class in com.intershop.beehive.startup.ServletEngineStartup.

Therefore, the former tomcat.sh was split into two parts, one for

  • the Intershop Commerce Management application server (tomcat.sh) and for
  • the independent Tomcat application server (tomcat_external.sh)

In case your deployment is manipulating the tomcat.sh, please validate that the customization (mostly defined at deploy.gradle files) is working with the new version.

2.2.2 Startup Modification

The nodemanager is responsible for observing the application servers. The default configuration contains only the "process declaration" for tomcat.sh.

The (external) Tomcat application server will not be started by default.

Note

Please add an additional server to the nodemanager.properties (<appserver>/engine/nodemanager/config) in case you need the external Tomcat for other applications. The external Tomcat application will be removed with ICM 7.11. Currently it is provided for compatibility reasons only. Please make sure that your applications using the external Tomcat are compatible with the update.
nodemanager.properties (process section
# The list of recognized process definitions (see below).
process.list=icm-as,tomcat_ext

# Process definitions - (reads appserver/config/appserver0.properties and writes logfile at appserver/log/icm-as.log)
process.icm-as.command=tomcat.sh appserver0 -Xms2048m -Xmx3072m -Djava.net.preferIPv4Stack=true
process.icm-as.autostart=true

# Process definitions - (reads appserver/engine/tomcat/servers/appserver0/conf/ and writes logfile at appserver/log/tomcat_ext.log)
process.tomcat_ext.command=tomcat_external.sh appserver0 -Xms2048m -Xmx3072m -Djava.net.preferIPv4Stack=true
process.tomcat_ext.autostart=true


TCC is disfunctional and will be removed in 7.11.

Projects with Solr 4 require an additional update of the Solr 4 Connector (release 30.0.0).

Projects with Solr Cloud require an additional update of the Solr Cloud Connector (release 3.0.0).





Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets