Note: I’ve now (Sep 2017) added an extra step ‘3. b)’ to cover running Spring apps using IntelliJ Community Edition, so it is now possible to follow along without needing IntelliJ Ultimate Edition 🙂
In the last couple of weeks I’ve moved into a new team at work – the people are great, the office is amazing, life is wonderful. However, joining a new team means learning how they work and learning the technology they use, in this case I’m facing down the Spring Framework.
In the past I’ve worked with the Play! Framework to create and deploy a webapp, choosing it more or less entirely due to its simplicity and close knit relationship with plain old Java. This isn’t to say that Spring isn’t closely knit with Java, just that learning a billion annotations and figuring out how Java Beans worked seemed quite a daunting task at the time, as opposed to being able to to get straight into Java code in a fully-featured (perhaps a little bloated, in retrospect) framework. In essence, I was being lazy and doing my best to dodge having to learn a ton of new stuff before developing anything meaningful. Lesson learnt!
Anyways, karma has come right back around on me and here I am, now attempting to get up to speed with Spring as soon as my little brain can manage!
The purpose of this post is to share a brief ‘getting started’ guide. This isn’t here to explain all of the intricate steps in detail, this will come when I know these steps intimately myself, this guide is here to get anyone from a blank Maven project in IntelliJ to a very basic web application hosted on a local Tomcat server. Any code I’ve used is available on my GitHub repo for anyone to clone/download and play around with.
FYI – this guide is based on me using a Windows 10 PC, so some steps will be slightly different (read: ‘easier’, ‘less painful’ etc.) if using a Mac.
What is Spring?
As a one-liner – ‘Spring is a framework for developing applications or services that can be accessed/used through the web (via http)’. Basically, it lets you write applications (in Java) that can be deployed and then accessed by users through their web browser of choice (Chrome, Firefox, Safari etc.) by navigating to a URL e.g. http://marksamazingsite.com.
The main benefit of Spring is that it is designed to be modular. You start with the core functionality (Spring Boot) and from there you can choose to extend that by installing additional Spring modules. For instance, if you wanted to hook your application up to a database, you can use the Spring Data module, or if you want to account for security concerns you could apply the Spring Security module, or what if you wanted to develop your app towards Android users, there’s the Spring For Android module! There are loads of different modules to fit most needs, these are all described on the Spring projects website.
The inherent modularity of Spring means that you don’t need to start with a monolithic project and then strip away what you don’t need, it means that you can start with a simple, understandable base and build up gradually according to your needs. The obvious downside to this if you are a beginner (like me), is that implementing additional modules may require a bit of a learning curve, but I’ll find out as I use it more in future posts!
What is Tomcat and how do we use it with Spring?
Tomcat is a ‘web server’ technology, this means that installing and running it on a machine (be it your laptop, or a server in the cloud etc.) will enable you to ‘serve’ content or applications to other machines (clients) in your network, or over the internet if you host your Tomcat machine publicly. If you’re new to the idea of client-server architecture, have a look at this quick (~2 min) video to get an idea of how a server (machine with Tomcat installed, for example) can provide content, data or services to clients (other machines out there able to connect to the server) through the use of requests and responses.
In our case, we are going to install Tomcat on our PC and rather than sending requests to our Tomcat server externally, we can use a special ‘localhost’ URL which will allow us to write a Spring web application, host it (serve it from) our local Tomcat server installed on our machine, then access it using a URL of http://localhost:8080. This just means “send a http request to a local server on port 8080 (Tomcat’s default port)”.
What are we going to do?
- Create a new Maven project
- Download Apache Tomcat 8 to deploy our application to later on
- Set up a run configuration in IntelliJ to run our project on a local Tomcat server
- Write a basic SpringMVC (Spring 4) application
- Deploy and run your webapp!
Stuff you’ll need
IntelliJ Ultimate or Community Edition
If you haven’t already got hold of a free copy of IntelliJ Community Edition, I would highly recommend it. For general coding, in my opinion, it is THE BEST integrated development environment (IDE) for Java, Scala or pretty much anything else it supports!
In this guide we can use either the Ultimate Edition or the Community (free) Edition, if you’re a student you’ll likely be able to get the Ultimate edition for free using your institution’s details here. Step 3 (Setting up Run Configurations) has now been split into part a, and b, to set up a run configuration in either Ultimate or Community Editions’ respectfully. If you’re using Ultimate Edition you can use either of the two methods, however Community Edition will only allow you to use the latter of the two steps.
Apache Tomcat 8
It’s all good and well writing a Spring application, but we need some way of ‘hosting’ it from our machine so we that it can be accessed using a web browser (Chrome, Firefox, Safari etc.) to see it working as a live application! We’ll install and set it up for sue with IntelliJ after we run it manually to test it. We’ll set this up a step in the guide so that you can see the process of going from nothing at all on your machine, to deploying a Spring webapp to your very own local Tomcat server as a matter of easy steps.
In this guide we’ll be using Tomcat 8 which relies on Java 7 or upwards being installed on your machine. I’d recommend using Java 8 straight away anyway though just to stay a little bit more up to date and allow you to take advantage of features such as Java Streams later on in development if you take your Spring project further.
Head to the Oracle website to download Java for your machine.
Let’s get to it!
A lot of the steps in this guide have been taken from a fantastic YouTube video by LynAs Sazzad, have a look at his video to get up and running quickly! As he moves quite fast through the steps in his video (a lot of pausing and going back was required!) and as he already had Tomcat set up to run his application, I’ve decided to write out some of the required steps but for the most part I’ll point you at his video to set up the code you need.
1. Create a new Maven project
Open IntelliJ and choose File -> New -> Project… then select the option for Maven from the list on the left hand side (it should be about halfway down).
Leave the Create from archetype option un-ticked and click next.
Give it a GroupId e.g. com.myTestProject. This option isn’t too important, it’s mainly important only for enterprise-level project where you’d need to define the domain or team your app will fall under such as com.marksCompany.financeWebApp.
ArtifactID is the name you want to assign to your app type in something like springMVCTest and click next. In the following screen the Project Name will likely autopopulate with the ArtifactID you gave your project so just check it is set and that you’re happy with the location of where your project will be stored and then click Finish.
2. Download Apache Tomcat 8 to deploy our application to later on
On my hunt to find a nice easy way of understanding how to install Tomcat on Windows 10, I found this awesome guide. It is a lengthy read but if you want to get to grips with webapps and understanding Tomcat, this covers everything you’ll likely need to know, conveniently enough it’s also got a nice section of downloading and running Tomcat. Below I’ve summarised the steps to downloading Tomcat and testing it by running it on your machine manually.
To download Tomcat for Windows, the easiest way I found was to download a zip file from Tomcat’s official website. At the time of writing, under the 8.5.14 heading there is a section called ‘Binary Distributions’ and in there is an option to download the ‘Core’.zip file (see red box below).
When it had finished downloading, I moved the downloaded .zip file into a new folder called H://Tomcat/Tomcat8/ on the hard drive of my computer and unzipped it there (right click .zip file -> Extract Here). This is just to give it a permanent home on my machine so any of my run configurations that I might put together later on have a definitive location in which to find and use Tomcat from.
As mentioned at the start. we need at least Java 1.7 (Java 7) installed on the machine running Tomcat 8 in order for it to work. Additionally we need to set up an environment variable called JAVA_HOME to point anything on our machine to its location. Hopefully, you’ve already downloaded Java through the Oracle website as explained at the beginning, if so follow the very last few instructions under the heading ‘to install the JDK Software and set JAVA_HOME on a Windows System’ on this site.
Now we are able to test that our downloaded version of Tomcat works, to do this click into the newly unzipped Tomcat file and go into the /bin directory. In here hold down shift and right click a blank are of the window to view the option to ‘Open command window here’, click this to enter command prompt. The only thing you need to do now is type ‘startup’ (without quotes) and press enter, this should open up another little command window, the whole thing should look similar to the output shown below.
Note: the equivalent command in Linux/Mac is ‘./catalinasa.sh run’
Great, so in this new little window it’s telling you that Tomcat is running and that it’s listening on port 8080, so how do we access this? As we mentioned earlier on, we need to send it a request, as Tomcat is a web server, this therefore needs to be via http, so let’s open a web browser such as Chrome and navigate to http://localhost:8080. The result should look similar to the screenshot shown below.
This is Tomcat’s default page to serve to any requests, all this means is that we’ve not told Tomcat to serve anything other than this in response to any requests it receives, simple!
I don’t want to go too far into Tomcat stuff in this guide but I do want to quickly show you how to host your own content from this server manually before moving on. To do this I have created a very simple HTML file called index.html and stored this within a folder called marksApp in Tomcat’s webapps folder (see below).
You should now be able to go to localhost:8080/marksApp (in my example) and take in the awesome beauty of my website.
Now that we’re happy that we have a working Tomcat installation, we just need to set up IntelliJ to use it and write the webapp to be served from it!
3. a) Set up a Tomcat run configuration in IntelliJ Ultimate Edition
In this step we’re simply telling IntelliJ how we would like it to run a program, in this case we’ll be writing a bunch of code that we’d like to run on a Tomcat server locally, so we’ll tell it just that by defining a ‘run configuration’ – a way of setting a particular way to run something.
To do this, from the top menu bar in IntelliJ choose Run -> Edit Configurations. In the
Click the little green ‘+’ in the top left of the window that opens (see screenshot on the right).
You might get an option to choose Tomcat Server as shown in the image to the right, if not, click the option at the bottom titled ‘x items more (irrelevant)…’ and scroll down to find the Tomcat Server option. Once you’v found this click it to choose the Local or Remote options, we want to serve our app from a local Tomcat server so click ‘Local’ as shown below.
A new run configuration has now been created, you just need to edit it to your needs.
Firstly, set the Name field to something meaningful like SpringTomcat, now click the ‘Configure…’ button in the Application server section to bring up a small window (see screenshot to the right).
Clicking the ‘…’ the the right of the Tomcat Home box will allow you to tell IntelliJ where your Tomcat installation lives. Simply put, navigate to the unzipped version of Tomcat that you downloaded earlier, and click OK as shown on the left. You should now be presented with the original small window without the error icons and with some details of your Tomcat installation, click OK.
The final thing we need to do is address the warning at the bottom of the run configuration, click the Fix button and choose the option suffixed with ‘exploded’ then click Apply and OK to finalise the run configuration.
3. b) Set up a Maven run configuration in IntelliJ Community Edition
In the more likely event that you’re following along using IntelliJ Community Edition, here is how you can easily set up a Maven run configuration to run your Spring applications. In this section I will be using the Tomcat7 plugin for Maven (rather than Tomcat8 as used previously in this guide). For the purposes of this guide the version of Tomcat being used isn’t important though.
Add the following plugin to your pom.xml.
From the Run menu, select ‘Edit Configurations…’
The Run Configuration window will now pop up – click the grey ‘+’ icon in the top left of this window and choose the Maven option.
Enter a name for your new run configuration and add ‘tomcat7:run’ in the Command Line box. Now click Apply and then OK to exit the window. This may require you to download and install Tomcat
All you need to do now is choose your new run configuration from the Run menu!
If your application fails to start, make sure that no other applications are running on the same port as the current application you’re trying to run. Most tutorials use the default port of 8080 so if this is the case, just stop any other apps you might be working on and try again. Other common issues relate to either the contents of your WEB-INF folder, or the dependencies in your pom.xml, so be sure to check them and Google any specific errors that come up.
4. Write a basic SpringMVC application
For this section I will point you directly at LynAs Sazzad‘s fantastic video for instructions on setting up all of the Spring code and dependencies in the pom.xml file. If you get stuck at any point or are having difficulty getting it working, my code is up on GitHub so feel free to use it for comparison or as a starting point for your own app!
The reason I’ve followed this tutorial specifically is that it uses Spring version 4, the latest release. Older versions of Spring use different annotations and also rely on .xml files for configuration of Beans etc. So this is all in aid of using the most up-to-date (at time of writing) version of Spring which uses Java instead of xml to work with Beans and in my opinion uses better structured annotations.
5. Deploy and run your webapp!
Once you have completed all of the above steps you can now use your run configuration to deploy your Spring webapp to your local Tomcat server and access it through the browser!
At the top of the window in IntelliJ you’ll notice a Run Configuration dropdown with a green ‘play/run’ button next to it, make sure your new run configuration is selected and click the green run button.
The run console at the bottom of the screen will start churning out all sorts of messages, a lot of them will be in red text but are only ‘info’ messages rather than errors! When it’s finished deploying your app to the local Tomcat server it will show you the ‘deployed successfully’ message (see white lines of text in screenshot below) and will open up your application automatically in a web browser window, if it doesn’t just navigate to http://localhost:8080/ in your browser to view it.
That’s all for now
That’s it! You’ve successfully set up a local Tomcat server, written a Spring application and deployed it to your server to be accessible by clients on your network (localhost)! In addition to this guide, I intend to write a sequel showing you how to deploy your application to a remote Tomcat server so it can be accessed by anyone on the internet. But for now that’s pretty good going 🙂
Also, as I start to learn more than just the absolute basics I’ll figure out what I can write about coherently and add that up on there as well!
If you have any questions or comments please as always feel free to message me or put them in the comments section below 🙂
Thanks for reading,