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.

Library Updates

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

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.${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'
			}
     }
}

Replacement of Dependencies

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 {
            srcDir(isml2classMain)
        }
    }
 } 

...
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(DefaultPluginManager.java:153)
at org.gradle.api.internal.plugins.DefaultPluginManager.apply(DefaultPluginManager.java:112)
...
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(ExtensionsStorage.java:38)
at org.gradle.api.internal.plugins.DefaultConvention.add(DefaultConvention.java:101)
... more

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

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

- // 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 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.

Startup Modification

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

# 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

Additional loaderapp.properties changes

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

cp.ignoredClasses = ^com[.]intershop[.]beehive[.]runtime[.].;
  ^com[.]sun[.]org[.]apache[.].;
  ^javax[.]xml[.]namespace[.].;
  ^javax[.]xml[.]stream[.].;
  ^javax[.]activation[.].;
  ^javax[.]transaction[.]xa.;
  ^javax[.]xml[.]bind[.].