STS3 Migration

Migration Guide from Spring Tool Suite 3 (STS) to Spring Tools 4

Preface

Migrating to the Spring Tools 4 in Eclipse is not complicated or requires a huge amount of work. The overall goal is that most of your projects will "just work" in the Spring Tools 4 for Eclipse.

However, the feature set of the Spring Tools 4 for Eclipse and the overall user experience is quite different. So before you migrate, we recommend that you make yourself familiar with the way the Spring Tools 4 work using a sample project or a project of your choice, read through the user guide for Spring Tools 4 in this wiki, and take a look at the feature comparison between Spring Tool Suite 3 and Spring Tools 4 here.

We would recommend to do the migration in these steps:

1. Make yourself familiar with Spring Tools 4 (as described above)
2. backup your projects and your workspace (including its metadata)
3. start with a fresh Spring Tools 4 for Eclipse distribution (do not update an existing STS3 install)
4. make sure to install all your additional third-party plugins into that fresh install
5. try to open your workspace using the new and fresh Spring Tools 4 installation

Common problems and how to solve them

Spring Perspective looks strange and broken

In case you had the Spring Perspective open in your workspace when working with the Spring Tool Suite 3, opening up that workspace will re-open the Spring Perspective again, but it doesn't really exist anymore in the Spring Tools 4. Therefore the workbench looks broken, shows red icons for some empty views, and similar things.

You can solve that by simply closing the Spring Perspective. Right-click on the perspective text at the top of the workbench and select "Close". And continue to use a different perspective, like the default Java one.

Error on pom.xml file

On certain projects, the is an error showing up on the pom.xml files, saying: Project configuration is not up-to-date with pom.xml. Select: Maven->Update Project... from the project context menu or use Quick Fix.. Following the advice in the description will usually fix the issue.

Depending on the additional third-party m2e extensions that you might have installed into your previous Spring Tool Suite 3 installation, more errors and warnings no our pom.xml files might not go away after updating the Maven project. In those cases, you might need to re-install those m2e extensions into your new Spring Tools 4 for Eclipse install.

(if you have additional advice or came across specific issues here, please let us know or submit a pull request for this page to fill it up with additional details and information)

Unknown reference to Spring nature

Most of the projects in your workspace will surface a warning saying: Unknown referenced nature: org.springframework.ide.eclipse.core.springnature.. The reason for that is that the Spring project nature from the Spring Tool Suite 3 is still part of your project metadata (in the .project file), but no longer exists in the Spring Tools 4 for Eclipse. The best way to deal with this is either to ignore this warning (in case you want to continue to use the same project with an Spring Tool Suite 3 installation, e.g. of your team mates) or to delete the line from your .project file. For example:

...
<natures>
	<nature>org.springframework.ide.eclipse.core.springnature</nature> <== DELETE THIS LINE
	<nature>org.eclipse.jdt.core.javanature</nature>
	<nature>org.eclipse.m2e.core.maven2Nature</nature>
	<nature>org.eclipse.wst.common.project.facet.core.nature</nature>
</natures>
...

Project facet for Cloud Foundry standalone app not found

Another warning that might appear in your workspace says: Implementation of project facet cloudfoundry.standalone.app could not be found. Functionality will be limited.. This is caused by the fact that the Spring Tools 4 for Eclipse do not include the Cloud Foundry Integration for Eclipse add-on by default, which contributed the above mentioned project facet and probably got added to your Spring projects automatically. In case you don't need the Cloud Foundry Integration for Eclipse, you can remove that facet from your project definition (instead of re-installing the Cloud Foundry Integration for Eclipse). In order to do that, you have to manually edit the file .settings/org.eclipse.wst.common.project.facet.core.xml and remove the entry for the missing facet. For example:

<?xml version="1.0" encoding="UTF-8"?>
<faceted-project>
  <installed facet="cloudfoundry.standalone.app" version="1.0"/>   <=== REMOVE THIS LINE
</faceted-project>

Further cleanup of the .project file

In order to further cleanup your project definitions, you should remove the Spring project builder entry from your .project files. For example:

<buildSpec>
	...
	<buildCommand>   <==== REMOVE THIS ENTRY FROM HERE...
		<name>org.springframework.ide.eclipse.core.springbuilder</name>
		<arguments>
		</arguments>
	</buildCommand>   ====> TO HERE
	...
</buildSpec>

Missing Spring-specific project settings

Most of the Spring-specific project settings are not available anymore in the Spring Tools 4 for Eclipse, so please do not wonder about missing project setting nodes in the project properties dialog. Those settings are gone and no longer required in the Spring Tools 4 for Eclipse.

In more detail:

• The XML-specific settings are gone, since Spring Tools 4 for Eclipse includes one rudimentary support for editing and validating Spring XML files. The basic settings for that can be found in the workspace preferences under Language Servers -> Spring Language Servers -> Spring Boot Language Server -> Spring XML Config.
• The tooling doesn't need a configuration for specific entry points like XML config files or annotated Spring application files anymore. Those files are identified automatically.

(In case you are missing specific features that you still urgently require in your Spring Tools 4 for Eclipse installation, please let us know and file an enhancement request at https://github.com/spring-projects/sts4/issues - add tag those enhancement requests with the label sts3-feature-request.)