Hello <SpringMVC/> World in IntelliJ — the 2020.1 Edition
I have just spent the last 3 days wrestling with the Spring MVC configuration trying to understand how to get a simple Hello World index page to show up. Going through this process makes me truly appreciate the simplicity of other frameworks, such as Express.js. This is also the reason why abstractions such as Spring Boot have been created on top of the Spring Framework, in an attempt to remove the configuration nightmares that come about with xml config files, dependency management, and even IntelliJ plugin configuration.
However, oftentimes, in the midst of the struggle, that is where deeper learning takes place.
I have found a lot of tutorials and how-to guides using Eclipse to set this up, which is why I was determined to get it running in my favorite java IDE, IntelliJ.
At any rate, here are the steps to setting up a Spring MVC App in IntelliJ.
- Download and Install IntelliJ 2020.1 Ultimate Edition. They offer a free trial, but if you’re a student, you may be able to grab your self a free copy. Ultimate edition is required to build Web Apps in Java, so the community edition will not cut it for a Spring MVC app.
- If you haven’t already, make sure you install the JDK (Java Development Kit). I recommend the JDK 11, which is the latest version that has LTS (Long Term Support). I personally use an Open Source JDK flavor by AWS, Amazon Coretto 11.
- Open up IntelliJ and make sure the Spring plugins are enabled. To get to plugins from the home screen, click configure => plugins:
- Download Apache Tomcat 9. It is an Application Server that is required for the Spring MVC to run.Make sure to download Apache Tomcat Core. Unzip the download to a location of your choice.
- Give full access to Apache Tomcat. You can do this by navigating to the folder in a CLI and changing the permissions.
Now the initial housekeeping is done, you will want to create a new project.
- Create a Spring MVC project. You will need to select Spring MVC, Java EE Web Application, and Java EE Application Server. For the Application Server, you may have to add Apache Tomcat as a new Server that IntelliJ can recognize.
If all goes well, you should see an initial project structure like as follows :
2. Add the Spring MVC jar files to the project’s “artifact.”
This step caused me days of headache and struggle. Go to file => project structure, and click on artifacts. Then you may see a message towards the bottom :
Click fix and apply to add the jar’s to your project module.
3. create a “base package”. This will be the primary package where your project is located. You should place the package in the src folder that was automatically created by IntelliJ.
4. Configure the web.xml file. It is stored in the WEB-INF folder. The only change you should have to make is the urlPattern of the dispatcher servlet.
the url-pattern should just have a simple forward slash as it’s value.
To be thorough, here is a screen shot of the complete web.xml file, generated automatically by IntelliJ :
5. Configure the dispatcher-servlet.xml file, also stored in the WEB-INF folder.
- Add support for component scanning
this allows the spring framework to scan all classes with a @Component annotation and to treat them as “spring beans”. Note the base package is set to the package we created.
- Add support for form conversion, formatting, and validation
Adding the above <mvc/> tag causes IntelliJ to generate a few more urls in the <beans> header tag.
This is the most cumbersome step and tricky step. You need to manually change every occurence of “cache” to “tx”. Don’t ask me why Spring MVC or IntelliJ doesn’t do this automatically. The Spring MVC will have a bunch of urls in the <beans> header tag to URLS having the word “cache” in them. But the correct dependency required is the spring-tx jar file that should have been downloaded by IntelliJ if you selected the Spring MVC project.
After you finish changing out the word “cache”, you will end up with the following <beans> header tag info for the dispatcher-servlet.xml file
- Add a bean to resolve the view
For the prefix, that is the path to our front end views (html , jsp, thymeleaf, etc.). Don’t forget the forward slash at the end of views/ because the prefix will not consider views to be a folder name, but part of the file name instead.
In this example, we want our view to be a .jsp file type. JSP’s are (java server pages) an html templating system for java apps.
To be complete, here is the completed dispatcher-servlet.xml file :
6. Set up the View
6.1 — Create the views folder in WEB-INF/views. Move the index.jsp file into the newly created folder.
6.2 — Create a basic html page in index.jsp
7. Create a Spring Controller
- create a java class in the base package. Call the class some type of controller.
- Add the annotation to the class to make it a @Controller.
- Create a method in the class that returns a String. the string that is returned MUST be the name of the .jsp view file you just created. In this case, it should be index, since we just moved the index.jsp file that was generated by intelliJ.
- Add the @RequestMapping(“/”) annotation to the method. Set the path to be a simple forward slash
The final step is to run the app! Click the run button next to the Apache Tomcat configuration menu.
If all goes well, you should see a browser pop up with the contents of the index.jsp file showing to the page.
I can’t imagine how this makes the life of a java developer any easier. But, all this configuration could have been the motivation behind why Spring Boot came into existence and further abstracted away these complicated configurations.
