Migrate Play 2.2 to Play 2.3
Play is an open source web application framework which makes it easy to build web applications with Java & Scala. When we built our project, we were using Play 2.2. As time goes by, while more and more features and dependencies are included, this project has been growing bigger and bigger, and the only Play upgrade we have done was from Play 2.2.1 to Play 2.2.3. The thing is, The more we developed for this project, the more reluctant we are to upgrade the framework. However, Play 2.2 is pretty outdated now, and many fixes and features are in the newer versions. Consequently, we cannot live with the old framework forever and the time has come for upgrading this beast.
Start With the Guide
It is recommended that the framework be upgraded gradually. For this reason, instead of to the latest version (2.5.x), here I am going to first upgrade 2.2.3 to 2.3.10, in which there will be already enough work to do. The official website has provided a good guide to perform this migration. One thing to stress (even though it's already mentioned in the guide) is that, if you use Scala to describe your build, i.e. not using build.sbt file, then you need to import the libraries like in the following:
After you change the version of the Play plugin in project/plugins.sbt as follows
,and run the compile command
Now you are using Play 2.3.xxx, and that's when the nightmare begins. The project won't compile and errors are flying around. Let's continue to see their causes and what we need to deal with them.
Update IDE Dependency Caches
First, you have to update your IDE dependencies because it will help you a lot in identifying the issues. If you are using IntelliJ IDEA, simply run
to update the Play dependencies then restart IDEA. You may need to remove .idea and .idea_module folders first. An alternative way is directly from the File -> Invalidate Caches/Restart in the IDEA application.
Update WS Classes
One of the errors that you will see at compile is the WS class symbol not found. This is because in Play 2.3, the WS (Web Service) library has been modified and some classes in there have been changed and renamed. The following are renamed library and classes that are used in our project:
play.lib.WS -> play.lib.ws.WS
WS.WSRequestHolder -> WSRequestHolder
WS.Response -> WSResponse
So you'll have to go through your project and change them. It's a laborious work, but once fixing them you'll find more than half of the errors have gone.
Replace SimpleResult with Result
The next errors that you will notice are something like the following one (this is not the actual error message, but essentially something to do with the converting):
So with Play 2.3, basically anything reference to SimpleResult will fail. Also, delegate.call(Context ctx) is no longer returned as Promise<SimpleResult>, it's now returned as Promise<Result> instead. Again, you need to go through your project, look for the usages of SimpleResult and change them to Result.
No Need of WithApplication For Unit Tests
From Play 2.3, the application is automatically started before each test, so you don't need to call start() provided in WithApplication class explicitly anymore.
Upgrade Deadbolt
If you used Deadbolt with version like 2.2-RC2, now it will not work because it relies on Play 2.2 and uses SimpleResult too. Here we bump it to version 2.3.2. In addition, you also need to modify your handler classes and add some handler classes as described here.
Finally, Upgrade Swagger
Alright, everything should work now, unless you integrated Swagger into your project like me. In our project, we used Swagger 1.3.1 which is not compatible with Play 2.3 and will give the following error:
This is related to the SimpleResult issue mentioned above because Swagger 1.3.1 is based on Play 2.2. According to their compatibility chart (here), we upgrade it to the version 1.3.12. Now we see another error like this:
This one is tricky and took me a while to resolve it. It turns out upgrading Swagger 1.3.12 automatically bring in org.reflections % reflections % 0.9.9, it's supposed to work well with the new Swagger, but it just doesn't. After couple rounds of trial and error, finally I found that the version 0.9.8 works, and now we need that version of reflections to stay in our project. According to the sbt manual, when we prefer the version we have specified over the version from indirect dependencies, we need to use force() like:
After doing this, the project compiles and runs successfully and the Swagger API Doc page is now displayed properly.
Conclusion
Now your application is finally migrated to Play 2.3 (hopefully). Remember, from time to time, if you find something wrong with your project and get some xxxxNotFound errors, you can try to run
or
first to clean up your project and then recompile. Sometimes the errors will disappear by doing that.
Update
According to the manual, to distribute your application, you might need to use
Also, to build it in DockerFile, if you previously point to the config file that is in the target/universal/stage folder, you now need to do it after the stage:
