Document Tree
Document Properties
Last Modified
Added to KB
Public Access
Doc Type
ICM 7.10
Guide - Migration to Tomcat 9


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

Library Updates

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

LibraryOld VersionNew Version

No Template Processing of ISML templates located in sites folder

Unfortunately, templates located in the "sites" folder will not longer be processed. ISML templates are code artifacts and must not be modifiable in a runtime environment. Please move and adapt templates to your application cartridges, so you can provide different templates for different application types.

Migration Steps

Migration of Source Cartridges

Apply JSP for ISML Dependencies

To minimize the declaration for each subproject, 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.

It is obligatory to adapt the source compatibility to 1.8 (otherwise errors like new java.util.HashMap<>() diamond operator are not compatible with your source version).

subprojects {
	apply plugin: 'com.intershop.gradle.buildinfo'
    if(! assemblyProjects.contains(it)) {
    		// 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.${}"
				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'

Replacement of Dependencies

Dependency ScopeOld LibraryNew LibraryComment
compilecom.intershop.platform:servletengine(can be moved to root build.gradle, because is used for all projects with isml)

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'

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.

Cartridges with ISML

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

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

	packages {
        cartridge {

After applying the changes you may receive an error message, e.g. like this:

Error Message
Caused by: org.gradle.api.internal.plugins.PluginApplicationException: Failed to apply plugin [id 'com.intershop.gradle.isml']
at org.gradle.api.internal.plugins.DefaultPluginManager.doApply(
at org.gradle.api.internal.plugins.DefaultPluginManager.apply(
Caused by: java.lang.IllegalArgumentException: Cannot add extension with name 'isml', as there is an extension already registered with that name.
at org.gradle.api.internal.plugins.ExtensionsStorage.add(
at org.gradle.api.internal.plugins.DefaultConvention.add(
... more

The error is thrown because the plugin 'static-cartridge' applies the deprecated 'isml' object extension. This conflicts with the ISML extension just added to the build.gradle file.

In order to solve the issue, you have to add the lines to your project-wide build.gradle file:

	// disable standard (old) ISML to avoid plugin conflicts
	project.ext.disableStandardISML = true

The property will disable the old ISML plugin, so the newly added plugin can be applied without conflict.

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.

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

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"));

Migration of Deployment Scripts

Adaption of

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 was split into two parts, one for

  • the Intershop Commerce Management application server ( and for
  • the independent Tomcat application server (

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

Startup Modification

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

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


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

# Process definitions - (reads appserver/config/ and writes logfile at appserver/log/icm-as.log) appserver0 -Xms2048m -Xmx3072m

# Process definitions - (reads appserver/engine/tomcat/servers/appserver0/conf/ and writes logfile at appserver/log/tomcat_ext.log) appserver0 -Xms2048m -Xmx3072m

Additional changes

The package "javax.xml.bind" was added to the cp.ignoredClasses property.

all class pattern in one
cp.ignoredClasses = ^com[.]intershop[.]beehive[.]runtime[.].;

TCC is disfunctional and will be removed in ICM11.

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

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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to if you experience login issues,
or if you want to register as customer.