With the current work I am doing for our client as a consultant, I have not had any recent opportunity to work with or let alone, configure a Spring framework. Realizing that I was getting a bit rusty and that Spring 4 had come out since I last worked with Spring, I thought it best to spend a little extra time reviewing Spring by putting together a simple server environment using Spring and JSON (which is a application popular protocol for use with client software). I thought this should only take a couple of hours at most. I figured the latest Eclipse would have everything built-in and it would be just a matter of creating a few application classes.
Eclipse can indeed create a client/server project but I saw no sample code for creating JSON controllers. I knew it was just a matter of defining a few annotation items but I had forgotten which ones I needed and their particular syntax. Solution: go to the Internet and search for “json eclipse server example”. I found a number of tutorial sites that included downloadable projects. I tried three of them. None of them worked out of the box. I found this particularly surprising as there were comments and thanks from users who had found the tutorials very useful and presumably had used the downloadable code. I assumed the issue was versioning and so I set out to grab the latest and greatest of everything (at least as of the date that I am writing this article). Building with these versions, too, wasn’t as obvious as it should have been. One of the library names had changed. But with a little perseverance, I finally hit on the correct versions of libraries that I needed to produce a functional JSON-based web server project.
The details are described below. Note that this article is not meant to be a tutorial on JSON. It is simply meant to be informative information for quickly getting a JSON-based web server project up and running.
Install Java 8
I should really be assuming that you have the JDK version of Java 8 installed. How do you expect to develop any software without it? Nevertheless, if you have Java 6 or Java 7 installed, realize that they are no longer supported. You really need to upgrade to Java 8. Here’s a link to the latest Java download page: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html. You can have more than one version of Java installed at the same time. Just set your PATH and JAVA_HOME variables to the appropriate version.
Install Tomcat 8
Tomcat is one of the easiest application servers to install, configure and run. There are other similarly good app servers but this is the one I chose to use. The latest version of tomcat is version 9 but it’s really very new (and I don’t know what features it has above and beyond version 8) and so I chose to install version 8. Download tomcat from here: https://tomcat.apache.org/download-80.cgi. I usually download the zip file onto my Windows box and install it in a local directory called util (this is where I drop all my Apache software after downloading the respective zip files). So if my user name is ‘jberry’, I will end up with a directory called jberry/util/apache-tomcat-8.0.32.
Install Eclipse
Install the latest version of eclipse. Go to the eclipse download page: https://eclipse.org/downloads/. I suggest installing “Eclipse IDE for Java EE Developers”. This gives you all the tools you might need for developing your web-based application. The download file will be a zip file. I unzipped everything into folder jberry/eclipse. To execute eclipse, go to directory jberry/eclipse/jee-mars/eclipse. There you will find the executable file, eclipse.exe.
Workspace setup
Create a directory called jberry/workspace (or wherever you want). Download the zip file that includes my source code for the JSON example. The link is here: https://dl.dropboxusercontent.com/u/14719415/RecordCollection.zip.
Eclipse startup
Start eclipse. It will ask you for the location of your workspace. Enter the workspace path from the previous step. After a brief moment, you will see an eclipse window entitled “Eclipse Java EE IDE for Web Developers”. In the upper right corner, press the button “Workbench”.
From the top pulldown menu, click on WIndow –> Preferences. By the left side of the window, find Java, expand the arrow and click on Installed JREs, as shown here:
Click on the “Add” button and find the path where your Java 8 JDK was installed.
Press the “Apply” button.
Setup tomcat within eclipse
In the same preferences window, at the left side of the window, find “Server”, open it up and click on Runtime Environments:
Press the “Add” button you will see a list of servers.
Select Apache Tomcat v8.0 and click on “Next>”. Do not check the box that says Create a new local server. Click on the “Browse” button and find where you installed tomcat. Enter that path. Under JRE, click on “Workbench default JRE” and specify your JDK install. Your window should look something like this:
Press “OK” to close your window.
At the bottom of the eclipse window, click on the “Servers” tab, right-click and select “New Server”. A window similar to the follow should pop up. Press “Finish” to create the server.
Import the JSON project
Click on “File” from the top pulldown menu and select “Import…”. Open category General and select “Existing Projects into Workspace” and press “Next>”. Press the “Browse…” button and select the workspace directory that was defined above. You should see an Import Projects dialog box like this one:
Click on the “Finish” button.
Select the “Markers” tab at the bottom of eclipse. There should not be any Java errors. If there are errors, right-click on “RecordCollection” which should appear in the Project Explorer view (far left side of eclipse) and select “Maven” –> “Update Project…”.
Description of the project
The data objects, Artist, Cd, and RegistrationInfo are straight-forward and are defined in package com.topshot.recordcolleciton.model. The two classes, ArtistInfo and CdInfo, are meant to simulate a simple database get or fetch operation but just returned hard-coded values.
The interesting stuff takes place in the controller package. Note how @RequestMapping, both at the class level and the method level are used to define which method is to be executed see the section called Testing below). And most of all, note that there is no JSON conversion code in the application. Conversion of the various output classes is handled invisibly via Spring and its support libraries. Simply adding produces=”application/json” tells Spring to perform this magic.
Run the project
Select the “Servers” tab at the bottom of eclipse. Then right-click on the tomcat instance and select “Start”. After a moment or so, tomcat will show that it is started and synchronized. This can be verified by opening the console tab. You should see something like this:
INFO: Server startup in 10395 ms
Go back to the server tab and right-click on the server. Select “Add and Remove…”. Select the RecordCollection resource and press the “Add>” button. Your dialog window should look something like this:
Personally, I always uncheck the box that says “If server is started, publish changes immediately”. But that’s up to you. The pluses and minuses of this choice are best saved for a more detailed discussion on software development and debugging. Press “Finish”.
Testing
Open a browser and enter URL http://localhost:8080/RecordCollection/Records/artists. You should get back the following line:
[{“name”:”Bob Dylan”},{“name”:”John Prine”},{“name”:”Joan Baez”},{“name”:”Leonard Cohen”}]
Now enter http://localhost:8080/RecordCollection/Records/cd/CD2 and you should get back the following line:
{“title”:”CD2″,”artist”:[{“name”:”John Prine”},{“name”:”Joan Baez”}],”song”:null}
In both of the above cases, you were executing HTTP GET commands. In order to execute an HTTP PUT command, a little more setup work is needed. There are many tools available that will generate a PUT command. One such tool is SoapUI. Configuring SoapUI is beyond the scope of this article. See the file README.txt which is part of the RecordCollection project for a little more information on testing PUTs.
You must be logged in to post a comment.