CSci 3601 Lab #2 - Building a web server in Java with Javalin

• Overview of the project
• Setup
  • Clone the project in GitKraken
  • Open the project in VS Code
  • JSON viewer browser extension
• Running Your project
• Testing Your Project
• Checking your code coverage
• Continuous Integration with GitHub Actions
• Go do the lab!
• Resources

Here you will explore serving up a simple website that you create, using a server written with the Javalin framework server. Javalin is a micro framework for creating web applications in Java which you will be using to create the server component (back-end) of your website.

The client component (front-end) of your website will use JavaScript to allow you to accept and process user input. We will use JUnit to test the server code and introduce continuous integration using GitHub Actions.

Your specific tasks for this lab can be found in the LABTASKS.md file in this repository.

Overview of the project

You'll be building parts of a simple to-do list using a client-server architecture. The server will be able to handle simple HTTP GET requests, where a client (or a user) can visit a URL such as http://localhost:4567/api/users and the server will respond with JSON-formatted text containing all the users the server knows about, e.g.,

[
  {
    "_id":"588935f57546a2daea44de7c",
    "name":"Connie Stewart",
    "age":25,
    "company":"OHMNET",
    "email":"conniestewart@ohmnet.com"
  },
  {
    "_id":"588935f5597715f06f3e8f6c",
    "name":"Lynn Ferguson",
    "age":25,
    "company":"NIQUENT",
    "email":"lynnferguson@niquent.com"
  },
  {
    "_id":"588935f51c55b55c75a84848",
    "name":"Roseann Roberson",
    "age":23,
    "company":"OHMNET",
    "email":"roseannroberson@ohmnet.com"
  },
  ...
]

The client will be a combination of HTML, CSS, and JavaScript that runs in the browser and converts user actions (such as clicking a button) into requests to the server. In a "real" system you'd want to display the results nicely as part of the application web interface (like the nicely formatted list of e-mails in GMail). To keep this lab simple, however, you'll just display the "raw" JSON that the client receives from the server.

This goal of this lab is to implement the desired server functionality. The details are in LABTASKS.md.

Setup

Clone the project in GitKraken

1. First, Open GitKraken. If you already have a project open, close it or open a new tab.
2. Click "Clone a repo", select "GitHub.com" and find this repo in "Repository to Clone"
3. Select where to put it and clone it
4. You can then click "Open Repo" from the notification that appears to open the repo

Open the project in VS Code

Launch Visual Studio Code, and then choose File -> Open Folder…. Navigate to your clone of the repo and choose Open.

You may see a dialog that looks like this if you don't already have the recommended extensions:

Don't worry if you don't get the dialog, it is probably because you already have them all installed.

Like in previous labs, click "Install All" to automatically install them.

JSON viewer browser extension

If you use Chrome, you may find it helpful to install the JSONVue extension. This will make JSON in the browser look pretty and actually be readable when you visit the different API endpoints.

If you use Firefox, this functionality is built-in, so there is no need to install an extension.

Running Your project

We use the Gradle build tool to build and run our web application. Gradle is a powerful system for defining, managing, and running tasks that allows us to easily build and test our full web application.

We will be using Gradle from the terminal. You can do this either with the terminal app or the terminal built into VS Code.

From the project directory, you will need to change into the server directory with

cd server

From the server directory you can use Gradle to run the server:

./gradlew run

Your server should now be running on port 4567, the port we've configured Javalin to run on. Visit it at http://localhost:4567 in your web browser. The server will continue to run indefinitely until you stop it

Testing Your Project

There's very little meaningful logic in the client component of this project so we're not going to worry about testing the client here. We'll begin testing the client when we introduce Angular in subsequent labs.

The server-side portion of this project will be tested using JUnit. Server-side tests are located in the src/test/java directory.

To run your server-side tests: while in the server directory, run:

./gradlew test

This will run all tests and output info about the run to a test report "website". To see the report open the file in your browser:

server/build/reports/tests/test/index.html

It will look something like this:

These test reports are especially helpful when a test fails because you will get the full stack trace there.

When a test fails, you will get a notice in the terminal that there were failing tests along with a path to the report. You can copy that path into your browser to see the report.

Checking your code coverage

We have the JaCoCo (Java Code Coverage) plugin set up in Gradle so you can see how well your tests cover (i.e., exercise) your code. The command

./gradlew check

will run the tests followed by the test coverage report generator. This report is a "website" like the one from JUnit above. To see the report open the file in your browser:

server/build/jacocoHtml/index.html

It will look something like this:

If you generate and look at that report at the start of the lab, you'll see that you start with 100% coverage of all the user files. You'd like to keep it that way, so check your code coverage after major stories are finished and look for areas that you're not yet testing. You also want to maintain high test coverage as you introduce your todo code.

‼️ ./gradlew check will fail (and thus block your ability to merge in a pull request)) if your test coverage ever falls below 80%, so keep an eye on it and take action if it starts to slide down.

📌 The Main.java and Server.java files are excluded from the test coverage. They're hard to test without actually generating HTTP requests, and are mostly configuration rather than "logic", so we've chosen to not over-complicate the project with attempts to test that code. You are not obliged to provide any coverage for that. You should make sure your tests cover things like your ToDoController and the like, though.

Continuous Integration with GitHub Actions

GitHub Actions is a Continuous Integration tool that performs builds of your project every time you push to GitHub. This is very helpful, as it makes keeping track of your testing over the lifetime of a project very easy. Having a build/test history makes it easy to find where, or when, your project broke, which makes it a lot easier to figure out why it broke and get it fixed and building successfully again.

GitHub Actions is built into GitHub and free to use on open source projects (like ours).

We've done the hard part of setting up the config files for GitHub Actions so it will work automatically. You can find the tests in the "Actions" tab of the GitHub repo.

Go do the lab!

Now that you're all set up, you should be ready to head over to LABTASKS.md, where most of the actual work of the lab is described.

Resources

• Getting started in Javalin
• Javalin tutorials
• Testing Javalin
• Mockito testing in Javalin
• Best practices for REST interface design
• HTTP Status Codes